inc/FUiCtrlEditDate.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                        FUiCtrlEditDate.h
  20  * @brief       This is the header file for the %EditDate class.
  21  *
  22  * This header file contains the declarations of the %EditDate class.
  23  */
  24 #ifndef _FUI_CTRL_EDITDATE_H_
  25 #define _FUI_CTRL_EDITDATE_H_
  26
  27 #include <FUiControl.h>
  28 #include <FUiIDateChangeEventListener.h>
  29 #include <FUiIOrientationEventListener.h>
  30
  31 namespace Tizen { namespace Ui { namespace  Controls
  32 {
  33
  34 /**
  35  * @class       EditDate
  36  * @brief    This class defines the common behavior of an %EditDate control.
  37  *
  38  * @since               2.0
  39  *
  40  * The %EditDate class displays a small, fixed-size selector that allows the user to select a date. Unlike the DatePicker, %EditDate can be placed in a container.
  41  *
  42  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_edittime_editdate.htm">EditDate and EditTime</a>.
  43  *
  44  * The following example demonstrates how to use the %EditDate class.
  45  *
  46  * @code
  47 // Sample code for EditDateSample.h
  48 #include <FUi.h>
  49
  50 class EditDateSample
  51         : public Tizen::Ui::Controls::Form
  52         , public Tizen::Ui::IDateChangeEventListener
  53 {
  54 public:
  55         EditDateSample(void)
  56         : __pEditDate(null){}
  57
  58         bool Initialize(void);
  59         virtual result OnInitializing(void);
  60
  61         // IDateChangeEventListener
  62         virtual void OnDateChanged(const Tizen::Ui::Control& source, int year, int month, int day);
  63         virtual void OnDateChangeCanceled(const Tizen::Ui::Control& source);
  64
  65 private:
  66         Tizen::Ui::Controls::EditDate* __pEditDate;
  67 };
  68
  69  *      @endcode
  70  *
  71  *      @code
  72 // Sample code for EditDateSample.cpp
  73 #include <FGraphics.h>
  74
  75 #include "EditDateSample.h"
  76
  77 using namespace Tizen::Graphics;
  78 using namespace Tizen::Ui::Controls;
  79
  80 bool
  81 EditDateSample::Initialize(void)
  82 {
  83         Construct(FORM_STYLE_NORMAL);
  84         return true;
  85 }
  86
  87 result
  88 EditDateSample::OnInitializing(void)
  89 {
  90         result r = E_SUCCESS;
  91
  92         // Creates an instance of EditDate
  93         __pEditDate = new EditDate();
  94         __pEditDate->Construct(Point(100, 100));
  95         __pEditDate->AddDateChangeEventListener(*this);
  96
  97         // Adds an instace of IDateChangeEventListener
  98         AddControl(*__pEditDate);
  99
 100         return r;
 101 }
 102
 103 // IDateChangeEventListener implementation
 104 void
 105 EditDateSample::OnDateChanged(const Tizen::Ui::Control& source, int year, int month, int day)
 106 {
 107         // ....
 108 }
 109
 110 void
 111 EditDateSample::OnDateChangeCanceled(const Tizen::Ui::Control& source)
 112 {
 113         // ....
 114 }
 115  * @endcode
 116  */
 117 class _OSP_EXPORT_ EditDate
 118         : public Tizen::Ui::Control
 119 {
 120 public:
 121         /**
 122          * 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.
 123          *
 124          * @since               2.0
 125          */
 126         EditDate(void);
 127
 128         /**
 129          * 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.
 130          *
 131          * @since               2.0
 132          */
 133         virtual ~EditDate(void);
 134
 135         /**
 136          * Adds a data change event listener instance.
 137          * Added listener is called when the date of the DatePicker is changed either through user manipulation or by calling one of its setters.
 138          *
 139          * @since                       2.0
 140          *
 141          * @param[in]   listener    The listener to be added
 142          * @see                         IDateChangeEventListener::OnDateChanged()
 143          * @see                         IDateChangeEventListener::OnDateChangeCanceled()
 144          * @see                         RemoveDateChangeEventListener()
 145          */
 146         void AddDateChangeEventListener(Tizen::Ui::IDateChangeEventListener& listener);
 147
 148         /**
 149          * Removes a date changed event listener instance. @n
 150          * Removed listener cannot listen to events when they are fired.
 151          *
 152          * @since                       2.0
 153          *
 154          * @param[in]   listener        The listener to be removed
 155          * @see                         IDateChangeEventListener::OnDateChanged()
 156          * @see                         IDateChangeEventListener::OnDateChangeCanceled()
 157          * @see                         AddDateChangeEventListener()
 158          */
 159         void RemoveDateChangeEventListener(Tizen::Ui::IDateChangeEventListener& listener);
 160
 161         /**
 162          * Initializes this instance of %EditDate with the specified parameter.
 163          *
 164          * @since                       2.0
 165          *
 166          * @return                      An error code
 167          * @param[in]   point           The position of the %EditDate in the 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          * @remarks             A control is fully usable only after it has been added to a container, therefore, some methods may fail if used earlier.
 172          */
 173         result Construct(const Tizen::Graphics::Point& point, const Tizen::Base::String& title = L"");
 174
 175         /**
 176          * Gets the current date value of the %EditDate control.
 177          *
 178          * @since               2.0
 179          *
 180          * @return              The date value
 181          */
 182         Tizen::Base::DateTime GetDate(void) const;
 183
 184         /**
 185          * Gets the current day value of the %EditDate control.
 186          *
 187          * @since               2.0
 188          *
 189          * @return              The current day value as an integer, @n
 190          *                      else @c -1 if the %EditDate instance is not constructed
 191          */
 192         int GetDay(void) const;
 193
 194         /**
 195          * Gets the current month value of the %EditDate control.
 196          *
 197          * @since       2.0
 198          *
 199          * @return   The current month value as an integer,  @n
 200          *                      else @c -1 if the %EditDate instance is not constructed
 201          */
 202         int GetMonth(void) const;
 203
 204         /**
 205          * Gets the current year value of the %EditDate control.
 206          *
 207          * @since               2.0
 208          *
 209          * @return              The current year value, @n
 210          *                              else @c -1 if the %EditDate instance is not constructed
 211          */
 212         int GetYear(void) const;
 213
 214         /**
 215          * Sets the designated time value of the %EditDate control.
 216          *
 217          * @since                2.0
 218          *
 219          * @param[in]   date    The date to be set
 220          */
 221         void SetDate(const Tizen::Base::DateTime& date);
 222
 223         /**
 224          * Sets the value of the %EditDate control using the current system date.
 225          *
 226          * @since               2.0
 227          */
 228         void SetCurrentDate(void);
 229
 230         /**
 231          * Sets the year value.
 232          * The year value should be between @c 1 and @c 9999.
 233          *
 234          * @since                       2.0
 235          *
 236          * @return                      An error code
 237          * @param[in]   year            The year to be set
 238          * @exception   E_SUCCESS       The method is successful.
 239          * @exception   E_INVALID_ARG   The given year value is invalid.
 240          * @exception   E_SYSTEM                A system error has occurred.
 241          */
 242         result SetYear(int year);
 243
 244         /**
 245          * Sets the month value of the %EditDate control.
 246          * The month value should be between @c 1 and @c 12.
 247          *
 248          * @since                       2.0
 249          *
 250          * @return                      An error code
 251          * @param[in]   month           The month to be set
 252          * @exception   E_SUCCESS       The method is successful.
 253          * @exception   E_INVALID_ARG   The given month value is invalid.
 254          * @exception   E_SYSTEM                A system error has occurred.
 255          *
 256          */
 257         result SetMonth(int month);
 258
 259         /**
 260          * Sets the day value of the %EditDate control.
 261          * The day value should be between @c 1 and @c 31.
 262          *
 263          * @since                       2.0
 264          *
 265          * @return                      An error code
 266          * @param[in]   day                             The day to be set
 267          * @exception   E_SUCCESS       The method is successful.
 268          * @exception   E_INVALID_ARG   The given day value is invalid.
 269          * @exception   E_SYSTEM                A system error has occurred.
 270          */
 271         result SetDay(int day);
 272
 273         /**
 274          * Enables the %DatePicker control.
 275          *
 276          * @since                               2.0
 277          *
 278          * @param[in]   enable          Set to @c true to enable the DatePicker control, @n
 279          *                                                      else @c false
 280          */
 281         void SetDatePickerEnabled(bool enable);
 282
 283         /**
 284          * Checks whether the DatePicker control is enabled.
 285          *
 286          * @since               2.0
 287          *
 288          * @return              @c true if the DatePicker control is enabled, @n
 289          *                              else @c false
 290          */
 291         bool IsDatePickerEnabled(void) const;
 292
 293         /**
 294          * Sets the valid year range. @n
 295          * The range should be set in between @c 1 and @c 9999.
 296          *
 297          * @since                        2.0
 298          *
 299          * @return                             An error code
 300          * @param[in]   minYear                The minimum year for the valid range
 301          * @param[in]   maxYear                The maximum year for the valid range
 302          * @exception    E_SUCCESS                      The method is successful.
 303          * @exception   E_INVALID_ARG          The given year range is invalid.
 304          * @exception    E_SYSTEM                       A system error has occurred.
 305          */
 306         result SetYearRange(int minYear, int maxYear);
 307
 308         /**
 309          * Gets the valid year range.
 310          *
 311          * @since                        2.0
 312          *
 313          * @return                             An error code
 314          * @param[out]  minYear                The minimum year for the valid range
 315          * @param[out]  maxYear                The maximum year for the valid range
 316          * @exception    E_SUCCESS              The method is successful.
 317          * @exception    E_SYSTEM               A system error has occurred.
 318          */
 319         result GetYearRange(int& minYear, int& maxYear) const;
 320
 321 private:
 322         //
 323         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 324         //
 325         EditDate(const EditDate& rhs);
 326
 327         //
 328         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 329         //
 330         EditDate& operator =(const EditDate& rhs);
 331
 332         friend class _EditDateImpl;
 333 }; // EditDate
 334
 335 }}} //Tizen::Ui::Controls
 336
 337 #endif      // _FUI_CTRL_EDITDATE_H_