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