1a690e9b389685bdc3ddded6c72a89547f4a9e10
[platform/core/uifw/dali-toolkit.git] / capi / dali-toolkit / public-api / controls / control-impl.h
1 #ifndef __DALI_TOOLKIT_CONTROL_IMPL_H__
2 #define __DALI_TOOLKIT_CONTROL_IMPL_H__
3
4 //
5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
6 //
7 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
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  * @addtogroup CAPI_DALI_TOOLKIT_CONTROLS_MODULE
22  * @{
23  */
24
25 // INTERNAL INCLUDES
26 #include <dali-toolkit/public-api/controls/control.h>
27 #include <dali-toolkit/public-api/styling/style-manager.h>
28
29 namespace Dali DALI_IMPORT_API
30 {
31
32 namespace Toolkit
33 {
34
35 namespace Internal DALI_INTERNAL
36 {
37 class RelayoutControllerImpl;
38 class KeyInputFocusManager;
39 }
40
41 typedef std::pair< Actor, Vector2 > ActorSizePair;       ///< Pair of actor and size
42 typedef std::vector< ActorSizePair > ActorSizeContainer; ///< Container of actors and their sizes
43
44 namespace Internal
45 {
46
47 /**
48  * @brief This is the internal base class for all controls.
49  *
50  * It will provide some common functionality required by all controls.
51  * Implements ConnectionTrackerInterface so that signals (typically connected to member functions) will
52  * be disconnected automatically when the control is destroyed.
53  */
54 class DALI_IMPORT_API Control : public CustomActorImpl, public ConnectionTrackerInterface
55 {
56 public:
57
58   // Properties
59   enum
60   {
61     CONTROL_PROPERTY_START_INDEX = PROPERTY_REGISTRATION_START_INDEX,
62     CONTROL_PROPERTY_END_INDEX = CONTROL_PROPERTY_START_INDEX + 1000 ///< Reserving 1000 property indices
63   };
64
65   // Creation
66
67   /**
68    * @brief Create a new ControlImpl instance that does not require touch by default.
69    *
70    * If touch is required then the user can connect to this class' touch signal.
71    * @return A handle to the ConntrolImpl instance.
72    */
73   static Toolkit::Control New();
74
75   // Destruction
76
77   /**
78    * @brief Virtual destructor.
79    */
80   virtual ~Control();
81
82   // Actions
83
84   /**
85    * @brief This method should be overridden by deriving classes when they wish to be notified when they
86    * are activated.
87    */
88   virtual void OnActivated() { }
89
90   /**
91    * @brief This method should be overridden by deriving classes when they wish to respond the accessibility
92    * pan gesture.
93    *
94    * @param[in] gesture The pan gesture.
95    * @return true if the pan gesture has been consumed by this control
96    */
97   virtual bool OnAccessibilityPan(PanGesture gesture);
98
99   /**
100    * @brief This method should be overridden by deriving classes when they wish to respond
101    * the accessibility up and down action (i.e. value change of slider control).
102    *
103    * @param[in] isIncrease Whether the value should be increased or decreased
104    * @return true if the value changed action has been consumed by this control
105    */
106   virtual bool OnAccessibilityValueChange(bool isIncrease);
107
108   /**
109    * @brief Sets whether this control supports two dimensional
110    * keyboard navigation (i.e. whether it knows how to handle the
111    * keyboardn focus movement between its child actors).
112    *
113    * The control doesn't support it by default.
114    * @param[in] isSupported Whether this control supports two dimensional keyboard navigation.
115    */
116   void SetKeyboardNavigationSupport(bool isSupported);
117
118   /**
119    * @brief Gets whether this control supports two dimensional keyboard navigation.
120    *
121    * @return true if this control supports two dimensional keyboard navigation.
122    */
123   bool IsKeyboardNavigationSupported();
124
125   /**
126    * @brief Sets whether this control is a focus group for keyboard navigation.
127    *
128    * (i.e. the scope of keyboard focus movement
129    * can be limitied to its child actors). The control is not a focus group by default.
130    * @param[in] isFocusGroup Whether this control is set as a focus group for keyboard navigation.
131    */
132   void SetAsKeyboardFocusGroup(bool isFocusGroup);
133
134   /**
135    * @brief Gets whether this control is a focus group for keyboard navigation.
136    *
137    * @return true if this control is set as a focus group for keyboard navigation.
138    */
139   bool IsKeyboardFocusGroup();
140
141   /**
142    * @brief Gets the next keyboard focusable actor in this control towards the given direction.
143    *
144    * A control needs to override this function in order to support two dimensional keyboard navigation.
145    * @param[in] currentFocusedActor The current focused actor.
146    * @param[in] direction The direction to move the focus towards.
147    * @param[in] loopEnabled Whether the focus movement should be looped within the control.
148    * @return the next keyboard focusable actor in this control or an empty handle if no actor can be focused.
149    */
150   virtual Actor GetNextKeyboardFocusableActor(Actor currentFocusedActor, Toolkit::Control::KeyboardFocusNavigationDirection direction, bool loopEnabled);
151
152   /**
153    * @brief Informs this control that its chosen focusable actor will be focused.
154    *
155    * This allows the application to preform any actions if wishes
156    * before the focus is actually moved to the chosen actor.
157    *
158    * @param[in] commitedFocusableActor The commited focusable actor.
159    */
160   virtual void OnKeyboardFocusChangeCommitted(Actor commitedFocusableActor) { }
161
162   /**
163    * @brief Performs actions as requested using the action name.
164    *
165    * @param[in] object The object on which to perform the action.
166    * @param[in] actionName The action to perform.
167    * @param[in] attributes The attributes with which to perfrom this action.
168    * @return true if action has been accepted by this control
169    */
170   static bool DoAction(BaseObject* object, const std::string& actionName, const std::vector<Property::Value>& attributes);
171
172   /**
173    * @brief If deriving classes wish to fine tune pinch gesture
174    * detection then they can access the gesture detector through this
175    * API and modify the detection.
176    *
177    * @return The pinch gesture detector.
178    * @pre Pinch detection should have been enabled via EnableGestureDetection().
179    * @see EnableGestureDetection
180    */
181   PinchGestureDetector GetPinchGestureDetector() const;
182
183   /**
184    * @brief If deriving classes wish to fine tune pan gesture
185    * detection then they can access the gesture detector through this
186    * API and modify the detection.
187    *
188    * @return The pan gesture detector.
189    * @pre Pan detection should have been enabled via EnableGestureDetection().
190    * @see EnableGestureDetection
191    */
192   PanGestureDetector GetPanGestureDetector() const;
193
194   /**
195    * @brief If deriving classes wish to fine tune tap gesture
196    * detection then they can access the gesture detector through this
197    * API and modify the detection.
198    *
199    * @return The tap gesture detector.
200    * @pre Tap detection should have been enabled via EnableGestureDetection().
201    * @see EnableGestureDetection
202    */
203   TapGestureDetector GetTapGestureDetector() const;
204
205   /**
206    * @brief If deriving classes wish to fine tune long press gesture
207    * detection then they can access the gesture detector through this
208    * API and modify the detection.
209    *
210    * @return The long press gesture detector.
211    * @pre Long press detection should have been enabled via EnableGestureDetection().
212    * @see EnableGestureDetection
213    */
214   LongPressGestureDetector GetLongPressGestureDetector() const;
215
216   // Background
217
218   /**
219    * @copydoc Dali::Toolkit::Control::SetBackgroundColor
220    */
221   void SetBackgroundColor( const Vector4& color );
222
223   /**
224    * @copydoc Dali::Toolkit::Control::GetBackgroundColor
225    */
226   Vector4 GetBackgroundColor() const;
227
228   /**
229    * @copydoc Dali::Toolkit::Control::SetBackground
230    */
231   void SetBackground( Image image );
232
233   /**
234    * @copydoc Dali::Toolkit::Control::ClearBackground
235    */
236   void ClearBackground();
237
238   /**
239    * @copydoc Dali::Toolkit::Control::GetBackgroundActor
240    */
241   Actor GetBackgroundActor() const;
242
243 public:
244
245   /**
246    * @copydoc Dali::Toolkit::Control::KeyEventSignal()
247    */
248   Toolkit::Control::KeyEventSignalV2& KeyEventSignal();
249
250 protected:
251
252   // Construction
253
254   /**
255    * @brief Second phase initialization.
256    */
257   void Initialize();
258
259   // Gesture Detection
260
261   /**
262    * @brief Allows deriving classes to enable any of the gesture detectors that are available.
263    *
264    * Gesture detection can be enabled one at a time or in bitwise format as shown:
265    * @code
266    * EnableGestureDetection(Gesture::Type(Gesture::Pinch | Gesture::Tap | Gesture::Pan));
267    * @endcode
268    * @param[in]  type  The gesture type(s) to enable.
269    */
270   void EnableGestureDetection(Gesture::Type type);
271
272   /**
273    * @brief Allows deriving classes to disable any of the gesture detectors.
274    *
275    * Like EnableGestureDetection, this can also be called using bitwise or.
276    * @param[in]  type  The gesture type(s) to disable.
277    * @see EnableGetureDetection
278    */
279   void DisableGestureDetection(Gesture::Type type);
280
281 private: // For derived classes to override
282
283   /**
284    * @brief This method is called after the Control has been initialized.
285    *
286    * Derived classes should do any second phase initialization by
287    * overriding this method.
288    */
289   virtual void OnInitialize() { }
290
291   /**
292    * @brief Callback for when the theme changes.
293    */
294   virtual void OnThemeChange( Toolkit::StyleManager styleManager );
295
296   /**
297    * @brief Called whenever a pinch gesture is detected on this control.
298    *
299    * This can be overridden by deriving classes when pinch detection
300    * is enabled.  The default behaviour is to scale the control by the
301    * pinch scale.
302    *
303    * @note If overridden, then the default behaviour will not occur.
304    * @note Pinch detection should be enabled via EnableGestureDetection().
305    * @param[in]  pinch  The pinch gesture.
306    * @see EnableGestureDetection
307    */
308   virtual void OnPinch(PinchGesture pinch);
309
310   /**
311    * @brief Called whenever a pan gesture is detected on this control.
312    *
313    * This should be overridden by deriving classes when pan detection
314    * is enabled.
315    *
316    * @note There is no default behaviour with panning.
317    * @note Pan detection should be enabled via EnableGestureDetection().
318    * @param[in]  pan  The pan gesture.
319    * @see EnableGestureDetection
320    */
321   virtual void OnPan(PanGesture pan) { }
322
323   /**
324    * @brief Called whenever a tap gesture is detected on this control.
325    *
326    * This should be overridden by deriving classes when tap detection
327    * is enabled.
328    *
329    * @note There is no default behaviour with a tap.
330    * @note Tap detection should be enabled via EnableGestureDetection().
331    * @param[in]  tap  The tap gesture.
332    * @see EnableGestureDetection
333    */
334   virtual void OnTap(TapGesture tap) { }
335
336   /**
337    * @brief Called whenever a long press gesture is detected on this control.
338    *
339    * This should be overridden by deriving classes when long press
340    * detection is enabled.
341    *
342    * @note There is no default behaviour associated with a long press.
343    * @note Long press detection should be enabled via EnableGestureDetection().
344    * @param[in]  longPress  The long press gesture.
345    * @see EnableGestureDetection
346    */
347   virtual void OnLongPress(LongPressGesture longPress) { }
348
349   /**
350    * @brief Called whenever the control is added to the stage.
351    *
352    * Could be overridden by derived classes.
353    */
354   virtual void OnControlStageConnection() { }
355
356   /**
357    * @brief Called whenever the control is removed from the stage.
358    *
359    * Could be overridden by derived classes.
360    */
361   virtual void OnControlStageDisconnection() { }
362
363   /**
364    * @brief Called whenever an Actor is added to the control.
365    *
366    * Could be overridden by derived classes.
367    *
368    * @param[in] child The added actor.
369    */
370   virtual void OnControlChildAdd( Actor& child ) { }
371
372   /**
373    * @brief Called whenever an Actor is removed from the control.
374    *
375    * Could be overridden by derived classes.
376    *
377    * @param[in] child The removed actor.
378    */
379   virtual void OnControlChildRemove( Actor& child ) { }
380
381   /**
382    * @brief Called whenever the Control's size is set.
383    *
384    * Could be overridden by derived classes.
385    *
386    * @param[in] size The new size.
387    */
388   virtual void OnControlSizeSet( const Vector3& size ) { }
389
390   /**
391    * @brief Called after the Dali::Stage::SignalMessageQueueFlushed()
392    * signal is emitted if this control requested to be relaid-out.
393    *
394    * Should be overridden by derived classes if they need to layout
395    * actors differently after certain operations like add or remove
396    * actors, resize or after changing especific properties.
397    *
398    * @param[in]      size       The allocated size.
399    * @param[in,out]  container  The control should add actors to this container that it is not able
400    *                            to allocate a size for.
401    */
402   virtual void OnRelaidOut( Vector2 size, ActorSizeContainer& container );
403
404 private: // From CustomActorImpl, derived classes can override these.
405
406   /**
407    * @brief Sends a request to relayout this control.
408    *
409    * The control will be relaid out after the
410    * Dali::Stage::SignalMessageQueueFlushed() signal is emitted.
411    *
412    * It calls OnControlStageConnection() to notify derived classes.
413    *
414    * @see Dali::CustomActorImpl::OnStageConnection()
415    */
416   virtual void OnStageConnection();
417
418   /**
419    * @brief Calls OnControlStageDisconnection() to notify derived classed.
420    *
421    * @see Dali::CustomActorImpl::OnStageDisconnection()
422    */
423   virtual void OnStageDisconnection();
424
425   /**
426    * @brief Sends a request to relayout this control.
427    *
428    * The control will be relaid out after the
429    * Dali::Stage::SignalMessageQueueFlushed() signal is emitted.  It
430    * calls OnControlChildAdd() to notify derived classes.
431    *
432    * @note This method shouldn't be overridden by derived classes.
433    *
434    * @param[in] child The added actor.
435    *
436    * @see Dali::CustomActorImpl::OnChildAdd(Actor&)
437    */
438   virtual void OnChildAdd(Actor& child);
439
440   /**
441    * @brief Sends a request to relayout this control.
442    *
443    * The control will be relaid out after the
444    * Dali::Stage::SignalMessageQueueFlushed() signal is emitted.  It
445    * calls OnControlChildRemove() to notify derived classes.
446    *
447    * @note This method shouldn't be overridden by derived classes.
448    *
449    * @param[in] child The removed actor.
450    *
451    * @see Dali::CustomActorImpl::OnChildRemove(Actor&)
452    */
453   virtual void OnChildRemove(Actor& child);
454
455   /**
456    * @brief It stores the size set by size negotiation and relayout.
457    *
458    * It also keeps a backup of the size set through the Actor's API used in the size negotiation.
459    * It calls the OnControlSizeSet() to notify derived classes.
460    *
461    * @param[in] targetSize The new size.
462    *
463    * @see Dali::CustomActorImpl::OnSizeSet(const Vector3&)
464    */
465   virtual void OnSizeSet(const Vector3& targetSize);
466
467   /**
468    * @copydoc Dali::CustomActorImpl::OnSizeAnimation(Animation&, const Vector3&)
469    */
470   virtual void OnSizeAnimation(Animation& animation, const Vector3& targetSize);
471
472   /**
473    * @copydoc Dali::CustomActorImpl::OnTouchEvent(const TouchEvent&)
474    */
475   virtual bool OnTouchEvent(const TouchEvent& event);
476
477   /**
478    * @copydoc Dali::CustomActorImpl::OnKeyEvent(const KeyEvent&)
479    */
480   virtual bool OnKeyEvent(const KeyEvent& event);
481
482   /**
483    * @copydoc Dali::CustomActorImpl::OnMouseWheelEvent(const MouseWheelEvent&)
484    */
485   virtual bool OnMouseWheelEvent(const MouseWheelEvent& event);
486
487   /**
488    * @copydoc Dali::CustomActorImpl::OnKeyInputFocusGained()
489    */
490   virtual void OnKeyInputFocusGained();
491
492   /**
493    * @copydoc Dali::CustomActorImpl::OnKeyInputFocusLost()
494    */
495   virtual void OnKeyInputFocusLost();
496
497   /**
498    * @copydoc Dali::CustomActorImpl::GetChildByAlias(const std::string& actorAlias)
499    */
500   virtual Actor GetChildByAlias(const std::string& actorAlias);
501
502 private:
503
504   /**
505    * @brief Perform the activated action.
506    *
507    * @param[in] attributes The attributes to perfrom this action.
508    */
509   void DoActivatedAction(const PropertyValueContainer& attributes);
510
511 protected: // Construction
512
513   // Flags for the constructor
514   enum ControlBehaviour
515   {
516     CONTROL_BEHAVIOUR_NONE        = 0x0,
517     REQUIRES_TOUCH_EVENTS         = 0x1,     ///< True if the OnTouchEvent() callback is required.
518     REQUIRES_THEME_CHANGE_SIGNALS = 0x2      ///< True if this control should listen to theme change signals
519   };
520
521   /**
522    * @deprecated Use the constructor taking flags instead
523    * @brief Create a Control.
524    *
525    * @param[in] requiresTouchEvents True if the OnTouchEvent() callback is required.
526    */
527   Control(bool requiresTouchEvents);
528
529   /**
530    * @brief Create a Control.
531    *
532    * @param[in] behaviourFlags Behavioural flags from ControlBehaviour enum
533    */
534   Control(ControlBehaviour behaviourFlags);
535
536 public:
537
538   // Size negotiation
539
540   /**
541    * @copydoc Toolkit::Control::SetSizePolicy()
542    */
543   void SetSizePolicy( Toolkit::Control::SizePolicy widthPolicy, Toolkit::Control::SizePolicy heightPolicy );
544
545   /**
546    * @copydoc Toolkit::Control::GetSizePolicy()
547    */
548   void GetSizePolicy( Toolkit::Control::SizePolicy& widthPolicy, Toolkit::Control::SizePolicy& heightPolicy ) const;
549
550   /**
551    * @copydoc Toolkit::Control::SetMinimumSize()
552    */
553   void SetMinimumSize( const Vector3& size );
554
555   /**
556    * @copydoc Toolkit::Control::GetMinimumSize()
557    */
558   const Vector3& GetMinimumSize() const;
559
560   /**
561    * @copydoc Toolkit::Control::SetMaximumSize()
562    */
563   void SetMaximumSize( const Vector3& size );
564
565   /**
566    * @copydoc Toolkit::Control::GetMaximumSize()
567    */
568   const Vector3& GetMaximumSize() const;
569
570   /**
571    * @copydoc Toolkit::Control::GetNaturalSize()
572    */
573   virtual Vector3 GetNaturalSize();
574
575   /**
576    * @copydoc Toolkit::Control::GetHeightForWidth()
577    */
578   virtual float GetHeightForWidth( float width );
579
580   /**
581    * @copydoc Toolkit::Control::GetWidthForHeight()
582    */
583   virtual float GetWidthForHeight( float height );
584
585   /**
586    * @brief Retrieves the current Control's size.
587    *
588    * @return The control's size.
589    */
590   const Vector3& GetControlSize() const;
591
592   /**
593    * @brief Retrieves the Control's size set by the Application / Control.
594    *
595    * @return The control's size.
596    */
597   const Vector3& GetSizeSet() const;
598
599   //KeyInput
600
601   /**
602    * @copydoc Toolkit::Control::SetKeyInputFocus()
603    */
604   void SetKeyInputFocus();
605
606   /**
607    * @copydoc Toolkit::Control::HasKeyInputFocus()
608    */
609   bool HasKeyInputFocus();
610
611   /**
612    * @copydoc Toolkit::Control::ClearKeyInputFocus()
613    */
614   void ClearKeyInputFocus();
615
616   /**
617    * @copydoc ConnectionTrackerInterface::SignalConnected
618    */
619   virtual void SignalConnected( SlotObserver* slotObserver, CallbackBase* callback );
620
621   /**
622    * @copydoc ConnectionTrackerInterface::SignalDisconnected
623    */
624   virtual void SignalDisconnected( SlotObserver* slotObserver, CallbackBase* callback );
625
626   /**
627    * @copydoc ConnectionTrackerInterface::GetConnectionCount
628    */
629   virtual std::size_t GetConnectionCount() const;
630
631 protected:
632
633   /**
634    * @brief Sends a request to be relaid-out.
635    *
636    * This method is called from OnStageConnection(), OnChildAdd(),
637    * OnChildRemove(), SetSizePolicy(), SetMinimumSize() and
638    * SetMaximumSize().
639    *
640    * This method could also be called from derived classes every time
641    * a control's poperty change and it needs to be relaid-out.  After
642    * the Dali::Stage::SignalMessageQueueFlushed() is emitted a
643    * relayout process starts and all controls which called this method
644    * will be relaid-out.
645    *
646    * @note RelayoutRequest() only sends a request per Control before
647    * the Dali::Stage::SignalMessageQueueFlushed() signal is
648    * emitted. That means a control will be relaid-out only once, even
649    * if more than one request is sent between two consecutive signals.
650    */
651   void RelayoutRequest();
652
653   /**
654    * @brief Helper method for controls to Relayout their children if
655    * they do not know whether that child is a control or not.
656    *
657    * @param[in]      actor      The actor to relayout.
658    * @param[in]      size       The size to allocate to the actor.
659    * @param[in,out]  container  The container that holds actors that have not been allocated a size yet.
660    */
661   static void Relayout( Actor actor, Vector2 size, ActorSizeContainer& container );
662
663 private: // Used by the RelayoutController
664
665   /**
666    * @brief Called by the RelayoutController to negotiate the size of a control.
667    *
668    * The size allocated by the the algorithm is passed in which the
669    * control must adhere to.  A container is passed in as well which
670    * the control should populate with actors it has not / or does not
671    * need to handle in its size negotiation.
672    *
673    * @param[in]      size       The allocated size.
674    * @param[in,out]  container  The container that holds actors that are fed back into the
675    *                            RelayoutController algorithm.
676    */
677   void NegotiateSize( Vector2 size, ActorSizeContainer& container );
678
679 private:
680
681   /**
682    * @brief Called by NegotiateSize when the size to allocate to the control has been calculated.
683    *
684    * It calls the OnRelaidOut() method which can be overridden by derived classes.
685    *
686    * @param[in]      size       The allocated size.
687    * @param[in,out]  container  The control should add actors to this container that it is not able
688    *                            to allocate a size for.
689    */
690   void Relayout( Vector2 size, ActorSizeContainer& container );
691
692   /**
693    * @brief Used by the KeyInputFocusManager to emit key event signals.
694    *
695    * @param[in] event The key event.
696    * @return True if the event was consumed.
697    */
698   bool EmitKeyEventSignal(const KeyEvent& event);
699
700
701
702 private:
703
704   // Undefined
705   Control(const Control&);
706   Control& operator=(const Control&);
707
708   class Impl;
709   Impl *mImpl;
710
711   friend class Internal::RelayoutControllerImpl;   ///< Relayout controller needs to call Relayout() which is private.
712   friend class Internal::KeyInputFocusManager;     ///< KeyInputFocusManager needs to call which is private.
713 };
714
715 } // namespace Internal
716
717 typedef Internal::Control ControlImpl; ///< @deprecated, Use Internal::Control
718
719 } // namespace Toolkit
720
721 } // namespace Dali
722
723 /**
724  * @}
725  */
726 #endif // __DALI_TOOLKIT_CONTROL_IMPL_H__