2ff121d219a15a4a6f2bfcc6784fcecd301e2a59
[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 after the button initialization.
339    * Could be reimplemented in subclasses to provide specific behaviour.
340    */
341   virtual void OnButtonInitialize() { }
342
343   /**
344    * This method is called when the label is set.
345    * @param[in] noPadding Used to bypass padding if the label is to be treated generically.
346    */
347   virtual void OnLabelSet( bool noPadding ) {}
348
349   /**
350    * This method is called when the unselected button image is set
351    */
352   virtual void OnUnselectedImageSet() {}
353
354   /**
355    * This method is called when the selected image is set
356    */
357   virtual void OnSelectedImageSet() {}
358
359   /**
360    * This method is called when the background image is set
361    */
362   virtual void OnBackgroundImageSet() {}
363
364   /**
365    * This method is called when the selected background image is set
366    */
367   virtual void OnSelectedBackgroundImageSet() {}
368
369   /**
370    * This method is called when the disabled button image is set
371    */
372   virtual void OnDisabledImageSet() {}
373
374   /**
375    * This method is called when the disabled selected image is set
376    */
377   virtual void OnDisabledSelectedImageSet() {}
378
379   /**
380    * This method is called when the disabled background image is set
381    */
382   virtual void OnDisabledBackgroundImageSet() {}
383
384   /**
385    * This method is called from the OnTouchEvent method when the button is down.
386    * Could be reimplemented in subclasses to provide specific behaviour.
387    */
388   virtual void OnButtonDown();
389
390   /**
391    * This method is called from the OnTouchEvent method when the button is up.
392    * Could be reimplemented in subclasses to provide specific behaviour.
393    */
394   virtual void OnButtonUp();
395
396   /**
397    * This method is called from the OnTouchEvent method when the touch point leaves the boundary of the button or
398    * more than one touch points are received.
399    * Could be reimplemented in subclasses to provide specific behaviour.
400    */
401   virtual void OnTouchPointLeave();
402
403   /**
404    * This method is called from the OnTouchEvent method when the touch point is interrupted.
405    * Could be reimplemented in subclasses to provide specific behaviour.
406    */
407   virtual void OnTouchPointInterrupted();
408
409   /**
410    * This method is called when the button is removed from the stage.
411    * Could be reimplemented in subclasses to provide specific behaviour.
412    */
413   virtual void OnButtonStageDisconnection();
414
415   /**
416    * This method is called when the \e selected property is changed.
417    */
418   virtual void OnSelected() {}
419
420   /**
421    * This method is called when the \e disabled property is changed.
422    */
423   virtual void OnDisabled() {}
424
425   /**
426    * This method is called when the button is pressed.
427    */
428   virtual void OnPressed() {}
429
430   /**
431    * This method is called when the button is released.
432    */
433   virtual void OnReleased() {}
434
435 public:
436
437   /**
438    * @copydoc Dali::Toolkit::PushButton::PressedSignal()
439    */
440   Toolkit::Button::ButtonSignalType& PressedSignal();
441
442   /**
443    * @copydoc Dali::Toolkit::PushButton::ReleasedSignal()
444    */
445   Toolkit::Button::ButtonSignalType& ReleasedSignal();
446
447   /**
448    * @copydoc Dali::Toolkit::Button::ClickedSignal()
449    */
450   Toolkit::Button::ButtonSignalType& ClickedSignal();
451
452   /**
453    * @copydoc Dali::Toolkit::Button::StateChangedSignal()
454    */
455   Toolkit::Button::ButtonSignalType& StateChangedSignal();
456
457   /**
458    * Connects a callback function with the object's signals.
459    * @param[in] object The object providing the signal.
460    * @param[in] tracker Used to disconnect the signal.
461    * @param[in] signalName The signal to connect to.
462    * @param[in] functor A newly allocated FunctorDelegate.
463    * @return True if the signal was connected.
464    * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
465    */
466   static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
467
468   // Properties
469
470   /**
471    * Called when a property of an object of this type is set.
472    * @param[in] object The object whose property is set.
473    * @param[in] index The property index.
474    * @param[in] value The new property value.
475    */
476   static void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
477
478   /**
479    * Called to retrieve a property of an object of this type.
480    * @param[in] object The object whose property is to be retrieved.
481    * @param[in] index The property index.
482    * @return The current value of the property.
483    */
484   static Property::Value GetProperty( BaseObject* object, Property::Index propertyIndex );
485
486 protected: // From CustomActorImpl
487
488   /**
489    * @copydoc Dali::CustomActorImpl::OnTouchEvent( const TouchEvent& event )
490    */
491   virtual bool OnTouchEvent( const TouchEvent& event );
492
493 private: // From Control
494
495   /**
496    * @copydoc Toolkit::Control::OnInitialize()
497    */
498   virtual void OnInitialize();
499
500   /**
501    * @copydoc Toolkit::Control::OnAccessibilityActivated()
502    */
503   virtual bool OnAccessibilityActivated();
504
505   /**
506    * @copydoc Toolkit::Control::OnKeyboardEnter()
507    */
508   virtual bool OnKeyboardEnter();
509
510   /**
511    * Callback received when the button is disconnected from the stage.
512    * It resets the button status.
513    */
514   void OnStageDisconnection();
515
516 private:
517
518   /**
519    * Handler for tap events.
520    * We do not actually do anything when we receive a tap as the button handles tap event through
521    * the touch event system itself as it requires more than just tap handling (e.g. leave events).
522    * This stops any of our parents receiving a tap gesture when it occurs within our area.
523    * @param[in]  actor  The tapped actor.
524    * @param[in]  tap    The tap gesture.
525    */
526   void OnTap(Actor actor, const TapGesture& tap);
527
528   /**
529    * Sets up the autorepeating timer.
530    * @param[in] delay The delay time in seconds.
531    */
532   void SetUpTimer( float delay );
533
534   /**
535    * Slot called when Dali::Timer::SignalTick signal. Resets the autorepeating timer.
536    */
537   bool AutoRepeatingSlot();
538
539   /**
540    * Sets the button as selected or unselected.
541    * @param[in] selected \e selected property value.
542    * @param[in] emitSignal Emit a signal if this value is \e true.
543    */
544   void SetSelected( bool selected, bool emitSignal );
545
546   /**
547    * This method is called when the button is pressed.
548    */
549   void Pressed();
550
551   /**
552    * This method is called when the button is released.
553    */
554   void Released();
555
556   /**
557    * Used to perform common setup applied to images within button.
558    * This will replace the current image with the specifed one.
559    * @param[in]  actorToModify The image to replace.
560    * @param[out] newActor The new image to use.
561    */
562   void SetupContent( Actor& actorToModify, Actor newActor );
563
564   /**
565    * Sets the color of the unselected image.
566    * If no image exists, it is created.
567    * @param[in]  color The color to use.
568    */
569   void SetUnselectedColor( const Vector4& color );
570
571   /**
572    * Gets the unselected content color.
573    * @return     The currently used unselected color.
574    */
575   const Vector4 GetUnselectedColor() const;
576
577   /**
578    * Sets the color of the selected image.
579    * If no image exists, it is created.
580    * @param[in]  color The color to use.
581    */
582   void SetSelectedColor( const Vector4& color );
583
584   /**
585    * Gets the selected content color.
586    * @return     The currently used selected color.
587    */
588   const Vector4 GetSelectedColor() const;
589
590 protected:
591
592   enum ButtonState
593   {
594     ButtonUp,                                  ///< The button is up.
595     ButtonDown,                                ///< The button is down.
596   };
597
598   /**
599    * Button paint states.
600    */
601   enum PaintState
602   {
603     UnselectedState,              ///< The button is unselected.
604     SelectedState,                ///< The button is selected.
605     DisabledUnselectedState,      ///< The button is disabled and unselected.
606     DisabledSelectedState,        ///< The button is disabled and selected.
607   };
608
609   /**
610    * Enum to specify which decoration when getting and setting decorations.
611    */
612   enum DecorationState
613   {
614     UNSELECTED_DECORATION = 0,
615     SELECTED_DECORATION,
616     DECORATION_STATES
617   };
618
619   ButtonState GetState();
620   PaintState GetPaintState();
621   void SetDecoration( DecorationState state, Actor actor );
622   Actor& GetDecoration( DecorationState state );
623
624
625   /**
626    * Returns the animation to be used for transitioning creating the animation if needed.
627    * @return The initialised transition animation.
628    */
629   Dali::Animation GetTransitionAnimation();
630
631   /**
632    * Prepares the actor to be transitioned in.
633    * @param[in]  actor  The actor that will be transitioned in.
634    */
635   virtual void PrepareForTranstionIn( Actor actor ) {}
636
637   /**
638    * Prepares the actor to be transitioned in.
639    * @param[in]  actor  The actor that will be transitioned out.
640    */
641   virtual void PrepareForTranstionOut( Actor actor ) {}
642
643   /**
644    * Transitions the actor in, allowing derived classes to configure
645    * the GetTransitionAnimation() animation ready.
646    * Button is in charge of calling Dali::Animation::Play and so derived classes
647    * only need to add the animation.
648    */
649   virtual void OnTransitionIn( Actor actor ) {}
650
651   /**
652    * Transitions the actor out, allowing derived classes to configure
653    * the GetTransitionAnimation() animation ready.
654    * Button is in charge of calling Dali::Animation::Play and so derived classes
655    * only need to add the animation.
656    */
657   virtual void OnTransitionOut( Actor actor ) {}
658
659 private:
660
661   /**
662    * Starts the transition animation.
663    * Button::TransitionFinished is called when the animation finishes.
664    */
665   void StartTransitionAnimation();
666
667   /**
668    * This method stops all transition animations
669    */
670   void StopTransitionAnimation();
671
672   /**
673    * Called when the transition animation finishes.
674    */
675   void TransitionAnimationFinished( Dali::Animation& source );
676
677   /**
678    * Resets the Button to the base state for the current paint state.
679    * Any additionally inserted images needed for transitions that are
680    * no longer needed and the removed.
681    */
682   void ResetImageLayers();
683
684   /**
685    * Transitions out the actor
686    */
687   void TransitionOut( Actor actor );
688
689   /**
690    * Removes the actor from the button and prepares it to be transitioned out
691    */
692   void RemoveButtonImage( Actor& actor );
693
694   /**
695    * Finds the index of the actor.
696    * If the actor doesn't exist, return the last index + 1.
697    */
698   unsigned int FindChildIndex( Actor& actor );
699
700   /**
701    * Adds an actor to the hierarchy and prepares it to be transitioned.
702    * @param[in] actor The actor to add
703    */
704   void PrepareAddButtonImage( Actor& actor );
705
706   /**
707    * Adds an actor to the hierarchy and marks it to be transitioned.
708    * @param[in] actor The actor to add
709    */
710   void TransitionButtonImage( Actor& actor );
711
712   /**
713    * Adds an actor to the hierarchy.
714    * @param[in] actor The actor to add
715    */
716   void AddButtonImage( Actor& actor );
717
718   /**
719    * (Re)Adds the label (if exists) to the hierarchy (so it is always on top).
720    */
721   void ReAddLabel();
722
723   // Undefined
724   Button( const Button& );
725
726   // Undefined
727   Button& operator = ( const Button& );
728
729 private:
730
731   // Signals
732   Toolkit::Button::ButtonSignalType mPressedSignal;           ///< Signal emitted when the button is pressed.
733   Toolkit::Button::ButtonSignalType mReleasedSignal;          ///< Signal emitted when the button is released.
734   Toolkit::Button::ButtonSignalType mClickedSignal;           ///< Signal emitted when the button is clicked.
735   Toolkit::Button::ButtonSignalType mStateChangedSignal;      ///< Signal emitted when the button's state is changed.
736
737   Timer mAutoRepeatingTimer;                   ///< Timer used to implement the autorepeating property.
738
739   Actor mLabel;                                ///< Stores the button label.
740
741   Actor mDecoration[ DECORATION_STATES ];      ///< Stores the decorations for both selected and unselected states.
742
743   Actor mUnselectedContent;                    ///< Stores the unselected content.
744   Actor mSelectedContent;                      ///< Stores the selected content.
745   Actor mBackgroundContent;                    ///< Stores the background content.
746   Actor mSelectedBackgroundContent;            ///< Stores the selected background content.
747   Actor mDisabledContent;                      ///< Stores the disabled content.
748   Actor mDisabledSelectedContent;              ///< Stores the disabled selected content.
749   Actor mDisabledBackgroundContent;            ///< Stores the disabled background content.
750
751   Animation        mTransitionAnimation;       ///< Animation used in the state transitions.
752
753   TapGestureDetector mTapDetector;
754
755   Vector4          mUnselectedColor;           ///< Color to use for unselected content.
756   Vector4          mSelectedColor;             ///< Color to use for selected content.
757
758   bool             mDisabled;                  ///< Stores the disabled property.
759   bool             mAutoRepeating;             ///< Stores the autorepeating property.
760   bool             mTogglableButton;           ///< Stores the togglable property.
761   bool             mSelected;                  ///< Stores the selected state.
762   float            mInitialAutoRepeatingDelay; ///< Stores the initial autorepeating delay in seconds.
763   float            mNextAutoRepeatingDelay;    ///< Stores the next autorepeating delay in seconds.
764
765   float            mAnimationTime;             ///< The animation time.
766
767   // Actions
768   bool             mClickActionPerforming;
769
770   ButtonState      mState;                     ///< Stores the button state.
771   PaintState       mPaintState;                ///< Stores the paint state.
772 };
773
774 } // namespace Internal
775
776 // Helpers for public-api forwarding methods
777
778 inline Toolkit::Internal::Button& GetImplementation( Toolkit::Button& button )
779 {
780   DALI_ASSERT_ALWAYS( button );
781
782   Dali::RefObject& handle = button.GetImplementation();
783
784   return static_cast<Toolkit::Internal::Button&>( handle );
785 }
786
787 inline const Toolkit::Internal::Button& GetImplementation( const Toolkit::Button& button )
788 {
789   DALI_ASSERT_ALWAYS( button );
790
791   const Dali::RefObject& handle = button.GetImplementation();
792
793   return static_cast<const Toolkit::Internal::Button&>( handle );
794 }
795
796 } // namespace Toolkit
797
798 } // namespace Dali
799
800 #endif // __DALI_TOOLKIT_INTERNAL_BUTTON_H__