Wikitude ARchitect v2.0 API Documentation

Wikitude ARchitect > AR > HtmlDrawable
Filters

Class HtmlDrawable - extends Drawable2D

A HTML-described representation of an ARObject as a plain circle.

A HtmlDrawable can be created with either
  • a string holding the HTML content
  • using a URI that points to HTML content that will be used for representation.
If both properties are given on creation, plain HTML will take precedence over the URI content. If the properties are changed afterwards, the last change will take immediate effect, regardless of if it is specified via plain HTML or via URI.

In case both html and uri are set to null or undefined, the HtmlDrawable will not be rendered on the screen. The default anchor settings for a HtmlDrawable are as follows:
  • horizontal anchor: AR.CONST.HORIZONTAL_ANCHOR.CENTER
  • vertical anchor: AR.CONST.VERTICAL_ANCHOR.MIDDLE
On creation, setup parameters can be passed to customize the properties of the HtmlDrawable.

Example:
//create a new html drawable and pass some setup parameters to it
var htmlDrawable = new AR.HtmlDrawable({html:"<div>My div</div>"}, 1, {
  offsetX : 1,
  onClick : function() {
    htmlDrawable.html += "<div>Another div</div>";
  },
  horizontalAnchor : AR.CONST.HORIZONTAL_ANCHOR.LEFT,
  opacity : 0.9
});
// precedence example:
// htmlDrawable will use the html representation
htmlDrawable = new AR.HtmlDrawable({
  html:"<div>My div</div>", uri:"http://mydomain.com/my.html"
}, 1);
// now, uri will take precedence:
htmlDrawable.uri = "http://mydomain.com/myNew.html";

Constructor

HtmlDrawable ( content , width , options )
Parameters:
content <object> a JSON object describing the content of the HtmlDrawable. The object must either contain a html property of type string containing the HTML string (see example above), or a uri property of type string pointing to some HTML content. If both properties are specified, html takes precedence to uri. However, at least on of html and uri must be specified.
width <float> The width of the HTML drawable, in SDUs. Must be a positive number. Controls how wide the HtmlDrawable will be rendered on the screen. The height of the HtmlDrawable will be automatically adjusted keeping the aspect ratio of the Drawable.
options <object> Setup-Parameters to customize additional object properties.

Accepted options-properties are
  • enabled
  • horizontalAnchor
  • verticalAnchor
  • offsetX
  • offsetY
  • zOrder
  • rotation
  • scale
  • opacity
  • viewportWidth
  • updateRate
  • onClick
  • onLoaded
  • onError
  • roll
  • tilt
  • heading
  • backgroundColor
  • clickThroughEnabled
  • allowDocumentLocationChanges
  • onDocumentLocationChanged

Properties

allowDocumentLocationChanges - boolean

The property controls if changes to the document.location property of the HTML document wrapped inside the HtmlDrawable will actually be visible.

For example, if a HtmlDrawable contains a link to http://www.wikitude.com, the user clicks on the link and the clickThroughEnabled property is active, the onDocumentLocationChanged trigger will fire. After that, two things can happen, depending on the allowDocumentLocationChanges setting:

If allowDocumentLocationChanges is set to true, the content inside the HtmlDrawable will change to the content of http://www.wikitude.com
If allowDocumentLocationChanges is set to false, the content inside the HtmlDrawable will not change.
Default Value: : false

backgroundColor - string

The background color of the HtmlDrawable in case the background of the HTML body is set to transparent. Can be passed as hexadecimal RGB or RGBA values (see here for details on RGBA colorcoding). In case RGB is used, the alpha value is set to full opacity.

The property is useful when the HtmlDrawable's content is set to a URI which assumes a white browser background, but sets its own background to transparent. Setting the backgroundColor property to a non-transparent value causes transparent webpages to have a colored background.

Remark: The background of the HtmlDrawable itself does not change, the property only sets the background the HtmlDrawable is drawn on. If the body of the content of the HtmlDrawable has a non-transparent background, changing the backgroundColor property has no effect.
Default Value: #00000000 (transparent)

clickThroughEnabled - boolean

The property controls if clicks on HtmlDrawables will also be forwarded to the HTML content inside the HtmlDrawable. When a user clicks on a HtmlDrawable, the Drawable's onClick(arObject)-trigger will fire. If clickThroughEnabled is set to true, the click will also be executed inside the HTML content, causing the onclick-function of the HTML element hit by the click to be executed.
Default Value: : false

