5 Actor is the primary object with which Dali applications interact. UI controls can be built by combining multiple actors.
7 There are different types of Actors supported by Dali. They all have the same
8 base functionality of the actor class.
11 var actor = new dali.Actor();
12 var textActor = new dali.TextActor("hello world");
13 var camera = new dali.CameraActor();
14 var layer = new dali.Layer();
17 ### Hello world example
19 var myActor = new dali.TextActor("hello-world");
21 myActor.name = "my first actor";
22 myActor.color = [ 1, 0, 0, 1]; // Red,Green,Blue, Alpha ( 1 == max, 0 = none )
23 myActor.scale = [ 2, 2, 1]; // double the width and height
25 // by default an actor is anchored to the top-left of it's parent actor
26 // change it to the middle
28 myActor.parentOrigin = [0.5,0.5,0.5];
31 dali.stage.add( myActor );
35 ### Positioning Actors
37 An actor inherits its parent's position. The relative position between the actor & parent is determined by 3 properties:
39 1) ParentOrigin. This Vector3 property defines a point within the parent actor's area.
41 ![ ](../assets/img/parent-origin.png)
44 The default is "top-left", which can be visualized in 2D as (0, 0), but is actually Vector3(0, 0, 0.5) in the 3D DALi world. The actor's position is relative to this point.
46 // to change parent origin to the centre
47 myActor.parentOrigin = [0.5, 0.5, 0.5];
50 2) AnchorPoint. This Vector3 property defines a point within the child actor's area.
52 ![ ](../assets/img/anchor-point.png)
54 The default is "center", which can be visualized in 2D as (0.5, 0.5), but is actually Vector3(0.5, 0.5, 0.5) in the 3D DALi world. The actor's position is also relative to this point.
56 // setting anchor point to the centre
57 myActor.anchorPoint = [0.5, 0.5, 0.5];
60 3) Position. This is the position vector between the parent-origin and anchor-point.
62 ![ ](../assets/img/actor-position.png)
64 Therefore by default, an actors position is the distance between its center and the top-left corner of its parent.
66 An actor added directly to the stage with position (X = stageWidth*0.5, Y = stageHeight*0.5), would appear in the center of the screen. Likewise an actor with position (X = actorWidth*0.5, Y = actorWidth*0.5), would appear at the top-left of the screen.
68 Note that since DALi is a 3D toolkit, this behaviour is the result of a default perspective camera setup.
70 ### Actor callback events
72 The actor provides the following call back events
74 | Name | Description | Parameters passed to call back |
75 |-----------------|----------------------------------------|--------------------------|
76 |touch | touch | (actor, touchData ) |
77 |hovered | mouse or pointer hovering over actor | (actor, hoverEvent) |
78 |mouseWheelEvent | mouse wheel events | (actor, wheelEvent) |
79 |onStage | actor has been moved on stage | (actor) |
80 |offStage | actor has been moved off stage | (actor) |
85 Used to detect multiple touch events on the actor. The state of each touch point can be:
88 + "MOTION" = Finger dragged or hovered
89 + "LEAVE" = Leave the boundary of an actor
90 + "STATIONARY" = No change from last event. Useful when a multi-point event occurs where
91 all points are sent but indicates that this particular point has not changed
93 + "INTERRUPTED" = A system event has occurred which has interrupted the touch or hover event sequence
100 pointCount: int, // number of points touched ( multi-touch )
101 time: int, // The time in milliseconds that the touch event occurred.
102 points = [ Points ], // array of Points
105 "deviceId" : int, // Each touch point has a unique device ID
106 "state" : string, // touch state ="DOWN","UP","MOTION","LEAVE","STATIONARY","INTERRUPTED"
107 "sourceActor" : actor, // the actor that is emitting the callback (the actor that is hit maybe a child of it)
108 "hitActor" : actor, // actor that was hit
109 "local" : {x,y}, // co-ordinates of top left of hit actor (local.x, local.y)
110 "screen" : {x,y}, // co-ordinates of top left of hit actor (screen.x, screen.y)
111 "radius" : float, // radius of the press point (average of both the horizontal & vertical radii)
112 "ellipseRadius" : {x,y}, // both the horizontal and the vertical radii of the press point
113 "pressure" : float, // the touch pressure
114 "angle" : float // angle of the press point relative to the Y-Axis (in degrees)
118 function onPressed( actor, touchData )
120 var firstPoint = touchData.points[0];
121 log("first touch point = " + firstPoint.screen.x + "," + firstPoint.screen.x + "actor= " + firstPoint.hitActor );
123 var anim = new dali.Animation( 4 );
124 var rotation = new dali.Rotation( 90, 0, 0 ); // pitch, yaw, roll
125 anim.animateBy( actor, "orientation", rotation );
130 // connect to touch events
131 myActor.on( "touch", onPressed );
140 pointCount // number of points hovered over
141 time // The time in milliseconds that the hover event occurred.
142 points[] // array of TouchPoints
145 "deviceId" : int, // Each touch point has a unique device ID
146 "state" : string, // touch state ="down,up,motion,leave,stationary, interrupted }
147 "sourceActor" : actor, // the actor that is emitting the callback (the actor that is hit maybe a child of it)
148 "hitActor" : actor, // actor that was hit
149 "local" : {x,y}, // co-ordinates of top left of hit actor (local.x, local.y)
150 "screen" : {x,y} // co-ordinates of top left of hit actor (screen.x, screen.y)
154 // connect to touch events
155 myActor.on( "hovered", onHover);
157 #### Mouse wheel event
162 direction, // "vertical" or "horizontal" direction the wheel is being rolled
163 shiftPressed, // boolean, shift key is held
164 ctrlPressed, // boolean, ctrl key is held
165 altPressed, // boolean, alt key is held
166 keyModifiers, // bitmask of keys pressed
167 point {x,y}, // The co-ordinates of the mouse cursor relative to the top-left of the screen when the wheel is being rolled.
168 rolled, // offset of mouse wheel rolling, positive = rolling down, negative = rolling up
169 timestamp // The time in milliseconds that the mouse event occurred
172 // connect to touch events
173 myActor.on( "mouseWheelEvent", onMouseWheel );
177 Key events are performed using the dali.stage object and dali.keyboardFocusManager.
178 - {{#crossLink "stage"}}Stage{{/crossLink}}
181 #### Multi-touch events
184 - {{#crossLink "MultiTouch"}}Multi Touch Events.{{/crossLink}}
189 Name | Type | Writable | Animatable
190 ------------------------|------------|--------------|-----------
191 anchorPoint |VECTOR3 | ✔ | ✘
192 anchorPointX |FLOAT | ✔ | ✘
193 anchorPointY |FLOAT | ✔ | ✘
194 anchorPointZ |FLOAT | ✔ | ✘
195 size |VECTOR3 | ✔ | ✔
196 sizeWidth |FLOAT | ✔ | ✔
197 sizeHeight |FLOAT | ✔ | ✔
198 sizeDepth |FLOAT | ✔ | ✔
199 position |VECTOR3 | ✔ | ✔
200 positionX |FLOAT | ✔ | ✔
201 positionY |FLOAT | ✔ | ✔
202 positionZ |FLOAT | ✔ | ✔
203 worldPosition |VECTOR3 | ✘ | ✘
204 worldPositionX |FLOAT | ✘ | ✘
205 worldPositionY |FLOAT | ✘ | ✘
206 worldPositionZ |FLOAT | ✘ | ✘
207 orientation |ROTATION | ✔ | ✔
208 worldOrientation |ROTATION | ✘ | ✘
209 scale |VECTOR3 | ✔ | ✔
210 scaleX |FLOAT | ✔ | ✔
211 scaleY |FLOAT | ✔ | ✔
212 scaleZ |FLOAT | ✔ | ✔
213 worldScale |VECTOR3 | ✘ | ✘
214 visible |BOOLEAN | ✔ | ✔
215 color |VECTOR4 | ✔ | ✔
216 colorRed |FLOAT | ✔ | ✔
217 colorGreen |FLOAT | ✔ | ✔
218 colorBlue |FLOAT | ✔ | ✔
219 colorAlpha |FLOAT | ✔ | ✔
220 worldColor |VECTOR4 | ✘ | ✘
221 worldMatrix |MATRIX | ✘ | ✘
222 name |STRING | ✔ | ✘
223 sensitive |BOOLEAN | ✔ | ✘
224 leaveRequired |BOOLEAN | ✔ | ✘
225 inheritOrientation |BOOLEAN | ✔ | ✘
226 inheritScale |BOOLEAN | ✔ | ✘
227 colorMode |NUMBER | ✔ | ✘
228 positionInheritance |NUMBER | ✔ | ✘
229 drawMode |NUMBER | ✔ | ✘
230 sizeMode |NUMBER | ✔ | ✘
231 sizeModeFactor |VECTOR3 | ✔ | ✘
242 * Actors parent origin
244 * @property parentOrigin
246 * @default TOP_LEFT (0.0, 0.0, 0.5).
251 * Actors parent origin X
253 * @property parentOriginX
260 * Actors parent origin-y
261 * @property parentOriginY
268 * Actors parent origin-z
269 * @property parentOriginZ
276 * Actors anchor point
277 * @property anchorPoint
279 * @default CENTER (0.5, 0.5, 0.5)
284 * Actors anchor point x
285 * @property anchorPointX
291 * Actors anchor point y
292 * @property anchorPointY
298 * Actors anchor point z
299 * @property anchorPointZ
314 * @property sizeWidth
321 * @property sizeHeight
328 * @property sizeDepth
343 * @property positionX
350 * @property positionY
357 * @property positionZ
364 * Actors world position
366 * @type dali Vector3 ( read-only, not animatable )
371 * Actors world x position
372 * @property worldPositionX
373 * @type Number ( read-only )
378 * Actors world y position
379 * @property worldPositionY
380 * @type Number ( read-only )
385 * Actors world z position
386 * @property worldPositionZ
387 * @type Number ( read-only )
394 * @property orientation
395 * @type dali Rotation object
401 * Actors world-orientation
402 * @property worldOrientation
403 * @type dali Rotation object ( read only)
437 * @property worldScale
438 * @type dali Vector3 ( read only )
443 * Actors visible flag
444 * If an actor is not visible, then the actor and its children will not be rendered.
445 * This is regardless of the individual visibility values of the children i.e. an actor will only be
446 * rendered if all of its parents have visibility set to true.
455 * The final color of the actor depends on its color mode.
456 * 4 components, red, green, blue and alpha. Each range from 0..1
458 * @type dali Vector 4
465 * @type Number ( 0..1)
471 * @property colorGreen
472 * @type Number ( 0..1)
478 * @property colorBlue
479 * @type Number ( 0..1)
484 * Actors world color.
485 * 4 components, red, green, blue and alpha. Each range from 0..1
486 * @property worldColor
487 * @type dali Vector 4 ( read only)
498 * Actors sensitive flag
499 * brief Sets whether an actor should emit touch event signals; @see SignalTouch().
501 * An actor is sensitive by default, which means that as soon as an application connects to the SignalTouch(),
502 * the touch event signal will be emitted.
504 * If the application wishes to temporarily disable the touch event signal emission, then they can do so by calling
506 * actor.sensitve = false;
508 * Then, to re-enable the touch event signal emission, the application should call:
510 * actor.sensitive = true;
512 * @property sensitive
514 * @default true ( is sensistive )
519 * Controls whether the actor should receive a notification when touch motion events leave
520 * the boundary of the actor.
522 * Note: Need to connect to the SignalTouch to actually receive this event.
523 * Should be set to true if a Leave event is required
525 * @property leaveRequired
526 * @default false, this is set to false as most actors do not require this.
531 * Set whether a child actor inherits it's parent's orientation.
533 * @property inheritOrientation
540 * Set whether a child actor inherits it's parent's scale.
542 * @property inheritScale
549 * Set how the actor and its children should be drawn.
551 * Not all actors are renderable, but DrawMode can be inherited from any actor.
552 * By default a renderable actor will be drawn as a 3D object. It will be depth-tested against
553 * other objects in the world i.e. it may be obscured if other objects are in front.
555 * If OVERLAY_2D is used, the actor and its children will be drawn as a 2D overlay.
556 * Overlay actors are drawn in a separate pass, after all non-overlay actors within the Layer.
557 * For overlay actors, the drawing order is determined by the hierachy (depth-first search order),
558 * and depth-testing will not be used.
560 * If STENCIL is used, the actor and its children will be used to stencil-test other actors
561 * within the Layer. Stencil actors are therefore drawn into the stencil buffer before any other
562 * actors within the Layer.
566 * var actor.drawMode = dali.DRAW_MODE_NORMAL; // binary 00. The default draw-mode
567 * var actor.drawMode = dali.DRAW_MODE_OVERLAY_2D; // binary 01. Draw the actor and its children as an overlay
568 * var actor.drawMode = dali.DRAW_MODE_STENCIL ; // binary 11. Draw the actor and its children into the stencil buffer
573 * @default 0 (Normal )
579 * Sets the actor's color mode.
581 * This specifies whether the Actor uses its own color, or inherits
582 * its parent color. The default is USE_OWN_MULTIPLY_PARENT_ALPHA.
585 * actor.colorMode = dali.COLOR_MODE_USE_OWN_COLOR; // Actor will use its own color
586 * actor.colorMode = dali.COLOR_MODE_USE_PARENT_COLOR; // Actor will use its parent color
587 * actor.colorMode = dali. COLOR_MODE_USE_OWN_MULTIPLY_PARENT_COLOR; // Actor will blend its color with its parents color.
588 * actor.colorMode = dali.COLOR_MODE_USE_OWN_MULTIPLY_PARENT_ALPHA ; // Actor will blend its alpha with its parents alpha. This means when parent fades in or out child does as well. This is the default.
592 * @property colorMode
593 * @default 2 (USE_OWN_MULTIPLY_PARENT_ALPHA )
598 * Set the actors position inheritance mode.
601 * actor.positionInheritance = dali.POSITION_INHERITANCE_INHERIT_PARENT_POSITION; // Actor will inherit its parent position. This is the default
602 * actor.positionInheritance = dali.POSITION_INHERITANCE_USE_PARENT_POSITION; // Actor will copy its parent position. This is useful if many actors are stacked together in the same place. This option ignores parent origin and anchor point.
603 * actor.positionInheritance = dali.POSITION_INHERITANCE_USE_PARENT_POSITION_PLUS_LOCAL_POSITION; // Actor will copy its parent position and add local position. This is useful if many actors are stacked together in the same place with an offset. This option ignores parent origin and anchor point.
604 * actor.positionInheritance = dali.POSITION_INHERITANCE_DONT_INHERIT_POSITION; // Actor will not inherit position. Local position is treated as world position. This is useful if a constraint is used to override local position or if an actor is positioned globally. This option ignores parent origin, anchor point and local position.
606 * Switching this off means that using SetPosition() sets the actor's world position.
608 * @property positionInheritance
609 * @default 0 (INHERIT_PARENT_POSITION )
611 POSTITION_INHERITANCE
615 * Defines how a child actor's size is affected by its parent's size.
617 * The default is to ignore the parent's size and use the size property of this actor.
619 * If USE_OWN_SIZE is used, this option is bypassed and the actor's size
622 * If SIZE_EQUAL_TO_PARENT is used, this actor's size will be equal to that
623 * of its parent. The actor's size property is ignored.
625 * If SIZE_RELATIVE_TO_PARENT is used, this actor's size will be based on
626 * its parent's size by multiplying the parent size by
629 * If SIZE_FIXED_OFFSET_FROM_PARENT is used, this actor's size will be based on
630 * its parent's size plus SizeModeFactor.
634 * actor.sizeMode = dali.USE_OWN_SIZE;
635 * actor.sizeMode = dali.SIZE_EQUAL_TO_PARENT;
636 * actor.sizeMode = dali.SIZE_RELATIVE_TO_PARENT;
637 * actor.sizeMode = dali.SIZE_FIXED_OFFSET_FROM_PARENT
641 * @default 0 (dali.SIZE_MODE_USE_OWN_SIZE; )
647 * @brief Sets the relative to parent size factor of the actor.
649 * This factor is only used when SizeMode is set to either:
650 * SIZE_RELATIVE_TO_PARENT or SIZE_FIXED_OFFSET_FROM_PARENT.
651 * This actor's size is set to the actor's parent size multipled by or added to this factor,
652 * depending on SideMode (See SetSizeMode).
654 * @property sizeModeFactor