HtmlDrawable Class
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.
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.
//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
Objecta 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
NumberThe 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 optionalSetup-Parameters to customize additional object properties.
Accepted options-properties are-
enabled
(defaults totrue
) Boolean optional -
mirrored
(defaults tofalse
) Boolean optional -
horizontalAnchor
Number optional -
verticalAnchor
Number optional -
offsetX
(defaults to0
) Number optional -
offsetY
(defaults to0
) Number optional -
zOrder
(defaults to0
) Number optional -
rotation
(defaults to0
) Number optional -
scale
(defaults to1
) Number optional -
opacity
(defaults to1
) Number optional -
onClick
Function optional -
onLoaded
Function optional -
onError
Function optional -
roll
(defaults to0
) Number optional -
tilt
(defaults to0
) Number optional -
heading
(defaults to0
) Number optional -
viewportWidth
(defaults to256
) Number optional -
viewportHeight
(defaults to256
) Number optional -
backgroundColor
String optional -
clickThroughEnabled
(defaults tofalse
) Boolean optional -
allowDocumentLocationChanges
(defaults tofalse
) Boolean optional -
onDocumentLocationChanged
Function optional
-
Item Index
Properties
- allowDocumentLocationChanges
- backgroundColor
- clickThroughEnabled
- destroyed
- enabled
- heading deprecated
- horizontalAnchor
- html
- mirrored
- offsetX
- offsetY
- opacity
- roll deprecated
- rotate.heading
- rotate.roll
- rotate.tilt
- rotation
- scale
- scaling deprecated
- tilt deprecated
- UPDATE_RATE deprecated
- updateRate deprecated
- uri
- verticalAnchor
- viewportHeight
- viewportWidth
- width
- zOrder
Events
Methods
destroy
()
Destroys the object.
evalJavaScript
-
js
Evaluates the passed javascript string in the context of the given HtmlDrawable.
Parameters:
-
js
Stringthe javascript that should be evaluated. In case of an errornous script, the execution will fail gracefully.
getBoundingRectangle
()
BoundingRectangle
Returns the BoundingRectangle for this Drawable2D. In case of an error, null will be returned.
Returns:
the BoundingRectangle for the Drawable2D
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: : 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: #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: : false
enabled
Boolean
Flag to enable/disable the Drawable. If the Drawable is disabled, it will never appear on the screen and triggers on this Drawable will never be fired. In case it is enabled, it can be rendered on the screen and fire triggers.
Default: true
horizontalAnchor
Number
The horizontal anchor defines which pixel (in a horizontal
pixel row) of the Drawable2D will be placed right at the
screen position of the GeoObject represented by the
Drawable2D.
Valid values are defined in AR.CONST.HORIZONTAL_ANCHOR. For example, if
LEFT is set as horizontal anchor of an ImageDrawable, the image's left edge will
match the calculated position of the Drawable2D.
The default horizontal anchor points is dependent on the concrete class of the Drawable2D.
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).
mirrored
Boolean
Flag to enable/disable mirroring for this Drawable. When using the front camera, a mirrored drawable will be rotated 180 degree around its y axis.
Default: true for generic drawables, false for labels and HTMLDrawables
offsetX
Number
The horizontal offset to the calculated position of the Drawable2D, in SDUs. A positive offsetX causes the Drawable2D to move right, a negative offsetX causes it to move left.
Default: 0
offsetY
Number
The vertical offset to the calculated position of the Drawable2D, in SDUs. A positive offsetY causes the Drawable2D to move up, a negative offsetY causes it to move down.
Default: 0
opacity
Number
A value within the interval from 0.0 to 1.0 defining the opacity of the entire Drawable2D. A value of 0 indicates full transparency, a value of 1 indicates full opacity.
Default: 1
rotate.heading
Number
Defines a rotation of the Drawable around the y-axis, specified in degrees. Values will be applied modulo 360. A value of 361 degrees has the same effect as setting the value to 1 degree.
Default: 0
rotate.roll
Number
Defines a rotation of the Drawable around the z-axis, specified in degrees. Values will be applied modulo 360. A value of 361 degrees has the same effect as setting the value to 1 degree.
Default: 0
rotate.tilt
Number
Defines a rotation of the Drawable around the x-axis, specified in degrees. Values will be applied modulo 360. A value of 361 degrees has the same effect as setting the value to 1 degree.
Default: 0
rotation
Number
Defines the rotation of the Drawable, in degrees, with the
rotation axis perpendicular to the screen plain. For
example, setting rotation to 45.0 on a square plain image
turns it into a rhombus. A positive value defines a rotation
in clockwise direction, a negative value defines a rotation
in anti-clockwise direction. Rotation can influence the
BoundingRectangle of the Drawable (for example, when a
Rectangle is rotated).
Note, rotation is applied in addition to any roll-tilt-heading rotations defined.
Rotation specifies the rotation on the screen, with the origin of the rotation
being the center of the Drawable2D, including any offsets etc.
Default: 0
scale
Number
The scale factor for the Drawable2D. A scale factor greater than 1 enlarges the drawable, a scale factor less than 1 shrinks it down. Only values greater than or equal to 0 are allowed. A scale factor of 0 makes the Drawable2D invisible. A scale factor of 2 doubles the size of the Drawable2D, a scale factor of 0.5 halfs the size of the Drawable2D. Scale will influence the BoundingRectangle of the Drawable, but it will not influence the original properties of the Drawable2D.
Default: 1
UPDATE_RATE
Number
deprecated
Not used anymore, since each HtmlDrawable automatically has its update rate set to HIGH.
The following values are valid (use AR.HtmlDrawable.UPDATE_RATE for valid
values):
Value | Description |
AR.HtmlDrawable.UPDATE_RATE.STATIC | The HtmlDrawables will be rendered only once, and is never updated. Useful for static HTML content. |
AR.HtmlDrawable.UPDATE_RATE.LOW | The HtmlDrawables will be updated in one second intervals as a maximum. |
AR.HtmlDrawable.UPDATE_RATE.MEDIUM | The HtmlDrawables will be updated a few times a second. The exact update rate is dependent on the underlying device. |
AR.HtmlDrawable.UPDATE_RATE.HIGH | The 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.
updateRate
Number
deprecated
Not used anymore, each HtmlDrawable has a high update rate. Property is always set to 1, changes to the property are ignored.
verticalAnchor
Number
The vertical anchor defines which pixel (in a vertical pixel
column) of the Drawable2D will be placed right at the screen
position of the GeoObject represented by the Drawable2D.
Valid values are defined in AR.CONST.VERTICAL_ANCHOR. For example, if TOP
is set as horizontal anchor of an Image, the image's top edge will match
the calculated position of the Drawable2D.
The default vertical anchor points is dependent on the concrete class of the Drawable2D.
viewportHeight
Number
The height 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: 256
viewportWidth
Number
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: 256
width
Number
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.
zOrder
Number
If multiple Drawable2Ds are assigned to a certain GeoObject, the zOrder defines the drawing order of these Drawables.
In case the Drawables overlap, the Drawable with the higher zOrder value is rendered on top of the others (e.g. a Drawable with
zOrder 1 is rendered on top of a Drawable of zOrder 0, which again is rendered on top of -1).
In case Drawables have the same zOrder defined, and they overlap, the behavior is undefined and might cause unexpected results,
thus it is good practice to define the zOrder for potentially overlapping Drawables.
To specify the rendering order of the Drawables of different GeoObjects, refer to GeoObject.renderingOrder.
Must be a whole number.
Default: 0
Events
onClick
When the Drawable is clicked, the system will trigger Drawable.onClick(ARObject). A click on the screen might hit multiple Drawables, thus a click creates a "clicked Drawables-queue", with the uppermost Drawable in the front of the queue. The return value of the function determines if, after the onClick()-Function was executed for this Drawable, the queue shall continue to execute onClick() for the next Drawable in the queue. In case the last Drawable in the queue still requests to continue the click-queue, ARObject.onClick() will be executed. If the queue still continues, context.onScreenClick() will be executed.
The return value of the function determines what happens next. If false, the click-queue should not stop with this Drawable. Thus, the next Drawable's onClick() function will be executed. This is the default value in case no return value is set or the function is not defined for this Drawable. If true, the queue-execution will stop at the current Drawable, underlying Drawables will not receive onClick() calls.
Event Payload:
-
arObject
ARObjectthe ARObject the clicked Drawable is attached to.
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 onClick.
onDocumentLocationChanged
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.
Event Payload:
-
uri
Stringthe URI the document.location property changes to.
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.
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.
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.