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) 2020 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  * @addtogroup dali_toolkit_controls_buttons
  36  * @{
  37  */
  38
  39 /**
  40  * @brief Button is a base class for different kinds of buttons.
  41  *
  42  * This class provides the disabled property and the clicked signal.
  43  *
  44  * A ClickedSignal() is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
  45  *
  46  * When the \e disabled property is set to \e true, no signal is emitted.
  47  *
  48  * Button provides the following properties which modify the signals emitted:
  49  * <ul>
  50  *   <li>\e autorepeating
  51  *       When \e autorepeating is set to \e true, a Button::PressedSignal(), Button::ReleasedSignal() and Button::ClickedSignal() signals are emitted at regular
  52  *       intervals while the button is touched.
  53  *       The intervals could be modified with the Button::SetInitialAutoRepeatingDelay and Button::SetNextAutoRepeatingDelay methods.
  54  *
  55  *       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
  56  *       false but no signal is emitted.
  57  *
  58  *   <li>\e togglable
  59  *       When \e togglable is set to \e true, a Button::StateChangedSignal() signal is emitted, with the selected state.
  60  * </ul>
  61  *
  62  * 'Visual' describes not just traditional images like png, bmp but refers to whatever is used to show the button, it could be a color, gradient or some other kind of renderer.
  63  *
  64  * The button's appearance can be modified by setting properties for the various visuals/images.
  65  *
  66  * It is not mandatory to set all visuals. A button could be defined only by setting its \e background visual or by setting its \e background and \e selected visuals.
  67  *
  68  * The \e button visual is shown over the \e background visual.
  69  * When pressed the unselected visuals are replaced by the \e selected visual. The text label is always placed on the top of all images.
  70  *
  71  * When the button is disabled, \e background, \e button and \e selected visuals are replaced by their \e disabled visuals.
  72  *
  73  *
  74  * Signals
  75  * | %Signal Name     | Method                      |
  76  * |------------------|-----------------------------|
  77  * | pressed          | @ref PressedSignal()        |
  78  * | released         | @ref ReleasedSignal()       |
  79  * | clicked          | @ref ClickedSignal()        |
  80  * | stateChanged     | @ref StateChangedSignal()   |
  81  *
  82  * Actions
  83  * | %Action Name     | Attributes              | Description                                   |
  84  * |------------------|-------------------------|-----------------------------------------------|
  85  * | buttonClick      | Doesn't have attributes | Simulates a button click. See @ref DoAction() |
  86  * @SINCE_1_0.0
  87  */
  88 class DALI_TOOLKIT_API Button : public Control
  89 {
  90 public:
  91
  92   /**
  93    * @brief Enumeration for the start and end property ranges for this control.
  94    * @SINCE_1_0.0
  95    */
  96   enum PropertyRange
  97   {
  98     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
  99     PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000              ///< Reserve property indices @SINCE_1_0.0
 100   };
 101
 102   /**
 103    * @brief Enumeration for the instance of properties belonging to the Button class.
 104    * @SINCE_1_0.0
 105    */
 106   struct Property
 107   {
 108     /**
 109      * @brief Enumeration for the instance of properties belonging to the Button class.
 110      * @SINCE_1_0.0
 111      */
 112     enum
 113     {
 114       /**
 115        * @brief name "disabled", type bool
 116        * @details Sets the button as \e disabled.
 117        * @SINCE_1_0.0
 118        */
 119       DISABLED = PROPERTY_START_INDEX,
 120
 121       /**
 122        * @brief name "autoRepeating", type bool
 123        * @details If the \e autorepeating property is set to \e true then the \e togglable property is set to false
 124        * @SINCE_1_0.0
 125        */
 126       AUTO_REPEATING,
 127
 128       /**
 129        * @brief name "initialAutoRepeatingDelay", type float
 130        * @details By default this value is set to 0.15 seconds.
 131        * @SINCE_1_0.0
 132        */
 133       INITIAL_AUTO_REPEATING_DELAY,
 134
 135       /**
 136        * @brief name "nextAutoRepeatingDelay", type float
 137        * @details default this value is set to 0.05 seconds
 138        * @SINCE_1_0.0
 139        */
 140       NEXT_AUTO_REPEATING_DELAY,
 141
 142       /**
 143        * @brief name "togglable", type bool
 144        * @details If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
 145        * @SINCE_1_0.0
 146        */
 147       TOGGLABLE,
 148
 149       /**
 150        * @brief name "selected", type bool
 151        * @details Sets the togglable button as either selected or unselected, \e togglable property must be set to \e true.
 152        * @SINCE_1_0.0
 153        */
 154       SELECTED,
 155
 156       /**
 157        * @brief name "unselectedVisual", type string if it is a url, map otherwise.
 158        * @details Sets the unselected button foreground/icon visual
 159        * @SINCE_1_4.32
 160        */
 161       UNSELECTED_VISUAL,
 162
 163       /**
 164        * @brief name "selectedImage", type string if it is a url, map otherwise
 165        * @details Sets the selected button foreground/icon visual
 166        * @SINCE_1_4.32
 167        */
 168       SELECTED_VISUAL,
 169
 170       /**
 171        * @brief name "disabledSelectedVisual", type string if it is a url, map otherwise
 172        * @details Sets the disabled selected state foreground/icon button visual
 173        * @SINCE_1_4.32
 174        */
 175       DISABLED_SELECTED_VISUAL,
 176
 177       /**
 178        * @brief name "disabledUnselectedVisual", type string if it is a url, map otherwise
 179        * @details Sets the disabled unselected state foreground/icon visual
 180        * @SINCE_1_4.32
 181        */
 182       DISABLED_UNSELECTED_VISUAL,
 183
 184       /**
 185        * @brief name "unselectedBackgroundVisual", type string if it is a url, map otherwise
 186        * @details Sets the disabled in the unselected state background, button visual
 187        * @SINCE_1_4.32
 188        */
 189       UNSELECTED_BACKGROUND_VISUAL,
 190
 191       /**
 192        * @brief name "label", type Property::Map or std::string
 193        * @SINCE_1_0.0
 194        */
 195       LABEL,
 196
 197       /**
 198        * @brief name "selectedBackgroundVisual", type string if it is a url, map otherwise
 199        * @details Sets the selected background button visual
 200        * @SINCE_1_4.32
 201        */
 202       SELECTED_BACKGROUND_VISUAL,
 203
 204       /**
 205        * @brief name "disabledUnselectedBackgroundVisual", type string if it is a url, map otherwise
 206        * @details Sets the disabled while unselected background button visual
 207        * @SINCE_1_4.32
 208        */
 209       DISABLED_UNSELECTED_BACKGROUND_VISUAL,
 210
 211       /**
 212        * @brief name "disabledSelectedBackgroundVisual", type string if it is a url, map otherwise
 213        * @details Sets the disabled while selected background button visual
 214        * @SINCE_1_4.32
 215        */
 216       DISABLED_SELECTED_BACKGROUND_VISUAL,
 217     };
 218   };
 219
 220 public:
 221
 222   /**
 223    * @brief Creates an uninitialized Button.
 224    *
 225    * Only derived versions can be instantiated.  Calling member
 226    * functions with an uninitialized Dali::Object is not allowed.
 227    * @SINCE_1_0.0
 228    */
 229   Button();
 230
 231   /**
 232    * @brief Copy constructor.
 233    * @SINCE_1_0.0
 234    * @param[in] button Handle to an object
 235    */
 236   Button( const Button& button );
 237
 238   /**
 239    * @brief Move constructor
 240    * @SINCE_1_9.23
 241    *
 242    * @param[in] rhs A reference to the moved handle
 243    */
 244   Button( Button&& rhs );
 245
 246   /**
 247    * @brief Assignment operator.
 248    * @SINCE_1_0.0
 249    * @param[in] button Handle to an object
 250    * @return A reference to this
 251    */
 252   Button& operator=( const Button& button );
 253
 254   /**
 255    * @brief Move assignment
 256    * @SINCE_1_9.23
 257    *
 258    * @param[in] rhs A reference to the moved handle
 259    * @return A reference to this
 260    */
 261   Button& operator=( Button&& rhs );
 262
 263   /**
 264    * @brief Downcasts a handle to Button handle.
 265    *
 266    * If handle points to a Button, the downcast produces valid handle.
 267    * If not the returned handle is left uninitialized.
 268    *
 269    * @SINCE_1_0.0
 270    * @param[in] handle Handle to an object
 271    * @return A handle to a Button or an uninitialized handle
 272    */
 273   static Button DownCast( BaseHandle handle );
 274
 275   /**
 276    * @brief Destructor.
 277    *
 278    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 279    * @SINCE_1_0.0
 280    */
 281   ~Button();
 282
 283 public: //Signals
 284
 285   /**
 286    * @brief Button signal type.
 287    * @SINCE_1_0.0
 288    */
 289   typedef Signal< bool ( Button ) > ButtonSignalType;
 290
 291   /**
 292    * @brief This signal is emitted when the button is touched.
 293    *
 294    * A callback of the following type may be connected:
 295    * @code
 296    *   bool YourCallbackName( Button button );
 297    * @endcode
 298    * @SINCE_1_0.0
 299    * @return The signal to connect to
 300    */
 301   ButtonSignalType& PressedSignal();
 302
 303   /**
 304    * @brief This signal is emitted when the button is touched and the touch point leaves the boundary of the button.
 305    *
 306    * A callback of the following type may be connected:
 307    * @code
 308    *   bool YourCallbackName( Button button );
 309    * @endcode
 310    * @SINCE_1_0.0
 311    * @return The signal to connect to
 312    */
 313   ButtonSignalType& ReleasedSignal();
 314
 315   /**
 316    * @brief This signal is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
 317    *
 318    * A callback of the following type may be connected:
 319    * @code
 320    *   bool YourCallbackName( Button button );
 321    * @endcode
 322    * @SINCE_1_0.0
 323    * @return The signal to connect to
 324    */
 325   ButtonSignalType& ClickedSignal();
 326
 327   /**
 328    * @brief This signal is emitted when the button's state is changed.
 329    *
 330    * The application can get the state by calling IsSelected().
 331    *
 332    * A callback of the following type may be connected:
 333    * @code
 334    *   bool YourCallbackName( Button button );
 335    * @endcode
 336    * @SINCE_1_0.0
 337    * @return The signal to connect to
 338    */
 339   ButtonSignalType& StateChangedSignal();
 340
 341 public: // Not intended for application developers
 342
 343   /// @cond internal
 344   /**
 345    * @brief Creates a handle using the Toolkit::Internal implementation.
 346    *
 347    * @SINCE_1_0.0
 348    * @param[in] implementation The Control implementation
 349    */
 350   DALI_INTERNAL Button( Internal::Button& implementation );
 351
 352   /**
 353    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 354    *
 355    * @SINCE_1_0.0
 356    * @param[in] internal A pointer to the internal CustomActor
 357    */
 358   DALI_INTERNAL Button( Dali::Internal::CustomActor* internal );
 359   /// @endcond
 360 };
 361
 362 /**
 363  * @}
 364  */
 365 } // namespace Toolkit
 366
 367 } // namespace Dali
 368
 369 #endif // DALI_TOOLKIT_BUTTON_H