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