2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
4 // Licensed under the Apache License, Version 2.0 (the License);
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
8 // http://www.apache.org/licenses/LICENSE-2.0
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
18 * @file FLclCalendar.h
19 * @brief This is the header file for the %Calendar class.
21 * This header file contains the declarations of the %Calendar class.
24 #ifndef _FLCL_CALENDAR_H_
25 #define _FLCL_CALENDAR_H_
28 #include <FLclLocale.h>
29 #include <FLclTimeZone.h>
31 namespace Tizen { namespace Locales
35 * @brief This class provides methods for displaying a calendar.
39 * The %Calendar class is an abstract base class for displaying a calendar. It is used to convert between the Tizen::Base::DateTime instance and a set of time fields, such as TIME_FIELD_YEAR, TIME_FIELD_MONTH, and TIME_FIELD_DAY_OF_MONTH.
40 * Subclasses of %Calendar interpret %Tizen::Base::DateTime according to the rules of a specific calendar system. GregorianCalendar is commonly used.
42 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/locales/calendar.htm">Calendar</a>.
44 * @see Tizen::Locales::TimeZone
46 * The following example demonstrates how to use the %Calendar class to set or add the time field.
53 using namespace Tizen::Base;
54 using namespace Tizen::Locales;
57 MyClass::CalendarExample(void)
60 String timeZoneName(L"Europe/Paris");
61 TimeZone timeZone(offset, timeZoneName);
63 Calendar* pCalendar = Calendar::CreateInstanceN(timeZone, CALENDAR_GREGORIAN);
64 pCalendar->SetTime(2012,7,18);
66 // Increase one day. The date will be 2012/7/19
67 pCalendar->AddTimeField(TIME_FIELD_DAY_OF_MONTH, 1);
69 // Decrease two months. The date will be 2012/5/19
70 pCalendar->AddTimeField(TIME_FIELD_MONTH, -2);
76 #define GET_TIME_FIELD_MASK(X) (static_cast<int>(1 << (X)))
80 * Defines the time fields for date and time. @n
81 * This enum is used in %Calendar.
87 TIME_FIELD_ERA, /**< Era : 0 - BC, 1 - AD */
88 TIME_FIELD_YEAR, /**< Year : 1-based */
89 TIME_FIELD_MONTH, /**< Month : 1-based (1~13)*/
90 TIME_FIELD_WEEK_OF_YEAR, /**< Week of Year : 1-based (1~53) */
91 TIME_FIELD_WEEK_OF_MONTH, /**< Week of Month : 1-based (1~6, may be specified as 0) */
92 TIME_FIELD_DAY_OF_MONTH, /**< Date : 1-based (1~31) */
93 TIME_FIELD_DAY_OF_YEAR, /**< Day of Year : 1-based (1~366) */
94 TIME_FIELD_DAY_OF_WEEK, /**< Day of Week : 1-based (1~7) */
95 TIME_FIELD_DAY_OF_WEEK_IN_MONTH, /**< Day of Week in Month : 1-based (1~5, may be specified as -1) */
96 TIME_FIELD_AM_PM, /**< AmPm : 0 - AM, 1 - PM */
97 TIME_FIELD_HOUR, /**< Hour : 0-based (0~11) */
98 TIME_FIELD_HOUR_OF_DAY, /**< Hour of Day : 0-based (0~23) */
99 TIME_FIELD_MINUTE, /**< Minute : 0-based (0~59) */
100 TIME_FIELD_SECOND, /**< Second : 0-based (0~59) */
101 TIME_FIELD_MILLISECOND, /**< Millisecond : 0-based (0~999) */
102 TIME_FIELD_ZONE_OFFSET, /**< Time Zone Offset : 0-based (-43200000~54000000 in milliseconds) */
103 TIME_FIELD_DST_OFFSET, /**< Daylight Saving Offset : 0-based (0~3600000 in milliseconds)*/
104 TIME_FIELD_FIELD_COUNT /**< The number of time field */
107 class _OSP_EXPORT_ Calendar
108 : public Tizen::Base::Object
112 * This is the destructor for this class. @n
113 * This destructor overrides Tizen::Base::Object::~Object().
117 virtual ~Calendar(void);
120 * Adds the specified amount to the given time field, based on the calendar rules. @n
121 * It is equivalent to calling SetTimeField(field, GetTimeField(field)+amount) with two adjustments. @n
123 * @b Add @b Rule1: The value of the time field @c field after the call minus the value of the field
124 * before the call is delta modulo any overflow that has occurred in the field.
125 * Overflow occurs when a time field value exceeds its range and, as a result, the next larger field
126 * is incremented or decremented and the field value is adjusted back into its range. @n
128 * @b Add @b Rule2: If a smaller field is expected to be invariant, but it is impossible for it to be
129 * equal to its prior value because of changes in its minimum or maximum value after the time field @c field
130 * is changed, then its value is adjusted to be as close as possible to its expected value. @n
132 * A smaller field represents a smaller unit of time. TIME_FIELD_HOUR is a smaller field than TIME_FIELD_DAY_OF_MONTH.
133 * No adjustment is made to smaller fields that are not expected to be invariant.
134 * The calendar system determines what fields are expected to be invariant.
136 * In addition, this method forces re-computation of the calendar's milliseconds and
137 * all time fields immediately. @n
139 * For example, consider a GregorianCalendar set to Oct 31, 2004.
140 * Calling AddTimeField(TIME_FIELD_MONTH, 13) sets the calendar to Nov 30, 2005. @n
141 * The TIME_FIELD_MONTH field is set to NOVEMBER by @b Rule1, since adding 13 months to October gives the
142 * November of the next year.
143 * Since, the TIME_FIELD_DAY_OF_MONTH cannot be 31 in November in a %GregorianCalendar, the TIME_FIELD_DAY_OF_MONTH is set to 30 by @b Rule2.
146 * @brief <i> [Compatibility] </i>
150 * @compatibility This method has compatibility issues with OSP compatible applications. @n
151 * For more information, see @ref CompCalendarAddTimeFieldPage "here".
154 * @return An error code
155 * @param[in] field The time field
156 * @param[in] amount The amount to add
157 * @exception E_SUCCESS The method is successful.
158 * @exception E_INVALID_ARG The specified @c field is invalid.
160 virtual result AddTimeField(TimeField field, int amount) = 0;
164 * @page CompCalendarAddTimeFieldPage Compatibility for AddTimeField()
165 * @section CompCalendarAddTimeFieldIssueSection Issues
166 * Implementation of this method in OSP compatible applications has the following issue: @n
167 * -# The method returns E_INVALID_STATE if the time field is invalid.
169 * @section CompCalendarAddTimeFieldSolutionSection Resolutions
170 * This issue has been resolved in Tizen.
172 * @par When working in Tizen:
173 * -# The method returns E_INVALID_ARG if the time field is invalid.
178 * Compares the current instance of %Calendar with the specified instance.
181 * @brief <i> [Compatibility] </i>
185 * @compatibility This method has compatibility issues with OSP compatible applications. @n
186 * For more information, see @ref CompCalendarAfterPage "here".
189 * @return An error code
190 * @param[in] otherCalendar The instance of %Calendar to compare
191 * @param[out] after Set to @c true if the current instance of %Calendar is after the specified instance of %Calendar, @n
193 * @exception E_SUCCESS The method is successful.
194 * @exception E_INVALID_ARG The specified @c otherCalendar is invalid.
195 * @exception E_INVALID_STATE In this method, the time fields of this instance are calculated. @n
196 * If any time field value previously set is invalid, this exception is returned.
197 * @exception E_OUT_OF_RANGE In this method, the time fields of this instance are calculated. @n
198 * If the value of the time fields goes out of range, this exception is returned.
200 result After(const Calendar& otherCalendar, bool& after);
204 * @page CompCalendarAfterPage Compatibility for After()
205 * @section CompCalendarAfterIssueSection Issues
206 * Implementation of this method in OSP compatible applications has the following issue: @n
207 * -# The method returns E_INVALID_STATE and E_OUT_OF_RANGE if the instance of %Calendar to be compared is invalid.
209 * @section CompCalendarAfterSolutionSection Resolutions
210 * This issue has been resolved in Tizen.
212 * @par When working in Tizen:
213 * -# The method returns E_INVALID_ARG if the instance of %Calendar to be compared is invalid.
214 * -# The method returns E_INVALID_STATE if any time field value previously set is invalid.
215 * -# The method returns E_OUT_OF_RANGE if the value of the time fields goes out of range.
220 * Compares the current instance of %Calendar with the specified instance.
223 * @brief <i> [Compatibility] </i>
227 * @compatibility This method has compatibility issues with OSP compatible applications. @n
228 * For more information, see @ref CompCalendarBeforePage "here".
231 * @return An error code
232 * @param[in] otherCalendar The instance of %Calendar to compare
233 * @param[out] before Set to @c true if the current instance of %Calendar is before the specified instance of %Calendar, @n
235 * @exception E_SUCCESS The method is successful.
236 * @exception E_INVALID_ARG The specified @c otherCalendar is invalid.
237 * @exception E_INVALID_STATE In this method, the time fields of this instance are calculated. @n
238 * If any time field value previously set is invalid, this exception is returned.
239 * @exception E_OUT_OF_RANGE In this method, the time fields of this instance are calculated. @n
240 * If the value of the time fields goes out of range, this exception is returned.
242 result Before(const Calendar& otherCalendar, bool& before);
246 * @page CompCalendarBeforePage Compatibility for Before()
247 * @section CompCalendarBeforeIssueSection Issues
248 * Implementation of this method in OSP compatible applications has the following issue: @n
249 * -# The method returns E_INVALID_STATE and E_OUT_OF_RANGE if the instance of %Calendar to be compared is invalid.
251 * @section CompCalendarBeforeSolutionSection Resolutions
252 * This issue has been resolved in Tizen.
254 * @par When working in Tizen:
255 * -# The method returns E_INVALID_ARG if the instance of %Calendar to be compared is invalid.
256 * -# The method returns E_INVALID_STATE if any time field value previously set is invalid.
257 * -# The method returns E_OUT_OF_RANGE if the value of the time fields goes out of range.
262 * Clears all the time fields and sets it to @c 0. @n
263 * Zero is not the default value for each field. It means the field is cleared.
267 * @return An error code
268 * @exception E_SUCCESS The method is successful.
273 * Clears the specified time field and sets it to @c 0. @n
274 * Zero is not the default value for each field. It means the field is cleared.
278 * @return An error code
279 * @param[in] field The time field to clear
280 * @exception E_SUCCESS The method is successful.
282 result Clear(TimeField field);
285 * Checks whether the value of the specified instance of Tizen::Base::Object is equal to the value of the current instance of %Calendar.
289 * @return @c true if the value of the specified instance of Tizen::Base::Object is equal to the value of the current instance of %Calendar, @n
291 * @param[in] obj An instance of Tizen::Base::Object to compare
293 virtual bool Equals(const Tizen::Base::Object& obj) const;
296 * Gets the hash value of the current instance.
300 * @return The hash value of the current instance
302 virtual int GetHashCode(void) const;
305 * Rolls up or down as per the specified @c amount in the specified time field without changing the larger fields (for example, TIME_FIELD_YEAR field cannot be changed when the input field is TIME_FIELD_MONTH). @n
306 * If the specified @c amount is negative, the amount value is deducted from the specified time field value.
307 * In this method, the time field of this instance is operated upon. If the value of the specified @c field goes out of range, E_OUT_OF_RANGE is returned.
310 * @brief <i> [Compatibility] </i>
314 * @compatibility This method has compatibility issues with OSP compatible applications. @n
315 * For more information, see @ref CompCalendarRollPage "here".
318 * @return An error code
319 * @param[in] field The time field to roll
320 * @param[in] amount The amount to add to the time field
321 * @exception E_SUCCESS The method is successful.
322 * @exception E_INVALID_ARG The specified @c field is invalid (for example, TIME_FIELD_DST_OFFSET, TIME_FIELD_ZONE_OFFSET).
323 * @exception E_OUT_OF_RANGE In this method, the time fields of this instance are calculated. @n
324 * If the value of the time fields goes out of range, this exception is returned.
326 virtual result Roll(TimeField field, int amount);
330 * @page CompCalendarRollPage Compatibility for Roll()
331 * @section CompCalendarRollIssueSection Issues
332 * Implementation of this method in OSP compatible applications has the following issue: @n
333 * -# The method returns E_INVALID_STATE if the time field is invalid.
335 * @section CompCalendarRollSolutionSection Resolutions
336 * This issue has been resolved in Tizen.
338 * @par When working in Tizen:
339 * -# The method returns E_INVALID_ARG if the time field is invalid.
344 * Sets the specified time field with the specified @c value. @n
345 * This sets an internal member variable to indicate that the field has been changed.
346 * Although the time field is changed, the milliseconds of %Calendar are not recomputed
347 * until GetTimeField(), GetTime(), or GetTimeInMillisec() is called.
348 * Thus, even if you call this method several times, unnecessary multiple computations are not triggered. @n
350 * As a result of changing a field using SetTimeField(), other fields may also change
351 * depending on the field, the field value, and the calendar system. @n
353 * For example, consider a GregorianCalendar set to Oct. 31, 2004.
354 * Calling SetTimeField(TIME_FIELD_MONTH, NOVEMBER) sets the calendar to Nov 31, 2004. @n
355 * But, if you call GetTime(), then Dec 1, 2004 is returned because Nov 31, 2004 does not exist.
356 * However, a call to SetTimeField(TIME_FIELD_MONTH, SEPTEMBER) before a call to GetTime() sets the calendar
357 * to Sep 30, 2004, since no re-computation has occurred after the first call to SetTimeField().
359 * The value of field is not affected by it being local time or UTC time.
360 * The value is only overwritten.
364 * @return An error code
365 * @param[in] field The time field to set
366 * @param[in] value The value to set
367 * @exception E_SUCCESS The method is successful.
368 * @exception E_OUT_OF_RANGE The value is out of range in lenient mode.
369 * @exception E_INVALID_ARG The specified @c field is invalid.
371 result SetTimeField(TimeField field, int value);
374 * Sets the first day of the week.
378 * @return An error code
379 * @param[in] dayOfWeek The value to set as the first day of the week
380 * @exception E_SUCCESS The method is successful.
381 * @exception E_INVALID_ARG The specified @c dayOfWeek is invalid.
383 result SetFirstDayOfWeek(DayOfWeek dayOfWeek);
386 * Sets the leniency of date and time interpretations.
390 * @return An error code
391 * @param[in] lenient Set to @c true if the date and time interpretation is set to lenient, @n
393 * @exception E_SUCCESS The method is successful.
395 result SetLenient(bool lenient);
398 * Sets the minimal days required in the first week.
402 * @return An error code
403 * @param[in] value The minimal days required in the first week
404 * @exception E_SUCCESS The method is successful.
406 result SetMinDaysInFirstWeek(short value);
409 * Sets the value of year, month, day, hour, minute, and seconds. @n
410 * The date and time are local time.
414 * @return An error code
415 * @param[in] year The value to set for year
416 * @param[in] month The value to set for month @n
417 * The indexing is 1-based. Therefore, 1 means January.
418 * @param[in] day The value to set for day
419 * @param[in] hour The value to set for hour
420 * @param[in] minute The value to set for minute
421 * @param[in] second The value to set for second
422 * @exception E_SUCCESS The method is successful.
423 * @exception E_OUT_OF_RANGE A time field or its value is out of range in lenient mode.
425 result SetTime(int year, int month, int day, int hour = 0, int minute = 0, int second = 0);
428 * Sets the calendar's current time with the specified Tizen::Base::DateTime.
432 * @return An error code
433 * @param[in] dateTime The Tizen::Base::DateTime instance to set
434 * @exception E_SUCCESS The method is successful.
435 * @remarks The time specified is the local time.
437 result SetTime(const Tizen::Base::DateTime& dateTime);
440 * Sets the current time of this %Calendar instance with the specified value.
444 * @return An error code
445 * @param[in] millisec The new time in milliseconds from the starting day (Jan 1, 1.)
446 * @exception E_SUCCESS The method is successful.
447 * @exception E_OUT_OF_RANGE A time field or its value is out of range.
449 result SetTimeInMillisec(long long millisec);
452 * Sets the time zone of the calendar to the specified time zone.
456 * @return An error code
457 * @param[in] timeZone The time zone to set
458 * @exception E_SUCCESS The method is successful.
460 result SetTimeZone(const TimeZone& timeZone);
463 * Gets the actual maximum value that the specified field can have, given the current date. @n
464 * For example, if the current date is "Feb 10, 2004" and the time field specified is TIME_FIELD_DAY_OF_MONTH, then the actual
465 * maximum value for this time field is 29.
469 * @return An integer value indicating the actual maximum value
470 * @param[in] field The time field
471 * @exception E_SUCCESS The method is successful.
472 * @exception E_INVALID_ARG The specified @c field is invalid.
473 * @remarks The specific error code can be accessed using the GetLastResult() method.
475 virtual int GetActualMaxTimeField(TimeField field) const;
478 * Gets the actual minimum value that the specified time field can have, given the current date. @n
479 * For the Gregorian calendar, this is the same as GetMinTimeField() and
480 * GetGreatestMinTimeField().
484 * @return An integer value indicating the actual minimum value
485 * @param[in] field The time field
486 * @exception E_SUCCESS The method is successful.
487 * @exception E_INVALID_ARG The specified @c field is invalid.
488 * @exception E_SYSTEM A system error has occurred.
489 * @remarks The specific error code can be accessed using the GetLastResult() method.
491 virtual int GetActualMinTimeField(TimeField field) const;
494 * Gets the value of the first day of the week. @n
495 * For example, in USA, the first day of the week is SUNDAY. But, it is MONDAY in France.
499 * @return An integer value indicating the first day of the week, @n
500 * else @c -1 if the method fails
502 int GetFirstDayOfWeek(void) const;
505 * Gets the greatest minimum value that the specified time field can have.
509 * @return An integer value indicating the greatest minimum value for the specified time field
510 * @param[in] field The time field
511 * @exception E_SUCCESS The method is successful.
512 * @exception E_INVALID_ARG The specified @c field is invalid.
513 * @exception E_SYSTEM A system error has occurred.
514 * @remarks The specific error code can be accessed using the GetLastResult() method.
516 virtual int GetGreatestMinTimeField(TimeField field) const;
519 * Gets the least maximum value that the specified time field can have.
523 * @return An integer value indicating the least maximum value for the specified time field
524 * @param[in] field The time field
525 * @exception E_SUCCESS The method is successful.
526 * @exception E_INVALID_ARG The specified @c field is invalid.
527 * @exception E_SYSTEM A system error has occurred.
528 * @remarks The specific error code can be accessed using the GetLastResult() method.
530 virtual int GetLeastMaxTimeField(TimeField field) const;
533 * Gets the maximum value that the specified time field can have.
537 * @return An integer value indicating the maximum value for the specified time field
538 * @param[in] field The time field
539 * @exception E_SUCCESS The method is successful.
540 * @exception E_INVALID_ARG The specified @c field is invalid.
541 * @exception E_SYSTEM A system error has occurred.
542 * @remarks The specific error code can be accessed using the GetLastResult() method.
544 virtual int GetMaxTimeField(TimeField field) const;
547 * Gets the minimum value that the specified time field can have.
551 * @return An integer value indicating the minimum value for the specified time field
552 * @param[in] field The time field
553 * @exception E_SUCCESS The method is successful.
554 * @exception E_INVALID_ARG The specified @c field is invalid.
555 * @exception E_SYSTEM A system error has occurred.
556 * @remarks The specific error code can be accessed using the GetLastResult() method.
558 virtual int GetMinTimeField(TimeField field) const;
561 * Gets the minimum number of days required in the first week of the year. @n
562 * For example, if the first week is defined as the one that contains the first day of
563 * the first month of a year, this method returns @c 1.
567 * @return An integer value indicating the minimum number of days required in the first week
569 int GetMinDaysInFirstWeek(void) const;
572 * Gets the date and time of the current instance of %Calendar.
576 * @return An instance of Tizen::Base::DateTime with the current time in local time
577 * @remarks The time specified is local time.
579 Tizen::Base::DateTime GetTime(void) const;
582 * Gets the value of the specified time field.
586 * @return An integer value indicating the value of the specified time field
588 * @param[in] field The given time field
589 * @exception E_SUCCESS The method is successful.
590 * @exception E_INVALID_ARG The specified @c field is invalid.
591 * @exception E_SYSTEM A system error has occurred.
592 * @remarks This method is semantically const, but may alter the instance in memory.
593 * All fields are re-computed if any field is invalid.
594 * The specific error code can be accessed using the GetLastResult() method.
596 int GetTimeField(TimeField field) const;
599 * Gets the current time of the instance in the @c long format.
603 * @return An error code
604 * @param[out] millisec The current time in milliseconds from starting day (Jan 1, 1.)
605 * @exception E_SUCCESS The method is successful.
606 * @exception E_INVALID_STATE In this method, the time fields of this instance are calculated. @n
607 * If any time field value previously set is invalid, this exception is returned.
608 * @exception E_OUT_OF_RANGE The value of the argument is out of the valid range defined by the method.
610 result GetTimeInMillisec(long long& millisec) const;
613 * Gets a reference to the time zone owned by this instance of %Calendar.
617 * @return The TimeZone instance associated with the current instance of %Calendar
618 * @remarks The returned reference is valid only until the SetTimeZone() method is called or this instance of %Calendar is destroyed.
621 TimeZone GetTimeZone(void) const;
624 * Gets the calendar type of the current instance of %Calendar.
628 * @return An instance of CalendarType representing the calendar type of the current instance of %Calendar @n
629 * For example, CALENDAR_GREGORIAN.
631 virtual CalendarType GetType(void) const = 0;
634 * Checks whether the current date for the instance of %Calendar is in Daylight Saving Time (DST).
638 * @return An error code
639 * @param[out] isInDst Set to @c true if the current date is in DST, @n
641 * @exception E_SUCCESS The method is successful.
642 * @exception E_INVALID_STATE In this method, the time fields of this instance are calculated. @n
643 * If any time field value previously set is invalid, this exception is returned.
644 * @exception E_OUT_OF_RANGE A time field or its value is out of range. @n
645 * In this method, the time fields of this instance are calculated. If the value of the time fields goes out of range, this exception is returned.
647 virtual result IsInDst(bool& isInDst) const = 0;
650 * Checks whether the date and time interpretation is lenient.
654 * @return @c true if the date and time interpretation is set to lenient, @n
657 bool IsLenient(void) const;
660 * Checks whether the specified time field has a value.
664 * @return @c true if the specified time field has a value, @n
666 * @param[in] field The time field
668 bool IsSet(TimeField field) const;
671 * Creates an instance of %Calendar of the specified type with the GMT time zone and the system locale. @n
672 * An instance has weekdata which are the first of week, minimal days in the first week, weekend on set, and weekend cease.
673 * The weekdata are set as default values by the locale.
677 * @return A pointer to the created %Calendar instance, @n
678 * else @c null if the method fails
679 * @param[in] calendarType The type of calendar @n
680 * Default calendar is the Gregorian calendar (CALENDAR_GREGORIAN).
681 * @exception E_SUCCESS The method is successful.
682 * @exception E_OUT_OF_MEMORY The memory is insufficient.
683 * @exception E_SYSTEM A system error has occurred.
684 * @remarks The specific error code can be accessed using the GetLastResult() method.
686 static Calendar* CreateInstanceN(CalendarType calendarType = CALENDAR_GREGORIAN);
689 * Creates an instance of %Calendar of the specified type with the specified time zone and the system locale. @n
690 * The @c timeZone is used for the zone offset and the DST offset.
691 * An instance has weekdata which are the first of week, minimal days in the first week, weekend on set, and weekend cease.
692 * The weekdata are set as default values by the locale.
696 * @return A pointer to the created %Calendar instance, @n
697 * else @c null if the method fails
698 * @param[in] timeZone An instance of TimeZone
699 * @param[in] calendarType The type of calendar @n
700 * Default calendar is the Gregorian calendar (CALENDAR_GREGORIAN).
701 * @exception E_SUCCESS The method is successful.
702 * @exception E_OUT_OF_MEMORY The memory is insufficient.
703 * @exception E_SYSTEM A system error has occurred.
704 * @remarks The specific error code can be accessed using the GetLastResult() method.
706 static Calendar* CreateInstanceN(const TimeZone& timeZone, CalendarType calendarType = CALENDAR_GREGORIAN);
709 * Creates an instance of %Calendar of the specified type with the specified @c locale and the GMT time zone. @n
710 * An instance has weekdata which are the first of week, minimal days in the first week, weekend on set, and weekend cease.
711 * The weekdata are set as default values by the specified @c locale.
714 * @brief <i> [Compatibility] </i>
718 * @compatibility This method has compatibility issues with OSP compatible applications. @n
719 * For more information, see @ref CompCalendarCreateInstanceNPage "here".
722 * @return A pointer to the created %Calendar instance, @n
723 * else @c null if the method fails
724 * @param[in] locale The locale for whose country the %Calendar instance is needed
725 * @param[in] calendarType The type of calendar @n
726 * Default calendar is the Gregorian calendar (CALENDAR_GREGORIAN).
727 * @exception E_SUCCESS The method is successful.
728 * @exception E_SYSTEM A system error has occurred.
729 * @exception E_OUT_OF_MEMORY The memory is insufficient.
730 * @exception E_INVALID_ARG The specified @c locale is invalid.
731 * @remarks The specific error code can be accessed using the GetLastResult() method.
733 static Calendar* CreateInstanceN(const Locale& locale, CalendarType calendarType = CALENDAR_GREGORIAN);
736 * Creates an instance of %Calendar of the specified type with the specified time zone and @c locale. @n
737 * The @c timeZone is used for the zone offset and the DST offset.
738 * An instance has weekdata which are the first of week, minimal days in the first week, weekend on set, and weekend cease.
739 * The weekdata are set as default values by the specified @c locale.
742 * @brief <i> [Compatibility] </i>
746 * @compatibility This method has compatibility issues with OSP compatible applications. @n
747 * For more information, see @ref CompCalendarCreateInstanceNPage "here".
750 * @return A pointer to the created %Calendar instance, @n
751 * else @c null if the method fails
752 * @param[in] timeZone An instance of TimeZone
753 * @param[in] locale The locale for whose country the %Calendar instance is needed
754 * @param[in] calendarType The type of calendar @n
755 * Default calendar is the Gregorian calendar (CALENDAR_GREGORIAN).
756 * @exception E_SUCCESS The method is successful.
757 * @exception E_SYSTEM A system error has occurred.
758 * @exception E_OUT_OF_MEMORY The memory is insufficient.
759 * @exception E_INVALID_ARG The specified @c locale is invalid.
760 * @remarks The specific error code can be accessed using the GetLastResult() method.
762 static Calendar* CreateInstanceN(const TimeZone& timeZone, const Locale& locale, CalendarType calendarType = CALENDAR_GREGORIAN);
766 * @page CompCalendarCreateInstanceNPage Compatibility for CreateInstanceN()
767 * @section CompCalendarCreateInstanceNIssueSection Issues
768 * Implementation of this method in OSP compatible applications has the following issue: @n
769 * -# The method returns E_UNSUPPORTED_OPERATION if the locale is invalid.
771 * @section CompCalendarCreateInstanceNSolutionSection Resolutions
772 * This issue has been resolved in Tizen.
773 * @par When working in Tizen:
774 * -# The method returns E_INVALID_ARG if the locale is invalid.
782 * Defines the AM/PM mode. @n
783 * This is a.m./p.m. The indexing is 0-based.
789 AM, /**< The time is in A.M */
790 PM /**< The time is in P.M */
794 * @enum CalendarLimitType
796 * Defines the calendar limitations.
800 enum CalendarLimitType
802 CALENDAR_LIMIT_MINIMUM = 0, /**< The minimum limit */
803 CALENDAR_LIMIT_GREATEST_MINIMUM, /**< The greatest minimum limit */
804 CALENDAR_LIMIT_LEAST_MAXIMUM, /**< The least maximum limit */
805 CALENDAR_LIMIT_MAXIMUM, /**< The maximum limit */
806 CALENDAR_LIMIT_COUNT /**< The number of limit type */
812 * Defines the stamp value.
818 UNSET = 0, /**< Unset */
819 COMPUTED, /**< Computed */
820 MINIMUM_USER_STAMP /**< Minimum user stamp */
824 * This is the default constructor for this class. @n
825 * 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.
834 * Initializes this instance of %Calendar.
838 * @return An error code
839 * @exception E_SUCCESS The method is successful.
841 result Construct(void);
844 * Initializes this instance of %Calendar with the specified parameter.
848 * @return An error code
849 * @param[in] calendar The %Calendar instance to copy
850 * @exception E_SUCCESS The method is successful.
851 * @exception E_SYSTEM A system error has occurred.
854 result Construct(const Calendar& calendar);
857 * Initializes this instance of %Calendar with the specified time zone and @c locale. @n
858 * The @c timeZone is used for the zone offset and the DST offset.
859 * An instance has weekdata which are the first of week, minimal days in the first week, weekend on set, and weekend cease.
860 * The weekdata are set as default values by the specified @c locale.
863 * @brief <i> [Compatibility] </i>
867 * @compatibility This method has compatibility issues with OSP compatible applications. @n
868 * For more information, see @ref CompCalendarConstructPage "here".
871 * @return An error code
872 * @param[in] timeZone An instance of TimeZone
873 * @param[in] locale An instance of Locale
874 * @exception E_SUCCESS The method is successful.
875 * @exception E_INVALID_ARG The specified @c locale is invalid.
877 result Construct(const Tizen::Locales::TimeZone& timeZone, const Locale& locale);
881 * @page CompCalendarConstructPage Compatibility for Construct()
882 * @section CompCalendarConstructIssueSection Issues
883 * Implementation of this method in OSP compatible applications has the following issue: @n
884 * -# The method returns E_UNSUPPORTED_OPERATION if the locale is invalid.
886 * @section CompCalendarConstructSolutionSection Resolutions
887 * This issue has been resolved in Tizen.
888 * @par When working in Tizen:
889 * -# The method returns E_INVALID_ARG if the locale is invalid.
894 * Rolls up or down with a single unit of time on a given time field without changing larger fields. @n
895 * When rolling on the MONTH field, other fields such as DATE field might conflict
896 * and needs to be changed.
900 * @return An error code
901 * @param[in] field The time field to change
902 * @param[in] up Set to @c true if the time field must be rolled upwards, @n
904 * @exception E_SUCCESS The method is successful.
905 * @exception E_INVALID_STATE In this method, the time fields of this instance are calculated. @n
906 * If any time field value previously set is invalid, this exception is returned.
907 * @exception E_INVALID_ARG The specified @c field is invalid (for example, TIME_FIELD_DST_OFFSET, TIME_FIELD_ZONE_OFFSET).
908 * @exception E_OUT_OF_RANGE A time field or its value is out of range. @n
909 * In this method, the time fields of this instance are calculated.
910 * If the value of the time fields goes out of range, this exception is returned.
912 virtual result RollWithSingleUnit(TimeField field, bool up) = 0;
915 * Checks whether the current instance of %Calendar is equivalent to the specified instance of %Calendar.
919 * @return @c true if the current instance of %Calendar is equivalent to the specified %Calendar instance, @n
921 * @param[in] calendar The instance of %Calendar to compare with
922 * @remarks If the specified %Calendar instance is equivalent to the current instance, the two instances behave
923 * exactly the same, but they may be set to different times.
925 virtual bool IsEquivalentTo(const Calendar& calendar) const;
928 * Computes the time field value. @n
929 * Converts the current millisecond time value to TimeField. @n
930 * This allows synching up the time field values with a new time that is set for the calendar.
934 * @return An error code
935 * @exception E_SUCCESS The method is successful.
936 * @exception E_OUT_OF_RANGE The time fields contain an invalid value. @n
937 * In this method, the time fields of this instance are calculated. If the value of the time fields goes out of range, this exception is returned.
939 virtual result ComputeTimeFields(void) = 0;
942 * Computes the time value. @n
943 * Converts the current values of time field to the millisecond time value.
947 * @return An error code
948 * @exception E_SUCCESS The method is successful.
949 * @exception E_INVALID_STATE A value of the internal time field is invalid.
951 virtual result ComputeTime(void) = 0;
954 * Gets the length of the specified month.
958 * @return An integer value indicating the number of days in the specified month
959 * @param[in] extendedYear An extended year
960 * @param[in] month A month
962 virtual int GetMonthLength(int extendedYear, int month) const = 0;
965 * Handles the limits of different types. @n
966 * Derived classes must implement this method for the following fields:
967 * TIME_FIELD_ERA, TIME_FIELD_YEAR, TIME_FIELD_MONTH, TIME_FIELD_WEEK_OF_YEAR, TIME_FIELD_WEEK_OF_MONTH,
968 * TIME_FIELD_DAY_OF_MONTH, TIME_FIELD_DAY_OF_YEAR, TIME_FIELD_DAY_OF_WEEK_IN_MONTH, TIME_FIELD_YEAR_WOY,
969 * TIME_FIELD_EXTENDED_YEAR.
973 * @return The limit of the specified field
974 * @param[in] field The time field
975 * @param[in] limitType The type of limit
977 virtual int HandleGetLimit(TimeField field, CalendarLimitType limitType) const = 0;
980 * Creates and returns a polymorphic copy of this calendar.
984 * @return A polymorphic copy of this calendar
986 virtual Tizen::Locales::Calendar* CloneN(void) const = 0;
989 // This method is for internal use only. Using this method can cause behavioral, security-related,
990 // and consistency-related issues in the application.
992 // This method is reserved and may change its name at any time without prior notice.
996 virtual void Calendar_Reserved1(void) { }
999 // This method is for internal use only. Using this method can cause behavioral, security-related,
1000 // and consistency-related issues in the application.
1002 // This method is reserved and may change its name at any time without prior notice.
1006 virtual void Calendar_Reserved2(void) { }
1009 // This method is for internal use only. Using this method can cause behavioral, security-related,
1010 // and consistency-related issues in the application.
1012 // This method is reserved and may change its name at any time without prior notice.
1016 virtual void Calendar_Reserved3(void) { }
1019 // This method is for internal use only. Using this method can cause behavioral, security-related,
1020 // and consistency-related issues in the application.
1022 // This method is reserved and may change its name at any time without prior notice.
1026 virtual void Calendar_Reserved4(void) { }
1029 // This method is for internal use only. Using this method can cause behavioral, security-related,
1030 // and consistency-related issues in the application.
1032 // This method is reserved and may change its name at any time without prior notice.
1036 virtual void Calendar_Reserved5(void) { }
1040 * The implementation of this copy constructor is intentionally blank and declared as private to
1041 * prohibit copying of objects. Use CloneN() to get an exact copy of the instance.
1043 Calendar(const Calendar& calendar);
1046 * The implementation of this copy assignment operator is intentionally blank and declared as private
1047 * to prohibit copying of objects. Use CloneN() to get an exact copy of the instance.
1049 Calendar& operator =(const Calendar& calendar);
1053 * Millisecond constants for one day.
1057 static const int ONE_DAY_IN_MILLISEC = 86400000;
1060 * Millisecond constants for one hour.
1064 static const int ONE_HOUR_IN_MILLISEC = 60 * 60 * 1000;
1067 * Millisecond constants for one minute.
1071 static const int ONE_MINUTE_IN_MILLISEC = 60000;
1074 * Millisecond constants for one second.
1078 static const int ONE_SECOND_IN_MILLISEC = 1000;
1081 * Millisecond constants for one week.
1085 static const long long ONE_WEEK_IN_MILLISEC = 7 * ONE_DAY_IN_MILLISEC;
1089 * The field values for the currently set time for this calendar.
1091 int _timeFields[TIME_FIELD_FIELD_COUNT];
1094 * Pseudo-time-stamps which specify when each field is set.
1095 * There are two special values - UNSET and INTERNALLY_SET.
1097 int _stamp[TIME_FIELD_FIELD_COUNT];
1100 * The flags which tell if a specified time field for the calendar is set.
1102 bool _isSet[TIME_FIELD_FIELD_COUNT];
1104 long long _time; // UTC time
1105 Tizen::Locales::TimeZone _timeZone;
1109 bool _areAllFieldsSet;
1112 bool _isConstructed;
1114 // Mask values for calendar fields
1115 static const int ERA_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_ERA);
1116 static const int YEAR_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_YEAR);
1117 static const int MONTH_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_MONTH);
1118 static const int WEEK_OF_YEAR_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_WEEK_OF_YEAR);
1119 static const int WEEK_OF_MONTH_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_WEEK_OF_MONTH);
1120 static const int DAY_OF_MONTH_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_DAY_OF_MONTH);
1121 static const int DAY_OF_YEAR_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_DAY_OF_YEAR);
1122 static const int DAY_OF_WEEK_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_DAY_OF_WEEK);
1123 static const int DAY_OF_WEEK_IN_MONTH_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_DAY_OF_WEEK_IN_MONTH);
1124 static const int AM_PM_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_AM_PM);
1125 static const int HOUR_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_HOUR);
1126 static const int HOUR_OF_DAY_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_HOUR_OF_DAY);
1127 static const int MINUTE_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_MINUTE);
1128 static const int SECOND_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_SECOND);
1129 static const int MILLISECOND_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_MILLISECOND);
1130 static const int ZONE_OFFSET_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_ZONE_OFFSET);
1131 static const int DST_OFFSET_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_DST_OFFSET);
1132 static const int ALL_FIELDS = GET_TIME_FIELD_MASK(TIME_FIELD_FIELD_COUNT) - 1;
1135 friend class _CalendarImpl;
1136 class _CalendarImpl* _pCalendarImpl;
1140 }} // Tizen::Locales
1142 #endif //_FLCL_CALENDAR_H_