inc/FUiCtrlDateTimePicker.h

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