dali/public-api/actors/custom-actor-impl.h

   1 #ifndef __DALI_CUSTOM_ACTOR_IMPL_H__
   2 #define __DALI_CUSTOM_ACTOR_IMPL_H__
   3
   4 /*
   5  * Copyright (c) 2015 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 // INTERNAL INCLUDES
  22 #include <dali/public-api/common/vector-wrapper.h>
  23 #include <dali/public-api/object/property.h>
  24 #include <dali/public-api/object/ref-object.h>
  25 #include <dali/public-api/actors/actor-enumerations.h>
  26 #include <dali/public-api/math/compile-time-math.h>
  27
  28 namespace Dali
  29 {
  30
  31 namespace Internal DALI_INTERNAL
  32 {
  33 class CustomActor;
  34 }
  35
  36 class Actor;
  37 class Animation;
  38 class CustomActor;
  39 class CustomActorImpl;
  40 class RelayoutContainer;
  41 struct KeyEvent;
  42 struct TouchEvent;
  43 struct HoverEvent;
  44 struct MouseWheelEvent;
  45 struct Vector2;
  46 struct Vector3;
  47
  48
  49 /**
  50  * @brief Pointer to Dali::CustomActorImpl object.
  51  */
  52 typedef IntrusivePtr<CustomActorImpl> CustomActorImplPtr;
  53
  54 /**
  55  * @brief CustomActorImpl is an abstract base class for custom control implementations.
  56  *
  57  * This provides a series of pure virtual methods, which are called when actor-specific events occur.
  58  * An CustomActorImpl is typically owned by a single CustomActor instance; see also CustomActor::New(CustomActorImplPtr).
  59  */
  60 class DALI_IMPORT_API CustomActorImpl : public Dali::RefObject
  61 {
  62 public:
  63
  64   /**
  65    * @brief Virtual destructor.
  66    */
  67   virtual ~CustomActorImpl();
  68
  69   /**
  70    * @brief Used by derived CustomActorImpl instances, to access the public Actor interface.
  71    *
  72    * @return A pointer to self, or an uninitialized pointer if the CustomActorImpl is not owned.
  73    */
  74   CustomActor Self() const;
  75
  76   /**
  77    * @brief Called after the actor has been connected to the stage.
  78    *
  79    * When an actor is connected, it will be directly or indirectly parented to the root Actor.
  80    * @note The root Actor is provided automatically by Dali::Stage, and is always considered to be connected.
  81    *
  82    * @note When the parent of a set of actors is connected to the stage, then all of the children
  83    * will received this callback.
  84    *
  85    * For the following actor tree, the callback order will be A, B, D, E, C, and finally F.
  86    *
  87    *       A (parent)
  88    *      / \
  89    *     B   C
  90    *    / \   \
  91    *   D   E   F
  92    */
  93   virtual void OnStageConnection() = 0;
  94
  95   /**
  96    * @brief Called after the actor has been disconnected from the stage.
  97    *
  98    * If an actor is disconnected it either has no parent, or is parented to a disconnected actor.
  99    *
 100    * @note When the parent of a set of actors is disconnected to the stage, then all of the children
 101    * will received this callback, starting with the leaf actors.
 102    *
 103    * For the following actor tree, the callback order will be D, E, B, F, C, and finally A.
 104    *
 105    *       A (parent)
 106    *      / \
 107    *     B   C
 108    *    / \   \
 109    *   D   E   F
 110    */
 111   virtual void OnStageDisconnection() = 0;
 112
 113   /**
 114    * @brief Called after a child has been added to the owning actor.
 115    *
 116    * @param[in] child The child which has been added.
 117    */
 118   virtual void OnChildAdd(Actor& child) = 0;
 119
 120   /**
 121    * @brief Called after a child has been removed from the owning actor.
 122    *
 123    * @param[in] child The child being removed.
 124    */
 125   virtual void OnChildRemove(Actor& child) = 0;
 126
 127   /**
 128    * @brief Called when the owning actor property is set.
 129    *
 130    * @param[in] index The Property index that was set.
 131    * @param[in] propertyValue The value to set.
 132    */
 133   virtual void OnPropertySet( Property::Index index, Property::Value propertyValue ) ;
 134
 135   /**
 136    * @brief Called when the owning actor's size is set e.g. using Actor::SetSize().
 137    *
 138    * @param[in] targetSize The target size. Note that this target size may not match the size returned via Actor::GetSize().
 139    */
 140   virtual void OnSizeSet(const Vector3& targetSize) = 0;
 141
 142   /**
 143    * @brief Called when the owning actor's size is animated e.g. using Animation::AnimateTo( Property( actor, Actor::Property::SIZE ), ... ).
 144    *
 145    * @param[in] animation The object which is animating the owning actor.
 146    * @param[in] targetSize The target size. Note that this target size may not match the size returned via Actor::GetSize().
 147    */
 148   virtual void OnSizeAnimation(Animation& animation, const Vector3& targetSize) = 0;
 149
 150   /**
 151    * @brief Called after a touch-event is received by the owning actor.
 152    *
 153    * @note This must be enabled during construction; see CustomActorImpl::CustomActorImpl(bool)
 154    * @param[in] event The touch event.
 155    * @return True if the event should be consumed.
 156    */
 157   virtual bool OnTouchEvent(const TouchEvent& event) = 0;
 158
 159   /**
 160    * @brief Called after a hover-event is received by the owning actor.
 161    *
 162    * @note This must be enabled during construction; see CustomActorImpl::SetRequiresHoverEvents(bool)
 163    * @param[in] event The hover event.
 164    * @return True if the event should be consumed.
 165    */
 166   virtual bool OnHoverEvent(const HoverEvent& event) = 0;
 167
 168   /**
 169    * @brief Called after a key-event is received by the actor that has had its focus set.
 170    *
 171    * @param[in] event the Key Event
 172    * @return True if the event should be consumed.
 173    */
 174   virtual bool OnKeyEvent(const KeyEvent& event) = 0;
 175
 176   /**
 177    * @brief Called after a mouse-wheel-event is received by the owning actor.
 178    *
 179    * @note This must be enabled during construction; see CustomActorImpl::SetRequiresMouseWheelEvents(bool)
 180    * @param[in] event The mouse wheel event.
 181    * @return True if the event should be consumed.
 182    */
 183   virtual bool OnMouseWheelEvent(const MouseWheelEvent& event) = 0;
 184
 185   /**
 186    * @brief Called after the size negotiation has been finished for this control.
 187    *
 188    * The control is expected to assign this given size to itself/its children.
 189    *
 190    * Should be overridden by derived classes if they need to layout
 191    * actors differently after certain operations like add or remove
 192    * actors, resize or after changing specific properties.
 193    *
 194    * Note! As this function is called from inside the size negotiation algorithm, you cannot
 195    * call RequestRelayout (the call would just be ignored)
 196    *
 197    * @param[in]      size       The allocated size.
 198    * @param[in,out]  container  The control should add actors to this container that it is not able
 199    *                            to allocate a size for.
 200    */
 201   virtual void OnRelayout( const Vector2& size, RelayoutContainer& container ) = 0;
 202
 203   /**
 204    * @brief Notification for deriving classes
 205    *
 206    * @param[in] policy The policy being set
 207    * @param[in] dimension The dimension the policy is being set for
 208    */
 209   virtual void OnSetResizePolicy( ResizePolicy::Type policy, Dimension::Type dimension ) = 0;
 210
 211   /**
 212    * Return the natural size of the actor
 213    *
 214    * @return The actor's natural size
 215    */
 216   virtual Vector3 GetNaturalSize() = 0;
 217
 218   /**
 219    * @brief Calculate the size for a child
 220    *
 221    * @param[in] child The child actor to calculate the size for
 222    * @param[in] dimension The dimension to calculate the size for. E.g. width or height.
 223    * @return Return the calculated size for the given dimension
 224    */
 225   virtual float CalculateChildSize( const Dali::Actor& child, Dimension::Type dimension ) = 0;
 226
 227   /**
 228    * @brief This method is called during size negotiation when a height is required for a given width.
 229    *
 230    * Derived classes should override this if they wish to customize the height returned.
 231    *
 232    * @param width to use.
 233    * @return the height based on the width.
 234    */
 235   virtual float GetHeightForWidth( float width ) = 0;
 236
 237   /**
 238    * @brief This method is called during size negotiation when a width is required for a given height.
 239    *
 240    * Derived classes should override this if they wish to customize the width returned.
 241    *
 242    * @param height to use.
 243    * @return the width based on the width.
 244    */
 245   virtual float GetWidthForHeight( float height ) = 0;
 246
 247   /**
 248    * @brief Determine if this actor is dependent on it's children for relayout
 249    *
 250    * @param dimension The dimension(s) to check for
 251    * @return Return if the actor is dependent on it's children
 252    */
 253   virtual bool RelayoutDependentOnChildren( Dimension::Type dimension = Dimension::ALL_DIMENSIONS ) = 0;
 254
 255   /**
 256    * @brief Virtual method to notify deriving classes that relayout dependencies have been
 257    * met and the size for this object is about to be calculated for the given dimension
 258    *
 259    * @param dimension The dimension that is about to be calculated
 260    */
 261   virtual void OnCalculateRelayoutSize( Dimension::Type dimension ) = 0;
 262
 263   /**
 264    * @brief Virtual method to notify deriving classes that the size for a dimension
 265    * has just been negotiated
 266    *
 267    * @param[in] size The new size for the given dimension
 268    * @param[in] dimension The dimension that was just negotiated
 269    */
 270   virtual void OnLayoutNegotiated( float size, Dimension::Type dimension ) = 0;
 271
 272 protected: // For derived classes
 273
 274   // Flags for the constructor
 275   enum ActorFlags
 276   {
 277     ACTOR_BEHAVIOUR_NONE          = 0,
 278     DISABLE_SIZE_NEGOTIATION      = 1 << 0,     ///< True if control does not need size negotiation, i.e. it can be skipped in the algorithm
 279     REQUIRES_TOUCH_EVENTS         = 1 << 1,     ///< True if the OnTouchEvent() callback is required.
 280     REQUIRES_HOVER_EVENTS         = 1 << 2,     ///< True if the OnHoverEvent() callback is required.
 281     REQUIRES_MOUSE_WHEEL_EVENTS   = 1 << 3,     ///< True if the OnMouseWheelEvent() callback is required.
 282
 283     LAST_ACTOR_FLAG                             ///< Special marker for last actor flag
 284   };
 285
 286   static const int ACTOR_FLAG_COUNT = Log< LAST_ACTOR_FLAG - 1 >::value + 1;      ///< Value for deriving classes to continue on the flag enum
 287
 288   /**
 289    * @brief Create a CustomActorImpl.
 290    * @param[in] flags Bitfield of ActorFlags to define behaviour
 291    */
 292   CustomActorImpl( ActorFlags flags );
 293
 294   /**
 295    * @brief Request a relayout, which means performing a size negotiation on this actor, its parent and children (and potentially whole scene)
 296    *
 297    * This method can also be called from a derived class every time it needs a different size.
 298    * At the end of event processing, the relayout process starts and
 299    * all controls which requested Relayout will have their sizes (re)negotiated.
 300    *
 301    * @note RelayoutRequest() can be called multiple times; the size negotiation is still
 302    * only performed once, i.e. there is no need to keep track of this in the calling side.
 303    */
 304   void RelayoutRequest();
 305
 306   /**
 307    * @brief Calculate the size for a child using the base actor object
 308    *
 309    * @param[in] child The child actor to calculate the size for
 310    * @param[in] dimension The dimension to calculate the size for. E.g. width or height.
 311    * @return Return the calculated size for the given dimension
 312    */
 313   float CalculateChildSizeBase( const Dali::Actor& child, Dimension::Type dimension );
 314
 315   /**
 316    * @brief Determine if this actor is dependent on it's children for relayout from the base class
 317    *
 318    * @param dimension The dimension(s) to check for
 319    * @return Return if the actor is dependent on it's children
 320    */
 321   bool RelayoutDependentOnChildrenBase( Dimension::Type dimension = Dimension::ALL_DIMENSIONS );
 322
 323 public: // Not intended for application developers
 324
 325   /**
 326    * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor.
 327    * @pre The CustomActorImpl is not already owned.
 328    * @param[in] owner The owning object.
 329    */
 330   void Initialize(Internal::CustomActor& owner);
 331
 332   /**
 333    * @brief Get the owner.
 334    *
 335    * This method is needed when creating additional handle objects to existing objects.
 336    * Owner is the Dali::Internal::CustomActor that owns the implementation of the custom actor
 337    * inside core. Creation of a handle to Dali public API Actor requires this pointer.
 338    * @return a pointer to the Actor implementation that owns this custom actor implementation
 339    */
 340   Internal::CustomActor* GetOwner() const;
 341
 342   /**
 343    * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor.
 344    * @return True if the OnTouchEvent() callback is required.
 345    */
 346   bool RequiresTouchEvents() const;
 347
 348   /**
 349    * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor.
 350    * @return True if the OnHoverEvent() callback is required.
 351    */
 352   bool RequiresHoverEvents() const;
 353
 354   /**
 355    * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor.
 356    * @return True if the OnMouseWheelEvent() callback is required.
 357    */
 358   bool RequiresMouseWheelEvents() const;
 359
 360   /**
 361    * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor.
 362    * @return Return true if relayout is enabled on the custom actor
 363    */
 364   bool IsRelayoutEnabled() const;
 365
 366 private:
 367
 368   Internal::CustomActor* mOwner;        ///< Internal owner of this custom actor implementation
 369   ActorFlags mFlags :ACTOR_FLAG_COUNT;  ///< ActorFlags flags to determine behaviour
 370 };
 371
 372 } // namespace Dali
 373
 374 #endif // __DALI_CUSTOM_ACTOR_IMPL_H__