Moved ControlImpl to Internal namespace & renamed to Control
[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
28 namespace Dali DALI_IMPORT_API
29 {
30
31 namespace Toolkit
32 {
33
34 namespace Internal DALI_INTERNAL
35 {
36 class StyleChangeProcessor;
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 This method should be overridden by deriving classes when
293    * they wish to be notified when the style changes.
294    *
295    * @param[in] change  Information denoting what has changed.
296    */
297   virtual void OnStyleChange(StyleChange change) { }
298
299   /**
300    * @brief Called whenever a pinch gesture is detected on this control.
301    *
302    * This can be overridden by deriving classes when pinch detection
303    * is enabled.  The default behaviour is to scale the control by the
304    * pinch scale.
305    *
306    * @note If overridden, then the default behaviour will not occur.
307    * @note Pinch detection should be enabled via EnableGestureDetection().
308    * @param[in]  pinch  The pinch gesture.
309    * @see EnableGestureDetection
310    */
311   virtual void OnPinch(PinchGesture pinch);
312
313   /**
314    * @brief Called whenever a pan gesture is detected on this control.
315    *
316    * This should be overridden by deriving classes when pan detection
317    * is enabled.
318    *
319    * @note There is no default behaviour with panning.
320    * @note Pan detection should be enabled via EnableGestureDetection().
321    * @param[in]  pan  The pan gesture.
322    * @see EnableGestureDetection
323    */
324   virtual void OnPan(PanGesture pan) { }
325
326   /**
327    * @brief Called whenever a tap gesture is detected on this control.
328    *
329    * This should be overridden by deriving classes when tap detection
330    * is enabled.
331    *
332    * @note There is no default behaviour with a tap.
333    * @note Tap detection should be enabled via EnableGestureDetection().
334    * @param[in]  tap  The tap gesture.
335    * @see EnableGestureDetection
336    */
337   virtual void OnTap(TapGesture tap) { }
338
339   /**
340    * @brief Called whenever a long press gesture is detected on this control.
341    *
342    * This should be overridden by deriving classes when long press
343    * detection is enabled.
344    *
345    * @note There is no default behaviour associated with a long press.
346    * @note Long press detection should be enabled via EnableGestureDetection().
347    * @param[in]  longPress  The long press gesture.
348    * @see EnableGestureDetection
349    */
350   virtual void OnLongPress(LongPressGesture longPress) { }
351
352   /**
353    * @brief Called whenever the control is added to the stage.
354    *
355    * Could be overridden by derived classes.
356    */
357   virtual void OnControlStageConnection() { }
358
359   /**
360    * @brief Called whenever the control is removed from the stage.
361    *
362    * Could be overridden by derived classes.
363    */
364   virtual void OnControlStageDisconnection() { }
365
366   /**
367    * @brief Called whenever an Actor is added to the control.
368    *
369    * Could be overridden by derived classes.
370    *
371    * @param[in] child The added actor.
372    */
373   virtual void OnControlChildAdd( Actor& child ) { }
374
375   /**
376    * @brief Called whenever an Actor is removed from the control.
377    *
378    * Could be overridden by derived classes.
379    *
380    * @param[in] child The removed actor.
381    */
382   virtual void OnControlChildRemove( Actor& child ) { }
383
384   /**
385    * @brief Called whenever the Control's size is set.
386    *
387    * Could be overridden by derived classes.
388    *
389    * @param[in] size The new size.
390    */
391   virtual void OnControlSizeSet( const Vector3& size ) { }
392
393   /**
394    * @brief Called after the Dali::Stage::SignalMessageQueueFlushed()
395    * signal is emitted if this control requested to be relaid-out.
396    *
397    * Should be overridden by derived classes if they need to layout
398    * actors differently after certain operations like add or remove
399    * actors, resize or after changing especific properties.
400    *
401    * @param[in]      size       The allocated size.
402    * @param[in,out]  container  The control should add actors to this container that it is not able
403    *                            to allocate a size for.
404    */
405   virtual void OnRelaidOut( Vector2 size, ActorSizeContainer& container );
406
407 private: // From CustomActorImpl, derived classes can override these.
408
409   /**
410    * @brief Sends a request to relayout this control.
411    *
412    * The control will be relaid out after the
413    * Dali::Stage::SignalMessageQueueFlushed() signal is emitted.
414    *
415    * It calls OnControlStageConnection() to notify derived classes.
416    *
417    * @see Dali::CustomActorImpl::OnStageConnection()
418    */
419   virtual void OnStageConnection();
420
421   /**
422    * @brief Calls OnControlStageDisconnection() to notify derived classed.
423    *
424    * @see Dali::CustomActorImpl::OnStageDisconnection()
425    */
426   virtual void OnStageDisconnection();
427
428   /**
429    * @brief Sends a request to relayout this control.
430    *
431    * The control will be relaid out after the
432    * Dali::Stage::SignalMessageQueueFlushed() signal is emitted.  It
433    * calls OnControlChildAdd() to notify derived classes.
434    *
435    * @note This method shouldn't be overridden by derived classes.
436    *
437    * @param[in] child The added actor.
438    *
439    * @see Dali::CustomActorImpl::OnChildAdd(Actor&)
440    */
441   virtual void OnChildAdd(Actor& child);
442
443   /**
444    * @brief Sends a request to relayout this control.
445    *
446    * The control will be relaid out after the
447    * Dali::Stage::SignalMessageQueueFlushed() signal is emitted.  It
448    * calls OnControlChildRemove() to notify derived classes.
449    *
450    * @note This method shouldn't be overridden by derived classes.
451    *
452    * @param[in] child The removed actor.
453    *
454    * @see Dali::CustomActorImpl::OnChildRemove(Actor&)
455    */
456   virtual void OnChildRemove(Actor& child);
457
458   /**
459    * @brief It stores the size set by size negotiation and relayout.
460    *
461    * It also keeps a backup of the size set through the Actor's API used in the size negotiation.
462    * It calls the OnControlSizeSet() to notify derived classes.
463    *
464    * @param[in] targetSize The new size.
465    *
466    * @see Dali::CustomActorImpl::OnSizeSet(const Vector3&)
467    */
468   virtual void OnSizeSet(const Vector3& targetSize);
469
470   /**
471    * @copydoc Dali::CustomActorImpl::OnSizeAnimation(Animation&, const Vector3&)
472    */
473   virtual void OnSizeAnimation(Animation& animation, const Vector3& targetSize);
474
475   /**
476    * @copydoc Dali::CustomActorImpl::OnTouchEvent(const TouchEvent&)
477    */
478   virtual bool OnTouchEvent(const TouchEvent& event);
479
480   /**
481    * @copydoc Dali::CustomActorImpl::OnKeyEvent(const KeyEvent&)
482    */
483   virtual bool OnKeyEvent(const KeyEvent& event);
484
485   /**
486    * @copydoc Dali::CustomActorImpl::OnMouseWheelEvent(const MouseWheelEvent&)
487    */
488   virtual bool OnMouseWheelEvent(const MouseWheelEvent& event);
489
490   /**
491    * @copydoc Dali::CustomActorImpl::OnKeyInputFocusGained()
492    */
493   virtual void OnKeyInputFocusGained();
494
495   /**
496    * @copydoc Dali::CustomActorImpl::OnKeyInputFocusLost()
497    */
498   virtual void OnKeyInputFocusLost();
499
500   /**
501    * @copydoc Dali::CustomActorImpl::GetChildByAlias(const std::string& actorAlias)
502    */
503   virtual Actor GetChildByAlias(const std::string& actorAlias);
504
505 private:
506
507   /**
508    * @brief Perform the activated action.
509    *
510    * @param[in] attributes The attributes to perfrom this action.
511    */
512   void DoActivatedAction(const PropertyValueContainer& attributes);
513
514 protected: // Construction
515
516   /**
517    * @brief Create a Control.
518    *
519    * @param[in] requiresTouchEvents True if the OnTouchEvent() callback is required.
520    */
521   Control(bool requiresTouchEvents);
522
523 public:
524
525   // Size negotiation
526
527   /**
528    * @copydoc Toolkit::Control::SetSizePolicy()
529    */
530   void SetSizePolicy( Toolkit::Control::SizePolicy widthPolicy, Toolkit::Control::SizePolicy heightPolicy );
531
532   /**
533    * @copydoc Toolkit::Control::GetSizePolicy()
534    */
535   void GetSizePolicy( Toolkit::Control::SizePolicy& widthPolicy, Toolkit::Control::SizePolicy& heightPolicy ) const;
536
537   /**
538    * @copydoc Toolkit::Control::SetMinimumSize()
539    */
540   void SetMinimumSize( const Vector3& size );
541
542   /**
543    * @copydoc Toolkit::Control::GetMinimumSize()
544    */
545   const Vector3& GetMinimumSize() const;
546
547   /**
548    * @copydoc Toolkit::Control::SetMaximumSize()
549    */
550   void SetMaximumSize( const Vector3& size );
551
552   /**
553    * @copydoc Toolkit::Control::GetMaximumSize()
554    */
555   const Vector3& GetMaximumSize() const;
556
557   /**
558    * @copydoc Toolkit::Control::GetNaturalSize()
559    */
560   virtual Vector3 GetNaturalSize();
561
562   /**
563    * @copydoc Toolkit::Control::GetHeightForWidth()
564    */
565   virtual float GetHeightForWidth( float width );
566
567   /**
568    * @copydoc Toolkit::Control::GetWidthForHeight()
569    */
570   virtual float GetWidthForHeight( float height );
571
572   /**
573    * @brief Retrieves the current Control's size.
574    *
575    * @return The control's size.
576    */
577   const Vector3& GetControlSize() const;
578
579   /**
580    * @brief Retrieves the Control's size set by the Application / Control.
581    *
582    * @return The control's size.
583    */
584   const Vector3& GetSizeSet() const;
585
586   //KeyInput
587
588   /**
589    * @copydoc Toolkit::Control::SetKeyInputFocus()
590    */
591   void SetKeyInputFocus();
592
593   /**
594    * @copydoc Toolkit::Control::HasKeyInputFocus()
595    */
596   bool HasKeyInputFocus();
597
598   /**
599    * @copydoc Toolkit::Control::ClearKeyInputFocus()
600    */
601   void ClearKeyInputFocus();
602
603   /**
604    * @copydoc ConnectionTrackerInterface::SignalConnected
605    */
606   virtual void SignalConnected( SlotObserver* slotObserver, CallbackBase* callback );
607
608   /**
609    * @copydoc ConnectionTrackerInterface::SignalDisconnected
610    */
611   virtual void SignalDisconnected( SlotObserver* slotObserver, CallbackBase* callback );
612
613   /**
614    * @copydoc ConnectionTrackerInterface::GetConnectionCount
615    */
616   virtual std::size_t GetConnectionCount() const;
617
618 protected:
619
620   /**
621    * @brief Sends a request to be relaid-out.
622    *
623    * This method is called from OnStageConnection(), OnChildAdd(),
624    * OnChildRemove(), SetSizePolicy(), SetMinimumSize() and
625    * SetMaximumSize().
626    *
627    * This method could also be called from derived classes every time
628    * a control's poperty change and it needs to be relaid-out.  After
629    * the Dali::Stage::SignalMessageQueueFlushed() is emitted a
630    * relayout process starts and all controls which called this method
631    * will be relaid-out.
632    *
633    * @note RelayoutRequest() only sends a request per Control before
634    * the Dali::Stage::SignalMessageQueueFlushed() signal is
635    * emitted. That means a control will be relaid-out only once, even
636    * if more than one request is sent between two consecutive signals.
637    */
638   void RelayoutRequest();
639
640   /**
641    * @brief Helper method for controls to Relayout their children if
642    * they do not know whether that child is a control or not.
643    *
644    * @param[in]      actor      The actor to relayout.
645    * @param[in]      size       The size to allocate to the actor.
646    * @param[in,out]  container  The container that holds actors that have not been allocated a size yet.
647    */
648   static void Relayout( Actor actor, Vector2 size, ActorSizeContainer& container );
649
650 private: // Used by the RelayoutController
651
652   /**
653    * @brief Called by the RelayoutController to negotiate the size of a control.
654    *
655    * The size allocated by the the algorithm is passed in which the
656    * control must adhere to.  A container is passed in as well which
657    * the control should populate with actors it has not / or does not
658    * need to handle in its size negotiation.
659    *
660    * @param[in]      size       The allocated size.
661    * @param[in,out]  container  The container that holds actors that are fed back into the
662    *                            RelayoutController algorithm.
663    */
664   void NegotiateSize( Vector2 size, ActorSizeContainer& container );
665
666 private:
667
668   /**
669    * @brief Called by NegotiateSize when the size to allocate to the control has been calculated.
670    *
671    * It calls the OnRelaidOut() method which can be overridden by derived classes.
672    *
673    * @param[in]      size       The allocated size.
674    * @param[in,out]  container  The control should add actors to this container that it is not able
675    *                            to allocate a size for.
676    */
677   void Relayout( Vector2 size, ActorSizeContainer& container );
678
679   /**
680    * @brief Used by the KeyInputFocusManager to emit key event signals.
681    *
682    * @param[in] event The key event.
683    * @return True if the event was consumed.
684    */
685   bool EmitKeyEventSignal(const KeyEvent& event);
686
687
688
689 private:
690
691   // Undefined
692   Control(const Control&);
693   Control& operator=(const Control&);
694
695   class Impl;
696   Impl *mImpl;
697
698   friend class Internal::StyleChangeProcessor;
699   friend class Internal::RelayoutControllerImpl;   ///< Relayout controller needs to call Relayout() which is private.
700   friend class Internal::KeyInputFocusManager;     ///< KeyInputFocusManager needs to call which is private.
701 };
702
703 } // namespace Internal
704
705 typedef Internal::Control ControlImpl; ///< @deprecated, Use Internal::Control
706
707 } // namespace Toolkit
708
709 } // namespace Dali
710
711 /**
712  * @}
713  */
714 #endif // __DALI_TOOLKIT_CONTROL_IMPL_H__