dali/internal/event/actors/actor-impl.h

   1 #ifndef __DALI_INTERNAL_ACTOR_H__
   2 #define __DALI_INTERNAL_ACTOR_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
  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 // EXTERNAL INCLUDES
  21 #include <string>
  22
  23 // INTERNAL INCLUDES
  24 #include <dali/public-api/common/map-wrapper.h>
  25 #include <dali/public-api/common/vector-wrapper.h>
  26 #include <dali/public-api/object/ref-object.h>
  27 #include <dali/public-api/actors/actor.h>
  28 #include <dali/public-api/common/dali-common.h>
  29 #include <dali/public-api/math/viewport.h>
  30 #include <dali/internal/event/common/proxy-object.h>
  31 #include <dali/internal/event/common/stage-def.h>
  32 #include <dali/internal/event/actors/actor-declarations.h>
  33 #include <dali/internal/event/actor-attachments/actor-attachment-declarations.h>
  34 #include <dali/internal/event/dynamics/dynamics-declarations.h>
  35 #include <dali/internal/update/nodes/node-declarations.h>
  36
  37 namespace Dali
  38 {
  39
  40 struct KeyEvent;
  41 struct TouchEvent;
  42 struct MouseWheelEvent;
  43
  44 namespace Internal
  45 {
  46
  47 class Actor;
  48 class RenderTask;
  49 class ShaderEffect;
  50 struct DynamicsData;
  51
  52 typedef IntrusivePtr<Actor>                   ActorPtr;
  53 typedef IntrusivePtr<ShaderEffect>            ShaderEffectPtr;
  54 typedef Dali::ActorContainer                  ActorContainer; // Store handles to return via public-api
  55 typedef ActorContainer::iterator              ActorIter;
  56 typedef ActorContainer::const_iterator        ActorConstIter;
  57
  58 /**
  59  * Actor is the primary object which Dali applications interact with.
  60  * UI controls can be built by combining multiple actors.
  61  * Multi-Touch events are received through signals emitted by the actor tree.
  62  *
  63  * An Actor is a proxy for a Node in the scene graph.
  64  * When an Actor is added to the Stage, it creates a node and attaches it to the scene graph.
  65  * The scene-graph can be updated in a separate thread, so the attachment is done using an asynchronous message.
  66  * When a tree of Actors is detached from the Stage, a message is sent to destroy the associated nodes.
  67  */
  68 class Actor : public ProxyObject
  69 {
  70 public:
  71
  72   /**
  73    * Create a new actor.
  74    * @return A smart-pointer to the newly allocated Actor.
  75    */
  76   static ActorPtr New();
  77
  78   /**
  79    * Retrieve the name of the actor.
  80    * @return The name.
  81    */
  82   const std::string& GetName() const;
  83
  84   /**
  85    * Set the name of the actor.
  86    * @param[in] name The new name.
  87    */
  88   void SetName(const std::string& name);
  89
  90   /**
  91    * @copydoc Dali::Actor::GetId
  92    */
  93   unsigned int GetId() const;
  94
  95   // Attachments
  96
  97   /**
  98    * Attach an object to an actor.
  99    * @pre The actor does not already have an attachment.
 100    * @param[in] attachment The object to attach.
 101    */
 102   void Attach(ActorAttachment& attachment);
 103
 104   /**
 105    * Retreive the object attached to an actor.
 106    * @return The attachment.
 107    */
 108   ActorAttachmentPtr GetAttachment();
 109
 110   // Containment
 111
 112   /**
 113    * Query whether an actor is the root actor, which is owned by the Stage.
 114    * @return True if the actor is a root actor.
 115    */
 116   bool IsRoot() const
 117   {
 118     return mIsRoot;
 119   }
 120
 121   /**
 122    * Query whether the actor is connected to the Stage.
 123    */
 124   bool OnStage() const;
 125
 126   /**
 127    * Query whether the actor is a RenderableActor derived type.
 128    * @return True if the actor is renderable.
 129    */
 130   bool IsRenderable() const
 131   {
 132     // inlined as this is called a lot in hit testing
 133     return mIsRenderable;
 134   }
 135
 136   /**
 137    * Query whether the actor is of class Dali::Layer
 138    * @return True if the actor is a layer.
 139    */
 140   bool IsLayer() const
 141   {
 142     // inlined as this is called a lot in hit testing
 143     return mIsLayer;
 144   }
 145
 146   /**
 147    * Gets the layer in which the actor is present
 148    * @return The layer, which will be uninitialized if the actor is off-stage.
 149    */
 150   Dali::Layer GetLayer();
 151
 152   /**
 153    * Adds a child Actor to this Actor.
 154    * @pre The child actor is not the same as the parent actor.
 155    * @pre The child actor does not already have a parent.
 156    * @param [in] child The child.
 157    * @post The child will be referenced by its parent.
 158    */
 159   void Add(Actor& child);
 160
 161   /**
 162    * Removes a child Actor from this Actor.
 163    * @param [in] child The child.
 164    * @post The child will be unreferenced.
 165    */
 166   void Remove(Actor& child);
 167
 168   /**
 169    * @copydoc Dali::Actor::Unparent
 170    */
 171   void Unparent();
 172
 173   /**
 174    * Retrieve the number of children held by the actor.
 175    * @return The number of children
 176    */
 177   unsigned int GetChildCount() const;
 178
 179   /**
 180    * @copydoc Dali::Actor::GetChildAt
 181    */
 182   Dali::Actor GetChildAt(unsigned int index) const;
 183
 184   /**
 185    * Retrieve the Actor's children.
 186    * @return A copy of the container of children.
 187    */
 188   ActorContainer GetChildren();
 189
 190   /**
 191    * Retrieve the Actor's children.
 192    * @return A const reference to the container of children.
 193    */
 194   const ActorContainer& GetChildren() const;
 195
 196   /**
 197    * Retrieve a reference to Actor's children.
 198    * @note Not for public use.
 199    * @return A reference to the container of children.
 200    */
 201   ActorContainer& GetChildrenInternal()
 202   {
 203     return *mChildren;
 204   }
 205
 206   /**
 207    * @copydoc Dali::Actor::FindChildByName
 208    */
 209   ActorPtr FindChildByName(const std::string& actorName);
 210
 211   /**
 212    * @copydoc Dali::Actor::FindChildByAlias
 213    */
 214   Dali::Actor FindChildByAlias(const std::string& actorAlias);
 215
 216   /**
 217    * @copydoc Dali::Actor::FindChildById
 218    */
 219   ActorPtr FindChildById(const unsigned int id);
 220
 221   /**
 222    * Retrieve the parent of an Actor.
 223    * @return The parent actor, or NULL if the Actor does not have a parent.
 224    */
 225   Actor* GetParent() const
 226   {
 227     return mParent;
 228   }
 229
 230   /**
 231    * Sets the size of an actor.
 232    * ActorAttachments attached to the actor, can be scaled to fit within this area.
 233    * This does not interfere with the actors scale factor.
 234    * @param [in] width  The new width.
 235    * @param [in] height The new height.
 236    */
 237   void SetSize(float width, float height);
 238
 239   /**
 240    * Sets the size of an actor.
 241    * ActorAttachments attached to the actor, can be scaled to fit within this area.
 242    * This does not interfere with the actors scale factor.
 243    * @param [in] width The size of the actor along the x-axis.
 244    * @param [in] height The size of the actor along the y-axis.
 245    * @param [in] depth The size of the actor along the z-axis.
 246    */
 247   void SetSize(float width, float height, float depth);
 248
 249   /**
 250    * Sets the size of an actor.
 251    * ActorAttachments attached to the actor, can be scaled to fit within this area.
 252    * This does not interfere with the actors scale factor.
 253    * @param [in] size The new size.
 254    */
 255   void SetSize(const Vector2& size);
 256
 257   /**
 258    * Sets the size of an actor.
 259    * ActorAttachments attached to the actor, can be scaled to fit within this area.
 260    * This does not interfere with the actors scale factor.
 261    * @param [in] size The new size.
 262    */
 263   void SetSize(const Vector3& size);
 264
 265   /**
 266    * Set the width component of the Actor's size.
 267    * @param [in] width The new width component.
 268    */
 269   void SetWidth( float width );
 270
 271   /**
 272    * Set the height component of the Actor's size.
 273    * @param [in] height The new height component.
 274    */
 275   void SetHeight( float height );
 276
 277   /**
 278    * Set the depth component of the Actor's size.
 279    * @param [in] depth The new depth component.
 280    */
 281   void SetDepth( float depth );
 282
 283   /**
 284    * Retrieve the Actor's size.
 285    * @return The Actor's size.
 286    */
 287   const Vector3& GetCurrentSize() const;
 288
 289   /**
 290    * Set the origin of an actor, within its parent's area.
 291    * This is expressed in 2D unit coordinates, such that (0.0, 0.0, 0.5) is the top-left corner of the parent,
 292    * and (1.0, 1.0, 0.5) is the bottom-right corner.
 293    * The default parent-origin is top-left (0.0, 0.0, 0.5).
 294    * An actor position is the distance between this origin, and the actors anchor-point.
 295    * @param [in] origin The new parent-origin.
 296    */
 297   void SetParentOrigin(const Vector3& origin);
 298
 299   /**
 300    * Set the x component of the parent-origin
 301    * @param [in] x The new x value.
 302    */
 303   void SetParentOriginX( float x );
 304
 305   /**
 306    * Set the y component of the parent-origin
 307    * @param [in] y The new y value.
 308    */
 309   void SetParentOriginY( float y );
 310
 311   /**
 312    * Set the z component of the parent-origin
 313    * @param [in] z The new z value.
 314    */
 315   void SetParentOriginZ( float z );
 316
 317   /**
 318    * Retrieve the parent-origin of an actor.
 319    * @return The parent-origin.
 320    */
 321   const Vector3& GetCurrentParentOrigin() const;
 322
 323   /**
 324    * Set the anchor-point of an actor. This is expressed in 2D unit coordinates, such that
 325    * (0.0, 0.0, 0.5) is the top-left corner of the actor, and (1.0, 1.0, 0.5) is the bottom-right corner.
 326    * The default anchor point is top-left (0.0, 0.0, 0.5).
 327    * An actor position is the distance between its parent-origin, and this anchor-point.
 328    * An actor's rotation is centered around its anchor-point.
 329    * @param [in] anchorPoint The new anchor-point.
 330    */
 331   void SetAnchorPoint(const Vector3& anchorPoint);
 332
 333   /**
 334    * Set the x component of the anchor-point.
 335    * @param [in] x The new x value.
 336    */
 337   void SetAnchorPointX( float x );
 338
 339   /**
 340    * Set the y component of the anchor-point.
 341    * @param [in] y The new y value.
 342    */
 343   void SetAnchorPointY( float y );
 344
 345   /**
 346    * Set the z component of the anchor-point.
 347    * @param [in] z The new z value.
 348    */
 349   void SetAnchorPointZ( float z );
 350
 351   /**
 352    * Retrieve the anchor-point of an actor.
 353    * @return The anchor-point.
 354    */
 355   const Vector3& GetCurrentAnchorPoint() const;
 356
 357   /**
 358    * Sets the position of the Actor.
 359    * The coordinates are relative to the Actor's parent.
 360    * The Actor's z position will be set to 0.0f.
 361    * @param [in] x The new x position
 362    * @param [in] y The new y position
 363    */
 364   void SetPosition(float x, float y);
 365
 366   /**
 367    * Sets the position of the Actor.
 368    * The coordinates are relative to the Actor's parent.
 369    * @param [in] x The new x position
 370    * @param [in] y The new y position
 371    * @param [in] z The new z position
 372    */
 373   void SetPosition(float x, float y, float z);
 374
 375   /**
 376    * Sets the position of the Actor.
 377    * The coordinates are relative to the Actor's parent.
 378    * @param [in] position The new position.
 379    */
 380   void SetPosition(const Vector3& position);
 381
 382   /**
 383    * Set the position of an actor along the X-axis.
 384    * @param [in] x The new x position
 385    */
 386   void SetX(float x);
 387
 388   /**
 389    * Set the position of an actor along the Y-axis.
 390    * @param [in] y The new y position.
 391    */
 392   void SetY(float y);
 393
 394   /**
 395    * Set the position of an actor along the Z-axis.
 396    * @param [in] z The new z position
 397    */
 398   void SetZ(float z);
 399
 400   /**
 401    * Move an actor relative to its existing position.
 402    * @param[in] distance The actor will move by this distance.
 403    */
 404   void MoveBy(const Vector3& distance);
 405
 406   /**
 407    * Retrieve the position of the Actor.
 408    * The coordinates are relative to the Actor's parent.
 409    * @return the Actor's position.
 410    */
 411   const Vector3& GetCurrentPosition() const;
 412
 413   /**
 414    * @copydoc Dali::Actor::GetCurrentWorldPosition()
 415    */
 416   const Vector3& GetCurrentWorldPosition() const;
 417
 418   /**
 419    * @copydoc Dali::Actor::SetPositionInheritanceMode()
 420    */
 421   void SetPositionInheritanceMode( PositionInheritanceMode mode );
 422
 423   /**
 424    * @copydoc Dali::Actor::GetPositionInheritanceMode()
 425    */
 426   PositionInheritanceMode GetPositionInheritanceMode() const;
 427
 428   /**
 429    * Sets the rotation of the Actor.
 430    * @param [in] angleRadians The new rotation angle in radians.
 431    * @param [in] axis The new axis of rotation.
 432    */
 433   void SetRotation(const Radian& angleRadians, const Vector3& axis);
 434
 435   /**
 436    * Sets the rotation of the Actor.
 437    * @param [in] rotation The new rotation.
 438    */
 439   void SetRotation(const Quaternion& rotation);
 440
 441   /**
 442    * Rotate an actor around its existing rotation axis.
 443    * @param[in] angleRadians The angle to the rotation to combine with the existing rotation.
 444    * @param[in] axis The axis of the rotation to combine with the existing rotation.
 445    */
 446   void RotateBy(const Radian& angleRadians, const Vector3& axis);
 447
 448   /**
 449    * Apply a relative rotation to an actor.
 450    * @param[in] relativeRotation The rotation to combine with the actors existing rotation.
 451    */
 452   void RotateBy(const Quaternion& relativeRotation);
 453
 454   /**
 455    * Retreive the Actor's rotation.
 456    * @return the rotation.
 457    */
 458   const Quaternion& GetCurrentRotation() const;
 459
 460   /**
 461    * Set whether a child actor inherits it's parent's orientation. Default is to inherit.
 462    * Switching this off means that using SetRotation() sets the actor's world orientation.
 463    * @param[in] inherit - true if the actor should inherit orientation, false otherwise.
 464    */
 465   void SetInheritRotation(bool inherit);
 466
 467   /**
 468    * Returns whether the actor inherit's it's parent's orientation.
 469    * @return true if the actor inherit's it's parent orientation, false if it uses world orientation.
 470    */
 471   bool IsRotationInherited() const;
 472
 473   /**
 474    * @copydoc Dali::Actor::GetCurrentWorldRotation()
 475    */
 476   const Quaternion& GetCurrentWorldRotation() const;
 477
 478   /**
 479    * Sets a scale factor applied to an actor.
 480    * @param [in] scale The scale factor applied on all axes.
 481    */
 482   void SetScale(float scale);
 483
 484   /**
 485    * Sets a scale factor applied to an actor.
 486    * @param [in] scaleX The scale factor applied along the x-axis.
 487    * @param [in] scaleY The scale factor applied along the y-axis.
 488    * @param [in] scaleZ The scale factor applied along the z-axis.
 489    */
 490   void SetScale(float scaleX, float scaleY, float scaleZ);
 491
 492   /**
 493    * Sets a scale factor applied to an actor.
 494    * @param [in] scale A vector representing the scale factor for each axis.
 495    */
 496   void SetScale(const Vector3& scale);
 497
 498   /**
 499    * Set the x component of the scale factor.
 500    * @param [in] x The new x value.
 501    */
 502   void SetScaleX( float x );
 503
 504   /**
 505    * Set the y component of the scale factor.
 506    * @param [in] y The new y value.
 507    */
 508   void SetScaleY( float y );
 509
 510   /**
 511    * Set the z component of the scale factor.
 512    * @param [in] z The new z value.
 513    */
 514   void SetScaleZ( float z );
 515
 516   /**
 517    * Apply a relative scale to an actor.
 518    * @param[in] relativeScale The scale to combine with the actors existing scale.
 519    */
 520   void ScaleBy(const Vector3& relativeScale);
 521
 522   /**
 523    * Retrieve the scale factor applied to an actor.
 524    * @return A vector representing the scale factor for each axis.
 525    */
 526   const Vector3& GetCurrentScale() const;
 527
 528   /**
 529    * @copydoc Dali::Actor::GetCurrentWorldScale()
 530    */
 531   const Vector3& GetCurrentWorldScale() const;
 532
 533   /**
 534    * @copydoc Dali::Actor::SetInheritScale()
 535    */
 536   void SetInheritScale( bool inherit );
 537
 538   /**
 539    * @copydoc Dali::Actor::IsScaleInherited()
 540    */
 541   bool IsScaleInherited() const;
 542
 543   /**
 544    * @copydoc Dali::Actor::GetCurrentWorldMatrix()
 545    */
 546   Matrix GetCurrentWorldMatrix() const;
 547
 548   // Visibility
 549
 550   /**
 551    * Sets the visibility flag of an actor.
 552    * @param [in] visible The new visibility flag.
 553    */
 554   void SetVisible(bool visible);
 555
 556   /**
 557    * Retrieve the visibility flag of an actor.
 558    * @return The visibility flag.
 559    */
 560   bool IsVisible() const;
 561
 562   /**
 563    * Sets the opacity of an actor.
 564    * @param [in] opacity The new opacity.
 565    */
 566   void SetOpacity(float opacity);
 567
 568   /**
 569    * Apply a relative opacity change to an actor.
 570    * @param[in] relativeOpacity The opacity to combine with the actors existing opacity.
 571    */
 572   void OpacityBy(float relativeOpacity);
 573
 574   /**
 575    * Retrieve the actor's opacity.
 576    * @return The actor's opacity.
 577    */
 578   float GetCurrentOpacity() const;
 579
 580   /**
 581    * Sets whether an actor should emit touch signals; see SignalTouch().
 582    * An actor is sensitive by default, which means that as soon as an application connects to the SignalTouch(),
 583    * the touch event signal will be emitted.
 584    *
 585    * If the application wishes to temporarily disable the touch event signal emission, then they can do so by calling:
 586    * @code
 587    * actor.SetSensitive(false);
 588    * @endcode
 589    *
 590    * Then, to re-enable the touch event signal emission, the application should call:
 591    * @code
 592    * actor.SetSensitive(true);
 593    * @endcode
 594    *
 595    * @see SignalTouch().
 596    * @note If an actor's sensitivity is set to false, then it's children will not emit a touch event signal either.
 597    * @param[in]  sensitive  true to enable emission of the touch event signals, false otherwise.
 598    */
 599   void SetSensitive(bool sensitive)
 600   {
 601     mSensitive = sensitive;
 602   }
 603
 604   /**
 605    * Query whether an actor emits touch event signals.
 606    * @see SetSensitive(bool)
 607    * @return true, if emission of touch event signals is enabled, false otherwise.
 608    */
 609   bool IsSensitive() const
 610   {
 611     return mSensitive;
 612   }
 613
 614   /**
 615    * Set whether the actor inherits a shader effect from its parent.
 616    * The inherited effect can be overridden using SetShaderEffect()
 617    * @param [in] inherit True if the parent effect is inherited.
 618    */
 619   void SetInheritShaderEffect(bool inherit);
 620
 621   /**
 622    * Query whether the actor inherits a shader effect from its parent.
 623    * @return True if the parent effect is inherited.
 624    */
 625   bool GetInheritShaderEffect() const;
 626
 627   /**
 628    * Sets the shader effect for the Actor.
 629    * Shader effects provide special effects like rippling and bending.
 630    * Setting a shader effect removes any shader effect previously set by SetShaderEffect.
 631    * @param [in] effect The shader effect.
 632    */
 633   void SetShaderEffect(ShaderEffect& effect);
 634
 635   /**
 636    * Retrieve the shader effect for the Actor.
 637    * @return The shader effect
 638    */
 639   ShaderEffectPtr GetShaderEffect() const;
 640
 641   /**
 642    * Removes the current shader effect.
 643    */
 644   void RemoveShaderEffect();
 645
 646   /**
 647    * @copydoc Dali::Actor::SetDrawMode
 648    */
 649   void SetDrawMode( DrawMode::Type drawMode );
 650
 651   /**
 652    * @copydoc Dali::Actor::GetDrawMode
 653    */
 654   DrawMode::Type GetDrawMode() const;
 655
 656   /**
 657    * @copydoc Dali::Actor::SetOverlay
 658    */
 659   void SetOverlay(bool enable);
 660
 661   /**
 662    * @copydoc Dali::Actor::IsOverlay
 663    */
 664   bool IsOverlay() const;
 665
 666   /**
 667    * Sets whether an actor transmits geometry scaling to it's children.
 668    * The default value is for it not to transmit scaling.
 669    * @param[in] transmitGeometryScaling True to transmit scaling.
 670    */
 671   void SetTransmitGeometryScaling(bool transmitGeometryScaling);
 672
 673   /**
 674    * Get the TransmitGeometryScaling property for this actor.
 675    * @return True if geometry scaling is applied to the inherited scale.
 676    */
 677   bool GetTransmitGeometryScaling() const;
 678
 679   /**
 680    * Sets the initial volume of the actor. Used for scaling the
 681    * actor appropriately as the actor is sized when transmitGeometryScaling
 682    * is set to true.
 683    *
 684    * @param[in] volume the volume of the model and it's children
 685    */
 686   void SetInitialVolume(const Vector3& volume);
 687
 688   /**
 689    * Sets the actor's color.  The final color of actor depends on its color mode.
 690    * This final color is applied to the drawable elements of an actor.
 691    * @param [in] color The new color.
 692    */
 693   void SetColor(const Vector4& color);
 694
 695   /**
 696    * Set the red component of the color.
 697    * @param [in] red The new red component.
 698    */
 699   void SetColorRed( float red );
 700
 701   /**
 702    * Set the green component of the color.
 703    * @param [in] green The new green component.
 704    */
 705   void SetColorGreen( float green );
 706
 707   /**
 708    * Set the blue component of the scale factor.
 709    * @param [in] blue The new blue value.
 710    */
 711   void SetColorBlue( float blue );
 712
 713   /**
 714    * Apply a relative color change to an actor.
 715    * @param[in] relativeColor The color to combine with the actors existing color.
 716    */
 717   void ColorBy(const Vector4& relativeColor);
 718
 719   /**
 720    * Retrieve the actor's color.
 721    * @return The color.
 722    */
 723   const Vector4& GetCurrentColor() const;
 724
 725   /**
 726    * Sets the actor's color mode.
 727    * Color mode specifies whether Actor uses its own color or inherits its parent color
 728    * @param [in] colorMode to use.
 729    */
 730   void SetColorMode(ColorMode colorMode);
 731
 732   /**
 733    * Returns the actor's color mode.
 734    * @return currently used colorMode.
 735    */
 736   ColorMode GetColorMode() const;
 737
 738   /**
 739    * @copydoc Dali::Actor::GetCurrentWorldColor()
 740    */
 741   const Vector4& GetCurrentWorldColor() const;
 742
 743   // Dynamics
 744
 745   /// @copydoc Dali::Actor::DisableDynamics
 746   void DisableDynamics();
 747
 748   /// @copydoc Dali::Actor::EnableDynamics(Dali::DynamicsBodyConfig)
 749   DynamicsBodyPtr  EnableDynamics(DynamicsBodyConfigPtr bodyConfig);
 750
 751   /// @copydoc Dali::Actor::GetDynamicsBody
 752   DynamicsBodyPtr GetDynamicsBody() const;
 753
 754   /// @copydoc Dali::Actor::AddDynamicsJoint(Dali::Actor,const Vector3&)
 755   DynamicsJointPtr AddDynamicsJoint( ActorPtr attachedActor, const Vector3& offset );
 756
 757   /// @copydoc Dali::Actor::AddDynamicsJoint(Dali::Actor,const Vector3&,const Vector3&)
 758   DynamicsJointPtr AddDynamicsJoint( ActorPtr attachedActor, const Vector3& offsetA, const Vector3& offsetB );
 759
 760   /// @copydoc Dali::Actor::GetNumberOfJoints
 761   const int GetNumberOfJoints() const;
 762
 763   /// @copydoc Dali::Actor::GetDynamicsJointByIndex
 764   DynamicsJointPtr GetDynamicsJointByIndex( const int index ) const;
 765
 766   /// @copydoc Dali::Actor::GetDynamicsJoint
 767   DynamicsJointPtr GetDynamicsJoint( ActorPtr attachedActor ) const;
 768
 769   /// @copydoc Dali::Actor::RemoveDynamicsJoint
 770   void RemoveDynamicsJoint( DynamicsJointPtr joint );
 771
 772   /**
 773    * Hold a reference to a DynamicsJoint
 774    * @param[in] joint The joint
 775    */
 776   void ReferenceJoint( DynamicsJointPtr joint );
 777
 778   /**
 779    * Release a reference to a DynamicsJoint
 780    * @param[in] joint The joint
 781    */
 782   void ReleaseJoint( DynamicsJointPtr joint );
 783
 784   /**
 785    * Set this actor to be the root actor in the dynamics simulation
 786    * All children of the actor are added/removed from the simulation.
 787    * @param[in] flag  When true sets this actor to be the simulation world root actor and
 788    *                  if OnStage() all dynamics enabled child actors are added to the simulation,
 789    *                  when false stops this actor being the simulation root and if OnStage() all
 790    *                  dynamics enabled child actors are removed from the simulation.
 791    */
 792   void SetDynamicsRoot(bool flag);
 793
 794 private:
 795   /**
 796    * Check if this actor is the root actor in the dynamics simulation
 797    * @return true if this is the dynamics root actor.
 798    */
 799   bool IsDynamicsRoot() const;
 800
 801   /**
 802    * Add actor to the dynamics simulation
 803    * Invoked when the actor is staged, or it's parent becomes the simulation root
 804    */
 805   void ConnectDynamics();
 806
 807   /**
 808    * Remove actor from the dynamics simulation
 809    * Invoked when the actor is unstaged, or it's parent stops being the the simulation root
 810    */
 811   void DisconnectDynamics();
 812
 813   /**
 814    * An actor in a DynamicsJoint relationship has been staged
 815    * @param[in] actor The actor passed into AddDynamicsJoint()
 816    */
 817   void AttachedActorOnStage( Dali::Actor actor );
 818
 819   /**
 820    * An actor in a DynamicsJoint relationship has been unstaged
 821    * @param[in] actor The actor passed into AddDynamicsJoint()
 822    */
 823   void AttachedActorOffStage( Dali::Actor actor );
 824 public:
 825   /**
 826    * Converts screen coordinates into the actor's coordinate system.
 827    * @note The actor coordinates are relative to the top-left (0.0, 0.0, 0.5)
 828    * @param[out] localX On return, the X-coordinate relative to the actor.
 829    * @param[out] localY On return, the Y-coordinate relative to the actor.
 830    * @param[in] screenX The screen X-coordinate.
 831    * @param[in] screenY The screen Y-coordinate.
 832    * @return True if the conversion succeeded.
 833    */
 834   bool ScreenToLocal(float& localX, float& localY, float screenX, float screenY) const;
 835
 836   /**
 837    * Converts screen coordinates into the actor's coordinate system.
 838    * @note The actor coordinates are relative to the top-left (0.0, 0.0, 0.5)
 839    * @param[in] renderTask The render-task used to display the actor.
 840    * @param[out] localX On return, the X-coordinate relative to the actor.
 841    * @param[out] localY On return, the Y-coordinate relative to the actor.
 842    * @param[in] screenX The screen X-coordinate.
 843    * @param[in] screenY The screen Y-coordinate.
 844    * @return True if the conversion succeeded.
 845    */
 846   bool ScreenToLocal(RenderTask& renderTask, float& localX, float& localY, float screenX, float screenY) const;
 847
 848   /**
 849    * Converts from the actor's coordinate system to screen coordinates.
 850    * @note The actor coordinates are relative to the top-left (0.0, 0.0, 0.5)
 851    * @param[in] viewMatrix The view-matrix
 852    * @param[in] projectionMatrix The projection-matrix
 853    * @param[in] viewport The view-port
 854    * @param[out] localX On return, the X-coordinate relative to the actor.
 855    * @param[out] localY On return, the Y-coordinate relative to the actor.
 856    * @param[in] screenX The screen X-coordinate.
 857    * @param[in] screenY The screen Y-coordinate.
 858    * @return True if the conversion succeeded.
 859    */
 860   bool ScreenToLocal( const Matrix& viewMatrix,
 861                       const Matrix& projectionMatrix,
 862                       const Viewport& viewport,
 863                       float& localX,
 864                       float& localY,
 865                       float screenX,
 866                       float screenY ) const;
 867
 868   /**
 869    * Performs a ray-sphere test with the given pick-ray and the actor's bounding sphere.
 870    * @note The actor coordinates are relative to the top-left (0.0, 0.0, 0.5)
 871    * @param[in] rayOrigin The ray origin in the world's reference system.
 872    * @param[in] rayDir The ray director vector in the world's reference system.
 873    * @return True if the ray intersects the actor's bounding sphere.
 874    */
 875   bool RaySphereTest( const Vector4& rayOrigin, const Vector4& rayDir ) const;
 876
 877   /**
 878    * Performs a ray-actor test with the given pick-ray and the actor's geometry.
 879    * @note The actor coordinates are relative to the top-left (0.0, 0.0, 0.5)
 880    * @param[in] rayOrigin The ray origin in the world's reference system.
 881    * @param[in] rayDir The ray director vector in the world's reference system.
 882    * @param[out] hitPointLocal The hit point in the Actor's local reference system.
 883    * @param[out] distance The distance from the hit point to the camera.
 884    * @return True if the ray intersects the actor's geometry.
 885    */
 886   bool RayActorTest( const Vector4& rayOrigin, const Vector4& rayDir, Vector4& hitPointLocal, float& distance ) const;
 887
 888   /**
 889    * Sets whether the actor should receive a notification when touch motion events leave
 890    * the boundary of the actor.
 891    *
 892    * @note By default, this is set to false as most actors do not require this.
 893    * @note Need to connect to the SignalTouch to actually receive this event.
 894    *
 895    * @param[in]  required  Should be set to true if a Leave event is required
 896    */
 897   void SetLeaveRequired(bool required);
 898
 899   /**
 900    * This returns whether the actor requires touch events whenever touch motion events leave
 901    * the boundary of the actor.
 902    * @return true if a Leave event is required, false otherwise.
 903    */
 904   bool GetLeaveRequired() const;
 905
 906   /**
 907    * @copydoc Dali::Actor::SetKeyboardFocusable()
 908    */
 909   void SetKeyboardFocusable( bool focusable );
 910
 911   /**
 912    * @copydoc Dali::Actor::IsKeyboardFocusable()
 913    */
 914   bool IsKeyboardFocusable() const;
 915
 916   /**
 917    * Query whether the application or derived actor type requires touch events.
 918    * @return True if touch events are required.
 919    */
 920   bool GetTouchRequired() const;
 921
 922   /**
 923    * Query whether the application or derived actor type requires mouse wheel events.
 924    * @return True if mouse wheel events are required.
 925    */
 926   bool GetMouseWheelEventRequired() const;
 927
 928   /**
 929    * Query whether the actor is actually hittable.  This method checks whether the actor is
 930    * sensitive, has the visibility flag set to true and is not fully transparent.
 931    * @return true, if it can be hit, false otherwise.
 932    */
 933   bool IsHittable() const;
 934
 935
 936   // Signals
 937
 938   /**
 939    * Used by the EventProcessor to emit touch event signals.
 940    * @param[in] event The touch event.
 941    * @return True if the event was consumed.
 942    */
 943   bool EmitTouchEventSignal(const TouchEvent& event);
 944
 945   /**
 946    * Used by the EventProcessor to emit mouse wheel event signals.
 947    * @param[in] event The mouse wheel event.
 948    * @return True if the event was consumed.
 949    */
 950   bool EmitMouseWheelEventSignal(const MouseWheelEvent& event);
 951
 952   /**
 953    * @copydoc Dali::Actor::TouchedSignal()
 954    */
 955   Dali::Actor::TouchSignalV2& TouchedSignal();
 956
 957   /**
 958    * @copydoc Dali::Actor::MouseWheelEventSignal()
 959    */
 960   Dali::Actor::MouseWheelEventSignalV2& MouseWheelEventSignal();
 961
 962   /**
 963    * @copydoc Dali::Actor::SetSizeSignal()
 964    */
 965   Dali::Actor::SetSizeSignalV2& SetSizeSignal();
 966
 967   /**
 968    * @copydoc Dali::Actor::OnStageSignal()
 969    */
 970   Dali::Actor::OnStageSignalV2& OnStageSignal();
 971
 972   /**
 973    * @copydoc Dali::Actor::OffStageSignal()
 974    */
 975   Dali::Actor::OffStageSignalV2& OffStageSignal();
 976
 977   /**
 978    * Connects a callback function with the object's signals.
 979    * @param[in] object The object providing the signal.
 980    * @param[in] tracker Used to disconnect the signal.
 981    * @param[in] signalName The signal to connect to.
 982    * @param[in] functor A newly allocated FunctorDelegate.
 983    * @return True if the signal was connected.
 984    * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
 985    */
 986   static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
 987
 988   /**
 989    * Performs actions as requested using the action name.
 990    * @param[in] object The object on which to perform the action.
 991    * @param[in] actionName The action to perform.
 992    * @param[in] attributes The attributes with which to perfrom this action.
 993    * @return true if the action was done.
 994    */
 995   static bool DoAction(BaseObject* object, const std::string& actionName, const std::vector<Property::Value>& attributes);
 996
 997 public:  // For Animation
 998
 999   /**
1000    * For use in derived classes.
1001    * This should only be called by Animation, when the actor is resized using Animation::Resize().
1002    */
1003   virtual void OnSizeAnimation(Animation& animation, const Vector3& targetSize) {}
1004
1005 protected:
1006
1007   enum DerivedType
1008   {
1009     BASIC,
1010     RENDERABLE,
1011     LAYER,
1012     ROOT_LAYER
1013   };
1014
1015   /**
1016    * Protected Constructor.  See Actor::New().
1017    * The second-phase construction Initialize() member should be called immediately after this.
1018    * @param[in] derivedType The derived type of actor (if any).
1019    */
1020   Actor( DerivedType derivedType );
1021
1022   /**
1023    * Second-phase constructor. Must be called immediately after creating a new Actor;
1024    */
1025   void Initialize(void);
1026
1027   /**
1028    * A reference counted object may only be deleted by calling Unreference()
1029    */
1030   virtual ~Actor();
1031
1032   /**
1033    * Called on a child during Add() when the parent actor is connected to the Stage.
1034    * @param[in] stage The stage.
1035    */
1036   void ConnectToStage(Stage& stage);
1037
1038   /**
1039    * Helper for ConnectToStage, to recursively connect a tree of actors.
1040    * This is atomic i.e. not interrupted by user callbacks.
1041    * @param[in] stage The stage.
1042    * @param[out] connectionList On return, the list of connected actors which require notification.
1043    */
1044   void RecursiveConnectToStage( Stage& stage, ActorContainer& connectionList );
1045
1046   /**
1047    * Connect the Node associated with this Actor to the scene-graph.
1048    */
1049   void ConnectToSceneGraph();
1050
1051   /**
1052    * Helper for ConnectToStage, to notify a connected actor through the public API.
1053    */
1054   void NotifyStageConnection();
1055
1056   /**
1057    * Called on a child during Remove() when the actor was previously on the Stage.
1058    */
1059   void DisconnectFromStage();
1060
1061   /**
1062    * Helper for DisconnectFromStage, to recursively disconnect a tree of actors.
1063    * This is atomic i.e. not interrupted by user callbacks.
1064    * @param[out] disconnectionList On return, the list of disconnected actors which require notification.
1065    */
1066   void RecursiveDisconnectFromStage( ActorContainer& disconnectionList );
1067
1068   /**
1069    * Disconnect the Node associated with this Actor from the scene-graph.
1070    */
1071   void DisconnectFromSceneGraph();
1072
1073   /**
1074    * Helper for DisconnectFromStage, to notify a disconnected actor through the public API.
1075    */
1076   void NotifyStageDisconnection();
1077
1078   /**
1079    * When the Actor is OnStage, checks whether the corresponding Node is connected to the scene graph.
1080    * @return True if the Actor is OnStage & has a Node connected to the scene graph.
1081    */
1082   bool IsNodeConnected() const;
1083
1084 public: // Default property extensions from ProxyObject
1085
1086   /**
1087    * @copydoc Dali::Internal::ProxyObject::IsSceneObjectRemovable()
1088    */
1089   virtual bool IsSceneObjectRemovable() const;
1090
1091   /**
1092    * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyCount()
1093    */
1094   virtual unsigned int GetDefaultPropertyCount() const;
1095
1096   /**
1097    * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyIndices()
1098    */
1099   virtual void GetDefaultPropertyIndices( Property::IndexContainer& indices ) const;
1100
1101   /**
1102    * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyName()
1103    */
1104   virtual const std::string& GetDefaultPropertyName(Property::Index index) const;
1105
1106   /**
1107    * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyIndex()
1108    */
1109   virtual Property::Index GetDefaultPropertyIndex(const std::string& name) const;
1110
1111   /**
1112    * @copydoc Dali::Internal::ProxyObject::IsDefaultPropertyWritable()
1113    */
1114   virtual bool IsDefaultPropertyWritable(Property::Index index) const;
1115
1116   /**
1117    * @copydoc Dali::Internal::ProxyObject::IsDefaultPropertyAnimatable()
1118    */
1119   virtual bool IsDefaultPropertyAnimatable(Property::Index index) const;
1120
1121   /**
1122    * @copydoc Dali::Internal::ProxyObject::GetDefaultPropertyType()
1123    */
1124   virtual Property::Type GetDefaultPropertyType(Property::Index index) const;
1125
1126   /**
1127    * @copydoc Dali::Internal::ProxyObject::SetDefaultProperty()
1128    */
1129   virtual void SetDefaultProperty(Property::Index index, const Property::Value& propertyValue);
1130
1131   /**
1132    * @copydoc Dali::Internal::ProxyObject::SetCustomProperty()
1133    */
1134   virtual void SetCustomProperty( Property::Index index, const CustomProperty& entry, const Property::Value& value );
1135
1136   /**
1137    * @copydoc Dali::Internal::ProxyObject::GetDefaultProperty()
1138    */
1139   virtual Property::Value GetDefaultProperty( Property::Index index ) const;
1140
1141   /**
1142    * @copydoc Dali::Internal::ProxyObject::InstallSceneObjectProperty()
1143    */
1144   virtual void InstallSceneObjectProperty( SceneGraph::PropertyBase& newProperty, const std::string& name, unsigned int index );
1145
1146   /**
1147    * @copydoc Dali::Internal::ProxyObject::GetSceneObject()
1148    */
1149   virtual const SceneGraph::PropertyOwner* GetSceneObject() const;
1150
1151   /**
1152    * @copydoc Dali::Internal::ProxyObject::GetSceneObjectAnimatableProperty()
1153    */
1154   virtual const SceneGraph::PropertyBase* GetSceneObjectAnimatableProperty( Property::Index index ) const;
1155
1156   /**
1157    * @copydoc Dali::Internal::ProxyObject::GetSceneObjectInputProperty()
1158    */
1159   virtual const PropertyInputImpl* GetSceneObjectInputProperty( Property::Index index ) const;
1160
1161   /**
1162    * @copydoc Dali::Internal::ProxyObject::GetPropertyComponentIndex()
1163    */
1164   virtual int GetPropertyComponentIndex( Property::Index index ) const;
1165
1166 private:
1167
1168   // Undefined
1169   Actor();
1170
1171   // Undefined
1172   Actor(const Actor&);
1173
1174   // Undefined
1175   Actor& operator=(const Actor& rhs);
1176
1177   /**
1178    * Set the actors parent.
1179    * @param[in] parent The new parent.
1180    */
1181   void SetParent(Actor* parent);
1182
1183   /**
1184    * Helper to create a Node for this Actor.
1185    * To be overriden in derived classes.
1186    * @return A newly allocated node.
1187    */
1188   virtual SceneGraph::Node* CreateNode() const;
1189
1190   /**
1191    * For use in derived classes, called after Initialize()
1192    */
1193   virtual void OnInitialize() {}
1194
1195   /**
1196    * For use in internal derived classes.
1197    * This is called during ConnectToStage(), after the actor has finished adding its node to the scene-graph.
1198    * The derived class must not modify the actor hierachy (Add/Remove children) during this callback.
1199    */
1200   virtual void OnStageConnectionInternal() {}
1201
1202   /**
1203    * For use in internal derived classes.
1204    * This is called during DisconnectFromStage(), before the actor removes its node from the scene-graph.
1205    * The derived class must not modify the actor hierachy (Add/Remove children) during this callback.
1206    */
1207   virtual void OnStageDisconnectionInternal() {}
1208
1209   /**
1210    * For use in external (CustomActor) derived classes.
1211    * This is called after the atomic ConnectToStage() traversal has been completed.
1212    */
1213   virtual void OnStageConnectionExternal() {}
1214
1215   /**
1216    * For use in external (CustomActor) derived classes.
1217    * This is called after the atomic DisconnectFromStage() traversal has been completed.
1218    */
1219   virtual void OnStageDisconnectionExternal() {}
1220
1221   /**
1222    * For use in derived classes; this is called after Add() has added a child.
1223    * @param[in] child The child that was added.
1224    */
1225   virtual void OnChildAdd( Actor& child ) {}
1226
1227   /**
1228    * For use in derived classes; this is called after Remove() has removed a child.
1229    * @param[in] child The child that was removed.
1230    */
1231   virtual void OnChildRemove( Actor& child ) {}
1232
1233   /**
1234    * For use in derived classes.
1235    * This is called after SizeSet() has been called.
1236    */
1237   virtual void OnSizeSet(const Vector3& targetSize) {}
1238
1239   /**
1240    * For use in derived classes.
1241    * This is called after a non animatable custom property is set.
1242    * @param [in] index The index of the property.
1243    * @param [in] propertyValue The value of the property.
1244    */
1245   virtual void OnPropertySet( Property::Index index, Property::Value propertyValue ) {}
1246
1247   /**
1248    * For use in derived classes.
1249    * This is only called if mTouchRequired is true, and the touch-signal was not consumed.
1250    * @param[in] event The touch event.
1251    * @return True if the event should be consumed.
1252    */
1253   virtual bool OnTouchEvent(const TouchEvent& event) { return false; }
1254
1255   /**
1256    * For use in derived classes.
1257    * This is only called if the mouse wheel signal was not consumed.
1258    * @param[in] event The mouse event.
1259    * @return True if the event should be consumed.
1260    */
1261   virtual bool OnMouseWheelEvent(const MouseWheelEvent& event) { return false; }
1262
1263   /**
1264    * For use in derived class
1265    * If an alias for a child exists, return the child otherwise return an empty handle.
1266    * For example 'previous' could return the last selected child.
1267    * @pre The Actor has been initialized.
1268    * @param[in] actorAlias the name of the actor to find
1269    * @return A handle to the actor if found, or an empty handle if not.
1270    */
1271   virtual Dali::Actor GetChildByAlias(const std::string& actorAlias) { return Dali::Actor(); }
1272
1273   /**
1274    * Support function for FindChildByAlias
1275    * @pre The Actor has been initialized.
1276    * @param[in] actorAlias the name of the aliased actor to find
1277    * @return A handle to the actor if found, or an empty handle if not.
1278    */
1279   Dali::Actor DoGetChildByAlias(const std::string& actorAlias);
1280
1281 protected:
1282
1283   std::string mName;
1284
1285   static unsigned int mActorCounter;  ///< A counter to track the actor instance creation
1286   unsigned int mId;  ///< A unique ID to identify the actor starting from 1, and 0 is reserved
1287
1288   StagePtr mStage; ///< Used to send messages to Node; valid until Core destruction
1289
1290   const bool mIsRoot                   : 1;   ///< Flag to identify the root actor
1291   const bool mIsRenderable             : 1;   ///< Flag to identify that this is a renderable actor
1292   const bool mIsLayer                  : 1;   ///< Flag to identify that this is a layer
1293   bool mIsOnStage                      : 1;   ///< Flag to identify whether the actor is on-stage
1294   bool mIsDynamicsRoot                 : 1;   ///< Flag to identify if this is the dynamics world root
1295   bool mSensitive                      : 1;   ///< Whether the actor emits touch event signals
1296   bool mLeaveRequired                  : 1;   ///< Whether a touch event signal is emitted when the a touch leaves the actor's bounds
1297   bool mKeyboardFocusable              : 1;   ///< Whether the actor should be focusable by keyboard navigation
1298   bool mDerivedRequiresTouch           : 1;   ///< Whether the derived actor type requires touch event signals
1299   bool mDerivedRequiresMouseWheelEvent : 1;   ///< Whether the derived actor type requires mouse wheel event signals
1300   bool mOnStageSignalled               : 1;   ///< Set to true before OnStageConnection signal is emitted, and false before OnStageDisconnection
1301
1302   bool mInheritRotation:1; ///< Cached: Whether the parent's rotation should be inherited.
1303   bool mInheritScale:1; ///< Cached: Whether the parent's scale should be inherited.
1304   DrawMode::Type mDrawMode:2; ///< Cached: How the actor and its children should be drawn
1305   PositionInheritanceMode mPositionInheritanceMode:2; ///< Cached: Determines how position is inherited
1306   ColorMode mColorMode:2; ///< Cached: Determines whether mWorldColor is inherited
1307
1308   Actor* mParent; ///< Each actor (except the root) can have one parent
1309
1310   ActorContainer*              mChildren;     ///< Container of referenced actors
1311   static ActorContainer        mNullChildren; ///< Empty container (shared by all actors, returned by GetChildren() const)
1312   ActorAttachmentPtr           mAttachment;   ///< Optional referenced attachment
1313
1314   const SceneGraph::Node* mNode; ///< Not owned
1315
1316   // ParentOrigin & AnchorPoint are non-animatable
1317   Vector3* mParentOrigin; // NULL means ParentOrigin::DEFAULT
1318   Vector3* mAnchorPoint; // NULL means AnchorPoint::DEFAULT
1319
1320   ShaderEffectPtr mShaderEffect; ///< Optional referenced shader effect
1321
1322   // Dynamics
1323   DynamicsData* mDynamicsData;
1324
1325   // Signals
1326   Dali::Actor::TouchSignalV2              mTouchedSignalV2;
1327   Dali::Actor::MouseWheelEventSignalV2    mMouseWheelEventSignalV2;
1328   Dali::Actor::SetSizeSignalV2            mSetSizeSignalV2;
1329   Dali::Actor::OnStageSignalV2            mOnStageSignalV2;
1330   Dali::Actor::OffStageSignalV2           mOffStageSignalV2;
1331
1332   // Default properties
1333
1334   typedef std::map<std::string, Property::Index> DefaultPropertyLookup;
1335
1336 private:
1337
1338   // Default properties
1339
1340   static DefaultPropertyLookup* mDefaultPropertyLookup;
1341 };
1342
1343 } // namespace Internal
1344
1345 // Helpers for public-api forwarding methods
1346
1347 inline Internal::Actor& GetImplementation(Dali::Actor& actor)
1348 {
1349   DALI_ASSERT_ALWAYS(actor && "Actor handle is empty");
1350
1351   BaseObject& handle = actor.GetBaseObject();
1352
1353   return static_cast<Internal::Actor&>(handle);
1354 }
1355
1356 inline const Internal::Actor& GetImplementation(const Dali::Actor& actor)
1357 {
1358   DALI_ASSERT_ALWAYS(actor && "Actor handle is empty");
1359
1360   const BaseObject& handle = actor.GetBaseObject();
1361
1362   return static_cast<const Internal::Actor&>(handle);
1363 }
1364
1365 } // namespace Dali
1366
1367 #endif // __DALI_INTERNAL_ACTOR_H__