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) 2020 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    * @brief Sets the button as \e disabled.
  73    * @param[in] disabled Disabled property
  74    */
  75   void SetDisabled( bool disabled );
  76
  77   /**
  78    * @brief Returns if the button is disabled.
  79    * @return \e true if the button is \e disabled
  80    */
  81   bool IsDisabled() const;
  82
  83   /**
  84    * @brief Sets the \e autorepeating property.
  85    * @param[in] autoRepeating \e autorepeating property
  86    */
  87   void SetAutoRepeating( bool autoRepeating );
  88
  89   /**
  90    * @brief Sets the initial autorepeating delay.
  91    * @param[in] initialAutoRepeatingDelay in seconds
  92    */
  93   void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
  94
  95   /**
  96    * @brief Sets the next autorepeating delay.
  97    * @param[in] nextAutoRepeatingDelay in seconds
  98    */
  99   void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
 100
 101   /**
 102    * @brief Sets the \e togglable property.
 103    * @param[in] togglable Togglable property
 104    */
 105   void SetTogglableButton( bool togglable );
 106
 107   /**
 108    * @brief Sets the button as selected or unselected.
 109    * @param[in] selected Selected property
 110    */
 111   void SetSelected( bool selected );
 112
 113   /**
 114    * @brief Returns if the selected property is set and the button is togglable.
 115    * @return \e true if the button is \e selected
 116    */
 117   bool IsSelected() const;
 118
 119   /**
 120    * @brief Produces a Property::Map of Text properties to create a Text Visual, merging existing properties with supplied map
 121    * If the label does not exist yet, it is created.
 122    * The derived buttons are notified if any properties are changed.
 123    * @param[in] properties A Property::Map of key-value pairs of properties to set.
 124    * @param[out] properties A Property::Map of text visual properties to set after merging inMap with existing maps
 125    */
 126   void MergeWithExistingLabelProperties( const Property::Map& inMap, Property::Map& outMap );
 127
 128   /**
 129    * Performs actions as requested using the action name.
 130    * @param[in] object The object on which to perform the action.
 131    * @param[in] actionName The action to perform.
 132    * @param[in] attributes The attributes with which to perfrom this action.
 133    * @return true if action has been accepted by this control
 134    */
 135   static bool DoAction( BaseObject* object, const std::string& actionName, const Property::Map& attributes );
 136
 137 public:
 138
 139   /**
 140    * Button's state
 141    */
 142   enum State
 143   {
 144     UNSELECTED_STATE,              ///< The button is unselected.
 145     SELECTED_STATE,                ///< The button is selected.
 146     DISABLED_UNSELECTED_STATE,     ///< The button is disabled and unselected.
 147     DISABLED_SELECTED_STATE,       ///< The button is disabled and selected.
 148     STATE_COUNT,                   ///< Number of States
 149   };
 150
 151   /**
 152    * Enum to distinguish the different style-able components of the button
 153    */
 154   enum Visuals
 155   {
 156     UNSELECTED_FOREGROUND = 0,
 157     SELECTED_FOREGROUND,
 158     DISABLED_SELECTED_FOREGROUND,
 159     DISABLED_UNSELECTED_FOREGROUND,
 160     UNSELECTED_BACKGROUND,
 161     SELECTED_BACKGROUND,
 162     DISABLED_UNSELECTED_BACKGROUND,
 163     DISABLED_SELECTED_BACKGROUND,
 164     VISUALS_COUNT
 165   };
 166
 167   /**
 168    * Enum to list types of visual a state can have.
 169    */
 170   enum VisualState
 171   {
 172     BACKGROUND = 0,
 173     FOREGROUND,
 174     VISUAL_STATE_COUNT
 175   };
 176
 177 protected:
 178
 179   /**
 180    * Button press state which is not the same as the actual button's state.
 181    * For example An UNSELECTED button can be DEPRESSED, but until released, the actual button state doesn't change to SELECTED
 182    */
 183   enum PressState
 184   {
 185     DEPRESSED,                           ///< The button is up.
 186     UNPRESSED,                           ///< The button is down.
 187     TOGGLE_DEPRESSED,                    ///< The button has been pressed down and will stay depressed when released.
 188   };
 189
 190   /**
 191    * Construct a new Button.
 192    */
 193   Button();
 194
 195   /**
 196    * A reference counted object may only be deleted by calling Unreference()
 197    */
 198   virtual ~Button();
 199   /**
 200    * @return A reference to the label actor.
 201    */
 202   Actor& GetLabelActor();
 203
 204   /**
 205    * @return A reference to the unselected button image.
 206    */
 207   Actor GetUnselectedImage();
 208
 209   /**
 210    * @return A reference to the selected image.
 211    */
 212   Actor GetSelectedImage();
 213
 214 private:
 215
 216   /**
 217    * Perform the click action to click the button.
 218    * @param[in] attributes The attributes to perfrom this action.
 219    * @return true if this control can perform action.
 220    */
 221   bool DoClickAction( const Property::Map& attributes );
 222
 223   /**
 224    * This method is called when the button is a Toggle button and released
 225    * Could be reimplemented in subclasses to provide specific behaviour.
 226    * @return bool returns true if state changed.
 227    */
 228   virtual bool OnToggleReleased();
 229
 230   /**
 231    * This method is called when touch leaves the boundary of the button or several touch points are received.
 232    * Could be reimplemented in subclasses to provide specific behaviour.
 233    */
 234   virtual void OnTouchPointLeave();
 235
 236   /**
 237    * This method is called when the touch is interrupted.
 238    * Could be reimplemented in subclasses to provide specific behaviour.
 239    */
 240   virtual void OnTouchPointInterrupted();
 241
 242   /**
 243    * This method is called when the \e selected property is changed.
 244    */
 245   virtual void OnStateChange( State newState ){}
 246
 247   /**
 248    * This method is called when the \e disabled property is changed.
 249    */
 250   virtual void OnDisabled() {}
 251
 252   /**
 253    * This method is called when the button is pressed.
 254    */
 255   virtual void OnPressed() {}
 256
 257   /**
 258    * This method is called when the button is released.
 259    */
 260   virtual void OnReleased() {}
 261
 262 public:
 263
 264   /**
 265    * @copydoc Dali::Toolkit::PushButton::PressedSignal()
 266    */
 267   Toolkit::Button::ButtonSignalType& PressedSignal();
 268
 269   /**
 270    * @copydoc Dali::Toolkit::PushButton::ReleasedSignal()
 271    */
 272   Toolkit::Button::ButtonSignalType& ReleasedSignal();
 273
 274   /**
 275    * @copydoc Dali::Toolkit::Button::ClickedSignal()
 276    */
 277   Toolkit::Button::ButtonSignalType& ClickedSignal();
 278
 279   /**
 280    * @copydoc Dali::Toolkit::Button::StateChangedSignal()
 281    */
 282   Toolkit::Button::ButtonSignalType& StateChangedSignal();
 283
 284   /**
 285    * Connects a callback function with the object's signals.
 286    * @param[in] object The object providing the signal.
 287    * @param[in] tracker Used to disconnect the signal.
 288    * @param[in] signalName The signal to connect to.
 289    * @param[in] functor A newly allocated FunctorDelegate.
 290    * @return True if the signal was connected.
 291    * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
 292    */
 293   static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
 294
 295   // Properties
 296
 297   /**
 298    * Called when a property of an object of this type is set.
 299    * @param[in] object The object whose property is set.
 300    * @param[in] index The property index.
 301    * @param[in] value The new property value.
 302    */
 303   static void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
 304
 305   /**
 306    * Called to retrieve a property of an object of this type.
 307    * @param[in] object The object whose property is to be retrieved.
 308    * @param[in] index The property index.
 309    * @return The current value of the property.
 310    */
 311   static Property::Value GetProperty( BaseObject* object, Property::Index propertyIndex );
 312
 313 protected: // From Control
 314
 315   /**
 316    * @copydoc Toolkit::Control::OnInitialize()
 317    * @note If overridden by deriving button classes, then an up-call to Button::OnInitialize MUST be made at the start.
 318    */
 319   virtual void OnInitialize();
 320
 321   /**
 322    * @copydoc Toolkit::Control::OnAccessibilityActivated()
 323    */
 324   virtual bool OnAccessibilityActivated();
 325
 326   /**
 327    * @copydoc Toolkit::Control::OnKeyboardEnter()
 328    */
 329   virtual bool OnKeyboardEnter();
 330
 331   /**
 332    * @copydoc Toolkit::Control::OnSceneDisconnection()
 333    * @note If overridden by deriving button classes, then an up-call to Button::OnSceneDisconnection MUST be made at the end.
 334    */
 335   virtual void OnSceneDisconnection();
 336
 337   /**
 338    * @copydoc Toolkit::Control::OnSceneConnection()
 339    */
 340   virtual void OnSceneConnection( int depth );
 341
 342   /**
 343    * @copydoc Toolkit::Control::GetNaturalSize
 344    */
 345   virtual Vector3 GetNaturalSize();
 346
 347   /**
 348    * @copydoc Toolkit::Control::OnSetResizePolicy
 349    */
 350   virtual void OnSetResizePolicy( ResizePolicy::Type policy, Dimension::Type dimension );
 351
 352   /**
 353    * @copydoc Toolkit::Control::OnRelayout
 354    */
 355   virtual void OnRelayout( const Vector2& size, RelayoutContainer& container );
 356
 357 private:
 358
 359   /**
 360    * @brief Handler for touch data
 361    * @param[in]  actor  The touched actor.
 362    * @param[in]  touch  The touch info.
 363    * @return true, if consumed, false otherwise.
 364    */
 365   bool OnTouch( Actor actor, const TouchEvent& touch );
 366
 367   /**
 368    * Handler for tap events.
 369    * We do not actually do anything when we receive a tap as the button handles tap event through
 370    * the touch event system itself as it requires more than just tap handling (e.g. leave events).
 371    * This stops any of our parents receiving a tap gesture when it occurs within our area.
 372    * @param[in]  actor  The tapped actor.
 373    * @param[in]  tap    The tap gesture.
 374    */
 375   void OnTap(Actor actor, const TapGesture& tap);
 376
 377   /**
 378    * Sets up the autorepeating timer.
 379    * @param[in] delay The delay time in seconds.
 380    */
 381   void SetUpTimer( float delay );
 382
 383   /**
 384    * Button has been pressed
 385    */
 386   void Pressed();
 387
 388   /**
 389    * This method is called the button is down.
 390    */
 391   void ButtonDown();
 392
 393   /**
 394    * This method is called when the button is up.
 395    */
 396   void ButtonUp();
 397
 398   /**
 399    * Slot called when Dali::Timer::SignalTick signal. Resets the autorepeating timer.
 400    */
 401   bool AutoRepeatingSlot();
 402
 403   /**
 404    *  Check the requested state is an allowed transition.
 405    *  Some states can not be transitioned to from certain states.
 406    *  @param[in] requestedState check if can transition to this state
 407    *  @return bool true if state change valid
 408    */
 409   bool ValidateState( State requestedState );
 410
 411   /**
 412    * Changes the button state when an action occurs on it
 413    * @param[in] requestedState the state to change to
 414    */
 415   void ChangeState( State requestedState );
 416
 417   /**
 418    * This method is called when the button is released.
 419    */
 420   void Released();
 421
 422 protected:
 423
 424   /**
 425    * Set Text Label Padding
 426    * @param[in] padding BEGIN END BOTTOM TOP
 427    */
 428   void SetLabelPadding( const Padding& padding );
 429
 430   /**
 431    * Get Text Label padding
 432    * @return Padding
 433    */
 434   Padding GetLabelPadding();
 435
 436   /**
 437    * Set Foreground/icon Padding
 438    * @param[in] padding BEGIN END BOTTOM TOP
 439    */
 440   void SetForegroundPadding( const Padding& padding);
 441
 442   /**
 443    * Get Foreground padding
 444    * @ return Padding
 445    */
 446   Padding GetForegroundPadding();
 447
 448   /**
 449    * @brief Setup the button components for example foregrounds and background
 450    * @param[in] index the index of the visual to set
 451    * @param[in] value the value to set on the component
 452    * @param[in] visualDepth the depth of the visual if overlapping another
 453    */
 454   void CreateVisualsForComponent( Property::Index index, const Property::Value& value, const int visualDepth );
 455
 456   /**
 457    * @brief Get the Property map for the given Visual
 458    * @param[in] visualIndex visual index of the required visual
 459    * @param[out] retreivedMap the property map used to construct the required visual
 460    * @return bool success flag, true if visual found
 461    */
 462   bool GetPropertyMapForVisual( Property::Index visualIndex, Property::Map& retreivedMap ) const;
 463   /**
 464    * Returns the animation to be used for transition, creating the animation if needed.
 465    * @return The initialised transition animation.
 466    */
 467   Dali::Animation GetTransitionAnimation();
 468
 469   /**
 470    * @brief Set the position of the label relative to foreground/icon, if both present
 471    * @param[in] labelAlignment given alignment setting
 472    */
 473   void SetLabelAlignment( Align labelAlignment);
 474
 475   /**
 476    * @brief Get set alignment of label in relation to foreground/icon
 477    * @return Set alignment value
 478    */
 479   Align GetLabelAlignment();
 480
 481   /**
 482    * Removes the visual from the button (un-staged)
 483    * If the derived button does not want the visual removed then use this virtual function to
 484    * define the required behaviour.
 485    * Can decide to only remove specified visuals via index
 486    */
 487   virtual void OnButtonVisualRemoval( Property::Index visualIndex );
 488
 489
 490 private:
 491
 492   /**
 493    * Removes the visual from the button and prepares it to be transitioned out
 494    * @param[in] visualIndex the visual to remove
 495    */
 496   void RemoveVisual( Property::Index visualIndex );
 497
 498   /**
 499    * Adds the required visual to the button.
 500    * @param[in] visualIndex The Property index of the visual required
 501    */
 502   void SelectRequiredVisual( Property::Index visualIndex );
 503
 504   // Undefined
 505   Button( const Button& );
 506
 507   // Undefined
 508   Button& operator = ( const Button& );
 509
 510 private:
 511
 512   // Signals
 513   Toolkit::Button::ButtonSignalType mPressedSignal;           ///< Signal emitted when the button is pressed.
 514   Toolkit::Button::ButtonSignalType mReleasedSignal;          ///< Signal emitted when the button is released.
 515   Toolkit::Button::ButtonSignalType mClickedSignal;           ///< Signal emitted when the button is clicked.
 516   Toolkit::Button::ButtonSignalType mStateChangedSignal;      ///< Signal emitted when the button's state is changed.
 517
 518   Timer            mAutoRepeatingTimer;
 519
 520   Actor            mLabel;                      ///< Stores the button text label.
 521   Padding          mLabelPadding;               ///< The padding around the label (if present).
 522   Padding          mForegroundPadding;          ///< The padding around the foreground/icon visual (if present).
 523
 524   Align            mTextLabelAlignment;           ///< Position of text label in relation to foreground/icon when both are present.
 525
 526   TapGestureDetector mTapDetector;
 527
 528   bool             mAutoRepeating;              ///< Stores the autorepeating property.
 529   bool             mTogglableButton;            ///< Stores the togglable property as a flag.
 530   bool             mTextStringSetFlag;          ///< Stores if text has been set. Required in relayout but don't want to calculate there.
 531
 532   float            mInitialAutoRepeatingDelay;  ///< Stores the initial autorepeating delay in seconds.
 533   float            mNextAutoRepeatingDelay;     ///< Stores the next autorepeating delay in seconds.
 534
 535   float            mAnimationTime;
 536
 537   PressState       mButtonPressedState;         ///< In relation to the button being pressed/released
 538   State            mButtonState;
 539   State            mPreviousButtonState;        ///< During a transition between two states, this stores the previous state so Visuals can be removed.
 540
 541   // Actions
 542   bool             mClickActionPerforming;      ///< Used to manage signal emissions during action
 543 };
 544
 545 } // namespace Internal
 546
 547 // Helpers for public-api forwarding methods
 548
 549 inline Toolkit::Internal::Button& GetImplementation( Toolkit::Button& button )
 550 {
 551   DALI_ASSERT_ALWAYS( button );
 552
 553   Dali::RefObject& handle = button.GetImplementation();
 554
 555   return static_cast<Toolkit::Internal::Button&>( handle );
 556 }
 557
 558 inline const Toolkit::Internal::Button& GetImplementation( const Toolkit::Button& button )
 559 {
 560   DALI_ASSERT_ALWAYS( button );
 561
 562   const Dali::RefObject& handle = button.GetImplementation();
 563
 564   return static_cast<const Toolkit::Internal::Button&>( handle );
 565 }
 566
 567 } // namespace Toolkit
 568
 569 } // namespace Dali
 570
 571 #endif // DALI_TOOLKIT_INTERNAL_BUTTON_H