[dali_1.4.32] Merge branch 'devel/master'
[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) 2019 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 kinds 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  * '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.
63  *
64  * The button's appearance can be modified by setting properties for the various visuals/images.
65  *
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.
67  *
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.
70  *
71  * When the button is disabled, \e background, \e button and \e selected visuals are replaced by their \e disabled visuals.
72  *
73  *
74  * Signals
75  * | %Signal Name     | Method                      |
76  * |------------------|-----------------------------|
77  * | pressed          | @ref PressedSignal()        |
78  * | released         | @ref ReleasedSignal()       |
79  * | clicked          | @ref ClickedSignal()        |
80  * | stateChanged     | @ref StateChangedSignal()   |
81  *
82  * Actions
83  * | %Action Name     | Attributes              | Description                                   |
84  * |------------------|-------------------------|-----------------------------------------------|
85  * | buttonClick      | Doesn't have attributes | Simulates a button click. See @ref DoAction() |
86  * @SINCE_1_0.0
87  */
88 class DALI_TOOLKIT_API Button : public Control
89 {
90 public:
91
92   /**
93    * @brief Enumeration for the start and end property ranges for this control.
94    * @SINCE_1_0.0
95    */
96   enum PropertyRange
97   {
98     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
99     PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000              ///< Reserve property indices @SINCE_1_0.0
100   };
101
102   /**
103    * @brief Enumeration for the instance of properties belonging to the Button class.
104    * @SINCE_1_0.0
105    */
106   struct Property
107   {
108     /**
109      * @brief Enumeration for the instance of properties belonging to the Button class.
110      * @SINCE_1_0.0
111      */
112     enum
113     {
114       /**
115        * @brief name "disabled", type bool
116        * @details Sets the button as \e disabled.
117        * @SINCE_1_0.0
118        */
119       DISABLED = PROPERTY_START_INDEX,
120
121       /**
122        * @brief name "autoRepeating", type bool
123        * @details If the \e autorepeating property is set to \e true then the \e togglable property is set to false
124        * @SINCE_1_0.0
125        */
126       AUTO_REPEATING,
127
128       /**
129        * @brief name "initialAutoRepeatingDelay", type float
130        * @details By default this value is set to 0.15 seconds.
131        * @SINCE_1_0.0
132        */
133       INITIAL_AUTO_REPEATING_DELAY,
134
135       /**
136        * @brief name "nextAutoRepeatingDelay", type float
137        * @details default this value is set to 0.05 seconds
138        * @SINCE_1_0.0
139        */
140       NEXT_AUTO_REPEATING_DELAY,
141
142       /**
143        * @brief name "togglable", type bool
144        * @details If the \e togglable property is set to \e true, then the \e autorepeating property is set to false.
145        * @SINCE_1_0.0
146        */
147       TOGGLABLE,
148
149       /**
150        * @brief name "selected", type bool
151        * @details Sets the togglable button as either selected or unselected, \e togglable property must be set to \e true.
152        * @SINCE_1_0.0
153        */
154       SELECTED,
155
156       /**
157        * @brief name "unselectedVisual", type string if it is a url, map otherwise.
158        * @details Sets the unselected button foreground/icon visual
159        * @SINCE_1_4.32
160        */
161       UNSELECTED_VISUAL,
162
163       /**
164        * @brief name "selectedImage", type string if it is a url, map otherwise
165        * @details Sets the selected button foreground/icon visual
166        * @SINCE_1_4.32
167        */
168       SELECTED_VISUAL,
169
170       /**
171        * @brief name "disabledSelectedVisual", type string if it is a url, map otherwise
172        * @details Sets the disabled selected state foreground/icon button visual
173        * @SINCE_1_4.32
174        */
175       DISABLED_SELECTED_VISUAL,
176
177       /**
178        * @brief name "disabledUnselectedVisual", type string if it is a url, map otherwise
179        * @details Sets the disabled unselected state foreground/icon visual
180        * @SINCE_1_4.32
181        */
182       DISABLED_UNSELECTED_VISUAL,
183
184       /**
185        * @brief name "unselectedBackgroundVisual", type string if it is a url, map otherwise
186        * @details Sets the disabled in the unselected state background, button visual
187        * @SINCE_1_4.32
188        */
189       UNSELECTED_BACKGROUND_VISUAL,
190
191       /**
192        * @brief name "label", type Property::Map or std::string
193        * @SINCE_1_0.0
194        */
195       LABEL,
196
197       /**
198        * @brief name "selectedBackgroundVisual", type string if it is a url, map otherwise
199        * @details Sets the selected background button visual
200        * @SINCE_1_4.32
201        */
202       SELECTED_BACKGROUND_VISUAL,
203
204       /**
205        * @brief name "disabledUnselectedBackgroundVisual", type string if it is a url, map otherwise
206        * @details Sets the disabled while unselected background button visual
207        * @SINCE_1_4.32
208        */
209       DISABLED_UNSELECTED_BACKGROUND_VISUAL,
210
211       /**
212        * @brief name "disabledSelectedBackgroundVisual", type string if it is a url, map otherwise
213        * @details Sets the disabled while selected background button visual
214        * @SINCE_1_4.32
215        */
216       DISABLED_SELECTED_BACKGROUND_VISUAL,
217     };
218   };
219
220 public:
221
222   /**
223    * @brief Creates an uninitialized Button.
224    *
225    * Only derived versions can be instantiated.  Calling member
226    * functions with an uninitialized Dali::Object is not allowed.
227    * @SINCE_1_0.0
228    */
229   Button();
230
231   /**
232    * @brief Copy constructor.
233    * @SINCE_1_0.0
234    * @param[in] button Handle to an object
235    */
236   Button( const Button& button );
237
238   /**
239    * @brief Assignment operator.
240    * @SINCE_1_0.0
241    * @param[in] button Handle to an object
242    * @return A reference to this
243    */
244   Button& operator=( const Button& button );
245
246   /**
247    * @brief Downcasts a handle to Button handle.
248    *
249    * If handle points to a Button, the downcast produces valid handle.
250    * If not the returned handle is left uninitialized.
251    *
252    * @SINCE_1_0.0
253    * @param[in] handle Handle to an object
254    * @return A handle to a Button or an uninitialized handle
255    */
256   static Button DownCast( BaseHandle handle );
257
258   /**
259    * @brief Destructor.
260    *
261    * This is non-virtual since derived Handle types must not contain data or virtual methods.
262    * @SINCE_1_0.0
263    */
264   ~Button();
265
266 public: //Signals
267
268   /**
269    * @brief Button signal type.
270    * @SINCE_1_0.0
271    */
272   typedef Signal< bool ( Button ) > ButtonSignalType;
273
274   /**
275    * @brief This signal is emitted when the button is touched.
276    *
277    * A callback of the following type may be connected:
278    * @code
279    *   bool YourCallbackName( Button button );
280    * @endcode
281    * @SINCE_1_0.0
282    * @return The signal to connect to
283    */
284   ButtonSignalType& PressedSignal();
285
286   /**
287    * @brief This signal is emitted when the button is touched and the touch point leaves the boundary of the button.
288    *
289    * A callback of the following type may be connected:
290    * @code
291    *   bool YourCallbackName( Button button );
292    * @endcode
293    * @SINCE_1_0.0
294    * @return The signal to connect to
295    */
296   ButtonSignalType& ReleasedSignal();
297
298   /**
299    * @brief This signal is emitted when the button is touched and the touch point doesn't leave the boundary of the button.
300    *
301    * A callback of the following type may be connected:
302    * @code
303    *   bool YourCallbackName( Button button );
304    * @endcode
305    * @SINCE_1_0.0
306    * @return The signal to connect to
307    */
308   ButtonSignalType& ClickedSignal();
309
310   /**
311    * @brief This signal is emitted when the button's state is changed.
312    *
313    * The application can get the state by calling IsSelected().
314    *
315    * A callback of the following type may be connected:
316    * @code
317    *   bool YourCallbackName( Button button );
318    * @endcode
319    * @SINCE_1_0.0
320    * @return The signal to connect to
321    */
322   ButtonSignalType& StateChangedSignal();
323
324 public: // Not intended for application developers
325
326   /// @cond internal
327   /**
328    * @brief Creates a handle using the Toolkit::Internal implementation.
329    *
330    * @SINCE_1_0.0
331    * @param[in] implementation The Control implementation
332    */
333   DALI_INTERNAL Button( Internal::Button& implementation );
334
335   /**
336    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
337    *
338    * @SINCE_1_0.0
339    * @param[in] internal A pointer to the internal CustomActor
340    */
341   DALI_INTERNAL Button( Dali::Internal::CustomActor* internal );
342   /// @endcond
343 };
344
345 /**
346  * @}
347  */
348 } // namespace Toolkit
349
350 } // namespace Dali
351
352 #endif // DALI_TOOLKIT_BUTTON_H