Included changes from magnolia/doc/sdk-internal
[framework/osp/uifw.git] / inc / FUiCtrlEditTime.h
1 //
2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
4 //
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
8 //
9 //     http://www.apache.org/licenses/LICENSE-2.0/
10 //
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an ”AS IS” BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
16 //
17
18 /**
19 * @file                 FUiCtrlEditTime.h
20 * @brief                This is the header file for the %EditTime class.
21 *
22 * This header file contains the declarations of the %EditTime class.
23 */
24 #ifndef _FUI_CTRL_EDIT_TIME_H_
25 #define _FUI_CTRL_EDIT_TIME_H_
26
27 #include <FUiControl.h>
28 #include <FUiITimeChangeEventListener.h>
29 #include <FUiIOrientationEventListener.h>
30
31 namespace Tizen { namespace Ui { namespace Controls
32 {
33
34 /**
35 * @class        EditTime
36 * @brief    This class defines the common behavior of an %EditTime control.
37 *
38 * @since        2.0
39 *
40 * The %EditTime class displays a small, fixed-size selector that allows the user to select a time.
41 * Unlike TimePicker, %EditTime can be placed in a container.
42 *
43 * For more information on the class features, see 
44 * <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_edittime_editdate.htm">EditDate and EditTime</a>.
45 *
46 * The following example demonstrates how to use the %EditTime class.
47 *
48 * @code
49 // Sample code for EditTimeSample.h
50 #include <FUi.h>
51
52 class EditTimeSample
53         : public Tizen::Ui::Controls::Form
54         , public Tizen::Ui::ITimeChangeEventListener
55 {
56 public:
57         EditTimeSample(void)
58         : __pEditTime(null){}
59
60         bool Initialize(void);
61         virtual result OnInitializing(void);
62
63         // ITimeChangeEventListener
64         virtual void OnTimeChanged(const Tizen::Ui::Control& source, int hour, int minute);
65         virtual void OnTimeChangeCanceled(const Tizen::Ui::Control& source);
66
67 private:
68         Tizen::Ui::Controls::EditTime* __pEditTime;
69 };
70  *      @endcode
71  *
72  *      @code
73 // Sample code for EditTimeSample.cpp
74 #include <FGraphics.h>
75
76 #include "EditTimeSample.h"
77
78 using namespace Tizen::Graphics;
79 using namespace Tizen::Ui::Controls;
80
81 bool
82 EditTimeSample::Initialize(void)
83 {
84         Construct(FORM_STYLE_NORMAL);
85         return true;
86 }
87
88 result
89 EditTimeSample::OnInitializing(void)
90 {
91         result r = E_SUCCESS;
92
93         // Creates an instance of EditTime
94         __pEditTime = new EditTime();
95         __pEditTime->Construct(Point(100, 100));
96         __pEditTime->AddTimeChangeEventListener(*this);
97
98         //Adds the edit time to the form
99         AddControl(*__pEditTime);
100
101         return r;
102 }
103
104 // ITimeChangeEventListener implementation
105 void
106 EditTimeSample::OnTimeChanged(const Control& source, int hour, int minute)
107 {
108         // ....
109 }
110
111 void
112 EditTimeSample::OnTimeChangeCanceled(const Control& source)
113 {
114         // ....
115 }
116 * @endcode
117 **/
118 class _OSP_EXPORT_ EditTime
119         : public Tizen::Ui::Control
120 {
121 public:
122         /**
123          * The object is not fully constructed after this constructor is called. @n
124          * For full construction, the %Construct() method must be called right after calling this constructor.
125          *
126          * @since               2.0
127          */
128         EditTime(void);
129
130         /**
131          * This polymorphic destructor should be overridden if required.@n
132          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
133          *
134          * @since               2.0
135          */
136         virtual ~EditTime(void);
137
138         /**
139          * Adds a time changed event listener instance.
140          *
141          * @since                       2.0
142          *
143          * @param[in]   listener    The listener to add
144          * @see                         ITimeChangeEventListener::OnTimeChanged()
145          * @see                         ITimeChangeEventListener::OnTimeChangeCanceled()
146          * @see                         RemoveTimeChangeEventListener()
147          */
148         void AddTimeChangeEventListener(Tizen::Ui::ITimeChangeEventListener& listener);
149
150         /**
151          * Removes a listener instance. @n
152          * The removed listener cannot listen to events when they are fired.
153          *
154          * @since                       2.0
155          *
156          * @param[in]   listener    The listener to remove
157          * @see                         AddTimeChangeEventListener()
158          */
159         void RemoveTimeChangeEventListener(Tizen::Ui::ITimeChangeEventListener& listener);
160
161         /**
162          * Initializes this instance of %EditTime with the specified parameters.
163          *
164          * @since                       2.0
165          *
166          * @return              An error code
167          * @param[in]   point                           The position of %EditTime in container
168          * @param[in]   title                           The title
169          * @exception   E_SUCCESS           The method is successful.
170          * @exception   E_SYSTEM                        A system error has occurred.
171          */
172         result Construct(const Tizen::Graphics::Point& point, const Tizen::Base::String& title = L"");
173
174         /**
175          * Initializes this instance of %EditTime with the specified parameters.
176          *
177          * @since                       2.1
178          *
179          * @return              An error code
180          * @param[in]   point                           The position of %EditTime in container
181          * @param[in]   title                           The title
182          * @exception   E_SUCCESS           The method is successful.
183          * @exception   E_SYSTEM                        A system error has occurred.
184          */
185         result Construct(const Tizen::Graphics::FloatPoint& point, const Tizen::Base::String& title = L"");
186
187         /**
188          * Gets the current hour value of the %EditTime control.
189          *
190          * @since               2.0
191          *
192          * @return      The current hour value. @n
193          *                      The hour value is between @c 0 to @c 23.
194          *
195          * @remarks     The default hour value is the current system hour.
196          */
197         int GetHour(void) const;
198
199         /**
200          * Gets the current minute value of the %EditTime control.
201          *
202          * @since       2.0
203          *
204          * @return      The current minute value
205          *
206          * @remarks     The default minute value is the current system minute.
207          */
208         int GetMinute(void) const;
209
210         /**
211          * Gets the current time value of the %EditTime control.
212          *
213          * @since                       2.0
214          *
215          * @return              The time value
216          */
217         Tizen::Base::DateTime GetTime(void) const;
218
219         /**
220          * Sets the 12-hour or 24-hour display type of the %EditTime. @n
221          * This can be 12-hour or 24-hour type.
222          *
223          * @since                       2.0
224          *
225          * @param[in]   enable  Set to @c true to set the 24-hour notation, @n
226          *                                              else @c false to set the 12-hour notation
227          */
228         void Set24HourNotationEnabled(bool enable);
229
230         /**
231          * Sets the hour value of the %EditTime control. @n
232          * The hour value should be between @c 0 and @c 23.
233          *
234          * @since                       2.0
235          *
236          * @param[in]   hour                    The hour value to set
237          * @exception   E_SUCCESS       The method is successful.
238          * @exception   E_INVALID_ARG   The specified hour value is invalid.
239          * @exception   E_SYSTEM        A system error has occurred.
240          *
241          */
242         result SetHour(int hour);
243
244         /**
245          * Sets the minute value of the %EditTime control. @n
246          * The minute value should be between @c 0 and @c 59.
247          *
248          * @since                       2.0
249          *
250          * @param[in]   minute                  The minute value to set
251          * @exception   E_SUCCESS       The method is successful.
252          * @exception   E_INVALID_ARG   The specified minute value is invalid.
253          * @exception   E_SYSTEM        A system error has occurred.
254          *
255          */
256         result SetMinute(int minute);
257
258         /**
259          * Sets the designated time value of the %EditTime control.
260          *
261          * @since                       2.0
262          *
263          * @param[in]   time    The time to set
264          */
265         void SetTime(const Tizen::Base::DateTime& time);
266
267         /**
268          * Sets the value of the %EditTime control using the current system time.
269          *
270          * @since               2.0
271          */
272         void SetCurrentTime(void);
273
274         /**
275          * Enables TimePicker.
276          *
277          * @since                               2.0
278          *
279          * @param[in]   enable          Set to @c true to enable %TimePicker, @n
280          *                                                      else @c false
281          */
282         void SetTimePickerEnabled(bool enable);
283
284         /**
285          * Checks whether TimePicker is enabled.
286          *
287          * @since               2.0
288          *
289          * @return      @c true if TimePicker is enabled, @n
290          *                      else @c false
291          */
292         bool IsTimePickerEnabled(void) const;
293
294 private:
295         //
296         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
297         //
298         EditTime(const EditTime& rhs);
299
300         //
301         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
302         //
303         EditTime& operator =(const EditTime& rhs);
304
305         friend class _EditTimeImpl;
306 }; // EditTime
307
308 }}} //Tizen::Ui::Controls
309
310 #endif      // _FUI_CTRL_EDIT_TIME_H_