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