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