Merge "Add ALIASES for new DALi doxygen tagging rule to dali.doxy.in" into devel...
[platform/core/uifw/dali-toolkit.git] / dali-toolkit / public-api / controls / control.h
1 #ifndef __DALI_TOOLKIT_CONTROL_H__
2 #define __DALI_TOOLKIT_CONTROL_H__
3
4 /*
5  * Copyright (c) 2015 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 // EXTERNAL INCLUDES
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>
30
31 namespace Dali
32 {
33
34 namespace Toolkit
35 {
36
37 //Forward declarations.
38
39 namespace Internal
40 {
41 class Control;
42 }
43 /**
44  * @addtogroup dali_toolkit_controls
45  * @{
46  */
47
48 /**
49  * @brief Control is the base class for all controls.
50  *
51  * The implementation of the control must be supplied; see Internal::Control for more details.
52  * @see Internal::Control
53  *
54  * Signals
55  * | %Signal Name           | Method                                              |
56  * |------------------------|-----------------------------------------------------|
57  * | keyEvent               | @ref KeyEventSignal()                               |
58  * | keyInputFocusGained    | @ref KeyInputFocusGainedSignal()                    |
59  * | keyInputFocusLost      | @ref KeyInputFocusLostSignal()                      |
60  * | tapped                 | @ref GetTapGestureDetector().DetectedSignal()       |
61  * | panned                 | @ref GetPanGestureDetector().DetectedSignal()       |
62  * | pinched                | @ref GetPinchGestureDetector().DetectedSignal()     |
63  * | longPressed            | @ref GetLongPressGestureDetector().DetectedSignal() |
64  *
65  * Actions
66  * | %Action Name           | %Control method called                             |
67  * |------------------------|----------------------------------------------------|
68  * | accessibilityActivated | %OnAccessibilityActivated()                        |
69  */
70 class DALI_IMPORT_API Control : public CustomActor
71 {
72 public:
73
74   /**
75    * @brief The start and end property ranges for control.
76    */
77   enum PropertyRange
78   {
79     PROPERTY_START_INDEX = PROPERTY_REGISTRATION_START_INDEX,        ///< Start index is used by the property registration macro.
80     CONTROL_PROPERTY_START_INDEX = PROPERTY_START_INDEX,             ///< Start index of Control properties.
81     CONTROL_PROPERTY_END_INDEX = CONTROL_PROPERTY_START_INDEX + 1000 ///< Reserving 1000 property indices.
82   };
83
84   /**
85    * @brief An enumeration of properties belonging to the Control class.
86    */
87   struct Property
88   {
89     enum
90     {
91       STYLE_NAME = PROPERTY_START_INDEX, ///< name "styleName",        @see SetStyleName,                                                             type std::string
92       BACKGROUND_COLOR,                  ///< name "background-color", @deprecated DALi 1.1.3 mutually exclusive with BACKGROUND_IMAGE & BACKGROUND,  type Vector4
93       BACKGROUND_IMAGE,                  ///< name "background-image", @deprecated DALi 1.1.3 mutually exclusive with BACKGROUND_COLOR & BACKGROUND,  type Map
94       KEY_INPUT_FOCUS,                   ///< name "keyInputFocus",    @see SetKeyInputFocus,                                                         type bool
95       BACKGROUND,                        ///< name "background",       @since DALi 1.1.3 mutually exclusive with BACKGROUND_COLOR & BACKGROUND_IMAGE, type Map
96     };
97   };
98
99   /**
100    * @brief Describes the direction to move the keyboard focus towards.
101    */
102   struct KeyboardFocus
103   {
104     enum Direction
105     {
106       LEFT,   ///< Move keyboard focus towards the left direction
107       RIGHT,  ///< Move keyboard focus towards the right direction
108       UP,     ///< Move keyboard focus towards the up direction
109       DOWN    ///< Move keyboard focus towards the down direction
110     };
111   };
112
113   // Typedefs
114
115   /// @brief Key Event signal type;
116   typedef Signal<bool ( Control, const KeyEvent& ) > KeyEventSignalType;
117
118   /// @brief Key InputFocusType signal type;
119   typedef Signal<void ( Control ) > KeyInputFocusSignalType;
120
121 public: // Creation & Destruction
122
123   /**
124    * @brief Create a new instance of a Control.
125    *
126    * @return A handle to a new Control.
127    */
128   static Control New();
129
130   /**
131    * @brief Create an uninitialized Control handle.
132    *
133    * Only derived versions can be instantiated.  Calling member
134    * functions with an uninitialized Dali::Object is not allowed.
135    */
136   Control();
137
138   /**
139    * @brief Copy constructor.
140    *
141    * Creates another handle that points to the same real object
142    * @param[in] uiControl Handle to copy
143    */
144   Control(const Control& uiControl);
145
146   /**
147    * @brief Dali::Control is intended as a base class
148    *
149    * This is non-virtual since derived Handle types must not contain data or virtual methods.
150    */
151   ~Control();
152
153 public: // operators
154
155   /**
156    * @brief Assignment operator.
157    *
158    * Changes this handle to point to another real object
159    * @param[in] handle Object to assign this to
160    * @return reference to this
161    */
162   Control& operator=( const Control& handle );
163
164 public:
165
166   /**
167    * @brief Downcast an Object handle to Control.
168    *
169    * If handle points to a Control the downcast produces valid
170    * handle. If not the returned handle is left uninitialized.
171    *
172    * @param[in] handle Handle to an object
173    * @return handle to a Control or an uninitialized handle
174    */
175   static Control DownCast( BaseHandle handle );
176
177   // Key Input
178
179   /**
180    * @brief This sets the control to receive key events.
181    *
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.
186    */
187   void SetKeyInputFocus();
188
189   /**
190    * @brief Quries whether the control has key input focus.
191    *
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
200    */
201   bool HasKeyInputFocus();
202
203   /**
204    * @brief Once an actor is Set to receive key input focus this function is called to stop it receiving key events.
205    *
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.
208    */
209   void ClearKeyInputFocus();
210
211   // Gesture Detection
212
213   /**
214    * @brief Retrieves the pinch gesture detector of the control.
215    *
216    * @return The pinch gesture detector.
217    * @note Will return an empty handle if the control does not handle the gesture itself.
218    */
219   PinchGestureDetector GetPinchGestureDetector() const;
220
221   /**
222    * @brief Retrieves the pan gesture detector of the control.
223    *
224    * @return The pan gesture detector.
225    * @note Will return an empty handle if the control does not handle the gesture itself.
226    */
227   PanGestureDetector GetPanGestureDetector() const;
228
229   /**
230    * @brief Retrieves the tap gesture detector of the control.
231    *
232    * @return The tap gesture detector.
233    * @note Will return an empty handle if the control does not handle the gesture itself.
234    */
235   TapGestureDetector GetTapGestureDetector() const;
236
237   /**
238    * @brief Retrieves the long press gesture detector of the control.
239    *
240    * @return The long press gesture detector.
241    * @note Will return an empty handle if the control does not handle the gesture itself.
242    */
243   LongPressGestureDetector GetLongPressGestureDetector() const;
244
245   // Styling
246
247   /**
248    * @brief Sets the name of the style to be applied to the control.
249    *
250    * @param[in] styleName A string matching a style described in a stylesheet.
251    */
252   void SetStyleName( const std::string& styleName );
253
254   /**
255    * @brief Retrieves the name of the style to be applied to the control (if any).
256    *
257    * @return A string matching a style or an empty string.
258    */
259   const std::string& GetStyleName() const;
260
261   // Background
262
263   /**
264    * @brief Sets the background color of the control.
265    *
266    * @note if SetBackgroundImage is called later, this background color is removed.
267    *
268    * @param[in] color The required background color of the control
269    *
270    * @note The background color fully blends with the actor color.
271    */
272   void SetBackgroundColor( const Vector4& color );
273
274   /**
275    * @brief Retrieves the background color of the control.
276    *
277    * @deprecated DALi 1.1.3 API removed.
278    *
279    * @return The background color of the control.
280    */
281   Vector4 GetBackgroundColor() const;
282
283   /**
284    * @brief Sets an image as the background of the control.
285    *
286    * @param[in] image The image to set as the background.
287    */
288   void SetBackgroundImage( Image image );
289
290   /**
291    * @brief Clears the background.
292    */
293   void ClearBackground();
294
295   // Signals
296
297   /**
298    * @brief This signal is emitted when key event is received.
299    *
300    * A callback of the following type may be connected:
301    * @code
302    *   bool YourCallbackName(Control control, const KeyEvent& event);
303    * @endcode
304    * The return value of True, indicates that the event should be consumed.
305    * Otherwise the signal will be emitted on the next parent of the actor.
306    * @pre The Control has been initialized.
307    * @return The signal to connect to.
308    */
309   KeyEventSignalType& KeyEventSignal();
310
311   /**
312    * @brief This signal is emitted when the control gets Key Input Focus
313    *
314    * A callback of the following type may be connected:
315    * @code
316    *   bool YourCallbackName( Control control );
317    * @endcode
318    * The return value of True, indicates that the event should be consumed.
319    * Otherwise the signal will be emitted on the next parent of the actor.
320    * @pre The Control has been initialized.
321    * @return The signal to connect to.
322    */
323   KeyInputFocusSignalType& KeyInputFocusGainedSignal();
324
325   /**
326    * @brief This signal is emitted when the control loses Key Input Focus
327    * which could be due to it being gained by another Control or Actor or just cleared from
328    * this control as no longer required.
329    *
330    * A callback of the following type may be connected:
331    * @code
332    *   bool YourCallbackName( Control control );
333    * @endcode
334    * The return value of True, indicates that the event should be consumed.
335    * Otherwise the signal will be emitted on the next parent of the actor.
336    * @pre The Control has been initialized.
337    * @return The signal to connect to.
338    */
339   KeyInputFocusSignalType& KeyInputFocusLostSignal();
340
341 public: // Intended for control developers
342
343   /**
344    * @brief Create an initialised Control.
345    *
346    * @param[in] implementation The implementation for this control.
347    * @return A handle to a newly allocated Dali resource.
348    *
349    * @note Should NOT be called to create a handle from the implementation. As stated, this allocates a NEW Dali resource.
350    */
351   explicit Control(Internal::Control& implementation);
352
353   /**
354    * @brief This constructor is used by CustomActor within Dali core to create additional Control handles
355    * using an Internal CustomActor pointer.
356    *
357    * @param [in] internal A pointer to a newly allocated Dali resource
358    */
359   explicit Control(Dali::Internal::CustomActor* internal);
360
361 public: // Templates for Deriving Classes
362
363   /**
364    * @brief Template to allow deriving controls to DownCast handles to deriving handle classes.
365    *
366    * @tparam     T       The handle class
367    * @tparam     I       The implementation class
368    * @param[in]  handle  Handle to an object
369    * @return Handle to a class T or an uninitialized handle.
370    * @see DownCast(BaseHandle)
371    */
372   template<typename T, typename I>
373   DALI_INTERNAL static T DownCast( BaseHandle handle )
374   {
375     T result;
376
377     CustomActor custom = Dali::CustomActor::DownCast( handle );
378     if ( custom )
379     {
380       CustomActorImpl& customImpl = custom.GetImplementation();
381
382       I* impl = dynamic_cast<I*>(&customImpl);
383
384       if (impl)
385       {
386         result = T(customImpl.GetOwner());
387       }
388     }
389
390     return result;
391   }
392
393   /**
394    * @brief Template to allow deriving controls to verify whether the Internal::CustomActor* is actually an
395    * implementation of their class.
396    *
397    * @tparam     I         The implementation class
398    * @param[in]  internal  Pointer to the Internal::CustomActor
399    */
400   template<typename I>
401   DALI_INTERNAL void VerifyCustomActorPointer(Dali::Internal::CustomActor* internal)
402   {
403     // Can have a NULL pointer so we only need to check if the internal implementation is our class
404     // when there is a value.
405     if (internal)
406     {
407       DALI_ASSERT_DEBUG(dynamic_cast<I*>(&CustomActor(internal).GetImplementation()));
408     }
409   }
410
411 };
412
413 /**
414  * @}
415  */
416 } // namespace Toolkit
417
418 } // namespace Dali
419
420 #endif // __DALI_TOOLKIT_CONTROL_H__