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