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