Wikitude SDK API Reference

API Docs for: 7.2.0
Show:

Drawable Class

Extends ARchitectObject
Module: AR

A Drawable is the base class for any graphical element representing an ARObject.

Drawable is a superclass for other classes and must not be directly instantiated by the developer.

Transformations(local and global rotation and translation, local scaling) can be applied to Drawables. The local coordinate system of a Drawable is defined as a righthanded coordinate system, following the definitions below:

  • The origin of the coordinate system is in the location of the Object the Drawable is attached to.
  • The x axis is pointing right
  • The y axis is pointing up
  • The z axis is pointing out of the screen.
The definition of right and up depend on the type of the ARObject the Drawable is attached to. In case of a GeoObject, the direction are defined relative to the earth's surface, and the Drawable is oriented towards the user unless Drawable.rotatesToCamera is set to false. In case of an ImageTrackable, the directions are defined relative to the underlying tracked object.

A drawable can be mirrored when using the front cam, by setting the mirrored flag. By default all drawables are mirrored except labels and HTMLDrawables, but the setting can be overridden.

Methods

destroy

()

Inherited from ARchitectObject

Destroys the object.

Properties

destroyed

Boolean

Inherited from ARchitectObject

Indicates if the object has already been destroyed.

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

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

rotate

Object

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

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

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

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

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

rotate.roll

Number deprecated

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

rotate.tilt

Number deprecated

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

rotate.x

Number

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

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

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

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

scale

Object

Defines the scale 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.

scale.x

Number

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

Default: 1

scale.y

Number

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

Default: 1

scale.z

Number

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

Default: 1

translate

Object

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

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

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

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

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

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

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

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 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.

onDragBegan

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

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

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

onPanBegan

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

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

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

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

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

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

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

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

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