capi/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 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 /**
  21  * @addtogroup CAPI_DALI_FRAMEWORK
  22  * @{
  23  */
  24
  25 // INTERNAL INCLUDES
  26 #include <dali/public-api/common/vector-wrapper.h>
  27 #include <dali/public-api/object/property.h>
  28 #include <dali/public-api/object/ref-object.h>
  29
  30 namespace Dali DALI_IMPORT_API
  31 {
  32
  33 namespace Internal DALI_INTERNAL
  34 {
  35 class CustomActor;
  36 }
  37
  38 class Actor;
  39 class Animation;
  40 class CustomActor;
  41 class CustomActorImpl;
  42 struct KeyEvent;
  43 struct TouchEvent;
  44 struct MouseWheelEvent;
  45 struct Vector3;
  46
  47 typedef IntrusivePtr<CustomActorImpl> CustomActorImplPtr;
  48
  49 /**
  50  * CustomActorImpl is an abstract base class for custom control implementations.
  51  * This provides a series of pure virtual methods, which are called when actor-specific events occur.
  52  * An CustomActorImpl is typically owned by a single CustomActor instance; see also CustomActor::New(CustomActorImplPtr).
  53  */
  54 class DALI_IMPORT_API CustomActorImpl : public Dali::RefObject
  55 {
  56 public:
  57
  58   /**
  59    * Virtual destructor.
  60    */
  61   virtual ~CustomActorImpl();
  62
  63   /**
  64    * Used by derived CustomActorImpl instances, to access the public Actor interface.
  65    * @return A pointer to self, or an uninitialized pointer if the CustomActorImpl is not owned.
  66    */
  67   CustomActor Self() const;
  68
  69   /**
  70    * Called after the actor has been connected to the stage.
  71    * When an actor is connected, it will be directly or indirectly parented to the root Actor.
  72    * @note The root Actor is provided automatically by Dali::Stage, and is always considered to be connected.
  73    *
  74    * @note When the parent of a set of actors is connected to the stage, then all of the children
  75    * will received this callback.
  76    *
  77    * For the following actor tree, the callback order will be A, B, D, E, C, and finally F.
  78    *
  79    *       A (parent)
  80    *      / \
  81    *     B   C
  82    *    / \   \
  83    *   D   E   F
  84    */
  85   virtual void OnStageConnection() = 0;
  86
  87   /**
  88    * Called after the actor has been disconnected from the stage.
  89    * If an actor is disconnected it either has no parent, or is parented to a disconnected actor.
  90    *
  91    * @note When the parent of a set of actors is disconnected to the stage, then all of the children
  92    * will received this callback, starting with the leaf actors.
  93    *
  94    * For the following actor tree, the callback order will be D, E, B, F, C, and finally A.
  95    *
  96    *       A (parent)
  97    *      / \
  98    *     B   C
  99    *    / \   \
 100    *   D   E   F
 101    */
 102   virtual void OnStageDisconnection() = 0;
 103
 104   /**
 105    * Called after a child has been added to the owning actor.
 106    * @param[in] child The child which has been added.
 107    */
 108   virtual void OnChildAdd(Actor& child) = 0;
 109
 110   /**
 111    * Called after a child has been removed from the owning actor.
 112    * @param[in] child The child being removed.
 113    */
 114   virtual void OnChildRemove(Actor& child) = 0;
 115
 116   /**
 117    * Called when the owning actor property is set.
 118    * @param[in] index The Property index that was set.
 119    * @param[in] propertyValue The value to set.
 120    */
 121   virtual void OnPropertySet( Property::Index index, Property::Value propertyValue ) ;
 122
 123   /**
 124    * Called when the owning actor's size is set e.g. using Actor::SetSize().
 125    * @param[in] targetSize The target size. Note that this target size may not match the size returned via Actor::GetSize().
 126    */
 127   virtual void OnSizeSet(const Vector3& targetSize) = 0;
 128
 129   /**
 130    * Called when the owning actor's size is animated e.g. using Animation::Resize().
 131    * @param[in] animation The object which is animating the owning actor.
 132    * @param[in] targetSize The target size. Note that this target size may not match the size returned via Actor::GetSize().
 133    */
 134   virtual void OnSizeAnimation(Animation& animation, const Vector3& targetSize) = 0;
 135
 136   /**
 137    * Called after a touch-event is received by the owning actor.
 138    * @note This must be enabled during construction; see CustomActorImpl::CustomActorImpl(bool)
 139    * @param[in] event The touch event.
 140    * @return True if the event should be consumed.
 141    */
 142   virtual bool OnTouchEvent(const TouchEvent& event) = 0;
 143
 144   /**
 145    * Called after a key-event is received by the actor that has had its focus set.
 146    * @param[in] event the Key Event
 147    * @return True if the event should be consumed.
 148    */
 149   virtual bool OnKeyEvent(const KeyEvent& event) = 0;
 150
 151   /**
 152    * Called after a mouse-wheel-event is received by the owning actor.
 153    * @note This must be enabled during construction; see CustomActorImpl::SetRequiresMouseWheelEvents(bool)
 154    * @param[in] event The mouse wheel event.
 155    * @return True if the event should be consumed.
 156    */
 157   virtual bool OnMouseWheelEvent(const MouseWheelEvent& event) = 0;
 158
 159   /**
 160    * Called when this actor gains keyboard focus.
 161    */
 162   virtual void OnKeyInputFocusGained() = 0;
 163
 164   /**
 165    * Called when this actor loses keyboard focus.
 166    */
 167   virtual void OnKeyInputFocusLost() = 0;
 168
 169   /**
 170    * Called to find a child by an alias.
 171    * If an alias for a child exists, return the child otherwise return an empty handle.
 172    * For example 'previous' could return the last selected child.
 173    * @pre The Actor has been initialized.
 174    * @param[in] actorAlias the name of the actor to find
 175    * @return A handle to the actor if found, or an empty handle if not.
 176    */
 177   virtual Dali::Actor GetChildByAlias(const std::string& actorAlias) = 0;
 178
 179 protected: // For derived classes
 180
 181   /**
 182    * Create a CustomActorImpl.
 183    * @param[in] requiresTouchEvents True if the OnTouchEvent() callback is required.
 184    */
 185   CustomActorImpl(bool requiresTouchEvents);
 186
 187   /**
 188    * Set whether the custom actor requires mouse wheel events.
 189    * @param[in] requiresMouseWheelEvents True if the OnMouseWheelEvent() callback is required.
 190    */
 191   void SetRequiresMouseWheelEvents(bool requiresMouseWheelEvents);
 192
 193 public: // Not intended for application developers
 194
 195   /**
 196    * Called when ownership of the CustomActorImpl passed to a CustomActor.
 197    * @pre The CustomActorImpl is not already owned.
 198    * @param[in] owner The owning object.
 199    */
 200   void Initialize(Internal::CustomActor& owner);
 201
 202   /**
 203    * This method is needed when creating additional handle objects to existing objects.
 204    * Owner is the Dali::Internal::CustomActor that owns the implementation of the custom actor
 205    * inside core. Creation of a handle to Dali public API Actor requires this pointer.
 206    * @return a pointer to the Actor implementation that owns this custom actor implementation
 207    */
 208   Internal::CustomActor* GetOwner() const;
 209
 210   /**
 211    * Called when ownership of the CustomActorImpl passed to a CustomActor.
 212    * @return True if the OnTouchEvent() callback is required.
 213    */
 214   bool RequiresTouchEvents() const;
 215
 216   /**
 217    * Called when ownership of the CustomActorImpl passed to a CustomActor.
 218    * @return True if the OnMouseWheelEvent() callback is required.
 219    */
 220   bool RequiresMouseWheelEvents() const;
 221
 222 private:
 223
 224   Internal::CustomActor* mOwner;
 225   bool mRequiresTouchEvents;
 226   bool mRequiresMouseWheelEvents;
 227 };
 228
 229 } // namespace Dali
 230
 231 /**
 232  * @}
 233  */
 234
 235 #endif // __DALI_CUSTOM_ACTOR_IMPL_H__