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_RELATIVE_ALIGNMENT | labelRelativeAlignment | STRING | Y | N |
99 * -------------------------------------------------------------------------------------------------------------------------------------
101 * Note, *_VISUAL properties of type MAP can also be passed a uri of type STRING
104 * | %Signal Name | Method |
105 * |------------------|-----------------------------|
106 * | pressed | @ref PressedSignal() |
107 * | released | @ref ReleasedSignal() |
108 * | clicked | @ref ClickedSignal() |
109 * | stateChanged | @ref StateChangedSignal() |
112 * | %Action Name | Attributes | Description |
113 * |------------------|-------------------------|-----------------------------------------------|
114 * | buttonClick | Doesn't have attributes | Simulates a button click. See @ref DoAction() |
117 class DALI_IMPORT_API Button : public Control
122 * @brief The start and end property ranges for this control.
127 PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
128 PROPERTY_END_INDEX = PROPERTY_START_INDEX + 1000 ///< Reserve property indices @SINCE_1_0.0
132 * @brief An enumeration of properties belonging to the Button class.
138 * @brief An enumeration of properties belonging to the Button class.
144 * @brief name "disabled", type bool
145 * @details Sets the button as \e disabled.
148 DISABLED = PROPERTY_START_INDEX,
151 * @brief name "autoRepeating", type bool
152 * @details If the \e autorepeating property is set to \e true then the \e togglable property is set to false
158 * @brief name "initialAutoRepeatingDelay", type float
159 * @details By default this value is set to 0.15 seconds.
162 INITIAL_AUTO_REPEATING_DELAY,
165 * @brief name "nextAutoRepeatingDelay", type float
166 * @details default this value is set to 0.05 seconds
169 NEXT_AUTO_REPEATING_DELAY,
172 * @brief name "togglable", type bool
173 * @details If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
179 * @brief name "selected", type bool
180 * @details Sets the togglable button as either selected or unselected, \e togglable property must be set to \e true.
186 * @DEPRECATED_1_1.XX Use UNSELECTED_VISUAL
187 * @brief name "unselectedStateImage", type string if it is a url, map otherwise
188 * @details Sets the unselected button foreground image
191 UNSELECTED_STATE_IMAGE,
194 * @DEPRECATED_1_1.XX Use SELECTED_VISUAL
195 * @brief name "selectedStateImage", type string if it is a url, map otherwise
196 * @details Sets the selected button foreground image
199 SELECTED_STATE_IMAGE,
202 * @DEPRECATED_1_1.XX Use DISABLED_UNSELECTED_VISUAL
203 * @brief name "disabledStateImage", type string if it is a url, map otherwise
204 * @details Sets the disabled whilst unselected foreground button visual
207 DISABLED_STATE_IMAGE,
210 * @DEPRECATED_1_1.XX Use UNSELECTED_BACKGROUND_VISUAL
211 * @brief name "unselectedColor", type Vector4
217 * @DEPRECATED_1_1.XX Use SELECTED_BACKGROUND_VISUAL
218 * @brief name "selectedColor", type Vector4
224 * @brief name "label", type Property::Map
230 * @DEPRECATED_1_1.32 Use LABEL
231 * @brief name "labelText", type std::string
237 * @brief name "unselectedVisual", type string if it is a url, map otherwise
238 * @details Sets the unselected button foreground/icon visual
244 * @brief name "selectedImage", type string if it is a url, map otherwise
245 * @details Sets the selected button foreground/icon visual
251 * @brief name "disabledSelectedVisual", type string if it is a url, map otherwise
252 * @details Sets the disabled selected state foreground/icon button visual
255 DISABLED_SELECTED_VISUAL,
258 * @brief name "disabledUnSelectedVisual", type string if it is a url, map otherwise
259 * @details Sets the disabled unselected state foreground/icon visual
262 DISABLED_UNSELECTED_VISUAL,
265 * @brief name "unselectedBackgroundVisual", type string if it is a url, map otherwise
266 * @details Sets the disabled in the unselected state background, button visual
269 UNSELECTED_BACKGROUND_VISUAL,
272 * @brief name "selectedBackgroundVisual", type string if it is a url, map otherwise
273 * @details Sets the selected background button visual
276 SELECTED_BACKGROUND_VISUAL,
279 * @brief name "disabledUnselectedBackgroundVisual", type string if it is a url, map otherwise
280 * @details Sets the disabled while unselected background button visual
283 DISABLED_UNSELECTED_BACKGROUND_VISUAL,
286 * @brief name "disabledSelectedBackgroundVisual", type string if it is a url, map otherwise
287 * @details Sets the disabled while selected background button visual
290 DISABLED_SELECTED_BACKGROUND_VISUAL,
293 * @brief name "labelRelativeAlignment", type STRING
294 * @details Sets the position of the the label in relation to the foreground/icon if both present
297 LABEL_RELATIVE_ALIGNMENT,
304 * @brief Create an uninitialized Button.
306 * Only derived versions can be instantiated. Calling member
307 * functions with an uninitialized Dali::Object is not allowed.
313 * @brief Copy constructor.
315 * @param[in] button Handle to an object
317 Button( const Button& button );
320 * @brief Assignment operator.
322 * @param[in] button Handle to an object
323 * @return A reference to this
325 Button& operator=( const Button& button );
328 * @brief Downcast a handle to Button handle.
330 * If handle points to a Button the downcast produces valid
331 * handle. If not the returned handle is left uninitialized.
334 * @param[in] handle Handle to an object
335 * @return A handle to a Button or an uninitialized handle
337 static Button DownCast( BaseHandle handle );
342 * This is non-virtual since derived Handle types must not contain data or virtual methods.
350 * @DEPRECATED_1_1.32 Use SetProperty DISABLED or Styling file
352 * @brief Sets the button as \e disabled.
354 * No signals are emitted when the \e disabled property is set.
357 * @param[in] disabled property.
359 void SetDisabled( bool disabled ) DALI_DEPRECATED_API;
362 * @DEPRECATED_1_1.32 Use GetProperty DISABLED
364 * @brief Returns if the button is disabled.
366 * @return \e true if the button is \e disabled.
368 bool IsDisabled() const DALI_DEPRECATED_API;
371 * @DEPRECATED_1_1.32 SetProperty AUTO_REPEATING or Styling file
373 * @brief Sets the \e autorepeating property.
375 * If the \e autorepeating property is set to \e true, then the \e togglable property is set to false
376 * but no signal is emitted.
379 * @param[in] autoRepeating \e autorepeating property.
381 void SetAutoRepeating( bool autoRepeating ) DALI_DEPRECATED_API;
384 * @DEPRECATED_1_1.32 GetProperty AUTO_REPEATING
386 * @brief Returns if the autorepeating property is set.
388 * @return \e true if the \e autorepeating property is set.
390 bool IsAutoRepeating() const DALI_DEPRECATED_API;
393 * @DEPRECATED_1_1.32 SetProperty INITIAL_AUTO_REPEATING_DELAY or Styling file
395 * @brief Sets the initial autorepeating delay.
397 * By default this value is set to 0.15 seconds.
400 * @param[in] initialAutoRepeatingDelay in seconds.
401 * @pre initialAutoRepeatingDelay must be greater than zero.
403 void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay ) DALI_DEPRECATED_API;
406 * @DEPRECATED_1_1.32 GetProperty INITIAL_AUTO_REPEATING_DELAY
408 * @brief Gets the initial autorepeating delay in seconds.
410 * @return the initial autorepeating delay in seconds.
412 float GetInitialAutoRepeatingDelay() const DALI_DEPRECATED_API;
415 * @DEPRECATED_1_1.32 SetProperty NEXT_AUTO_REPEATING_DELAY or Styling file
417 * @brief Sets the next autorepeating delay.
419 * By default this value is set to 0.05 seconds.
422 * @param[in] nextAutoRepeatingDelay in seconds.
423 * @pre nextAutoRepeatingDelay must be greater than zero.
425 void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay ) DALI_DEPRECATED_API;
428 * @DEPRECATED_1_1.32 GetProperty NEXT_AUTO_REPEATING_DELAY
430 * @brief Gets the next autorepeating delay in seconds.
432 * @return the next autorepeating delay in seconds.
434 float GetNextAutoRepeatingDelay() const DALI_DEPRECATED_API;
437 * @DEPRECATED_1_1.32 SetProperty TOGGLABLE or Styling file
439 * @brief Sets the \e togglable property.
441 * If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
444 * @param[in] togglable property.
446 void SetTogglableButton( bool togglable ) DALI_DEPRECATED_API;
449 * @DEPRECATED_1_1.32 GetProperty TOGGLABLE
451 * @brief Returns if the togglable property is set.
453 * @return \e true if the \e togglable property is set.
455 bool IsTogglableButton() const DALI_DEPRECATED_API;
458 * @DEPRECATED_1_1.32 SetProperty SELECTED
460 * @brief Sets the button as selected or unselected.
462 * \e togglable property must be set to \e true.
464 * Emits a Button::StateChangedSignal() signal.
467 * @param[in] selected property.
469 void SetSelected( bool selected ) DALI_DEPRECATED_API;
472 * DEPRECATED_1_1.32 GetProperty SELECTED
474 * @brief Returns if the selected property is set and the button is togglable.
476 * @return \e true if the button is \e selected.
478 bool IsSelected() const DALI_DEPRECATED_API;
481 * @DEPRECATED_1_1.32 Use Styling file to set animation
483 * @brief Sets the animation time.
486 * @param[in] animationTime The animation time in seconds.
488 void SetAnimationTime( float animationTime ) DALI_DEPRECATED_API;
491 * DEPRECATED_1_1.32 Use Styling file to set animation
493 * @brief Retrieves button's animation time.
496 * @return The animation time in seconds.
498 float GetAnimationTime() const DALI_DEPRECATED_API;
501 * @DEPRECATED_1_1.32 SetProperty Property::LABEL or Styling file
503 * @brief Sets the button's label.
506 * @param[in] label The label text.
508 void SetLabelText( const std::string& label ) DALI_DEPRECATED_API;
511 * DEPRECATED_1_1.32 GetProperty LABEL
513 * @brief Gets the label.
516 * @return The label text.
518 std::string GetLabelText() const DALI_DEPRECATED_API;
521 * @DEPRECATED_1_1.32 Use Styling file Property::UNSELECTED_STATE_IMAGE
523 * @brief Sets the unselected button image.
526 * @param[in] filename The button image.
528 void SetUnselectedImage( const std::string& filename ) DALI_DEPRECATED_API;
531 * @DEPRECATED_1_1.32 Use styling
532 * Use Property::UNSELECTED_BACKGROUND_VISUAL
534 * @brief Sets the unselected background image.
537 * @param[in] filename The background image.
539 void SetBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
542 * @DEPRECATED_1_1.32 Use styling file, Property::SELECTED_STATE_IMAGE
544 * @brief Sets the selected image.
547 * @param[in] filename The selected image.
549 void SetSelectedImage( const std::string& filename ) DALI_DEPRECATED_API;
552 * @DEPRECATED_1_2.32 Use styling file
553 * Use Property::SELECTED_BACKGROUND_VISUAL
555 * @brief Sets the selected background image.
558 * @param[in] filename The selected background image.
560 void SetSelectedBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
563 * @DEPRECATED_1_1.32 Use styling file
564 * Use Property::DISABLED_SELECTED_BACKGROUND_VISUAL
566 * @brief Sets the disabled background image.
569 * @param[in] filename The disabled background image.
571 void SetDisabledBackgroundImage( const std::string& filename ) DALI_DEPRECATED_API;
574 * @DEPRECATED_1_1.32 Use styling file Property::DISABLED_STATE_IMAGE
576 * @brief Sets the disabled button image.
579 * @param[in] filename The disabled button image.
581 void SetDisabledImage( const std::string& filename ) DALI_DEPRECATED_API;
584 * @DEPRECATED_1_1.32 Use styling file
585 * Use Property::DISABLED_SELECTED_VISUAL
587 * @brief Sets the disabled selected button image.
590 * @param[in] filename The disabled selected button image.
592 void SetDisabledSelectedImage( const std::string& filename ) DALI_DEPRECATED_API;
595 * @DEPRECATED_1_0.50. Instead, use SetLabelText.
597 * @brief Sets the label with an actor.
600 * @param[in] label The actor to use as a label
602 void SetLabel( Actor label ) DALI_DEPRECATED_API;
605 * @DEPRECATED_1_0.50. Instead, use SetUnselectedImage.
607 * @brief Sets the button image.
610 * @param[in] image The button image.
612 void SetButtonImage( Image image ) DALI_DEPRECATED_API;
615 * @DEPRECATED_1_0.50. Instead, use SetSelectedImage( const std::string& filename ).
617 * @brief Sets the selected image.
620 * @param[in] image The selected image.
622 void SetSelectedImage( Image image ) DALI_DEPRECATED_API;
627 * @brief Gets the button image.
630 * @remarks Avoid using this method as it's a legacy code.
631 * @return An actor with the button image.
633 Actor GetButtonImage() const DALI_DEPRECATED_API;
638 * @brief Gets the selected image.
641 * @remarks Avoid using this method as it's a legacy code.
642 * @return An actor with the selected image.
644 Actor GetSelectedImage() const DALI_DEPRECATED_API;
649 * @brief Button signal type
652 typedef Signal< bool ( Button ) > ButtonSignalType;
655 * @brief This signal is emitted when the button is touched.
657 * A callback of the following type may be connected:
659 * bool YourCallbackName( Button button );
662 * @return The signal to connect to.
664 ButtonSignalType& PressedSignal();
667 * @brief This signal is emitted when the button is touched and the touch point leaves the boundary of the button.
669 * A callback of the following type may be connected:
671 * bool YourCallbackName( Button button );
674 * @return The signal to connect to.
676 ButtonSignalType& ReleasedSignal();
679 * @brief This signal is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
681 * A callback of the following type may be connected:
683 * bool YourCallbackName( Button button );
686 * @return The signal to connect to.
688 ButtonSignalType& ClickedSignal();
691 * @brief This signal is emitted when the button's state is changed.
693 * The application can get the state by calling IsSelected().
695 * A callback of the following type may be connected:
697 * bool YourCallbackName( Button button );
700 * @return The signal to connect to.
702 ButtonSignalType& StateChangedSignal();
704 public: // Not intended for application developers
708 * @brief Creates a handle using the Toolkit::Internal implementation.
711 * @param[in] implementation The Control implementation.
713 DALI_INTERNAL Button( Internal::Button& implementation );
716 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
719 * @param[in] internal A pointer to the internal CustomActor.
721 DALI_INTERNAL Button( Dali::Internal::CustomActor* internal );
728 } // namespace Toolkit
732 #endif // __DALI_TOOLKIT_BUTTON_H__