[dali_2.0.2] Merge branch 'devel/master'
[platform/core/uifw/dali-toolkit.git] / dali-toolkit / public-api / controls / buttons / push-button.h
1 #ifndef DALI_TOOLKIT_PUSH_BUTTON_H
2 #define DALI_TOOLKIT_PUSH_BUTTON_H
3
4 /*
5  * Copyright (c) 2020 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 "button.h"
23
24 namespace Dali
25 {
26 namespace Toolkit
27 {
28 // Forward declarations
29
30 namespace Internal DALI_INTERNAL
31 {
32 // Forward declarations
33
34 class PushButton;
35 } // namespace DALI_INTERNAL
36 /**
37  * @addtogroup dali_toolkit_controls_buttons
38  * @{
39  */
40
41 /**
42  * @brief A PushButton changes its appearance when is pressed and returns to its original when is released.
43  *
44  * By default, a PushButton emits a Button::PressedSignal() signal when the button is pressed, a Button::ClickedSignal() signal when it's clicked.
45  * and a Button::ReleasedSignal() signal when it's released or having pressed it, the touch point leaves the boundary of the button.
46  *
47  * Usage example: -
48  *
49  * @code
50  * // in Creating a DALi Application
51  * void HelloWorldExample::Create( Application& application )
52  * {
53  *   PushButton button = PushButton::New();
54  *   button.SetProperty( Actor::Property::PARENT_ORIGIN, ParentOrigin::CENTER );
55  *   button.SetProperty( Button::Property::LABEL, "Press" );
56  *   Stage::GetCurrent().Add( button );
57  *
58  *   // Connect to button signals emitted by the button
59  *   button.ClickedSignal().Connect( this, &HelloWorldExample::OnButtonClicked );
60  *   button.PressedSignal().Connect( this, &HelloWorldExample::OnButtonPressed );
61  *   button.ReleasedSignal().Connect( this, &HelloWorldExample::OnButtonReleased );
62  * }
63  *
64  * bool HelloWorldExample::OnButtonClicked( Button button )
65  * {
66  *   // Do something when the button is clicked
67  *   return true;
68  * }
69  *
70  * bool HelloWorldExample::OnButtonPressed( Button button )
71  * {
72  *   // Do something when the button is pressed
73  *   return true;
74  * }
75  *
76  * bool HelloWorldExample::OnButtonReleased( Button button )
77  * {
78  *   // Do something when the button is released
79  *   return true;
80  * }
81  * @endcode
82  *
83  * See Button for more details on signals and modifying appearance via properties.
84  * @SINCE_1_0.0
85  */
86 class DALI_TOOLKIT_API PushButton : public Button
87 {
88 public:
89   /**
90    * @brief Enumeration for the start and end property ranges for this control.
91    * @SINCE_1_0.0
92    */
93   enum PropertyRange
94   {
95     PROPERTY_START_INDEX = Button::PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
96     PROPERTY_END_INDEX   = PROPERTY_START_INDEX + 1000     ///< Reserving 1000 property indices @SINCE_1_0.0
97   };
98
99   /**
100    * @brief Enumeration for the instance of properties belonging to the PushButton class.
101    * @SINCE_1_0.0
102    */
103   struct Property
104   {
105     /**
106      * @brief Enumeration for the instance of properties belonging to the PushButton class.
107      * @SINCE_1_0.0
108      */
109     enum
110     {
111       LABEL_PADDING = PROPERTY_START_INDEX, ///< Property, name "labelPadding",    type Vector4 @SINCE_1_0.0
112       ICON_PADDING,                         ///< Property, name "iconPadding",     type Vector4 @SINCE_1_0.0
113     };
114   };
115
116 public:
117   /**
118    * @brief Creates an uninitialized PushButton; this can be initialized with PushButton::New().
119    *
120    * Calling member functions with an uninitialized Dali::Object is not allowed.
121    * @SINCE_1_0.0
122    */
123   PushButton();
124
125   /**
126    * @brief Copy constructor.
127    * @SINCE_1_0.0
128    * @param[in] pushButton Handle to an object
129    */
130   PushButton(const PushButton& pushButton);
131
132   /**
133    * @brief Move constructor
134    * @SINCE_1_9.23
135    *
136    * @param[in] rhs A reference to the moved handle
137    */
138   PushButton(PushButton&& rhs);
139
140   /**
141    * @brief Assignment operator.
142    * @SINCE_1_0.0
143    * @param[in] pushButton Handle to an object
144    * @return A reference to this
145    */
146   PushButton& operator=(const PushButton& pushButton);
147
148   /**
149    * @brief Move assignment
150    * @SINCE_1_9.23
151    *
152    * @param[in] rhs A reference to the moved handle
153    * @return A reference to this
154    */
155   PushButton& operator=(PushButton&& rhs);
156
157   /**
158    * @brief Destructor.
159    *
160    * This is non-virtual since derived Handle types must not contain data or virtual methods.
161    * @SINCE_1_0.0
162    */
163   ~PushButton();
164
165   /**
166    * @brief Creates an initialized PushButton.
167    *
168    * @SINCE_1_0.0
169    * @return A handle to a newly allocated Dali resource
170    */
171   static PushButton New();
172
173   /**
174    * @brief Downcasts a handle to PushButton handle.
175    *
176    * If handle points to a PushButton, the downcast produces valid handle.
177    * If not, the returned handle is left uninitialized.
178    *
179    * @SINCE_1_0.0
180    * @param[in] handle Handle to an object
181    * @return handle to a PushButton or an uninitialized handle
182    */
183   static PushButton DownCast(BaseHandle handle);
184
185 public: // Not intended for application developers
186   /// @cond internal
187   /**
188    * @brief Creates a handle using the Toolkit::Internal implementation.
189    *
190    * @SINCE_1_0.0
191    * @param[in] implementation The Control implementation
192    */
193   DALI_INTERNAL PushButton(Internal::PushButton& implementation);
194
195   /**
196    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
197    *
198    * @SINCE_1_0.0
199    * @param[in] internal A pointer to the internal CustomActor
200    */
201   DALI_INTERNAL PushButton(Dali::Internal::CustomActor* internal);
202   /// @endcond
203 };
204
205 /**
206  * @}
207  */
208 } // namespace Toolkit
209
210 } // namespace Dali
211
212 #endif // DALI_TOOLKIT_PUSH_BUTTON_H