inc/FUiCtrlDatePicker.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                 FUiCtrlDatePicker.h
  20 * @brief                This is the header file for the %DatePicker class.
  21 *
  22 * This header file contains the declarations of the %DatePicker class.
  23 */
  24 #ifndef _FUI_CTRL_DATE_PICKER_H_
  25 #define _FUI_CTRL_DATE_PICKER_H_
  26
  27 #include <FUiWindow.h>
  28 #include <FUiIDateChangeEventListener.h>
  29
  30 namespace Tizen { namespace Ui { namespace Controls
  31 {
  32
  33 /**
  34 * @class        DatePicker
  35 * @brief        This class displays a full screen %DatePicker on top of the screen.
  36 *
  37 * @since                2.0
  38 *
  39 * @remarks   One cannot change the size and the position of the %DatePicker.
  40 *
  41 * The %DatePicker class displays a full screen window-based selector that allows the user to select a certain date.
  42 *
  43 * For more information on the class features,
  44 * see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_datepicker.htm">DatePicker, TimePicker, and DateTimePicker</a>.
  45 *
  46 * The following example demonstrates how to use the %DatePicker class.
  47 *
  48 * @code
  49 // Sample code for DatePickerSample.h
  50 #include <FUi.h>
  51
  52 class DatePickerSample
  53         : public Tizen::Ui::Controls::Form
  54         , public Tizen::Ui::IDateChangeEventListener
  55         , public Tizen::Ui::IActionEventListener
  56 {
  57 public:
  58         DatePickerSample(void)
  59         :__pDatePicker(null){}
  60
  61         bool Initialize(void);
  62         virtual result OnInitializing(void);
  63         virtual result OnTerminating(void);
  64         void ShowDatePicker(bool show);
  65
  66         // IActionEventListener
  67         virtual void OnActionPerformed(const Tizen::Ui::Control& source, int actionId);
  68
  69         // IDateChangeEventListener
  70         virtual void OnDateChanged(const Tizen::Ui::Control& source, int year, int month, int day);
  71         virtual void OnDateChangeCanceled(const Tizen::Ui::Control& source);
  72
  73 private:
  74         static const int ID_BUTTON  = 101;
  75
  76         Tizen::Ui::Controls::DatePicker* __pDatePicker;
  77 };
  78
  79  *      @endcode
  80  *
  81  *      @code
  82 // Sample code for DatePickerSample.cpp
  83 #include "DatePickerSample.h"
  84 #include <FGraphics.h>
  85
  86 using namespace Tizen::Graphics;
  87 using namespace Tizen::Ui::Controls;
  88
  89 bool
  90 DatePickerSample::Initialize(void)
  91 {
  92         Construct(FORM_STYLE_NORMAL);
  93         return true;
  94 }
  95
  96 result
  97 DatePickerSample::OnInitializing(void)
  98 {
  99         result r = E_SUCCESS;
 100
 101         // Creates an instance of Button
 102         Button* pButton = new Button();
 103         pButton->Construct(Rectangle(50, 50, 300, 200), L"Show DatePicker");
 104         pButton->SetActionId(ID_BUTTON);
 105         pButton->AddActionEventListener(*this);
 106
 107         // Adds the button to the form
 108         AddControl(pButton);
 109
 110         // Creates an instance of DatePicker
 111         __pDatePicker = new DatePicker();
 112         __pDatePicker->Construct();
 113
 114         // Adds an instance of IDateChangeEventListener
 115         __pDatePicker->AddDateChangeEventListener(*this);
 116
 117         // Shows the date picker after it's owner form is shown.
 118
 119         return r;
 120 }
 121
 122 void
 123 DatePickerSample::ShowDatePicker(bool show)
 124 {
 125         // Changes to desired show state
 126         __pDatePicker->SetShowState(show);
 127
 128         // Calls Show() of the control
 129         if (show)
 130         {
 131                 __pDatePicker->Show();
 132         }
 133         // Calls Show() of the container
 134         else
 135         {
 136                 Invalidate(true);
 137         }
 138 }
 139
 140 result
 141 DatePickerSample::OnTerminating(void)
 142 {
 143         result r = E_SUCCESS;
 144
 145         // Deallocates the date picker
 146         __pDatePicker->Destroy();
 147
 148         return r;
 149 }
 150
 151 // IActionEventListener implementation
 152 void
 153 DatePickerSample::OnActionPerformed(const Control& source, int actionId)
 154 {
 155         switch (actionId)
 156         {
 157         case ID_BUTTON:
 158                 {
 159                         ShowDatePicker(true);
 160                 }
 161                 break;
 162         default:
 163                 break;
 164         }
 165 }
 166
 167 // IDateChangeEventListener implementation
 168 void
 169 DatePickerSample::OnDateChanged(const Control& source, int year, int month, int day)
 170 {
 171         // ....
 172 }
 173
 174 void
 175 DatePickerSample::OnDateChangeCanceled(const Control& source)
 176 {
 177         // ....
 178 }
 179 * @endcode
 180 **/
 181 class _OSP_EXPORT_ DatePicker
 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 DatePicker::Construct() method must be called right after calling this constructor.
 188         *
 189         * @since                2.0
 190         */
 191         DatePicker(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 ~DatePicker(void);
 200
 201         /**
 202         * Adds a data change event listener instance. @n
 203         * The added listener is called when the date of the %DatePicker is changed either through user manipulation or by calling one of its setters.
 204         *
 205         * @since                2.0
 206         *
 207         * @param[in]    listener        The listener to add
 208         * @see                  IDateChangeEventListener::OnDateChanged()
 209         * @see                  IDateChangeEventListener::OnDateChangeCanceled()
 210         * @see                  RemoveDateChangeEventListener()
 211         */
 212         void AddDateChangeEventListener(Tizen::Ui::IDateChangeEventListener& listener);
 213
 214         /**
 215         * Removes a date changed event listener instance. @n
 216         * The removed listener cannot listen to events when they are fired.
 217         *
 218         * @since                2.0
 219         *
 220         * @param[in]    listener        The listener to remove
 221         * @see                  IDateChangeEventListener::OnDateChanged()
 222         * @see                  IDateChangeEventListener::OnDateChangeCanceled()
 223         * @see                  AddDateChangeEventListener()
 224         */
 225         void RemoveDateChangeEventListener(Tizen::Ui::IDateChangeEventListener& listener);
 226
 227         /**
 228         * Initializes this instance of %DatePicker with the specified parameter.
 229         *
 230         * @since                        2.0
 231         *
 232         * @return               An error code
 233         * @param[in]    title               The title
 234         * @exception    E_SUCCESS           The method is successful.
 235         * @exception    E_SYSTEM                    A system error has occurred.
 236         * @remarks              The optimal size of the control is defined in
 237         * <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 238         */
 239         result Construct(const Tizen::Base::String& title = L"");
 240
 241         /**
 242         * Gets the current date value of the %DatePicker control.
 243         *
 244         * @since        2.0
 245         *
 246         * @return   A %DateTime instance
 247         */
 248         Tizen::Base::DateTime GetDate(void) const;
 249
 250         /**
 251         * Gets the current day value of the %DatePicker control. @n
 252         * The day value is between @c 1 to @c 31.
 253         *
 254         * @since        2.0
 255         *
 256         * @return       The current day value, @n
 257         *           else @c -1 if an error occurs
 258         */
 259         int GetDay(void) const;
 260
 261         /**
 262         * Gets the current month value of the %DatePicker control. @n
 263         * The month value is between @c 1 to @c 12.
 264         *
 265         * @since        2.0
 266         *
 267         * @return       The current month value, @n
 268         *           else @c -1 if an error occurs
 269         */
 270         int GetMonth(void) const;
 271
 272         /**
 273         * Gets the current year value of the %DatePicker control.
 274         * The year value is between @c 1 to @c 9999.
 275         *
 276         * @since        2.0
 277         *
 278         * @return       The current year value, @n
 279         *           else @c -1 if an error occurs
 280         *
 281         */
 282         int GetYear(void) const;
 283
 284         /**
 285         * Sets the date value of the %DatePicker control.
 286         *
 287         * @since                2.0
 288         *
 289         * @param[in]    date    The date to set
 290         */
 291         void SetDate(const Tizen::Base::DateTime& date);
 292
 293         /**
 294         * Sets the date value of the %DatePicker control with the current date.
 295         *
 296         * @since                2.0
 297         */
 298         void SetCurrentDate(void);
 299
 300         /**
 301         * Sets the year value. @n
 302         * The year value should be between @c 1 and @c 9999.
 303         *
 304         * @since                        2.0
 305         *
 306         * @return                       An error code
 307         * @param[in]    year    The year value
 308         * @exception    E_SUCCESS       The method is successful.
 309         * @exception    E_INVALID_ARG   The specified year value is invalid.
 310         */
 311         result SetYear(int year);
 312
 313         /**
 314         * Sets the month value. @n
 315         * The month value should be between @c 1 and @c 12.
 316         *
 317         * @since                2.0
 318         *
 319         * @return               An error code
 320         * @param[in]    month           The month value
 321         * @exception    E_SUCCESS       The method is successful.
 322         * @exception    E_INVALID_ARG   The specified month value is invalid.
 323         */
 324         result SetMonth(int month);
 325
 326         /**
 327         * Sets the day value. @n
 328         * The day value should be between @c 1 and @c 31.
 329         *
 330         * @since                2.0
 331         *
 332         * @return               An error code
 333         * @param[in]    day                 The day value
 334         * @exception    E_SUCCESS       The method is successful.
 335         * @exception    E_INVALID_ARG   The specified @c day is invalid.
 336         */
 337         result SetDay(int day);
 338
 339         /**
 340         * Sets the valid year range.
 341         * The range should be set in between @c 1 and @c 9999.
 342         *
 343         * @since                         2.0
 344         *
 345         * @return                              An error code
 346         * @param[in]   minYear                The minimum year for the valid range
 347         * @param[in]   maxYear                The maximum year for the valid range
 348         * @exception    E_SUCCESS                       The method is successful.
 349         * @exception   E_INVALID_ARG          The given year range is invalid.
 350         * @exception    E_SYSTEM                        A system error has occurred.
 351         */
 352         result SetYearRange(int minYear, int maxYear);
 353
 354         /**
 355         * Gets the valid year range.
 356         *
 357         * @since                         2.0
 358         *
 359         * @return                             An error code
 360         * @param[out]  minYear                The minimum year for the valid range
 361         * @param[out]  maxYear                The maximum year for the valid range
 362         * @exception    E_SUCCESS                       The method is successful.
 363         * @exception    E_SYSTEM                        A system error has occurred.
 364         */
 365         result GetYearRange(int& minYear, int& maxYear) const;
 366
 367 protected:
 368         friend class _DatePickerImpl;
 369
 370 private:
 371         //
 372         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 373         //
 374         DatePicker(const DatePicker& rhs);
 375
 376         //
 377         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 378         //
 379         DatePicker& operator =(const DatePicker& rhs);
 380
 381 }; // DatePicker
 382
 383 }}} // Tizen::Ui::Controls
 384
 385 #endif      // _FUI_CTRL_DATE_PICKER_H_