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) 2014 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // 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
  26 namespace Dali
  27 {
  28
  29 namespace Internal DALI_INTERNAL
  30 {
  31 class CustomActor;
  32 }
  33
  34 class Actor;
  35 class Animation;
  36 class CustomActor;
  37 class CustomActorImpl;
  38 struct KeyEvent;
  39 struct TouchEvent;
  40 struct HoverEvent;
  41 struct MouseWheelEvent;
  42 struct Vector3;
  43
  44 /**
  45  * @brief Pointer to Dali::CustomActorImpl object.
  46  */
  47 typedef IntrusivePtr<CustomActorImpl> CustomActorImplPtr;
  48
  49 /**
  50  * @brief CustomActorImpl is an abstract base class for custom control implementations.
  51  *
  52  * This provides a series of pure virtual methods, which are called when actor-specific events occur.
  53  * An CustomActorImpl is typically owned by a single CustomActor instance; see also CustomActor::New(CustomActorImplPtr).
  54  */
  55 class DALI_IMPORT_API CustomActorImpl : public Dali::RefObject
  56 {
  57 public:
  58
  59   /**
  60    * @brief Virtual destructor.
  61    */
  62   virtual ~CustomActorImpl();
  63
  64   /**
  65    * @brief Used by derived CustomActorImpl instances, to access the public Actor interface.
  66    *
  67    * @return A pointer to self, or an uninitialized pointer if the CustomActorImpl is not owned.
  68    */
  69   CustomActor Self() const;
  70
  71   /**
  72    * @brief Called after the actor has been connected to the stage.
  73    *
  74    * When an actor is connected, it will be directly or indirectly parented to the root Actor.
  75    * @note The root Actor is provided automatically by Dali::Stage, and is always considered to be connected.
  76    *
  77    * @note When the parent of a set of actors is connected to the stage, then all of the children
  78    * will received this callback.
  79    *
  80    * For the following actor tree, the callback order will be A, B, D, E, C, and finally F.
  81    *
  82    *       A (parent)
  83    *      / \
  84    *     B   C
  85    *    / \   \
  86    *   D   E   F
  87    */
  88   virtual void OnStageConnection() = 0;
  89
  90   /**
  91    * @brief Called after the actor has been disconnected from the stage.
  92    *
  93    * If an actor is disconnected it either has no parent, or is parented to a disconnected actor.
  94    *
  95    * @note When the parent of a set of actors is disconnected to the stage, then all of the children
  96    * will received this callback, starting with the leaf actors.
  97    *
  98    * For the following actor tree, the callback order will be D, E, B, F, C, and finally A.
  99    *
 100    *       A (parent)
 101    *      / \
 102    *     B   C
 103    *    / \   \
 104    *   D   E   F
 105    */
 106   virtual void OnStageDisconnection() = 0;
 107
 108   /**
 109    * @brief Called after a child has been added to the owning actor.
 110    *
 111    * @param[in] child The child which has been added.
 112    */
 113   virtual void OnChildAdd(Actor& child) = 0;
 114
 115   /**
 116    * @brief Called after a child has been removed from the owning actor.
 117    *
 118    * @param[in] child The child being removed.
 119    */
 120   virtual void OnChildRemove(Actor& child) = 0;
 121
 122   /**
 123    * @brief Called when the owning actor property is set.
 124    *
 125    * @param[in] index The Property index that was set.
 126    * @param[in] propertyValue The value to set.
 127    */
 128   virtual void OnPropertySet( Property::Index index, Property::Value propertyValue ) ;
 129
 130   /**
 131    * @brief Called when the owning actor's size is set e.g. using Actor::SetSize().
 132    *
 133    * @param[in] targetSize The target size. Note that this target size may not match the size returned via Actor::GetSize().
 134    */
 135   virtual void OnSizeSet(const Vector3& targetSize) = 0;
 136
 137   /**
 138    * @brief Called when the owning actor's size is animated e.g. using Animation::Resize().
 139    *
 140    * @param[in] animation The object which is animating the owning actor.
 141    * @param[in] targetSize The target size. Note that this target size may not match the size returned via Actor::GetSize().
 142    */
 143   virtual void OnSizeAnimation(Animation& animation, const Vector3& targetSize) = 0;
 144
 145   /**
 146    * @brief Called after a touch-event is received by the owning actor.
 147    *
 148    * @note This must be enabled during construction; see CustomActorImpl::CustomActorImpl(bool)
 149    * @param[in] event The touch event.
 150    * @return True if the event should be consumed.
 151    */
 152   virtual bool OnTouchEvent(const TouchEvent& event) = 0;
 153
 154   /**
 155    * @brief Called after a hover-event is received by the owning actor.
 156    *
 157    * @note This must be enabled during construction; see CustomActorImpl::SetRequiresHoverEvents(bool)
 158    * @param[in] event The hover event.
 159    * @return True if the event should be consumed.
 160    */
 161   virtual bool OnHoverEvent(const HoverEvent& event) = 0;
 162
 163   /**
 164    * @brief Called after a key-event is received by the actor that has had its focus set.
 165    *
 166    * @param[in] event the Key Event
 167    * @return True if the event should be consumed.
 168    */
 169   virtual bool OnKeyEvent(const KeyEvent& event) = 0;
 170
 171   /**
 172    * @brief Called after a mouse-wheel-event is received by the owning actor.
 173    *
 174    * @note This must be enabled during construction; see CustomActorImpl::SetRequiresMouseWheelEvents(bool)
 175    * @param[in] event The mouse wheel event.
 176    * @return True if the event should be consumed.
 177    */
 178   virtual bool OnMouseWheelEvent(const MouseWheelEvent& event) = 0;
 179
 180   /**
 181    * @brief Called to find a child by an alias.
 182    *
 183    * If an alias for a child exists, return the child otherwise return an empty handle.
 184    * For example 'previous' could return the last selected child.
 185    * @pre The Actor has been initialized.
 186    * @param[in] actorAlias the name of the actor to find
 187    * @return A handle to the actor if found, or an empty handle if not.
 188    */
 189   virtual Dali::Actor GetChildByAlias(const std::string& actorAlias) = 0;
 190
 191   /**
 192    * Return the natural size of the actor
 193    *
 194    * @return The actor's natural size
 195    */
 196   virtual Vector3 GetNaturalSize() = 0;
 197
 198 protected: // For derived classes
 199
 200   /**
 201    * @brief Create a CustomActorImpl.
 202    * @param[in] requiresTouchEvents True if the OnTouchEvent() callback is required.
 203    */
 204   CustomActorImpl(bool requiresTouchEvents);
 205
 206   /**
 207    * @brief Set whether the custom actor requires hover events.
 208    * @param[in] requiresHoverEvents True if the OnHoverEvent() callback is required.
 209    */
 210   void SetRequiresHoverEvents(bool requiresHoverEvents);
 211
 212   /**
 213    * @brief Set whether the custom actor requires mouse wheel events.
 214    * @param[in] requiresMouseWheelEvents True if the OnMouseWheelEvent() callback is required.
 215    */
 216   void SetRequiresMouseWheelEvents(bool requiresMouseWheelEvents);
 217
 218 public: // Not intended for application developers
 219
 220   /**
 221    * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor.
 222    * @pre The CustomActorImpl is not already owned.
 223    * @param[in] owner The owning object.
 224    */
 225   void Initialize(Internal::CustomActor& owner);
 226
 227   /**
 228    * @brief Get the owner.
 229    *
 230    * This method is needed when creating additional handle objects to existing objects.
 231    * Owner is the Dali::Internal::CustomActor that owns the implementation of the custom actor
 232    * inside core. Creation of a handle to Dali public API Actor requires this pointer.
 233    * @return a pointer to the Actor implementation that owns this custom actor implementation
 234    */
 235   Internal::CustomActor* GetOwner() const;
 236
 237   /**
 238    * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor.
 239    * @return True if the OnTouchEvent() callback is required.
 240    */
 241   bool RequiresTouchEvents() const;
 242
 243   /**
 244    * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor.
 245    * @return True if the OnHoverEvent() callback is required.
 246    */
 247   bool RequiresHoverEvents() const;
 248
 249   /**
 250    * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor.
 251    * @return True if the OnMouseWheelEvent() callback is required.
 252    */
 253   bool RequiresMouseWheelEvents() const;
 254
 255 private:
 256
 257   Internal::CustomActor* mOwner;  ///< Internal owner of this custom actor implementation
 258   bool mRequiresTouchEvents;      ///< Whether the OnTouchEvent() callback is required
 259   bool mRequiresHoverEvents;      ///< Whether the OnHoverEvent() callback is required
 260   bool mRequiresMouseWheelEvents; ///< Whether the OnMouseWheelEvent() callback is required
 261 };
 262
 263 } // namespace Dali
 264
 265 #endif // __DALI_CUSTOM_ACTOR_IMPL_H__