Merge branch 'devel/master' 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) 2015 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  * @addtogroup dali_toolkit_controls_buttons
36  * @{
37  */
38
39 /**
40  * @brief Button is a base class for different kind of buttons.
41  *
42  * This class provides the disabled property and the clicked signal.
43  *
44  * A ClickedSignal() is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
45  *
46  * When the \e disabled property is set to \e true, no signal is emitted.
47  *
48  * Button provides the following properties which modify the signals emitted:
49  * <ul>
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.
54  *
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.
57  *
58  *   <li>\e togglable
59  *       When \e togglable is set to \e true, a Button::StateChangedSignal() signal is emitted, with the selected state.
60  * </ul>
61  *
62  * The button's appearance can be modified by setting properties for the various image filenames.
63  *
64  * The \e background is always shown and doesn't change if the button is pressed or released. The \e button image is shown over the \e background image when the
65  * button is not pressed and is replaced by the \e selected image when the button is pressed. The text label is placed always on the top of all images.
66  *
67  * When the button is disabled, \e background, \e button and \e selected images are replaced by their \e disabled images.
68  *
69  * Is not mandatory set all images. A button could be defined only by setting its \e background image or by setting its \e background and \e selected images.
70  *
71  * Signals
72  * | %Signal Name     | Method                      |
73  * |------------------|-----------------------------|
74  * | pressed          | @ref PressedSignal()        |
75  * | released         | @ref ReleasedSignal()       |
76  * | clicked          | @ref ClickedSignal()        |
77  * | stateChanged     | @ref StateChangedSignal()   |
78  *
79  * Actions
80  * | %Action Name     | %Button method called       |
81  * |------------------|-----------------------------|
82  * | buttonClick      | %DoClickAction()            |
83  * @SINCE_1_0.0
84  */
85 class DALI_IMPORT_API Button : public Control
86 {
87 public:
88
89   /**
90    * @brief The start and end property ranges for this control.
91    * @SINCE_1_0.0
92    */
93   enum PropertyRange
94   {
95     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
96     PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000              ///< Reserve property indices @SINCE_1_0.0
97   };
98
99   /**
100    * @brief An enumeration of properties belonging to the Button class.
101    * @SINCE_1_0.0
102    */
103   struct Property
104   {
105     enum
106     {
107       DISABLED = PROPERTY_START_INDEX, ///< name "disabled",                     @see SetDisabled(),                  type bool @SINCE_1_0.0
108       AUTO_REPEATING,                  ///< name "autoRepeating",                @see SetAutoRepeating(),             type bool @SINCE_1_0.0
109       INITIAL_AUTO_REPEATING_DELAY,    ///< name "initialAutoRepeatingDelay",    @see SetInitialAutoRepeatingDelay(), type float @SINCE_1_0.0
110       NEXT_AUTO_REPEATING_DELAY,       ///< name "nextAutoRepeatingDelay",       @see SetNextAutoRepeatingDelay(),    type float @SINCE_1_0.0
111       TOGGLABLE,                       ///< name "togglable",                    @see SetTogglableButton(),           type bool @SINCE_1_0.0
112       SELECTED,                        ///< name "selected",                     @see SetSelected(),                  type bool @SINCE_1_0.0
113       UNSELECTED_STATE_IMAGE,          ///< name "unselectedStateImage",         @see SetUnselectedImage(),           type std::string @SINCE_1_0.0
114       SELECTED_STATE_IMAGE,            ///< name "selectedStateImage",           @see SetSelectedImage(),             type std::string @SINCE_1_0.0
115       DISABLED_STATE_IMAGE,            ///< name "disabledStateImage",           @see SetDisabledImage(),             type std::string @SINCE_1_0.0
116       UNSELECTED_COLOR,                ///< name "unselectedColor",                                                   type Vector4 @SINCE_1_0.0
117       SELECTED_COLOR,                  ///< name "selectedColor",                                                     type Vector4 @SINCE_1_0.0
118       LABEL,                           ///< name "label",                                                             type Property::Map @SINCE_1_0.0
119
120       // Deprecated properties:
121       LABEL_TEXT,                      ///< name "labelText",                    @see SetLabelText(),                 type std::string @SINCE_1_0.0
122     };
123   };
124
125 public:
126
127   /**
128    * @brief Create an uninitialized Button.
129    *
130    * Only derived versions can be instantiated.  Calling member
131    * functions with an uninitialized Dali::Object is not allowed.
132    * @SINCE_1_0.0
133    */
134   Button();
135
136   /**
137    * @brief Copy constructor.
138    * @SINCE_1_0.0
139    */
140   Button( const Button& button );
141
142   /**
143    * @brief Assignment operator.
144    * @SINCE_1_0.0
145    */
146   Button& operator=( const Button& button );
147
148   /**
149    * @brief Downcast a handle to Button handle.
150    *
151    * If handle points to a Button the downcast produces valid
152    * handle. If not the returned handle is left uninitialized.
153    *
154    * @SINCE_1_0.0
155    * @param[in] handle Handle to an object
156    * @return A handle to a Button or an uninitialized handle
157    */
158   static Button DownCast( BaseHandle handle );
159
160   /**
161    * @brief Destructor
162    *
163    * This is non-virtual since derived Handle types must not contain data or virtual methods.
164    * @SINCE_1_0.0
165    */
166   ~Button();
167
168   /**
169    * @brief Sets the button as \e disabled.
170    *
171    * No signals are emitted when the \e disabled property is set.
172    *
173    * @SINCE_1_0.0
174    * @param[in] disabled property.
175    */
176   void SetDisabled( bool disabled );
177
178   /**
179    * @brief Returns if the button is disabled.
180    * @SINCE_1_0.0
181    * @return \e true if the button is \e disabled.
182    */
183   bool IsDisabled() const;
184
185   /**
186    * @brief Sets the \e autorepeating property.
187    *
188    * If the \e autorepeating property is set to \e true, then the \e togglable property is set to false
189    * but no signal is emitted.
190    *
191    * @SINCE_1_0.0
192    * @param[in] autoRepeating \e autorepeating property.
193    */
194   void SetAutoRepeating( bool autoRepeating );
195
196   /**
197    * @brief Returns if the autorepeating property is set.
198    * @SINCE_1_0.0
199    * @return \e true if the \e autorepeating property is set.
200    */
201   bool IsAutoRepeating() const;
202
203   /**
204    * @brief Sets the initial autorepeating delay.
205    *
206    * By default this value is set to 0.15 seconds.
207    *
208    * @SINCE_1_0.0
209    * @param[in] initialAutoRepeatingDelay in seconds.
210    * @pre initialAutoRepeatingDelay must be greater than zero.
211    */
212   void SetInitialAutoRepeatingDelay( float initialAutoRepeatingDelay );
213
214   /**
215    * @brief Gets the initial autorepeating delay in seconds.
216    * @SINCE_1_0.0
217    * @return the initial autorepeating delay in seconds.
218    */
219   float GetInitialAutoRepeatingDelay() const;
220
221   /**
222    * @brief Sets the next autorepeating delay.
223    *
224    * By default this value is set to 0.05 seconds.
225    *
226    * @SINCE_1_0.0
227    * @param[in] nextAutoRepeatingDelay in seconds.
228    * @pre nextAutoRepeatingDelay must be greater than zero.
229    */
230   void SetNextAutoRepeatingDelay( float nextAutoRepeatingDelay );
231
232   /**
233    * @brief Gets the next autorepeating delay in seconds.
234    * @SINCE_1_0.0
235    * @return the next autorepeating delay in seconds.
236    */
237   float GetNextAutoRepeatingDelay() const;
238
239   /**
240    * @brief Sets the \e togglable property.
241    *
242    * If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
243    *
244    * @SINCE_1_0.0
245    * @param[in] togglable property.
246    */
247   void SetTogglableButton( bool togglable );
248
249   /**
250    * @brief Returns if the togglable property is set.
251    * @SINCE_1_0.0
252    * @return \e true if the \e togglable property is set.
253    */
254   bool IsTogglableButton() const;
255
256   /**
257    * @brief Sets the button as selected or unselected.
258    *
259    * \e togglable property must be set to \e true.
260    *
261    * Emits a Button::StateChangedSignal() signal.
262    *
263    * @SINCE_1_0.0
264    * @param[in] selected property.
265    */
266   void SetSelected( bool selected );
267
268   /**
269    * @brief Returns if the selected property is set and the button is togglable.
270    * @SINCE_1_0.0
271    * @return \e true if the button is \e selected.
272    */
273   bool IsSelected() const;
274
275   /**
276    * @brief Sets the animation time.
277    *
278    * @SINCE_1_0.0
279    * @param[in] animationTime The animation time in seconds.
280    */
281   void SetAnimationTime( float animationTime );
282
283   /**
284    * @brief Retrieves button's animation time.
285    *
286    * @SINCE_1_0.0
287    * @return The animation time in seconds.
288    */
289   float GetAnimationTime() const;
290
291   /**
292    * @brief Sets the button's label.
293    *
294    * @SINCE_1_0.0
295    * @param[in] label The label text.
296    */
297   void SetLabelText( const std::string& label );
298
299   /**
300    * @brief Gets the label.
301    *
302    * @SINCE_1_0.0
303    * @return The label text.
304    */
305   std::string GetLabelText() const;
306
307   /**
308    * @brief Sets the unselected button image.
309    *
310    * @SINCE_1_0.0
311    * @param[in] filename The button image.
312    */
313   void SetUnselectedImage( const std::string& filename );
314
315   /**
316    * @brief Sets the background image.
317    *
318    * @SINCE_1_0.0
319    * @param[in] filename The background image.
320    */
321   void SetBackgroundImage( const std::string& filename );
322
323   /**
324    * @brief Sets the selected image.
325    *
326    * @SINCE_1_0.0
327    * @param[in] filename The selected image.
328    */
329   void SetSelectedImage( const std::string& filename );
330
331   /**
332    * @brief Sets the selected background image.
333    *
334    * @SINCE_1_0.0
335    * @param[in] filename The selected background image.
336    */
337   void SetSelectedBackgroundImage( const std::string& filename );
338
339   /**
340    * @brief Sets the disabled background image.
341    *
342    * @SINCE_1_0.0
343    * @param[in] filename The disabled background image.
344    */
345   void SetDisabledBackgroundImage( const std::string& filename );
346
347   /**
348    * @brief Sets the disabled button image.
349    *
350    * @SINCE_1_0.0
351    * @param[in] filename The disabled button image.
352    */
353   void SetDisabledImage( const std::string& filename );
354
355   /**
356    * @brief Sets the disabled selected button image.
357    *
358    * @SINCE_1_0.0
359    * @param[in] filename The disabled selected button image.
360    */
361   void SetDisabledSelectedImage( const std::string& filename );
362
363   // Deprecated API
364
365   /**
366    * @DEPRECATED_1_0.50. Instead, use SetLabelText.
367    *
368    * @brief Sets the label with an actor.
369    *
370    * @SINCE_1_0.0
371    * @param[in]  label The actor to use as a label
372    */
373   void SetLabel( Actor label );
374
375   /**
376    * @DEPRECATED_1_0.50. Instead, use SetUnselectedImage.
377    *
378    * @brief Sets the button image.
379    *
380    * @SINCE_1_0.0
381    * @param[in]  image The button image.
382    */
383   void SetButtonImage( Image image );
384
385   /**
386    * @DEPRECATED_1_0.50. Instead, use SetSelectedImage( const std::string& filename ).
387    *
388    * @brief Sets the selected image.
389    *
390    * @SINCE_1_0.0
391    * @param[in]  image The selected image.
392    */
393   void SetSelectedImage( Image image );
394
395   /**
396    * @DEPRECATED_1_0.50
397    *
398    * @brief Gets the button image.
399    *
400    * @SINCE_1_0.0
401    * @remarks Avoid using this method as it's a legacy code.
402    * @return     An actor with the button image.
403    */
404   Actor GetButtonImage() const;
405
406   /**
407    * @DEPRECATED_1_0.50
408    *
409    * @brief Gets the selected image.
410    *
411    * @SINCE_1_0.0
412    * @remarks Avoid using this method as it's a legacy code.
413    * @return     An actor with the selected image.
414    */
415   Actor GetSelectedImage() const;
416
417 public: //Signals
418
419   /**
420    * @brief Button signal type
421    * @SINCE_1_0.0
422    */
423   typedef Signal< bool ( Button ) > ButtonSignalType;
424
425   /**
426    * @brief This signal is emitted when the button is touched.
427    *
428    * A callback of the following type may be connected:
429    * @code
430    *   bool YourCallbackName( Button button );
431    * @endcode
432    * @SINCE_1_0.0
433    * @return The signal to connect to.
434    */
435   ButtonSignalType& PressedSignal();
436
437   /**
438    * @brief This signal is emitted when the button is touched and the touch point leaves the boundary of the button.
439    *
440    * A callback of the following type may be connected:
441    * @code
442    *   bool YourCallbackName( Button button );
443    * @endcode
444    * @SINCE_1_0.0
445    * @return The signal to connect to.
446    */
447   ButtonSignalType& ReleasedSignal();
448
449   /**
450    * @brief This signal is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
451    *
452    * A callback of the following type may be connected:
453    * @code
454    *   bool YourCallbackName( Button button );
455    * @endcode
456    * @SINCE_1_0.0
457    * @return The signal to connect to.
458    */
459   ButtonSignalType& ClickedSignal();
460
461   /**
462    * @brief This signal is emitted when the button's state is changed.
463    *
464    * The application can get the state by calling IsSelected().
465    *
466    * A callback of the following type may be connected:
467    * @code
468    *   bool YourCallbackName( Button button );
469    * @endcode
470    * @SINCE_1_0.0
471    * @return The signal to connect to.
472    */
473   ButtonSignalType& StateChangedSignal();
474
475 public: // Not intended for application developers
476
477   /**
478    * @brief Creates a handle using the Toolkit::Internal implementation.
479    *
480    * @SINCE_1_0.0
481    * @param[in]  implementation  The Control implementation.
482    */
483   DALI_INTERNAL Button( Internal::Button& implementation );
484
485   /**
486    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
487    *
488    * @SINCE_1_0.0
489    * @param[in]  internal  A pointer to the internal CustomActor.
490    */
491   DALI_INTERNAL Button( Dali::Internal::CustomActor* internal );
492 };
493
494 /**
495  * @}
496  */
497 } // namespace Toolkit
498
499 } // namespace Dali
500
501 #endif // __DALI_TOOLKIT_BUTTON_H__