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) 2015 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 kind 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  * The button's appearance can be modified by setting properties for the various image filenames.
  63  *
  64  * The \e background is always shown and doesn't change if the button is pressed or released. The \e button image is shown over the \e background image when the
  65  * button is not pressed and is replaced by the \e selected image when the button is pressed. The text label is placed always on the top of all images.
  66  *
  67  * When the button is disabled, \e background, \e button and \e selected images are replaced by their \e disabled images.
  68  *
  69  * Is not mandatory to set all images. A button could be defined only by setting its \e background image or by setting its \e background and \e selected images.
  70  *
  71  * Signals
  72  * | %Signal Name     | Method                      |
  73  * |------------------|-----------------------------|
  74  * | pressed          | @ref PressedSignal()        |
  75  * | released         | @ref ReleasedSignal()       |
  76  * | clicked          | @ref ClickedSignal()        |
  77  * | stateChanged     | @ref StateChangedSignal()   |
  78  *
  79  * Actions
  80  * | %Action Name     | Attributes              | Description                                   |
  81  * |------------------|-------------------------|-----------------------------------------------|
  82  * | buttonClick      | Doesn't have attributes | Simulates a button click. See @ref DoAction() |
  83  * @SINCE_1_0.0
  84  */
  85 class DALI_IMPORT_API Button : public Control
  86 {
  87 public:
  88
  89   /**
  90    * @brief The start and end property ranges for this control.
  91    * @SINCE_1_0.0
  92    */
  93   enum PropertyRange
  94   {
  95     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
  96     PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000              ///< Reserve property indices @SINCE_1_0.0
  97   };
  98
  99   /**
 100    * @brief An enumeration of properties belonging to the Button class.
 101    * @SINCE_1_0.0
 102    */
 103   struct Property
 104   {
 105     enum
 106     {
 107       DISABLED = PROPERTY_START_INDEX, ///< name "disabled",                     @see SetDisabled(),                  type bool @SINCE_1_0.0
 108       AUTO_REPEATING,                  ///< name "autoRepeating",                @see SetAutoRepeating(),             type bool @SINCE_1_0.0
 109       INITIAL_AUTO_REPEATING_DELAY,    ///< name "initialAutoRepeatingDelay",    @see SetInitialAutoRepeatingDelay(), type float @SINCE_1_0.0
 110       NEXT_AUTO_REPEATING_DELAY,       ///< name "nextAutoRepeatingDelay",       @see SetNextAutoRepeatingDelay(),    type float @SINCE_1_0.0
 111       TOGGLABLE,                       ///< name "togglable",                    @see SetTogglableButton(),           type bool @SINCE_1_0.0
 112       SELECTED,                        ///< name "selected",                     @see SetSelected(),                  type bool @SINCE_1_0.0
 113       UNSELECTED_STATE_IMAGE,          ///< name "unselectedStateImage",         @see SetUnselectedImage(),           type std::string @SINCE_1_0.0
 114       SELECTED_STATE_IMAGE,            ///< name "selectedStateImage",           @see SetSelectedImage(),             type std::string @SINCE_1_0.0
 115       DISABLED_STATE_IMAGE,            ///< name "disabledStateImage",           @see SetDisabledImage(),             type std::string @SINCE_1_0.0
 116       UNSELECTED_COLOR,                ///< name "unselectedColor",                                                   type Vector4 @SINCE_1_0.0
 117       SELECTED_COLOR,                  ///< name "selectedColor",                                                     type Vector4 @SINCE_1_0.0
 118       LABEL,                           ///< name "label",                                                             type Property::Map @SINCE_1_0.0
 119
 120       // Deprecated properties:
 121       LABEL_TEXT,                      ///< name "labelText",                    @see SetLabelText(),                 type std::string @SINCE_1_0.0
 122     };
 123   };
 124
 125 public:
 126
 127   /**
 128    * @brief Create an uninitialized Button.
 129    *
 130    * Only derived versions can be instantiated.  Calling member
 131    * functions with an uninitialized Dali::Object is not allowed.
 132    * @SINCE_1_0.0
 133    */
 134   Button();
 135
 136   /**
 137    * @brief Copy constructor.
 138    * @SINCE_1_0.0
 139    * @param[in] button Handle to an object
 140    */
 141   Button( const Button& button );
 142
 143   /**
 144    * @brief Assignment operator.
 145    * @SINCE_1_0.0
 146    * @param[in] button Handle to an object
 147    * @return A reference to this
 148    */
 149   Button& operator=( const Button& button );
 150
 151   /**
 152    * @brief Downcast a handle to Button handle.
 153    *
 154    * If handle points to a Button the downcast produces valid
 155    * handle. If not the returned handle is left uninitialized.
 156    *
 157    * @SINCE_1_0.0
 158    * @param[in] handle Handle to an object
 159    * @return A handle to a Button or an uninitialized handle
 160    */
 161   static Button DownCast( BaseHandle handle );
 162
 163   /**
 164    * @brief Destructor
 165    *
 166    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 167    * @SINCE_1_0.0
 168    */
 169   ~Button();
 170
 171   // Deprecated API
 172
 173   /**
 174    * @DEPRECATED_1_1.32 Use SetProperty DISABLED or Styling file
 175    *
 176    * @brief Sets the button as \e disabled.
 177    *
 178    * No signals are emitted when the \e disabled property is set.
 179    *
 180    * @SINCE_1_0.0
 181    * @param[in] disabled property.
 182    */
 183   void SetDisabled( bool disabled );
 184
 185   /**
 186    * @DEPRECATED_1_1.32 Use GetProperty DISABLED
 187    *
 188    * @brief Returns if the button is disabled.
 189    * @SINCE_1_0.0
 190    * @return \e true if the button is \e disabled.
 191    */
 192   bool IsDisabled() const;
 193
 194   /**
 195    * @DEPRECATED_1_1.32 SetProperty AUTO_REPEATING or Styling file
 196    *
 197    * @brief Sets the \e autorepeating property.
 198    *
 199    * If the \e autorepeating property is set to \e true, then the \e togglable property is set to false
 200    * but no signal is emitted.
 201    *
 202    * @SINCE_1_0.0
 203    * @param[in] autoRepeating \e autorepeating property.
 204    */
 205   void SetAutoRepeating( bool autoRepeating );
 206
 207   /**
 208    * @DEPRECATED_1_1.32 GetProperty AUTO_REPEATING
 209    *
 210    * @brief Returns if the autorepeating property is set.
 211    * @SINCE_1_0.0
 212    * @return \e true if the \e autorepeating property is set.
 213    */
 214   bool IsAutoRepeating() const;
 215
 216   /**
 217    * @DEPRECATED_1_1.32 SetProperty INITIAL_AUTO_REPEATING_DELAY or Styling file
 218    *
 219    * @brief Sets the initial autorepeating delay.
 220    *
 221    * By default this value is set to 0.15 seconds.
 222    *
 223    * @SINCE_1_0.0
 224    * @param[in] initialAutoRepeatingDelay in seconds.
 225    * @pre initialAutoRepeatingDelay must be greater than zero.
 226    */
 227   void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
 228
 229   /**
 230    * @DEPRECATED_1_1.32 GetProperty INITIAL_AUTO_REPEATING_DELAY
 231    *
 232    * @brief Gets the initial autorepeating delay in seconds.
 233    * @SINCE_1_0.0
 234    * @return the initial autorepeating delay in seconds.
 235    */
 236   float GetInitialAutoRepeatingDelay() const;
 237
 238   /**
 239    * @DEPRECATED_1_1.32 SetProperty NEXT_AUTO_REPEATING_DELAY or Styling file
 240    *
 241    * @brief Sets the next autorepeating delay.
 242    *
 243    * By default this value is set to 0.05 seconds.
 244    *
 245    * @SINCE_1_0.0
 246    * @param[in] nextAutoRepeatingDelay in seconds.
 247    * @pre nextAutoRepeatingDelay must be greater than zero.
 248    */
 249   void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
 250
 251   /**
 252    * @DEPRECATED_1_1.32 GetProperty NEXT_AUTO_REPEATING_DELAY
 253    *
 254    * @brief Gets the next autorepeating delay in seconds.
 255    * @SINCE_1_0.0
 256    * @return the next autorepeating delay in seconds.
 257    */
 258   float GetNextAutoRepeatingDelay() const;
 259
 260   /**
 261    * @DEPRECATED_1_1.32 SetProperty TOGGLABLE or Styling file
 262    *
 263    * @brief Sets the \e togglable property.
 264    *
 265    * If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
 266    *
 267    * @SINCE_1_0.0
 268    * @param[in] togglable property.
 269    */
 270   void SetTogglableButton( bool togglable );
 271
 272   /**
 273    * @DEPRECATED_1_1.32 GetProperty TOGGLABLE
 274    *
 275    * @brief Returns if the togglable property is set.
 276    * @SINCE_1_0.0
 277    * @return \e true if the \e togglable property is set.
 278    */
 279   bool IsTogglableButton() const;
 280
 281   /**
 282    * @DEPRECATED_1_1.32 SetProperty SELECTED
 283    *
 284    * @brief Sets the button as selected or unselected.
 285    *
 286    * \e togglable property must be set to \e true.
 287    *
 288    * Emits a Button::StateChangedSignal() signal.
 289    *
 290    * @SINCE_1_0.0
 291    * @param[in] selected property.
 292    */
 293   void SetSelected( bool selected );
 294
 295   /**
 296    * DEPRECATED_1_1.32  SetProperty SELECTED
 297    *
 298    * @brief Returns if the selected property is set and the button is togglable.
 299    * @SINCE_1_0.0
 300    * @return \e true if the button is \e selected.
 301    */
 302   bool IsSelected() const;
 303
 304   /**
 305    * @DEPRECATED_1_1.32 Use Styling file to set animation
 306    *
 307    * @brief Sets the animation time.
 308    *
 309    * @SINCE_1_0.0
 310    * @param[in] animationTime The animation time in seconds.
 311    */
 312   void SetAnimationTime( float animationTime );
 313
 314   /**
 315    * DEPRECATED_1_1.32 Use Styling file to set animation
 316    *
 317    * @brief Retrieves button's animation time.
 318    *
 319    * @SINCE_1_0.0
 320    * @return The animation time in seconds.
 321    */
 322   float GetAnimationTime() const;
 323
 324   /**
 325    * @DEPRECATED_1_1.32 SetProperty LABEL or Styling file
 326    *
 327    * @brief Sets the button's label.
 328    *
 329    * @SINCE_1_0.0
 330    * @param[in] label The label text.
 331    */
 332   void SetLabelText( const std::string& label );
 333
 334   /**
 335    * DEPRECATED_1_1.32 GetProperty LABEL
 336    *
 337    * @brief Gets the label.
 338    *
 339    * @SINCE_1_0.0
 340    * @return The label text.
 341    */
 342   std::string GetLabelText() const;
 343
 344   /**
 345    * @DEPRECATED_1_1.32 Use Styling file
 346    *
 347    * @brief Sets the unselected button image.
 348    *
 349    * @SINCE_1_0.0
 350    * @param[in] filename The button image.
 351    */
 352   void SetUnselectedImage( const std::string& filename );
 353
 354   /**
 355    * @DEPRECATED_1_1.32 Use styling
 356    *
 357    * @brief Sets the background image.
 358    *
 359    * @SINCE_1_0.0
 360    * @param[in] filename The background image.
 361    */
 362   void SetBackgroundImage( const std::string& filename );
 363
 364   /**
 365    * @DEPRECATED_1_1.32 Use styling file
 366    *
 367    * @brief Sets the selected image.
 368    *
 369    * @SINCE_1_0.0
 370    * @param[in] filename The selected image.
 371    */
 372   void SetSelectedImage( const std::string& filename );
 373
 374   /**
 375    * @DEPRECATED_1_1.32 Use styling file
 376    *
 377    * @brief Sets the selected background image.
 378    *
 379    * @SINCE_1_0.0
 380    * @param[in] filename The selected background image.
 381    */
 382   void SetSelectedBackgroundImage( const std::string& filename );
 383
 384   /**
 385    * @DEPRECATED_1_1.32 Use styling file
 386    *
 387    * @brief Sets the disabled background image.
 388    *
 389    * @SINCE_1_0.0
 390    * @param[in] filename The disabled background image.
 391    */
 392   void SetDisabledBackgroundImage( const std::string& filename );
 393
 394   /**
 395    * @DEPRECATED_1_1.32 Use styling file
 396    *
 397    * @brief Sets the disabled button image.
 398    *
 399    * @SINCE_1_0.0
 400    * @param[in] filename The disabled button image.
 401    */
 402   void SetDisabledImage( const std::string& filename );
 403
 404   /**
 405    * @DEPRECATED_1_1.32 Use styling file
 406    *
 407    * @brief Sets the disabled selected button image.
 408    *
 409    * @SINCE_1_0.0
 410    * @param[in] filename The disabled selected button image.
 411    */
 412   void SetDisabledSelectedImage( const std::string& filename );
 413
 414   /**
 415    * @DEPRECATED_1_0.50. Instead, use SetLabelText.
 416    *
 417    * @brief Sets the label with an actor.
 418    *
 419    * @SINCE_1_0.0
 420    * @param[in]  label The actor to use as a label
 421    */
 422   void SetLabel( Actor label );
 423
 424   /**
 425    * @DEPRECATED_1_0.50. Instead, use SetUnselectedImage.
 426    *
 427    * @brief Sets the button image.
 428    *
 429    * @SINCE_1_0.0
 430    * @param[in]  image The button image.
 431    */
 432   void SetButtonImage( Image image );
 433
 434   /**
 435    * @DEPRECATED_1_0.50. Instead, use SetSelectedImage( const std::string& filename ).
 436    *
 437    * @brief Sets the selected image.
 438    *
 439    * @SINCE_1_0.0
 440    * @param[in]  image The selected image.
 441    */
 442   void SetSelectedImage( Image image );
 443
 444   /**
 445    * @DEPRECATED_1_0.50
 446    *
 447    * @brief Gets the button image.
 448    *
 449    * @SINCE_1_0.0
 450    * @remarks Avoid using this method as it's a legacy code.
 451    * @return     An actor with the button image.
 452    */
 453   Actor GetButtonImage() const;
 454
 455   /**
 456    * @DEPRECATED_1_0.50
 457    *
 458    * @brief Gets the selected image.
 459    *
 460    * @SINCE_1_0.0
 461    * @remarks Avoid using this method as it's a legacy code.
 462    * @return     An actor with the selected image.
 463    */
 464   Actor GetSelectedImage() const;
 465
 466 public: //Signals
 467
 468   /**
 469    * @brief Button signal type
 470    * @SINCE_1_0.0
 471    */
 472   typedef Signal< bool ( Button ) > ButtonSignalType;
 473
 474   /**
 475    * @brief This signal is emitted when the button is touched.
 476    *
 477    * A callback of the following type may be connected:
 478    * @code
 479    *   bool YourCallbackName( Button button );
 480    * @endcode
 481    * @SINCE_1_0.0
 482    * @return The signal to connect to.
 483    */
 484   ButtonSignalType& PressedSignal();
 485
 486   /**
 487    * @brief This signal is emitted when the button is touched and the touch point leaves the boundary of the button.
 488    *
 489    * A callback of the following type may be connected:
 490    * @code
 491    *   bool YourCallbackName( Button button );
 492    * @endcode
 493    * @SINCE_1_0.0
 494    * @return The signal to connect to.
 495    */
 496   ButtonSignalType& ReleasedSignal();
 497
 498   /**
 499    * @brief This signal is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
 500    *
 501    * A callback of the following type may be connected:
 502    * @code
 503    *   bool YourCallbackName( Button button );
 504    * @endcode
 505    * @SINCE_1_0.0
 506    * @return The signal to connect to.
 507    */
 508   ButtonSignalType& ClickedSignal();
 509
 510   /**
 511    * @brief This signal is emitted when the button's state is changed.
 512    *
 513    * The application can get the state by calling IsSelected().
 514    *
 515    * A callback of the following type may be connected:
 516    * @code
 517    *   bool YourCallbackName( Button button );
 518    * @endcode
 519    * @SINCE_1_0.0
 520    * @return The signal to connect to.
 521    */
 522   ButtonSignalType& StateChangedSignal();
 523
 524 public: // Not intended for application developers
 525
 526   /// @cond internal
 527   /**
 528    * @brief Creates a handle using the Toolkit::Internal implementation.
 529    *
 530    * @SINCE_1_0.0
 531    * @param[in]  implementation  The Control implementation.
 532    */
 533   DALI_INTERNAL Button( Internal::Button& implementation );
 534
 535   /**
 536    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 537    *
 538    * @SINCE_1_0.0
 539    * @param[in]  internal  A pointer to the internal CustomActor.
 540    */
 541   DALI_INTERNAL Button( Dali::Internal::CustomActor* internal );
 542   /// @endcond
 543 };
 544
 545 /**
 546  * @}
 547  */
 548 } // namespace Toolkit
 549
 550 } // namespace Dali
 551
 552 #endif // __DALI_TOOLKIT_BUTTON_H__