Android Essentials: Adding Events to the User’s Calendar

The latest version of the Android SDK, code-named Ice Cream Sandwich, reached developers this week. For the first time, the SDK provides access to the Calendar application in a legitimate fashion. One of the most common tasks that developers often want to be able to do is create new events in the user’s calendar, so today we’ll show you how.

The Calendar is a common application that users rely upon on their Android devices. Applications can access the Calendar using the new APIs available in Android 4.0. Adding new events to the Calendar is simple and requires no special application permissions.

Note: The user is responsible for configuring the Calendar application with the appropriate Calendar accounts (e.g. Microsoft Exchange).

Step 0: Getting Started

This tutorial assumes you have a project that supports Android 4.0 (API Level 14 compatible) and that you are compiling with the latest tools. It also assumes that you’ve properly configured the Calendar application on the Android emulator (or a suitable device, when one becomes available in the coming weeks).

Step 1: Create the Calendar Intent

In order to prompt the user to create a calendar event in their existing calendar, you’ll need to create the appropriate intent. This intent will launch the Calendar application with a screen that allows them to create a new event. The user must confirm this event and can add or change any of the event data associated with the event.

The intent to create a calendar event is shown below:

Intent calIntent = new Intent(Intent.ACTION_INSERT); 
calIntent.setData(CalendarContract.Events.CONTENT_URI);
startActivity(calIntent);

This code simply launches the intent. It does not set any of the calendar data associated with the event.

Step 2: Seeding Calendar Details

You can seed the information associated with a calendar event by supplying a number of intent extras. Extras can be used to describe event details, the date and time of the event, as well as calendar event settings like whether the event can be seen by others and whether it is busy or available time. The typical calendar event settings are all available as Extras. For example, the following intent call supplies some title and description information about an event:

Intent calIntent = new Intent(Intent.ACTION_INSERT); 
calIntent.setType("vnd.android.cursor.item/event");    
calIntent.putExtra(Events.TITLE, "My House Party"); 
calIntent.putExtra(Events.EVENT_LOCATION, "My Beach House"); 
calIntent.putExtra(Events.DESCRIPTION, "A Pig Roast on the Beach"); 
startActivity(calIntent);

Here we set the title, location, and description access for the event using the appropriate intent Extras. These fields will be set in a form that displays for the user to confirm the event in their calendar.

Step 3: Seeding Calendar Dates and Times

Calendar events are associated with specific dates and times. Some events have a specific time window and others are “all day” events. You can specify the date and time of an event using extras as well.

Intent calIntent = new Intent(Intent.ACTION_INSERT); 
calIntent.setType("vnd.android.cursor.item/event");    
calIntent.putExtra(Events.TITLE, "My House Party"); 
calIntent.putExtra(Events.EVENT_LOCATION, "My Beach House"); 
calIntent.putExtra(Events.DESCRIPTION, "A Pig Roast on the Beach"); 

GregorianCalendar calDate = new GregorianCalendar(2012, 7, 15);
calIntent.putExtra(CalendarContract.EXTRA_EVENT_ALL_DAY, true); 
calIntent.putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, 
     calDate.getTimeInMillis()); 
calIntent.putExtra(CalendarContract.EXTRA_EVENT_END_TIME, 
     calDate.getTimeInMillis()); 

startActivity(calIntent);

Here we set the event to be an all day event on a specific date. You can also set much more fine-grained events by simply using the two extras for the beginning and ending time.

Step 4: Event Configuration Details

There are several other intent extras you can seed as well. These include whether or not others can see the event (access level) and whether or not the time should be shown as busy or available (availability)

You could set these extras as follows:

calIntent.putExtra(Events.ACCESS_LEVEL, Events.ACCESS_PRIVATE); 
calIntent.putExtra(Events.AVAILABILITY, Events.AVAILABILITY_BUSY

Here we include an extra setting to set the access of this event in the calendar to private. We set the availability during the event’s time period to busy (no other events can overlap).

Step 5: Configuring Recurring Events

There are one-time events, like our pig roast, and then there are recurring events, like by-weekly meetings. You can seed the recurrence rule using an intent extra, like this:

calIntent.putExtra(Events.RRULE, “FREQ=WEEKLY;COUNT=10;WKST=SU;BYDAY=TU,TH”);

The RRULE intent extra takes a standard iCalendar recurrence rule format (see RFC 5544 for details). For example, the one above creates a recurrence rule for an event that occurs every Tuesday and Thursday for 5 weeks.

Conclusion

The Calendar application has been available on the Android platform for a long time, but there have been no documented APIs for accessing it: until now. Android 4.0 (API Level 14) includes a full Calendar content provider which can be used to access the user’s calendar information, provided the application has the appropriate permissions. However, one of the simplest and most common tasks, adding a new event to a user’s calendar, requires no special permissions and is very easy to implement.

About the Authors

Mobile developers Lauren Darcey and Shane Conder have coauthored several books on Android development: an in-depth programming book entitled Android Wireless Application Development and Sams Teach Yourself Android Application Development in 24 Hours. When not writing, they spend their time developing mobile software at their company and providing consulting services. They can be reached at via email to [email protected], via their blog at androidbook.blogspot.com, and on Twitter @androidwireless.

HIGHLIGHTS OF THE DAY