inc/FUiCtrlDateTimePicker.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                 FUiCtrlDateTimePicker.h
  20 * @brief        This is the header file for the %DateTimePicker class.
  21 *
  22 * This header file contains the declarations of the %DateTimePicker class.
  23 */
  24 #ifndef _FUI_CTRL_DATE_TIME_PICKER_H_
  25 #define _FUI_CTRL_DATE_TIME_PICKER_H_
  26
  27 #include <FUiWindow.h>
  28 #include <FUiIDateTimeChangeEventListener.h>
  29
  30 namespace Tizen { namespace Ui { namespace Controls
  31 {
  32
  33 /**
  34 * @class        DateTimePicker
  35 * @brief        This class displays a full screen %DateTimePicker on top of the screen.
  36 *
  37 * @since                2.0
  38 *
  39 * The %DateTimePicker class displays a full screen window-based selector that allows the user to select a certain date and time.
  40 *
  41 * For more information on the class features,
  42 * see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_datepicker.htm">DatePicker, TimePicker, and DateTimePicker</a>.
  43 *
  44 * The following example demonstrates how to use the %DateTimePicker class.
  45 *
  46 * @code
  47 // Sample code for DateTimePickerSample.h
  48 #include <FUi.h>
  49
  50 class DateTimePickerSample
  51         : public Tizen::Ui::Controls::Form
  52         , public Tizen::Ui::IDateTimeChangeEventListener
  53         , public Tizen::Ui::IActionEventListener
  54 {
  55 public:
  56         DateTimePickerSample(void)
  57         :__pDateTimePicker(null){}
  58
  59         bool Initialize(void);
  60         void ShowDateTimePicker(bool show);
  61         virtual result OnInitializing(void);
  62         virtual result OnTerminating(void);
  63
  64         // IActionEventListener
  65         virtual void OnActionPerformed(const Tizen::Ui::Control& source, int actionId);
  66
  67         // IDateTimeChangeEventListener
  68         virtual void OnDateTimeChanged(const Tizen::Ui::Control& source, int year, int month, int day, int hour, int minute);
  69         virtual void OnDateTimeChangeCanceled(const Tizen::Ui::Control& source);
  70
  71 private:
  72         static const int ID_BUTTON  = 101;
  73
  74         Tizen::Ui::Controls::DateTimePicker* __pDateTimePicker;
  75 };
  76
  77  *      @endcode
  78  *
  79  *      @code
  80 // Sample code for DateTimePickerSample.cpp
  81 #include <FGraphics.h>
  82
  83 #include "DateTimePickerSample.h"
  84
  85 using namespace Tizen::Graphics;
  86 using namespace Tizen::Ui::Controls;
  87
  88 bool
  89 DateTimePickerSample::Initialize(void)
  90 {
  91         Construct(FORM_STYLE_NORMAL);
  92         return true;
  93 }
  94
  95 result
  96 DateTimePickerSample::OnInitializing(void)
  97 {
  98         result r = E_SUCCESS;
  99
 100         // Creates an instance of Button
 101         Button* pButton = new Button();
 102         pButton->Construct(Rectangle(50, 50, 300, 200), L"Show DateTimePicker");
 103         pButton->SetActionId(ID_BUTTON);
 104         pButton->AddActionEventListener(*this);
 105
 106         // Adds the button to the form
 107         AddControl(pButton);
 108
 109         // Creates an instance of DateTimePicker
 110         __pDateTimePicker = new DateTimePicker();
 111         __pDateTimePicker->Construct();
 112
 113         // Adds an instance of IDateTimeChangeEventListener
 114         __pDateTimePicker->AddDateTimeChangeEventListener(*this);
 115
 116         // Shows the date time picker after it's owner form is shown.
 117
 118         return r;
 119 }
 120
 121 void
 122 DateTimePickerSample::ShowDateTimePicker(bool show)
 123 {
 124         // Changes to desired show state
 125         __pDateTimePicker->SetShowState(show);
 126
 127         // Calls Show() of the control
 128         if (show)
 129         {
 130                 __pDateTimePicker->Show();
 131         }
 132         // Calls Show() of the container
 133         else
 134         {
 135                 Invalidate(true);
 136         }
 137 }
 138
 139 result
 140 DateTimePickerSample::OnTerminating(void)
 141 {
 142         result r = E_SUCCESS;
 143
 144         // Deallocates the date time picker
 145         __pDateTimePicker->Destroy();
 146
 147         return r;
 148 }
 149
 150 // IActionEventListener implementation
 151 void
 152 DateTimePickerSample::OnActionPerformed(const Control& source, int actionId)
 153 {
 154         switch (actionId)
 155         {
 156         case ID_BUTTON:
 157                 {
 158                         ShowDateTimePicker(true);
 159                 }
 160                 break;
 161         default:
 162                 break;
 163         }
 164 }
 165
 166 // IDateTimeChangeEventListener implementation
 167 void
 168 DateTimePickerSample::OnDateTimeChanged(const Control& source, int year, int month, int day, int hour, int minute)
 169 {
 170         // ....
 171 }
 172
 173 void
 174 DateTimePickerSample::OnDateTimeChangeCanceled(const Control& source)
 175 {
 176         // ....
 177 }
 178 * @endcode
 179 **/
 180
 181 class _OSP_EXPORT_ DateTimePicker
 182         : public Tizen::Ui::Window
 183 {
 184 public:
 185         /**
 186          * The object is not fully constructed after this constructor is called. @n
 187          * For full construction, the DateTimePicker::Construct() method must be called right after calling this constructor.
 188          *
 189          * @since               2.0
 190          */
 191         DateTimePicker(void);
 192
 193         /**
 194          * This polymorphic destructor should be overridden if required.  @n
 195          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
 196          *
 197          * @since               2.0
 198          */
 199         virtual ~DateTimePicker(void);
 200
 201         /**
 202          * Adds the IDateTimeChangeEventListener instance. @n
 203          * The added listener gets notified when date or time of the %DateTimePicker instance is changed either by user manipulation or by calling one of its
 204          * setters.
 205          *
 206          * @since               2.0
 207          *
 208          * @param[in]   listener        The listener to add
 209          * @see                 IDateTimeChangeEventListener::OnDateTimeChanged()
 210          * @see                 IDateTimeChangeEventListener::OnDateTimeChangeCanceled()
 211          * @see                 RemoveDateTimeChangeEventListener()
 212          */
 213         void AddDateTimeChangeEventListener(Tizen::Ui::IDateTimeChangeEventListener& listener);
 214
 215         /**
 216          * Removes the IDateTimeChangeEventListener instance. @n
 217          * The removed listener is not called even when the date and time change events are fired.
 218          *
 219          * @since               2.0
 220          *
 221          * @param[in]   listener        The listener to remove
 222          * @see                 IDateTimeChangeEventListener::OnDateTimeChanged()
 223          * @see                 IDateTimeChangeEventListener::OnDateTimeChangeCanceled()
 224          * @see                 AddDateTimeChangeEventListener()
 225          */
 226         void RemoveDateTimeChangeEventListener(Tizen::Ui::IDateTimeChangeEventListener& listener);
 227
 228         /**
 229          * Initializes this instance of %DateTimePicker to the current date and time in the wall time mode.
 230          *
 231          * @since                       2.0
 232          *
 233          * @return          An error code
 234          * @param[in]   title                           The title
 235          * @exception   E_SUCCESS                       The method is successful.
 236          * @exception   E_SYSTEM                        A system error has occurred.
 237          * @remarks             The optimal size of the control is defined in
 238          * <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 239          */
 240         result Construct(const Tizen::Base::String& title = L"");
 241
 242         /**
 243          *  Sets the date and time value of the %DateTimePicker control.
 244          *
 245          * @since               2.0
 246          *
 247          * @param[in]   dateTime        The date and time to set
 248          */
 249         void SetDateTime(const Tizen::Base::DateTime& dateTime);
 250
 251         /**
 252          * Sets the date and time value of the %DateTimePicker control with the current date and time in the Coordinated Universal Time (UTC) mode.
 253          *
 254          * @since               2.0
 255          */
 256         void SetCurrentDateTime(void);
 257
 258         /**
 259          * Sets the year value of the %DateTimePicker control.
 260          *
 261          * @since               2.0
 262          *
 263          * @return              An error code
 264          * @param[in]   year                    The year value @n
 265          *                                              It should be in the range set by SetYearRange(). The default year range is from @c 1 to @c 9999.
 266          * @exception   E_SUCCESS       The method is successful.
 267          * @exception   E_INVALID_ARG   The specified @c year value is invalid.
 268          * @exception   E_SYSTEM                A system error has occurred.
 269          * @exception   E_OUT_OF_RANGE  The value of the argument is outside the valid range defined by SetYearRange().
 270          * @see                 SetYearRange()
 271          */
 272         result SetYear(int year);
 273
 274         /**
 275          * Sets the month value.
 276          *
 277          * @since               2.0
 278          *
 279          * @return              An error code
 280          * @param[in]   month   The month value between @c 1 and @c 12.
 281          * @exception   E_SUCCESS       The method is successful.
 282          * @exception   E_INVALID_ARG   The specified @c month value is invalid.
 283          * @exception   E_SYSTEM                A system error has occurred.
 284          */
 285         result SetMonth(int month);
 286
 287         /**
 288          * Sets the day value.
 289          *
 290          * @since               2.0
 291          *
 292          * @return              An error code
 293          * @param[in]   day      The day value between @c 1 and @c 31.
 294          * @exception   E_SUCCESS       The method is successful.
 295          * @exception   E_INVALID_ARG   The specified @c day value is invalid.
 296          * @exception   E_SYSTEM                A system error has occurred.
 297          */
 298         result SetDay(int day);
 299
 300         /**
 301          * Sets the hour value of the %DateTimePicker control.
 302          *
 303          * @since               2.0
 304          *
 305          * @return              An error code
 306          * @param[in]   hour                    The hour value between @c 0 and @c 23.
 307          * @exception   E_SUCCESS       The method is successful.
 308          * @exception   E_INVALID_ARG   The specified @c hour value is invalid.
 309          * @exception   E_SYSTEM        A system error has occurred.
 310          */
 311         result SetHour(int hour);
 312
 313         /**
 314          * Sets the minute value of the %DateTimePicker control.
 315          *
 316          * @since               2.0
 317          *
 318          * @return              An error code
 319          * @param[in]   minute              The minute value between @c 0 and @c 59.
 320          * @exception   E_SUCCESS       The method is successful.
 321          * @exception   E_INVALID_ARG   The specified @c minute value is invalid.
 322          * @exception   E_SYSTEM        A system error has occurred.
 323          */
 324         result SetMinute(int minute);
 325
 326         /**
 327          * Gets the current date and time value of the %DateTimePicker control.
 328          *
 329          * @since                2.0
 330          *
 331          * @return   The current date and time
 332          */
 333         Tizen::Base::DateTime GetDateTime(void) const;
 334
 335         /**
 336          * Gets the current year value of %DateTimePicker. @n
 337          *
 338          * @since               2.0
 339          *
 340          * @return      The current year value between @c 1 to @c 9999, @n
 341          *                      else @c -1 if an error occurs
 342          */
 343         int GetYear(void) const;
 344
 345         /**
 346          * Gets the current month value of %DateTimePicker. @n
 347          *
 348          * @since               2.0
 349          *
 350          * @return          The current month value between @c 1 to @c 12, @n
 351          *                          else @c -1 if an error occurs
 352          */
 353         int GetMonth(void) const;
 354
 355         /**
 356          * Gets the current day value of %DateTimePicker. @n
 357          *
 358          * @since               2.0
 359          *
 360          * @return          The current day value between @c 1 to @c 31, @n
 361          *                          else @c -1 if an error occurs
 362          */
 363         int GetDay(void) const;
 364
 365         /**
 366          * Gets the current hour value of the %DateTimePicker control. @n
 367          *
 368          * @since               2.0
 369          *
 370          * @return          The current hour value between @c 0 to @c 23, @n
 371          *                          else @c -1 if an error occurs
 372          * @remarks         Whether the time display mode is 12-hour or 24-hour, this method always returns the hour value ranging from @c 0 to @c 23.
 373          */
 374         int GetHour(void) const;
 375
 376         /**
 377          * Gets the current minute value of the %DateTimePicker control.
 378          *
 379          * @since               2.0
 380          *
 381          * @return          The current minute value, @n
 382          *                          else @c -1 if an error occurs
 383          */
 384         int GetMinute(void) const;
 385
 386         /**
 387          * Sets the 12-hour or 24-hour display mode of the %DateTimePicker control.
 388          *
 389          * @since               2.0
 390          */
 391         void Set24HourNotationEnabled(bool enable);
 392
 393         /**
 394          * Checks whether the 24-hour notation is enabled for the %DateTimePicker control. @n
 395          * This can be 12-hour or 24-hour mode.
 396          *
 397          * @since               2.0
 398          *
 399          * @return      @c true if the 24-hour notation is enabled, @n
 400          *                      else @c false if the 12-hour notation is enabled
 401          */
 402         bool Is24HourNotationEnabled(void) const;
 403
 404         /**
 405          * Sets the valid year range. @n
 406          *
 407          * @since               2.0
 408          *
 409          * @return              An error code
 410          * @param[in]   minYear                The minimum year for the valid range between @c 1 and @c 9999
 411          * @param[in]   maxYear                The maximum year for the valid range
 412          * @exception   E_SUCCESS                       The method is successful.
 413          * @exception   E_INVALID_ARG          The specified year range is invalid.
 414          * @exception   E_SYSTEM                        A system error has occurred.
 415          */
 416         result SetYearRange(int minYear, int maxYear);
 417
 418         /**
 419          * Gets the valid year range.
 420          *
 421          * @since               2.0
 422          *
 423          * @return              An error code
 424          * @param[out]  minYear                The minimum year for the valid range
 425          * @param[out]  maxYear                The maximum year for the valid range
 426          * @exception   E_SUCCESS               The method is successful.
 427          * @exception   E_SYSTEM                A system error has occurred.
 428          */
 429         result GetYearRange(int& minYear, int& maxYear) const;
 430
 431 protected:
 432         friend class _DateTimePickerImpl;
 433
 434 private:
 435         //
 436         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 437         //
 438         DateTimePicker(const DateTimePicker& rhs);
 439
 440         //
 441         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 442         //
 443         DateTimePicker& operator =(const DateTimePicker& rhs);
 444
 445 }; // DateTimePicker
 446
 447 }}} // Tizen::Ui::Controls
 448
 449 #endif      // _FUI_CTRL_DATE_TIME_PICKER_H_