You are reading 12.5.0. See this page in 13.4.1.
Titanium.Calendar
Extends Titanium.ModuleTitanium.Proxy
The Calendar module provides an API for accessing the native calendar functionality.
This module supports retrieving information about existing events and creating new events. Modifying or deleting existing events and creating recurring events are only supported on iOS.
Android
On Android, calendar permissions must be explicitly configured in tiapp.xml in order to access the
calendar and you have to use requestCalendarPermissions
to request runtime permissions.
<uses-permission android:name="android.permission.READ_CALENDAR"/>
<uses-permission android:name="android.permission.WRITE_CALENDAR"/>
See "Common Requirements" in tiapp.xml and timodule.xml Reference.
Examples
All Calendars vs Selectable Calendars
Print the names of all calendars, and the names of calendars that have been selected in the native Android calendar application.
function showCalendars(calendars) {
for (var i = 0; i < calendars.length; i++) {
Ti.API.info(calendars[i].name);
}
}
// Provide permissions if necessary
if (!Ti.Calendar.hasCalendarPermissions()) {
Ti.Calendar.requestCalendarPermissions(function (e) {
if (e.success) {
printCalendars();
}
});
} else {
printCalendars();
}
function printCalendars() {
Ti.API.info('ALL CALENDARS:');
showCalendars(Ti.Calendar.allCalendars);
if (Ti.Platform.osname === 'android') {
Ti.API.info('SELECTABLE CALENDARS:');
showCalendars(Ti.Calendar.selectableCalendars);
}
}
Create an Event and Reminder on Android
Creates an event and adds an e-mail reminder for 10 minutes before the event.
var CALENDAR_TO_USE = 3;
var calendar = Ti.Calendar.getCalendarById(CALENDAR_TO_USE);
// Create the event
var eventBegins = new Date(2010, 11, 26, 12, 0, 0);
var eventEnds = new Date(2010, 11, 26, 14, 0, 0);
var details = {
title: 'Do some stuff',
description: "I'm going to do some stuff at this time.",
begin: eventBegins,
end: eventEnds
};
var event = calendar.createEvent(details);
// Now add a reminder via e-mail for 10 minutes before the event.
var reminderDetails = {
minutes: 10,
method: Ti.Calendar.METHOD_EMAIL
};
event.createReminder(reminderDetails);
Events in a year
Create a picker to allow an existing calendar to be selected and, when a button is clicked, generate details of all events in that calendar for the current year.
var calendars = [];
var selectedCalendarName;
var selectedid;
var pickerData = [];
var osname = Ti.Platform.osname;
//**read events from calendar*******
function performCalendarReadFunctions(){
var scrollView = Ti.UI.createScrollView({
backgroundColor: '#eee',
height: 500,
top: 20
});
var label = Ti.UI.createLabel({
backgroundColor: 'gray',
text: 'Click on the button to display the events for the selected calendar',
textAlign: Ti.UI.TEXT_ALIGNMENT_CENTER,
top: 20
});
scrollView.add(label);
var selectableCalendars = Ti.Calendar.allCalendars;
for (var i = 0, ilen = selectableCalendars.length; i < ilen; i++) {
calendars.push({ name: selectableCalendars[i].name, id: selectableCalendars[i].id });
pickerData.push( Ti.UI.createPickerRow({ title: calendars[i].name }) );
if(i === 0){
selectedCalendarName = selectableCalendars[i].name;
selectedid = selectableCalendars[i].id;
}
}
if(!calendars.length){
label.text = 'No calendars available. Select at least one in the native calendar before using this app';
} else {
label.text = 'Click button to view calendar events';
var picker = Ti.UI.createPicker({
top:20
});
picker.add(pickerData);
win.add(picker);
picker.addEventListener('change', function(e){
for (var i = 0, ilen = calendars.length; i < ilen; i++) {
if(calendars[i].name === e.row.title){
selectedCalendarName = calendars[i].name;
selectedid = calendars[i].id;
Ti.API.info('Selected calendar that we are going to fetch is :: '+ selectedid + ' name:' + selectedCalendarName);
}
}
});
var button = Ti.UI.createButton({
title: 'View events',
top: 20
});
win.add(button);
button.addEventListener('click', function(e){
label.text = 'Generating...';
var currentYear = new Date().getFullYear();
var consoleString = '';
function print(s) {
if (consoleString.length) {
consoleString = consoleString + '\n';
}
consoleString = consoleString + s;
}
var calendar = Ti.Calendar.getCalendarById(selectedid);
Ti.API.info('Calendar was of type' + calendar);
Ti.API.info('calendar that we are going to fetch is :: '+ calendar.id + ' name:' + calendar.name);
function printReminder(r) {
if (osname === 'android') {
var typetext = '[method unknown]';
if (r.method == Ti.Calendar.METHOD_EMAIL) {
typetext = 'Email';
} else if (r.method == Ti.Calendar.METHOD_SMS) {
typetext = 'SMS';
} else if (r.method == Ti.Calendar.METHOD_ALERT) {
typetext = 'Alert';
} else if (r.method == Ti.Calendar.METHOD_DEFAULT) {
typetext = '[default reminder method]';
}
print(typetext + ' reminder to be sent ' + r.minutes + ' minutes before the event');
}
}
function printAlert(a) {
if (osname === 'android') {
print('Alert id ' + a.id + ' begin ' + a.begin + '; end ' + a.end + '; alarmTime ' + a.alarmTime + '; minutes ' + a.minutes);
} else if (osname === 'iphone' || osname === 'ipad') {
print('Alert absoluteDate ' + a.absoluteDate + ' relativeOffset ' + a.relativeOffset);
}
}
function printEvent(event) {
if (event.allDay) {
print('Event: ' + event.title + '; ' + event.begin + ' (all day)');
} else {
print('Event: ' + event.title + '; ' + event.begin + ' ' + event.begin+ '-' + event.end);
}
var reminders = event.reminders;
if (reminders && reminders.length) {
print('There is/are ' + reminders.length + ' reminder(s)');
for (var i = 0; i < reminders.length; i++) {
printReminder(reminders[i]);
}
}
print('hasAlarm? ' + event.hasAlarm);
var alerts = event.alerts;
if (alerts && alerts.length) {
for (var i = 0; i < alerts.length; i++) {
printAlert(alerts[i]);
}
}
var status = event.status;
if (status == Ti.Calendar.STATUS_TENTATIVE) {
print('This event is tentative');
}
if (status == Ti.Calendar.STATUS_CONFIRMED) {
print('This event is confirmed');
}
if (status == Ti.Calendar.STATUS_CANCELED) {
print('This event was canceled');
}
}
var events = calendar.getEventsInYear(currentYear);
if (events && events.length) {
print(events.length + ' event(s) in ' + currentYear);
print('');
for (var i = 0; i < events.length; i++) {
printEvent(events[i]);
print('');
}
} else {
print('No events');
}
label.text = consoleString;
});
}
win.add(scrollView);
}
var win = Ti.UI.createWindow({
backgroundColor: 'gray',
exitOnClose: true,
fullscreen: false,
layout: 'vertical',
title: 'Calendar Demo'
});
if (Ti.Calendar.hasCalendarPermissions()) {
performCalendarReadFunctions();
} else {
Ti.Calendar.requestCalendarPermissions(function(e) {
if (e.success) {
performCalendarReadFunctions();
} else {
Ti.API.error(e.error);
alert('Access to calendar is not allowed');
}
});
}
win.open();
Create a Recurring Event with Alerts on iOS (add the code to the sample above)
Create a recurring event with alerts.
function printEventDetails(eventID) {
Ti.API.info('eventID:' + eventID);
var defCalendar = Ti.Calendar.getCalendarById(selectedid);
var eventFromCalendar = defCalendar.getEventById(eventID);
if (eventFromCalendar) {
Ti.API.info('Printing event values ::');
Ti.API.info('title: '+ eventFromCalendar.title);
Ti.API.info('notes: ' + eventFromCalendar.notes);
Ti.API.info('location: ' + eventFromCalendar.location);
Ti.API.info('allDay?:' + eventFromCalendar.allDay);
Ti.API.info('status: '+ eventFromCalendar.status);
Ti.API.info('availability: '+ eventFromCalendar.availability);
Ti.API.info('hasAlarm?: '+ eventFromCalendar.hasAlarm);
Ti.API.info('id: '+ eventFromCalendar.id);
Ti.API.info('isDetached?: '+ eventFromCalendar.isDetached);
Ti.API.info('begin: '+ eventFromCalendar.begin);
Ti.API.info('end: '+ eventFromCalendar.end);
var eventRule = eventFromCalendar.recurrenceRules;
Ti.API.info('recurrenceRules : ' + eventRule);
for (var i = 0; i < eventRule.length; i++) {
Ti.API.info('Rule # ' + i);
Ti.API.info('frequency: ' + eventRule[i].frequency);
Ti.API.info('interval: ' + eventRule[i].interval);
Ti.API.info('daysofTheWeek: ' );
var daysofTheWeek = eventRule[i].daysOfTheWeek;
for (var j = 0; j < daysofTheWeek.length; j++) {
Ti.API.info('{ dayOfWeek: ' + daysofTheWeek[j].dayOfWeek + ', weekNumber: ' + daysofTheWeek[j].week + ' }, ');
}
Ti.API.info('firstDayOfTheWeek: ' + eventRule[i].firstDayOfTheWeek);
Ti.API.info('daysOfTheMonth: ');
var daysOfTheMonth = eventRule[i].daysOfTheMonth;
for(var j = 0; j < daysOfTheMonth.length; j++) {
Ti.API.info(' ' + daysOfTheMonth[j]);
}
Ti.API.info('daysOfTheYear: ');
var daysOfTheYear = eventRule[i].daysOfTheYear;
for(var j = 0; j < daysOfTheYear.length; j++) {
Ti.API.info(' ' + daysOfTheYear[j]);
}
Ti.API.info('weeksOfTheYear: ');
var weeksOfTheYear = eventRule[i].weeksOfTheYear;
for(var j = 0; j < weeksOfTheYear.length; j++) {
Ti.API.info(' ' + weeksOfTheYear[j]);
}
Ti.API.info('monthsOfTheYear: ');
var monthsOfTheYear = eventRule[i].monthsOfTheYear;
for(var j = 0; j < monthsOfTheYear.length; j++) {
Ti.API.info(' ' + monthsOfTheYear[j]);
}
Ti.API.info('daysOfTheYear: ');
if (osname !== 'android') {
var setPositions = eventRule[i].setPositions;
for(var j = 0; j < setPositions.length; j++) {
Ti.API.info(' ' + setPositions[j]);
}
}
};
Ti.API.info('alerts: ' + eventFromCalendar.alerts);
var newAlerts = eventFromCalendar.alerts;
for(var i = 0 ; i < newAlerts.length ; i++) {
Ti.API.info('*****Alert ' + i);
Ti.API.info('absoluteDate: ' + newAlerts[i].absoluteDate);
Ti.API.info('relativeOffset: ' + newAlerts[i].relativeOffset);
}
}
}
function performCalendarWriteFunctions(){
var defCalendar = Ti.Calendar.getCalendarById(selectedid);
var date1 = new Date(new Date().getTime() + 3000),
date2 = new Date(new Date().getTime() + 900000);
Ti.API.info('Date1: ' + date1 + ', Date2: ' + date2);
var event1 = defCalendar.createEvent({
title: 'Sample Event',
notes: 'This is a test event which has some values assigned to it.',
location: 'Appcelerator Inc',
begin: date1,
end: date2,
availability: Ti.Calendar.AVAILABILITY_FREE,
allDay: false,
});
var alert1;
var alert2;
if (osname === 'android') {
alert1 = event1.createAlert({
minutes: 60
})
} else {
alert1 = event1.createAlert({
absoluteDate: new Date(new Date().getTime() - (1000*60*20))
});
alert2 = event1.createAlert({
relativeOffset:-(60*15)
})
}
var allAlerts = new Array(alert1,alert2);
event1.alerts = allAlerts;
var newRule = event1.createRecurrenceRule({
frequency: Ti.Calendar.RECURRENCEFREQUENCY_MONTHLY,
interval: 1,
daysOfTheWeek: [ { dayOfWeek: 1, week: 2 }, { dayOfWeek: 2 } ],
end: { occurrenceCount: 10 }
});
Ti.API.info('newRule: '+ newRule);
event1.recurrenceRules = [newRule];
Ti.API.info('Going to save event now');
event1.save(Ti.Calendar.SPAN_THISEVENT);
Ti.API.info('Done with saving event,\n Now trying to retrieve it.');
printEventDetails(event1.id);
}
var button2 = Ti.UI.createButton({
title: 'Create a recurring event',
top: 20
});
win.add(button2);
button2.addEventListener('click', function () {
performCalendarWriteFunctions();
});
Properties 72
All alerts in selected calendars.
All calendars known to the native calendar app.
All calendars known to the native calendar app that can add, edit, and delete items in the calendar.
Inherited from Titanium.Proxy
The name of the API that this proxy corresponds to.
Attendee role is chair.
Attendee is not a participant.
Attendee role is optional.
Attendee role is required.
Attendee role is unknown.
Attendee status is accepted.
Attendee status is declined.
Attendee status is delegated.
Attendee status is in process.
Attendee status is invited.
There is no Attendee status.
Attendee status is pending.
Attendee status is tentative.
Attendee status is unknown.
Attendee type is group.
There is not attendee type.
Attendee type is person.
Attendee type is required.
Attendee type is resource.
Attendee type is room.
Attendee type is unknown.
An calendarAuthorization value indicating that the application is authorized to use events in the Calendar.
This value is always returned if the device is running an iOS release prior to 6.0.
An calendarAuthorization value indicating that the application is not authorized to use events in the Calendar.
An calendarAuthorization value indicating that the application is not authorized to use events in the Calendar. the user cannot change this application's status.
An calendarAuthorization value indicating that the authorization state is unknown.
Event has a busy availability setting.
An event's availability value.
One of the group of event method constants, AVAILABILITY_NOTSUPPORTED, AVAILABILITY_BUSY, AVAILABILITY_FREE, AVAILABILITY_TENTATIVE, and AVAILABILITY_UNAVAILABLE.
Event has a free availability setting.
An event's availability value.
One of the group of event method constants, AVAILABILITY_NOTSUPPORTED, AVAILABILITY_BUSY, AVAILABILITY_FREE, AVAILABILITY_TENTATIVE, and AVAILABILITY_UNAVAILABLE.
Availability settings are not supported by the event's calendar.
An event's availability value.
One of the group of event method constants, AVAILABILITY_NOTSUPPORTED, AVAILABILITY_BUSY, AVAILABILITY_FREE, AVAILABILITY_TENTATIVE, and AVAILABILITY_UNAVAILABLE.
Event has a tentative availability setting.
An event's availability value.
One of the group of event method constants, AVAILABILITY_NOTSUPPORTED, AVAILABILITY_BUSY, AVAILABILITY_FREE, AVAILABILITY_TENTATIVE, and AVAILABILITY_UNAVAILABLE.
Event has a tentative availability setting.
An event's availability value.
One of the group of event method constants, AVAILABILITY_NOTSUPPORTED, AVAILABILITY_BUSY, AVAILABILITY_FREE, AVAILABILITY_TENTATIVE, and AVAILABILITY_UNAVAILABLE.
Inherited from Titanium.Proxy
Indicates if the proxy will bubble an event to its parent.
Default: true
Returns an authorization constant indicating if the application has access to the events in the EventKit.
Always returns AUTHORIZATION_AUTHORIZED on iOS pre-6.0.
type: Number
Calendar that events are added to by default, as specified by user settings.
Will return the default calendar of your phone. On Android it will return the first primary calendar in case you have multiple accounts on your phone.
Inherited from Titanium.Proxy
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
Reminder alert delivery method.
Used with Titanium.Calendar.Reminder.
One of the group of reminder method constants, METHOD_ALERT, METHOD_DEFAULT, METHOD_EMAIL, and METHOD_SMS.
Reminder default delivery method.
Used with Titanium.Calendar.Reminder.
One of the group of reminder method constants, METHOD_ALERT, METHOD_DEFAULT, METHOD_EMAIL, and METHOD_SMS.
Reminder email delivery method.
Used with Titanium.Calendar.Reminder.
One of the group of reminder method constants, METHOD_ALERT, METHOD_DEFAULT, METHOD_EMAIL, and METHOD_SMS.
Reminder SMS delivery method.
Used with Titanium.Calendar.Reminder.
One of the group of reminder method constants, METHOD_ALERT, METHOD_DEFAULT, METHOD_EMAIL, and METHOD_SMS.
Indicates a daily recurrence rule for a events reccurance frequency.
Used with the Titanium.Calendar.RecurrenceRule.frequency property.
One of the group of event "frequency" constants RECURRENCEFREQUENCY_DAILY, RECURRENCEFREQUENCY_WEEKLY, RECURRENCEFREQUENCY_MONTHLY, and RECURRENCEFREQUENCY_YEARLY.
Indicates a monthly recurrence rule for a events reccurance frequency.
Used with the Titanium.Calendar.RecurrenceRule.frequency property.
One of the group of event "frequency" constants RECURRENCEFREQUENCY_DAILY, RECURRENCEFREQUENCY_WEEKLY, RECURRENCEFREQUENCY_MONTHLY, and RECURRENCEFREQUENCY_YEARLY.
Indicates a weekly recurrence rule for a events reccurance frequency.
Used with the Titanium.Calendar.RecurrenceRule.frequency property.
One of the group of event "frequency" constants RECURRENCEFREQUENCY_DAILY, RECURRENCEFREQUENCY_WEEKLY, RECURRENCEFREQUENCY_MONTHLY, and RECURRENCEFREQUENCY_YEARLY.
Indicates a yearly recurrence rule for a events reccurance frequency.
Used with the Titanium.Calendar.RecurrenceRule.frequency property.
One of the group of event "frequency" constants RECURRENCEFREQUENCY_DAILY, RECURRENCEFREQUENCY_WEEKLY, RECURRENCEFREQUENCY_MONTHLY, and RECURRENCEFREQUENCY_YEARLY.
Relationship is attendee.
There is no relationship.
Attendee is organizer.
Attendee is performer.
Attendee is speaker.
Relationship is unknown.
All calendars selected within the native calendar app, which may be a subset of allCalendars.
The native calendar application may know via the registered webservices, such as Gooogle or Facebook accounts about calendars that it has access to but have not been selected to be displayed in the native calendar app.
A birthday calendar source.
A calDev calendar source.
A microsoft exchange calendar source.
A local calendar source.
A mobileMe calendar source.
A subscribed calendar source.
Alert dismissed state.
Used with Titanium.Calendar.Alert.
One of the group of reminder method constants, STATE_DISMISSED, STATE_FIRED, and STATE_SCHEDULED.
Alert fired state.
Used with Titanium.Calendar.Alert.
One of the group of reminder method constants, STATE_DISMISSED, STATE_FIRED, and STATE_SCHEDULED.
Alert scheduled status.
Used with Titanium.Calendar.Alert.
One of the group of reminder method constants, STATE_DISMISSED, STATE_FIRED, and STATE_SCHEDULED.
Event canceled status.
An event's status value.
One of the group of event "status" constants, STATUS_NONE, STATUS_CANCELED, STATUS_CONFIRMED, and STATUS_TENTATIVE.
Event confirmed status.
An event's status value.
One of the group of event "status" constants, STATUS_NONE, STATUS_CANCELED, STATUS_CONFIRMED, and STATUS_TENTATIVE.
Event has no status.
An event's status value.
One of the group of event "status" constants, STATUS_CANCELED, STATUS_CONFIRMED, and STATUS_TENTATIVE.
Event tentative status.
An event's status value.
One of the group of event "status" constants, STATUS_NONE, STATUS_CANCELED, STATUS_CONFIRMED, and STATUS_TENTATIVE.
Event confidential visibility.
Used with Titanium.Calendar.Event.
One of the group of reminder method constants, VISIBILITY_CONFIDENTIAL, VISIBILITY_DEFAULT, VISIBILITY_PRIVATE, and VISIBILITY_PUBLIC.
Event default visibility.
Used with Titanium.Calendar.Event.
One of the group of reminder method constants, VISIBILITY_CONFIDENTIAL, VISIBILITY_DEFAULT, VISIBILITY_PRIVATE, and VISIBILITY_PUBLIC.
Event private visibility.
Used with Titanium.Calendar.Event.
One of the group of reminder method constants, VISIBILITY_CONFIDENTIAL, VISIBILITY_DEFAULT, VISIBILITY_PRIVATE, and VISIBILITY_PUBLIC.
Event public visibility.
Used with Titanium.Calendar.Event.
One of the group of reminder method constants, VISIBILITY_CONFIDENTIAL, VISIBILITY_DEFAULT, VISIBILITY_PRIVATE, and VISIBILITY_PUBLIC.
Methods 7
Inherited from Titanium.Proxy
Adds the specified callback as an event listener for the named event.
| Parameters | Type | Description |
|---|---|---|
| name | String | Name of the event. |
| callback | Callback<Titanium.Event> | Callback function to invoke when the event is fired. 4 fields
|
applyProperties
since 3.0.0Inherited from Titanium.Proxy
Applies the properties to the proxy.
| Parameters | Type | Description |
|---|---|---|
| props | Dictionary | A dictionary of properties to apply. |
Inherited from Titanium.Proxy
Fires a synthesized event to any registered listeners.
| Parameters | Type | Description |
|---|---|---|
| name | String | Name of the event. |
| event? | Dictionary | A dictionary of keys and values to add to the Titanium.Event object sent to the listeners. |
Gets the calendar with the specified identifier.
| Parameters | Type | Description |
|---|---|---|
| id | String | Identifier of the calendar. |
hasCalendarPermissions
since 5.1.0Returns true if the app has calendar access.
Inherited from Titanium.Proxy
Removes the specified callback as an event listener for the named event.
| Parameters | Type | Description |
|---|---|---|
| name | String | Name of the event. |
| callback | Callback<Titanium.Event> | Callback function to remove. Must be the same function passed to 4 fields
|
requestCalendarPermissions
since 5.1.0Requests for calendar access.
On Android, the request view will show if the permission is not accepted by the user, and the user did
not check the box "Never ask again" when denying the request. If the user checks the box "Never ask again,"
the user has to manually enable the permission in device settings. This method requests Manifest.permission.READ_CALENDAR
and Manifest.permission.WRITE_CALENDAR on Android. If you require other permissions, you can also use
Titanium.Android.requestPermissions.
In iOS 6, Apple introduced the Info.plist key NSCalendarsUsageDescription that is used to display an
own description while authorizing calendar permissions. In iOS 10, this key is mandatory and the application
will crash if your app does not include the key. Check the Apple docs for more information.
| Parameters | Type | Description |
|---|---|---|
| callback? | Callback<EventsAuthorizationResponse> | Function to call upon user decision to grant calendar access.
Optional on SDK 10, as this method will return a 3 fields
|
On SDK 10+, this method will return a Promise whose resolved value is equivalent to that passed to the optional callback argument.
Events 1
Fired when the database backing the EventKit module is modified.
This event is fired when changes are made to the Calendar database, including adding, removing, and changing events or reminders. Individual changes are not described. When you receive this notification, you should refetch all Event objects you have accessed, as they are considered stale. If you are actively editing an event and do not wish to refetch it unless it is absolutely necessary to do so, you can call the refresh method on it. If the method returns YES, you do not need to refetch the event.