[dali_1.1.42] Merge branch 'devel/master'
[platform/core/uifw/dali-toolkit.git] / dali-toolkit / internal / controls / buttons / button-impl.h
1 #ifndef __DALI_TOOLKIT_INTERNAL_BUTTON_H__
2 #define __DALI_TOOLKIT_INTERNAL_BUTTON_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/adaptor-framework/timer.h>
23 #include <dali/public-api/animation/animation.h>
24
25 // INTERNAL INCLUDES
26 #include <dali-toolkit/public-api/controls/buttons/button.h>
27 #include <dali-toolkit/public-api/controls/control-impl.h>
28
29 namespace Dali
30 {
31
32 namespace Toolkit
33 {
34
35 class Button;
36
37 namespace Internal
38 {
39
40 /**
41  * Button is the base class implementation for all buttons.
42  */
43 class Button : public Control
44 {
45
46 protected:
47
48   /**
49    * Construct a new Button.
50    */
51   Button();
52
53   /**
54    * A reference counted object may only be deleted by calling Unreference()
55    */
56   virtual ~Button();
57
58 public:
59
60   /**
61    * @copydoc Dali::Toolkit::Button::SetDisabled
62    */
63   void SetDisabled( bool disabled );
64
65   /**
66    * @copydoc Dali::Toolkit::Button::IsDisabled
67    */
68   bool IsDisabled() const;
69
70   /**
71    * @copydoc Dali::Toolkit::Button::SetAutoRepeating
72    */
73   void SetAutoRepeating( bool autoRepeating );
74
75   /**
76    * @copydoc Dali::Toolkit::Button::IsAutoRepeating
77    */
78   bool IsAutoRepeating() const;
79
80   /**
81    * @copydoc Dali::Toolkit::Button::SetInitialAutoRepeatingDelay
82    */
83   void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
84
85   /**
86    * @copydoc Dali::Toolkit::Button::GetInitialAutoRepeatingDelay
87    */
88   float GetInitialAutoRepeatingDelay() const;
89
90   /**
91    * @copydoc Dali::Toolkit::Button::SetNextAutoRepeatingDelay
92    */
93   void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
94
95   /**
96    * @copydoc Dali::Toolkit::Button::GetNextAutoRepeatingDelay
97    */
98   float GetNextAutoRepeatingDelay() const;
99
100   /**
101    * @copydoc Dali::Toolkit::Button::SetTogglableButton
102    */
103   void SetTogglableButton( bool togglable );
104
105   /**
106    * @copydoc Dali::Toolkit::Button::IsTogglableButton
107    */
108   bool IsTogglableButton() const;
109
110   /**
111    * @copydoc Dali::Toolkit::Button::SetSelected
112    */
113   void SetSelected( bool selected );
114
115   /**
116    * @copydoc Dali::Toolkit::Button::IsSelected
117    */
118   bool IsSelected() const;
119
120   /**
121    * @copydoc Dali::Toolkit::Button::SetAnimationTime
122    */
123   void SetAnimationTime( float animationTime );
124
125   /**
126    * @copydoc Dali::Toolkit::Button::GetAnimationTime
127    */
128   float GetAnimationTime() const;
129
130   /**
131    * @copydoc Dali::Toolkit::Button::SetLabelText
132    */
133   void SetLabelText( const std::string& label );
134
135   /**
136    * @copydoc Dali::Toolkit::Button::GetLabelText
137    */
138   std::string GetLabelText() const;
139
140   /**
141    * @copydoc Dali::Toolkit::PushButton::SetUnselectedImage
142    */
143   void SetUnselectedImage( const std::string& filename );
144
145   /**
146    * @copydoc Dali::Toolkit::PushButton::SetSelectedImage
147    */
148   void SetSelectedImage( const std::string& filename );
149
150   /**
151    * @copydoc Dali::Toolkit::PushButton::SetBackgroundImage
152    */
153   void SetBackgroundImage( const std::string& filename );
154
155   /**
156    * @copydoc Dali::Toolkit::PushButton::SetSelectedBackgroundImage
157    */
158   void SetSelectedBackgroundImage( const std::string& filename );
159
160   /**
161    * @copydoc Dali::Toolkit::PushButton::SetDisabledImage
162    */
163   void SetDisabledImage( const std::string& filename );
164
165   /**
166    * @copydoc Dali::Toolkit::CheckBoxButton::SetDisabledSelectedImage
167    */
168   void SetDisabledSelectedImage( const std::string& filename );
169
170   /**
171    * @copydoc Dali::Toolkit::PushButton::SetDisabledBackgroundImage
172    */
173   void SetDisabledBackgroundImage( const std::string& filename );
174
175   /**
176    * @return The filename used for the button image.
177    */
178   std::string GetUnselectedImageFilename() const;
179
180   /**
181    * @return The filename used for the selected image.
182    */
183   std::string GetSelectedImageFilename() const;
184
185   /**
186    * @return The filename used for the background image.
187    */
188   std::string GetBackgroundImageFilename() const;
189
190   /**
191    * @return The filename used for the selected background image.
192    */
193   std::string GetSelectedBackgroundImageFilename() const;
194
195   /**
196    * @return The filename used for the disabled button image.
197    */
198   std::string GetDisabledImageFilename() const;
199
200   /**
201    * @return The filename used for the disabled selected image.
202    */
203   std::string GetDisabledSelectedImageFilename() const;
204
205   /**
206    * @return The filename used for the disabled background image.
207    */
208   std::string GetDisabledBackgroundImageFilename() const;
209
210   /**
211    * @brief Sets the specified properties on the button label.
212    * If the label does not exist yet, it is created.
213    * The derived buttons are notified if any properties are changed.
214    * @param[in] properties A Property::Map of key-value pairs of properties to set.
215    */
216   void ModifyLabel( const Property::Map& properties );
217
218   /**
219    * Performs actions as requested using the action name.
220    * @param[in] object The object on which to perform the action.
221    * @param[in] actionName The action to perform.
222    * @param[in] attributes The attributes with which to perfrom this action.
223    * @return true if action has been accepted by this control
224    */
225   static bool DoAction( BaseObject* object, const std::string& actionName, const Property::Map& attributes );
226
227 public: // Deprecated API
228
229   /**
230    * @copydoc Dali::Toolkit::Button::SetLabel( Actor label )
231    */
232   void SetLabel( Actor label );
233
234   /**
235    * @deprecated Sets the unselected image with an Actor.
236    * @param[in] image The Actor to use.
237    */
238   void SetButtonImage( Actor image );
239
240   /**
241    * @deprecated Sets the selected image with an Actor.
242    * @param[in] image The Actor to use.
243    */
244   void SetSelectedImage( Actor image );
245
246   /**
247    * @deprecated Sets the background image with an Actor.
248    * @param[in] image The Actor to use.
249    */
250   void SetBackgroundImage( Actor image );
251
252   /**
253    * @deprecated Sets the selected background image with an Actor.
254    * @param[in] image The Actor to use.
255    */
256   void SetSelectedBackgroundImage( Actor image );
257
258   /**
259    * @deprecated Sets the disabled image with an Actor.
260    * @param[in] image The Actor to use.
261    */
262   void SetDisabledImage( Actor image );
263
264   /**
265    * @deprecated Sets the disabled selected image with an Actor.
266    * @param[in] image The Actor to use.
267    */
268   void SetDisabledSelectedImage( Actor image );
269
270   /**
271    * @deprecated Sets the disabled background image with an Actor.
272    * @param[in] image The Actor to use.
273    */
274   void SetDisabledBackgroundImage( Actor image );
275
276   /**
277    * @copydoc Dali::Toolkit::Button::GetButtonImage
278    */
279   Actor GetButtonImage() const;
280
281   /**
282    * @copydoc Dali::Toolkit::Button::GetSelectedImage
283    */
284   Actor GetSelectedImage() const;
285
286 protected:
287
288   /**
289    * @return A reference to the label actor.
290    */
291   Actor& GetLabelActor();
292
293   /**
294    * @return A reference to the unselected button image.
295    */
296   Actor& GetUnselectedImage();
297
298   /**
299    * @return A reference to the selected image.
300    */
301   Actor& GetSelectedImage();
302
303   /**
304    * @return A reference to the background image.
305    */
306   Actor& GetBackgroundImage();
307
308   /**
309    * @return A reference to the selected background image.
310    */
311   Actor& GetSelectedBackgroundImage();
312
313   /**
314    * @return A reference to the disabled button image.
315    */
316   Actor& GetDisabledImage();
317
318   /**
319    * @return A reference to the disabled selected image.
320    */
321   Actor& GetDisabledSelectedImage();
322
323   /**
324    * @return A reference to the disabled background image.
325    */
326   Actor& GetDisabledBackgroundImage();
327
328 private:
329
330   /**
331    * Perform the click action to click the button.
332    * @param[in] attributes The attributes to perfrom this action.
333    * @return true if this control can perform action.
334    */
335   bool DoClickAction( const Property::Map& attributes );
336
337   /**
338    * This method is called when the label is set.
339    * @param[in] noPadding Used to bypass padding if the label is to be treated generically.
340    */
341   virtual void OnLabelSet( bool noPadding ) {}
342
343   /**
344    * This method is called when the unselected button image is set
345    */
346   virtual void OnUnselectedImageSet() {}
347
348   /**
349    * This method is called when the selected image is set
350    */
351   virtual void OnSelectedImageSet() {}
352
353   /**
354    * This method is called when the background image is set
355    */
356   virtual void OnBackgroundImageSet() {}
357
358   /**
359    * This method is called when the selected background image is set
360    */
361   virtual void OnSelectedBackgroundImageSet() {}
362
363   /**
364    * This method is called when the disabled button image is set
365    */
366   virtual void OnDisabledImageSet() {}
367
368   /**
369    * This method is called when the disabled selected image is set
370    */
371   virtual void OnDisabledSelectedImageSet() {}
372
373   /**
374    * This method is called when the disabled background image is set
375    */
376   virtual void OnDisabledBackgroundImageSet() {}
377
378   /**
379    * This method is called the button is down.
380    * Could be reimplemented in subclasses to provide specific behaviour.
381    */
382   virtual void OnButtonDown();
383
384   /**
385    * This method is called when the button is up.
386    * Could be reimplemented in subclasses to provide specific behaviour.
387    */
388   virtual void OnButtonUp();
389
390   /**
391    * This method is called when touch leaves the boundary of the button or several touch points are received.
392    * Could be reimplemented in subclasses to provide specific behaviour.
393    */
394   virtual void OnTouchPointLeave();
395
396   /**
397    * This method is called when the touch is interrupted.
398    * Could be reimplemented in subclasses to provide specific behaviour.
399    */
400   virtual void OnTouchPointInterrupted();
401
402   /**
403    * This method is called when the \e selected property is changed.
404    */
405   virtual void OnSelected() {}
406
407   /**
408    * This method is called when the \e disabled property is changed.
409    */
410   virtual void OnDisabled() {}
411
412   /**
413    * This method is called when the button is pressed.
414    */
415   virtual void OnPressed() {}
416
417   /**
418    * This method is called when the button is released.
419    */
420   virtual void OnReleased() {}
421
422 public:
423
424   /**
425    * @copydoc Dali::Toolkit::PushButton::PressedSignal()
426    */
427   Toolkit::Button::ButtonSignalType& PressedSignal();
428
429   /**
430    * @copydoc Dali::Toolkit::PushButton::ReleasedSignal()
431    */
432   Toolkit::Button::ButtonSignalType& ReleasedSignal();
433
434   /**
435    * @copydoc Dali::Toolkit::Button::ClickedSignal()
436    */
437   Toolkit::Button::ButtonSignalType& ClickedSignal();
438
439   /**
440    * @copydoc Dali::Toolkit::Button::StateChangedSignal()
441    */
442   Toolkit::Button::ButtonSignalType& StateChangedSignal();
443
444   /**
445    * Connects a callback function with the object's signals.
446    * @param[in] object The object providing the signal.
447    * @param[in] tracker Used to disconnect the signal.
448    * @param[in] signalName The signal to connect to.
449    * @param[in] functor A newly allocated FunctorDelegate.
450    * @return True if the signal was connected.
451    * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
452    */
453   static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
454
455   // Properties
456
457   /**
458    * Called when a property of an object of this type is set.
459    * @param[in] object The object whose property is set.
460    * @param[in] index The property index.
461    * @param[in] value The new property value.
462    */
463   static void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
464
465   /**
466    * Called to retrieve a property of an object of this type.
467    * @param[in] object The object whose property is to be retrieved.
468    * @param[in] index The property index.
469    * @return The current value of the property.
470    */
471   static Property::Value GetProperty( BaseObject* object, Property::Index propertyIndex );
472
473 protected: // From Control
474
475   /**
476    * @copydoc Toolkit::Control::OnInitialize()
477    * @note If overridden by deriving button classes, then an up-call to Button::OnInitialize MUST be made at the start.
478    */
479   virtual void OnInitialize();
480
481   /**
482    * @copydoc Toolkit::Control::OnAccessibilityActivated()
483    */
484   virtual bool OnAccessibilityActivated();
485
486   /**
487    * @copydoc Toolkit::Control::OnKeyboardEnter()
488    */
489   virtual bool OnKeyboardEnter();
490
491   /**
492    * @copydoc Toolkit::Control::OnStageDisconnection()
493    * @note If overridden by deriving button classes, then an up-call to Button::OnStageDisconnection MUST be made at the end.
494    */
495   void OnStageDisconnection();
496
497 private:
498
499   /**
500    * @brief Handler for touch data
501    * @param[in]  actor  The touched actor.
502    * @param[in]  touch  The touch info.
503    * @return true, if consumed, false otherwise.
504    */
505   bool OnTouch( Actor actor, const TouchData& touch );
506
507   /**
508    * Handler for tap events.
509    * We do not actually do anything when we receive a tap as the button handles tap event through
510    * the touch event system itself as it requires more than just tap handling (e.g. leave events).
511    * This stops any of our parents receiving a tap gesture when it occurs within our area.
512    * @param[in]  actor  The tapped actor.
513    * @param[in]  tap    The tap gesture.
514    */
515   void OnTap(Actor actor, const TapGesture& tap);
516
517   /**
518    * Sets up the autorepeating timer.
519    * @param[in] delay The delay time in seconds.
520    */
521   void SetUpTimer( float delay );
522
523   /**
524    * Slot called when Dali::Timer::SignalTick signal. Resets the autorepeating timer.
525    */
526   bool AutoRepeatingSlot();
527
528   /**
529    * Sets the button as selected or unselected.
530    * @param[in] selected \e selected property value.
531    * @param[in] emitSignal Emit a signal if this value is \e true.
532    */
533   void SetSelected( bool selected, bool emitSignal );
534
535   /**
536    * This method is called when the button is pressed.
537    */
538   void Pressed();
539
540   /**
541    * This method is called when the button is released.
542    */
543   void Released();
544
545   /**
546    * Used to perform common setup applied to images within button.
547    * This will replace the current image with the specifed one.
548    * @param[in]  actorToModify The image to replace.
549    * @param[out] newActor The new image to use.
550    */
551   void SetupContent( Actor& actorToModify, Actor newActor );
552
553   /**
554    * Sets the color of the unselected image.
555    * If no image exists, it is created.
556    * @param[in]  color The color to use.
557    */
558   void SetUnselectedColor( const Vector4& color );
559
560   /**
561    * Gets the unselected content color.
562    * @return     The currently used unselected color.
563    */
564   const Vector4 GetUnselectedColor() const;
565
566   /**
567    * Sets the color of the selected image.
568    * If no image exists, it is created.
569    * @param[in]  color The color to use.
570    */
571   void SetSelectedColor( const Vector4& color );
572
573   /**
574    * Gets the selected content color.
575    * @return     The currently used selected color.
576    */
577   const Vector4 GetSelectedColor() const;
578
579 protected:
580
581   enum ButtonState
582   {
583     ButtonUp,                                  ///< The button is up.
584     ButtonDown,                                ///< The button is down.
585   };
586
587   /**
588    * Button paint states.
589    */
590   enum PaintState
591   {
592     UnselectedState,              ///< The button is unselected.
593     SelectedState,                ///< The button is selected.
594     DisabledUnselectedState,      ///< The button is disabled and unselected.
595     DisabledSelectedState,        ///< The button is disabled and selected.
596   };
597
598   /**
599    * Enum to specify which decoration when getting and setting decorations.
600    */
601   enum DecorationState
602   {
603     UNSELECTED_DECORATION = 0,
604     SELECTED_DECORATION,
605     DECORATION_STATES
606   };
607
608   ButtonState GetState();
609   PaintState GetPaintState();
610   void SetDecoration( DecorationState state, Actor actor );
611   Actor& GetDecoration( DecorationState state );
612
613
614   /**
615    * Returns the animation to be used for transitioning creating the animation if needed.
616    * @return The initialised transition animation.
617    */
618   Dali::Animation GetTransitionAnimation();
619
620   /**
621    * Prepares the actor to be transitioned in.
622    * @param[in]  actor  The actor that will be transitioned in.
623    */
624   virtual void PrepareForTranstionIn( Actor actor ) {}
625
626   /**
627    * Prepares the actor to be transitioned in.
628    * @param[in]  actor  The actor that will be transitioned out.
629    */
630   virtual void PrepareForTranstionOut( Actor actor ) {}
631
632   /**
633    * Transitions the actor in, allowing derived classes to configure
634    * the GetTransitionAnimation() animation ready.
635    * Button is in charge of calling Dali::Animation::Play and so derived classes
636    * only need to add the animation.
637    */
638   virtual void OnTransitionIn( Actor actor ) {}
639
640   /**
641    * Transitions the actor out, allowing derived classes to configure
642    * the GetTransitionAnimation() animation ready.
643    * Button is in charge of calling Dali::Animation::Play and so derived classes
644    * only need to add the animation.
645    */
646   virtual void OnTransitionOut( Actor actor ) {}
647
648 private:
649
650   /**
651    * Starts the transition animation.
652    * Button::TransitionFinished is called when the animation finishes.
653    */
654   void StartTransitionAnimation();
655
656   /**
657    * This method stops all transition animations
658    */
659   void StopTransitionAnimation();
660
661   /**
662    * Called when the transition animation finishes.
663    */
664   void TransitionAnimationFinished( Dali::Animation& source );
665
666   /**
667    * Resets the Button to the base state for the current paint state.
668    * Any additionally inserted images needed for transitions that are
669    * no longer needed and the removed.
670    */
671   void ResetImageLayers();
672
673   /**
674    * Transitions out the actor
675    */
676   void TransitionOut( Actor actor );
677
678   /**
679    * Removes the actor from the button and prepares it to be transitioned out
680    */
681   void RemoveButtonImage( Actor& actor );
682
683   /**
684    * Finds the index of the actor.
685    * If the actor doesn't exist, return the last index + 1.
686    */
687   unsigned int FindChildIndex( Actor& actor );
688
689   /**
690    * Adds an actor to the hierarchy and prepares it to be transitioned.
691    * @param[in] actor The actor to add
692    */
693   void PrepareAddButtonImage( Actor& actor );
694
695   /**
696    * Adds an actor to the hierarchy and marks it to be transitioned.
697    * @param[in] actor The actor to add
698    */
699   void TransitionButtonImage( Actor& actor );
700
701   /**
702    * Adds an actor to the hierarchy.
703    * @param[in] actor The actor to add
704    */
705   void AddButtonImage( Actor& actor );
706
707   /**
708    * (Re)Adds the label (if exists) to the hierarchy (so it is always on top).
709    */
710   void ReAddLabel();
711
712   // Undefined
713   Button( const Button& );
714
715   // Undefined
716   Button& operator = ( const Button& );
717
718 private:
719
720   // Signals
721   Toolkit::Button::ButtonSignalType mPressedSignal;           ///< Signal emitted when the button is pressed.
722   Toolkit::Button::ButtonSignalType mReleasedSignal;          ///< Signal emitted when the button is released.
723   Toolkit::Button::ButtonSignalType mClickedSignal;           ///< Signal emitted when the button is clicked.
724   Toolkit::Button::ButtonSignalType mStateChangedSignal;      ///< Signal emitted when the button's state is changed.
725
726   Timer mAutoRepeatingTimer;                   ///< Timer used to implement the autorepeating property.
727
728   Actor mLabel;                                ///< Stores the button label.
729
730   Actor mDecoration[ DECORATION_STATES ];      ///< Stores the decorations for both selected and unselected states.
731
732   Actor mUnselectedContent;                    ///< Stores the unselected content.
733   Actor mSelectedContent;                      ///< Stores the selected content.
734   Actor mBackgroundContent;                    ///< Stores the background content.
735   Actor mSelectedBackgroundContent;            ///< Stores the selected background content.
736   Actor mDisabledContent;                      ///< Stores the disabled content.
737   Actor mDisabledSelectedContent;              ///< Stores the disabled selected content.
738   Actor mDisabledBackgroundContent;            ///< Stores the disabled background content.
739
740   Animation        mTransitionAnimation;       ///< Animation used in the state transitions.
741
742   TapGestureDetector mTapDetector;
743
744   Vector4          mUnselectedColor;           ///< Color to use for unselected content.
745   Vector4          mSelectedColor;             ///< Color to use for selected content.
746
747   bool             mDisabled;                  ///< Stores the disabled property.
748   bool             mAutoRepeating;             ///< Stores the autorepeating property.
749   bool             mTogglableButton;           ///< Stores the togglable property.
750   bool             mSelected;                  ///< Stores the selected state.
751   float            mInitialAutoRepeatingDelay; ///< Stores the initial autorepeating delay in seconds.
752   float            mNextAutoRepeatingDelay;    ///< Stores the next autorepeating delay in seconds.
753
754   float            mAnimationTime;             ///< The animation time.
755
756   // Actions
757   bool             mClickActionPerforming;
758
759   ButtonState      mState;                     ///< Stores the button state.
760   PaintState       mPaintState;                ///< Stores the paint state.
761 };
762
763 } // namespace Internal
764
765 // Helpers for public-api forwarding methods
766
767 inline Toolkit::Internal::Button& GetImplementation( Toolkit::Button& button )
768 {
769   DALI_ASSERT_ALWAYS( button );
770
771   Dali::RefObject& handle = button.GetImplementation();
772
773   return static_cast<Toolkit::Internal::Button&>( handle );
774 }
775
776 inline const Toolkit::Internal::Button& GetImplementation( const Toolkit::Button& button )
777 {
778   DALI_ASSERT_ALWAYS( button );
779
780   const Dali::RefObject& handle = button.GetImplementation();
781
782   return static_cast<const Toolkit::Internal::Button&>( handle );
783 }
784
785 } // namespace Toolkit
786
787 } // namespace Dali
788
789 #endif // __DALI_TOOLKIT_INTERNAL_BUTTON_H__