1 #ifndef __DALI_TOOLKIT_BUTTON_H__
2 #define __DALI_TOOLKIT_BUTTON_H__
5 * Copyright (c) 2018 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <dali-toolkit/public-api/controls/control.h>
30 namespace Internal DALI_INTERNAL
35 * @addtogroup dali_toolkit_controls_buttons
40 * @brief Button is a base class for different kinds of buttons.
42 * This class provides the disabled property and the clicked signal.
44 * A ClickedSignal() is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
46 * When the \e disabled property is set to \e true, no signal is emitted.
48 * Button provides the following properties which modify the signals emitted:
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.
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.
59 * When \e togglable is set to \e true, a Button::StateChangedSignal() signal is emitted, with the selected state.
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.
64 * The button's appearance can be modified by setting properties for the various visuals/images.
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.
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.
71 * When the button is disabled, \e background, \e button and \e selected visuals are replaced by their \e disabled visuals.
75 * | %Signal Name | Method |
76 * |------------------|-----------------------------|
77 * | pressed | @ref PressedSignal() |
78 * | released | @ref ReleasedSignal() |
79 * | clicked | @ref ClickedSignal() |
80 * | stateChanged | @ref StateChangedSignal() |
83 * | %Action Name | Attributes | Description |
84 * |------------------|-------------------------|-----------------------------------------------|
85 * | buttonClick | Doesn't have attributes | Simulates a button click. See @ref DoAction() |
88 class DALI_TOOLKIT_API Button : public Control
93 * @brief Enumeration for the start and end property ranges for this control.
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
103 * @brief Enumeration for the instance of properties belonging to the Button class.
109 * @brief Enumeration for the instance of properties belonging to the Button class.
115 * @brief name "disabled", type bool
116 * @details Sets the button as \e disabled.
119 DISABLED = PROPERTY_START_INDEX,
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
129 * @brief name "initialAutoRepeatingDelay", type float
130 * @details By default this value is set to 0.15 seconds.
133 INITIAL_AUTO_REPEATING_DELAY,
136 * @brief name "nextAutoRepeatingDelay", type float
137 * @details default this value is set to 0.05 seconds
140 NEXT_AUTO_REPEATING_DELAY,
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.
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.
157 * @DEPRECATED_1_1.XX Use UNSELECTED_VISUAL
158 * @brief name "unselectedStateImage", type string if it is a url, map otherwise
159 * @details Sets the unselected button foreground image
162 UNSELECTED_STATE_IMAGE,
165 * @DEPRECATED_1_1.XX Use SELECTED_VISUAL
166 * @brief name "selectedStateImage", type string if it is a url, map otherwise
167 * @details Sets the selected button foreground image
170 SELECTED_STATE_IMAGE,
173 * @DEPRECATED_1_1.XX Use DISABLED_UNSELECTED_VISUAL
174 * @brief name "disabledStateImage", type string if it is a url, map otherwise
175 * @details Sets the disabled whilst unselected foreground button visual
178 DISABLED_STATE_IMAGE,
181 * @DEPRECATED_1_1.XX Use UNSELECTED_BACKGROUND_VISUAL
182 * @brief name "unselectedColor", type Vector4
188 * @DEPRECATED_1_1.XX Use SELECTED_BACKGROUND_VISUAL
189 * @brief name "selectedColor", type Vector4
195 * @brief name "label", type Property::Map or std::string
201 * @DEPRECATED_1_1.32 Use LABEL
202 * @brief name "labelText", type std::string
212 * @brief Creates an uninitialized Button.
214 * Only derived versions can be instantiated. Calling member
215 * functions with an uninitialized Dali::Object is not allowed.
221 * @brief Copy constructor.
223 * @param[in] button Handle to an object
225 Button( const Button& button );
228 * @brief Assignment operator.
230 * @param[in] button Handle to an object
231 * @return A reference to this
233 Button& operator=( const Button& button );
236 * @brief Downcasts a handle to Button handle.
238 * If handle points to a Button, the downcast produces valid handle.
239 * If not the returned handle is left uninitialized.
242 * @param[in] handle Handle to an object
243 * @return A handle to a Button or an uninitialized handle
245 static Button DownCast( BaseHandle handle );
250 * This is non-virtual since derived Handle types must not contain data or virtual methods.
258 * @DEPRECATED_1_1.32 Use SetProperty DISABLED or Styling file
260 * @brief Sets the button as \e disabled.
262 * No signals are emitted when the \e disabled property is set.
265 * @param[in] disabled Disabled property
267 void SetDisabled( bool disabled ) DALI_DEPRECATED_API;
270 * @DEPRECATED_1_1.32 Use GetProperty DISABLED
272 * @brief Returns if the button is disabled.
274 * @return \e true if the button is \e disabled
276 bool IsDisabled() const DALI_DEPRECATED_API;
279 * @DEPRECATED_1_1.32 SetProperty AUTO_REPEATING or Styling file
281 * @brief Sets the \e autorepeating property.
283 * If the \e autorepeating property is set to \e true, then the \e togglable property is set to false
284 * but no signal is emitted.
287 * @param[in] autoRepeating \e autorepeating property
289 void SetAutoRepeating( bool autoRepeating ) DALI_DEPRECATED_API;
292 * @DEPRECATED_1_1.32 GetProperty AUTO_REPEATING
294 * @brief Returns if the autorepeating property is set.
296 * @return \e true if the \e autorepeating property is set
298 bool IsAutoRepeating() const DALI_DEPRECATED_API;
301 * @DEPRECATED_1_1.32 SetProperty INITIAL_AUTO_REPEATING_DELAY or Styling file
303 * @brief Sets the initial autorepeating delay.
305 * By default, this value is set to 0.15 seconds.
308 * @param[in] initialAutoRepeatingDelay in seconds
309 * @pre initialAutoRepeatingDelay must be greater than zero.
311 void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay ) DALI_DEPRECATED_API;
314 * @DEPRECATED_1_1.32 GetProperty INITIAL_AUTO_REPEATING_DELAY
316 * @brief Gets the initial autorepeating delay in seconds.
318 * @return The initial autorepeating delay in seconds
320 float GetInitialAutoRepeatingDelay() const DALI_DEPRECATED_API;
323 * @DEPRECATED_1_1.32 SetProperty NEXT_AUTO_REPEATING_DELAY or Styling file
325 * @brief Sets the next autorepeating delay.
327 * By default, this value is set to 0.05 seconds.
330 * @param[in] nextAutoRepeatingDelay in seconds
331 * @pre nextAutoRepeatingDelay must be greater than zero.
333 void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay ) DALI_DEPRECATED_API;
336 * @DEPRECATED_1_1.32 GetProperty NEXT_AUTO_REPEATING_DELAY
338 * @brief Gets the next autorepeating delay in seconds.
340 * @return The next autorepeating delay in seconds
342 float GetNextAutoRepeatingDelay() const DALI_DEPRECATED_API;
345 * @DEPRECATED_1_1.32 SetProperty TOGGLABLE or Styling file
347 * @brief Sets the \e togglable property.
349 * If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
352 * @param[in] togglable Togglable property
354 void SetTogglableButton( bool togglable ) DALI_DEPRECATED_API;
357 * @DEPRECATED_1_1.32 GetProperty TOGGLABLE
359 * @brief Returns if the togglable property is set.
361 * @return \e true if the \e togglable property is set
363 bool IsTogglableButton() const DALI_DEPRECATED_API;
366 * @DEPRECATED_1_1.32 SetProperty SELECTED
368 * @brief Sets the button as selected or unselected.
370 * \e togglable property must be set to \e true.
372 * Emits a Button::StateChangedSignal() signal.
375 * @param[in] selected Selected property
377 void SetSelected( bool selected ) DALI_DEPRECATED_API;
380 * DEPRECATED_1_1.32 GetProperty SELECTED
382 * @brief Returns if the selected property is set and the button is togglable.
384 * @return \e true if the button is \e selected
386 bool IsSelected() const DALI_DEPRECATED_API;
389 * @DEPRECATED_1_1.32 Use Styling file to set animation
391 * @brief Sets the animation time.
394 * @param[in] animationTime The animation time in seconds
396 void SetAnimationTime( float animationTime ) DALI_DEPRECATED_API;
399 * DEPRECATED_1_1.32 Use Styling file to set animation
401 * @brief Retrieves button's animation time.
404 * @return The animation time in seconds
406 float GetAnimationTime() const DALI_DEPRECATED_API;
409 * @DEPRECATED_1_1.32 SetProperty Property::LABEL or Styling file
411 * @brief Sets the button's label.
414 * @param[in] label The label text
416 void SetLabelText( const std::string& label ) DALI_DEPRECATED_API;
419 * DEPRECATED_1_1.32 GetProperty LABEL
421 * @brief Gets the label.
424 * @return The label text
426 std::string GetLabelText() const DALI_DEPRECATED_API;
429 * @DEPRECATED_1_1.32 Use Styling file Property::UNSELECTED_STATE_IMAGE
431 * @brief Sets the unselected button image.
434 * @param[in] filename The button image
436 void SetUnselectedImage( const std::string& filename ) DALI_DEPRECATED_API;
439 * @DEPRECATED_1_1.32 Use styling Set Control::Property::BACKGROUND which is same as un-selected background
440 * Or use DevelButton::Property::UNSELECTED_BACKGROUND_VISUAL
442 * @brief Sets the background image.
445 * @param[in] filename The background image
447 void SetBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
450 * @DEPRECATED_1_1.32 Use styling file, Property::SELECTED_STATE_IMAGE
452 * @brief Sets the selected image.
455 * @param[in] filename The selected image
457 void SetSelectedImage( const std::string& filename ) DALI_DEPRECATED_API;
460 * @DEPRECATED_1_1.32 Set Control::Property::BACKGROUND which is same as un-selected background
461 * Or use DevelButton::Property::SELECTED_BACKGROUND_VISUAL
463 * @brief Sets the selected background image.
466 * @param[in] filename The selected background image
468 void SetSelectedBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
471 * @DEPRECATED_1_1.32 Only able to set Property::DISABLED_STATE_IMAGE
472 * Or use DevelButton::Property::DISABLED_SELECTED_BACKGROUND_VISUAL
474 * @brief Sets the disabled background image.
477 * @param[in] filename The disabled background image
479 void SetDisabledBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
482 * @DEPRECATED_1_1.32 Use styling file Property::DISABLED_STATE_IMAGE
484 * @brief Sets the disabled button image.
487 * @param[in] filename The disabled button image
489 void SetDisabledImage( const std::string& filename ) DALI_DEPRECATED_API;
492 * @DEPRECATED_1_1.32 Use Property::DISABLED_STATE_IMAGE which provides same disabled image for un/selected
493 * Or DevelButton::Property::DISABLED_SELECTED_VISUAL to disable selected visual.
495 * @brief Sets the disabled selected button image.
498 * @param[in] filename The disabled selected button image
500 void SetDisabledSelectedImage( const std::string& filename ) DALI_DEPRECATED_API;
503 * @DEPRECATED_1_0.50. Instead, use SetLabelText
505 * @brief Sets the label with an actor.
508 * @param[in] label The actor to use as a label
510 void SetLabel( Actor label ) DALI_DEPRECATED_API;
513 * @DEPRECATED_1_0.50. Instead, use SetUnselectedImage.
515 * @brief Sets the button image.
518 * @param[in] image The button image
520 void SetButtonImage( Image image ) DALI_DEPRECATED_API;
523 * @DEPRECATED_1_0.50. Instead, use SetSelectedImage( const std::string& filename ).
525 * @brief Sets the selected image.
528 * @param[in] image The selected image
530 void SetSelectedImage( Image image ) DALI_DEPRECATED_API;
535 * @brief Gets the button image.
538 * @remarks Avoid using this method as it's a legacy code.
539 * @return An actor with the button image
541 Actor GetButtonImage() const DALI_DEPRECATED_API;
546 * @brief Gets the selected image.
549 * @remarks Avoid using this method as it's a legacy code.
550 * @return An actor with the selected image
552 Actor GetSelectedImage() const DALI_DEPRECATED_API;
557 * @brief Button signal type.
560 typedef Signal< bool ( Button ) > ButtonSignalType;
563 * @brief This signal is emitted when the button is touched.
565 * A callback of the following type may be connected:
567 * bool YourCallbackName( Button button );
570 * @return The signal to connect to
572 ButtonSignalType& PressedSignal();
575 * @brief This signal is emitted when the button is touched and the touch point leaves the boundary of the button.
577 * A callback of the following type may be connected:
579 * bool YourCallbackName( Button button );
582 * @return The signal to connect to
584 ButtonSignalType& ReleasedSignal();
587 * @brief This signal is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
589 * A callback of the following type may be connected:
591 * bool YourCallbackName( Button button );
594 * @return The signal to connect to
596 ButtonSignalType& ClickedSignal();
599 * @brief This signal is emitted when the button's state is changed.
601 * The application can get the state by calling IsSelected().
603 * A callback of the following type may be connected:
605 * bool YourCallbackName( Button button );
608 * @return The signal to connect to
610 ButtonSignalType& StateChangedSignal();
612 public: // Not intended for application developers
616 * @brief Creates a handle using the Toolkit::Internal implementation.
619 * @param[in] implementation The Control implementation
621 DALI_INTERNAL Button( Internal::Button& implementation );
624 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
627 * @param[in] internal A pointer to the internal CustomActor
629 DALI_INTERNAL Button( Dali::Internal::CustomActor* internal );
636 } // namespace Toolkit
640 #endif // __DALI_TOOLKIT_BUTTON_H__