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