8d4d7329c66378efbada493ddaf1647864397bdc
[platform/core/uifw/dali-toolkit.git] / base / dali-toolkit / public-api / controls / control.h
1 #ifndef __DALI_TOOLKIT_CONTROL_H__
2 #define __DALI_TOOLKIT_CONTROL_H__
3
4 /*
5  * Copyright (c) 2014 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 /**
45  * @brief Control is the base class for all controls.
46  *
47  * The implementation of the control must be supplied; see Internal::Control for more details.
48  * @see Internal::Control
49  */
50 class DALI_IMPORT_API Control : public CustomActor
51 {
52 public:
53
54   /// @name Properties
55   /** @{ */
56   static const Property::Index PROPERTY_BACKGROUND_COLOR;    ///< name "background-color",        @see SetBackgroundColor,        type VECTOR4
57   static const Property::Index PROPERTY_BACKGROUND;          ///< name "background",              @see SetBackground,             type MAP
58   static const Property::Index PROPERTY_WIDTH_POLICY;        ///< name "width-policy",            @see SetSizePolicy,             type STRING
59   static const Property::Index PROPERTY_HEIGHT_POLICY;       ///< name "height-policy",           @see SetSizePolicy,             type STRING
60   static const Property::Index PROPERTY_MINIMUM_SIZE;        ///< name "minimum-size",            @see SetMinimumSize,            type VECTOR3
61   static const Property::Index PROPERTY_MAXIMUM_SIZE;        ///< name "maximum-size",            @see SetMaximumSize,            type VECTOR3
62   static const Property::Index PROPERTY_KEY_INPUT_FOCUS;     ///< name "key-input-focus",         @see SetKeyInputFocus,          type BOOLEAN
63   /** @} */
64
65   /// @name Signals
66   /** @{ */
67   static const char* const SIGNAL_KEY_EVENT;                 ///< name "key-event"
68   static const char* const SIGNAL_TAPPED;                    ///< name "tapped"
69   static const char* const SIGNAL_PANNED;                    ///< name "panned"
70   static const char* const SIGNAL_PINCHED;                   ///< name "pinched"
71   static const char* const SIGNAL_LONG_PRESSED;              ///< name "long-pressed"
72   /** @} */
73
74   /// @name Actions
75   /** @{ */
76   static const char* const ACTION_CONTROL_ACTIVATED;         ///< name "control-activated"
77   /** @} */
78
79   /**
80    * @brief Describes how a control could be resized.
81    */
82   enum SizePolicy
83   {
84     Fixed,    ///< Size can't grow or shrink.
85     Minimum,  ///< Size can grow but shrink up to a minimum level.
86     Maximum,  ///< Size can shrink but grow up to a maximum value.
87     Range,    ///< Size can grow or shrink between a minimum and a maximum values.
88     Flexible, ///< Size can grow or shrink with no limits.
89   };
90
91   /**
92    * @brief Describes what a control should do when a contained actor/control exceeds the boundary of the control.
93    */
94   enum ExceedPolicy
95   {
96     Crop,   ///< Control's contents will be cropped.
97     Shrink, ///< Control's contents will be shrunk.
98     Scroll  ///< Control's contents will be added to a scroll.
99   };
100
101   /**
102    * @brief Describes the direction to move the keyboard focus towards.
103    */
104   enum KeyboardFocusNavigationDirection
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   // Typedefs
113
114   /// @brief Key Event signal type;
115   typedef SignalV2<bool ( Control, const KeyEvent& ) > KeyEventSignalV2;
116
117 public: // Creation & Destruction
118
119   /**
120    * @brief Create a new instance of a Control.
121    *
122    * @return A handle to a new Control.
123    */
124   static Control New();
125
126   /**
127    * @brief Create an uninitialized Control handle.
128    *
129    * Only derived versions can be instantiated.  Calling member
130    * functions with an uninitialized Dali::Object is not allowed.
131    */
132   Control();
133
134   /**
135    * @brief Copy constructor.
136    *
137    * Creates another handle that points to the same real object
138    * @param[in] uiControl Handle to copy
139    */
140   Control(const Control& uiControl);
141
142   /**
143    * @brief Dali::Control is intended as a base class
144    *
145    * This is non-virtual since derived Handle types must not contain data or virtual methods.
146    */
147   ~Control();
148
149 public: // operators
150
151   /**
152    * @brief Assignment operator.
153    *
154    * Changes this handle to point to another real object
155    * @param[in] handle Object to assign this to
156    * @return reference to this
157    */
158   Control& operator=( const Control& handle );
159
160 public:
161
162   /**
163    * @brief Downcast an Object handle to Control.
164    *
165    * If handle points to a Control the downcast produces valid
166    * handle. If not the returned handle is left uninitialized.
167    *
168    * @param[in] handle Handle to an object
169    * @return handle to a Control or an uninitialized handle
170    */
171   static Control DownCast( BaseHandle handle );
172
173   /**
174    * @brief Retrieve the Control implementation.
175    *
176    * @return The implementation.
177    */
178   Internal::Control& GetImplementation();
179
180   /**
181    * @brief Retrieve the Control implementation.
182    *
183    * @return The implementation.
184    */
185   const Internal::Control& GetImplementation() const;
186
187   // Size Negotiation
188
189   /**
190    * @brief Sets the size policies for the width and height dimensions.
191    *
192    * @param[in] widthPolicy Size policy for the width dimension.
193    * @param[in] heightPolicy Size policy for the height dimension.
194    */
195   void SetSizePolicy( SizePolicy widthPolicy, SizePolicy heightPolicy );
196
197   /**
198    * @brief Retrieves the size policies for the width and height dimensions.
199    *
200    * @param[out] widthPolicy Width's size policy.
201    * @param[out] heightPolicy Height's size policy.
202    */
203   void GetSizePolicy( SizePolicy& widthPolicy, SizePolicy& heightPolicy ) const;
204
205   /**
206    * @brief Sets the minimum size for the control.
207    *
208    * @param[in] size The minimum size.
209    */
210   void SetMinimumSize( const Vector3& size );
211
212   /**
213    * @brief Retrieves the minimum size.
214    *
215    * @return The minimum size.
216    */
217   const Vector3& GetMinimumSize() const;
218
219   /**
220    * @brief Sets the maximum size.
221    *
222    * @param[in] size The maximum size.
223    */
224   void SetMaximumSize( const Vector3& size );
225
226   /**
227    * @brief Retrieves the maximum size.
228    *
229    * @return The maximum size.
230    */
231   const Vector3& GetMaximumSize() const;
232
233   /**
234    * @brief Works out the natural size.
235    *
236    * Natural size is the control's size with any restriction.
237    *
238    * @return The natural size.
239    */
240   Vector3 GetNaturalSize();
241
242   /**
243    * @brief Works out the control's height for a given width.
244    *
245    * @param[in] width The control's width.
246    *
247    * @return The control's height for the given width.
248    */
249   float GetHeightForWidth( float width );
250
251   /**
252    * @brief Works out the control's width for a given height.
253    *
254    * @param[in] height The control's height.
255    *
256    * @return The control's width for the given height.
257    */
258   float GetWidthForHeight( float height );
259
260   // Key Input
261
262   /**
263    * @brief This sets the control to receive key events.
264    *
265    * The key event can originate from a virtual or physical keyboard.
266    * @pre The Control has been initialized.
267    * @pre The Control should be on the stage before setting keyboard focus.
268    * @return True if the control has foucs, False otherwise.
269    */
270   void SetKeyInputFocus();
271
272   /**
273    * @brief Quries whether the control has key input focus.
274    *
275    * 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.
276    * As the key input focus mechanism works like a stack, the top most control receives all the key events, and passes on the
277    * unhandled events to the controls below in the stack. A control in the stack will regain key input focus when there are no more
278    * controls above it in the focus stack.
279    * To query for the conrol which is on top of the focus stack use Dali::Toolkit::KeyInputFocusManager::GetCurrentKeyboardFocusActor()
280    * @pre The Control has been initialized.
281    * @pre The Control should be on the stage before setting keyboard focus.
282    * @return true if this control has keyboard input focus
283    */
284   bool HasKeyInputFocus();
285
286   /**
287    * @brief Once an actor is Set to receive key input focus this function is called to stop it receiving key events.
288    *
289    * A check is performed to ensure it was previously set, if this check fails then nothing is done.
290    * @pre The Actor has been initialized.
291    */
292   void ClearKeyInputFocus();
293
294   // Gesture Detection
295
296   /**
297    * @brief Retrieves the pinch gesture detector of the control.
298    *
299    * @return The pinch gesture detector.
300    * @note Will return an empty handle if the control does not handle the gesture itself.
301    */
302   PinchGestureDetector GetPinchGestureDetector() const;
303
304   /**
305    * @brief Retrieves the pan gesture detector of the control.
306    *
307    * @return The pan gesture detector.
308    * @note Will return an empty handle if the control does not handle the gesture itself.
309    */
310   PanGestureDetector GetPanGestureDetector() const;
311
312   /**
313    * @brief Retrieves the tap gesture detector of the control.
314    *
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    * @return The long press gesture detector.
324    * @note Will return an empty handle if the control does not handle the gesture itself.
325    */
326   LongPressGestureDetector GetLongPressGestureDetector() const;
327
328   // Background
329
330   /**
331    * @brief Sets the background color of the control.
332    *
333    * @param[in] color The required background color of the control
334    *
335    * @note The background color fully blends with the actor color.
336    */
337   void SetBackgroundColor( const Vector4& color );
338
339   /**
340    * @brief Retrieves the background color of the control.
341    *
342    * @return The background color of the control.
343    */
344   Vector4 GetBackgroundColor() const;
345
346   /**
347    * @brief Sets an image as the background of the control.
348    *
349    * The color of this image is blended with the background color @see SetBackgroundColor
350    *
351    * @param[in] image The image to set as the background.
352    */
353   void SetBackground( Image image );
354
355   /**
356    * @brief Clears the background.
357    */
358   void ClearBackground();
359
360   /**
361    * @brief Retrieves the actor used as the background for this control.
362    *
363    * @return The actor that used as the background for this control.
364    */
365   Actor GetBackgroundActor() const;
366
367   // Signals
368
369   /**
370    * @brief This signal is emitted when key event is received.
371    *
372    * A callback of the following type may be connected:
373    * @code
374    *   bool YourCallbackName(Control control, const KeyEvent& event);
375    * @endcode
376    * The return value of True, indicates that the touch event should be consumed.
377    * Otherwise the signal will be emitted on the next sensitive parent of the actor.
378    * @pre The Control has been initialized.
379    * @return The signal to connect to.
380    */
381   KeyEventSignalV2& KeyEventSignal();
382
383 public: // Intended for control developers (used implicitly)
384
385   /**
386    * @brief Create an initialised Control.
387    *
388    * @param[in] implementation The implementation for this control.
389    * @return A handle to a newly allocated Dali resource.
390    */
391   Control(Internal::Control& implementation);
392
393   /**
394    * @brief This constructor is used by CustomActor within Dali core to create additional Control handles
395    * using an Internal CustomActor pointer.
396    *
397    * @param [in] internal A pointer to a newly allocated Dali resource
398    */
399   Control(Dali::Internal::CustomActor* internal);
400
401 public: // Templates for Deriving Classes
402
403   /**
404    * @brief Template to allow deriving controls to DownCast handles to deriving handle classes.
405    *
406    * @tparam     T       The handle class
407    * @tparam     I       The implementation class
408    * @param[in]  handle  Handle to an object
409    * @return Handle to a class T or an uninitialized handle.
410    * @see DownCast(BaseHandle)
411    */
412   template<typename T, typename I>
413   DALI_INTERNAL static T DownCast( BaseHandle handle )
414   {
415     T result;
416
417     CustomActor custom = Dali::CustomActor::DownCast( handle );
418     if ( custom )
419     {
420       CustomActorImpl& customImpl = custom.GetImplementation();
421
422       I* impl = dynamic_cast<I*>(&customImpl);
423
424       if (impl)
425       {
426         result = T(customImpl.GetOwner());
427       }
428     }
429
430     return result;
431   }
432
433   /**
434    * @brief Template to allow deriving controls to verify whether the Internal::CustomActor* is actually an
435    * implementation of their class.
436    *
437    * @tparam     I         The implementation class
438    * @param[in]  internal  Pointer to the Internal::CustomActor
439    */
440   template<typename I>
441   DALI_INTERNAL void VerifyCustomActorPointer(Dali::Internal::CustomActor* internal)
442   {
443     // Can have a NULL pointer so we only need to check if the internal implementation is our class
444     // when there is a value.
445     if (internal)
446     {
447       DALI_ASSERT_DEBUG(dynamic_cast<I*>(&CustomActor(internal).GetImplementation()));
448     }
449   }
450
451 };
452
453 } // namespace Toolkit
454
455 } // namespace Dali
456
457 #endif // __DALI_TOOLKIT_CONTROL_H__