dali/public-api/actors/actor.h

   1 #ifndef DALI_ACTOR_H
   2 #define DALI_ACTOR_H
   3
   4 /*
   5  * Copyright (c) 2020 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 <string>
  23 #include <cstdint> // uint32_t
  24
  25 // INTERNAL INCLUDES
  26 #include <dali/public-api/actors/actor-enumerations.h>
  27 #include <dali/public-api/actors/draw-mode.h>
  28 #include <dali/public-api/math/radian.h>
  29 #include <dali/public-api/object/handle.h>
  30 #include <dali/public-api/object/property-index-ranges.h>
  31 #include <dali/public-api/signals/dali-signal.h>
  32
  33 #undef SIZE_WIDTH // Defined in later versions of cstdint but is used in this header
  34
  35 namespace Dali
  36 {
  37 /**
  38  * @addtogroup dali_core_actors
  39  * @{
  40  */
  41
  42 namespace Internal DALI_INTERNAL
  43 {
  44 class Actor;
  45 }
  46
  47 class Actor;
  48 class Renderer;
  49 struct Degree;
  50 class Quaternion;
  51 class Layer;
  52 class TouchData;
  53 struct TouchEvent;
  54 struct HoverEvent;
  55 struct WheelEvent;
  56 struct Vector2;
  57 struct Vector3;
  58 struct Vector4;
  59
  60 typedef Rect<float> Padding;      ///< Padding definition @SINCE_1_0.0
  61
  62 /**
  63  * @brief Actor is the primary object with which Dali applications interact.
  64  *
  65  * UI controls can be built by combining multiple actors.
  66  *
  67  * <h3>Multi-Touch Events:</h3>
  68  *
  69  * Touch or hover events are received via signals; see Actor::TouchedSignal() and Actor::HoveredSignal() for more details.
  70  *
  71  * <i>Hit Testing Rules Summary:</i>
  72  *
  73  * - An actor is only hittable if the actor's touch or hover signal has a connection.
  74  * - An actor is only hittable when it is between the camera's near and far planes.
  75  * - If an actor is made insensitive, then the actor and its children are not hittable; see Actor::Property::SENSITIVE.
  76  * - If an actor's visibility flag is unset, then none of its children are hittable either; see Actor::Property::VISIBLE.
  77  * - To be hittable, an actor must have a non-zero size.
  78  * - If an actor's world color is fully transparent, then it is not hittable; see GetCurrentWorldColor().
  79  *
  80  * <i>Hit Test Algorithm:</i>
  81  *
  82  * - Stage
  83  *   - Gets the first down and the last up touch events to the screen, regardless of actor touch event consumption.
  84  *   - Stage's root layer can be used to catch unconsumed touch events.
  85  *
  86  * - RenderTasks
  87  *   - Hit testing is dependent on the camera used, which is specific to each RenderTask.
  88  *
  89  * - Layers
  90  *   - For each RenderTask, hit testing starts from the top-most layer and we go through all the
  91  *     layers until we have a hit or there are none left.
  92  *   - Before we perform a hit test within a layer, we check if all the layer's parents are visible
  93  *     and sensitive.
  94  *   - If they are not, we skip hit testing the actors in that layer altogether.
  95  *   - If a layer is set to consume all touch, then we do not check any layers behind this layer.
  96  *
  97  * - Actors
  98  *   - The final part of hit testing is performed by walking through the actor tree within a layer.
  99  *   - The following pseudocode shows the algorithm used:
 100  *     @code
 101  *     HIT-TEST-WITHIN-LAYER( ACTOR )
 102  *     {
 103  *       // Only hit-test the actor and its children if it is sensitive and visible
 104  *       IF ( ACTOR-IS-SENSITIVE &&
 105  *            ACTOR-IS-VISIBLE &&
 106  *            ACTOR-IS-ON-SCENE )
 107  *       {
 108  *         // Depth-first traversal within current layer, visiting parent first
 109  *
 110  *         // Check whether current actor should be hit-tested.
 111  *         IF ( ( TOUCH-SIGNAL-NOT-EMPTY || HOVER-SIGNAL-NOT-EMPTY ) &&
 112  *              ACTOR-HAS-NON-ZERO-SIZE &&
 113  *              ACTOR-WORLD-COLOR-IS-NOT-TRANSPARENT )
 114  *         {
 115  *           // Hit-test current actor
 116  *           IF ( ACTOR-HIT )
 117  *           {
 118  *             IF ( ACTOR-IS-OVERLAY || ( DISTANCE-TO-ACTOR < DISTANCE-TO-LAST-HIT-ACTOR ) )
 119  *             {
 120  *               // The current actor is the closest actor that was underneath the touch.
 121  *               LAST-HIT-ACTOR = CURRENT-ACTOR
 122  *             }
 123  *           }
 124  *         }
 125  *
 126  *         // Keep checking children, in case we hit something closer.
 127  *         FOR-EACH CHILD (in order)
 128  *         {
 129  *           IF ( CHILD-IS-NOT-A-LAYER )
 130  *           {
 131  *             // Continue traversal for this child's sub-tree
 132  *             HIT-TEST-WITHIN-LAYER ( CHILD )
 133  *           }
 134  *           // else we skip hit-testing the child's sub-tree altogether.
 135  *         }
 136  *       }
 137  *     }
 138  *     @endcode
 139  *   - Overlays always take priority (i.e. they're considered closer) regardless of distance.
 140  *     The overlay children take priority over their parents, and overlay siblings take priority
 141  *     over their previous siblings (i.e. reverse of rendering order):
 142  *     @code
 143  *           1
 144  *          / \
 145  *         /   \
 146  *        2     5
 147  *       / \     \
 148  *      /   \     \
 149  *     3     4     6
 150  *
 151  *     Hit Priority of above Actor tree (all overlays): 1 - Lowest. 6 - Highest.
 152  *     @endcode
 153  *     For more information, see Property::DRAW_MODE.
 154  *
 155  * <i>Touch or hover Event Delivery:</i>
 156  *
 157  * - Delivery
 158  *   - The hit actor's touch or hover signal is emitted first; if it is not consumed by any of the listeners,
 159  *     the parent's touch or hover signal is emitted, and so on.
 160  *   - The following pseudocode shows the delivery mechanism:
 161  *     @code
 162  *     EMIT-TOUCH-SIGNAL( ACTOR )
 163  *     {
 164  *       IF ( TOUCH-SIGNAL-NOT-EMPTY )
 165  *       {
 166  *         // Only do the emission if touch signal of actor has connections.
 167  *         CONSUMED = TOUCHED-SIGNAL( TOUCH-EVENT )
 168  *       }
 169  *
 170  *       IF ( NOT-CONSUMED )
 171  *       {
 172  *         // If event is not consumed then deliver it to the parent unless we reach the root actor
 173  *         IF ( ACTOR-PARENT )
 174  *         {
 175  *           EMIT-TOUCH-SIGNAL( ACTOR-PARENT )
 176  *         }
 177  *       }
 178  *     }
 179  *
 180  *     EMIT-HOVER-SIGNAL( ACTOR )
 181  *     {
 182  *       IF ( HOVER-SIGNAL-NOT-EMPTY )
 183  *       {
 184  *         // Only do the emission if hover signal of actor has connections.
 185  *         CONSUMED = HOVERED-SIGNAL( HOVER-EVENT )
 186  *       }
 187  *
 188  *       IF ( NOT-CONSUMED )
 189  *       {
 190  *         // If event is not consumed then deliver it to the parent unless we reach the root actor.
 191  *         IF ( ACTOR-PARENT )
 192  *         {
 193  *           EMIT-HOVER-SIGNAL( ACTOR-PARENT )
 194  *         }
 195  *       }
 196  *     }
 197  *     @endcode
 198  *   - If there are several touch points, then the delivery is only to the first touch point's hit
 199  *     actor (and its parents). There will be NO touch or hover signal delivery for the hit actors of the
 200  *     other touch points.
 201  *   - The local coordinates are from the top-left (0.0f, 0.0f, 0.5f) of the hit actor.
 202  *
 203  * - Leave State
 204  *   - A "Leave" state is set when the first point exits the bounds of the previous first point's
 205  *     hit actor (primary hit actor).
 206  *   - When this happens, the last primary hit actor's touch or hover signal is emitted with a "Leave" state
 207  *     (only if it requires leave signals); see SetLeaveRequired().
 208  *
 209  * - Interrupted State
 210  *   - If a system event occurs which interrupts the touch or hover processing, then the last primary hit
 211  *     actor's touch or hover signals are emitted with an "Interrupted" state.
 212  *   - If the last primary hit actor, or one of its parents, is no longer touchable or hoverable, then its
 213  *     touch or hover signals are also emitted with an "Interrupted" state.
 214  *   - If the consumed actor on touch-down is not the same as the consumed actor on touch-up, then
 215  *     touch signals are also emitted from the touch-down actor with an "Interrupted" state.
 216  *   - If the consumed actor on hover-start is not the same as the consumed actor on hover-finished, then
 217  *     hover signals are also emitted from the hover-started actor with an "Interrupted" state.
 218  *
 219  * @nosubgrouping
 220  *
 221  * Signals
 222  * | %Signal Name      | Method                       |
 223  * |-------------------|------------------------------|
 224  * | touched           | @ref TouchedSignal()         |
 225  * | hovered           | @ref HoveredSignal()         |
 226  * | wheelEvent        | @ref WheelEventSignal()      |
 227  * | onScene           | @ref OnSceneSignal()         |
 228  * | offScene          | @ref OffSceneSignal()        |
 229  * | onRelayout        | @ref OnRelayoutSignal()      |
 230  *
 231  * Actions
 232  * | %Action Name      | %Actor method called         |
 233  * |-------------------|------------------------------|
 234  * | show              | %SetVisible( true )          |
 235  * | hide              | %SetVisible( false )         |
 236  * @SINCE_1_0.0
 237  */
 238
 239 class DALI_CORE_API Actor : public Handle
 240 {
 241 public:
 242
 243   /**
 244    * @brief Enumeration for the instance of properties belonging to the Actor class.
 245    * @SINCE_1_0.0
 246    */
 247   struct Property
 248   {
 249     /**
 250      * @brief Enumeration for instance of properties belonging to the Actor class.
 251      * @SINCE_1_0.0
 252      */
 253     enum
 254     {
 255       /**
 256        * @brief The origin of an actor, within its parent's area.
 257        * @details Name "parentOrigin", type Property::VECTOR3, constraint-input
 258        * @SINCE_1_0.0
 259        */
 260       PARENT_ORIGIN = DEFAULT_ACTOR_PROPERTY_START_INDEX,
 261
 262       /**
 263        * @brief The x origin of an actor, within its parent's area.
 264        * @details Name "parentOriginX", type Property::FLOAT, constraint-input
 265        * @SINCE_1_0.0
 266        */
 267       PARENT_ORIGIN_X,
 268
 269       /**
 270        * @brief The y origin of an actor, within its parent's area.
 271        * @details Name "parentOriginY", type Property::FLOAT, constraint-input
 272        * @SINCE_1_0.0
 273        */
 274       PARENT_ORIGIN_Y,
 275
 276       /**
 277        * @brief The z origin of an actor, within its parent's area.
 278        * @details Name "parentOriginZ", type Property::FLOAT, constraint-input
 279        * @SINCE_1_0.0
 280        */
 281       PARENT_ORIGIN_Z,
 282
 283       /**
 284        * @brief The anchor-point of an actor.
 285        * @details Name "anchorPoint", type Property::VECTOR3, constraint-input
 286        * @SINCE_1_0.0
 287        */
 288       ANCHOR_POINT,
 289
 290       /**
 291        * @brief The x anchor-point of an actor.
 292        * @details Name "anchorPointX", type Property::FLOAT, constraint-input
 293        * @SINCE_1_0.0
 294        */
 295       ANCHOR_POINT_X,
 296
 297       /**
 298        * @brief The y anchor-point of an actor.
 299        * @details Name "anchorPointY", type Property::FLOAT, constraint-input
 300        * @SINCE_1_0.0
 301        */
 302       ANCHOR_POINT_Y,
 303
 304       /**
 305        * @brief The z anchor-point of an actor.
 306        * @details Name "anchorPointZ", type Property::FLOAT, constraint-input
 307        * @SINCE_1_0.0
 308        */
 309       ANCHOR_POINT_Z,
 310
 311       /**
 312        * @brief The size of an actor.
 313        * @details Name "size", type Property::VECTOR3 or Property::VECTOR2, animatable / constraint-input
 314        * @note Only Property::VECTOR3 can be animated or used as constraint-input
 315        * @SINCE_1_0.0
 316        */
 317       SIZE,
 318
 319       /**
 320        * @brief The width of an actor.
 321        * @details Name "sizeWidth", type Property::FLOAT, animatable / constraint-input
 322        * @SINCE_1_0.0
 323        */
 324       SIZE_WIDTH,
 325
 326       /**
 327        * @brief The height of an actor.
 328        * @details Name "sizeHeight", type Property::FLOAT, animatable / constraint-input
 329        * @SINCE_1_0.0
 330        */
 331       SIZE_HEIGHT,
 332
 333       /**
 334        * @brief The depth of an actor.
 335        * @details Name "sizeDepth", type Property::FLOAT, animatable / constraint-input
 336        * @SINCE_1_0.0
 337        */
 338       SIZE_DEPTH,
 339
 340       /**
 341        * @brief The position of an actor.
 342        * @details Name "position", type Property::VECTOR3 or Property::VECTOR2, animatable / constraint-input
 343        * @note Only Property::VECTOR3 can be animated or used as constraint-input
 344        * @SINCE_1_0.0
 345        */
 346       POSITION,
 347
 348       /**
 349        * @brief The x position of an actor.
 350        * @details Name "positionX", type Property::FLOAT, animatable / constraint-input
 351        * @SINCE_1_0.0
 352        */
 353       POSITION_X,
 354
 355       /**
 356        * @brief The y position of an actor.
 357        * @details Name "positionY", type Property::FLOAT, animatable / constraint-input
 358        * @SINCE_1_0.0
 359        */
 360       POSITION_Y,
 361
 362       /**
 363        * @brief The z position of an actor.
 364        * @details Name "positionZ", type Property::FLOAT, animatable / constraint-input
 365        * @SINCE_1_0.0
 366        */
 367       POSITION_Z,
 368
 369       /**
 370        * @brief The world position of an actor.
 371        * @details Name "worldPosition", type Property::VECTOR3, read-only / constraint-input
 372        * @SINCE_1_0.0
 373        */
 374       WORLD_POSITION,
 375
 376       /**
 377        * @brief The x world position of an actor.
 378        * @details Name "worldPositionX", type Property::FLOAT, read-only / constraint-input
 379        * @SINCE_1_0.0
 380        */
 381       WORLD_POSITION_X,
 382
 383       /**
 384        * @brief The y world position of an actor.
 385        * @details Name "worldPositionY", type Property::FLOAT, read-only / constraint-input
 386        * @SINCE_1_0.0
 387        */
 388       WORLD_POSITION_Y,
 389
 390       /**
 391        * @brief The z world position of an actor.
 392        * @details Name "worldPositionZ", type Property::FLOAT, read-only / constraint-input
 393        * @SINCE_1_0.0
 394        */
 395       WORLD_POSITION_Z,
 396
 397       /**
 398        * @brief The orientation of an actor.
 399        * @details Name "orientation", type Property::ROTATION, animatable / constraint-input
 400        * @SINCE_1_0.0
 401        */
 402       ORIENTATION,
 403
 404       /**
 405        * @brief The world orientation of an actor.
 406        * @details Name "worldOrientation", type Property::ROTATION, read-only / constraint-input
 407        * @SINCE_1_0.0
 408        */
 409       WORLD_ORIENTATION,
 410
 411       /**
 412        * @brief The scale factor applied to an actor.
 413        * @details Name "scale", type Property::VECTOR3 or Property::FLOAT, animatable / constraint-input
 414        * @note Only Property::VECTOR3 can be animated or used as constraint-input
 415        * @SINCE_1_0.0
 416        */
 417       SCALE,
 418
 419       /**
 420        * @brief The x scale factor applied to an actor.
 421        * @details Name "scaleX", type Property::FLOAT, animatable / constraint-input
 422        * @SINCE_1_0.0
 423        */
 424       SCALE_X,
 425
 426       /**
 427        * @brief The y scale factor applied to an actor.
 428        * @details Name "scaleY", type Property::FLOAT, animatable / constraint-input
 429        * @SINCE_1_0.0
 430        */
 431       SCALE_Y,
 432
 433       /**
 434        * @brief The x scale factor applied to an actor.
 435        * @details Name "scaleZ", type Property::FLOAT, animatable / constraint-input
 436        * @SINCE_1_0.0
 437        */
 438       SCALE_Z,
 439
 440       /**
 441        * @brief The world scale factor applied to an actor.
 442        * @details Name "worldScale", type Property::VECTOR3, read-only / constraint-input
 443        * @SINCE_1_0.0
 444        */
 445       WORLD_SCALE,
 446
 447       /**
 448        * @brief The visibility flag of an actor.
 449        * @details Name "visible", type Property::BOOL, animatable / constraint-input
 450        * @SINCE_1_0.0
 451        */
 452       VISIBLE,
 453
 454       /**
 455        * @brief The color of an actor.
 456        * @details Name "color", type Property::VECTOR4 or Property::VECTOR3, animatable / constraint-input
 457        * @note The alpha value will be 1.0f if a Vector3 type value is set.
 458        * @SINCE_1_0.0
 459        */
 460       COLOR,
 461
 462       /**
 463        * @brief The red component of an actor's color.
 464        * @details Name "colorRed", type Property::FLOAT, animatable / constraint-input
 465        * @SINCE_1_0.0
 466        */
 467       COLOR_RED,
 468
 469       /**
 470        * @brief The green component of an actor's color.
 471        * @details Name "colorGreen", type Property::FLOAT, animatable / constraint-input
 472        * @SINCE_1_0.0
 473        */
 474       COLOR_GREEN,
 475
 476       /**
 477        * @brief The blue component of an actor's color.
 478        * @details Name "colorBlue", type Property::FLOAT, animatable / constraint-input
 479        * @SINCE_1_0.0
 480        */
 481       COLOR_BLUE,
 482
 483       /**
 484        * @brief The alpha component of an actor's color.
 485        * @details Name "colorAlpha", type Property::FLOAT, animatable / constraint-input
 486        * @SINCE_1_0.0
 487        */
 488       COLOR_ALPHA,
 489
 490       /**
 491        * @brief The world color of an actor.
 492        * @details Name "worldColor", type Property::VECTOR4, read-only / constraint-input
 493        * @SINCE_1_0.0
 494        */
 495       WORLD_COLOR,
 496
 497       /**
 498        * @brief The world matrix of an actor.
 499        * @details Name "worldMatrix", type Property::MATRIX, read-only / constraint-input
 500        * @SINCE_1_0.0
 501        */
 502       WORLD_MATRIX,
 503
 504       /**
 505        * @brief The name of an actor.
 506        * @details Name "name", type Property::STRING
 507        * @SINCE_1_0.0
 508        */
 509       NAME,
 510
 511       /**
 512        * @brief The flag whether an actor should emit touch or hover signals.
 513        * @details Name "sensitive", type Property::BOOLEAN
 514        * @SINCE_1_0.0
 515        */
 516       SENSITIVE,
 517
 518       /**
 519        * @brief The flag whether an actor should receive a notification when touch or hover motion events leave.
 520        * @details Name "leaveRequired", type Property::BOOLEAN
 521        * @SINCE_1_0.0
 522        */
 523       LEAVE_REQUIRED,
 524
 525       /**
 526        * @brief The flag whether a child actor inherits it's parent's orientation.
 527        * @details Name "inheritOrientation", type Property::BOOLEAN
 528        * @SINCE_1_0.0
 529        */
 530       INHERIT_ORIENTATION,
 531
 532       /**
 533        * @brief The flag whether a child actor inherits it's parent's scale.
 534        * @details Name "inheritScale", type Property::BOOLEAN
 535        * @SINCE_1_0.0
 536        */
 537       INHERIT_SCALE,
 538
 539       /**
 540        * @brief The color mode of an actor.
 541        * @details Name "colorMode", type ColorMode (Property::INTEGER) or Property::STRING.
 542        * @SINCE_1_0.0
 543        */
 544       COLOR_MODE,
 545
 546       /**
 547        * @brief The draw mode of an actor.
 548        * @details Name "drawMode", type DrawMode::Type (Property::INTEGER) or Property::STRING.
 549        * @SINCE_1_0.0
 550        */
 551       DRAW_MODE,
 552
 553       /**
 554        * @brief The size mode factor of an actor.
 555        * @details Name "sizeModeFactor", type Property::VECTOR3.
 556        * @SINCE_1_0.0
 557        * @see Actor::SetSizeModeFactor()
 558        */
 559       SIZE_MODE_FACTOR,
 560
 561       /**
 562        * @brief The resize policy for the width of an actor.
 563        * @details Name "widthResizePolicy", type ResizePolicy::Type (Property::INTEGER) or Property::STRING.
 564        * @SINCE_1_0.0
 565        * @see Actor::SetResizePolicy()
 566        */
 567       WIDTH_RESIZE_POLICY,
 568
 569       /**
 570        * @brief The resize policy for the height of an actor.
 571        * @details Name "heightResizePolicy", type ResizePolicy::Type (Property::INTEGER) or Property::STRING.
 572        * @SINCE_1_0.0
 573        * @see Actor::SetResizePolicy()
 574        */
 575       HEIGHT_RESIZE_POLICY,
 576
 577       /**
 578        * @brief The size scale policy of an actor.
 579        * @details Name "sizeScalePolicy", type SizeScalePolicy::Type (Property::INTEGER) or Property::STRING.
 580        * @SINCE_1_0.0
 581        */
 582       SIZE_SCALE_POLICY,
 583
 584       /**
 585        * @brief The flag to determine the width dependent on the height.
 586        * @details Name "widthForHeight", type Property::BOOLEAN.
 587        * @SINCE_1_0.0
 588        * @see Actor::SetResizePolicy()
 589        */
 590       WIDTH_FOR_HEIGHT,
 591
 592       /**
 593        * @brief The flag to determine the height dependent on the width.
 594        * @details Name "heightForWidth", type Property::BOOLEAN.
 595        * @SINCE_1_0.0
 596        * @see Actor::SetResizePolicy()
 597        */
 598       HEIGHT_FOR_WIDTH,
 599
 600       /**
 601        * @brief The padding of an actor for use in layout.
 602        * @details Name "padding", type Property::VECTOR4.
 603        * @SINCE_1_0.0
 604        */
 605       PADDING,
 606
 607       /**
 608        * @brief The minimum size an actor can be assigned in size negotiation.
 609        * @details Name "minimumSize", type Property::VECTOR2.
 610        * @SINCE_1_0.0
 611        */
 612       MINIMUM_SIZE,
 613
 614       /**
 615        * @brief The maximum size an actor can be assigned in size negotiation.
 616        * @details Name "maximumSize", type Property::VECTOR2.
 617        * @SINCE_1_0.0
 618        */
 619       MAXIMUM_SIZE,
 620
 621       /**
 622        * @brief The flag whether a child actor inherits it's parent's position.
 623        * @details Name "inheritPosition", type Property::BOOLEAN.
 624        * @SINCE_1_1.24
 625        */
 626       INHERIT_POSITION,
 627
 628       /**
 629        * @brief The clipping mode of an actor.
 630        * @details Name "clippingMode", type ClippingMode::Type (Property::INTEGER) or Property::STRING.
 631        * @SINCE_1_2_5
 632        * @see ClippingMode::Type for supported values.
 633        */
 634       CLIPPING_MODE,
 635
 636       /**
 637        * @brief The direction of the layout.
 638        * @details Name "layoutDirection", type LayoutDirection::Type (Property::INTEGER) or Property::STRING.
 639        * @SINCE_1_2.60
 640        * @see LayoutDirection::Type for supported values.
 641        */
 642       LAYOUT_DIRECTION,
 643
 644       /**
 645        * @brief Determines whether child actors inherit the layout direction from a parent.
 646        * @details Name "layoutDirectionInheritance", type Property::BOOLEAN.
 647        * @SINCE_1_2.60
 648        */
 649       INHERIT_LAYOUT_DIRECTION,
 650
 651       /**
 652        * @brief The opacity of the actor.
 653        * @details Name "opacity", type Property::FLOAT.
 654        * @SINCE_1_9.17
 655        */
 656       OPACITY,
 657
 658       /**
 659        * @brief Returns the screen position of the Actor
 660        * @details Name "screenPosition", type Property::VECTOR2. Read-only
 661        * @note This assumes default camera and default render-task and the Z position is ZERO.
 662        * @note The last known frame is used for the calculation. May not match a position value just set.
 663        * @SINCE_1_9.17
 664        */
 665       SCREEN_POSITION,
 666
 667       /**
 668        * @brief Determines whether the anchor point should be used to determine the position of the actor.
 669        * @details Name "positionUsesAnchorPoint", type Property::BOOLEAN.
 670        * @note This is true by default.
 671        * @note If false, then the top-left of the actor is used for the position.
 672        * @note Setting this to false will allow scaling or rotation around the anchor-point without affecting the actor's position.
 673        * @SINCE_1_9.17
 674        */
 675       POSITION_USES_ANCHOR_POINT,
 676
 677       /**
 678        * @brief Returns whether the actor is culled or not.
 679        * @details Name "culled", type Property::BOOLEAN. Read-only
 680        * @note True means that the actor is out of the view frustum.
 681        * @SINCE_1_9.17
 682        */
 683       CULLED,
 684
 685       /**
 686        * @brief The unique ID of the actor.
 687        * @details Name "id", type Property::INTEGER. Read-only
 688        * @SINCE_1_9.17
 689        */
 690       ID,
 691
 692       /**
 693        * @brief The current depth in the hierarchy of the actor.
 694        * @details Name "hierarchyDepth", type Property::INTEGER. Read-only
 695        * @note The value is -1 if actor is not in the hierarchy.
 696        * @SINCE_1_9.17
 697        */
 698       HIERARCHY_DEPTH,
 699
 700       /**
 701        * @brief The flag whether an actor is the root actor, which is owned by the Scene.
 702        * @details Name "isRoot", type Property::BOOLEAN. Read-only
 703        * @SINCE_1_9.17
 704        */
 705       IS_ROOT,
 706
 707       /**
 708        * @brief The flag whether the actor is of class Dali::Layer.
 709        * @details Name "isLayer", type Property::BOOLEAN. Read-only
 710        * @SINCE_1_9.17
 711        */
 712       IS_LAYER,
 713
 714       /**
 715        * @brief The flag whether the actor is connected to the Scene.
 716        * When an actor is connected, it will be directly or indirectly parented to the root Actor.
 717        * @details Name "connectedToScene", type Property::BOOLEAN. Read-only
 718        * @note The root Actor is provided automatically by the Scene, and is always considered to be connected.
 719        * @SINCE_1_9.17
 720        */
 721       CONNECTED_TO_SCENE,
 722
 723       /**
 724        * @brief The flag whether the actor should be focusable by keyboard navigation.
 725        * @details Name "keyboardFocusable", type Property::BOOLEAN.
 726        * @SINCE_1_9.17
 727        */
 728       KEYBOARD_FOCUSABLE,
 729     };
 730   };
 731
 732   // Typedefs
 733
 734   typedef Signal< bool (Actor, const TouchEvent&) > TouchSignalType;        ///< @DEPRECATED_1_1.37 @brief Touch signal type @SINCE_1_0.0
 735   typedef Signal< bool (Actor, const TouchData&) >  TouchDataSignalType;    ///< Touch signal type @SINCE_1_1.37
 736   typedef Signal< bool (Actor, const HoverEvent&) > HoverSignalType;        ///< Hover signal type @SINCE_1_0.0
 737   typedef Signal< bool (Actor, const WheelEvent&) > WheelEventSignalType;   ///< Wheel signal type @SINCE_1_0.0
 738   typedef Signal< void (Actor) > OnSceneSignalType;                         ///< Scene connection signal type @SINCE_1_9.24
 739   typedef Signal< void (Actor) > OffSceneSignalType;                        ///< Scene disconnection signal type @SINCE_1_9.24
 740   typedef Signal< void (Actor) > OnRelayoutSignalType;                      ///< Called when the actor is relaid out @SINCE_1_0.0
 741   typedef Signal< void ( Actor, LayoutDirection::Type ) > LayoutDirectionChangedSignalType; ///< Layout direction changes signal type. @SINCE_1_2.60
 742
 743   // Creation
 744
 745   /**
 746    * @brief Creates an uninitialized Actor; this can be initialized with Actor::New().
 747    *
 748    * Calling member functions with an uninitialized Actor handle is not allowed.
 749    * @SINCE_1_0.0
 750    */
 751   Actor();
 752
 753   /**
 754    * @brief Creates an initialized Actor.
 755    *
 756    * @SINCE_1_0.0
 757    * @return A handle to a newly allocated Dali resource
 758    */
 759   static Actor New();
 760
 761   /**
 762    * @brief Downcasts a handle to Actor handle.
 763    *
 764    * If handle points to an Actor object, the downcast produces valid handle.
 765    * If not, the returned handle is left uninitialized.
 766    *
 767    * @SINCE_1_0.0
 768    * @param[in] handle to An object
 769    * @return handle to a Actor object or an uninitialized handle
 770    */
 771   static Actor DownCast( BaseHandle handle );
 772
 773   /**
 774    * @brief Dali::Actor is intended as a base class.
 775    *
 776    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 777    * @SINCE_1_0.0
 778    */
 779   ~Actor();
 780
 781   /**
 782    * @brief Copy constructor.
 783    *
 784    * @SINCE_1_0.0
 785    * @param[in] copy The actor to copy
 786    */
 787   Actor(const Actor& copy);
 788
 789   /**
 790    * @brief Assignment operator
 791    *
 792    * @SINCE_1_0.0
 793    * @param[in] rhs The actor to copy
 794    * @return A reference to this
 795    */
 796   Actor& operator=(const Actor& rhs);
 797
 798   /**
 799    * @brief Move constructor.
 800    *
 801    * @SINCE_1_9.22
 802    * @param[in] rhs A reference to the actor to move
 803    */
 804   Actor( Actor&& rhs );
 805
 806   /**
 807    * @brief Move assignment operator.
 808    *
 809    * @SINCE_1_9.22
 810    * @param[in] rhs A reference to the actor to move
 811    * @return A reference to this
 812    */
 813   Actor& operator=( Actor&& rhs );
 814
 815   // Containment
 816
 817   /**
 818    * @brief Gets the layer in which the actor is present.
 819    *
 820    * @SINCE_1_0.0
 821    * @return The layer, which will be uninitialized if the actor is off-stage
 822    * @pre The Actor has been initialized.
 823    */
 824   Layer GetLayer();
 825
 826   /**
 827    * @brief Adds a child Actor to this Actor.
 828    *
 829    * @SINCE_1_0.0
 830    * @param[in] child The child
 831    * @pre This Actor (the parent) has been initialized.
 832    * @pre The child actor has been initialized.
 833    * @pre The child actor is not the same as the parent actor.
 834    * @pre The actor is not the Root actor.
 835    * @post The child will be referenced by its parent. This means that the child will be kept alive,
 836    * even if the handle passed into this method is reset or destroyed.
 837    * @note If the child already has a parent, it will be removed from old parent
 838    * and reparented to this actor. This may change child's position, color,
 839    * scale etc as it now inherits them from this actor.
 840    */
 841   void Add(Actor child);
 842
 843   /**
 844    * @brief Removes a child Actor from this Actor.
 845    *
 846    * If the actor was not a child of this actor, this is a no-op.
 847    * @SINCE_1_0.0
 848    * @param[in] child The child
 849    * @pre This Actor (the parent) has been initialized.
 850    * @pre The child actor is not the same as the parent actor.
 851    */
 852   void Remove(Actor child);
 853
 854   /**
 855    * @brief Removes an actor from its parent.
 856    *
 857    * If the actor has no parent, this method does nothing.
 858    * @SINCE_1_0.0
 859    * @pre The (child) actor has been initialized.
 860    */
 861   void Unparent();
 862
 863   /**
 864    * @brief Retrieves the number of children held by the actor.
 865    *
 866    * @SINCE_1_0.0
 867    * @return The number of children
 868    * @pre The Actor has been initialized.
 869    */
 870   uint32_t GetChildCount() const;
 871
 872   /**
 873    * @brief Retrieve and child actor by index.
 874    *
 875    * @SINCE_1_0.0
 876    * @param[in] index The index of the child to retrieve
 877    * @return The actor for the given index or empty handle if children not initialized
 878    * @pre The Actor has been initialized.
 879    */
 880   Actor GetChildAt( uint32_t index ) const;
 881
 882   /**
 883    * @brief Search through this actor's hierarchy for an actor with the given name.
 884    *
 885    * The actor itself is also considered in the search.
 886    * @SINCE_1_0.0
 887    * @param[in] actorName The name of the actor to find
 888    * @return A handle to the actor if found, or an empty handle if not
 889    * @pre The Actor has been initialized.
 890    */
 891   Actor FindChildByName(const std::string& actorName);
 892
 893   /**
 894    * @brief Search through this actor's hierarchy for an actor with the given unique ID.
 895    *
 896    * The actor itself is also considered in the search.
 897    * @SINCE_1_0.0
 898    * @param[in] id The ID of the actor to find
 899    * @return A handle to the actor if found, or an empty handle if not
 900    * @pre The Actor has been initialized.
 901    */
 902   Actor FindChildById( const uint32_t id );
 903
 904   /**
 905    * @brief Retrieves the actor's parent.
 906    *
 907    * @SINCE_1_0.0
 908    * @return A handle to the actor's parent. If the actor has no parent, this handle will be invalid
 909    * @pre The actor has been initialized.
 910    */
 911   Actor GetParent() const;
 912
 913   // Positioning
 914
 915   /**
 916    * @brief Retrieves the actor's size.
 917    *
 918    * @SINCE_1_0.0
 919    * @return The actor's target size
 920    * @pre The actor has been initialized.
 921    * @note This return is the value that was set using SetSize or the target size of an animation.
 922    *       It may not match the current value in some cases, i.e. when the animation is progressing or the maximum or minimum size is set.
 923    */
 924   Vector3 GetTargetSize() const;
 925
 926   /**
 927    * @brief Returns the natural size of the actor.
 928    *
 929    * Deriving classes stipulate the natural size and by default an actor has a ZERO natural size.
 930    *
 931    * @SINCE_1_0.0
 932    * @return The actor's natural size
 933    */
 934   Vector3 GetNaturalSize() const;
 935
 936   /**
 937    * @brief Translates an actor relative to its existing position.
 938    *
 939    * @SINCE_1_0.0
 940    * @param[in] distance The actor will move by this distance
 941    * @pre The actor has been initialized.
 942    */
 943   void TranslateBy(const Vector3& distance);
 944
 945   /**
 946    * @brief Applies a relative rotation to an actor.
 947    *
 948    * @SINCE_1_0.0
 949    * @param[in] angle The angle to the rotation to combine with the existing orientation
 950    * @param[in] axis The axis of the rotation to combine with the existing orientation
 951    * @pre The actor has been initialized.
 952    */
 953   void RotateBy( const Degree& angle, const Vector3& axis )
 954   {
 955     RotateBy( Radian( angle ), axis );
 956   }
 957
 958   /**
 959    * @brief Applies a relative rotation to an actor.
 960    *
 961    * @SINCE_1_0.0
 962    * @param[in] angle The angle to the rotation to combine with the existing orientation
 963    * @param[in] axis The axis of the rotation to combine with the existing orientation
 964    * @pre The actor has been initialized.
 965    */
 966   void RotateBy(const Radian& angle, const Vector3& axis);
 967
 968   /**
 969    * @brief Applies a relative rotation to an actor.
 970    *
 971    * @SINCE_1_0.0
 972    * @param[in] relativeRotation The rotation to combine with the existing orientation
 973    * @pre The actor has been initialized.
 974    */
 975   void RotateBy(const Quaternion& relativeRotation);
 976
 977   /**
 978    * @brief Applies a relative scale to an actor.
 979    *
 980    * @SINCE_1_0.0
 981    * @param[in] relativeScale The scale to combine with the actor's existing scale
 982    * @pre The actor has been initialized.
 983    */
 984   void ScaleBy(const Vector3& relativeScale);
 985
 986   // Input Handling
 987
 988   /**
 989    * @brief Converts screen coordinates into the actor's coordinate system using the default camera.
 990    *
 991    * @SINCE_1_0.0
 992    * @param[out] localX On return, the X-coordinate relative to the actor
 993    * @param[out] localY On return, the Y-coordinate relative to the actor
 994    * @param[in] screenX The screen X-coordinate
 995    * @param[in] screenY The screen Y-coordinate
 996    * @return True if the conversion succeeded
 997    * @pre The Actor has been initialized.
 998    * @note The actor coordinates are relative to the top-left (0.0, 0.0, 0.5)
 999    */
1000   bool ScreenToLocal(float& localX, float& localY, float screenX, float screenY) const;
1001
1002   /**
1003    * @brief Raise actor above the next sibling actor.
1004    *
1005    * @SINCE_1_2.60
1006    * @pre The Actor has been initialized.
1007    * @pre The Actor has been parented.
1008    */
1009   void Raise();
1010
1011   /**
1012    * @brief Lower the actor below the previous sibling actor.
1013    *
1014    * @SINCE_1_2.60
1015    * @pre The Actor has been initialized.
1016    * @pre The Actor has been parented.
1017    */
1018   void Lower();
1019
1020   /**
1021    * @brief Raise actor above all other sibling actors.
1022    *
1023    * @SINCE_1_2.60
1024    * @pre The Actor has been initialized.
1025    * @pre The Actor has been parented.
1026    */
1027   void RaiseToTop();
1028
1029   /**
1030    * @brief Lower actor to the bottom of all other sibling actors.
1031    *
1032    * @SINCE_1_2.60
1033    * @pre The Actor has been initialized.
1034    * @pre The Actor has been parented.
1035    */
1036   void LowerToBottom();
1037
1038   /**
1039    * @brief Raises the actor above the target actor.
1040    *
1041    * @SINCE_1_2.60
1042    * @param[in] target The target actor
1043    * @pre The Actor has been initialized.
1044    * @pre The Actor has been parented.
1045    * @pre The target actor is a sibling.
1046    */
1047   void RaiseAbove( Actor target );
1048
1049   /**
1050    * @brief Lower the actor to below the target actor.
1051    *
1052    * @SINCE_1_2.60
1053    * @param[in] target The target actor
1054    * @pre The Actor has been initialized.
1055    * @pre The Actor has been parented.
1056    * @pre The target actor is a sibling.
1057    */
1058   void LowerBelow( Actor target );
1059
1060   // SIZE NEGOTIATION
1061
1062   /**
1063    * @brief Sets the resize policy to be used for the given dimension(s).
1064    *
1065    * @SINCE_1_0.0
1066    * @param[in] policy The resize policy to use
1067    * @param[in] dimension The dimension(s) to set policy for. Can be a bitfield of multiple dimensions
1068    */
1069   void SetResizePolicy( ResizePolicy::Type policy, Dimension::Type dimension );
1070
1071   /**
1072    * @brief Returns the resize policy used for a single dimension.
1073    *
1074    * @SINCE_1_0.0
1075    * @param[in] dimension The dimension to get policy for
1076    * @return Return the dimension resize policy. If more than one dimension is requested, just return the first one found
1077    */
1078   ResizePolicy::Type GetResizePolicy( Dimension::Type dimension ) const;
1079
1080   /**
1081    * @brief Calculates the height of the actor given a width.
1082    *
1083    * The natural size is used for default calculation.
1084    * size 0 is treated as aspect ratio 1:1.
1085    *
1086    * @SINCE_1_0.0
1087    * @param[in] width Width to use
1088    * @return Return the height based on the width
1089    */
1090   float GetHeightForWidth( float width );
1091
1092   /**
1093    * @brief Calculates the width of the actor given a height.
1094    *
1095    * The natural size is used for default calculation.
1096    * size 0 is treated as aspect ratio 1:1.
1097    *
1098    * @SINCE_1_0.0
1099    * @param[in] height Height to use
1100    * @return Return the width based on the height
1101    */
1102   float GetWidthForHeight( float height );
1103
1104   /**
1105    * @brief Returns the value of negotiated dimension for the given dimension.
1106    *
1107    * @SINCE_1_0.0
1108    * @param[in] dimension The dimension to retrieve
1109    * @return Return the value of the negotiated dimension. If more than one dimension is requested, just return the first one found
1110    */
1111   float GetRelayoutSize( Dimension::Type dimension ) const;
1112
1113 public: // Renderer
1114
1115   /**
1116    * @brief Adds a renderer to this actor.
1117    *
1118    * @SINCE_1_0.0
1119    * @param[in] renderer Renderer to add to the actor
1120    * @return The index of the Renderer that was added
1121    * @pre The renderer must be initialized.
1122    *
1123    */
1124   uint32_t AddRenderer( Renderer& renderer );
1125
1126   /**
1127    * @brief Gets the number of renderers on this actor.
1128    *
1129    * @SINCE_1_0.0
1130    * @return The number of renderers on this actor
1131    */
1132   uint32_t GetRendererCount() const;
1133
1134   /**
1135    * @brief Gets a Renderer by index.
1136    *
1137    * @SINCE_1_0.0
1138    * @param[in] index The index of the renderer to fetch
1139    * @return The renderer at the specified index
1140    * @pre The index must be between 0 and GetRendererCount()-1
1141    *
1142    */
1143   Renderer GetRendererAt( uint32_t index );
1144
1145   /**
1146    * @brief Removes a renderer from the actor.
1147    *
1148    * @SINCE_1_0.0
1149    * @param[in] renderer Handle to the renderer that is to be removed
1150    */
1151   void RemoveRenderer( Renderer& renderer );
1152
1153   /**
1154    * @brief Removes a renderer from the actor by index.
1155    *
1156    * @SINCE_1_0.0
1157    * @param[in] index Index of the renderer that is to be removed
1158    * @pre The index must be between 0 and GetRendererCount()-1
1159    *
1160    */
1161   void RemoveRenderer( uint32_t index );
1162
1163 public: // Signals
1164
1165   /**
1166    * @DEPRECATED_1_1.37 Use TouchSignal() instead.
1167    * @brief This signal is emitted when touch input is received.
1168    *
1169    * A callback of the following type may be connected:
1170    * @code
1171    *   bool YourCallbackName(Actor actor, const TouchEvent& event);
1172    * @endcode
1173    * The return value of True, indicates that the touch event should be consumed.
1174    * Otherwise the signal will be emitted on the next sensitive parent of the actor.
1175    * @SINCE_1_0.0
1176    * @return The signal to connect to
1177    * @pre The Actor has been initialized.
1178    */
1179   TouchSignalType& TouchedSignal() DALI_DEPRECATED_API;
1180
1181   /**
1182    * @brief This signal is emitted when touch input is received.
1183    *
1184    * A callback of the following type may be connected:
1185    * @code
1186    *   bool YourCallbackName( Actor actor, TouchData& touch );
1187    * @endcode
1188    * The return value of True, indicates that the touch event has been consumed.
1189    * Otherwise the signal will be emitted on the next sensitive parent of the actor.
1190    * A true return will also cancel any ongoing gestures.
1191    * @SINCE_1_1.37
1192    * @return The signal to connect to
1193    * @pre The Actor has been initialized.
1194    */
1195   TouchDataSignalType& TouchSignal();
1196
1197   /**
1198    * @brief This signal is emitted when hover input is received.
1199    *
1200    * A callback of the following type may be connected:
1201    * @code
1202    *   bool YourCallbackName(Actor actor, const HoverEvent& event);
1203    * @endcode
1204    * The return value of True, indicates that the hover event should be consumed.
1205    * Otherwise the signal will be emitted on the next sensitive parent of the actor.
1206    * @SINCE_1_0.0
1207    * @return The signal to connect to
1208    * @pre The Actor has been initialized.
1209    */
1210   HoverSignalType& HoveredSignal();
1211
1212   /**
1213    * @brief This signal is emitted when wheel event is received.
1214    *
1215    * A callback of the following type may be connected:
1216    * @code
1217    *   bool YourCallbackName(Actor actor, const WheelEvent& event);
1218    * @endcode
1219    * The return value of True, indicates that the wheel event should be consumed.
1220    * Otherwise the signal will be emitted on the next sensitive parent of the actor.
1221    * @SINCE_1_0.0
1222    * @return The signal to connect to
1223    * @pre The Actor has been initialized.
1224    */
1225   WheelEventSignalType& WheelEventSignal();
1226
1227   /**
1228    * @brief This signal is emitted after the actor has been connected to the scene.
1229    *
1230    * When an actor is connected, it will be directly or indirectly parented to the root Actor.
1231    * @SINCE_1_9.24
1232    * @return The signal to connect to
1233    * @note The root Actor is provided automatically by the Scene, and is always considered to be connected.
1234    *
1235    * @note When the parent of a set of actors is connected to the stage, then all of the children
1236    * will received this callback.
1237    * For the following actor tree, the callback order will be A, B, D, E, C, and finally F.
1238    *
1239    * @code
1240    *
1241    *       A (parent)
1242    *      / \
1243    *     B   C
1244    *    / \   \
1245    *   D   E   F
1246    *
1247    * @endcode
1248    */
1249   OnSceneSignalType& OnSceneSignal();
1250
1251   /**
1252    * @brief This signal is emitted after the actor has been disconnected from the scene.
1253    *
1254    * If an actor is disconnected it either has no parent, or is parented to a disconnected actor.
1255    *
1256    * @SINCE_1_9.24
1257    * @return The signal to connect to
1258    * @note When the parent of a set of actors is disconnected to the scene, then all of the children
1259    * will received this callback, starting with the leaf actors.
1260    * For the following actor tree, the callback order will be D, E, B, F, C, and finally A.
1261    *
1262    * @code
1263    *
1264    *       A (parent)
1265    *      / \
1266    *     B   C
1267    *    / \   \
1268    *   D   E   F
1269    *
1270    * @endcode
1271    *
1272    */
1273   OffSceneSignalType& OffSceneSignal();
1274
1275   /**
1276    * @brief This signal is emitted after the size has been set on the actor during relayout
1277    *
1278    * @SINCE_1_0.0
1279    * @return The signal
1280    */
1281   OnRelayoutSignalType& OnRelayoutSignal();
1282
1283   /**
1284    * @brief This signal is emitted when the layout direction property of this or a parent actor is changed.
1285    *
1286    * A callback of the following type may be connected:
1287    * @code
1288    *   void YourCallbackName( Actor actor, LayoutDirection::Type type );
1289    * @endcode
1290    * actor: The actor, or child of actor, whose layout direction has changed
1291    * type: Whether the actor's layout direction property has changed or a parent's.
1292    *
1293    * @SINCE_1_2.60
1294    * @return The signal to connect to
1295    * @pre The Actor has been initialized.
1296    */
1297   LayoutDirectionChangedSignalType& LayoutDirectionChangedSignal();
1298
1299 public: // Not intended for application developers
1300
1301   /// @cond internal
1302   /**
1303    * @brief This constructor is used by Actor::New() methods.
1304    *
1305    * @SINCE_1_0.0
1306    * @param [in] actor A pointer to a newly allocated Dali resource
1307    */
1308   explicit DALI_INTERNAL Actor(Internal::Actor* actor);
1309   /// @endcond
1310 };
1311
1312 /**
1313  * @brief Helper for discarding an actor handle.
1314  *
1315  * If the handle is empty, this method does nothing.  Otherwise
1316  * Actor::Unparent() will be called, followed by Actor::Reset().
1317  * @SINCE_1_0.0
1318  * @param[in,out] actor A handle to an actor, or an empty handle
1319  */
1320 inline void UnparentAndReset( Actor& actor )
1321 {
1322   if( actor )
1323   {
1324     actor.Unparent();
1325     actor.Reset();
1326   }
1327 }
1328
1329 /**
1330  * @}
1331  */
1332 } // namespace Dali
1333
1334 #endif // DALI_ACTOR_H