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/devel-api/visual-factory/visual-base.h>
  27 #include <dali-toolkit/public-api/controls/buttons/button.h>
  28 #include <dali-toolkit/public-api/controls/control-impl.h>
  29
  30 //#if defined(DEBUG_ENABLED)
  31 //  Debug::Filter* gLogButtonFilter = Debug::Filter::New(Debug::NoLogging, true, "LOG_BUTTON_CONTROL");
  32 //#endif
  33
  34 namespace Dali
  35 {
  36
  37 namespace Toolkit
  38 {
  39
  40 class Button;
  41
  42 namespace Internal
  43 {
  44
  45 /**
  46  * @copydoc Toolkit::Button
  47  *
  48  * Button is the base class implementation for all buttons.
  49  *
  50  * @note
  51  *
  52  * All Foreground/Icon visuals expected to be the same size.
  53  * Background visuals will take the size of the control.
  54  * Padding and struts take size precedence over visuals when available space is limited.
  55  * Icon/Foreground visuals take size precedence over Labels when available space is limited.
  56  */
  57 class Button : public Control
  58 {
  59
  60 public:
  61
  62   /**
  63    * Enum describing the position the text label can be in relation to the control (and foreground/icon)
  64    */
  65   enum Align
  66   {
  67     BEGIN,  // At the start of the control before the foreground/icon
  68     END,    // At the end of the control after the foreground/icon
  69     TOP,    // At the top of the control above the foreground/icon
  70     BOTTOM  // At the bottom of the control below the foreground/icon
  71   };
  72
  73 public:
  74
  75   /**
  76    * @copydoc Dali::Toolkit::Button::SetDisabled
  77    */
  78   void SetDisabled( bool disabled );
  79
  80   /**
  81    * @copydoc Dali::Toolkit::Button::IsDisabled
  82    */
  83   bool IsDisabled() const;
  84
  85   /**
  86    * @copydoc Dali::Toolkit::Button::SetAutoRepeating
  87    */
  88   void SetAutoRepeating( bool autoRepeating );
  89
  90   /**
  91    * @copydoc Dali::Toolkit::Button::IsAutoRepeating
  92    */
  93   bool IsAutoRepeating() const;
  94
  95   /**
  96    * @copydoc Dali::Toolkit::Button::SetInitialAutoRepeatingDelay
  97    */
  98   void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
  99
 100   /**
 101    * @copydoc Dali::Toolkit::Button::GetInitialAutoRepeatingDelay
 102    */
 103   float GetInitialAutoRepeatingDelay() const;
 104
 105   /**
 106    * @copydoc Dali::Toolkit::Button::SetNextAutoRepeatingDelay
 107    */
 108   void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
 109
 110   /**
 111    * @copydoc Dali::Toolkit::Button::GetNextAutoRepeatingDelay
 112    */
 113   float GetNextAutoRepeatingDelay() const;
 114
 115   /**
 116    * @copydoc Dali::Toolkit::Button::SetTogglableButton
 117    */
 118   void SetTogglableButton( bool togglable );
 119
 120   /**
 121    * @copydoc Dali::Toolkit::Button::IsTogglableButton
 122    */
 123   bool IsTogglableButton() const;
 124
 125   /**
 126    * @copydoc Dali::Toolkit::Button::SetSelected
 127    */
 128   void SetSelected( bool selected );
 129
 130   /**
 131    * @copydoc Dali::Toolkit::Button::IsSelected
 132    */
 133   bool IsSelected() const;
 134
 135   /**
 136    * @copydoc Dali::Toolkit::Button::SetAnimationTime
 137    */
 138   void SetAnimationTime( float animationTime );
 139
 140   /**
 141    * @copydoc Dali::Toolkit::Button::GetAnimationTime
 142    */
 143   float GetAnimationTime() const;
 144
 145   /**
 146    * @copydoc Dali::Toolkit::Button::SetLabelText
 147    */
 148   void SetLabelText( const std::string& label );
 149
 150   /**
 151    * @copydoc Dali::Toolkit::Button::GetLabelText
 152    */
 153   std::string GetLabelText() const;
 154
 155   /**
 156    * @brief Sets the specified properties on the button label.
 157    * If the label does not exist yet, it is created.
 158    * The derived buttons are notified if any properties are changed.
 159    * @param[in] properties A Property::Map of key-value pairs of properties to set.
 160    */
 161   void SetupLabel( const Property::Map& properties );
 162
 163   /**
 164    * Performs actions as requested using the action name.
 165    * @param[in] object The object on which to perform the action.
 166    * @param[in] actionName The action to perform.
 167    * @param[in] attributes The attributes with which to perfrom this action.
 168    * @return true if action has been accepted by this control
 169    */
 170   static bool DoAction( BaseObject* object, const std::string& actionName, const Property::Map& attributes );
 171
 172 public: // Deprecated API
 173
 174   /**
 175    * @copydoc Dali::Toolkit::Button::SetLabel( Actor label )
 176    */
 177   void SetLabel( Actor label );
 178
 179   /**
 180    * @deprecated Sets the unselected image with an url.
 181    * @param[in] image The Actor to use.
 182    */
 183   void SetUnselectedImage( const std::string& filename );
 184
 185   /**
 186    * @deprecated Sets the selected image with an url.
 187    * @param[in] filename The url of the image to use to use.
 188    */
 189   void SetSelectedImage( const std::string& filename );
 190
 191   /**
 192    * @deprecated Sets the selected background image with an url.
 193    * @param[in] filename The url of the image to use to use.
 194    */
 195   void SetSelectedBackgroundImage( const std::string& filename );
 196
 197   /**
 198    * @deprecated Sets the background image with an url.
 199    * @param[in] filename The url of the image to use to use.
 200    */
 201   void SetBackgroundImage( const std::string& filename );
 202
 203   /**
 204    * @deprecated Sets the disabled unselected background image with an url.
 205    * @param[in] filename The url of the image to use to use.
 206    */
 207   void SetDisabledBackgroundImage( const std::string& filename );
 208
 209   /**
 210    * @deprecated Sets the disabled unselected image with an url.
 211    * @param[in] filename The url of the image to use to use.
 212    */
 213   void SetDisabledImage( const std::string& filename );
 214
 215   /**
 216    * @deprecated Sets the disabled selected image with an url.
 217    * @param[in] filename The url of the image to use to use.
 218    */
 219   void SetDisabledSelectedImage( const std::string& filename );
 220
 221   /**
 222    * @deprecated Sets the unselected image with an Actor.
 223    * @param[in] image The Actor to use.
 224    */
 225   void SetUnselectedImage( Actor image );
 226
 227   /**
 228    * @deprecated Sets the selected image with an Actor.
 229    * @param[in] image The Actor to use.
 230    */
 231   void SetSelectedImage( Actor image );
 232
 233   /**
 234    * @deprecated Sets the selected background image with an Actor.
 235    * @param[in] image The Actor to use.
 236    */
 237   void SetSelectedBackgroundImage( Actor image );
 238
 239   /**
 240    * @deprecated Sets the disabled image with an Actor.
 241    * @param[in] image The Actor to use.
 242    */
 243   void SetDisabledImage( Actor image );
 244
 245   /**
 246    * @deprecated Sets the disabled selected image with an Actor.
 247    * @param[in] image The Actor to use.
 248    */
 249   void SetDisabledSelectedImage( Actor image );
 250
 251   /**
 252    * @deprecated Sets the disabled background image with an Actor.
 253    * @param[in] image The Actor to use.
 254    */
 255   void SetDisabledBackgroundImage( Actor image );
 256
 257   /**
 258    * @Gets url of a image visual, used by GetProperty but for deprecated Properties
 259    * @param[in] index Visual index of url required
 260    * @return filename for the corresponding visual
 261    */
 262   std::string GetUrlForImageVisual( Property::Index index );
 263
 264
 265   /**
 266    * @copydoc Dali::Toolkit::Button::GetButtonImage
 267    */
 268   Actor GetButtonImage() const;
 269
 270   /**
 271    * @copydoc Dali::Toolkit::Button::GetSelectedImage
 272    */
 273   Actor GetSelectedImage() const;
 274
 275 public:
 276
 277   /**
 278    * Button's state
 279    */
 280   enum State
 281   {
 282     UNSELECTED_STATE,              ///< The button is unselected.
 283     SELECTED_STATE,                ///< The button is selected.
 284     DISABLED_UNSELECTED_STATE,     ///< The button is disabled and unselected.
 285     DISABLED_SELECTED_STATE,       ///< The button is disabled and selected.
 286     STATE_COUNT,                   ///< Number of States
 287   };
 288
 289   /**
 290    * Enum to distinguish the different style-able components of the button
 291    */
 292   enum Visuals
 293   {
 294     UNSELECTED_FOREGROUND = 0,
 295     SELECTED_FOREGROUND,
 296     DISABLED_SELECTED_FOREGROUND,
 297     DISABLED_UNSELECTED_FOREGROUND,
 298     UNSELECTED_BACKGROUND,
 299     SELECTED_BACKGROUND,
 300     DISABLED_UNSELECTED_BACKGROUND,
 301     DISABLED_SELECTED_BACKGROUND,
 302     VISUALS_COUNT
 303   };
 304
 305   /**
 306    * Enum to list types of visual a state can have.
 307    */
 308   enum VisualState
 309   {
 310     BACKGROUND = 0,
 311     FOREGROUND,
 312     VISUAL_STATE_COUNT
 313   };
 314
 315 protected:
 316
 317   /**
 318    * Button press state which is not the same as the actual button's state.
 319    * For example An UNSELECTED button can be DEPRESSED, but until released, the actual button state doesn't change to SELECTED
 320    */
 321   enum PressState
 322   {
 323     DEPRESSED,                           ///< The button is up.
 324     UNPRESSED,                           ///< The button is down.
 325     TOGGLE_DEPRESSED,                    ///< The button has been pressed down and will stay depressed when released.
 326   };
 327
 328   /**
 329    * Construct a new Button.
 330    */
 331   Button();
 332
 333   /**
 334    * A reference counted object may only be deleted by calling Unreference()
 335    */
 336   virtual ~Button();
 337   /**
 338    * @return A reference to the label actor.
 339    */
 340   Actor& GetLabelActor();
 341
 342   /**
 343    * @return A reference to the unselected button image.
 344    */
 345   Actor GetUnselectedImage();
 346
 347   /**
 348    * @return A reference to the selected image.
 349    */
 350   Actor GetSelectedImage();
 351
 352 private:
 353
 354   /**
 355    * Perform the click action to click the button.
 356    * @param[in] attributes The attributes to perfrom this action.
 357    * @return true if this control can perform action.
 358    */
 359   bool DoClickAction( const Property::Map& attributes );
 360
 361   /**
 362    * This method is called when the button is a Toggle button and released
 363    * Could be reimplemented in subclasses to provide specific behaviour.
 364    * @return bool returns true if state changed.
 365    */
 366   virtual bool OnToggleReleased();
 367
 368   /**
 369    * This method is called when touch leaves the boundary of the button or several touch points are received.
 370    * Could be reimplemented in subclasses to provide specific behaviour.
 371    */
 372   virtual void OnTouchPointLeave();
 373
 374   /**
 375    * This method is called when the touch is interrupted.
 376    * Could be reimplemented in subclasses to provide specific behaviour.
 377    */
 378   virtual void OnTouchPointInterrupted();
 379
 380   /**
 381    * This method is called when the \e selected property is changed.
 382    */
 383   virtual void OnStateChange( State newState ){}
 384
 385   /**
 386    * This method is called when the \e disabled property is changed.
 387    */
 388   virtual void OnDisabled() {}
 389
 390   /**
 391    * This method is called when the button is pressed.
 392    */
 393   virtual void OnPressed() {}
 394
 395   /**
 396    * This method is called when the button is released.
 397    */
 398   virtual void OnReleased() {}
 399
 400 public:
 401
 402   /**
 403    * @copydoc Dali::Toolkit::PushButton::PressedSignal()
 404    */
 405   Toolkit::Button::ButtonSignalType& PressedSignal();
 406
 407   /**
 408    * @copydoc Dali::Toolkit::PushButton::ReleasedSignal()
 409    */
 410   Toolkit::Button::ButtonSignalType& ReleasedSignal();
 411
 412   /**
 413    * @copydoc Dali::Toolkit::Button::ClickedSignal()
 414    */
 415   Toolkit::Button::ButtonSignalType& ClickedSignal();
 416
 417   /**
 418    * @copydoc Dali::Toolkit::Button::StateChangedSignal()
 419    */
 420   Toolkit::Button::ButtonSignalType& StateChangedSignal();
 421
 422   /**
 423    * Connects a callback function with the object's signals.
 424    * @param[in] object The object providing the signal.
 425    * @param[in] tracker Used to disconnect the signal.
 426    * @param[in] signalName The signal to connect to.
 427    * @param[in] functor A newly allocated FunctorDelegate.
 428    * @return True if the signal was connected.
 429    * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
 430    */
 431   static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
 432
 433   // Properties
 434
 435   /**
 436    * Called when a property of an object of this type is set.
 437    * @param[in] object The object whose property is set.
 438    * @param[in] index The property index.
 439    * @param[in] value The new property value.
 440    */
 441   static void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
 442
 443   /**
 444    * Called to retrieve a property of an object of this type.
 445    * @param[in] object The object whose property is to be retrieved.
 446    * @param[in] index The property index.
 447    * @return The current value of the property.
 448    */
 449   static Property::Value GetProperty( BaseObject* object, Property::Index propertyIndex );
 450
 451 protected: // From Control
 452
 453   /**
 454    * @copydoc Toolkit::Control::OnInitialize()
 455    * @note If overridden by deriving button classes, then an up-call to Button::OnInitialize MUST be made at the start.
 456    */
 457   virtual void OnInitialize();
 458
 459   /**
 460    * @copydoc Toolkit::Control::OnAccessibilityActivated()
 461    */
 462   virtual bool OnAccessibilityActivated();
 463
 464   /**
 465    * @copydoc Toolkit::Control::OnKeyboardEnter()
 466    */
 467   virtual bool OnKeyboardEnter();
 468
 469   /**
 470    * @copydoc Toolkit::Control::OnStageDisconnection()
 471    * @note If overridden by deriving button classes, then an up-call to Button::OnStageDisconnection MUST be made at the end.
 472    */
 473   virtual void OnStageDisconnection();
 474
 475   /**
 476    * @copydoc Toolkit::Control::OnStageConnnection()
 477    */
 478   virtual void OnStageConnection( int depth );
 479
 480   /**
 481    * @copydoc Toolkit::Control::GetNaturalSize
 482    */
 483   virtual Vector3 GetNaturalSize();
 484
 485   /**
 486    * @copydoc Toolkit::Control::OnSetResizePolicy
 487    */
 488   virtual void OnSetResizePolicy( ResizePolicy::Type policy, Dimension::Type dimension );
 489
 490   /**
 491    * @copydoc Toolkit::Control::OnRelayout
 492    */
 493   virtual void OnRelayout( const Vector2& size, RelayoutContainer& container );
 494
 495 private:
 496
 497   /**
 498    * @brief Handler for touch data
 499    * @param[in]  actor  The touched actor.
 500    * @param[in]  touch  The touch info.
 501    * @return true, if consumed, false otherwise.
 502    */
 503   bool OnTouch( Actor actor, const TouchData& touch );
 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    * Button has been pressed
 523    */
 524   void Pressed();
 525
 526   /**
 527    * This method is called the button is down.
 528    */
 529   void ButtonDown();
 530
 531   /**
 532    * This method is called when the button is up.
 533    */
 534   void ButtonUp();
 535
 536   /**
 537    * Slot called when Dali::Timer::SignalTick signal. Resets the autorepeating timer.
 538    */
 539   bool AutoRepeatingSlot();
 540
 541   /**
 542    *  Check the requested state is an allowed transition.
 543    *  Some states can not be transitioned to from certain states.
 544    *  @param[in] requestedState check if can transition to this state
 545    *  @return bool true if state change valid
 546    */
 547   bool ValidateState( State requestedState );
 548
 549   /**
 550    * Perform the given function on the visuals in the given state. Can be used to add and remove visuals.
 551    * @param[in] functionPtr pointer to the function to perform an action on a visual
 552    * @param[in] state Visuals in this state will be the target
 553    */
 554   void PerformFunctionOnVisualsInState( void(Button::*functionPtr)( Property::Index visualIndex), State state  );
 555
 556   /**
 557    * Changes the button state when an action occurs on it
 558    * @param[in] requestedState the state to change to
 559    */
 560   void ChangeState( State requestedState );
 561
 562   /**
 563    * @brief Get unselected button color
 564    * @return color as vector4
 565    */
 566   const Vector4 GetUnselectedColor() const;
 567
 568   /**
 569    * @brief Get selected button color
 570    * @return color as vector4
 571    */
 572   const Vector4 GetSelectedColor() const;
 573
 574   /**
 575    * Sets the color of button in selected or unselected state, if image also supplied this color will be appplied to it.
 576    * If no visual exists, it is created.
 577    * @param[in]  color The color to use.
 578    * @param[in]  visualIndex The Visual to apply the color
 579    */
 580   void SetColor( const Vector4& color, Property::Index visualIndex );
 581
 582   /**
 583    * This method is called when the button is released.
 584    */
 585   void Released();
 586
 587 protected:
 588
 589   /**
 590    * Set Text Label Padding
 591    * @param[in] padding BEGIN END BOTTOM TOP
 592    */
 593   void SetLabelPadding( const Padding& padding );
 594
 595   /**
 596    * Get Text Label padding
 597    * @return Padding
 598    */
 599   Padding GetLabelPadding();
 600
 601   /**
 602    * Set Foreground/icon Padding
 603    * @param[in] padding BEGIN END BOTTOM TOP
 604    */
 605   void SetForegroundPadding( const Padding& padding);
 606
 607   /**
 608    * Get Foreground padding
 609    * @ return Padding
 610    */
 611   Padding GetForegroundPadding();
 612
 613   /**
 614    * @brief Setup the button components for example foregrounds and background
 615    * @param[in] index the index of the visual to set
 616    * @param[in] value the value to set on the component
 617    * @param[in] visualDepth the depth of the visual if overlapping another
 618    */
 619   void CreateVisualsForComponent( Property::Index index ,const Property::Value& value, const float visualDepth );
 620
 621   /**
 622    * Returns the animation to be used for transition, creating the animation if needed.
 623    * @return The initialised transition animation.
 624    */
 625   Dali::Animation GetTransitionAnimation();
 626
 627   /**
 628    * @brief Set the position of the label relative to foreground/icon, if both present
 629    * @param[in] labelAlignment given alignment setting
 630    */
 631   void SetLabelAlignment( Align labelAlignment);
 632
 633   /**
 634    * @brief Get set alignment of label in relation to foreground/icon
 635    * @return Set alignment value
 636    */
 637   Align GetLabelAlignment();
 638
 639   /**
 640    * Removes the visual from the button (un-staged)
 641    * If the derived button does not want the visual removed then use this virtual function to
 642    * define the required behaviour.
 643    * Can decide to only remove specified visuals via index
 644    */
 645   virtual void OnButtonVisualRemoval( Property::Index visualIndex );
 646
 647
 648 private:
 649
 650   /**
 651    * Removes the visual from the button and prepares it to be transitioned out
 652    * @param[in] visualIndex the visual to remove
 653    */
 654   void RemoveVisual( Property::Index visualIndex );
 655
 656   /**
 657    * Adds the required visual to the button.
 658    * @param[in] visualIndex The Property index of the visual required
 659    */
 660   void SelectRequiredVisual( Property::Index visualIndex );
 661
 662   // Undefined
 663   Button( const Button& );
 664
 665   // Undefined
 666   Button& operator = ( const Button& );
 667
 668 private:
 669
 670   // Signals
 671   Toolkit::Button::ButtonSignalType mPressedSignal;           ///< Signal emitted when the button is pressed.
 672   Toolkit::Button::ButtonSignalType mReleasedSignal;          ///< Signal emitted when the button is released.
 673   Toolkit::Button::ButtonSignalType mClickedSignal;           ///< Signal emitted when the button is clicked.
 674   Toolkit::Button::ButtonSignalType mStateChangedSignal;      ///< Signal emitted when the button's state is changed.
 675
 676   Timer            mAutoRepeatingTimer;
 677
 678   Actor            mLabel;                      ///< Stores the button text label.
 679   Padding          mLabelPadding;               ///< The padding around the label (if present).
 680   Padding          mForegroundPadding;          ///< The padding around the foreground/icon visual (if present).
 681
 682   Align            mTextLabelAlignment;           ///< Position of text label in relation to foreground/icon when both are present.
 683
 684   TapGestureDetector mTapDetector;
 685
 686   Vector4          mUnselectedColor;
 687   Vector4          mSelectedColor;
 688
 689   bool             mAutoRepeating;              ///< Stores the autorepeating property.
 690   bool             mTogglableButton;            ///< Stores the togglable property as a flag.
 691   float            mInitialAutoRepeatingDelay;  ///< Stores the initial autorepeating delay in seconds.
 692   float            mNextAutoRepeatingDelay;     ///< Stores the next autorepeating delay in seconds.
 693
 694   float            mAnimationTime;
 695
 696   PressState       mButtonPressedState;         ///< In relation to the button being pressed/released
 697   State            mButtonState;
 698   State            mPreviousButtonState;        ///< During a transition between two states, this stores the previous state so Visuals can be removed.
 699
 700   // Actions
 701   bool             mClickActionPerforming;      ///< Used to manage signal emissions during action
 702 };
 703
 704 } // namespace Internal
 705
 706 // Helpers for public-api forwarding methods
 707
 708 inline Toolkit::Internal::Button& GetImplementation( Toolkit::Button& button )
 709 {
 710   DALI_ASSERT_ALWAYS( button );
 711
 712   Dali::RefObject& handle = button.GetImplementation();
 713
 714   return static_cast<Toolkit::Internal::Button&>( handle );
 715 }
 716
 717 inline const Toolkit::Internal::Button& GetImplementation( const Toolkit::Button& button )
 718 {
 719   DALI_ASSERT_ALWAYS( button );
 720
 721   const Dali::RefObject& handle = button.GetImplementation();
 722
 723   return static_cast<const Toolkit::Internal::Button&>( handle );
 724 }
 725
 726 } // namespace Toolkit
 727
 728 } // namespace Dali
 729
 730 #endif // DALI_TOOLKIT_INTERNAL_BUTTON_H