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  * | state-changed     | @ref StateChangedSignal()   |
  78  *
  79  * Actions
  80  * | %Action Name      | %Button method called       |
  81  * |-------------------|-----------------------------|
  82  * | button-click      | %DoClickAction()            |
  83  */
  84 class DALI_IMPORT_API Button : public Control
  85 {
  86 public:
  87
  88   /**
  89    * @brief The start and end property ranges for this control.
  90    */
  91   enum PropertyRange
  92   {
  93     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
  94     PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000              ///< Reserve property indices
  95   };
  96
  97   /**
  98    * @brief An enumeration of properties belonging to the Button class.
  99    */
 100   struct Property
 101   {
 102     enum
 103     {
 104       DISABLED = PROPERTY_START_INDEX, ///< name "disabled",                     @see SetDisabled(),                  type bool
 105       AUTO_REPEATING,                  ///< name "auto-repeating",               @see SetAutoRepeating(),             type bool
 106       INITIAL_AUTO_REPEATING_DELAY,    ///< name "initial-auto-repeating-delay", @see SetInitialAutoRepeatingDelay(), type float
 107       NEXT_AUTO_REPEATING_DELAY,       ///< name "next-auto-repeating-delay",    @see SetNextAutoRepeatingDelay(),    type float
 108       TOGGLABLE,                       ///< name "togglable",                    @see SetTogglableButton(),           type bool
 109       SELECTED,                        ///< name "selected",                     @see SetSelected(),                  type bool
 110       UNSELECTED_STATE_IMAGE,          ///< name "unselected-state-image",       @see SetUnselectedImage(),           type std::string
 111       SELECTED_STATE_IMAGE,            ///< name "selected-state-image",         @see SetSelectedImage(),             type std::string
 112       DISABLED_STATE_IMAGE,            ///< name "disabled-state-image",         @see SetDisabledImage(),             type std::string
 113       UNSELECTED_COLOR,                ///< name "unselected-color",                                                  type Vector4
 114       SELECTED_COLOR,                  ///< name "selected-color",                                                    type Vector4
 115       LABEL,                           ///< name "label",                                                             type Property::Map
 116
 117       // Deprecated properties:
 118       LABEL_TEXT,                      ///< name "label-text",                   @see SetLabelText(),                 type std::string
 119     };
 120   };
 121
 122 public:
 123
 124   /**
 125    * @brief Create an uninitialized Button.
 126    *
 127    * Only derived versions can be instantiated.  Calling member
 128    * functions with an uninitialized Dali::Object is not allowed.
 129    */
 130   Button();
 131
 132   /**
 133    * @brief Copy constructor.
 134    */
 135   Button( const Button& button );
 136
 137   /**
 138    * @brief Assignment operator.
 139    */
 140   Button& operator=( const Button& button );
 141
 142   /**
 143    * @brief Downcast an Object handle to Button.
 144    *
 145    * If handle points to a Button the downcast produces valid
 146    * handle. If not the returned handle is left uninitialized.
 147    *
 148    * @param[in] handle Handle to an object
 149    * @return handle to a Button or an uninitialized handle
 150    */
 151   static Button DownCast( BaseHandle handle );
 152
 153   /**
 154    * @brief Destructor
 155    *
 156    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 157    */
 158   ~Button();
 159
 160   /**
 161    * @brief Sets the button as \e disabled.
 162    *
 163    * No signals are emitted when the \e disabled property is set.
 164    *
 165    * @param[in] disabled property.
 166    */
 167   void SetDisabled( bool disabled );
 168
 169   /**
 170    * @return \e true if the button is \e disabled.
 171    */
 172   bool IsDisabled() const;
 173
 174   /**
 175    * @brief Sets the \e autorepeating property.
 176    *
 177    * If the \e autorepeating property is set to \e true, then the \e togglable property is set to false
 178    * but no signal is emitted.
 179    *
 180    * @param[in] autoRepeating \e autorepeating property.
 181    */
 182   void SetAutoRepeating( bool autoRepeating );
 183
 184   /**
 185    * @return \e true if the \e autorepeating property is set.
 186    */
 187   bool IsAutoRepeating() const;
 188
 189   /**
 190    * @brief Sets the initial autorepeating delay.
 191    *
 192    * By default this value is set to 0.15 seconds.
 193    *
 194    * @pre initialAutoRepeatingDelay must be greater than zero.
 195    * @param[in] initialAutoRepeatingDelay in seconds.
 196    */
 197   void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
 198
 199   /**
 200    * @return the initial autorepeating delay in seconds.
 201    */
 202   float GetInitialAutoRepeatingDelay() const;
 203
 204   /**
 205    * @brief Sets the next autorepeating delay.
 206    *
 207    * By default this value is set to 0.05 seconds.
 208    *
 209    * @pre nextAutoRepeatingDelay must be greater than zero.
 210    * @param[in] nextAutoRepeatingDelay in seconds.
 211    */
 212   void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
 213
 214   /**
 215    * @return the next autorepeating delay in seconds.
 216    */
 217   float GetNextAutoRepeatingDelay() const;
 218
 219   /**
 220    * @brief Sets the \e togglable property.
 221    *
 222    * If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
 223    *
 224    * @param[in] togglable property.
 225    */
 226   void SetTogglableButton( bool togglable );
 227
 228   /**
 229    * @return \e true if the \e togglable property is set.
 230    */
 231   bool IsTogglableButton() const;
 232
 233   /**
 234    * Sets the button as selected or unselected.
 235    *
 236    * \e togglable property must be set to \e true.
 237    *
 238    * Emits a Button::StateChangedSignal() signal.
 239    *
 240    * @param[in] selected property.
 241    */
 242   void SetSelected( bool selected );
 243
 244   /**
 245    * @return \e true if the \e selected property is set and the button is togglable.
 246    */
 247   bool IsSelected() const;
 248
 249   /**
 250    * @brief Sets the animation time.
 251    *
 252    * @param[in] animationTime The animation time in seconds.
 253    */
 254   void SetAnimationTime( float animationTime );
 255
 256   /**
 257    * @brief Retrieves button's animation time.
 258    *
 259    * @return The animation time in seconds.
 260    */
 261   float GetAnimationTime() const;
 262
 263   /**
 264    * @brief Sets the button's label.
 265    *
 266    * @param[in] label The label text.
 267    */
 268   void SetLabelText( const std::string& label );
 269
 270   /**
 271    * @brief Gets the label.
 272    *
 273    * @return The label text.
 274    */
 275   std::string GetLabelText() const;
 276
 277   /**
 278    * @brief Sets the unselected button image.
 279    *
 280    * @param[in] filename The button image.
 281    */
 282   void SetUnselectedImage( const std::string& filename );
 283
 284   /**
 285    * @brief Sets the background image.
 286    *
 287    * @param[in] filename The background image.
 288    */
 289   void SetBackgroundImage( const std::string& filename );
 290
 291   /**
 292    * @brief Sets the selected image.
 293    *
 294    * @param[in] filename The selected image.
 295    */
 296   void SetSelectedImage( const std::string& filename );
 297
 298   /**
 299    * @brief Sets the selected background image.
 300    *
 301    * @param[in] filename The selected background image.
 302    */
 303   void SetSelectedBackgroundImage( const std::string& filename );
 304
 305   /**
 306    * @brief Sets the disabled background image.
 307    *
 308    * @param[in] filename The disabled background image.
 309    */
 310   void SetDisabledBackgroundImage( const std::string& filename );
 311
 312   /**
 313    * @brief Sets the disabled button image.
 314    *
 315    * @param[in] filename The disabled button image.
 316    */
 317   void SetDisabledImage( const std::string& filename );
 318
 319   /**
 320    * @brief Sets the disabled selected button image.
 321    *
 322    * @param[in] filename The disabled selected button image.
 323    */
 324   void SetDisabledSelectedImage( const std::string& filename );
 325
 326   // Deprecated API
 327
 328   /**
 329    * @brief Sets the label with an actor.
 330    *
 331    * @deprecated DALi 1.0.50
 332    *
 333    * @param[in]  label The actor to use as a label
 334    */
 335   void SetLabel( Actor label );
 336
 337   /**
 338    * @brief Sets the button image.
 339    *
 340    * @deprecated DALi 1.0.50
 341    *
 342    * @param[in]  image The button image.
 343    */
 344   void SetButtonImage( Image image );
 345
 346   /**
 347    * @brief Sets the selected image.
 348    *
 349    * @deprecated DALi 1.0.50
 350    *
 351    * @param[in]  image The selected image.
 352    */
 353   void SetSelectedImage( Image image );
 354
 355   /**
 356    * @brief Gets the button image.
 357    *
 358    * @deprecated DALi 1.0.50
 359    *
 360    * @return     An actor with the button image.
 361    */
 362   Actor GetButtonImage() const;
 363
 364   /**
 365    * @brief Gets the selected image.
 366    *
 367    * @deprecated DALi 1.0.50
 368    *
 369    * @return     An actor with the selected image.
 370    */
 371   Actor GetSelectedImage() const;
 372
 373 public: //Signals
 374
 375   /**
 376    * @brief Button signal type
 377    */
 378   typedef Signal< bool ( Button ) > ButtonSignalType;
 379
 380   /**
 381    * @brief This signal is emitted when the button is touched.
 382    *
 383    * A callback of the following type may be connected:
 384    * @code
 385    *   bool YourCallbackName( Button button );
 386    * @endcode
 387    * @return The signal to connect to.
 388    */
 389   ButtonSignalType& PressedSignal();
 390
 391   /**
 392    * @brief This signal is emitted when the button is touched and the touch point leaves the boundary of the button.
 393    *
 394    * A callback of the following type may be connected:
 395    * @code
 396    *   bool YourCallbackName( Button button );
 397    * @endcode
 398    * @return The signal to connect to.
 399    */
 400   ButtonSignalType& ReleasedSignal();
 401
 402   /**
 403    * @brief This signal is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
 404    *
 405    * A callback of the following type may be connected:
 406    * @code
 407    *   bool YourCallbackName( Button button );
 408    * @endcode
 409    * @return The signal to connect to.
 410    */
 411   ButtonSignalType& ClickedSignal();
 412
 413   /**
 414    * @brief This signal is emitted when the button's state is changed.
 415    * The application can get the state by calling IsSelected().
 416    *
 417    * A callback of the following type may be connected:
 418    * @code
 419    *   bool YourCallbackName( Button button );
 420    * @endcode
 421    * @return The signal to connect to.
 422    */
 423   ButtonSignalType& StateChangedSignal();
 424
 425 public: // Not intended for application developers
 426
 427   /**
 428    * @brief Creates a handle using the Toolkit::Internal implementation.
 429    *
 430    * @param[in]  implementation  The Control implementation.
 431    */
 432   DALI_INTERNAL Button( Internal::Button& implementation );
 433
 434   /**
 435    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 436    *
 437    * @param[in]  internal  A pointer to the internal CustomActor.
 438    */
 439   DALI_INTERNAL Button( Dali::Internal::CustomActor* internal );
 440 };
 441
 442 /**
 443  * @}
 444  */
 445 } // namespace Toolkit
 446
 447 } // namespace Dali
 448
 449 #endif // __DALI_TOOLKIT_BUTTON_H__