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( bool disabled )
  62    */
  63   void SetDisabled( bool disabled );
  64
  65   /**
  66    * @copydoc Dali::Toolkit::Button::IsDisabled() const
  67    */
  68   bool IsDisabled() const;
  69
  70   /**
  71    * @copydoc Dali::Toolkit::Button::SetAutoRepeating( bool autoRepeating )
  72    */
  73   void SetAutoRepeating( bool autoRepeating );
  74
  75   /**
  76    * @copydoc Dali::Toolkit::Button::IsAutoRepeating() const
  77    */
  78   bool IsAutoRepeating() const;
  79
  80   /**
  81    * @copydoc Dali::Toolkit::Button::SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay )
  82    */
  83   void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
  84
  85   /**
  86    * @copydoc Dali::Toolkit::Button::GetInitialAutoRepeatingDelay() const
  87    */
  88   float GetInitialAutoRepeatingDelay() const;
  89
  90   /**
  91    * @copydoc Dali::Toolkit::Button::SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay )
  92    */
  93   void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
  94
  95   /**
  96    * @copydoc Dali::Toolkit::Button::GetNextAutoRepeatingDelay() const
  97    */
  98   float GetNextAutoRepeatingDelay() const;
  99
 100   /**
 101    * @copydoc Dali::Toolkit::Button::SetTogglableButton( bool togglable )
 102    */
 103   void SetTogglableButton( bool togglable );
 104
 105   /**
 106    * @copydoc Dali::Toolkit::Button::IsTogglableButton() const
 107    */
 108   bool IsTogglableButton() const;
 109
 110   /**
 111    * @copydoc Dali::Toolkit::Button::SetSelected( bool selected )
 112    */
 113   void SetSelected( bool selected );
 114
 115   /**
 116    * @copydoc Dali::Toolkit::Button::IsSelected() const
 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::SetLabel( const std::string& label )
 132    */
 133   void SetLabel( const std::string& label );
 134
 135   /**
 136    * @copydoc Dali::Toolkit::Button::SetLabel( Actor label )
 137    */
 138   void SetLabel( Actor label );
 139
 140   /**
 141    * @copydoc Dali::Toolkit::Button::GetLabel()
 142    */
 143   Actor GetLabel() const;
 144
 145   /**
 146    * @copydoc Dali::Toolkit::PushButton::SetButtonImage( Actor image )
 147    */
 148   void SetButtonImage( Actor image );
 149
 150   /**
 151    * @copydoc Dali::Toolkit::PushButton::GetButtonImage()
 152    */
 153   Actor GetButtonImage() const;
 154
 155   /**
 156    * Internal use only.
 157    * @return A reference to the button image.
 158    */
 159   Actor& GetButtonImage();
 160
 161   /**
 162    * @copydoc Dali::Toolkit::PushButton::SetSelectedImage( Actor image )
 163    */
 164   void SetSelectedImage( Actor image );
 165
 166   /**
 167    * @copydoc Dali::Toolkit::PushButton::GetSelectedImage()
 168    */
 169   Actor GetSelectedImage() const;
 170
 171   /**
 172    * Internal use only.
 173    * @return A reference to the selected image.
 174    */
 175   Actor& GetSelectedImage();
 176
 177   /**
 178    * @copydoc Dali::Toolkit::PushButton::SetBackgroundImage( Actor image )
 179    */
 180   void SetBackgroundImage( Actor image );
 181
 182   /**
 183    * @copydoc Dali::Toolkit::PushButton::GetBackgroundImage()
 184    */
 185   Actor GetBackgroundImage() const;
 186
 187   /**
 188    * Internal use only.
 189    * @return A reference to the background image.
 190    */
 191   Actor& GetBackgroundImage();
 192
 193   /**
 194    * @copydoc Dali::Toolkit::PushButton::SetSelectedBackgroundImage( Actor image )
 195    */
 196   void SetSelectedBackgroundImage( Actor image );
 197
 198   /**
 199    * @copydoc Dali::Toolkit::PushButton::GetSelectedBackgroundImage()
 200    */
 201   Actor GetSelectedBackgroundImage() const;
 202
 203   /**
 204    * Internal use only.
 205    * @return A reference to the selected background image.
 206    */
 207   Actor& GetSelectedBackgroundImage();
 208
 209   /**
 210    * @copydoc Dali::Toolkit::PushButton::SetDisabledImage( Actor image )
 211    */
 212   void SetDisabledImage( Actor image );
 213
 214   /**
 215    * @copydoc Dali::Toolkit::PushButton::GetDisabledImage()
 216    */
 217   Actor GetDisabledImage() const;
 218
 219   /**
 220    * Internal use only.
 221    * @return A reference to the disabled button image.
 222    */
 223   Actor& GetDisabledImage();
 224
 225   /**
 226    * @copydoc Dali::Toolkit::CheckBoxButton::SetDisabledSelectedImage( Actor image )
 227    */
 228   void SetDisabledSelectedImage( Actor image );
 229
 230   /**
 231    * @copydoc Dali::Toolkit::CheckBoxButton::GetDisabledSelectedImage()
 232    */
 233   Actor GetDisabledSelectedImage() const;
 234
 235   /**
 236    * Internal use only.
 237    * @return A reference to the disabled selected image.
 238    */
 239   Actor& GetDisabledSelectedImage();
 240
 241   /**
 242    * @copydoc Dali::Toolkit::PushButton::SetDisabledBackgroundImage( Actor image )
 243    */
 244   void SetDisabledBackgroundImage( Actor image );
 245
 246   /**
 247    * @copydoc Dali::Toolkit::PushButton::GetDisabledBackgroundImage()
 248    */
 249   Actor GetDisabledBackgroundImage() const;
 250
 251   /**
 252    * Internal use only.
 253    * @return A reference to the disabled background image.
 254    */
 255   Actor& GetDisabledBackgroundImage();
 256
 257   /**
 258    * Performs actions as requested using the action name.
 259    * @param[in] object The object on which to perform the action.
 260    * @param[in] actionName The action to perform.
 261    * @param[in] attributes The attributes with which to perfrom this action.
 262    * @return true if action has been accepted by this control
 263    */
 264   static bool DoAction( BaseObject* object, const std::string& actionName, const Property::Map& attributes );
 265
 266 protected:
 267
 268   /**
 269    * @return A reference to the label actor.
 270    */
 271   Actor& GetLabel();
 272
 273 private:
 274
 275   /**
 276    * Perform the click action to click the button.
 277    * @param[in] attributes The attributes to perfrom this action.
 278    * @return true if this control can perform action.
 279    */
 280   bool DoClickAction( const Property::Map& attributes );
 281
 282   /**
 283    * This method is called after the button initialization.
 284    * Could be reimplemented in subclasses to provide specific behaviour.
 285    */
 286   virtual void OnButtonInitialize() { }
 287
 288   /**
 289    * This method is called when the label is set.
 290    */
 291   virtual void OnLabelSet() {}
 292
 293   /**
 294    * This method is called when the button image is set
 295    */
 296   virtual void OnButtonImageSet() {}
 297
 298   /**
 299    * This method is called when the selected image is set
 300    */
 301   virtual void OnSelectedImageSet() {}
 302
 303   /**
 304    * This method is called when the background image is set
 305    */
 306   virtual void OnBackgroundImageSet() {}
 307
 308   /**
 309    * This method is called when the selected background image is set
 310    */
 311   virtual void OnSelectedBackgroundImageSet() {}
 312
 313   /**
 314    * This method is called when the disabled button image is set
 315    */
 316   virtual void OnDisabledImageSet() {}
 317
 318   /**
 319    * This method is called when the disabled selected image is set
 320    */
 321   virtual void OnDisabledSelectedImageSet() {}
 322
 323   /**
 324    * This method is called when the disabled background image is set
 325    */
 326   virtual void OnDisabledBackgroundImageSet() {}
 327
 328   /**
 329    * This method is called from the OnTouchEvent method when the button is down.
 330    * Could be reimplemented in subclasses to provide specific behaviour.
 331    */
 332   virtual void OnButtonDown();
 333
 334   /**
 335    * This method is called from the OnTouchEvent method when the button is up.
 336    * Could be reimplemented in subclasses to provide specific behaviour.
 337    */
 338   virtual void OnButtonUp();
 339
 340   /**
 341    * This method is called from the OnTouchEvent method when the touch point leaves the boundary of the button or
 342    * more than one touch points are received.
 343    * Could be reimplemented in subclasses to provide specific behaviour.
 344    */
 345   virtual void OnTouchPointLeave();
 346
 347   /**
 348    * This method is called from the OnTouchEvent method when the touch point is interrupted.
 349    * Could be reimplemented in subclasses to provide specific behaviour.
 350    */
 351   virtual void OnTouchPointInterrupted();
 352
 353   /**
 354    * This method is called when the button is removed from the stage.
 355    * Could be reimplemented in subclasses to provide specific behaviour.
 356    */
 357   virtual void OnButtonStageDisconnection();
 358
 359   /**
 360    * This method is called when the \e selected property is changed.
 361    */
 362   virtual void OnSelected() {}
 363
 364   /**
 365    * This method is called when the \e disabled property is changed.
 366    */
 367   virtual void OnDisabled() {}
 368
 369   /**
 370    * This method is called when the button is pressed.
 371    */
 372   virtual void OnPressed() {}
 373
 374   /**
 375    * This method is called when the button is released.
 376    */
 377   virtual void OnReleased() {}
 378
 379 public:
 380
 381   /**
 382    * @copydoc Dali::Toolkit::PushButton::PressedSignal()
 383    */
 384   Toolkit::Button::ButtonSignalType& PressedSignal();
 385
 386   /**
 387    * @copydoc Dali::Toolkit::PushButton::ReleasedSignal()
 388    */
 389   Toolkit::Button::ButtonSignalType& ReleasedSignal();
 390
 391   /**
 392    * @copydoc Dali::Toolkit::Button::ClickedSignal()
 393    */
 394   Toolkit::Button::ButtonSignalType& ClickedSignal();
 395
 396   /**
 397    * @copydoc Dali::Toolkit::Button::StateChangedSignal()
 398    */
 399   Toolkit::Button::ButtonSignalType& StateChangedSignal();
 400
 401   /**
 402    * Connects a callback function with the object's signals.
 403    * @param[in] object The object providing the signal.
 404    * @param[in] tracker Used to disconnect the signal.
 405    * @param[in] signalName The signal to connect to.
 406    * @param[in] functor A newly allocated FunctorDelegate.
 407    * @return True if the signal was connected.
 408    * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
 409    */
 410   static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
 411
 412   // Properties
 413
 414   /**
 415    * Called when a property of an object of this type is set.
 416    * @param[in] object The object whose property is set.
 417    * @param[in] index The property index.
 418    * @param[in] value The new property value.
 419    */
 420   static void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
 421
 422   /**
 423    * Called to retrieve a property of an object of this type.
 424    * @param[in] object The object whose property is to be retrieved.
 425    * @param[in] index The property index.
 426    * @return The current value of the property.
 427    */
 428   static Property::Value GetProperty( BaseObject* object, Property::Index propertyIndex );
 429
 430 protected: // From CustomActorImpl
 431
 432   /**
 433    * @copydoc Dali::CustomActorImpl::OnTouchEvent( const TouchEvent& event )
 434    */
 435   virtual bool OnTouchEvent( const TouchEvent& event );
 436
 437 private: // From Control
 438
 439   /**
 440    * @copydoc Toolkit::Control::OnInitialize()
 441    */
 442   virtual void OnInitialize();
 443
 444   /**
 445    * @copydoc Toolkit::Control::OnAccessibilityActivated()
 446    */
 447   virtual bool OnAccessibilityActivated();
 448
 449   /**
 450    * @copydoc Toolkit::Control::OnKeyboardEnter()
 451    */
 452   virtual bool OnKeyboardEnter();
 453
 454   /**
 455    * Callback received when the button is disconnected from the stage.
 456    * It resets the button status.
 457    */
 458   void OnControlStageDisconnection();
 459
 460 private:
 461
 462   /**
 463    * Handler for tap events.
 464    * We do not actually do anything when we receive a tap as the button handles tap event through
 465    * the touch event system itself as it requires more than just tap handling (e.g. leave events).
 466    * This stops any of our parents receiving a tap gesture when it occurs within our area.
 467    * @param[in]  actor  The tapped actor.
 468    * @param[in]  tap    The tap gesture.
 469    */
 470   void OnTap(Actor actor, const TapGesture& tap);
 471
 472   /**
 473    * Sets up the autorepeating timer.
 474    * @param[in] delay The delay time in seconds.
 475    */
 476   void SetUpTimer( float delay );
 477
 478   /**
 479    * Slot called when Dali::Timer::SignalTick signal. Resets the autorepeating timer.
 480    */
 481   bool AutoRepeatingSlot();
 482
 483   /**
 484    * Sets the button as selected or unselected.
 485    * @param[in] selected \e selected property value.
 486    * @param[in] emitSignal Emit a signal if this value is \e true.
 487    */
 488   void SetSelected( bool selected, bool emitSignal );
 489
 490   /**
 491    * This method is called when the button is pressed.
 492    */
 493   void Pressed();
 494
 495   /**
 496    * This method is called when the button is released.
 497    */
 498   void Released();
 499
 500 protected:
 501
 502   enum ButtonState
 503   {
 504     ButtonUp,                                  ///< The button is up.
 505     ButtonDown,                                ///< The button is down.
 506   };
 507
 508   /**
 509    * Button paint states.
 510    */
 511   enum PaintState
 512   {
 513     UnselectedState,              ///< The button is unselected.
 514     SelectedState,                ///< The button is selected.
 515     DisabledUnselectedState,      ///< The button is disabled and unselected.
 516     DisabledSelectedState,        ///< The button is disabled and selected.
 517   };
 518
 519   ButtonState GetState();
 520   PaintState GetPaintState();
 521
 522   /**
 523    * Returns the animation to be used for transitioning creating the animation if needed.
 524    * @return The initialised transition animation.
 525    */
 526   Dali::Animation GetTransitionAnimation();
 527
 528   /**
 529    * Prepares the actor to be transitioned in.
 530    * @param[in]  actor  The actor that will be transitioned in.
 531    */
 532   virtual void PrepareForTranstionIn( Actor actor ) {}
 533
 534   /**
 535    * Prepares the actor to be transitioned in.
 536    * @param[in]  actor  The actor that will be transitioned out.
 537    */
 538   virtual void PrepareForTranstionOut( Actor actor ) {}
 539
 540   /**
 541    * Transitions the actor in, allowing derived classes to configure
 542    * the GetTransitionAnimation() animation ready.
 543    * Button is in charge of calling Dali::Animation::Play and so derived classes
 544    * only need to add the animation.
 545    */
 546   virtual void OnTransitionIn( Actor actor ) {}
 547
 548   /**
 549    * Transitions the actor out, allowing derived classes to configure
 550    * the GetTransitionAnimation() animation ready.
 551    * Button is in charge of calling Dali::Animation::Play and so derived classes
 552    * only need to add the animation.
 553    */
 554   virtual void OnTransitionOut( Actor actor ) {}
 555
 556 private:
 557   /**
 558    * Starts the transition animation.
 559    * Button::TransitionFinished is called when the animation finishes.
 560    */
 561   void StartTransitionAnimation();
 562
 563   /**
 564    * This method stops all transition animations
 565    */
 566   void StopTransitionAnimation();
 567
 568   /**
 569    * Called when the transition animation finishes.
 570    */
 571   void TransitionAnimationFinished( Dali::Animation& source );
 572
 573   /**
 574    * Resets the Button to the base state for the current paint state.
 575    * Any additionally inserted images needed for transitions that are
 576    * no longer needed and the removed.
 577    */
 578   void ResetImageLayers();
 579
 580   /**
 581    * Transitions out the actor
 582    */
 583   void TransitionOut( Actor actor );
 584
 585   /**
 586    * Removes the actor from the button and prepares it to be transitioned out
 587    */
 588   void RemoveButtonImage( Actor& actor );
 589
 590   /**
 591    * Finds the index of the actor.
 592    * If the actor doesn't exist, return the last index + 1.
 593    */
 594   unsigned int FindChildIndex( Actor& actor );
 595
 596   /**
 597    * Adds an actor to the hierarchy and prepares it to be transitioned.
 598    * @param[in] actor The actor to add
 599    */
 600   void PrepareAddButtonImage( Actor& actor );
 601
 602   /**
 603    * Adds an actor to the hierarchy and marks it to be transitioned.
 604    * @param[in] actor The actor to add
 605    */
 606   void TransitionButtonImage( Actor& actor );
 607
 608   /**
 609    * Adds an actor to the hierarchy.
 610    * @param[in] actor The actor to add
 611    */
 612   void AddButtonImage( Actor& actor );
 613
 614   /**
 615    * (Re)Adds the label (if exists) to the hierarchy (so it is always on top).
 616    */
 617   void ReAddLabel();
 618
 619   // Undefined
 620   Button( const Button& );
 621
 622   // Undefined
 623   Button& operator = ( const Button& );
 624
 625 private:
 626
 627   // Signals
 628   Toolkit::Button::ButtonSignalType mPressedSignal;           ///< Signal emitted when the button is pressed.
 629   Toolkit::Button::ButtonSignalType mReleasedSignal;          ///< Signal emitted when the button is released.
 630   Toolkit::Button::ButtonSignalType mClickedSignal;           ///< Signal emitted when the button is clicked.
 631   Toolkit::Button::ButtonSignalType mStateChangedSignal;      ///< Signal emitted when the button's state is changed.
 632
 633   Timer mAutoRepeatingTimer;                   ///< Timer used to implement the autorepeating property.
 634
 635   Actor mLabel;                                ///< Stores the button label.
 636
 637   Actor mUnselectedContent;                    ///< Stores the unselected content.
 638   Actor mSelectedContent;                      ///< Stores the selected content.
 639   Actor mBackgroundContent;                    ///< Stores the background content.
 640   Actor mSelectedBackgroundContent;            ///< Stores the selected background content.
 641   Actor mDisabledContent;                      ///< Stores the disabled content.
 642   Actor mDisabledSelectedContent;              ///< Stores the disabled selected content.
 643   Actor mDisabledBackgroundContent;            ///< Stores the disabled background content.
 644
 645   Animation        mTransitionAnimation;       ///< Animation used in the state transitions.
 646
 647   TapGestureDetector mTapDetector;
 648
 649   bool             mDisabled;                  ///< Stores the disabled property.
 650   bool             mAutoRepeating;             ///< Stores the autorepeating property.
 651   bool             mTogglableButton;           ///< Stores the togglable property.
 652   bool             mSelected;                  ///< Stores the selected state.
 653   float            mInitialAutoRepeatingDelay; ///< Stores the initial autorepeating delay in seconds.
 654   float            mNextAutoRepeatingDelay;    ///< Stores the next autorepeating delay in seconds.
 655
 656   float            mAnimationTime;             ///< The animation time.
 657
 658   // Actions
 659   bool             mClickActionPerforming;
 660
 661   ButtonState      mState;                     ///< Stores the button state.
 662   PaintState       mPaintState;                ///< Stores the paint state.
 663 };
 664
 665 } // namespace Internal
 666
 667 // Helpers for public-api forwarding methods
 668
 669 inline Toolkit::Internal::Button& GetImplementation( Toolkit::Button& button )
 670 {
 671   DALI_ASSERT_ALWAYS( button );
 672
 673   Dali::RefObject& handle = button.GetImplementation();
 674
 675   return static_cast<Toolkit::Internal::Button&>( handle );
 676 }
 677
 678 inline const Toolkit::Internal::Button& GetImplementation( const Toolkit::Button& button )
 679 {
 680   DALI_ASSERT_ALWAYS( button );
 681
 682   const Dali::RefObject& handle = button.GetImplementation();
 683
 684   return static_cast<const Toolkit::Internal::Button&>( handle );
 685 }
 686
 687 } // namespace Toolkit
 688
 689 } // namespace Dali
 690
 691 #endif // __DALI_TOOLKIT_INTERNAL_BUTTON_H__