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