1 #ifndef __DALI_TOOLKIT_CONTROL_H__
2 #define __DALI_TOOLKIT_CONTROL_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/actors/custom-actor.h>
23 #include <dali/public-api/common/dali-common.h>
24 #include <dali/public-api/events/long-press-gesture-detector.h>
25 #include <dali/public-api/events/pan-gesture-detector.h>
26 #include <dali/public-api/events/pinch-gesture-detector.h>
27 #include <dali/public-api/events/tap-gesture-detector.h>
28 #include <dali/public-api/events/tap-gesture-detector.h>
29 #include <dali/public-api/images/image.h>
37 //Forward declarations.
45 * @brief Control is the base class for all controls.
47 * The implementation of the control must be supplied; see Internal::Control for more details.
48 * @see Internal::Control
51 * | %Signal Name | Method |
52 * |-------------------|-----------------------------------------------------|
53 * | key-event | @ref KeyEventSignal() |
54 * | tapped | @ref GetTapGestureDetector().DetectedSignal() |
55 * | panned | @ref GetPanGestureDetector().DetectedSignal() |
56 * | pinched | @ref GetPinchGestureDetector().DetectedSignal() |
57 * | long-pressed | @ref GetLongPressGestureDetector().DetectedSignal() |
60 * | %Action Name | %Control method called |
61 * |-------------------|-----------------------------------------------------|
62 * | control-activated | %OnActivated() |
64 class DALI_IMPORT_API Control : public CustomActor
69 * @brief The start and end property ranges for control.
73 PROPERTY_START_INDEX = PROPERTY_REGISTRATION_START_INDEX, ///< Start index is used by the property registration macro.
74 CONTROL_PROPERTY_START_INDEX = PROPERTY_START_INDEX, ///< Start index of Control properties.
75 CONTROL_PROPERTY_END_INDEX = CONTROL_PROPERTY_START_INDEX + 1000 ///< Reserving 1000 property indices.
79 * @brief An enumeration of properties belonging to the Control class.
85 BACKGROUND_COLOR = PROPERTY_START_INDEX, ///< name "background-color", @see SetBackgroundColor, type Vector4
86 BACKGROUND_IMAGE, ///< name "background-image", @see SetBackgroundImage, type Map
87 KEY_INPUT_FOCUS, ///< name "key-input-focus", @see SetKeyInputFocus, type bool
92 * @brief Describes the direction to move the keyboard focus towards.
94 enum KeyboardFocusNavigationDirection
96 Left, ///< Move keyboard focus towards the left direction
97 Right, ///< Move keyboard focus towards the right direction
98 Up, ///< Move keyboard focus towards the up direction
99 Down ///< Move keyboard focus towards the down direction
104 /// @brief Key Event signal type;
105 typedef Signal<bool ( Control, const KeyEvent& ) > KeyEventSignalType;
107 public: // Creation & Destruction
110 * @brief Create a new instance of a Control.
112 * @return A handle to a new Control.
114 static Control New();
117 * @brief Create an uninitialized Control handle.
119 * Only derived versions can be instantiated. Calling member
120 * functions with an uninitialized Dali::Object is not allowed.
125 * @brief Copy constructor.
127 * Creates another handle that points to the same real object
128 * @param[in] uiControl Handle to copy
130 Control(const Control& uiControl);
133 * @brief Dali::Control is intended as a base class
135 * This is non-virtual since derived Handle types must not contain data or virtual methods.
142 * @brief Assignment operator.
144 * Changes this handle to point to another real object
145 * @param[in] handle Object to assign this to
146 * @return reference to this
148 Control& operator=( const Control& handle );
153 * @brief Downcast an Object handle to Control.
155 * If handle points to a Control the downcast produces valid
156 * handle. If not the returned handle is left uninitialized.
158 * @param[in] handle Handle to an object
159 * @return handle to a Control or an uninitialized handle
161 static Control DownCast( BaseHandle handle );
164 * @brief Retrieve the Control implementation.
166 * @return The implementation.
168 Internal::Control& GetImplementation();
171 * @brief Retrieve the Control implementation.
173 * @return The implementation.
175 const Internal::Control& GetImplementation() const;
180 * @brief This sets the control to receive key events.
182 * The key event can originate from a virtual or physical keyboard.
183 * @pre The Control has been initialized.
184 * @pre The Control should be on the stage before setting keyboard focus.
185 * @return True if the control has foucs, False otherwise.
187 void SetKeyInputFocus();
190 * @brief Quries whether the control has key input focus.
192 * Note: The control can be set to have the focus and still not receive all the key events if another control has over ridden it.
193 * As the key input focus mechanism works like a stack, the top most control receives all the key events, and passes on the
194 * unhandled events to the controls below in the stack. A control in the stack will regain key input focus when there are no more
195 * controls above it in the focus stack.
196 * To query for the conrol which is on top of the focus stack use Dali::Toolkit::KeyInputFocusManager::GetCurrentKeyboardFocusActor()
197 * @pre The Control has been initialized.
198 * @pre The Control should be on the stage before setting keyboard focus.
199 * @return true if this control has keyboard input focus
201 bool HasKeyInputFocus();
204 * @brief Once an actor is Set to receive key input focus this function is called to stop it receiving key events.
206 * A check is performed to ensure it was previously set, if this check fails then nothing is done.
207 * @pre The Actor has been initialized.
209 void ClearKeyInputFocus();
214 * @brief Retrieves the pinch gesture detector of the control.
216 * @return The pinch gesture detector.
217 * @note Will return an empty handle if the control does not handle the gesture itself.
219 PinchGestureDetector GetPinchGestureDetector() const;
222 * @brief Retrieves the pan gesture detector of the control.
224 * @return The pan gesture detector.
225 * @note Will return an empty handle if the control does not handle the gesture itself.
227 PanGestureDetector GetPanGestureDetector() const;
230 * @brief Retrieves the tap gesture detector of the control.
232 * @return The tap gesture detector.
233 * @note Will return an empty handle if the control does not handle the gesture itself.
235 TapGestureDetector GetTapGestureDetector() const;
238 * @brief Retrieves the long press gesture detector of the control.
240 * @return The long press gesture detector.
241 * @note Will return an empty handle if the control does not handle the gesture itself.
243 LongPressGestureDetector GetLongPressGestureDetector() const;
248 * @brief Sets the background color of the control.
250 * @param[in] color The required background color of the control
252 * @note The background color fully blends with the actor color.
254 void SetBackgroundColor( const Vector4& color );
257 * @brief Retrieves the background color of the control.
259 * @return The background color of the control.
261 Vector4 GetBackgroundColor() const;
264 * @brief Sets an image as the background of the control.
266 * The color of this image is blended with the background color @see SetBackgroundColor
268 * @param[in] image The image to set as the background.
270 void SetBackgroundImage( Image image );
273 * @brief Clears the background.
275 void ClearBackground();
278 * @brief Retrieves the actor used as the background for this control.
280 * @return The actor that used as the background for this control.
282 Actor GetBackgroundActor() const;
287 * @brief This signal is emitted when key event is received.
289 * A callback of the following type may be connected:
291 * bool YourCallbackName(Control control, const KeyEvent& event);
293 * The return value of True, indicates that the touch event should be consumed.
294 * Otherwise the signal will be emitted on the next sensitive parent of the actor.
295 * @pre The Control has been initialized.
296 * @return The signal to connect to.
298 KeyEventSignalType& KeyEventSignal();
300 public: // Intended for control developers
303 * @brief Create an initialised Control.
305 * @param[in] implementation The implementation for this control.
306 * @return A handle to a newly allocated Dali resource.
308 * @note Should NOT be called to create a handle from the implementation. As stated, this allocates a NEW Dali resource.
310 explicit Control(Internal::Control& implementation);
313 * @brief This constructor is used by CustomActor within Dali core to create additional Control handles
314 * using an Internal CustomActor pointer.
316 * @param [in] internal A pointer to a newly allocated Dali resource
318 explicit Control(Dali::Internal::CustomActor* internal);
320 public: // Templates for Deriving Classes
323 * @brief Template to allow deriving controls to DownCast handles to deriving handle classes.
325 * @tparam T The handle class
326 * @tparam I The implementation class
327 * @param[in] handle Handle to an object
328 * @return Handle to a class T or an uninitialized handle.
329 * @see DownCast(BaseHandle)
331 template<typename T, typename I>
332 DALI_INTERNAL static T DownCast( BaseHandle handle )
336 CustomActor custom = Dali::CustomActor::DownCast( handle );
339 CustomActorImpl& customImpl = custom.GetImplementation();
341 I* impl = dynamic_cast<I*>(&customImpl);
345 result = T(customImpl.GetOwner());
353 * @brief Template to allow deriving controls to verify whether the Internal::CustomActor* is actually an
354 * implementation of their class.
356 * @tparam I The implementation class
357 * @param[in] internal Pointer to the Internal::CustomActor
360 DALI_INTERNAL void VerifyCustomActorPointer(Dali::Internal::CustomActor* internal)
362 // Can have a NULL pointer so we only need to check if the internal implementation is our class
363 // when there is a value.
366 DALI_ASSERT_DEBUG(dynamic_cast<I*>(&CustomActor(internal).GetImplementation()));
372 } // namespace Toolkit
376 #endif // __DALI_TOOLKIT_CONTROL_H__