Merge "Reduced size of control depth index ranges" into devel/master
[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) 2016 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  * @SINCE_1_0.0
53  * @see Internal::Control
54  *
55  * Signals
56  * | %Signal Name           | Method                                              |
57  * |------------------------|-----------------------------------------------------|
58  * | keyEvent               | @ref KeyEventSignal()                               |
59  * | keyInputFocusGained    | @ref KeyInputFocusGainedSignal()                    |
60  * | keyInputFocusLost      | @ref KeyInputFocusLostSignal()                      |
61  * | tapped                 | @ref GetTapGestureDetector().DetectedSignal()       |
62  * | panned                 | @ref GetPanGestureDetector().DetectedSignal()       |
63  * | pinched                | @ref GetPinchGestureDetector().DetectedSignal()     |
64  * | longPressed            | @ref GetLongPressGestureDetector().DetectedSignal() |
65  *
66  * Actions
67  * | %Action Name           | %Control method called                             |
68  * |------------------------|----------------------------------------------------|
69  * | accessibilityActivated | %OnAccessibilityActivated()                        |
70  */
71 class DALI_IMPORT_API Control : public CustomActor
72 {
73 public:
74
75   /**
76    * @brief Enumeration for the start and end property ranges for control.
77    * @SINCE_1_0.0
78    */
79   enum PropertyRange
80   {
81     PROPERTY_START_INDEX = PROPERTY_REGISTRATION_START_INDEX,        ///< Start index is used by the property registration macro. @SINCE_1_0.0
82     CONTROL_PROPERTY_START_INDEX = PROPERTY_START_INDEX,             ///< Start index of Control properties. @SINCE_1_0.0
83     CONTROL_PROPERTY_END_INDEX = CONTROL_PROPERTY_START_INDEX + 1000 ///< Reserving 1000 property indices. @SINCE_1_0.0
84   };
85
86   /**
87    * @brief Enumeration for the instance of properties belonging to the Control class.
88    * @SINCE_1_0.0
89    */
90   struct Property
91   {
92     /**
93      * @brief Enumeration for the instance of properties belonging to the Control class.
94      * @SINCE_1_0.0
95      */
96     enum
97     {
98       /**
99        * @brief name "styleName", type std::string.
100        * @SINCE_1_0.0
101        * @see SetStyleName
102        */
103       STYLE_NAME = PROPERTY_START_INDEX,
104       /**
105        * @DEPRECATED_1_1.3
106        * @brief name "backgroundColor", mutually exclusive with BACKGROUND_IMAGE & BACKGROUND,  type Vector4.
107        * @SINCE_1_0.0
108        * @see SetStyleName
109        */
110       BACKGROUND_COLOR,
111       /**
112        * @DEPRECATED_1_1.3
113        * @brief name "backgroundImage", mutually exclusive with BACKGROUND_COLOR & BACKGROUND,  type Map.
114        * @SINCE_1_0.0
115        */
116       BACKGROUND_IMAGE,
117       /**
118        * @brief name "keyInputFocus", type bool.
119        * @SINCE_1_0.0
120        * @see SetKeyInputFocus
121        */
122       KEY_INPUT_FOCUS,
123       /**
124        * @brief name "background", mutually exclusive with BACKGROUND_COLOR & BACKGROUND_IMAGE, type Map or std::string for URL.
125        * @SINCE_1_1.3
126        */
127       BACKGROUND,
128     };
129   };
130
131   /**
132    * @brief Describes the direction to move the keyboard focus towards.
133    * @SINCE_1_0.0
134    */
135   struct KeyboardFocus
136   {
137     /**
138      * @brief Keyboard focus direction.
139      * @SINCE_1_0.0
140      */
141     enum Direction
142     {
143       LEFT,   ///< Move keyboard focus towards the left direction @SINCE_1_0.0
144       RIGHT,  ///< Move keyboard focus towards the right direction @SINCE_1_0.0
145       UP,     ///< Move keyboard focus towards the up direction @SINCE_1_0.0
146       DOWN,    ///< Move keyboard focus towards the down direction @SINCE_1_0.0
147       PAGE_UP,     ///< Move keyboard focus towards the previous page direction @SINCE_1_2.14
148       PAGE_DOWN    ///< Move keyboard focus towards the next page direction @SINCE_1_2.14
149     };
150   };
151
152   // Typedefs
153
154   /// @brief Key Event signal type;
155   typedef Signal<bool ( Control, const KeyEvent& ) > KeyEventSignalType;
156
157   /// @brief Key InputFocusType signal type;
158   typedef Signal<void ( Control ) > KeyInputFocusSignalType;
159
160 public: // Creation & Destruction
161
162   /**
163    * @brief Creates a new instance of a Control.
164    *
165    * @SINCE_1_0.0
166    * @return A handle to a new Control
167    */
168   static Control New();
169
170   /**
171    * @brief Creates an uninitialized Control handle.
172    *
173    * Only derived versions can be instantiated.  Calling member
174    * functions with an uninitialized Dali::Object is not allowed.
175    * @SINCE_1_0.0
176    */
177   Control();
178
179   /**
180    * @brief Copy constructor.
181    *
182    * Creates another handle that points to the same real object.
183    * @SINCE_1_0.0
184    * @param[in] uiControl Handle to copy
185    */
186   Control(const Control& uiControl);
187
188   /**
189    * @brief Dali::Control is intended as a base class.
190    *
191    * This is non-virtual since derived Handle types must not contain data or virtual methods.
192    * @SINCE_1_0.0
193    */
194   ~Control();
195
196 public: // operators
197
198   /**
199    * @brief Assignment operator.
200    *
201    * Changes this handle to point to another real object.
202    * @SINCE_1_0.0
203    * @param[in] handle Object to assign this to
204    * @return Reference to this
205    */
206   Control& operator=( const Control& handle );
207
208 public:
209
210   /**
211    * @brief Downcasts a handle to Control handle.
212    *
213    * If handle points to a Control, the downcast produces valid handle.
214    * If not, the returned handle is left uninitialized.
215    *
216    * @SINCE_1_0.0
217    * @param[in] handle Handle to an object
218    * @return A handle to a Control or an uninitialized handle
219    */
220   static Control DownCast( BaseHandle handle );
221
222   // Key Input
223
224   /**
225    * @brief This sets the control to receive key events.
226    *
227    * The key event can originate from a virtual or physical keyboard.
228    * @SINCE_1_0.0
229    * @pre The Control has been initialized.
230    * @pre The Control should be on the stage before setting keyboard focus.
231    */
232   void SetKeyInputFocus();
233
234   /**
235    * @brief Quries whether the control has key input focus.
236    *
237    * @SINCE_1_0.0
238    * @return true if this control has keyboard input focus
239    * @pre The Control has been initialized.
240    * @pre The Control should be on the stage before setting keyboard focus.
241    * @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.
242    * As the key input focus mechanism works like a stack, the top most control receives all the key events, and passes on the
243    * unhandled events to the controls below in the stack. A control in the stack will regain key input focus when there are no more
244    * controls above it in the focus stack.
245    * To query for the control which is on top of the focus stack use Dali::Toolkit::KeyInputFocusManager::GetCurrentKeyboardFocusActor().
246    */
247   bool HasKeyInputFocus();
248
249   /**
250    * @brief Once an actor is Set to receive key input focus this function is called to stop it receiving key events.
251    *
252    * A check is performed to ensure it was previously set, if this check fails then nothing is done.
253    * @SINCE_1_0.0
254    * @pre The Actor has been initialized.
255    */
256   void ClearKeyInputFocus();
257
258   // Gesture Detection
259
260   /**
261    * @brief Retrieves the pinch gesture detector of the control.
262    *
263    * @SINCE_1_0.0
264    * @return The pinch gesture detector
265    * @note Will return an empty handle if the control does not handle the gesture itself.
266    */
267   PinchGestureDetector GetPinchGestureDetector() const;
268
269   /**
270    * @brief Retrieves the pan gesture detector of the control.
271    *
272    * @SINCE_1_0.0
273    * @return The pan gesture detector
274    * @note Will return an empty handle if the control does not handle the gesture itself.
275    */
276   PanGestureDetector GetPanGestureDetector() const;
277
278   /**
279    * @brief Retrieves the tap gesture detector of the control.
280    *
281    * @SINCE_1_0.0
282    * @return The tap gesture detector
283    * @note Will return an empty handle if the control does not handle the gesture itself.
284    */
285   TapGestureDetector GetTapGestureDetector() const;
286
287   /**
288    * @brief Retrieves the long press gesture detector of the control.
289    *
290    * @SINCE_1_0.0
291    * @return The long press gesture detector
292    * @note Will return an empty handle if the control does not handle the gesture itself.
293    */
294   LongPressGestureDetector GetLongPressGestureDetector() const;
295
296   // Styling
297
298   /**
299    * @brief Sets the name of the style to be applied to the control.
300    *
301    * @SINCE_1_0.0
302    * @param[in] styleName A string matching a style described in a stylesheet
303    */
304   void SetStyleName( const std::string& styleName );
305
306   /**
307    * @brief Retrieves the name of the style to be applied to the control (if any).
308    * @SINCE_1_0.0
309    * @return A string matching a style, or an empty string
310    */
311   const std::string& GetStyleName() const;
312
313   // Background
314
315   /**
316    * @brief Sets the background color of the control.
317    *
318    * @SINCE_1_0.0
319    * @param[in] color The required background color of the control
320    *
321    * @note If SetBackgroundImage is called later, this background color is removed.
322    *
323    * @note The background color fully blends with the actor color.
324    */
325   void SetBackgroundColor( const Vector4& color );
326
327   /**
328    * @DEPRECATED_1_1.3
329    *
330    * @brief Retrieves the background color of the control.
331    *
332    * @SINCE_1_0.0
333    * @return The background color of the control
334    */
335   Vector4 GetBackgroundColor() const DALI_DEPRECATED_API;
336
337   /**
338    * @DEPRECATED_1_2_8, use Property::BACKGROUND instead
339    *
340    * @brief Sets an image as the background of the control.
341    *
342    * @SINCE_1_0.0
343    * @param[in] image The image to set as the background
344    */
345   void SetBackgroundImage( Image image ) DALI_DEPRECATED_API;
346
347   /**
348    * @brief Clears the background.
349    * @SINCE_1_0.0
350    */
351   void ClearBackground();
352
353   // Signals
354
355   /**
356    * @brief This signal is emitted when key event is received.
357    *
358    * A callback of the following type may be connected:
359    * @code
360    *   bool YourCallbackName(Control control, const KeyEvent& event);
361    * @endcode
362    * The return value of True, indicates that the event should be consumed.
363    * Otherwise the signal will be emitted on the next parent of the actor.
364    * @SINCE_1_0.0
365    * @return The signal to connect to
366    * @pre The Control has been initialized.
367    */
368   KeyEventSignalType& KeyEventSignal();
369
370   /**
371    * @brief This signal is emitted when the control gets Key Input Focus.
372    *
373    * A callback of the following type may be connected:
374    * @code
375    *   bool YourCallbackName( Control control );
376    * @endcode
377    * The return value of True, indicates that the event should be consumed.
378    * Otherwise the signal will be emitted on the next parent of the actor.
379    * @SINCE_1_0.0
380    * @return The signal to connect to
381    * @pre The Control has been initialized.
382    */
383   KeyInputFocusSignalType& KeyInputFocusGainedSignal();
384
385   /**
386    * @brief This signal is emitted when the control loses Key Input Focus
387    * which could be due to it being gained by another Control or Actor or just cleared from
388    * this control as no longer required.
389    *
390    * A callback of the following type may be connected:
391    * @code
392    *   bool YourCallbackName( Control control );
393    * @endcode
394    * The return value of True, indicates that the event should be consumed.
395    * Otherwise the signal will be emitted on the next parent of the actor.
396    * @SINCE_1_0.0
397    * @return The signal to connect to
398    * @pre The Control has been initialized.
399    */
400   KeyInputFocusSignalType& KeyInputFocusLostSignal();
401
402 public: // Intended for control developers
403
404   /**
405    * @brief Creates an initialized Control.
406    *
407    * @SINCE_1_0.0
408    * @param[in] implementation The implementation for this control
409    * @return A handle to a newly allocated Dali resource
410    * @note Should NOT be called to create a handle from the implementation. As stated, this allocates a NEW Dali resource.
411    */
412   explicit Control(Internal::Control& implementation);
413
414   /**
415    * @brief This constructor is used by CustomActor within Dali core to create additional Control handles
416    * using an Internal CustomActor pointer.
417    *
418    * @SINCE_1_0.0
419    * @param[in] internal A pointer to a newly allocated Dali resource
420    */
421   explicit Control(Dali::Internal::CustomActor* internal);
422
423 public: // Templates for Deriving Classes
424
425   /**
426    * @brief Template to allow deriving controls to DownCast handles to deriving handle classes.
427    *
428    * @tparam     T      The handle class
429    * @tparam     I      The implementation class
430    * @SINCE_1_0.0
431    * @param[in] handle Handle to an object
432    * @return Handle to a class T or an uninitialized handle
433    * @see DownCast(BaseHandle)
434    */
435   template<typename T, typename I>
436   DALI_INTERNAL static T DownCast( BaseHandle handle )
437   {
438     T result;
439
440     CustomActor custom = Dali::CustomActor::DownCast( handle );
441     if ( custom )
442     {
443       CustomActorImpl& customImpl = custom.GetImplementation();
444
445       I* impl = dynamic_cast<I*>(&customImpl);
446
447       if (impl)
448       {
449         result = T(customImpl.GetOwner());
450       }
451     }
452
453     return result;
454   }
455
456   /**
457    * @brief Template to allow deriving controls to verify whether the Internal::CustomActor* is actually an
458    * implementation of their class.
459    *
460    * @tparam     I       The implementation class
461    * @SINCE_1_0.0
462    * @param[in] internal Pointer to the Internal::CustomActor
463    */
464   template<typename I>
465   DALI_INTERNAL void VerifyCustomActorPointer(Dali::Internal::CustomActor* internal)
466   {
467     // Can have a NULL pointer so we only need to check if the internal implementation is our class
468     // when there is a value.
469     if (internal)
470     {
471       DALI_ASSERT_DEBUG(dynamic_cast<I*>(&CustomActor(internal).GetImplementation()));
472     }
473   }
474
475 };
476
477 /**
478  * @}
479  */
480 } // namespace Toolkit
481
482 } // namespace Dali
483
484 #endif // __DALI_TOOLKIT_CONTROL_H__