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