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) 2014 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 public: //Signals
 252
 253   /**
 254    * @brief Button signal type
 255    */
 256   typedef Signal< bool ( Button ) > ButtonSignalType;
 257
 258   /**
 259    * @brief This signal is emitted when the button is touched.
 260    *
 261    * A callback of the following type may be connected:
 262    * @code
 263    *   bool YourCallbackName( Button button );
 264    * @endcode
 265    * @return The signal to connect to.
 266    */
 267   ButtonSignalType& PressedSignal();
 268
 269   /**
 270    * @brief This signal is emitted when the button is touched and the touch point leaves the boundary of the button.
 271    *
 272    * A callback of the following type may be connected:
 273    * @code
 274    *   bool YourCallbackName( Button button );
 275    * @endcode
 276    * @return The signal to connect to.
 277    */
 278   ButtonSignalType& ReleasedSignal();
 279
 280   /**
 281    * @brief This signal is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
 282    *
 283    * A callback of the following type may be connected:
 284    * @code
 285    *   bool YourCallbackName( Button button );
 286    * @endcode
 287    * @return The signal to connect to.
 288    */
 289   ButtonSignalType& ClickedSignal();
 290
 291   /**
 292    * @brief This signal is emitted when the button's state is changed.
 293    * The application can get the state by calling IsSelected().
 294    *
 295    * A callback of the following type may be connected:
 296    * @code
 297    *   bool YourCallbackName( Button button );
 298    * @endcode
 299    * @return The signal to connect to.
 300    */
 301   ButtonSignalType& StateChangedSignal();
 302
 303 public: // Not intended for application developers
 304
 305   /**
 306    * @brief Creates a handle using the Toolkit::Internal implementation.
 307    *
 308    * @param[in]  implementation  The Control implementation.
 309    */
 310   DALI_INTERNAL Button( Internal::Button& implementation );
 311
 312   /**
 313    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 314    *
 315    * @param[in]  internal  A pointer to the internal CustomActor.
 316    */
 317   DALI_INTERNAL Button( Dali::Internal::CustomActor* internal );
 318 };
 319
 320 } // namespace Toolkit
 321
 322 } // namespace Dali
 323
 324 #endif // __DALI_TOOLKIT_BUTTON_H__