html - string

Plain HTML string that will be used to represent the drawable. If no <body> tag is supplied, it will automatically be added with default settings (transparent background, no margin).

updateRate - int

The updateRate of the HTMLDrawable. If the HTML contains dynamic parts, such as CSS animations or JavaScript snippets that are executed and dynamically change the content of the HTMLDrawable, the updateRate property gives hints to the application how often the HTMLDrawable should be refreshed.

The following values are valid (use AR.HtmlDrawable.UPDATE_RATE for valid values):
ValueDescription
AR.HtmlDrawable.UPDATE_RATE.STATICThe HtmlDrawables will be rendered only once, and is never updated. Useful for static HTML content.
AR.HtmlDrawable.UPDATE_RATE.LOWThe HtmlDrawables will be updated in one second intervals as a maximum.
AR.HtmlDrawable.UPDATE_RATE.MEDIUMThe HtmlDrawables will be updated a few times a second. The exact update rate is dependent on the underlying device.
AR.HtmlDrawable.UPDATE_RATE.HIGHThe HtmlDrawables will be updated as often as possible, depending on the current frame rate the mobile device is able to deliver. Useful for highly dynamic HTML content.

Remark: As dynamic HtmlDrawables are memory consuming, limit the number of dynamic HTMLDrawables as much as possible. If dynamic HtmlDrawables are required, try to limit those with HIGH and MEDIUM update rates, and use LOW update rates wherever possible to achieve good performance also on low end devices.
Default Value: : AR.HtmlDrawable.UPDATE_RATE.STATIC

uri - string

A URI pointing to HTML content that will be used to render the drawable.

viewportWidth - int

The width of the viewport the HTML texture will be rendered on, in pixels. A larger viewport makes the items in the HTMLDrawable appear smaller. The default value is set to 256. The viewport must be a positive integer, not exceeding 1024 pixels.
Default Value: 256

width - float

The width of the HTML drawable, in SDUs. Must be a positive number. Controls how wide the HtmlDrawable will be rendered on the screen. The height of the HtmlDrawable will be automatically adjusted keeping the aspect ratio of the Drawable.

Methods

evalJavaScript

void evalJavaScript ( js )
Evaluates the passed javascript string in the context of the given HtmlDrawable.
Parameters:
js <string> the javascript that should be evaluated. In case of an errornous script, the execution will fail gracefully.
Returns: void

onDocumentLocationChanged

void onDocumentLocationChanged ( uri )
The trigger fires when the HtmlDrawable's document.location changes, for example because a link was clicked inside the HtmlDrawable, which triggers a load of another document. The trigger will only be fired when click through is allowed for the HtmlDrawable, see HtmlDrawable.clickThroughEnabled for details.

The trigger is null by default, and will thus result in no action executed when the trigger fires. A developer can add custom functionality by assigning a custom function to onDocumentLocationChanged.
Parameters:
uri <string> the URI the document.location property changes to.
Returns: void

onError

void onError ( )
The trigger fires when the HtmlDrawable's content could not be loaded. Causes for this might include bad network connection or an invalid HTML.

The trigger will also fire when content could not be reloaded after the URI or HTML changed.

The trigger is null by default, and will thus result in no action executed when the trigger fires. A developer can add custom functionality by assigning a custom function to onError.
Returns: void

onLoaded

void onLoaded ( )
The trigger fires when the HtmlDrawable's content was successfully loaded.

The trigger will also fire when content was successfully reloaded because the URI or HTML changed.

Example:
htmlDrawable = new AR.HtmlDrawable({
  uri:"http://mydomain.com/my.html"
}, 1, { onLoaded : function(){
  uri:"http://mydomain.com/my2.html"
};}); //trigger will fire again


The trigger is null by default, and will thus result in no action executed when the trigger fires. A developer can add custom functionality by assigning a custom function to onLoaded.
Returns: void

Methods inherited from Drawable2D:

getBoundingRectangle

Methods inherited from ARchitectObject:

destroy

Methods inherited from Drawable:

onClick, triggers.onClick

Modules

Copyright © 2013 Wikitude GmbH. All rights reserved.