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;
41 struct MouseWheelEvent;
45 * @brief Pointer to Dali::CustomActorImpl object.
47 typedef IntrusivePtr<CustomActorImpl> CustomActorImplPtr;
50 * @brief CustomActorImpl is an abstract base class for custom control implementations.
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).
55 class DALI_IMPORT_API CustomActorImpl : public Dali::RefObject
60 * @brief Virtual destructor.
62 virtual ~CustomActorImpl();
65 * @brief Used by derived CustomActorImpl instances, to access the public Actor interface.
67 * @return A pointer to self, or an uninitialized pointer if the CustomActorImpl is not owned.
69 CustomActor Self() const;
72 * @brief Called after the actor has been connected to the stage.
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.
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.
80 * For the following actor tree, the callback order will be A, B, D, E, C, and finally F.
88 virtual void OnStageConnection() = 0;
91 * @brief Called after the actor has been disconnected from the stage.
93 * If an actor is disconnected it either has no parent, or is parented to a disconnected actor.
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.
98 * For the following actor tree, the callback order will be D, E, B, F, C, and finally A.
106 virtual void OnStageDisconnection() = 0;
109 * @brief Called after a child has been added to the owning actor.
111 * @param[in] child The child which has been added.
113 virtual void OnChildAdd(Actor& child) = 0;
116 * @brief Called after a child has been removed from the owning actor.
118 * @param[in] child The child being removed.
120 virtual void OnChildRemove(Actor& child) = 0;
123 * @brief Called when the owning actor property is set.
125 * @param[in] index The Property index that was set.
126 * @param[in] propertyValue The value to set.
128 virtual void OnPropertySet( Property::Index index, Property::Value propertyValue ) ;
131 * @brief Called when the owning actor's size is set e.g. using Actor::SetSize().
133 * @param[in] targetSize The target size. Note that this target size may not match the size returned via Actor::GetSize().
135 virtual void OnSizeSet(const Vector3& targetSize) = 0;
138 * @brief Called when the owning actor's size is animated e.g. using Animation::Resize().
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().
143 virtual void OnSizeAnimation(Animation& animation, const Vector3& targetSize) = 0;
146 * @brief Called after a touch-event is received by the owning actor.
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.
152 virtual bool OnTouchEvent(const TouchEvent& event) = 0;
155 * @brief Called after a hover-event is received by the owning actor.
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.
161 virtual bool OnHoverEvent(const HoverEvent& event) = 0;
164 * @brief Called after a key-event is received by the actor that has had its focus set.
166 * @param[in] event the Key Event
167 * @return True if the event should be consumed.
169 virtual bool OnKeyEvent(const KeyEvent& event) = 0;
172 * @brief Called after a mouse-wheel-event is received by the owning actor.
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.
178 virtual bool OnMouseWheelEvent(const MouseWheelEvent& event) = 0;
181 * @brief Called when this actor gains keyboard focus.
184 virtual void OnKeyInputFocusGained() = 0;
187 * @brief Called when this actor loses keyboard focus.
189 virtual void OnKeyInputFocusLost() = 0;
192 * @brief Called to find a child by an alias.
194 * If an alias for a child exists, return the child otherwise return an empty handle.
195 * For example 'previous' could return the last selected child.
196 * @pre The Actor has been initialized.
197 * @param[in] actorAlias the name of the actor to find
198 * @return A handle to the actor if found, or an empty handle if not.
200 virtual Dali::Actor GetChildByAlias(const std::string& actorAlias) = 0;
203 * Return the natural size of the actor
205 * @return The actor's natural size
207 virtual Vector3 GetNaturalSize() = 0;
209 protected: // For derived classes
212 * @brief Create a CustomActorImpl.
213 * @param[in] requiresTouchEvents True if the OnTouchEvent() callback is required.
215 CustomActorImpl(bool requiresTouchEvents);
218 * @brief Set whether the custom actor requires hover events.
219 * @param[in] requiresHoverEvents True if the OnHoverEvent() callback is required.
221 void SetRequiresHoverEvents(bool requiresHoverEvents);
224 * @brief Set whether the custom actor requires mouse wheel events.
225 * @param[in] requiresMouseWheelEvents True if the OnMouseWheelEvent() callback is required.
227 void SetRequiresMouseWheelEvents(bool requiresMouseWheelEvents);
229 public: // Not intended for application developers
232 * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor.
233 * @pre The CustomActorImpl is not already owned.
234 * @param[in] owner The owning object.
236 void Initialize(Internal::CustomActor& owner);
239 * @brief Get the owner.
241 * This method is needed when creating additional handle objects to existing objects.
242 * Owner is the Dali::Internal::CustomActor that owns the implementation of the custom actor
243 * inside core. Creation of a handle to Dali public API Actor requires this pointer.
244 * @return a pointer to the Actor implementation that owns this custom actor implementation
246 Internal::CustomActor* GetOwner() const;
249 * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor.
250 * @return True if the OnTouchEvent() callback is required.
252 bool RequiresTouchEvents() const;
255 * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor.
256 * @return True if the OnHoverEvent() callback is required.
258 bool RequiresHoverEvents() const;
261 * @brief Called when ownership of the CustomActorImpl is passed to a CustomActor.
262 * @return True if the OnMouseWheelEvent() callback is required.
264 bool RequiresMouseWheelEvents() const;
268 Internal::CustomActor* mOwner; ///< Internal owner of this custom actor implementation
269 bool mRequiresTouchEvents; ///< Whether the OnTouchEvent() callback is required
270 bool mRequiresHoverEvents; ///< Whether the OnHoverEvent() callback is required
271 bool mRequiresMouseWheelEvents; ///< Whether the OnMouseWheelEvent() callback is required
276 #endif // __DALI_CUSTOM_ACTOR_IMPL_H__