Calendar

Tizen enables you to manage your schedule and tasks.

A calendar is a collection of events or tasks, depending upon the calendar type. Each event or task has a series of attributes, such as purpose, starting time, and duration.

This feature is supported in mobile applications only.

Note
Due to time zone and daylight saving time, an event for "today" can actually occur in the past or in the future.

The events and tasks are identified using the CalendarItemId typedef, which is either a CalendarTaskId (for tasks) or CalendarEventId (for events). In recurring events, the CalendarEventId contains a recurrence ID (rid) in addition to the actual event ID, to separately identify each occurrence of the recurring event.

The Calendar API uses the TZDate object of the Time API and not the standard JavaScript Date object to handle difficult issues related to the time zone, because the TZDate object handles exact time and provides various utility methods.

The main features of the Calendar API include:

Calendar management
You can create a new calendar using the addCalendar() method of the CalendarManager interface (you also need the Account API).

To access an existing calendar item, you must first retrieve the calendar object of the applicable type from the applicable calendar. To access the device calendars, you can use:
- getDefaultCalendar() method of the CalendarManager interface to retrieve the default calendar.
- getCalendars() method to retrieve all the available calendars as an array.
- getUnifiedCalendar() method of the CalendarManager interface to retrieve the special calendar which combines events (or tasks) from all calendars of the same type.

Calendar item management

You can manage calendar items (add a new event or task to a calendar, or manage a single calendar event or task) by using the applicable methods of the Calendar interface.

If you need to delete or update a single instance of a recurring event, get the list of event instances first with the expandRecurrence() method of the CalendarEvent object. Then, delete the applicable event instance, or update it by calling the update() method with the updateAllInstances parameter set to false.

You can create multiple events or tasks, and manage multiple calendar events or tasks simultaneously by using the applicable batch methods: addBatch(), updateBatch(), and removeBatch(). The batch mode provides faster, optimized processing of multiple calendar items.

When searching for calendar items, you can create attribute filters, attribute range filters, and composite filters based on specific filter attributes. You can also sort the search results.

Note
The batch mode does not provide progress information about operations. To ensure that you can view the progress, break the batch operation down into multiple smaller batch operations. For example, break down a batch of 100 update requests into 10 batch operations that update 10 records at a time. Breaking down a batch operation also helps you avoid blocking other database operations, such as add or remove.

Note

The batch mode does not provide progress information about operations. To ensure that you can view the progress, break the batch operation down into multiple smaller batch operations. For example, break down a batch of 100 update requests into 10 batch operations that update 10 records at a time. Breaking down a batch operation also helps you avoid blocking other database operations, such as add or remove.

Calendar item alarms
You can set an alarm for an important event or task, such as a monthly meeting or a specific task (for example, paying a utility bill), by using the CalendarAlarm interface. The alarm is triggered at a defined time to remind the user of the event or task.
Calendar change notifications
You can keep the calendar in your application synchronized with user-specific calendars, such as a calendar on a social networking Web site, by receiving notifications in your application when calendar items change.

The addChangeListener() method of the Calendar interface registers an event listener, which starts asynchronously once the addChangeListener() method returns the subscription identifier for the listener. You can use the CalendarChangeCallback interface to define listener event handlers for receiving the notifications.

Every change made to the calendar database triggers an event for which you can define a notification. For batch mode operations, each operation generates only a single event. A recurring calendar event is treated as one event.
iCalendar 2.0 format conversions
You can convert a calendar event or task to the iCalendar format or back using the CalendarEvent or CalendarTask object constructor and the convertToString() method of the CalendarItem interface, respectively.

The conversion allows you to exchange calendar data between applications by sharing files with the .ics extension. The iCalendar format is independent of the underlying transport protocol, meaning that calendar items can be exchanged using a variety of transports, including HTTP, SMTP, and Infrared.

The iCalendar format can be used to store calendar item information and exchange calendar data over the internet.

The following example shows a sample event and task in the iCalendar format:
```
/* Event */
BEGIN:VCALENDAR
BEGIN:VEVENT
DTSTART:20110714T150000Z
DTEND:20110715T173000Z
SUMMARY:Prepare team meeting
END:VEVENT
END:VCALENDAR

/* Task */
BEGIN:VCALENDAR
BEGIN:VTODO
DTSTAMP:TZID=CET:20110902T110000Z
DTSTART:TZID=CET:20110906T140000Z
DUE:TZID=CET:20110906T150000Z
SUMMARY:Prepare team meeting
END:VTODO
END:VCALENDAR
```