Merge "Performance enhancement, cache glClear state" into tizen
[platform/core/uifw/dali-core.git] / dali / public-api / actors / actor.h
1 #ifndef __DALI_ACTOR_H__
2 #define __DALI_ACTOR_H__
3
4 /*
5  * Copyright (c) 2014 Samsung Electronics Co., Ltd.
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  * http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  *
19  */
20
21 // EXTERNAL INCLUDES
22 #include <boost/function.hpp>
23 #include <string>
24
25 // INTERNAL INCLUDES
26 #include <dali/public-api/common/vector-wrapper.h>
27 #include <dali/public-api/animation/active-constraint-declarations.h>
28 #include <dali/public-api/actors/actor-enumerations.h>
29 #include <dali/public-api/actors/draw-mode.h>
30 #include <dali/public-api/object/handle.h>
31 #include <dali/public-api/object/property-index-ranges.h>
32 #include <dali/public-api/signals/dali-signal.h>
33
34 namespace Dali
35 {
36
37 namespace Internal DALI_INTERNAL
38 {
39 class Actor;
40 }
41
42 class Actor;
43 class Animation;
44 class Constraint;
45 struct Degree;
46 class DynamicsBody;
47 class DynamicsBodyConfig;
48 class DynamicsJoint;
49 class Quaternion;
50 class Layer;
51 struct Radian;
52 struct KeyEvent;
53 struct TouchEvent;
54 struct HoverEvent;
55 struct MouseWheelEvent;
56 struct Vector2;
57 struct Vector3;
58 struct Vector4;
59
60 /**
61  * @brief Actor container.
62  */
63 typedef std::vector<Actor> ActorContainer;
64 typedef ActorContainer::iterator ActorIter; ///< Iterator for Dali::ActorContainer
65 typedef ActorContainer::const_iterator ActorConstIter; ///< Const iterator for Dali::ActorContainer
66
67
68 /**
69  * @brief Actor is the primary object with which Dali applications interact.
70  *
71  * UI controls can be built by combining multiple actors.
72  *
73  * <h3>Multi-Touch Events:</h3>
74  *
75  * Touch or hover events are received via signals; see Actor::TouchedSignal() and Actor::HoveredSignal() for more details.
76  *
77  * <i>Hit Testing Rules Summary:</i>
78  *
79  * - An actor is only hittable if the actor's touch or hover signal has a connection.
80  * - An actor is only hittable when it is between the camera's near and far planes.
81  * - If an actor is made insensitive, then the actor and its children are not hittable; see IsSensitive()
82  * - If an actor's visibility flag is unset, then none of its children are hittable either; see IsVisible()
83  * - To be hittable, an actor must have a non-zero size.
84  * - If an actor's world color is fully transparent, then it is not hittable; see GetCurrentWorldColor()
85  *
86  * <i>Hit Test Algorithm:</i>
87  *
88  * - RenderTasks
89  *   - Hit testing is dependent on the camera used, which is specific to each RenderTask.
90  *
91  * - Layers
92  *   - For each RenderTask, hit testing starts from the top-most layer and we go through all the
93  *     layers until we have a hit or there are none left.
94  *   - Before we perform a hit test within a layer, we check if all the layer's parents are visible
95  *     and sensitive.
96  *   - If they are not, we skip hit testing the actors in that layer altogether.
97  *   - If a layer is set to consume all touch, then we do not check any layers behind this layer.
98  *
99  * - Actors
100  *   - The final part of hit testing is performed by walking through the actor tree within a layer.
101  *   - The following pseudocode shows the algorithm used:
102  *     @code
103  *     HIT-TEST-WITHIN-LAYER( ACTOR )
104  *     {
105  *       // Only hit-test the actor and its children if it is sensitive and visible
106  *       IF ( ACTOR-IS-SENSITIVE &&
107  *            ACTOR-IS-VISIBLE )
108  *       {
109  *         // Depth-first traversal within current layer, visiting parent first
110  *
111  *         // Check whether current actor should be hit-tested
112  *         IF ( ( TOUCH-SIGNAL-NOT-EMPTY || HOVER-SIGNAL-NOT-EMPTY ) &&
113  *              ACTOR-HAS-NON-ZERO-SIZE &&
114  *              ACTOR-WORLD-COLOR-IS-NOT-TRANSPARENT )
115  *         {
116  *           // Hit-test current actor
117  *           IF ( ACTOR-HIT )
118  *           {
119  *             IF ( ACTOR-IS-OVERLAY || ( DISTANCE-TO-ACTOR < DISTANCE-TO-LAST-HIT-ACTOR ) )
120  *             {
121  *               // The current actor is the closest actor that was underneath the touch
122  *               LAST-HIT-ACTOR = CURRENT-ACTOR
123  *             }
124  *           }
125  *         }
126  *
127  *         // Keep checking children, in case we hit something closer
128  *         FOR-EACH CHILD (in order)
129  *         {
130  *           IF ( CHILD-IS-NOT-A-LAYER )
131  *           {
132  *             // Continue traversal for this child's sub-tree
133  *             HIT-TEST-WITHIN-LAYER ( CHILD )
134  *           }
135  *           // else we skip hit-testing the child's sub-tree altogether
136  *         }
137  *       }
138  *     }
139  *     @endcode
140  *   - Overlays always take priority (i.e. they're considered closer) regardless of distance.
141  *     The overlay children take priority over their parents, and overlay siblings take priority
142  *     over their previous siblings (i.e. reverse of rendering order):
143  *     @code
144  *           1
145  *          / \
146  *         /   \
147  *        2     5
148  *       / \     \
149  *      /   \     \
150  *     3     4     6
151  *
152  *     Hit Priority of above Actor tree (all overlays): 1 - Lowest. 6 - Highest.
153  *     @endcode
154  *   - Stencil Actors can be used to influence the result of hits on renderable actors within a layer.
155  *     If a Stencil Actor exists on a layer and that Actor is marked visible then a successful
156  *     hit on a renderable actor can only take place in the area that the stencil Actor marks as visible.
157  *     The hit can be in any Stencil Actor in that layer, but must be in the region of one of them.
158  *     Stencil Actor inheritance behaves as with rendering in that any child of a Stencil Actor will
159  *     also be considered a Stencil Actor.
160  *     Non-renderable actors can be hit regardless of whether a stencil actor is hit or not.
161  *
162  * <i>Touch or hover Event Delivery:</i>
163  *
164  * - Delivery
165  *   - The hit actor's touch or hover signal is emitted first; if it is not consumed by any of the listeners,
166  *     the parent's touch or hover signal is emitted, and so on.
167  *   - The following pseudocode shows the delivery mechanism:
168  *     @code
169  *     EMIT-TOUCH-SIGNAL( ACTOR )
170  *     {
171  *       IF ( TOUCH-SIGNAL-NOT-EMPTY )
172  *       {
173  *         // Only do the emission if touch signal of actor has connections.
174  *         CONSUMED = TOUCHED-SIGNAL( TOUCH-EVENT )
175  *       }
176  *
177  *       IF ( NOT-CONSUMED )
178  *       {
179  *         // If event is not consumed then deliver it to the parent unless we reach the root actor
180  *         IF ( ACTOR-PARENT )
181  *         {
182  *           EMIT-TOUCH-SIGNAL( ACTOR-PARENT )
183  *         }
184  *       }
185  *     }
186  *
187  *     EMIT-HOVER-SIGNAL( ACTOR )
188  *     {
189  *       IF ( HOVER-SIGNAL-NOT-EMPTY )
190  *       {
191  *         // Only do the emission if hover signal of actor has connections.
192  *         CONSUMED = HOVERED-SIGNAL( HOVER-EVENT )
193  *       }
194  *
195  *       IF ( NOT-CONSUMED )
196  *       {
197  *         // If event is not consumed then deliver it to the parent unless we reach the root actor
198  *         IF ( ACTOR-PARENT )
199  *         {
200  *           EMIT-HOVER-SIGNAL( ACTOR-PARENT )
201  *         }
202  *       }
203  *     }
204  *     @endcode
205  *   - If there are several touch points, then the delivery is only to the first touch point's hit
206  *     actor (and its parents).  There will be NO touch or hover signal delivery for the hit actors of the
207  *     other touch points.
208  *   - The local coordinates are from the top-left (0.0f, 0.0f, 0.5f) of the hit actor.
209  *
210  * - Leave State
211  *   - A "Leave" state is set when the first point exits the bounds of the previous first point's
212  *     hit actor (primary hit actor).
213  *   - When this happens, the last primary hit actor's touch or hover signal is emitted with a "Leave" state
214  *     (only if it requires leave signals); see SetLeaveRequired().
215  *
216  * - Interrupted State
217  *   - If a system event occurs which interrupts the touch or hover processing, then the last primary hit
218  *     actor's touch or hover signals are emitted with an "Interrupted" state.
219  *   - If the last primary hit actor, or one of its parents, is no longer touchable or hoverable, then its
220  *     touch or hover signals are also emitted with an "Interrupted" state.
221  *   - If the consumed actor on touch-down is not the same as the consumed actor on touch-up, then
222  *     touch signals are also emitted from the touch-down actor with an "Interrupted" state.
223  *   - If the consumed actor on hover-start is not the same as the consumed actor on hover-finished, then
224  *     hover signals are also emitted from the hover-started actor with an "Interrupted" state.
225  * <h3>Key Events:</h3>
226  *
227  * Key events are received by an actor once set to grab key events, only one actor can be set as focused.
228  *
229  * @nosubgrouping
230  *
231  * Signals
232  * | %Signal Name      | Method                       |
233  * |-------------------|------------------------------|
234  * | touched           | @ref TouchedSignal()         |
235  * | hovered           | @ref HoveredSignal()         |
236  * | mouse-wheel-event | @ref MouseWheelEventSignal() |
237  * | on-stage          | @ref OnStageSignal()         |
238  * | off-stage         | @ref OffStageSignal()        |
239  *
240  * Actions
241  * | %Action Name      | %Actor method called         |
242  * |-------------------|------------------------------|
243  * | show              | %SetVisible( true )          |
244  * | hide              | %SetVisible( false )         |
245  */
246 class DALI_IMPORT_API Actor : public Handle
247 {
248 public:
249
250   /**
251    * @brief An enumeration of properties belonging to the Actor class.
252    */
253   struct Property
254   {
255     enum
256     {
257       ParentOrigin = DEFAULT_ACTOR_PROPERTY_START_INDEX, ///< name "parent-origin",         type Vector3
258       ParentOriginX,                                     ///< name "parent-origin-x",       type Float
259       ParentOriginY,                                     ///< name "parent-origin-y",       type Float
260       ParentOriginZ,                                     ///< name "parent-origin-z",       type Float
261       AnchorPoint,                                       ///< name "anchor-point",          type Vector3
262       AnchorPointX,                                      ///< name "anchor-point-x",        type Float
263       AnchorPointY,                                      ///< name "anchor-point-y",        type Float
264       AnchorPointZ,                                      ///< name "anchor-point-z",        type Float
265       Size,                                              ///< name "size",                  type Vector3
266       SizeWidth,                                         ///< name "size-width",            type Float
267       SizeHeight,                                        ///< name "size-height",           type Float
268       SizeDepth,                                         ///< name "size-depth",            type Float
269       Position,                                          ///< name "position",              type Vector3
270       PositionX,                                         ///< name "position-x",            type Float
271       PositionY,                                         ///< name "position-y",            type Float
272       PositionZ,                                         ///< name "position-z",            type Float
273       WorldPosition,                                     ///< name "world-position",        type Vector3  (read-only)
274       WorldPositionX,                                    ///< name "world-position-x",      type Float    (read-only)
275       WorldPositionY,                                    ///< name "world-position-y",      type Float    (read-only)
276       WorldPositionZ,                                    ///< name "world-position-z",      type Float    (read-only)
277       Rotation,                                          ///< name "rotation",              type Rotation
278       WorldRotation,                                     ///< name "world-rotation",        type Rotation (read-only)
279       Scale,                                             ///< name "scale",                 type Vector3
280       ScaleX,                                            ///< name "scale-x",               type Float
281       ScaleY,                                            ///< name "scale-y",               type Float
282       ScaleZ,                                            ///< name "scale-z",               type Float
283       WorldScale,                                        ///< name "world-scale",           type Vector3  (read-only)
284       Visible,                                           ///< name "visible",               type Boolean
285       Color,                                             ///< name "color",                 type Vector4
286       ColorRed,                                          ///< name "color-red",             type Float
287       ColorGreen,                                        ///< name "color-green",           type Float
288       ColorBlue,                                         ///< name "color-blue",            type Float
289       ColorAlpha,                                        ///< name "color-alpha",           type Float
290       WorldColor,                                        ///< name "world-color",           type Vector4  (read-only)
291       WorldMatrix,                                       ///< name "world-matrix",          type Matrix   (read-only)
292       Name,                                              ///< name "name",                  type String
293       Sensitive,                                         ///< name "sensitive",             type Boolean
294       LeaveRequired,                                     ///< name "leave-required",        type Boolean
295       InheritRotation,                                   ///< name "inherit-rotation",      type Boolean
296       InheritScale,                                      ///< name "inherit-scale",         type Boolean
297       ColorMode,                                         ///< name "color-mode",            type String
298       PositionInheritance,                               ///< name "position-inheritance",  type String
299       DrawMode,                                          ///< name "draw-mode",             type String
300       SizeMode,                                          ///< name "size-mode",             type String
301       SizeModeFactor,                                    ///< name "size-mode-factor",      type Vector3
302     };
303   };
304
305   // Typedefs
306
307   typedef Signal< bool (Actor, const TouchEvent&)> TouchSignalType;                 ///< Touch signal type
308   typedef Signal< bool (Actor, const HoverEvent&)> HoverSignalType;                 ///< Hover signal type
309   typedef Signal< bool (Actor, const MouseWheelEvent&) > MouseWheelEventSignalType; ///< Mousewheel signal type
310   typedef Signal< void (Actor) > OnStageSignalType;  ///< Stage connection signal type
311   typedef Signal< void (Actor) > OffStageSignalType; ///< Stage disconnection signal type
312
313   // Creation
314
315   /**
316    * @brief Create an uninitialized Actor; this can be initialized with Actor::New().
317    *
318    * Calling member functions with an uninitialized Dali::Object is not allowed.
319    */
320   Actor();
321
322   /**
323    * @brief Create an initialized Actor.
324    *
325    * @return A handle to a newly allocated Dali resource.
326    */
327   static Actor New();
328
329   /**
330    * @brief Downcast an Object handle to Actor handle.
331    *
332    * If handle points to a Actor object the downcast produces valid
333    * handle. If not the returned handle is left uninitialized.
334    *
335    * @param[in] handle to An object
336    * @return handle to a Actor object or an uninitialized handle
337    */
338   static Actor DownCast( BaseHandle handle );
339
340   /**
341    * @brief Dali::Actor is intended as a base class
342    *
343    * This is non-virtual since derived Handle types must not contain data or virtual methods.
344    */
345   ~Actor();
346
347   /**
348    * @brief Copy constructor
349    *
350    * @param [in] copy The actor to copy.
351    */
352   Actor(const Actor& copy);
353
354   /**
355    * @brief Assignment operator
356    *
357    * @param [in] rhs The actor to copy.
358    */
359   Actor& operator=(const Actor& rhs);
360
361   /**
362    * @brief Retrieve the Actor's name.
363    *
364    * @pre The Actor has been initialized.
365    * @return The Actor's name.
366    */
367   const std::string& GetName() const;
368
369   /**
370    * @brief Sets the Actor's name.
371    *
372    * @pre The Actor has been initialized.
373    * @param [in] name The new name.
374    */
375   void SetName(const std::string& name);
376
377   /**
378    * @brief Retrieve the unique ID of the actor.
379    *
380    * @pre The Actor has been initialized.
381    * @return The ID.
382    */
383   unsigned int GetId() const;
384
385   // Containment
386
387   /**
388    * @brief Query whether an actor is the root actor, which is owned by the Stage.
389    *
390    * @pre The Actor has been initialized.
391    * @return True if the actor is the root actor.
392    */
393   bool IsRoot() const;
394
395   /**
396    * @brief Query whether the actor is connected to the Stage.
397    *
398    * When an actor is connected, it will be directly or indirectly parented to the root Actor.
399    * @note The root Actor is provided automatically by Dali::Stage, and is always considered to be connected.
400    * @pre The Actor has been initialized.
401    * @return True if the actor is connected to the Stage.
402    */
403   bool OnStage() const;
404
405   /**
406    * @brief Query whether the actor is of class Dali::Layer.
407    *
408    * @pre The Actor has been initialized.
409    * @return True if the actor is a layer.
410    */
411   bool IsLayer() const;
412
413   /**
414    * @brief Gets the layer in which the actor is present.
415    *
416    * @pre The Actor has been initialized.
417    * @return The layer, which will be uninitialized if the actor is off-stage.
418    */
419   Layer GetLayer();
420
421   /**
422    * @brief Adds a child Actor to this Actor.
423    *
424    * NOTE! if the child already has a parent, it will be removed from old parent
425    * and reparented to this actor. This may change childs position, color,
426    * scale etc as it now inherits them from this actor
427    * @pre This Actor (the parent) has been initialized.
428    * @pre The child actor has been initialized.
429    * @pre The child actor is not the same as the parent actor.
430    * @pre The actor is not the Root actor
431    * @param [in] child The child.
432    * @post The child will be referenced by its parent. This means that the child will be kept alive,
433    * even if the handle passed into this method is reset or destroyed.
434    * @post This may invalidate ActorContainer iterators.
435    */
436   void Add(Actor child);
437
438   /**
439    * @brief Inserts a child Actor to this actor's list of children at the given index
440    *
441    * NOTE! if the child already has a parent, it will be removed from old parent
442    * and reparented to this actor. This may change childs position, color,
443    * scale etc as it now inherits them from this actor
444    * @pre This Actor (the parent) has been initialized.
445    * @pre The child actor has been initialized.
446    * @pre The child actor is not the same as the parent actor.
447    * @pre The actor is not the Root actor
448    * @param [in] index of actor to insert before
449    * @param [in] child The child.
450    * @post The child will be referenced by its parent. This means that the child will be kept alive,
451    * even if the handle passed into this method is reset or destroyed.
452    * @post If the index is greater than the current child count, it will be ignored and added at the end.
453    * @post This may invalidate ActorContainer iterators.
454    */
455   void Insert(unsigned int index, Actor child);
456
457   /**
458    * @brief Removes a child Actor from this Actor.
459    *
460    * If the actor was not a child of this actor, this is a no-op.
461    * @pre This Actor (the parent) has been initialized.
462    * @pre The child actor is not the same as the parent actor.
463    * @param [in] child The child.
464    * @post This may invalidate ActorContainer iterators.
465    */
466   void Remove(Actor child);
467
468   /**
469    * @brief Removes an actor from its parent.
470    *
471    * If the actor has no parent, this method does nothing.
472    * @pre The (child) actor has been initialized.
473    * @post This may invalidate ActorContainer iterators.
474    */
475   void Unparent();
476
477   /**
478    * @brief Retrieve the number of children held by the actor.
479    *
480    * @pre The Actor has been initialized.
481    * @return The number of children
482    */
483   unsigned int GetChildCount() const;
484
485   /**
486    * @brief Retrieve and child actor by index.
487    *
488    * @pre The Actor has been initialized.
489    * @param[in] index The index of the child to retrieve
490    * @return The actor for the given index or empty handle if children not initialised
491    */
492   Actor GetChildAt(unsigned int index) const;
493
494   /**
495    * @brief Search through this actor's hierarchy for an actor with the given name.
496    *
497    * The actor itself is also considered in the search
498    * @pre The Actor has been initialized.
499    * @param[in] actorName the name of the actor to find
500    * @return A handle to the actor if found, or an empty handle if not.
501    */
502   Actor FindChildByName(const std::string& actorName);
503
504   /**
505    * @brief Search through this actor's hierarchy for an actor with the given name or alias.
506    *
507    * Actors can customize this function to provide actors with preferred alias'
508    * For example 'previous' could return the last selected child.
509    * If no aliased actor is found then FindChildByName() is called.
510    * @pre The Actor has been initialized.
511    * @param[in] actorAlias the name of the actor to find
512    * @return A handle to the actor if found, or an empty handle if not.
513    */
514   Actor FindChildByAlias(const std::string& actorAlias);
515
516   /**
517    * @brief Search through this actor's hierarchy for an actor with the given unique ID.
518    *
519    * The actor itself is also considered in the search
520    * @pre The Actor has been initialized.
521    * @param[in] id the ID of the actor to find
522    * @return A handle to the actor if found, or an empty handle if not.
523    */
524   Actor FindChildById(const unsigned int id);
525
526   /**
527    * @brief Retrieve the actor's parent.
528    *
529    * @pre The actor has been initialized.
530    * @return A handle to the actor's parent. If the actor has no parent, this handle will be invalid.
531    */
532   Actor GetParent() const;
533
534   // Positioning
535
536   /**
537    * @brief Set the origin of an actor, within its parent's area.
538    *
539    * This is expressed in unit coordinates, such that (0.0, 0.0, 0.5) is the top-left corner of the parent,
540    * and (1.0, 1.0, 0.5) is the bottom-right corner.
541    * The default parent-origin is Dali::ParentOrigin::TOP_LEFT (0.0, 0.0, 0.5).
542    * An actor position is the distance between this origin, and the actors anchor-point.
543    * @see Dali::ParentOrigin for predefined parent origin values
544    * @pre The Actor has been initialized.
545    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentParentOrigin().
546    * @param [in] origin The new parent-origin.
547    */
548   void SetParentOrigin(const Vector3& origin);
549
550   /**
551    * @brief Retrieve the parent-origin of an actor.
552    *
553    * @pre The Actor has been initialized.
554    * @note This property can be animated; the return value may not match the value written with SetParentOrigin().
555    * @return The current parent-origin.
556    */
557   Vector3 GetCurrentParentOrigin() const;
558
559   /**
560    * @brief Set the anchor-point of an actor.
561    *
562    * This is expressed in unit coordinates, such that (0.0, 0.0, 0.5)
563    * is the top-left corner of the actor, and (1.0, 1.0, 0.5) is the
564    * bottom-right corner.  The default anchor point is
565    * Dali::AnchorPoint::CENTER (0.5, 0.5, 0.5).
566    * An actor position is the distance between its parent-origin, and this anchor-point.
567    * An actor's rotation is centered around its anchor-point.
568    * @see Dali::AnchorPoint for predefined anchor point values
569    * @pre The Actor has been initialized.
570    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentAnchorPoint().
571    * @param [in] anchorPoint The new anchor-point.
572    */
573   void SetAnchorPoint(const Vector3& anchorPoint);
574
575   /**
576    * @brief Retrieve the anchor-point of an actor.
577    *
578    * @pre The Actor has been initialized.
579    * @note This property can be animated; the return value may not match the value written with SetAnchorPoint().
580    * @return The current anchor-point.
581    */
582   Vector3 GetCurrentAnchorPoint() const;
583
584   /**
585    * @brief Sets the size of an actor.
586    *
587    * Geometry can be scaled to fit within this area.
588    * This does not interfere with the actors scale factor.
589    * The actors default depth is the minimum of width & height.
590    * @pre The actor has been initialized.
591    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentSize().
592    * @param [in] width  The new width.
593    * @param [in] height The new height.
594    */
595   void SetSize(float width, float height);
596
597   /**
598    * @brief Sets the size of an actor.
599    *
600    * Geometry can be scaled to fit within this area.
601    * This does not interfere with the actors scale factor.
602    * @pre The actor has been initialized.
603    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentSize().
604    * @param [in] width  The size of the actor along the x-axis.
605    * @param [in] height The size of the actor along the y-axis.
606    * @param [in] depth The size of the actor along the z-axis.
607    */
608   void SetSize(float width, float height, float depth);
609
610   /**
611    * @brief Sets the size of an actor.
612    *
613    * Geometry can be scaled to fit within this area.
614    * This does not interfere with the actors scale factor.
615    * The actors default depth is the minimum of width & height.
616    * @pre The actor has been initialized.
617    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentSize().
618    * @param [in] size The new size.
619    */
620   void SetSize(const Vector2& size);
621
622   /**
623    * @brief Sets the size of an actor.
624    *
625    * Geometry can be scaled to fit within this area.
626    * This does not interfere with the actors scale factor.
627    * @pre The actor has been initialized.
628    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentSize().
629    * @param [in] size The new size.
630    */
631   void SetSize(const Vector3& size);
632
633   /**
634    * @brief Retrieve the actor's size.
635    *
636    * @pre The actor has been initialized.
637    * @note This return is the value that was set using SetSize or the target size of an animation
638    * @return The actor's current size.
639    */
640   Vector3 GetSize() const;
641
642   /**
643    * @brief Retrieve the actor's size.
644    *
645    * @pre The actor has been initialized.
646    * @note This property can be animated; the return value may not match the value written with SetSize().
647    * @return The actor's current size.
648    */
649   Vector3 GetCurrentSize() const;
650
651   /**
652    * Return the natural size of the actor.
653    *
654    * Deriving classes stipulate the natural size and by default an actor has a ZERO natural size.
655    *
656    * @return The actor's natural size
657    */
658   Vector3 GetNaturalSize() const;
659
660   /**
661    * @brief Sets the position of the actor.
662    *
663    * The Actor's z position will be set to 0.0f.
664    * @pre The Actor has been initialized.
665    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentPosition().
666    * @param [in] x The new x position
667    * @param [in] y The new y position
668    */
669   void SetPosition(float x, float y);
670
671   /**
672    * @brief Sets the position of the Actor.
673    *
674    * @pre The Actor has been initialized.
675    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentPosition().
676    * @param [in] x The new x position
677    * @param [in] y The new y position
678    * @param [in] z The new z position
679    */
680   void SetPosition(float x, float y, float z);
681
682   /**
683    * @brief Sets the position of the Actor.
684    *
685    * @pre The Actor has been initialized.
686    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentPosition().
687    * @param [in] position The new position
688    */
689   void SetPosition(const Vector3& position);
690
691   /**
692    * @brief Set the position of an actor along the X-axis.
693    *
694    * @pre The Actor has been initialized.
695    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentPosition().
696    * @param [in] x The new x position
697    */
698   void SetX(float x);
699
700   /**
701    * @brief Set the position of an actor along the Y-axis.
702    *
703    * @pre The Actor has been initialized.
704    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentPosition().
705    * @param [in] y The new y position.
706    */
707   void SetY(float y);
708
709   /**
710    * @brief Set the position of an actor along the Z-axis.
711    *
712    * @pre The Actor has been initialized.
713    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentPosition().
714    * @param [in] z The new z position
715    */
716   void SetZ(float z);
717
718   /**
719    * @brief Move an actor relative to its existing position.
720    *
721    * @pre The actor has been initialized.
722    * @param[in] distance The actor will move by this distance.
723    */
724   void MoveBy(const Vector3& distance);
725
726   /**
727    * @brief Retrieve the position of the Actor.
728    *
729    * @pre The Actor has been initialized.
730    * @note This property can be animated; the return value may not match the value written with SetPosition().
731    * @return the Actor's current position.
732    */
733   Vector3 GetCurrentPosition() const;
734
735   /**
736    * @brief Retrieve the world-position of the Actor.
737    *
738    * @note The actor will not have a world-position, unless it has previously been added to the stage.
739    * @pre The Actor has been initialized.
740    * @return The Actor's current position in world coordinates.
741    */
742   Vector3 GetCurrentWorldPosition() const;
743
744   /**
745    * @brief Set the actors position inheritance mode.
746    *
747    * The default is to inherit.
748    * Switching this off means that using SetPosition() sets the actor's world position.
749    * @see PositionInheritanceMode
750    * @pre The Actor has been initialized.
751    * @param[in] mode to use
752    */
753   void SetPositionInheritanceMode( PositionInheritanceMode mode );
754
755   /**
756    * @brief Returns the actors position inheritance mode.
757    *
758    * @pre The Actor has been initialized.
759    * @return true if the actor inherit's it's parent orientation, false if it uses world orientation.
760    */
761   PositionInheritanceMode GetPositionInheritanceMode() const;
762
763   /**
764    * @brief Sets the rotation of the Actor.
765    *
766    * An actor's rotation is centered around its anchor point.
767    * @pre The Actor has been initialized.
768    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentRotation().
769    * @param [in] angle The new rotation angle in degrees.
770    * @param [in] axis The new axis of rotation.
771    */
772   void SetRotation(const Degree& angle, const Vector3& axis);
773
774   /**
775    * @brief Sets the rotation of the Actor.
776    *
777    * An actor's rotation is centered around its anchor point.
778    * @pre The Actor has been initialized.
779    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentRotation().
780    * @param [in] angle The new rotation angle in radians.
781    * @param [in] axis The new axis of rotation.
782    */
783   void SetRotation(const Radian& angle, const Vector3& axis);
784
785   /**
786    * @brief Sets the rotation of the Actor.
787    *
788    * @pre The Actor has been initialized.
789    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentRotation().
790    * @param [in] rotation The new rotation.
791    */
792   void SetRotation(const Quaternion& rotation);
793
794   /**
795    * @brief Apply a relative rotation to an actor.
796    *
797    * @pre The actor has been initialized.
798    * @param[in] angle The angle to the rotation to combine with the existing rotation.
799    * @param[in] axis The axis of the rotation to combine with the existing rotation.
800    */
801   void RotateBy(const Degree& angle, const Vector3& axis);
802
803   /**
804    * @brief Apply a relative rotation to an actor.
805    *
806    * @pre The actor has been initialized.
807    * @param[in] angle The angle to the rotation to combine with the existing rotation.
808    * @param[in] axis The axis of the rotation to combine with the existing rotation.
809    */
810   void RotateBy(const Radian& angle, const Vector3& axis);
811
812   /**
813    * @brief Apply a relative rotation to an actor.
814    *
815    * @pre The actor has been initialized.
816    * @param[in] relativeRotation The rotation to combine with the existing rotation.
817    */
818   void RotateBy(const Quaternion& relativeRotation);
819
820   /**
821    * @brief Retreive the Actor's rotation.
822    *
823    * @pre The Actor has been initialized.
824    * @note This property can be animated; the return value may not match the value written with SetRotation().
825    * @return The current rotation.
826    */
827   Quaternion GetCurrentRotation() const;
828
829   /**
830    * @brief Set whether a child actor inherits it's parent's orientation.
831    *
832    * Default is to inherit.
833    * Switching this off means that using SetRotation() sets the actor's world orientation.
834    * @pre The Actor has been initialized.
835    * @param[in] inherit - true if the actor should inherit orientation, false otherwise.
836    */
837   void SetInheritRotation(bool inherit);
838
839   /**
840    * @brief Returns whether the actor inherit's it's parent's orientation.
841    *
842    * @pre The Actor has been initialized.
843    * @return true if the actor inherit's it's parent orientation, false if it uses world orientation.
844    */
845   bool IsRotationInherited() const;
846
847   /**
848    * @brief Retrieve the world-rotation of the Actor.
849    *
850    * @note The actor will not have a world-rotation, unless it has previously been added to the stage.
851    * @pre The Actor has been initialized.
852    * @return The Actor's current rotation in the world.
853    */
854   Quaternion GetCurrentWorldRotation() const;
855
856   /**
857    * @brief Set the scale factor applied to an actor.
858    *
859    * @pre The Actor has been initialized.
860    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentScale().
861    * @param [in] scale The scale factor applied on all axes.
862    */
863   void SetScale(float scale);
864
865   /**
866    * @brief Set the scale factor applied to an actor.
867    *
868    * @pre The Actor has been initialized.
869    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentScale().
870    * @param [in] scaleX The scale factor applied along the x-axis.
871    * @param [in] scaleY The scale factor applied along the y-axis.
872    * @param [in] scaleZ The scale factor applied along the z-axis.
873    */
874   void SetScale(float scaleX, float scaleY, float scaleZ);
875
876   /**
877    * @brief Set the scale factor applied to an actor.
878    *
879    * @pre The Actor has been initialized.
880    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentScale().
881    * @param [in] scale A vector representing the scale factor for each axis.
882    */
883   void SetScale(const Vector3& scale);
884
885   /**
886    * @brief Apply a relative scale to an actor.
887    *
888    * @pre The actor has been initialized.
889    * @param[in] relativeScale The scale to combine with the actors existing scale.
890    */
891   void ScaleBy(const Vector3& relativeScale);
892
893   /**
894    * @brief Retrieve the scale factor applied to an actor.
895    *
896    * @pre The Actor has been initialized.
897    * @note This property can be animated; the return value may not match the value written with SetScale().
898    * @return A vector representing the scale factor for each axis.
899    */
900   Vector3 GetCurrentScale() const;
901
902   /**
903    * @brief Retrieve the world-scale of the Actor.
904    *
905    * @note The actor will not have a world-scale, unless it has previously been added to the stage.
906    * @pre The Actor has been initialized.
907    * @return The Actor's current scale in the world.
908    */
909   Vector3 GetCurrentWorldScale() const;
910
911   /**
912    * @brief Set whether a child actor inherits it's parent's scale.
913    *
914    * Default is to inherit.
915    * Switching this off means that using SetScale() sets the actor's world scale.
916    * @pre The Actor has been initialized.
917    * @param[in] inherit - true if the actor should inherit scale, false otherwise.
918    */
919   void SetInheritScale( bool inherit );
920
921   /**
922    * @brief Returns whether the actor inherit's it's parent's scale.
923    *
924    * @pre The Actor has been initialized.
925    * @return true if the actor inherit's it's parent scale, false if it uses world scale.
926    */
927   bool IsScaleInherited() const;
928
929   /**
930    * @brief Defines how a child actor's size is affected by its parent's size.
931    *
932    * The default is to ignore the parent's size and use the size property of this actor.
933    *
934    * If USE_OWN_SIZE is used, this option is bypassed and the actor's size
935    *     property is used.
936    *
937    * If SIZE_EQUAL_TO_PARENT is used, this actor's size will be equal to that
938    *     of its parent. The actor's size property is ignored.
939    *
940    * If SIZE_RELATIVE_TO_PARENT is used, this actor's size will be based on
941    *     its parent's size by multiplying the parent size by
942    *     SizeModeFactor.
943    *
944    * If SIZE_FIXED_OFFSET_FROM_PARENT is used, this actor's size will be based on
945    *     its parent's size plus SizeModeFactor.
946    *
947    * @pre The Actor has been initialized.
948    * @param[in] mode The size relative to parent mode to use.
949    */
950   void SetSizeMode(const SizeMode mode);
951
952   /**
953    * @brief Returns the actor's mode for modifying its size relative to its parent.
954    *
955    * @pre The Actor has been initialized.
956    * @return The mode used.
957    */
958   SizeMode GetSizeMode() const;
959
960   /**
961    * @brief Sets the relative to parent size factor of the actor.
962    *
963    * This factor is only used when SizeMode is set to either:
964    * SIZE_RELATIVE_TO_PARENT or SIZE_FIXED_OFFSET_FROM_PARENT.
965    * This actor's size is set to the actor's parent size multipled by or added to this factor,
966    * depending on SideMode (See SetSizeMode).
967    *
968    * @pre The Actor has been initialized.
969    * @param [in] factor A Vector3 representing the relative factor to be applied to each axis.
970    */
971   void SetSizeModeFactor(const Vector3& factor);
972
973   /**
974    * @brief Retrieve the relative to parent size factor of the actor.
975    *
976    * @pre The Actor has been initialized.
977    * @return The Actor's current relative size factor.
978    */
979   Vector3 GetSizeModeFactor() const;
980
981   /**
982    * @brief Retrieves the world-matrix of the actor.
983    *
984    * @note The actor will not have a world-matrix, unless it has previously been added to the stage.
985    * @pre The Actor has been initialized.
986    * @return The Actor's current world matrix
987    */
988   Matrix GetCurrentWorldMatrix() const;
989
990   // Visibility & Color
991
992   /**
993    * @brief Sets the visibility flag of an actor.
994    *
995    * @pre The actor has been initialized.
996    * @note This is an asynchronous method; the value written may not match a value subsequently read with IsVisible().
997    * @note If an actor's visibility flag is set to false, then the actor and its children will not be rendered.
998    *       This is regardless of the individual visibility values of the children i.e. an actor will only be
999    *       rendered if all of its parents have visibility set to true.
1000    * @param [in] visible The new visibility flag.
1001    */
1002   void SetVisible(bool visible);
1003
1004   /**
1005    * @brief Retrieve the visibility flag of an actor.
1006    *
1007    * @pre The actor has been initialized.
1008    * @note This property can be animated; the return value may not match the value written with SetVisible().
1009    * @note If an actor is not visible, then the actor and its children will not be rendered.
1010    *       This is regardless of the individual visibility values of the children i.e. an actor will only be
1011    *       rendered if all of its parents have visibility set to true.
1012    * @return The visibility flag.
1013    */
1014   bool IsVisible() const;
1015
1016   /**
1017    * @brief Sets the opacity of an actor.
1018    *
1019    * @pre The actor has been initialized.
1020    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentOpacity().
1021    * @param [in] opacity The new opacity.
1022    */
1023   void SetOpacity(float opacity);
1024
1025   /**
1026    * @brief Apply a relative opacity change to an actor.
1027    *
1028    * @pre The actor has been initialized.
1029    * @param[in] relativeOpacity The opacity to combine with the actors existing opacity.
1030    */
1031   void OpacityBy(float relativeOpacity);
1032
1033   /**
1034    * @brief Retrieve the actor's opacity.
1035    *
1036    * @pre The actor has been initialized.
1037    * @note This property can be animated; the return value may not match the value written with SetOpacity().
1038    * @return The actor's opacity.
1039    */
1040   float GetCurrentOpacity() const;
1041
1042   /**
1043    * @brief Sets the actor's color; this is an RGBA value.
1044    *
1045    * The final color of the actor depends on its color mode.
1046    * @pre The Actor has been initialized.
1047    * @note This is an asynchronous method; the value written may not match a value subsequently read with GetCurrentColor().
1048    * @param [in] color The new color.
1049    */
1050   void SetColor(const Vector4& color);
1051
1052   /**
1053    * @brief Apply a relative color change to an actor.
1054    *
1055    * @pre The actor has been initialized.
1056    * @param[in] relativeColor The color to combine with the actors existing color.
1057    */
1058   void ColorBy(const Vector4& relativeColor);
1059
1060   /**
1061    * @brief Retrieve the actor's color.
1062    *
1063    * Actor's own color is not clamped.
1064    * @pre The Actor has been initialized.
1065    * @note This property can be animated; the return value may not match the value written with SetColor().
1066    * @return The color.
1067    */
1068   Vector4 GetCurrentColor() const;
1069
1070   /**
1071    * @brief Sets the actor's color mode.
1072    *
1073    * This specifies whether the Actor uses its own color, or inherits
1074    * its parent color. The default is USE_OWN_MULTIPLY_PARENT_ALPHA.
1075    * @pre The Actor has been initialized.
1076    * @param [in] colorMode to use.
1077    */
1078   void SetColorMode( ColorMode colorMode );
1079
1080   /**
1081    * @brief Returns the actor's color mode.
1082    *
1083    * @pre The Actor has been initialized.
1084    * @return currently used colorMode.
1085    */
1086   ColorMode GetColorMode() const;
1087
1088   /**
1089    * @brief Retrieve the world-color of the Actor, where each component is clamped within the 0->1 range.
1090    *
1091    * @note The actor will not have a world-color, unless it has previously been added to the stage.
1092    * @pre The Actor has been initialized.
1093    * @return The Actor's current color in the world.
1094    */
1095   Vector4 GetCurrentWorldColor() const;
1096
1097   /**
1098    * @brief Set how the actor and its children should be drawn.
1099    *
1100    * Not all actors are renderable, but DrawMode can be inherited from any actor.
1101    * By default a renderable actor will be drawn as a 3D object. It will be depth-tested against
1102    * other objects in the world i.e. it may be obscured if other objects are in front.
1103    *
1104    * If DrawMode::OVERLAY is used, the actor and its children will be drawn as a 2D overlay.
1105    * Overlay actors are drawn in a separate pass, after all non-overlay actors within the Layer.
1106    * For overlay actors, the drawing order is determined by the hierachy (depth-first search order),
1107    * and depth-testing will not be used.
1108    *
1109    * If DrawMode::STENCIL is used, the actor and its children will be used to stencil-test other actors
1110    * within the Layer. Stencil actors are therefore drawn into the stencil buffer before any other
1111    * actors within the Layer.
1112    *
1113    * @param[in] drawMode The new draw-mode to use.
1114    * @note Setting STENCIL will override OVERLAY, if that would otherwise have been inherited.
1115    * @note Layers do not inherit the DrawMode from their parents.
1116    */
1117   void SetDrawMode( DrawMode::Type drawMode );
1118
1119   /**
1120    * @brief Query how the actor and its children will be drawn.
1121    *
1122    * @return True if the Actor is an overlay.
1123    */
1124   DrawMode::Type GetDrawMode() const;
1125
1126   // Input Handling
1127
1128   /**
1129    * @brief Sets whether an actor should emit touch or hover signals; see SignalTouch() and SignalHover().
1130    *
1131    * An actor is sensitive by default, which means that as soon as an application connects to the SignalTouch(),
1132    * the touch event signal will be emitted, and as soon as an application connects to the SignalHover(), the
1133    * hover event signal will be emitted.
1134    *
1135    * If the application wishes to temporarily disable the touch or hover event signal emission, then they can do so by calling:
1136    * @code
1137    * actor.SetSensitive(false);
1138    * @endcode
1139    *
1140    * Then, to re-enable the touch or hover event signal emission, the application should call:
1141    * @code
1142    * actor.SetSensitive(true);
1143    * @endcode
1144    *
1145    * @see @see SignalTouch() and SignalHover().
1146    * @note If an actor's sensitivity is set to false, then it's children will not be hittable either.
1147    *       This is regardless of the individual sensitivity values of the children i.e. an actor will only be
1148    *       hittable if all of its parents have sensitivity set to true.
1149    * @pre The Actor has been initialized.
1150    * @param[in]  sensitive  true to enable emission of the touch or hover event signals, false otherwise.
1151    */
1152   void SetSensitive(bool sensitive);
1153
1154   /**
1155    * @brief Query whether an actor emits touch or hover event signals.
1156    *
1157    * @note If an actor is not sensitive, then it's children will not be hittable either.
1158    *       This is regardless of the individual sensitivity values of the children i.e. an actor will only be
1159    *       hittable if all of its parents have sensitivity set to true.
1160    * @pre The Actor has been initialized.
1161    * @return true, if emission of touch or hover event signals is enabled, false otherwise.
1162    */
1163   bool IsSensitive() const;
1164
1165   /**
1166    * @brief Converts screen coordinates into the actor's coordinate system using the default camera.
1167    *
1168    * @note The actor coordinates are relative to the top-left (0.0, 0.0, 0.5)
1169    * @pre The Actor has been initialized.
1170    * @param[out] localX On return, the X-coordinate relative to the actor.
1171    * @param[out] localY On return, the Y-coordinate relative to the actor.
1172    * @param[in] screenX The screen X-coordinate.
1173    * @param[in] screenY The screen Y-coordinate.
1174    * @return True if the conversion succeeded.
1175    */
1176   bool ScreenToLocal(float& localX, float& localY, float screenX, float screenY) const;
1177
1178   /**
1179    * @brief Sets whether the actor should receive a notification when touch or hover motion events leave
1180    * the boundary of the actor.
1181    *
1182    * @note By default, this is set to false as most actors do not require this.
1183    * @note Need to connect to the SignalTouch or SignalHover to actually receive this event.
1184    *
1185    * @pre The Actor has been initialized.
1186    * @param[in]  required  Should be set to true if a Leave event is required
1187    */
1188   void SetLeaveRequired(bool required);
1189
1190   /**
1191    * @brief This returns whether the actor requires touch or hover events whenever touch or hover motion events leave
1192    * the boundary of the actor.
1193    *
1194    * @pre The Actor has been initialized.
1195    * @return true if a Leave event is required, false otherwise.
1196    */
1197   bool GetLeaveRequired() const;
1198
1199   /**
1200    * @brief Sets whether the actor should be focusable by keyboard navigation.
1201    *
1202    * The default is true.
1203    * @pre The Actor has been initialized.
1204    * @param[in] focusable - true if the actor should be focusable by keyboard navigation,
1205    * false otherwise.
1206    */
1207   void SetKeyboardFocusable( bool focusable );
1208
1209   /**
1210    * @brief Returns whether the actor is focusable by keyboard navigation.
1211    *
1212    * @pre The Actor has been initialized.
1213    * @return true if the actor is focusable by keyboard navigation, false if not.
1214    */
1215   bool IsKeyboardFocusable() const;
1216
1217 public: // Signals
1218
1219   /**
1220    * @brief This signal is emitted when touch input is received.
1221    *
1222    * A callback of the following type may be connected:
1223    * @code
1224    *   bool YourCallbackName(Actor actor, const TouchEvent& event);
1225    * @endcode
1226    * The return value of True, indicates that the touch event should be consumed.
1227    * Otherwise the signal will be emitted on the next sensitive parent of the actor.
1228    * @pre The Actor has been initialized.
1229    * @return The signal to connect to.
1230    */
1231   TouchSignalType& TouchedSignal();
1232
1233   /**
1234    * @brief This signal is emitted when hover input is received.
1235    *
1236    * A callback of the following type may be connected:
1237    * @code
1238    *   bool YourCallbackName(Actor actor, const HoverEvent& event);
1239    * @endcode
1240    * The return value of True, indicates that the hover event should be consumed.
1241    * Otherwise the signal will be emitted on the next sensitive parent of the actor.
1242    * @pre The Actor has been initialized.
1243    * @return The signal to connect to.
1244    */
1245   HoverSignalType& HoveredSignal();
1246
1247   /**
1248    * @brief This signal is emitted when mouse wheel event is received.
1249    *
1250    * A callback of the following type may be connected:
1251    * @code
1252    *   bool YourCallbackName(Actor actor, const MouseWheelEvent& event);
1253    * @endcode
1254    * The return value of True, indicates that the mouse wheel event should be consumed.
1255    * Otherwise the signal will be emitted on the next sensitive parent of the actor.
1256    * @pre The Actor has been initialized.
1257    * @return The signal to connect to.
1258    */
1259   MouseWheelEventSignalType& MouseWheelEventSignal();
1260
1261   /**
1262    * @brief This signal is emitted after the actor has been connected to the stage.
1263    *
1264    * When an actor is connected, it will be directly or indirectly parented to the root Actor.
1265    * @note The root Actor is provided automatically by Dali::Stage, and is always considered to be connected.
1266    *
1267    * @note When the parent of a set of actors is connected to the stage, then all of the children
1268    * will received this callback.
1269    *
1270    * For the following actor tree, the callback order will be A, B, D, E, C, and finally F.
1271    *
1272    *       A (parent)
1273    *      / \
1274    *     B   C
1275    *    / \   \
1276    *   D   E   F
1277    *
1278    * @return The signal
1279    */
1280   OnStageSignalType& OnStageSignal();
1281
1282   /**
1283    * @brief This signal is emitted after the actor has been disconnected from the stage.
1284    *
1285    * If an actor is disconnected it either has no parent, or is parented to a disconnected actor.
1286    *
1287    * @note When the parent of a set of actors is disconnected to the stage, then all of the children
1288    * will received this callback, starting with the leaf actors.
1289    *
1290    * For the following actor tree, the callback order will be D, E, B, F, C, and finally A.
1291    *
1292    *       A (parent)
1293    *      / \
1294    *     B   C
1295    *    / \   \
1296    *   D   E   F
1297    *
1298    * @return The signal
1299    */
1300   OffStageSignalType& OffStageSignal();
1301
1302 public: // Dynamics
1303
1304   /**
1305    * @brief Enable dynamics for this actor.
1306    *
1307    * The actor will behave as a rigid/soft body in the simulation
1308    * @pre The actor is not already acting as a DynamicsBody and IsDynamicsRoot() returns false
1309    *
1310    * @param [in] bodyConfig The DynamicsBodyConfig specifying the dynamics properties for this actor in the dynamics world.
1311    * @return The DynamicsBody
1312    */
1313   DynamicsBody EnableDynamics(DynamicsBodyConfig bodyConfig);
1314
1315   /**
1316    * @brief Add a joint constraint to this actor.
1317    *
1318    * @param[in] attachedActor The other actor in the joint
1319    * @param[in] offset        The offset (relative to this actor) of the origin of the joint
1320    * @return                  The new joint
1321    * @pre Both actors are dynamics enabled actors (IE Actor::EnableDynamics()) has been invoked for both actors).
1322    * @post If the two actors are already connected by a joint, The existing joint is returned
1323    *       and offset is ignored.
1324    */
1325   DynamicsJoint AddDynamicsJoint( Actor attachedActor, const Vector3& offset );
1326
1327   /**
1328    * @brief Add a joint constraint to this actor.
1329    *
1330    * @param[in] attachedActor The other actor in the joint
1331    * @param[in] offsetA       The offset (relative to this actor) of the origin of the joint
1332    * @param[in] offsetB       The offset (relative to attachedActor) of the origin of the joint
1333    * @return                  The new joint
1334    * @pre Both actors are dynamics enabled actors (IE Actor::EnableDynamics()) has been invoked for both actors).
1335    * @post If the two actors are already connected by a joint, The existing joint is returned
1336    *       and offset is ignored.
1337    */
1338   DynamicsJoint AddDynamicsJoint( Actor attachedActor, const Vector3& offsetA, const Vector3& offsetB );
1339
1340   /**
1341    * @brief Get the number of DynamicsJoint objects added to this actor.
1342    *
1343    * @return The number of DynamicsJoint objects added to this actor
1344    */
1345   int GetNumberOfJoints() const;
1346
1347   /**
1348    * @brief Get a joint by index.
1349    *
1350    * @param[in] index The index of the joint.
1351    *                  Use GetNumberOfJoints to get the valid range of indices.
1352    * @return The joint.
1353    */
1354   DynamicsJoint GetDynamicsJointByIndex( const int index );
1355
1356   /**
1357    * @brief Get the joint between this actor and attachedActor.
1358    *
1359    * @param[in] attachedActor The other actor in the joint
1360    * @return The joint.
1361    */
1362   DynamicsJoint GetDynamicsJoint( Actor attachedActor );
1363
1364   /**
1365    * @brief Remove a joint from this actor
1366    *
1367    * @param[in] joint The joint to be removed
1368    */
1369   void RemoveDynamicsJoint( DynamicsJoint joint );
1370
1371   /**
1372    * @brief Disable dynamics for this actor.
1373    *
1374    * The actor will be detached from the DynamicsBody/DynamicsJoint associated with it through EnableDynamics
1375    */
1376   void DisableDynamics();
1377
1378   /**
1379    * @brief Get the associated DynamicsBody.
1380    *
1381    * @return A DynamicsBody
1382    */
1383   DynamicsBody GetDynamicsBody();
1384
1385 public: // Not intended for application developers
1386
1387   /**
1388    * @brief This constructor is used by Dali New() methods.
1389    *
1390    * @param [in] actor A pointer to a newly allocated Dali resource
1391    */
1392   explicit DALI_INTERNAL Actor(Internal::Actor* actor);
1393 };
1394
1395 /**
1396  * @brief Helper for discarding an actor handle.
1397  *
1398  * If the handle is empty, this method does nothing.  Otherwise
1399  * actor.Unparent() will be called, followed by actor.Reset().
1400  * @param[in,out] actor A handle to an actor, or an empty handle.
1401  */
1402  DALI_IMPORT_API void UnparentAndReset( Actor& actor );
1403
1404 } // namespace Dali
1405
1406 #endif // __DALI_ACTOR_H__