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 fields */
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 specified time field, based on the calendar rules. @n
121 * It is equivalent to calling SetTimeField(field, GetTimeField(field)+amount) with the following 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. @c TIME_FIELD_HOUR is a smaller field than @c 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 the fields that 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(@c TIME_FIELD_MONTH, 13) sets the calendar to Nov 30, 2005. @n
141 * The @c TIME_FIELD_MONTH field is set to NOVEMBER by @b Rule1, since adding 13 months to October sets the month as
142 * November of the next year.
143 * Since, the @c TIME_FIELD_DAY_OF_MONTH cannot be 31 in November in a %GregorianCalendar, the @c 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 @c 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 @c 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 @c E_INVALID_STATE and @c 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 @c E_INVALID_ARG if the instance of %Calendar to be compared is invalid.
214 * -# The method returns @c E_INVALID_STATE if any time field value previously set is invalid.
215 * -# The method returns @c 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 @c E_INVALID_STATE and @c 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 @c E_INVALID_ARG if the instance of %Calendar to be compared is invalid.
256 * -# The method returns @c E_INVALID_STATE if any time field value previously set is invalid.
257 * -# The method returns @c 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 that 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 that 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
306 * (for example, @c TIME_FIELD_YEAR field cannot be changed when the input field is @c TIME_FIELD_MONTH). @n
307 * If the specified @c amount is negative, the amount value is deducted from the specified time field value.
308 * In this method, the time field of this instance is operated upon. If the value of the specified @c field goes out of range,
309 * @c E_OUT_OF_RANGE is returned.
312 * @brief <i> [Compatibility] </i>
316 * @compatibility This method has compatibility issues with OSP compatible applications. @n
317 * For more information, see @ref CompCalendarRollPage "here".
320 * @return An error code
321 * @param[in] field The time field to roll
322 * @param[in] amount The amount to add to the time field
323 * @exception E_SUCCESS The method is successful.
324 * @exception E_INVALID_ARG The specified @c field is invalid (for example, @c TIME_FIELD_DST_OFFSET, @c TIME_FIELD_ZONE_OFFSET).
325 * @exception E_OUT_OF_RANGE In this method, the time fields of this instance are calculated. @n
326 * If the value of the time fields goes out of range, this exception is returned.
328 virtual result Roll(TimeField field, int amount);
332 * @page CompCalendarRollPage Compatibility for Roll()
333 * @section CompCalendarRollIssueSection Issues
334 * Implementation of this method in OSP compatible applications has the following issue: @n
335 * -# The method returns @c E_INVALID_STATE if the time field is invalid.
337 * @section CompCalendarRollSolutionSection Resolutions
338 * This issue has been resolved in Tizen.
340 * @par When working in Tizen:
341 * -# The method returns @c E_INVALID_ARG if the time field is invalid.
346 * Sets the specified time field with the specified @c value. @n
347 * This sets an internal member variable to indicate that the field has been changed.
348 * Although the time field is changed, the milliseconds of %Calendar are not recomputed
349 * until GetTimeField(), GetTime(), or GetTimeInMillisec() is called.
350 * Thus, even if you call this method several times, unnecessary multiple computations are not triggered. @n
352 * When a field is changed using SetTimeField(), other fields may also change
353 * depending on the field, the field value, and the calendar system. @n
355 * For example, consider a GregorianCalendar set to Oct. 31, 2004.
356 * Calling SetTimeField(@c TIME_FIELD_MONTH, NOVEMBER) sets the calendar to Nov 31, 2004. @n
357 * But, if you call GetTime(), then Dec 1, 2004 is returned because Nov 31, 2004 does not exist.
358 * However, a call to SetTimeField(@c TIME_FIELD_MONTH, SEPTEMBER) before a call to GetTime() sets the calendar
359 * to Sep 30, 2004, since no re-computation has occurred after the first call to SetTimeField().
361 * The value of field is not affected by it being local time or UTC time.
362 * The value is only overwritten.
366 * @return An error code
367 * @param[in] field The time field to set
368 * @param[in] value The value to set
369 * @exception E_SUCCESS The method is successful.
370 * @exception E_OUT_OF_RANGE The value is out of range in lenient mode.
371 * @exception E_INVALID_ARG The specified @c field is invalid.
373 result SetTimeField(TimeField field, int value);
376 * Sets the first day of the week.
380 * @return An error code
381 * @param[in] dayOfWeek The value to set as the first day of the week
382 * @exception E_SUCCESS The method is successful.
383 * @exception E_INVALID_ARG The specified @c dayOfWeek is invalid.
385 result SetFirstDayOfWeek(DayOfWeek dayOfWeek);
388 * Sets the leniency of date and time interpretations.
392 * @return An error code
393 * @param[in] lenient Set to @c true if the date and time interpretation is set to lenient, @n
395 * @exception E_SUCCESS The method is successful.
397 result SetLenient(bool lenient);
400 * Sets the minimal days required in the first week.
404 * @return An error code
405 * @param[in] value The minimal days required in the first week
406 * @exception E_SUCCESS The method is successful.
408 result SetMinDaysInFirstWeek(short value);
411 * Sets the value of year, month, day, hour, minute, and seconds. @n
412 * The date and time are the local date and time.
416 * @return An error code
417 * @param[in] year The year to set
418 * @param[in] month The month to set @n
419 * The indexing is 1-based. Therefore, 1 means January.
420 * @param[in] day The day to set
421 * @param[in] hour The hour to set
422 * @param[in] minute The minute to set
423 * @param[in] second The second to set
424 * @exception E_SUCCESS The method is successful.
425 * @exception E_OUT_OF_RANGE A time field or its value is out of range in lenient mode.
427 result SetTime(int year, int month, int day, int hour = 0, int minute = 0, int second = 0);
430 * Sets the current time of this %Calendar instance with the specified Tizen::Base::DateTime.
434 * @return An error code
435 * @param[in] dateTime The Tizen::Base::DateTime instance to set
436 * @exception E_SUCCESS The method is successful.
437 * @remarks The time specified is the local time.
439 result SetTime(const Tizen::Base::DateTime& dateTime);
442 * Sets the current time of this %Calendar instance with the specified value.
446 * @return An error code
447 * @param[in] millisec The new time in milliseconds from the starting day (Jan 1, 1.)
448 * @exception E_SUCCESS The method is successful.
449 * @exception E_OUT_OF_RANGE A time field or its value is out of range.
451 result SetTimeInMillisec(long long millisec);
454 * Sets the time zone of the calendar to the specified time zone.
458 * @return An error code
459 * @param[in] timeZone The time zone to set
460 * @exception E_SUCCESS The method is successful.
462 result SetTimeZone(const TimeZone& timeZone);
465 * Gets the actual maximum value that the specified field can have, given the current date. @n
466 * For example, if the current date is "Feb 10, 2004" and the time field specified is @c TIME_FIELD_DAY_OF_MONTH, then the actual
467 * maximum value for this time field is @c 29.
471 * @return An integer value indicating the actual maximum value
472 * @param[in] field The time field
473 * @exception E_SUCCESS The method is successful.
474 * @exception E_INVALID_ARG The specified @c field is invalid.
475 * @remarks The specific error code can be accessed using the GetLastResult() method.
477 virtual int GetActualMaxTimeField(TimeField field) const;
480 * Gets the actual minimum value that the specified time field can have, given the current date. @n
481 * For the Gregorian calendar, this is the same as GetMinTimeField() and GetGreatestMinTimeField().
485 * @return An integer value indicating the actual minimum value
486 * @param[in] field The time field
487 * @exception E_SUCCESS The method is successful.
488 * @exception E_INVALID_ARG The specified @c field is invalid.
489 * @exception E_SYSTEM A system error has occurred.
490 * @remarks The specific error code can be accessed using the GetLastResult() method.
492 virtual int GetActualMinTimeField(TimeField field) const;
495 * Gets the value of the first day of the week. @n
496 * For example, in USA, the first day of the week is SUNDAY. But, in France, it is MONDAY.
500 * @return An integer value indicating the first day of the week, @n
501 * else @c -1 if it fails
503 int GetFirstDayOfWeek(void) const;
506 * Gets the greatest minimum value that the specified time field can have.
510 * @return An integer value indicating the greatest minimum value for the specified time field
511 * @param[in] field The time field
512 * @exception E_SUCCESS The method is successful.
513 * @exception E_INVALID_ARG The specified @c field is invalid.
514 * @exception E_SYSTEM A system error has occurred.
515 * @remarks The specific error code can be accessed using the GetLastResult() method.
517 virtual int GetGreatestMinTimeField(TimeField field) const;
520 * Gets the least maximum value that the specified time field can have.
524 * @return An integer value indicating the least maximum value for the specified time field
525 * @param[in] field The time field
526 * @exception E_SUCCESS The method is successful.
527 * @exception E_INVALID_ARG The specified @c field is invalid.
528 * @exception E_SYSTEM A system error has occurred.
529 * @remarks The specific error code can be accessed using the GetLastResult() method.
531 virtual int GetLeastMaxTimeField(TimeField field) const;
534 * Gets the maximum value that the specified time field can have.
538 * @return An integer value indicating the maximum value for the specified time field
539 * @param[in] field The time field
540 * @exception E_SUCCESS The method is successful.
541 * @exception E_INVALID_ARG The specified @c field is invalid.
542 * @exception E_SYSTEM A system error has occurred.
543 * @remarks The specific error code can be accessed using the GetLastResult() method.
545 virtual int GetMaxTimeField(TimeField field) const;
548 * Gets the minimum value that the specified time field can have.
552 * @return An integer value indicating the minimum value for the specified time field
553 * @param[in] field The time field
554 * @exception E_SUCCESS The method is successful.
555 * @exception E_INVALID_ARG The specified @c field is invalid.
556 * @exception E_SYSTEM A system error has occurred.
557 * @remarks The specific error code can be accessed using the GetLastResult() method.
559 virtual int GetMinTimeField(TimeField field) const;
562 * Gets the minimum number of days required in the first week of the year. @n
563 * For example, if the first week is defined as the one that contains the first day of
564 * the first month of a year, this method returns @c 1.
568 * @return An integer value indicating the minimum number of days required in the first week
570 int GetMinDaysInFirstWeek(void) const;
573 * Gets the date and time of the current instance of %Calendar.
577 * @return An instance of Tizen::Base::DateTime with the current time in local time
578 * @remarks The time specified is the local time.
580 Tizen::Base::DateTime GetTime(void) const;
583 * Gets the value of the specified time field.
587 * @return An integer value indicating the value of the specified time field
589 * @param[in] field The given time field
590 * @exception E_SUCCESS The method is successful.
591 * @exception E_INVALID_ARG The specified @c field is invalid.
592 * @exception E_SYSTEM A system error has occurred.
594 * - This method is semantically const, but may alter the instance in memory.
595 * - All fields are re-computed if any field is invalid.
596 * - The specific error code can be accessed using the GetLastResult() method.
598 int GetTimeField(TimeField field) const;
601 * Gets the current time of the instance in the @c long format.
605 * @return An error code
606 * @param[out] millisec The current time in milliseconds from starting day (Jan 1, 1.)
607 * @exception E_SUCCESS The method is successful.
608 * @exception E_INVALID_STATE In this method, the time fields of this instance are calculated. @n
609 * If any time field value previously set is invalid, this exception is returned.
610 * @exception E_OUT_OF_RANGE The value of the argument is out of the valid range defined by the method.
612 result GetTimeInMillisec(long long& millisec) const;
615 * Gets a reference to the time zone owned by this instance of %Calendar.
619 * @return The TimeZone instance associated with the current instance of %Calendar
620 * @remarks The returned reference is valid only until the SetTimeZone() method is called or
621 * this instance of %Calendar is destroyed.
624 TimeZone GetTimeZone(void) const;
627 * Gets the calendar type of the current instance of %Calendar.
631 * @return An instance of CalendarType representing the calendar type of the current instance of %Calendar @n
632 * For example, @c CALENDAR_GREGORIAN.
634 virtual CalendarType GetType(void) const = 0;
637 * Checks whether the current date for the instance of %Calendar is in Daylight Saving Time (DST).
641 * @return An error code
642 * @param[out] isInDst Set to @c true if the current date is in DST, @n
644 * @exception E_SUCCESS The method is successful.
645 * @exception E_INVALID_STATE In this method, the time fields of this instance are calculated. @n
646 * If any time field value previously set is invalid, this exception is returned.
647 * @exception E_OUT_OF_RANGE A time field or its value is out of range. @n
648 * In this method, the time fields of this instance are calculated.
649 * If the value of the time fields goes out of range, this exception is returned.
651 virtual result IsInDst(bool& isInDst) const = 0;
654 * Checks whether the date and time interpretation is lenient.
658 * @return @c true if the date and time interpretation is set to lenient, @n
661 bool IsLenient(void) const;
664 * Checks whether the specified time field has a value.
668 * @return @c true if the specified time field has a value, @n
670 * @param[in] field The time field
672 bool IsSet(TimeField field) const;
675 * Creates an instance of %Calendar of the specified type with the GMT time zone and the system locale. @n
676 * The instance has weekdata which is the first of week, minimal days in the first week, weekend on set, and weekend cease.
677 * The weekdata is set to default values by the locale.
681 * @return A pointer to the created %Calendar instance, @n
682 * else @c null if it fails
683 * @param[in] calendarType The type of calendar @n
684 * The default calendar is the Gregorian calendar (@c CALENDAR_GREGORIAN).
685 * @exception E_SUCCESS The method is successful.
686 * @exception E_OUT_OF_MEMORY The memory is insufficient.
687 * @exception E_SYSTEM A system error has occurred.
688 * @remarks The specific error code can be accessed using the GetLastResult() method.
690 static Calendar* CreateInstanceN(CalendarType calendarType = CALENDAR_GREGORIAN);
693 * Creates an instance of %Calendar of the specified type with the specified time zone and the system locale. @n
694 * The @c timeZone is used for the zone offset and the DST offset.
695 * The instance has weekdata which is the first of week, minimal days in the first week, weekend on set, and weekend cease.
696 * The weekdata is set to default values by the locale.
700 * @return A pointer to the created %Calendar instance, @n
701 * else @c null if it fails
702 * @param[in] timeZone An instance of TimeZone
703 * @param[in] calendarType The type of calendar @n
704 * The default calendar is the Gregorian calendar (@c CALENDAR_GREGORIAN).
705 * @exception E_SUCCESS The method is successful.
706 * @exception E_OUT_OF_MEMORY The memory is insufficient.
707 * @exception E_SYSTEM A system error has occurred.
708 * @remarks The specific error code can be accessed using the GetLastResult() method.
710 static Calendar* CreateInstanceN(const TimeZone& timeZone, CalendarType calendarType = CALENDAR_GREGORIAN);
713 * Creates an instance of %Calendar of the specified type with the specified @c locale and the GMT time zone. @n
714 * The instance has weekdata which is the first of week, minimal days in the first week, weekend on set, and weekend cease.
715 * The weekdata is set to default values by the specified @c locale.
718 * @brief <i> [Compatibility] </i>
722 * @compatibility This method has compatibility issues with OSP compatible applications. @n
723 * For more information, see @ref CompCalendarCreateInstanceNPage "here".
726 * @return A pointer to the created %Calendar instance, @n
727 * else @c null if it fails
728 * @param[in] locale The locale for whose country the %Calendar instance is needed
729 * @param[in] calendarType The type of calendar @n
730 * The default calendar is the Gregorian calendar (@c CALENDAR_GREGORIAN).
731 * @exception E_SUCCESS The method is successful.
732 * @exception E_SYSTEM A system error has occurred.
733 * @exception E_OUT_OF_MEMORY The memory is insufficient.
734 * @exception E_INVALID_ARG The specified @c locale is invalid.
735 * @remarks The specific error code can be accessed using the GetLastResult() method.
737 static Calendar* CreateInstanceN(const Locale& locale, CalendarType calendarType = CALENDAR_GREGORIAN);
740 * Creates an instance of %Calendar of the specified type with the specified time zone and @c locale. @n
741 * The @c timeZone is used for the zone offset and the DST offset.
742 * The instance has weekdata which is the first of week, minimal days in the first week, weekend on set, and weekend cease.
743 * The weekdata is set to default values by the specified @c locale.
746 * @brief <i> [Compatibility] </i>
750 * @compatibility This method has compatibility issues with OSP compatible applications. @n
751 * For more information, see @ref CompCalendarCreateInstanceNPage "here".
754 * @return A pointer to the created %Calendar instance, @n
755 * else @c null if it fails
756 * @param[in] timeZone An instance of TimeZone
757 * @param[in] locale The locale for the country the %Calendar instance is created
758 * @param[in] calendarType The calendar type @n
759 * The default calendar is the Gregorian calendar (@c CALENDAR_GREGORIAN).
760 * @exception E_SUCCESS The method is successful.
761 * @exception E_SYSTEM A system error has occurred.
762 * @exception E_OUT_OF_MEMORY The memory is insufficient.
763 * @exception E_INVALID_ARG The specified @c locale is invalid.
764 * @remarks The specific error code can be accessed using the GetLastResult() method.
766 static Calendar* CreateInstanceN(const TimeZone& timeZone, const Locale& locale, CalendarType calendarType = CALENDAR_GREGORIAN);
770 * @page CompCalendarCreateInstanceNPage Compatibility for CreateInstanceN()
771 * @section CompCalendarCreateInstanceNIssueSection Issues
772 * Implementation of this method in OSP compatible applications has the following issue: @n
773 * -# The method returns @c E_UNSUPPORTED_OPERATION if the locale is invalid.
775 * @section CompCalendarCreateInstanceNSolutionSection Resolutions
776 * This issue has been resolved in Tizen.
777 * @par When working in Tizen:
778 * -# The method returns @c E_INVALID_ARG if the locale is invalid.
786 * Defines the AM/PM mode. @n
787 * The indexing is 0-based.
793 AM, /**< The time is in A.M */
794 PM /**< The time is in P.M */
798 * @enum CalendarLimitType
800 * Defines the calendar limits.
804 enum CalendarLimitType
806 CALENDAR_LIMIT_MINIMUM = 0, /**< The minimum limit */
807 CALENDAR_LIMIT_GREATEST_MINIMUM, /**< The greatest minimum limit */
808 CALENDAR_LIMIT_LEAST_MAXIMUM, /**< The least maximum limit */
809 CALENDAR_LIMIT_MAXIMUM, /**< The maximum limit */
810 CALENDAR_LIMIT_COUNT /**< The number of limit type */
816 * Defines the stamp value.
822 UNSET = 0, /**< The stamp is unset */
823 COMPUTED, /**< The stamp is computed */
824 MINIMUM_USER_STAMP /**< The minimum user stamp */
828 * This is the default constructor for this class. @n
829 * The object is not fully constructed after this constructor is called. For full construction,
830 * the Construct() method must be called right after calling this constructor.
837 * Initializes this instance of %Calendar.
841 * @return An error code
842 * @exception E_SUCCESS The method is successful.
844 result Construct(void);
847 * Initializes this instance of %Calendar with the specified %Calendar instance.
851 * @return An error code
852 * @param[in] calendar The %Calendar instance to copy
853 * @exception E_SUCCESS The method is successful.
854 * @exception E_SYSTEM A system error has occurred.
857 result Construct(const Calendar& calendar);
860 * Initializes this instance of %Calendar with the specified time zone and @c locale. @n
861 * The @c timeZone is used for the zone offset and the DST offset.
862 * The instance has weekdata which is the first of week, minimal days in the first week, weekend on set, and weekend cease.
863 * The weekdata is set to default values by the specified @c locale.
866 * @brief <i> [Compatibility] </i>
870 * @compatibility This method has compatibility issues with OSP compatible applications. @n
871 * For more information, see @ref CompCalendarConstructPage "here".
874 * @return An error code
875 * @param[in] timeZone An instance of TimeZone
876 * @param[in] locale An instance of Locale
877 * @exception E_SUCCESS The method is successful.
878 * @exception E_INVALID_ARG The specified @c locale is invalid.
880 result Construct(const Tizen::Locales::TimeZone& timeZone, const Locale& locale);
884 * @page CompCalendarConstructPage Compatibility for Construct()
885 * @section CompCalendarConstructIssueSection Issues
886 * Implementation of this method in OSP compatible applications has the following issue: @n
887 * -# The method returns @c E_UNSUPPORTED_OPERATION if the locale is invalid.
889 * @section CompCalendarConstructSolutionSection Resolutions
890 * This issue has been resolved in Tizen.
891 * @par When working in Tizen:
892 * -# The method returns @c E_INVALID_ARG if the locale is invalid.
897 * Rolls up or down with a single unit of time on the specified time field without changing the larger fields. @n
898 * When rolling on the MONTH field, other fields such as DATE field might conflict and need to be changed.
902 * @return An error code
903 * @param[in] field The time field to change
904 * @param[in] up Set to @c true if the time field must be rolled upwards, @n
906 * @exception E_SUCCESS The method is successful.
907 * @exception E_INVALID_STATE In this method, the time fields of this instance are calculated. @n
908 * If any time field value previously set is invalid, this exception is returned.
909 * @exception E_INVALID_ARG The specified @c field is invalid (for example, @c TIME_FIELD_DST_OFFSET, @c TIME_FIELD_ZONE_OFFSET).
910 * @exception E_OUT_OF_RANGE A time field or its value is out of range. @n
911 * In this method, the time fields of this instance are calculated.
912 * If the value of the time fields goes out of range, this exception is returned.
914 virtual result RollWithSingleUnit(TimeField field, bool up) = 0;
917 * Checks whether the current instance of %Calendar is equivalent to the specified instance of %Calendar.
921 * @return @c true if the current instance of %Calendar is equivalent to the specified %Calendar instance, @n
923 * @param[in] calendar The instance of %Calendar to compare
924 * @remarks If the specified %Calendar instance is equivalent to the current instance, the two instances behave
925 * exactly the same, but they may be set to different times.
927 virtual bool IsEquivalentTo(const Calendar& calendar) const;
930 * Computes the time field value. @n
931 * Converts the current millisecond time value to TimeField. @n
932 * This allows syncing up the time field values with a new time that is set for the calendar.
936 * @return An error code
937 * @exception E_SUCCESS The method is successful.
938 * @exception E_OUT_OF_RANGE The time fields contain an invalid value. @n
939 * In this method, the time fields of this instance are calculated.
940 * If the value of the time fields goes out of range, this exception is returned.
942 virtual result ComputeTimeFields(void) = 0;
945 * Computes the time value. @n
946 * Converts the current values of time field to the millisecond time value.
950 * @return An error code
951 * @exception E_SUCCESS The method is successful.
952 * @exception E_INVALID_STATE A value of the internal time field is invalid.
954 virtual result ComputeTime(void) = 0;
957 * Gets the length of the specified month.
961 * @return An integer value indicating the number of days in the specified month
962 * @param[in] extendedYear An extended year
963 * @param[in] month A month
965 virtual int GetMonthLength(int extendedYear, int month) const = 0;
968 * Handle the limits of the specified time field that depend on the type of limit. @n
969 * Derived classes must implement this method for the following fields:
970 * @c TIME_FIELD_ERA, @c TIME_FIELD_YEAR, @c TIME_FIELD_MONTH, @c TIME_FIELD_WEEK_OF_YEAR, @c TIME_FIELD_WEEK_OF_MONTH,
971 * @c TIME_FIELD_DAY_OF_MONTH, @c TIME_FIELD_DAY_OF_YEAR, @c TIME_FIELD_DAY_OF_WEEK_IN_MONTH, @c TIME_FIELD_YEAR_WOY,
972 * @c TIME_FIELD_EXTENDED_YEAR.
976 * @return The limit of the specified field
977 * @param[in] field The time field
978 * @param[in] limitType The type of limit
980 virtual int HandleGetLimit(TimeField field, CalendarLimitType limitType) const = 0;
983 * Creates and returns a polymorphic copy of this calendar.
987 * @return A polymorphic copy of this calendar
989 virtual Tizen::Locales::Calendar* CloneN(void) const = 0;
992 // This method is for internal use only. Using this method can cause behavioral, security-related,
993 // and consistency-related issues in the application.
995 // This method is reserved and may change its name at any time without prior notice.
999 virtual void Calendar_Reserved1(void) { }
1002 // This method is for internal use only. Using this method can cause behavioral, security-related,
1003 // and consistency-related issues in the application.
1005 // This method is reserved and may change its name at any time without prior notice.
1009 virtual void Calendar_Reserved2(void) { }
1012 // This method is for internal use only. Using this method can cause behavioral, security-related,
1013 // and consistency-related issues in the application.
1015 // This method is reserved and may change its name at any time without prior notice.
1019 virtual void Calendar_Reserved3(void) { }
1022 // This method is for internal use only. Using this method can cause behavioral, security-related,
1023 // and consistency-related issues in the application.
1025 // This method is reserved and may change its name at any time without prior notice.
1029 virtual void Calendar_Reserved4(void) { }
1032 // This method is for internal use only. Using this method can cause behavioral, security-related,
1033 // and consistency-related issues in the application.
1035 // This method is reserved and may change its name at any time without prior notice.
1039 virtual void Calendar_Reserved5(void) { }
1043 * The implementation of this copy constructor is intentionally blank and declared as private to
1044 * prohibit copying of objects. Use CloneN() to get an exact copy of the instance.
1046 Calendar(const Calendar& calendar);
1049 * The implementation of this copy assignment operator is intentionally blank and declared as private
1050 * to prohibit copying of objects. Use CloneN() to get an exact copy of the instance.
1052 Calendar& operator =(const Calendar& calendar);
1056 * One day in milliseconds.
1060 static const int ONE_DAY_IN_MILLISEC = 86400000;
1063 * One hour in milliseconds.
1067 static const int ONE_HOUR_IN_MILLISEC = 60 * 60 * 1000;
1070 * One minute in milliseconds.
1074 static const int ONE_MINUTE_IN_MILLISEC = 60000;
1077 * One second in milliseconds.
1081 static const int ONE_SECOND_IN_MILLISEC = 1000;
1084 * One week in milliseconds.
1088 static const long long ONE_WEEK_IN_MILLISEC = 7 * ONE_DAY_IN_MILLISEC;
1092 * The field values for the currently set time for this calendar.
1094 int _timeFields[TIME_FIELD_FIELD_COUNT];
1097 * Pseudo-time-stamps which specify when each field is set.
1098 * There are two special values - UNSET and INTERNALLY_SET.
1100 int _stamp[TIME_FIELD_FIELD_COUNT];
1103 * The flags which tell if a specified time field for the calendar is set.
1105 bool _isSet[TIME_FIELD_FIELD_COUNT];
1107 long long _time; // UTC time
1108 Tizen::Locales::TimeZone _timeZone;
1112 bool _areAllFieldsSet;
1115 bool _isConstructed;
1117 // Mask values for calendar fields
1118 static const int ERA_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_ERA);
1119 static const int YEAR_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_YEAR);
1120 static const int MONTH_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_MONTH);
1121 static const int WEEK_OF_YEAR_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_WEEK_OF_YEAR);
1122 static const int WEEK_OF_MONTH_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_WEEK_OF_MONTH);
1123 static const int DAY_OF_MONTH_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_DAY_OF_MONTH);
1124 static const int DAY_OF_YEAR_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_DAY_OF_YEAR);
1125 static const int DAY_OF_WEEK_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_DAY_OF_WEEK);
1126 static const int DAY_OF_WEEK_IN_MONTH_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_DAY_OF_WEEK_IN_MONTH);
1127 static const int AM_PM_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_AM_PM);
1128 static const int HOUR_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_HOUR);
1129 static const int HOUR_OF_DAY_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_HOUR_OF_DAY);
1130 static const int MINUTE_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_MINUTE);
1131 static const int SECOND_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_SECOND);
1132 static const int MILLISECOND_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_MILLISECOND);
1133 static const int ZONE_OFFSET_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_ZONE_OFFSET);
1134 static const int DST_OFFSET_MASK = GET_TIME_FIELD_MASK(TIME_FIELD_DST_OFFSET);
1135 static const int ALL_FIELDS = GET_TIME_FIELD_MASK(TIME_FIELD_FIELD_COUNT) - 1;
1138 friend class _CalendarImpl;
1139 class _CalendarImpl* _pCalendarImpl;
1143 }} // Tizen::Locales
1145 #endif //_FLCL_CALENDAR_H_