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