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 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     | %Button method called       |
  81  * |------------------|-----------------------------|
  82  * | buttonClick      | %DoClickAction()            |
  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    */
 140   Button( const Button& button );
 141
 142   /**
 143    * @brief Assignment operator.
 144    * @SINCE_1_0.0
 145    */
 146   Button& operator=( const Button& button );
 147
 148   /**
 149    * @brief Downcast a handle to Button handle.
 150    *
 151    * If handle points to a Button the downcast produces valid
 152    * handle. If not the returned handle is left uninitialized.
 153    *
 154    * @SINCE_1_0.0
 155    * @param[in] handle Handle to an object
 156    * @return A handle to a Button or an uninitialized handle
 157    */
 158   static Button DownCast( BaseHandle handle );
 159
 160   /**
 161    * @brief Destructor
 162    *
 163    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 164    * @SINCE_1_0.0
 165    */
 166   ~Button();
 167
 168   /**
 169    * @brief Sets the button as \e disabled.
 170    *
 171    * No signals are emitted when the \e disabled property is set.
 172    *
 173    * @SINCE_1_0.0
 174    * @param[in] disabled property.
 175    */
 176   void SetDisabled( bool disabled );
 177
 178   /**
 179    * @brief Returns if the button is disabled.
 180    * @SINCE_1_0.0
 181    * @return \e true if the button is \e disabled.
 182    */
 183   bool IsDisabled() const;
 184
 185   /**
 186    * @brief Sets the \e autorepeating property.
 187    *
 188    * If the \e autorepeating property is set to \e true, then the \e togglable property is set to false
 189    * but no signal is emitted.
 190    *
 191    * @SINCE_1_0.0
 192    * @param[in] autoRepeating \e autorepeating property.
 193    */
 194   void SetAutoRepeating( bool autoRepeating );
 195
 196   /**
 197    * @brief Returns if the autorepeating property is set.
 198    * @SINCE_1_0.0
 199    * @return \e true if the \e autorepeating property is set.
 200    */
 201   bool IsAutoRepeating() const;
 202
 203   /**
 204    * @brief Sets the initial autorepeating delay.
 205    *
 206    * By default this value is set to 0.15 seconds.
 207    *
 208    * @SINCE_1_0.0
 209    * @param[in] initialAutoRepeatingDelay in seconds.
 210    * @pre initialAutoRepeatingDelay must be greater than zero.
 211    */
 212   void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
 213
 214   /**
 215    * @brief Gets the initial autorepeating delay in seconds.
 216    * @SINCE_1_0.0
 217    * @return the initial autorepeating delay in seconds.
 218    */
 219   float GetInitialAutoRepeatingDelay() const;
 220
 221   /**
 222    * @brief Sets the next autorepeating delay.
 223    *
 224    * By default this value is set to 0.05 seconds.
 225    *
 226    * @SINCE_1_0.0
 227    * @param[in] nextAutoRepeatingDelay in seconds.
 228    * @pre nextAutoRepeatingDelay must be greater than zero.
 229    */
 230   void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
 231
 232   /**
 233    * @brief Gets the next autorepeating delay in seconds.
 234    * @SINCE_1_0.0
 235    * @return the next autorepeating delay in seconds.
 236    */
 237   float GetNextAutoRepeatingDelay() const;
 238
 239   /**
 240    * @brief Sets the \e togglable property.
 241    *
 242    * If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
 243    *
 244    * @SINCE_1_0.0
 245    * @param[in] togglable property.
 246    */
 247   void SetTogglableButton( bool togglable );
 248
 249   /**
 250    * @brief Returns if the togglable property is set.
 251    * @SINCE_1_0.0
 252    * @return \e true if the \e togglable property is set.
 253    */
 254   bool IsTogglableButton() const;
 255
 256   /**
 257    * @brief Sets the button as selected or unselected.
 258    *
 259    * \e togglable property must be set to \e true.
 260    *
 261    * Emits a Button::StateChangedSignal() signal.
 262    *
 263    * @SINCE_1_0.0
 264    * @param[in] selected property.
 265    */
 266   void SetSelected( bool selected );
 267
 268   /**
 269    * @brief Returns if the selected property is set and the button is togglable.
 270    * @SINCE_1_0.0
 271    * @return \e true if the button is \e selected.
 272    */
 273   bool IsSelected() const;
 274
 275   /**
 276    * @brief Sets the animation time.
 277    *
 278    * @SINCE_1_0.0
 279    * @param[in] animationTime The animation time in seconds.
 280    */
 281   void SetAnimationTime( float animationTime );
 282
 283   /**
 284    * @brief Retrieves button's animation time.
 285    *
 286    * @SINCE_1_0.0
 287    * @return The animation time in seconds.
 288    */
 289   float GetAnimationTime() const;
 290
 291   /**
 292    * @brief Sets the button's label.
 293    *
 294    * @SINCE_1_0.0
 295    * @param[in] label The label text.
 296    */
 297   void SetLabelText( const std::string& label );
 298
 299   /**
 300    * @brief Gets the label.
 301    *
 302    * @SINCE_1_0.0
 303    * @return The label text.
 304    */
 305   std::string GetLabelText() const;
 306
 307   /**
 308    * @brief Sets the unselected button image.
 309    *
 310    * @SINCE_1_0.0
 311    * @param[in] filename The button image.
 312    */
 313   void SetUnselectedImage( const std::string& filename );
 314
 315   /**
 316    * @brief Sets the background image.
 317    *
 318    * @SINCE_1_0.0
 319    * @param[in] filename The background image.
 320    */
 321   void SetBackgroundImage( const std::string& filename );
 322
 323   /**
 324    * @brief Sets the selected image.
 325    *
 326    * @SINCE_1_0.0
 327    * @param[in] filename The selected image.
 328    */
 329   void SetSelectedImage( const std::string& filename );
 330
 331   /**
 332    * @brief Sets the selected background image.
 333    *
 334    * @SINCE_1_0.0
 335    * @param[in] filename The selected background image.
 336    */
 337   void SetSelectedBackgroundImage( const std::string& filename );
 338
 339   /**
 340    * @brief Sets the disabled background image.
 341    *
 342    * @SINCE_1_0.0
 343    * @param[in] filename The disabled background image.
 344    */
 345   void SetDisabledBackgroundImage( const std::string& filename );
 346
 347   /**
 348    * @brief Sets the disabled button image.
 349    *
 350    * @SINCE_1_0.0
 351    * @param[in] filename The disabled button image.
 352    */
 353   void SetDisabledImage( const std::string& filename );
 354
 355   /**
 356    * @brief Sets the disabled selected button image.
 357    *
 358    * @SINCE_1_0.0
 359    * @param[in] filename The disabled selected button image.
 360    */
 361   void SetDisabledSelectedImage( const std::string& filename );
 362
 363   // Deprecated API
 364
 365   /**
 366    * @DEPRECATED_1_0.50. Instead, use SetLabelText.
 367    *
 368    * @brief Sets the label with an actor.
 369    *
 370    * @SINCE_1_0.0
 371    * @param[in]  label The actor to use as a label
 372    */
 373   void SetLabel( Actor label );
 374
 375   /**
 376    * @DEPRECATED_1_0.50. Instead, use SetUnselectedImage.
 377    *
 378    * @brief Sets the button image.
 379    *
 380    * @SINCE_1_0.0
 381    * @param[in]  image The button image.
 382    */
 383   void SetButtonImage( Image image );
 384
 385   /**
 386    * @DEPRECATED_1_0.50. Instead, use SetSelectedImage( const std::string& filename ).
 387    *
 388    * @brief Sets the selected image.
 389    *
 390    * @SINCE_1_0.0
 391    * @param[in]  image The selected image.
 392    */
 393   void SetSelectedImage( Image image );
 394
 395   /**
 396    * @DEPRECATED_1_0.50
 397    *
 398    * @brief Gets the button image.
 399    *
 400    * @SINCE_1_0.0
 401    * @remarks Avoid using this method as it's a legacy code.
 402    * @return     An actor with the button image.
 403    */
 404   Actor GetButtonImage() const;
 405
 406   /**
 407    * @DEPRECATED_1_0.50
 408    *
 409    * @brief Gets the selected image.
 410    *
 411    * @SINCE_1_0.0
 412    * @remarks Avoid using this method as it's a legacy code.
 413    * @return     An actor with the selected image.
 414    */
 415   Actor GetSelectedImage() const;
 416
 417 public: //Signals
 418
 419   /**
 420    * @brief Button signal type
 421    * @SINCE_1_0.0
 422    */
 423   typedef Signal< bool ( Button ) > ButtonSignalType;
 424
 425   /**
 426    * @brief This signal is emitted when the button is touched.
 427    *
 428    * A callback of the following type may be connected:
 429    * @code
 430    *   bool YourCallbackName( Button button );
 431    * @endcode
 432    * @SINCE_1_0.0
 433    * @return The signal to connect to.
 434    */
 435   ButtonSignalType& PressedSignal();
 436
 437   /**
 438    * @brief This signal is emitted when the button is touched and the touch point leaves the boundary of the button.
 439    *
 440    * A callback of the following type may be connected:
 441    * @code
 442    *   bool YourCallbackName( Button button );
 443    * @endcode
 444    * @SINCE_1_0.0
 445    * @return The signal to connect to.
 446    */
 447   ButtonSignalType& ReleasedSignal();
 448
 449   /**
 450    * @brief This signal is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
 451    *
 452    * A callback of the following type may be connected:
 453    * @code
 454    *   bool YourCallbackName( Button button );
 455    * @endcode
 456    * @SINCE_1_0.0
 457    * @return The signal to connect to.
 458    */
 459   ButtonSignalType& ClickedSignal();
 460
 461   /**
 462    * @brief This signal is emitted when the button's state is changed.
 463    *
 464    * The application can get the state by calling IsSelected().
 465    *
 466    * A callback of the following type may be connected:
 467    * @code
 468    *   bool YourCallbackName( Button button );
 469    * @endcode
 470    * @SINCE_1_0.0
 471    * @return The signal to connect to.
 472    */
 473   ButtonSignalType& StateChangedSignal();
 474
 475 public: // Not intended for application developers
 476
 477   /**
 478    * @brief Creates a handle using the Toolkit::Internal implementation.
 479    *
 480    * @SINCE_1_0.0
 481    * @param[in]  implementation  The Control implementation.
 482    */
 483   DALI_INTERNAL Button( Internal::Button& implementation );
 484
 485   /**
 486    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 487    *
 488    * @SINCE_1_0.0
 489    * @param[in]  internal  A pointer to the internal CustomActor.
 490    */
 491   DALI_INTERNAL Button( Dali::Internal::CustomActor* internal );
 492 };
 493
 494 /**
 495  * @}
 496  */
 497 } // namespace Toolkit
 498
 499 } // namespace Dali
 500
 501 #endif // __DALI_TOOLKIT_BUTTON_H__