Wikitude SDK API Reference

API Docs for: 8.2.0
Show:

HtmlDrawable Class

Extends Drawable2D
Module: AR

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.

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, {
  translate : { x: 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 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.

  • options Object optional

    Setup-Parameters to customize additional object properties.

    Accepted options-properties are

    • enabled (defaults to true) Boolean optional
    • mirrored (defaults to true) Boolean optional
    • onClick Function optional
    • onDragBegan Function optional
    • onDragChanged Function optional
    • onDragEnded Function optional
    • onPanBegan Function optional
    • onPanChanged Function optional
    • onPanEnded Function optional
    • onRotationBegan Function optional
    • onRotationChanged Function optional
    • onRotationEnded Function optional
    • onScaleBegan Function optional
    • onScaleChanged Function optional
    • onScaleEnded Function optional
    • rotate.x (defaults to 0) Number optional
    • rotate.y (defaults to 0) Number optional
    • rotate.z (defaults to 0) Number optional
    • rotate.global.x (defaults to 0) Number optional
    • rotate.global.y (defaults to 0) Number optional
    • rotate.global.z (defaults to 0) Number optional
    • translate.x (defaults to 0) Number optional
    • translate.y (defaults to 0) Number optional
    • translate.z (defaults to 0) Number optional
    • translate.global.x (defaults to 0) Number optional
    • translate.global.y (defaults to 0) Number optional
    • translate.global.z (defaults to 0) Number optional
    • scale.x (defaults to 1) Number optional
    • scale.y (defaults to 1) Number optional
    • scale.z (defaults to 1) Number optional
    • horizontalAnchor (defaults to AR.CONST.HORIZONTAL_ANCHOR.CENTER) Object optional
    • verticalAnchor (defaults to AR.CONST.VERTICAL_ANCHOR.MIDDLE) Object optional
    • zOrder (defaults to 0) Number optional
    • opacity (defaults to 1) Number optional
    • onLoaded Function optional
    • onError Function optional
    • viewportWidth (defaults to 256) Number optional
    • viewportHeight (defaults to 256) Number optional
    • backgroundColor String optional
    • clickThroughEnabled (defaults to false) Boolean optional
    • allowDocumentLocationChanges (defaults to false) Boolean optional
    • onDocumentLocationChanged Function optional

Methods

destroy

()

Inherited from ARchitectObject

Destroys the object.

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.

getBoundingRectangle

() BoundingRectangle

Inherited from Drawable2D

Returns the BoundingRectangle for this Drawable2D. In case of an error, null will be returned.

Returns:

BoundingRectangle:

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

destroyed

Boolean

Inherited from ARchitectObject

Indicates if the object has already been destroyed.

enabled

Boolean

Inherited from Drawable

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

Inherited from Drawable2D

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

Inherited from Drawable

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 deprecated

Inherited from Drawable2D

Deprecated: Use translate.x instead.

offsetY

Number deprecated

Inherited from Drawable2D

Deprecated: Use translate.x instead.

opacity

Number

Inherited from Drawable2D

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

Object

Inherited from Drawable

Defines the rotation of the Drawable around its center. This property can be used to set the x, y and z components simultaneously in a single call to the native side of the Wikitude SDK for maximum performance. The Object may contain x, y and z or any subset thereof.

rotate.global.x

Number

Inherited from Drawable

Defines a rotation of the Drawable around the x-axis of the target image, 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. All global transformations will be applied after the local transformations.

Default: 0

rotate.global.y

Number

Inherited from Drawable

Defines a rotation of the Drawable around the y-axis of the target image, 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. All global transformations will be applied after the local transformations.

Default: 0

rotate.global.z

Number

Inherited from Drawable

Defines a rotation of the Drawable around the z-axis of the target image, 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. All global transformations will be applied after the local transformations.

Default: 0

rotate.heading

Number deprecated

Inherited from Drawable

Deprecated: Use rotate.y or rotate.global.y instead.

rotate.roll

Number deprecated

Inherited from Drawable

Deprecated: Use rotate.z or rotate.global.z instead.

rotate.tilt

Number deprecated

Inherited from Drawable

Deprecated: Use rotate.x or rotate.global.x instead.

rotate.x

Number

Inherited from Drawable

Defines a rotation of the Drawable around the x-axis of the Drawable, 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.y

Number

Inherited from Drawable

Defines a rotation of the Drawable around the y-axis of the Drawable, 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.z

Number

Inherited from Drawable

Defines a rotation of the Drawable around the z-axis of the Drawable, 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

rotatesToCamera

Boolean

Inherited from Drawable

Defines if the drawable is oriented to face the camera. This is only possible for Drawables attached to a GeoObject.

Default: true for generic drawables, false for Models

rotation

Number deprecated

Inherited from Drawable2D

Deprecated: Use rotate.z instead.

scale

Number deprecated

Inherited from Drawable

Deprecated: Use scale.x and scale.y instead.

scale.x

Number

Inherited from Drawable

The scale in x-direction. Must be non-negative.

Default: 1

scale.y

Number

Inherited from Drawable

The scale in y-direction. Must be non-negative.

Default: 1

scale.z

Number

Inherited from Drawable

The scale in z-direction. Must be non-negative.

Default: 1

translate

Object

Inherited from Drawable

Defines the translation of the Drawable. This property can be used to set the x, y and z components simultaneously in a single call to the native side of the Wikitude SDK for maximum performance. The Object may contain x, y and z or any subset thereof.

translate.global.x

Number

Inherited from Drawable

The horizontal offset to the calculated position of the Drawable, in SDUs. A positive x causes the Drawable to move right, a negative x causes it to move left. All global transformations will be applied after the local transformations.

Default: 0

translate.global.y

Number

Inherited from Drawable

The vertical offset to the calculated position of the Drawable, in SDUs. A positive y causes the Drawable to move up, a negative y causes it to move down. All global transformations will be applied after the local transformations.

Default: 0

translate.global.z

Number

Inherited from Drawable

The depth-offset to the calculated position of the Drawable, in SDUs. A positive z causes the Drawable to move towards the user, a negative z causes it to move away. All global transformations will be applied after the local transformations.

Default: 0

translate.x

Number

Inherited from Drawable

The horizontal offset to the calculated position of the Drawable, in SDUs. A positive x causes the Drawable to move right, a negative x causes it to move left.

Default: 0

translate.y

Number

Inherited from Drawable

The vertical offset to the calculated position of the Drawable, in SDUs. A positive y causes the Drawable to move up, a negative y causes it to move down.

Default: 0

translate.z

Number

Inherited from Drawable

The depth-offset to the calculated position of the Drawable, in SDUs. A positive z causes the Drawable to move towards the user, a negative z causes it to move away.

Default: 0

uri

String

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

verticalAnchor

Number

Inherited from Drawable2D

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

Inherited from Drawable2D

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

Inherited from Drawable

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 ARObject

    the 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 String

    the URI the document.location property changes to.

onDragBegan

Inherited from Drawable

Executed when the user starts dragging on a Drawable with a single finger. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch position and the updated touch position [-1, 1]; always 0 in onDragBegan as no change to the drag gesture has occurred yet

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; always 0 in onDragBegan as no change to the drag gesture has occurred yet

  • xIntersection Number

    the world space X-coordinate of the intersection position of the initiating touch ray and the instant tracking plane [-infinity, infinity]; undefined if no InstantTrackable is available

  • xIntersection Number

    the world space X-coordinate of the intersection position of the initiating touch ray and the instant tracking plane [-infinity, infinity]; undefined if no InstantTrackable is available

onDragChanged

Inherited from Drawable

Executed when the user drags on a Drawable with a single finger. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch position and the updated touch position [-1, 1]

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]

  • xIntersection Number

    the world space X-coordinate of the intersection position of the updated touch ray and the instant tracking plane [-infinity, infinity]; undefined if no InstantTrackable is available

  • xIntersection Number

    the world space X-coordinate of the intersection position of the updated touch ray and the instant tracking plane [-infinity, infinity]; undefined if no InstantTrackable is available

onDragEnded

Inherited from Drawable

Executed when the user stops dragging on a Drawable with a single finger. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch position and the updated touch position [-1, 1]; always identical to the most recent distance received in onDragChanged

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; always identical to the most recent distance received in onDragChanged

  • xIntersection Number

    the world space X-coordinate of the intersection position of the final touch ray and the instant tracking plane [-infinity, infinity]; undefined if no InstantTrackable is available

  • xIntersection Number

    the world space X-coordinate of the intersection position of the final touch ray and the instant tracking plane [-infinity, infinity]; undefined if no InstantTrackable is available

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.

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.

onPanBegan

Inherited from Drawable

Executed when the user starts dragging on a Drawable with two fingers. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch positions and the updated touch positions [-1, 1]; always 0 in onPanBegan as no change to the pan gesture has occurred yet; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; always 0 in onPanBegan as no change to the pan gesture has occurred yet; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

onPanChanged

Inherited from Drawable

Executed when the user drags on a Drawable with two fingers. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch positions and the updated touch positions [-1, 1]; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

onPanEnded

Inherited from Drawable

Executed when the user stops dragging on a Drawable with two fingers. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • xNormalized Number

    the distance on the X-axis between the initiating touch positions and the updated touch positions [-1, 1]; always identical to the most recent distance received in onPanChanged; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

  • yNormalized Number

    the distance on the Y-axis between the initiating touch position and the updated touch position [-1, 1]; always identical to the most recent distance received in onPanChanged; the mid-points between the first and second touches are used to calculate the distances to allow co-operative behaviour with the scale and rotate gesture

onRotationBegan

Inherited from Drawable

Executed when the user starts rotating on a Drawable with two fingers. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • angle Number

    the CCW angle in degree between the line defined by the initiating touch positions and the line defined by the updated touch positions [0, 360); always 0 in onRotationBegan as no change to the rotation gesture has occurred yet

onRotationChanged

Inherited from Drawable

Executed when the user rotates on a Drawable with two fingers. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • angle Number

    the CCW angle in degree between the line defined by the initiating touch positions and the line defined by the updated touch positions [0, 360)

onRotationEnded

Inherited from Drawable

Executed when the user stops rotating on a Drawable with two fingers. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • angle Number

    the CCW angle in degree between the line defined by the initiating touch positions and the line defined by the updated touch positions [0, 360); always identical to the most recent angle received in onRotationChanged

onScaleBegan

Inherited from Drawable

Executed when the user starts scaling on a Drawable with two fingers. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • scale Number

    the scale value defined the ratio of the distance between the updated touches over the distance between the initiating touches [0, inf]; always 1 in onScaleBegan as no change to the scale gesture has occurred yet

onScaleChanged

Inherited from Drawable

Executed when the user scales on a Drawable with two fingers. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • scale Number

    the scale value defined the ratio of the distance between the updated touches over the distance between the initiating touches [0, inf]

onScaleEnded

Inherited from Drawable

Executed when the user stops scaling on a Drawable with two fingers. This callback behaves identically to the onClick callback in terms of event propagation.

Event Payload:

  • scale Number

    the scale value defined the ratio of the distance between the updated touches over the distance between the initiating touches [0, inf]; always identical to the most recent scale received in onScaleChanged