Merge "Button Refactoring phase 1" into tizen
[platform/core/uifw/dali-toolkit.git] / 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) 2014 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
27 namespace Toolkit
28 {
29
30 namespace Internal DALI_INTERNAL
31 {
32 class Button;
33 }
34
35 /**
36  * @brief Button is a base class for different kind of buttons.
37  *
38  * This class provides the disabled property and the clicked signal.
39  *
40  * A ClickedSignal() is emitted when the button is touched and the touch
41  * point doesn't leave the boundary of the button.
42  *
43  * When the \e disabled property is set to \e true, no signal is emitted.
44  */
45 class DALI_IMPORT_API Button : public Control
46 {
47 public:
48
49   // Signal Names
50   static const char* const SIGNAL_PRESSED;       ///< name "pressed"
51   static const char* const SIGNAL_RELEASED;      ///< name "released"
52   static const char* const SIGNAL_CLICKED;       ///< name "clicked"
53   static const char* const SIGNAL_STATE_CHANGED; ///< name "state-changed"
54
55   //Action Names
56   static const char* const ACTION_BUTTON_CLICK; ///< name "button-click"
57
58   // Properties
59   static const Property::Index PROPERTY_DISABLED;                     ///< name "disabled",                     @see SetDisabled(),                  type BOOLEAN
60   static const Property::Index PROPERTY_AUTO_REPEATING;               ///< name "auto-repeating",               @see SetAutoRepeating(),             type BOOLEAN
61   static const Property::Index PROPERTY_INITIAL_AUTO_REPEATING_DELAY; ///< name "initial-auto-repeating-delay", @see SetInitialAutoRepeatingDelay(), type FLOAT
62   static const Property::Index PROPERTY_NEXT_AUTO_REPEATING_DELAY;    ///< name "next-auto-repeating-delay",    @see SetNextAutoRepeatingDelay(),    type FLOAT
63   static const Property::Index PROPERTY_TOGGLABLE;                    ///< name "togglable",                    @see SetTogglableButton(),           type BOOLEAN
64   static const Property::Index PROPERTY_SELECTED;                     ///< name "selected",                     @see SetSelected(),                  type BOOLEAN
65   static const Property::Index PROPERTY_NORMAL_STATE_ACTOR;           ///< name "normal-state-actor",           @see SetButtonImage(),               type MAP
66   static const Property::Index PROPERTY_SELECTED_STATE_ACTOR;         ///< name "selected-state-actor",         @see SetSelectedImage(),             type MAP
67   static const Property::Index PROPERTY_DISABLED_STATE_ACTOR;         ///< name "disabled-state-actor",         @see SetDisabledImage(),             type MAP
68   static const Property::Index PROPERTY_LABEL_ACTOR;                  ///< name "label-actor",                  @see SetLabel(),                     type MAP
69
70 public:
71
72   /**
73    * @brief Create an uninitialized Button.
74    *
75    * Only derived versions can be instantiated.  Calling member
76    * functions with an uninitialized Dali::Object is not allowed.
77    */
78   Button();
79
80   /**
81    * @brief Copy constructor.
82    */
83   Button( const Button& button );
84
85   /**
86    * @brief Assignment operator.
87    */
88   Button& operator=( const Button& button );
89
90   /**
91    * @brief Downcast an Object handle to Button.
92    *
93    * If handle points to a Button the downcast produces valid
94    * handle. If not the returned handle is left uninitialized.
95    *
96    * @param[in] handle Handle to an object
97    * @return handle to a Button or an uninitialized handle
98    */
99   static Button DownCast( BaseHandle handle );
100
101   /**
102    * @brief Destructor
103    *
104    * This is non-virtual since derived Handle types must not contain data or virtual methods.
105    */
106   ~Button();
107
108   /**
109    * @brief Sets the button as \e disabled.
110    *
111    * No signals are emitted when the \e disabled property is set.
112    *
113    * @param[in] disabled property.
114    */
115   void SetDisabled( bool disabled );
116
117   /**
118    * @return \e true if the button is \e disabled.
119    */
120   bool IsDisabled() const;
121
122   /**
123    * @brief Sets the \e autorepeating property.
124    *
125    * If the \e autorepeating property is set to \e true, then the \e togglable property is set to false
126    * but no signal is emitted.
127    *
128    * @param[in] autoRepeating \e autorepeating property.
129    */
130   void SetAutoRepeating( bool autoRepeating );
131
132   /**
133    * @return \e true if the \e autorepeating property is set.
134    */
135   bool IsAutoRepeating() const;
136
137   /**
138    * @brief Sets the initial autorepeating delay.
139    *
140    * By default this value is set to 0.15 seconds.
141    *
142    * @pre initialAutoRepeatingDelay must be greater than zero.
143    * @param[in] initialAutoRepeatingDelay in seconds.
144    */
145   void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
146
147   /**
148    * @return the initial autorepeating delay in seconds.
149    */
150   float GetInitialAutoRepeatingDelay() const;
151
152   /**
153    * @brief Sets the next autorepeating delay.
154    *
155    * By default this value is set to 0.05 seconds.
156    *
157    * @pre nextAutoRepeatingDelay must be greater than zero.
158    * @param[in] nextAutoRepeatingDelay in seconds.
159    */
160   void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
161
162   /**
163    * @return the next autorepeating delay in seconds.
164    */
165   float GetNextAutoRepeatingDelay() const;
166
167   /**
168    * @brief Sets the \e togglable property.
169    *
170    * If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
171    *
172    * @param[in] togglable property.
173    */
174   void SetTogglableButton( bool togglable );
175
176   /**
177    * @return \e true if the \e togglable property is set.
178    */
179   bool IsTogglableButton() const;
180
181   /**
182    * Sets the button as selected or unselected.
183    *
184    * \e togglable property must be set to \e true.
185    *
186    * Emits a Button::StateChangedSignal() signal.
187    *
188    * @param[in] selected property.
189    */
190   void SetSelected( bool selected );
191
192   /**
193    * @return \e true if the \e selected property is set and the button is togglable.
194    */
195   bool IsSelected() const;
196
197   /**
198    * @brief Sets the animation time.
199    *
200    * @param [in] animationTime The animation time in seconds.
201    */
202   void SetAnimationTime( float animationTime );
203
204   /**
205    * @brief Retrieves button's animation time.
206    *
207    * @return The animation time in seconds.
208    */
209   float GetAnimationTime() const;
210
211   /**
212    * @brief Sets the button label.
213    *
214    * @param[in] label The button label.
215    */
216   void SetLabel( const std::string& label );
217
218   /**
219    * @copydoc SetLabel( const std::string& label )
220    */
221   void SetLabel( Actor label );
222
223   /**
224    * @brief Gets the label.
225    *
226    * @return An actor with the label.
227    */
228   Actor GetLabel() const;
229
230 public: //Signals
231
232   /**
233    * @brief Button signal type
234    */
235   typedef Signal< bool ( Button ) > ButtonSignalType;
236
237   /**
238    * @brief This signal is emitted when the button is touched.
239    *
240    * A callback of the following type may be connected:
241    * @code
242    *   bool YourCallbackName( Button button );
243    * @endcode
244    * @return The signal to connect to.
245    */
246   ButtonSignalType& PressedSignal();
247
248   /**
249    * @brief This signal is emitted when the button is touched and the touch point leaves the boundary of the button.
250    *
251    * A callback of the following type may be connected:
252    * @code
253    *   bool YourCallbackName( Button button );
254    * @endcode
255    * @return The signal to connect to.
256    */
257   ButtonSignalType& ReleasedSignal();
258
259   /**
260    * @brief This signal is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
261    *
262    * A callback of the following type may be connected:
263    * @code
264    *   bool YourCallbackName( Button button );
265    * @endcode
266    * @return The signal to connect to.
267    */
268   ButtonSignalType& ClickedSignal();
269
270   /**
271    * @brief This signal is emitted when the button's state is changed.
272    * The application can get the state by calling IsSelected().
273    *
274    * A callback of the following type may be connected:
275    * @code
276    *   bool YourCallbackName( Button button );
277    * @endcode
278    * @return The signal to connect to.
279    */
280   ButtonSignalType& StateChangedSignal();
281
282 public: // Not intended for application developers
283
284   /**
285    * @brief Creates a handle using the Toolkit::Internal implementation.
286    *
287    * @param[in]  implementation  The Control implementation.
288    */
289   DALI_INTERNAL Button( Internal::Button& implementation );
290
291   /**
292    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
293    *
294    * @param[in]  internal  A pointer to the internal CustomActor.
295    */
296   DALI_INTERNAL Button( Dali::Internal::CustomActor* internal );
297 };
298
299 } // namespace Toolkit
300
301 } // namespace Dali
302
303 #endif // __DALI_TOOLKIT_BUTTON_H__