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