dali-toolkit/public-api/controls/buttons/button.h

   1 #ifndef __DALI_TOOLKIT_BUTTON_H__
   2 #define __DALI_TOOLKIT_BUTTON_H__
   3
   4 /*
   5  * Copyright (c) 2018 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 // INTERNAL INCLUDES
  22 #include <dali-toolkit/public-api/controls/control.h>
  23
  24 namespace Dali
  25 {
  26
  27 namespace Toolkit
  28 {
  29
  30 namespace Internal DALI_INTERNAL
  31 {
  32 class Button;
  33 }
  34 /**
  35  * @addtogroup dali_toolkit_controls_buttons
  36  * @{
  37  */
  38
  39 /**
  40  * @brief Button is a base class for different kinds of buttons.
  41  *
  42  * This class provides the disabled property and the clicked signal.
  43  *
  44  * A ClickedSignal() is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
  45  *
  46  * When the \e disabled property is set to \e true, no signal is emitted.
  47  *
  48  * Button provides the following properties which modify the signals emitted:
  49  * <ul>
  50  *   <li>\e autorepeating
  51  *       When \e autorepeating is set to \e true, a Button::PressedSignal(), Button::ReleasedSignal() and Button::ClickedSignal() signals are emitted at regular
  52  *       intervals while the button is touched.
  53  *       The intervals could be modified with the Button::SetInitialAutoRepeatingDelay and Button::SetNextAutoRepeatingDelay methods.
  54  *
  55  *       A \e togglable button can't be \e autorepeating. If the \e autorepeating property is set to \e true, then the \e togglable property is set to
  56  *       false but no signal is emitted.
  57  *
  58  *   <li>\e togglable
  59  *       When \e togglable is set to \e true, a Button::StateChangedSignal() signal is emitted, with the selected state.
  60  * </ul>
  61  *
  62  * 'Visual' describes not just traditional images like png, bmp but refers to whatever is used to show the button, it could be a color, gradient or some other kind of renderer.
  63  *
  64  * The button's appearance can be modified by setting properties for the various visuals/images.
  65  *
  66  * It is not mandatory to set all visuals. A button could be defined only by setting its \e background visual or by setting its \e background and \e selected visuals.
  67  *
  68  * The \e button visual is shown over the \e background visual.
  69  * When pressed the unselected visuals are replaced by the \e selected visual. The text label is always placed on the top of all images.
  70  *
  71  * When the button is disabled, \e background, \e button and \e selected visuals are replaced by their \e disabled visuals.
  72  *
  73  *
  74  * Signals
  75  * | %Signal Name     | Method                      |
  76  * |------------------|-----------------------------|
  77  * | pressed          | @ref PressedSignal()        |
  78  * | released         | @ref ReleasedSignal()       |
  79  * | clicked          | @ref ClickedSignal()        |
  80  * | stateChanged     | @ref StateChangedSignal()   |
  81  *
  82  * Actions
  83  * | %Action Name     | Attributes              | Description                                   |
  84  * |------------------|-------------------------|-----------------------------------------------|
  85  * | buttonClick      | Doesn't have attributes | Simulates a button click. See @ref DoAction() |
  86  * @SINCE_1_0.0
  87  */
  88 class DALI_TOOLKIT_API Button : public Control
  89 {
  90 public:
  91
  92   /**
  93    * @brief Enumeration for the start and end property ranges for this control.
  94    * @SINCE_1_0.0
  95    */
  96   enum PropertyRange
  97   {
  98     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
  99     PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000              ///< Reserve property indices @SINCE_1_0.0
 100   };
 101
 102   /**
 103    * @brief Enumeration for the instance of properties belonging to the Button class.
 104    * @SINCE_1_0.0
 105    */
 106   struct Property
 107   {
 108     /**
 109      * @brief Enumeration for the instance of properties belonging to the Button class.
 110      * @SINCE_1_0.0
 111      */
 112     enum
 113     {
 114       /**
 115        * @brief name "disabled", type bool
 116        * @details Sets the button as \e disabled.
 117        * @SINCE_1_0.0
 118        */
 119       DISABLED = PROPERTY_START_INDEX,
 120
 121       /**
 122        * @brief name "autoRepeating", type bool
 123        * @details If the \e autorepeating property is set to \e true then the \e togglable property is set to false
 124        * @SINCE_1_0.0
 125        */
 126       AUTO_REPEATING,
 127
 128       /**
 129        * @brief name "initialAutoRepeatingDelay", type float
 130        * @details By default this value is set to 0.15 seconds.
 131        * @SINCE_1_0.0
 132        */
 133       INITIAL_AUTO_REPEATING_DELAY,
 134
 135       /**
 136        * @brief name "nextAutoRepeatingDelay", type float
 137        * @details default this value is set to 0.05 seconds
 138        * @SINCE_1_0.0
 139        */
 140       NEXT_AUTO_REPEATING_DELAY,
 141
 142       /**
 143        * @brief name "togglable", type bool
 144        * @details If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
 145        * @SINCE_1_0.0
 146        */
 147       TOGGLABLE,
 148
 149       /**
 150        * @brief name "selected", type bool
 151        * @details Sets the togglable button as either selected or unselected, \e togglable property must be set to \e true.
 152        * @SINCE_1_0.0
 153        */
 154       SELECTED,
 155
 156       /**
 157        * @DEPRECATED_1_1.XX Use UNSELECTED_VISUAL
 158        * @brief name "unselectedStateImage", type string if it is a url, map otherwise
 159        * @details Sets the unselected button foreground image
 160        * @SINCE_1_0.0
 161        */
 162       UNSELECTED_STATE_IMAGE,
 163
 164       /**
 165        * @DEPRECATED_1_1.XX Use SELECTED_VISUAL
 166        * @brief name "selectedStateImage", type string if it is a url, map otherwise
 167        * @details Sets the selected button foreground image
 168        * @SINCE_1_0.0
 169        */
 170       SELECTED_STATE_IMAGE,
 171
 172       /**
 173        * @DEPRECATED_1_1.XX Use DISABLED_UNSELECTED_VISUAL
 174        * @brief name "disabledStateImage", type string if it is a url, map otherwise
 175        * @details Sets the disabled whilst unselected foreground button visual
 176        * @SINCE_1_0.0
 177        */
 178       DISABLED_STATE_IMAGE,
 179
 180       /**
 181        * @DEPRECATED_1_1.XX Use UNSELECTED_BACKGROUND_VISUAL
 182        * @brief name "unselectedColor", type Vector4
 183        * @SINCE_1_0.0
 184        */
 185       UNSELECTED_COLOR,
 186
 187       /**
 188        * @DEPRECATED_1_1.XX Use SELECTED_BACKGROUND_VISUAL
 189        * @brief name "selectedColor", type Vector4
 190        * @SINCE_1_0.0
 191        */
 192       SELECTED_COLOR,
 193
 194       /**
 195        * @brief name "label", type Property::Map or std::string
 196        * @SINCE_1_0.0
 197        */
 198       LABEL,
 199
 200       /**
 201        * @DEPRECATED_1_1.32 Use LABEL
 202        * @brief name "labelText", type std::string
 203        * @SINCE_1_0.0
 204        */
 205       LABEL_TEXT
 206     };
 207   };
 208
 209 public:
 210
 211   /**
 212    * @brief Creates an uninitialized Button.
 213    *
 214    * Only derived versions can be instantiated.  Calling member
 215    * functions with an uninitialized Dali::Object is not allowed.
 216    * @SINCE_1_0.0
 217    */
 218   Button();
 219
 220   /**
 221    * @brief Copy constructor.
 222    * @SINCE_1_0.0
 223    * @param[in] button Handle to an object
 224    */
 225   Button( const Button& button );
 226
 227   /**
 228    * @brief Assignment operator.
 229    * @SINCE_1_0.0
 230    * @param[in] button Handle to an object
 231    * @return A reference to this
 232    */
 233   Button& operator=( const Button& button );
 234
 235   /**
 236    * @brief Downcasts a handle to Button handle.
 237    *
 238    * If handle points to a Button, the downcast produces valid handle.
 239    * If not the returned handle is left uninitialized.
 240    *
 241    * @SINCE_1_0.0
 242    * @param[in] handle Handle to an object
 243    * @return A handle to a Button or an uninitialized handle
 244    */
 245   static Button DownCast( BaseHandle handle );
 246
 247   /**
 248    * @brief Destructor.
 249    *
 250    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 251    * @SINCE_1_0.0
 252    */
 253   ~Button();
 254
 255   // Deprecated API
 256
 257   /**
 258    * @DEPRECATED_1_1.32 Use SetProperty DISABLED or Styling file
 259    *
 260    * @brief Sets the button as \e disabled.
 261    *
 262    * No signals are emitted when the \e disabled property is set.
 263    *
 264    * @SINCE_1_0.0
 265    * @param[in] disabled Disabled property
 266    */
 267   void SetDisabled( bool disabled ) DALI_DEPRECATED_API;
 268
 269   /**
 270    * @DEPRECATED_1_1.32 Use GetProperty DISABLED
 271    *
 272    * @brief Returns if the button is disabled.
 273    * @SINCE_1_0.0
 274    * @return \e true if the button is \e disabled
 275    */
 276   bool IsDisabled() const DALI_DEPRECATED_API;
 277
 278   /**
 279    * @DEPRECATED_1_1.32 SetProperty AUTO_REPEATING or Styling file
 280    *
 281    * @brief Sets the \e autorepeating property.
 282    *
 283    * If the \e autorepeating property is set to \e true, then the \e togglable property is set to false
 284    * but no signal is emitted.
 285    *
 286    * @SINCE_1_0.0
 287    * @param[in] autoRepeating \e autorepeating property
 288    */
 289   void SetAutoRepeating( bool autoRepeating ) DALI_DEPRECATED_API;
 290
 291   /**
 292    * @DEPRECATED_1_1.32 GetProperty AUTO_REPEATING
 293    *
 294    * @brief Returns if the autorepeating property is set.
 295    * @SINCE_1_0.0
 296    * @return \e true if the \e autorepeating property is set
 297    */
 298   bool IsAutoRepeating() const DALI_DEPRECATED_API;
 299
 300   /**
 301    * @DEPRECATED_1_1.32 SetProperty INITIAL_AUTO_REPEATING_DELAY or Styling file
 302    *
 303    * @brief Sets the initial autorepeating delay.
 304    *
 305    * By default, this value is set to 0.15 seconds.
 306    *
 307    * @SINCE_1_0.0
 308    * @param[in] initialAutoRepeatingDelay in seconds
 309    * @pre initialAutoRepeatingDelay must be greater than zero.
 310    */
 311   void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay ) DALI_DEPRECATED_API;
 312
 313   /**
 314    * @DEPRECATED_1_1.32 GetProperty INITIAL_AUTO_REPEATING_DELAY
 315    *
 316    * @brief Gets the initial autorepeating delay in seconds.
 317    * @SINCE_1_0.0
 318    * @return The initial autorepeating delay in seconds
 319    */
 320   float GetInitialAutoRepeatingDelay() const DALI_DEPRECATED_API;
 321
 322   /**
 323    * @DEPRECATED_1_1.32 SetProperty NEXT_AUTO_REPEATING_DELAY or Styling file
 324    *
 325    * @brief Sets the next autorepeating delay.
 326    *
 327    * By default, this value is set to 0.05 seconds.
 328    *
 329    * @SINCE_1_0.0
 330    * @param[in] nextAutoRepeatingDelay in seconds
 331    * @pre nextAutoRepeatingDelay must be greater than zero.
 332    */
 333   void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay ) DALI_DEPRECATED_API;
 334
 335   /**
 336    * @DEPRECATED_1_1.32 GetProperty NEXT_AUTO_REPEATING_DELAY
 337    *
 338    * @brief Gets the next autorepeating delay in seconds.
 339    * @SINCE_1_0.0
 340    * @return The next autorepeating delay in seconds
 341    */
 342   float GetNextAutoRepeatingDelay() const DALI_DEPRECATED_API;
 343
 344   /**
 345    * @DEPRECATED_1_1.32 SetProperty TOGGLABLE or Styling file
 346    *
 347    * @brief Sets the \e togglable property.
 348    *
 349    * If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
 350    *
 351    * @SINCE_1_0.0
 352    * @param[in] togglable Togglable property
 353    */
 354   void SetTogglableButton( bool togglable ) DALI_DEPRECATED_API;
 355
 356   /**
 357    * @DEPRECATED_1_1.32 GetProperty TOGGLABLE
 358    *
 359    * @brief Returns if the togglable property is set.
 360    * @SINCE_1_0.0
 361    * @return \e true if the \e togglable property is set
 362    */
 363   bool IsTogglableButton() const DALI_DEPRECATED_API;
 364
 365   /**
 366    * @DEPRECATED_1_1.32 SetProperty SELECTED
 367    *
 368    * @brief Sets the button as selected or unselected.
 369    *
 370    * \e togglable property must be set to \e true.
 371    *
 372    * Emits a Button::StateChangedSignal() signal.
 373    *
 374    * @SINCE_1_0.0
 375    * @param[in] selected Selected property
 376    */
 377   void SetSelected( bool selected ) DALI_DEPRECATED_API;
 378
 379   /**
 380    * DEPRECATED_1_1.32  GetProperty SELECTED
 381    *
 382    * @brief Returns if the selected property is set and the button is togglable.
 383    * @SINCE_1_0.0
 384    * @return \e true if the button is \e selected
 385    */
 386   bool IsSelected() const DALI_DEPRECATED_API;
 387
 388   /**
 389    * @DEPRECATED_1_1.32 Use Styling file to set animation
 390    *
 391    * @brief Sets the animation time.
 392    *
 393    * @SINCE_1_0.0
 394    * @param[in] animationTime The animation time in seconds
 395    */
 396   void SetAnimationTime( float animationTime ) DALI_DEPRECATED_API;
 397
 398   /**
 399    * DEPRECATED_1_1.32 Use Styling file to set animation
 400    *
 401    * @brief Retrieves button's animation time.
 402    *
 403    * @SINCE_1_0.0
 404    * @return The animation time in seconds
 405    */
 406   float GetAnimationTime() const DALI_DEPRECATED_API;
 407
 408   /**
 409    * @DEPRECATED_1_1.32 SetProperty Property::LABEL or Styling file
 410    *
 411    * @brief Sets the button's label.
 412    *
 413    * @SINCE_1_0.0
 414    * @param[in] label The label text
 415    */
 416   void SetLabelText( const std::string& label ) DALI_DEPRECATED_API;
 417
 418   /**
 419    * DEPRECATED_1_1.32 GetProperty LABEL
 420    *
 421    * @brief Gets the label.
 422    *
 423    * @SINCE_1_0.0
 424    * @return The label text
 425    */
 426   std::string GetLabelText() const DALI_DEPRECATED_API;
 427
 428   /**
 429    * @DEPRECATED_1_1.32 Use Styling file Property::UNSELECTED_STATE_IMAGE
 430    *
 431    * @brief Sets the unselected button image.
 432    *
 433    * @SINCE_1_0.0
 434    * @param[in] filename The button image
 435    */
 436   void SetUnselectedImage( const std::string& filename ) DALI_DEPRECATED_API;
 437
 438   /**
 439    * @DEPRECATED_1_1.32 Use styling Set Control::Property::BACKGROUND which is same as un-selected background
 440    * Or use DevelButton::Property::UNSELECTED_BACKGROUND_VISUAL
 441    *
 442    * @brief Sets the background image.
 443    *
 444    * @SINCE_1_0.0
 445    * @param[in] filename The background image
 446    */
 447   void SetBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
 448
 449   /**
 450    * @DEPRECATED_1_1.32 Use styling file, Property::SELECTED_STATE_IMAGE
 451    *
 452    * @brief Sets the selected image.
 453    *
 454    * @SINCE_1_0.0
 455    * @param[in] filename The selected image
 456    */
 457   void SetSelectedImage( const std::string& filename ) DALI_DEPRECATED_API;
 458
 459   /**
 460    * @DEPRECATED_1_1.32 Set Control::Property::BACKGROUND which is same as un-selected background
 461    * Or use DevelButton::Property::SELECTED_BACKGROUND_VISUAL
 462    *
 463    * @brief Sets the selected background image.
 464    *
 465    * @SINCE_1_0.0
 466    * @param[in] filename The selected background image
 467    */
 468   void SetSelectedBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
 469
 470   /**
 471    * @DEPRECATED_1_1.32 Only able to set Property::DISABLED_STATE_IMAGE
 472    * Or use DevelButton::Property::DISABLED_SELECTED_BACKGROUND_VISUAL
 473    *
 474    * @brief Sets the disabled background image.
 475    *
 476    * @SINCE_1_0.0
 477    * @param[in] filename The disabled background image
 478    */
 479   void SetDisabledBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
 480
 481   /**
 482    * @DEPRECATED_1_1.32 Use styling file Property::DISABLED_STATE_IMAGE
 483    *
 484    * @brief Sets the disabled button image.
 485    *
 486    * @SINCE_1_0.0
 487    * @param[in] filename The disabled button image
 488    */
 489   void SetDisabledImage( const std::string& filename ) DALI_DEPRECATED_API;
 490
 491   /**
 492    * @DEPRECATED_1_1.32 Use Property::DISABLED_STATE_IMAGE which provides same disabled image for un/selected
 493    * Or DevelButton::Property::DISABLED_SELECTED_VISUAL to disable selected visual.
 494    *
 495    * @brief Sets the disabled selected button image.
 496    *
 497    * @SINCE_1_0.0
 498    * @param[in] filename The disabled selected button image
 499    */
 500   void SetDisabledSelectedImage( const std::string& filename ) DALI_DEPRECATED_API;
 501
 502   /**
 503    * @DEPRECATED_1_0.50. Instead, use SetLabelText
 504    *
 505    * @brief Sets the label with an actor.
 506    *
 507    * @SINCE_1_0.0
 508    * @param[in] label The actor to use as a label
 509    */
 510   void SetLabel( Actor label ) DALI_DEPRECATED_API;
 511
 512   /**
 513    * @DEPRECATED_1_0.50. Instead, use SetUnselectedImage.
 514    *
 515    * @brief Sets the button image.
 516    *
 517    * @SINCE_1_0.0
 518    * @param[in] image The button image
 519    */
 520   void SetButtonImage( Image image ) DALI_DEPRECATED_API;
 521
 522   /**
 523    * @DEPRECATED_1_0.50. Instead, use SetSelectedImage( const std::string& filename ).
 524    *
 525    * @brief Sets the selected image.
 526    *
 527    * @SINCE_1_0.0
 528    * @param[in] image The selected image
 529    */
 530   void SetSelectedImage( Image image ) DALI_DEPRECATED_API;
 531
 532   /**
 533    * @DEPRECATED_1_0.50
 534    *
 535    * @brief Gets the button image.
 536    *
 537    * @SINCE_1_0.0
 538    * @remarks Avoid using this method as it's a legacy code.
 539    * @return An actor with the button image
 540    */
 541   Actor GetButtonImage() const DALI_DEPRECATED_API;
 542
 543   /**
 544    * @DEPRECATED_1_0.50
 545    *
 546    * @brief Gets the selected image.
 547    *
 548    * @SINCE_1_0.0
 549    * @remarks Avoid using this method as it's a legacy code.
 550    * @return An actor with the selected image
 551    */
 552   Actor GetSelectedImage() const DALI_DEPRECATED_API;
 553
 554 public: //Signals
 555
 556   /**
 557    * @brief Button signal type.
 558    * @SINCE_1_0.0
 559    */
 560   typedef Signal< bool ( Button ) > ButtonSignalType;
 561
 562   /**
 563    * @brief This signal is emitted when the button is touched.
 564    *
 565    * A callback of the following type may be connected:
 566    * @code
 567    *   bool YourCallbackName( Button button );
 568    * @endcode
 569    * @SINCE_1_0.0
 570    * @return The signal to connect to
 571    */
 572   ButtonSignalType& PressedSignal();
 573
 574   /**
 575    * @brief This signal is emitted when the button is touched and the touch point leaves the boundary of the button.
 576    *
 577    * A callback of the following type may be connected:
 578    * @code
 579    *   bool YourCallbackName( Button button );
 580    * @endcode
 581    * @SINCE_1_0.0
 582    * @return The signal to connect to
 583    */
 584   ButtonSignalType& ReleasedSignal();
 585
 586   /**
 587    * @brief This signal is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
 588    *
 589    * A callback of the following type may be connected:
 590    * @code
 591    *   bool YourCallbackName( Button button );
 592    * @endcode
 593    * @SINCE_1_0.0
 594    * @return The signal to connect to
 595    */
 596   ButtonSignalType& ClickedSignal();
 597
 598   /**
 599    * @brief This signal is emitted when the button's state is changed.
 600    *
 601    * The application can get the state by calling IsSelected().
 602    *
 603    * A callback of the following type may be connected:
 604    * @code
 605    *   bool YourCallbackName( Button button );
 606    * @endcode
 607    * @SINCE_1_0.0
 608    * @return The signal to connect to
 609    */
 610   ButtonSignalType& StateChangedSignal();
 611
 612 public: // Not intended for application developers
 613
 614   /// @cond internal
 615   /**
 616    * @brief Creates a handle using the Toolkit::Internal implementation.
 617    *
 618    * @SINCE_1_0.0
 619    * @param[in] implementation The Control implementation
 620    */
 621   DALI_INTERNAL Button( Internal::Button& implementation );
 622
 623   /**
 624    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 625    *
 626    * @SINCE_1_0.0
 627    * @param[in] internal A pointer to the internal CustomActor
 628    */
 629   DALI_INTERNAL Button( Dali::Internal::CustomActor* internal );
 630   /// @endcond
 631 };
 632
 633 /**
 634  * @}
 635  */
 636 } // namespace Toolkit
 637
 638 } // namespace Dali
 639
 640 #endif // __DALI_TOOLKIT_BUTTON_H__