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 instance 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 add
 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 remove
 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         * Initializes this instance of %EditDate with the specified parameter.
 177         *
 178         * @since                        2.1
 179         *
 180         * @return                       An error code
 181         * @param[in]    point           The position of the %EditDate in the container
 182         * @param[in]    title           The title
 183         * @exception    E_SUCCESS       The method is successful.
 184         * @exception    E_SYSTEM                A system error has occurred.
 185         * @remarks              A control is fully usable only after it has been added to a container, therefore, some methods may fail if used earlier.
 186         */
 187         result Construct(const Tizen::Graphics::FloatPoint& point, const Tizen::Base::String& title = L"");
 188
 189         /**
 190         * Gets the current date value of the %EditDate control.
 191         *
 192         * @since                2.0
 193         *
 194         * @return               The date value
 195         */
 196         Tizen::Base::DateTime GetDate(void) const;
 197
 198         /**
 199         * Gets the current day value of the %EditDate control.
 200         *
 201         * @since                2.0
 202         *
 203         * @return               The current day value
 204         *
 205         * @remarks              The default day value is the current system day.
 206         */
 207         int GetDay(void) const;
 208
 209         /**
 210         * Gets the current month value of the %EditDate control.
 211         *
 212         * @since        2.0
 213         *
 214         * @return   The current month value as an integer
 215         *
 216         * @remarks      The default month value is the current system month.
 217         */
 218         int GetMonth(void) const;
 219
 220         /**
 221         * Gets the current year value of the %EditDate control.
 222         *
 223         * @since                2.0
 224         *
 225         * @return               The current year value
 226         *
 227         * @remarks              The default year value is the current system year.
 228         */
 229         int GetYear(void) const;
 230
 231         /**
 232         * Sets the designated time value of the %EditDate control.
 233         *
 234         * @since                 2.0
 235         *
 236         * @param[in]    date    The date to set
 237         */
 238         void SetDate(const Tizen::Base::DateTime& date);
 239
 240         /**
 241         * Sets the value of the %EditDate control using the current system date.
 242         *
 243         * @since                2.0
 244         */
 245         void SetCurrentDate(void);
 246
 247         /**
 248         * Sets the year value.
 249         * The year value should be between @c 1 and @c 9999.
 250         *
 251         * @since                        2.0
 252         *
 253         * @return                       An error code
 254         * @param[in]    year            The year to set
 255         * @exception    E_SUCCESS       The method is successful.
 256         * @exception    E_INVALID_ARG   The given year value is invalid.
 257         * @exception    E_SYSTEM                A system error has occurred.
 258         */
 259         result SetYear(int year);
 260
 261         /**
 262         * Sets the month value of the %EditDate control.
 263         * The month value should be between @c 1 and @c 12.
 264         *
 265         * @since                        2.0
 266         *
 267         * @return                       An error code
 268         * @param[in]    month           The month to set
 269         * @exception    E_SUCCESS       The method is successful.
 270         * @exception    E_INVALID_ARG   The given month value is invalid.
 271         * @exception    E_SYSTEM                A system error has occurred.
 272         *
 273         */
 274         result SetMonth(int month);
 275
 276         /**
 277         * Sets the day value of the %EditDate control.
 278         * The day value should be between @c 1 and @c 31.
 279         *
 280         * @since                        2.0
 281         *
 282         * @return                       An error code
 283         * @param[in]    day                             The day to set
 284         * @exception    E_SUCCESS       The method is successful.
 285         * @exception    E_INVALID_ARG   The given day value is invalid.
 286         * @exception    E_SYSTEM                A system error has occurred.
 287         */
 288         result SetDay(int day);
 289
 290         /**
 291         * Enables the %DatePicker control.
 292         *
 293         * @since                                2.0
 294         *
 295         * @param[in]    enable          Set to @c true to enable the DatePicker control, @n
 296         *                                                       else @c false
 297         */
 298         void SetDatePickerEnabled(bool enable);
 299
 300         /**
 301         * Checks whether the DatePicker control is enabled.
 302         *
 303         * @since                2.0
 304         *
 305         * @return               @c true if the DatePicker control is enabled, @n
 306         *                               else @c false
 307         */
 308         bool IsDatePickerEnabled(void) const;
 309
 310         /**
 311         * Sets the valid year range. @n
 312         * The range should be set in between @c 1 and @c 9999.
 313         *
 314         * @since                         2.0
 315         *
 316         * @return                             An error code
 317         * @param[in]   minYear                The minimum year for the valid range
 318         * @param[in]   maxYear                The maximum year for the valid range
 319         * @exception    E_SUCCESS                       The method is successful.
 320         * @exception   E_INVALID_ARG          The given year range is invalid.
 321         * @exception    E_SYSTEM                        A system error has occurred.
 322         */
 323         result SetYearRange(int minYear, int maxYear);
 324
 325         /**
 326         * Gets the valid year range.
 327         *
 328         * @since                         2.0
 329         *
 330         * @return                             An error code
 331         * @param[out]  minYear                The minimum year for the valid range
 332         * @param[out]  maxYear                The maximum year for the valid range
 333         * @exception    E_SUCCESS               The method is successful.
 334         * @exception    E_SYSTEM                A system error has occurred.
 335         */
 336         result GetYearRange(int& minYear, int& maxYear) const;
 337
 338 private:
 339         //
 340         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 341         //
 342         EditDate(const EditDate& rhs);
 343
 344         //
 345         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 346         //
 347         EditDate& operator =(const EditDate& rhs);
 348
 349         friend class _EditDateImpl;
 350 }; // EditDate
 351
 352 }}} //Tizen::Ui::Controls
 353
 354 #endif      // _FUI_CTRL_EDITDATE_H_