Android devices with the stock Google experience have had a Calendar application installed since the early days of Android. However, third-party developers had no official way to access the user’s calendar as they did contacts and other user data. Developers who wanted to access the calendaring features were forced to use unofficial means of doing so, as we discussed in Working with the Android Calendar (December 2009).
Android 4.0 (Ice Cream Sandwich) introduced official means of accessing the Android calendar. Although the actual code changes needed are minimal compared to how people have been doing it all along, this represents a pretty significant improvement to the Android SDK for two reasons. First, this means that user calendar access is standardized and widely supported and second, it means that developers who wanted to include calendaring support in their applications but didn’t want to use a hack can now use these features with a much higher degree of comfort.
Working with Calendars on the Android Platform
The CalendarContract content provider was added to the Android SDK in API Level 14. This set of APIs allows third party developers to access and manipulate user calendar data, provided the user has configured a calendaring application on the device. Users may have no calendaring support configured, or they may have multiple calendar instances (Work vs. Play).
Android app developers who need only lightweight calendaring features in their applications may be able to get away with using the simple calendaring intents for creating, viewing and editing calendar entries. These intents require no special permissions to use because the user must commit the transactions. Developers that require deeper access to the calendaring data will need to make sure their apps have the appropriate calendaring permissions when they access the CalendarContract content provider in order to query and modify user calendars, events, attendee information, reminders and more.
Creating New Events in Android User’s Calendar via Intent
A common calendaring feature that third party developers often want to leverage is the ability to create new events in the user’s calendar. With the new Android calendaring APIs available in API Level 14 and higher, creating new calendar events is straightforward, as it is done by Intent. This mechanism requires no special permissions because it simply seeds a new calendar entry with developer-supplied fields and the user must save the entry themselves.
Intent calIntent = new Intent(Intent.ACTION_INSERT);
calIntent.setData(CalendarContract.Events.CONTENT_URI);
startActivity(calIntent);If you just did this, the user would be prompted with a blank new calendar event screen. They would have to fill in all the details themselves. However, you can help them along by seeding some of the fields for them via Intent extras. There are extras for all sorts of typical calendaring options, like Free/Busy, event privacy settings, all day events vs. time-duration events, and more.
For example, let’s say we wanted to hang out at the bar next to the Moscone Convention Center in San Francisco after Google I/O and shoot the breeze. The following intent supplies some title, description, and time information about such an event:
Intent calIntent = new Intent(Intent.ACTION_INSERT);
calIntent.setData(Events.CONTENT_URI);
calIntent.putExtra(Events.TITLE, "Google IO Afterparty");
calIntent.putExtra(Events.EVENT_LOCATION, "The W Hotel Bar on Third Street");
calIntent.putExtra(Events.DESCRIPTION, "Hang out after Google IO for a drink and geeky conversation.");
Calendar startTime = Calendar.getInstance();
startTime.set(2012, 5, 29, 18, 0);
Calendar endTime = Calendar.getInstance();
endTime.set(2012, 5, 29, 22, 30);
calIntent.putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME,
startTime.getTimeInMillis());
calIntent.putExtra(CalendarContract.EXTRA_EVENT_END_TIME,
endTime.getTimeInMillis());
startActivity(calIntent);Note that this Intent will only work seamlessly if the user has configured the Calendar application, much like intents that send emails only work if the user has a configured email client installed on the device. Therefore, make sure your application handles the situation in which the user has not set up their calendar gracefully. Once this Intent is launched, the user will be presented with a confirmation screen, much like the following, where they can also edit details as they see fit. Inserting into the calendar this way does not require any special permissions in your application’s manifest file.
Inserting items into the calendar via Intent is simple, yet limiting. Only a few fields are supported beyond what we’ve shown, and these include email address of guests, recurrence rules, whether the entry is private or not, and whether the entry should mark the time as busy or not. Not even the time zone can be controlled directly; it’s up to the user to change it if the event not in their local time.
Exploring the Android Calendar Content Provider
If your application needs more sophisticated calendaring support, then you’re going to need to use the CalendarContract content provider. This content provider allows fine-grained access to the users calendars (there may be several). You can use this content provider to search for existing events, as well as insert, update, and delete events as well as configure calendar settings, attendee details, time zone, and reminders. In order to work with the CalendarContract content provider, your application must have the appropriate permissions, like READ_CALENDAR and WRITE_CALENDAR.
For more information on the calendaring content provider on Android, check out the developer documentation for android.provider.CalendarContract.
Supporting Older Android Devices
Unfortunately, this Calendaring APIs are not backwards compatible with older versions of the platform (prior to Android 4.0, or API Level 14). These features are not part of the latest Support Package, and we are not expecting to see it in a future revision. If your application must attempt to work with calendars on older platform versions, see our other article about unofficial access to the user’s calendar (Working with the Android Calendar, December 2009), but understand you are not following Android best practices by using it. That being said, the difference is surprisingly minimal. Effectively, the CalendarContract documented the previously undocumented APIs. Some values changed, but creating a compatibility interface to work with the old version and the new version may possible for those that require it. There are older handsets where the undocumented method will not work, however, so the solution is still not perfect.
Conclusion
In Android 4.0 and higher, app developers now have access to the user’s calendar information through an official set of APIs. Specifically, there is a fully-featured CalendarContract content provider as well as easy-to-use intents for common calendaring tasks like adding events to the calendar. To support older devices, your only option right now is to use unofficial, undocumented APIs.
