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