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   // Properties
  63   static const Property::Index PROPERTY_DISABLED;                     ///< name "disabled",                     @see SetDisabled(),                  type BOOLEAN
  64   static const Property::Index PROPERTY_AUTO_REPEATING;               ///< name "auto-repeating",               @see SetAutoRepeating(),             type BOOLEAN
  65   static const Property::Index PROPERTY_INITIAL_AUTO_REPEATING_DELAY; ///< name "initial-auto-repeating-delay", @see SetInitialAutoRepeatingDelay(), type FLOAT
  66   static const Property::Index PROPERTY_NEXT_AUTO_REPEATING_DELAY;    ///< name "next-auto-repeating-delay",    @see SetNextAutoRepeatingDelay(),    type FLOAT
  67   static const Property::Index PROPERTY_TOGGLABLE;                    ///< name "togglable",                    @see SetTogglableButton(),           type BOOLEAN
  68   static const Property::Index PROPERTY_SELECTED;                     ///< name "selected",                     @see SetSelected(),                  type BOOLEAN
  69   static const Property::Index PROPERTY_NORMAL_STATE_ACTOR;           ///< name "normal-state-actor",           @see SetButtonImage(),               type MAP
  70   static const Property::Index PROPERTY_SELECTED_STATE_ACTOR;         ///< name "selected-state-actor",         @see SetSelectedImage(),             type MAP
  71   static const Property::Index PROPERTY_DISABLED_STATE_ACTOR;         ///< name "disabled-state-actor",         @see SetDisabledImage(),             type MAP
  72   static const Property::Index PROPERTY_LABEL_ACTOR;                  ///< name "label-actor",                  @see SetLabel(),                     type MAP
  73
  74 public:
  75
  76   /**
  77    * @brief Create an uninitialized Button.
  78    *
  79    * Only derived versions can be instantiated.  Calling member
  80    * functions with an uninitialized Dali::Object is not allowed.
  81    */
  82   Button();
  83
  84   /**
  85    * @brief Copy constructor.
  86    */
  87   Button( const Button& button );
  88
  89   /**
  90    * @brief Assignment operator.
  91    */
  92   Button& operator=( const Button& button );
  93
  94   /**
  95    * @brief Downcast an Object handle to Button.
  96    *
  97    * If handle points to a Button the downcast produces valid
  98    * handle. If not the returned handle is left uninitialized.
  99    *
 100    * @param[in] handle Handle to an object
 101    * @return handle to a Button or an uninitialized handle
 102    */
 103   static Button DownCast( BaseHandle handle );
 104
 105   /**
 106    * @brief Destructor
 107    *
 108    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 109    */
 110   ~Button();
 111
 112   /**
 113    * @brief Sets the button as \e disabled.
 114    *
 115    * No signals are emitted when the \e disabled property is set.
 116    *
 117    * @param[in] disabled property.
 118    */
 119   void SetDisabled( bool disabled );
 120
 121   /**
 122    * @return \e true if the button is \e disabled.
 123    */
 124   bool IsDisabled() const;
 125
 126   /**
 127    * @brief Sets the \e autorepeating property.
 128    *
 129    * If the \e autorepeating property is set to \e true, then the \e togglable property is set to false
 130    * but no signal is emitted.
 131    *
 132    * @param[in] autoRepeating \e autorepeating property.
 133    */
 134   void SetAutoRepeating( bool autoRepeating );
 135
 136   /**
 137    * @return \e true if the \e autorepeating property is set.
 138    */
 139   bool IsAutoRepeating() const;
 140
 141   /**
 142    * @brief Sets the initial autorepeating delay.
 143    *
 144    * By default this value is set to 0.15 seconds.
 145    *
 146    * @pre initialAutoRepeatingDelay must be greater than zero.
 147    * @param[in] initialAutoRepeatingDelay in seconds.
 148    */
 149   void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
 150
 151   /**
 152    * @return the initial autorepeating delay in seconds.
 153    */
 154   float GetInitialAutoRepeatingDelay() const;
 155
 156   /**
 157    * @brief Sets the next autorepeating delay.
 158    *
 159    * By default this value is set to 0.05 seconds.
 160    *
 161    * @pre nextAutoRepeatingDelay must be greater than zero.
 162    * @param[in] nextAutoRepeatingDelay in seconds.
 163    */
 164   void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
 165
 166   /**
 167    * @return the next autorepeating delay in seconds.
 168    */
 169   float GetNextAutoRepeatingDelay() const;
 170
 171   /**
 172    * @brief Sets the \e togglable property.
 173    *
 174    * If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
 175    *
 176    * @param[in] togglable property.
 177    */
 178   void SetTogglableButton( bool togglable );
 179
 180   /**
 181    * @return \e true if the \e togglable property is set.
 182    */
 183   bool IsTogglableButton() const;
 184
 185   /**
 186    * Sets the button as selected or unselected.
 187    *
 188    * \e togglable property must be set to \e true.
 189    *
 190    * Emits a Button::StateChangedSignal() signal.
 191    *
 192    * @param[in] selected property.
 193    */
 194   void SetSelected( bool selected );
 195
 196   /**
 197    * @return \e true if the \e selected property is set and the button is togglable.
 198    */
 199   bool IsSelected() const;
 200
 201   /**
 202    * @brief Sets the animation time.
 203    *
 204    * @param [in] animationTime The animation time in seconds.
 205    */
 206   void SetAnimationTime( float animationTime );
 207
 208   /**
 209    * @brief Retrieves button's animation time.
 210    *
 211    * @return The animation time in seconds.
 212    */
 213   float GetAnimationTime() const;
 214
 215   /**
 216    * @brief Sets the button label.
 217    *
 218    * @param[in] label The button label.
 219    */
 220   void SetLabel( const std::string& label );
 221
 222   /**
 223    * @copydoc SetLabel( const std::string& label )
 224    */
 225   void SetLabel( Actor label );
 226
 227   /**
 228    * @brief Gets the label.
 229    *
 230    * @return An actor with the label.
 231    */
 232   Actor GetLabel() const;
 233
 234 public: //Signals
 235
 236   /**
 237    * @brief Button signal type
 238    */
 239   typedef Signal< bool ( Button ) > ButtonSignalType;
 240
 241   /**
 242    * @brief This signal is emitted when the button is touched.
 243    *
 244    * A callback of the following type may be connected:
 245    * @code
 246    *   bool YourCallbackName( Button button );
 247    * @endcode
 248    * @return The signal to connect to.
 249    */
 250   ButtonSignalType& PressedSignal();
 251
 252   /**
 253    * @brief This signal is emitted when the button is touched and the touch point leaves the boundary of the button.
 254    *
 255    * A callback of the following type may be connected:
 256    * @code
 257    *   bool YourCallbackName( Button button );
 258    * @endcode
 259    * @return The signal to connect to.
 260    */
 261   ButtonSignalType& ReleasedSignal();
 262
 263   /**
 264    * @brief This signal is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
 265    *
 266    * A callback of the following type may be connected:
 267    * @code
 268    *   bool YourCallbackName( Button button );
 269    * @endcode
 270    * @return The signal to connect to.
 271    */
 272   ButtonSignalType& ClickedSignal();
 273
 274   /**
 275    * @brief This signal is emitted when the button's state is changed.
 276    * The application can get the state by calling IsSelected().
 277    *
 278    * A callback of the following type may be connected:
 279    * @code
 280    *   bool YourCallbackName( Button button );
 281    * @endcode
 282    * @return The signal to connect to.
 283    */
 284   ButtonSignalType& StateChangedSignal();
 285
 286 public: // Not intended for application developers
 287
 288   /**
 289    * @brief Creates a handle using the Toolkit::Internal implementation.
 290    *
 291    * @param[in]  implementation  The Control implementation.
 292    */
 293   DALI_INTERNAL Button( Internal::Button& implementation );
 294
 295   /**
 296    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 297    *
 298    * @param[in]  internal  A pointer to the internal CustomActor.
 299    */
 300   DALI_INTERNAL Button( Dali::Internal::CustomActor* internal );
 301 };
 302
 303 } // namespace Toolkit
 304
 305 } // namespace Dali
 306
 307 #endif // __DALI_TOOLKIT_BUTTON_H__