1 #ifndef __DALI_TOOLKIT_BUTTON_H__
2 #define __DALI_TOOLKIT_BUTTON_H__
5 * Copyright (c) 2015 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 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 * @brief A control which renders a short text string.
77 * Text labels are lightweight, non-editable and do not respond to user input.
80 * @section ButtonProperties Properties
81 * |%Property enum |String name |Type |Writable|Animatable|
82 * |-------------------------------------------------------|----------------------------------------|--------------|--------|----------|
83 * | Property::DISABLED | disabled | BOOLEAN | Y | N |
84 * | Property::AUTO_REPEATING | autoRepeating | BOOLEAN | Y | N |
85 * | Property::INITIAL_AUTO_REPEATING_DELAY | initialAutoRepeatingDelay | FLOAT | Y | N |
86 * | Property::NEXT_AUTO_REPEATING_DELAY | nextAutoRepeatingDelay | FLOAT | Y | N |
87 * | Property::TOGGLABLE | togglable | BOOLEAN | Y | N |
88 * | Property::SELECTED | selected | BOOLEAN | Y | N |
89 * | Property::LABEL | label | MAP | Y | N |
90 * | Property::UNSELECTED_STATE_VISUAL | unselectedVisual | MAP | Y | N |
91 * | Property::SELECTED_VISUAL | selectedVisual | MAP | Y | N |
92 * | Property::DISABLED_SELECTED_VISUAL | disabledSelectedVisual | MAP | Y | N |
93 * | Property::DISABLED_UNSELECTED_VISUAL | disabledUnselectedVisual | MAP | Y | N |
94 * | Property::UNSELECTED_BACKGROUND_VISUAL | unselectedBackgroundVisual | MAP | Y | N |
95 * | Property::SELECTED_BACKGROUND_VISUAL | selectedBackgroundVisual | MAP | Y | N |
96 * | Property::DISABLED_UNSELECTED_BACKGROUND_VISUAL | disabledUnselectedBackgroundVisual | MAP | Y | N |
97 * | Property::DISABLED_SELECTED_BACKGROUND_VISUAL | disabledSelectedBackgroundVisual | MAP | Y | N |
98 * | Property::LABEL_STRUT_LENGTH | labelStrutLength | INTEGER | Y | N |
99 * | Property::LABEL_RELATIVE_ALIGNMENT | labelRelativeAlignment | STRING | Y | N |
100 * -------------------------------------------------------------------------------------------------------------------------------------
102 * Note, *_VISUAL properties of type MAP can also be passed a uri of type STRING
105 * | %Signal Name | Method |
106 * |------------------|-----------------------------|
107 * | pressed | @ref PressedSignal() |
108 * | released | @ref ReleasedSignal() |
109 * | clicked | @ref ClickedSignal() |
110 * | stateChanged | @ref StateChangedSignal() |
113 * | %Action Name | Attributes | Description |
114 * |------------------|-------------------------|-----------------------------------------------|
115 * | buttonClick | Doesn't have attributes | Simulates a button click. See @ref DoAction() |
118 class DALI_IMPORT_API Button : public Control
123 * @brief The start and end property ranges for this control.
128 PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
129 PROPERTY_END_INDEX = PROPERTY_START_INDEX + 1000 ///< Reserve property indices @SINCE_1_0.0
133 * @brief An enumeration of properties belonging to the Button class.
139 * @brief An enumeration of properties belonging to the Button class.
145 * @brief name "disabled", type bool
146 * @details Sets the button as \e disabled.
149 DISABLED = PROPERTY_START_INDEX,
152 * @brief name "autoRepeating", type bool
153 * @details If the \e autorepeating property is set to \e true then the \e togglable property is set to false
159 * @brief name "initialAutoRepeatingDelay", type float
160 * @details By default this value is set to 0.15 seconds.
163 INITIAL_AUTO_REPEATING_DELAY,
166 * @brief name "nextAutoRepeatingDelay", type float
167 * @details default this value is set to 0.05 seconds
170 NEXT_AUTO_REPEATING_DELAY,
173 * @brief name "togglable", type bool
174 * @details If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
180 * @brief name "selected", type bool
181 * @details Sets the togglable button as either selected or unselected, \e togglable property must be set to \e true.
187 * @DEPRECATED_1_1.XX Use UNSELECTED_VISUAL
188 * @brief name "unselectedStateImage", type string if it is a url, map otherwise
189 * @details Sets the unselected button foreground image
192 UNSELECTED_STATE_IMAGE,
195 * @DEPRECATED_1_1.XX Use SELECTED_VISUAL
196 * @brief name "selectedStateImage", type string if it is a url, map otherwise
197 * @details Sets the selected button foreground image
200 SELECTED_STATE_IMAGE,
203 * @DEPRECATED_1_1.XX Use DISABLED_UNSELECTED_VISUAL
204 * @brief name "disabledStateImage", type string if it is a url, map otherwise
205 * @details Sets the disabled whilst unselected foreground button visual
208 DISABLED_STATE_IMAGE,
211 * @DEPRECATED_1_1.XX Use UNSELECTED_BACKGROUND_VISUAL
212 * @brief name "unselectedColor", type Vector4
218 * @DEPRECATED_1_1.XX Use SELECTED_BACKGROUND_VISUAL
219 * @brief name "selectedColor", type Vector4
225 * @brief name "label", type Property::Map
231 * @DEPRECATED_1_1.32 Use LABEL
232 * @brief name "labelText", type std::string
238 * @brief name "unselectedVisual", type string if it is a url, map otherwise
239 * @details Sets the unselected button foreground/icon visual
245 * @brief name "selectedImage", type string if it is a url, map otherwise
246 * @details Sets the selected button foreground/icon visual
252 * @brief name "disabledSelectedVisual", type string if it is a url, map otherwise
253 * @details Sets the disabled selected state foreground/icon button visual
256 DISABLED_SELECTED_VISUAL,
259 * @brief name "disabledUnSelectedVisual", type string if it is a url, map otherwise
260 * @details Sets the disabled unselected state foreground/icon visual
263 DISABLED_UNSELECTED_VISUAL,
266 * @brief name "unselectedBackgroundVisual", type string if it is a url, map otherwise
267 * @details Sets the disabled in the unselected state background, button visual
270 UNSELECTED_BACKGROUND_VISUAL,
273 * @brief name "selectedBackgroundVisual", type string if it is a url, map otherwise
274 * @details Sets the selected background button visual
277 SELECTED_BACKGROUND_VISUAL,
280 * @brief name "disabledUnselectedBackgroundVisual", type string if it is a url, map otherwise
281 * @details Sets the disabled while unselected background button visual
284 DISABLED_UNSELECTED_BACKGROUND_VISUAL,
287 * @brief name "disabledSelectedBackgroundVisual", type string if it is a url, map otherwise
288 * @details Sets the disabled while selected background button visual
291 DISABLED_SELECTED_BACKGROUND_VISUAL,
294 * @brief name "labelStrutLength", type INTEGER
295 * @details Sets the distance between the label and foreground/icon visual if both present
298 LABEL_STRUT_LENGTH, // todo ????? remove
301 * @brief name "labelRelativeAlignment", type STRING
302 * @details Sets the position of the the label in relation to the foreground/icon if both present
305 LABEL_RELATIVE_ALIGNMENT,
312 * @brief Create an uninitialized Button.
314 * Only derived versions can be instantiated. Calling member
315 * functions with an uninitialized Dali::Object is not allowed.
321 * @brief Copy constructor.
323 * @param[in] button Handle to an object
325 Button( const Button& button );
328 * @brief Assignment operator.
330 * @param[in] button Handle to an object
331 * @return A reference to this
333 Button& operator=( const Button& button );
336 * @brief Downcast a handle to Button handle.
338 * If handle points to a Button the downcast produces valid
339 * handle. If not the returned handle is left uninitialized.
342 * @param[in] handle Handle to an object
343 * @return A handle to a Button or an uninitialized handle
345 static Button DownCast( BaseHandle handle );
350 * This is non-virtual since derived Handle types must not contain data or virtual methods.
358 * @DEPRECATED_1_1.32 Use SetProperty DISABLED or Styling file
360 * @brief Sets the button as \e disabled.
362 * No signals are emitted when the \e disabled property is set.
365 * @param[in] disabled property.
367 void SetDisabled( bool disabled ) DALI_DEPRECATED_API;
370 * @DEPRECATED_1_1.32 Use GetProperty DISABLED
372 * @brief Returns if the button is disabled.
374 * @return \e true if the button is \e disabled.
376 bool IsDisabled() const DALI_DEPRECATED_API;
379 * @DEPRECATED_1_1.32 SetProperty AUTO_REPEATING or Styling file
381 * @brief Sets the \e autorepeating property.
383 * If the \e autorepeating property is set to \e true, then the \e togglable property is set to false
384 * but no signal is emitted.
387 * @param[in] autoRepeating \e autorepeating property.
389 void SetAutoRepeating( bool autoRepeating ) DALI_DEPRECATED_API;
392 * @DEPRECATED_1_1.32 GetProperty AUTO_REPEATING
394 * @brief Returns if the autorepeating property is set.
396 * @return \e true if the \e autorepeating property is set.
398 bool IsAutoRepeating() const DALI_DEPRECATED_API;
401 * @DEPRECATED_1_1.32 SetProperty INITIAL_AUTO_REPEATING_DELAY or Styling file
403 * @brief Sets the initial autorepeating delay.
405 * By default this value is set to 0.15 seconds.
408 * @param[in] initialAutoRepeatingDelay in seconds.
409 * @pre initialAutoRepeatingDelay must be greater than zero.
411 void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay ) DALI_DEPRECATED_API;
414 * @DEPRECATED_1_1.32 GetProperty INITIAL_AUTO_REPEATING_DELAY
416 * @brief Gets the initial autorepeating delay in seconds.
418 * @return the initial autorepeating delay in seconds.
420 float GetInitialAutoRepeatingDelay() const DALI_DEPRECATED_API;
423 * @DEPRECATED_1_1.32 SetProperty NEXT_AUTO_REPEATING_DELAY or Styling file
425 * @brief Sets the next autorepeating delay.
427 * By default this value is set to 0.05 seconds.
430 * @param[in] nextAutoRepeatingDelay in seconds.
431 * @pre nextAutoRepeatingDelay must be greater than zero.
433 void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay ) DALI_DEPRECATED_API;
436 * @DEPRECATED_1_1.32 GetProperty NEXT_AUTO_REPEATING_DELAY
438 * @brief Gets the next autorepeating delay in seconds.
440 * @return the next autorepeating delay in seconds.
442 float GetNextAutoRepeatingDelay() const DALI_DEPRECATED_API;
445 * @DEPRECATED_1_1.32 SetProperty TOGGLABLE or Styling file
447 * @brief Sets the \e togglable property.
449 * If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
452 * @param[in] togglable property.
454 void SetTogglableButton( bool togglable ) DALI_DEPRECATED_API;
457 * @DEPRECATED_1_1.32 GetProperty TOGGLABLE
459 * @brief Returns if the togglable property is set.
461 * @return \e true if the \e togglable property is set.
463 bool IsTogglableButton() const DALI_DEPRECATED_API;
466 * @DEPRECATED_1_1.32 SetProperty SELECTED
468 * @brief Sets the button as selected or unselected.
470 * \e togglable property must be set to \e true.
472 * Emits a Button::StateChangedSignal() signal.
475 * @param[in] selected property.
477 void SetSelected( bool selected ) DALI_DEPRECATED_API;
480 * DEPRECATED_1_1.32 GetProperty SELECTED
482 * @brief Returns if the selected property is set and the button is togglable.
484 * @return \e true if the button is \e selected.
486 bool IsSelected() const DALI_DEPRECATED_API;
489 * @DEPRECATED_1_1.32 Use Styling file to set animation
491 * @brief Sets the animation time.
494 * @param[in] animationTime The animation time in seconds.
496 void SetAnimationTime( float animationTime ) DALI_DEPRECATED_API;
499 * DEPRECATED_1_1.32 Use Styling file to set animation
501 * @brief Retrieves button's animation time.
504 * @return The animation time in seconds.
506 float GetAnimationTime() const DALI_DEPRECATED_API;
509 * @DEPRECATED_1_1.32 SetProperty Property::LABEL or Styling file
511 * @brief Sets the button's label.
514 * @param[in] label The label text.
516 void SetLabelText( const std::string& label ) DALI_DEPRECATED_API;
519 * DEPRECATED_1_1.32 GetProperty LABEL
521 * @brief Gets the label.
524 * @return The label text.
526 std::string GetLabelText() const DALI_DEPRECATED_API;
529 * @DEPRECATED_1_1.32 Use Styling file Property::UNSELECTED_STATE_IMAGE
531 * @brief Sets the unselected button image.
534 * @param[in] filename The button image.
536 void SetUnselectedImage( const std::string& filename ) DALI_DEPRECATED_API;
539 * @DEPRECATED_1_1.32 Use styling
540 * Use Property::UNSELECTED_BACKGROUND_VISUAL
542 * @brief Sets the unselected background image.
545 * @param[in] filename The background image.
547 void SetBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
550 * @DEPRECATED_1_1.32 Use styling file, Property::SELECTED_STATE_IMAGE
552 * @brief Sets the selected image.
555 * @param[in] filename The selected image.
557 void SetSelectedImage( const std::string& filename ) DALI_DEPRECATED_API;
560 * @DEPRECATED_1_2.32 Use styling file
561 * Use Property::SELECTED_BACKGROUND_VISUAL
563 * @brief Sets the selected background image.
566 * @param[in] filename The selected background image.
568 void SetSelectedBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
571 * @DEPRECATED_1_1.32 Use styling file
572 * Use Property::DISABLED_SELECTED_BACKGROUND_VISUAL
574 * @brief Sets the disabled background image.
577 * @param[in] filename The disabled background image.
579 void SetDisabledBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
582 * @DEPRECATED_1_1.32 Use styling file Property::DISABLED_STATE_IMAGE
584 * @brief Sets the disabled button image.
587 * @param[in] filename The disabled button image.
589 void SetDisabledImage( const std::string& filename ) DALI_DEPRECATED_API;
592 * @DEPRECATED_1_1.32 Use styling file
593 * Use Property::DISABLED_SELECTED_VISUAL
595 * @brief Sets the disabled selected button image.
598 * @param[in] filename The disabled selected button image.
600 void SetDisabledSelectedImage( const std::string& filename ) DALI_DEPRECATED_API;
603 * @DEPRECATED_1_0.50. Instead, use SetLabelText.
605 * @brief Sets the label with an actor.
608 * @param[in] label The actor to use as a label
610 void SetLabel( Actor label ) DALI_DEPRECATED_API;
613 * @DEPRECATED_1_0.50. Instead, use SetUnselectedImage.
615 * @brief Sets the button image.
618 * @param[in] image The button image.
620 void SetButtonImage( Image image ) DALI_DEPRECATED_API;
623 * @DEPRECATED_1_0.50. Instead, use SetSelectedImage( const std::string& filename ).
625 * @brief Sets the selected image.
628 * @param[in] image The selected image.
630 void SetSelectedImage( Image image ) DALI_DEPRECATED_API;
635 * @brief Gets the button image.
638 * @remarks Avoid using this method as it's a legacy code.
639 * @return An actor with the button image.
641 Actor GetButtonImage() const DALI_DEPRECATED_API;
646 * @brief Gets the selected image.
649 * @remarks Avoid using this method as it's a legacy code.
650 * @return An actor with the selected image.
652 Actor GetSelectedImage() const DALI_DEPRECATED_API;
657 * @brief Button signal type
660 typedef Signal< bool ( Button ) > ButtonSignalType;
663 * @brief This signal is emitted when the button is touched.
665 * A callback of the following type may be connected:
667 * bool YourCallbackName( Button button );
670 * @return The signal to connect to.
672 ButtonSignalType& PressedSignal();
675 * @brief This signal is emitted when the button is touched and the touch point leaves the boundary of the button.
677 * A callback of the following type may be connected:
679 * bool YourCallbackName( Button button );
682 * @return The signal to connect to.
684 ButtonSignalType& ReleasedSignal();
687 * @brief This signal is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
689 * A callback of the following type may be connected:
691 * bool YourCallbackName( Button button );
694 * @return The signal to connect to.
696 ButtonSignalType& ClickedSignal();
699 * @brief This signal is emitted when the button's state is changed.
701 * The application can get the state by calling IsSelected().
703 * A callback of the following type may be connected:
705 * bool YourCallbackName( Button button );
708 * @return The signal to connect to.
710 ButtonSignalType& StateChangedSignal();
712 public: // Not intended for application developers
716 * @brief Creates a handle using the Toolkit::Internal implementation.
719 * @param[in] implementation The Control implementation.
721 DALI_INTERNAL Button( Internal::Button& implementation );
724 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
727 * @param[in] internal A pointer to the internal CustomActor.
729 DALI_INTERNAL Button( Dali::Internal::CustomActor* internal );
736 } // namespace Toolkit
740 #endif // __DALI_TOOLKIT_BUTTON_H__