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