1 #ifndef __DALI_CUSTOM_ACTOR_IMPL_H__
2 #define __DALI_CUSTOM_ACTOR_IMPL_H__
5 * Copyright (c) 2014 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
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>
26 namespace Dali DALI_IMPORT_API
29 namespace Internal DALI_INTERNAL
37 class CustomActorImpl;
40 struct MouseWheelEvent;
44 * @brief Pointer to Dali::CustomActorImpl object.
46 typedef IntrusivePtr<CustomActorImpl> CustomActorImplPtr;
49 * @brief 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).
54 class DALI_IMPORT_API CustomActorImpl : public Dali::RefObject
59 * @brief Virtual destructor.
61 virtual ~CustomActorImpl();
64 * @brief Used by derived CustomActorImpl instances, to access the public Actor interface.
66 * @return A pointer to self, or an uninitialized pointer if the CustomActorImpl is not owned.
68 CustomActor Self() const;
71 * @brief Called after the actor has been connected to the stage.
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.
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.
79 * For the following actor tree, the callback order will be A, B, D, E, C, and finally F.
87 virtual void OnStageConnection() = 0;
90 * @brief Called after the actor has been disconnected from the stage.
92 * If an actor is disconnected it either has no parent, or is parented to a disconnected actor.
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.
97 * For the following actor tree, the callback order will be D, E, B, F, C, and finally A.
105 virtual void OnStageDisconnection() = 0;
108 * @brief Called after a child has been added to the owning actor.
110 * @param[in] child The child which has been added.
112 virtual void OnChildAdd(Actor& child) = 0;
115 * @brief Called after a child has been removed from the owning actor.
117 * @param[in] child The child being removed.
119 virtual void OnChildRemove(Actor& child) = 0;
122 * @brief Called when the owning actor property is set.
124 * @param[in] index The Property index that was set.
125 * @param[in] propertyValue The value to set.
127 virtual void OnPropertySet( Property::Index index, Property::Value propertyValue ) ;
130 * @brief Called when the owning actor's size is set e.g. using Actor::SetSize().
132 * @param[in] targetSize The target size. Note that this target size may not match the size returned via Actor::GetSize().
134 virtual void OnSizeSet(const Vector3& targetSize) = 0;
137 * @brief Called when the owning actor's size is animated e.g. using Animation::Resize().
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().
142 virtual void OnSizeAnimation(Animation& animation, const Vector3& targetSize) = 0;
145 * @brief Called after a touch-event is received by the owning actor.
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.
151 virtual bool OnTouchEvent(const TouchEvent& event) = 0;
154 * @brief Called after a key-event is received by the actor that has had its focus set.
156 * @param[in] event the Key Event
157 * @return True if the event should be consumed.
159 virtual bool OnKeyEvent(const KeyEvent& event) = 0;
162 * @brief Called after a mouse-wheel-event is received by the owning actor.
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.
168 virtual bool OnMouseWheelEvent(const MouseWheelEvent& event) = 0;
171 * @brief Called when this actor gains keyboard focus.
174 virtual void OnKeyInputFocusGained() = 0;
177 * @brief Called when this actor loses keyboard focus.
179 virtual void OnKeyInputFocusLost() = 0;
182 * @brief Called to find a child by an alias.
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.
190 virtual Dali::Actor GetChildByAlias(const std::string& actorAlias) = 0;
193 * Return the natural size of the actor
195 * @return The actor's natural size
197 virtual Vector3 GetNaturalSize() = 0;
199 protected: // For derived classes
202 * @brief Create a CustomActorImpl.
203 * @param[in] requiresTouchEvents True if the OnTouchEvent() callback is required.
205 CustomActorImpl(bool requiresTouchEvents);
208 * @brief Set whether the custom actor requires mouse wheel events.
209 * @param[in] requiresMouseWheelEvents True if the OnMouseWheelEvent() callback is required.
211 void SetRequiresMouseWheelEvents(bool requiresMouseWheelEvents);
213 public: // Not intended for application developers
216 * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor.
217 * @pre The CustomActorImpl is not already owned.
218 * @param[in] owner The owning object.
220 void Initialize(Internal::CustomActor& owner);
223 * @brief Get the owner.
225 * This method is needed when creating additional handle objects to existing objects.
226 * Owner is the Dali::Internal::CustomActor that owns the implementation of the custom actor
227 * inside core. Creation of a handle to Dali public API Actor requires this pointer.
228 * @return a pointer to the Actor implementation that owns this custom actor implementation
230 Internal::CustomActor* GetOwner() const;
233 * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor.
234 * @return True if the OnTouchEvent() callback is required.
236 bool RequiresTouchEvents() const;
239 * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor.
240 * @return True if the OnMouseWheelEvent() callback is required.
242 bool RequiresMouseWheelEvents() const;
246 Internal::CustomActor* mOwner; ///< Internal owner of this custom actor implementation
247 bool mRequiresTouchEvents; ///< Whether the OnTouchEvent() callback is required
248 bool mRequiresMouseWheelEvents; ///< Whether the OnMouseWheelEvent() callback is required
253 #endif // __DALI_CUSTOM_ACTOR_IMPL_H__