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