1 #ifndef __DALI_TOOLKIT_BUTTON_H__
2 #define __DALI_TOOLKIT_BUTTON_H__
5 * Copyright (c) 2014 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
36 * @brief Button is a base class for different kind of buttons.
38 * This class provides the disabled property and the clicked signal.
40 * A ClickedSignal() is emitted when the button is touched and the touch
41 * point doesn't leave the boundary of the button.
43 * When the \e disabled property is set to \e true, no signal is emitted.
46 * | %Signal Name | Method |
47 * |-------------------|-----------------------------|
48 * | pressed | @ref PressedSignal() |
49 * | released | @ref ReleasedSignal() |
50 * | clicked | @ref ClickedSignal() |
51 * | state-changed | @ref StateChangedSignal() |
54 * | %Action Name | %Button method called |
55 * |-------------------|-----------------------------|
56 * | button-click | %DoClickAction() |
58 class DALI_IMPORT_API Button : public Control
63 static const Property::Index PROPERTY_DISABLED; ///< name "disabled", @see SetDisabled(), type BOOLEAN
64 static const Property::Index PROPERTY_AUTO_REPEATING; ///< name "auto-repeating", @see SetAutoRepeating(), type BOOLEAN
65 static const Property::Index PROPERTY_INITIAL_AUTO_REPEATING_DELAY; ///< name "initial-auto-repeating-delay", @see SetInitialAutoRepeatingDelay(), type FLOAT
66 static const Property::Index PROPERTY_NEXT_AUTO_REPEATING_DELAY; ///< name "next-auto-repeating-delay", @see SetNextAutoRepeatingDelay(), type FLOAT
67 static const Property::Index PROPERTY_TOGGLABLE; ///< name "togglable", @see SetTogglableButton(), type BOOLEAN
68 static const Property::Index PROPERTY_SELECTED; ///< name "selected", @see SetSelected(), type BOOLEAN
69 static const Property::Index PROPERTY_NORMAL_STATE_ACTOR; ///< name "normal-state-actor", @see SetButtonImage(), type MAP
70 static const Property::Index PROPERTY_SELECTED_STATE_ACTOR; ///< name "selected-state-actor", @see SetSelectedImage(), type MAP
71 static const Property::Index PROPERTY_DISABLED_STATE_ACTOR; ///< name "disabled-state-actor", @see SetDisabledImage(), type MAP
72 static const Property::Index PROPERTY_LABEL_ACTOR; ///< name "label-actor", @see SetLabel(), type MAP
77 * @brief Create an uninitialized Button.
79 * Only derived versions can be instantiated. Calling member
80 * functions with an uninitialized Dali::Object is not allowed.
85 * @brief Copy constructor.
87 Button( const Button& button );
90 * @brief Assignment operator.
92 Button& operator=( const Button& button );
95 * @brief Downcast an Object handle to Button.
97 * If handle points to a Button the downcast produces valid
98 * handle. If not the returned handle is left uninitialized.
100 * @param[in] handle Handle to an object
101 * @return handle to a Button or an uninitialized handle
103 static Button DownCast( BaseHandle handle );
108 * This is non-virtual since derived Handle types must not contain data or virtual methods.
113 * @brief Sets the button as \e disabled.
115 * No signals are emitted when the \e disabled property is set.
117 * @param[in] disabled property.
119 void SetDisabled( bool disabled );
122 * @return \e true if the button is \e disabled.
124 bool IsDisabled() const;
127 * @brief Sets the \e autorepeating property.
129 * If the \e autorepeating property is set to \e true, then the \e togglable property is set to false
130 * but no signal is emitted.
132 * @param[in] autoRepeating \e autorepeating property.
134 void SetAutoRepeating( bool autoRepeating );
137 * @return \e true if the \e autorepeating property is set.
139 bool IsAutoRepeating() const;
142 * @brief Sets the initial autorepeating delay.
144 * By default this value is set to 0.15 seconds.
146 * @pre initialAutoRepeatingDelay must be greater than zero.
147 * @param[in] initialAutoRepeatingDelay in seconds.
149 void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
152 * @return the initial autorepeating delay in seconds.
154 float GetInitialAutoRepeatingDelay() const;
157 * @brief Sets the next autorepeating delay.
159 * By default this value is set to 0.05 seconds.
161 * @pre nextAutoRepeatingDelay must be greater than zero.
162 * @param[in] nextAutoRepeatingDelay in seconds.
164 void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
167 * @return the next autorepeating delay in seconds.
169 float GetNextAutoRepeatingDelay() const;
172 * @brief Sets the \e togglable property.
174 * If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
176 * @param[in] togglable property.
178 void SetTogglableButton( bool togglable );
181 * @return \e true if the \e togglable property is set.
183 bool IsTogglableButton() const;
186 * Sets the button as selected or unselected.
188 * \e togglable property must be set to \e true.
190 * Emits a Button::StateChangedSignal() signal.
192 * @param[in] selected property.
194 void SetSelected( bool selected );
197 * @return \e true if the \e selected property is set and the button is togglable.
199 bool IsSelected() const;
202 * @brief Sets the animation time.
204 * @param [in] animationTime The animation time in seconds.
206 void SetAnimationTime( float animationTime );
209 * @brief Retrieves button's animation time.
211 * @return The animation time in seconds.
213 float GetAnimationTime() const;
216 * @brief Sets the button label.
218 * @param[in] label The button label.
220 void SetLabel( const std::string& label );
223 * @copydoc SetLabel( const std::string& label )
225 void SetLabel( Actor label );
228 * @brief Gets the label.
230 * @return An actor with the label.
232 Actor GetLabel() const;
237 * @brief Button signal type
239 typedef Signal< bool ( Button ) > ButtonSignalType;
242 * @brief This signal is emitted when the button is touched.
244 * A callback of the following type may be connected:
246 * bool YourCallbackName( Button button );
248 * @return The signal to connect to.
250 ButtonSignalType& PressedSignal();
253 * @brief This signal is emitted when the button is touched and the touch point leaves the boundary of the button.
255 * A callback of the following type may be connected:
257 * bool YourCallbackName( Button button );
259 * @return The signal to connect to.
261 ButtonSignalType& ReleasedSignal();
264 * @brief This signal is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
266 * A callback of the following type may be connected:
268 * bool YourCallbackName( Button button );
270 * @return The signal to connect to.
272 ButtonSignalType& ClickedSignal();
275 * @brief This signal is emitted when the button's state is changed.
276 * The application can get the state by calling IsSelected().
278 * A callback of the following type may be connected:
280 * bool YourCallbackName( Button button );
282 * @return The signal to connect to.
284 ButtonSignalType& StateChangedSignal();
286 public: // Not intended for application developers
289 * @brief Creates a handle using the Toolkit::Internal implementation.
291 * @param[in] implementation The Control implementation.
293 DALI_INTERNAL Button( Internal::Button& implementation );
296 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
298 * @param[in] internal A pointer to the internal CustomActor.
300 DALI_INTERNAL Button( Dali::Internal::CustomActor* internal );
303 } // namespace Toolkit
307 #endif // __DALI_TOOLKIT_BUTTON_H__