Fork me on GitHub

Calendar

Open the calendar

Import the required classes and interfaces. 

import net.rim.blackberry.api.invoke.CalendarArguments;
import net.rim.blackberry.api.invoke.Invoke;
import net.rim.device.api.system.ControlledAccessException;

Invoke Invoke.invokeApplication(APP_TYPE_CALENDAR, CalendarArguments).

Check for a ControlledAccessException if your application does not have permission to access the application that it invokes.

View or change a calendar entry

Import the required classes and interfaces. 

import java.util.Enumeration;
import javax.microedition.pim.PIM;
import javax.microedition.pim.Event;
import javax.microedition.pim.EventList;
import net.rim.blackberry.api.invoke.CalendarArguments;
import net.rim.blackberry.api.invoke.Invoke;
import net.rim.device.api.system.ControlledAccessException;

Retrieve an Event from the list of events.

Event e = null;
EventList el = 
  (EventList)PIM.getInstance().openPIMList( PIM.EVENT_LIST, PIM.READ_WRITE );
Enumeration events = el.items();
e = (Event)events.nextElement();

Invoke Invoke.invokeApplication(APP_TYPE_CALENDAR, CalendarArguments) using the CalendarArguments object created using the ARG_VIEW_DEFAULT field and the retrieved Event.

Invoke.invokeApplication( Invoke.APP_TYPE_CALENDAR, 
new CalendarArguments( CalendarArguments.ARG_VIEW_DEFAULT, e ) );

Check for a ControlledAccessException if your application does not have permission to access the application that it invokes.

Open a new populated calendar entry

Import the required classes and interfaces. 

import javax.microedition.pim.PIM;
import javax.microedition.pim.Event;
import javax.microedition.pim.EventList;
import net.rim.blackberry.api.invoke.CalendarArguments;
import net.rim.blackberry.api.invoke.Invoke;
import net.rim.device.api.system.ControlledAccessException;

Create a new Event using an EventList object.

EventList el = (EventList)PIM.getInstance().openPIMList(
                    PIM.EVENT_LIST, PIM.READ_WRITE );
Event e = el.createEvent();

Add information to the Event object.

e.addString( Event.SUMMARY, 0, "Go For A Walk" );
e.addString( Event.LOCATION, 0, "The Park" );
long start = System.currentTimeMillis() + 8640000;
e.addDate( Event.START, 0, start );
e.addDate( Event.END, 0, start + 72000000 );

Invoke Invoke.invokeApplication(APP_TYPE_CALENDAR, CalendarArguments) using the CalendarArguments object created using the ARG_NEW field and the Event.

Invoke.invokeApplication(
                   Invoke.APP_TYPE_CALENDAR,
                   new CalendarArguments( CalendarArguments.ARG_NEW, e ) );

Update calendar entry information

Import the required classes and interfaces. 

import java.util.Date;
import javax.microedition.pim.Event;
import javax.microedition.pim.EventList;
import javax.microedition.pim.PIM;
import javax.microedition.pim.RepeatRule;

Invoke openPIMList() to open a list of calendar entries. Provide the following as parameters: the type of list to open (PIM.EVENT_LIST) and the mode in which to open the list:

  • READ_WRITE
  • READ_ONLY
  • WRITE_ONLY 
EventList eventList = null;
try 
{ 
   eventList = (EventList)PIM.getInstance().openPIMList(PIM.EVENT_LIST, 
     PIM.READ_WRITE); 
}
catch (PimException e) 
{
   // Handle exception.
}

To update calendar information, perform any of the following tasks:

Create an appointment:
  • Invoke createEvent() on an event list.
    Event event = eventList.createEvent();
Add appointment information:
  • Invoke Event.isSupportedField(int) to verify that an item supports a field.
    if (event.isSupportedField(Event.SUMMARY)) 
{
  event.addString(Event.SUMMARY, Event.ATTR_NONE, 
  "Meet with customer");
}

if (event.isSupportedField(Event.LOCATION)) 
{
  event.addString(Event.LOCATION, Event.ATTR_NONE, 
  "Conference Center");
}

Date start = new Date(System.currentTimeMillis() + 8640000);

if (event.isSupportedField(Event.START)) 
{
  event.addDate(Event.START, Event.ATTR_NONE, 
    start);
}

if (event.isSupportedField(Event.END)) 
{
  event.addDate(Event.END, Event.ATTR_NONE, start + 
    72000000);
}

if (event.isSupportedField(Event.ALARM)) 
{
  if (event.countValues(Event.ALARM) > 0) 
  {
    event.removeValue(Event.ALARM,0);
    event.setInt(Event.ALARM, 0, Event.ATTR_NONE, 
      396000);
  }
}
Create a recurring appointment:
  • Create a RepeatRule object. The RepeatRule class defines fields for the properties and values that you can set, such as COUNT, FREQUENCY, and INTERVAL.
  • Invoke RepeatRule.getFields() to retrieve an array of supported fields.
  • Invoke RepeatRule.setInt(int, int) or RepeatRule.setDate (int, int, int, long) on a new RepeatRule object to define a recurring pattern.
    RepeatRule recurring = new RepeatRule();
recurring.setInt(RepeatRule.FREQUENCY, 
  RepeatRule.MONTHLY);
recurring.setInt(RepeatRule.DAY_IN_MONTH, 14);
  • Invoke Event.setRepeat(RepeatRule) on an event to assign a recurrence pattern to an appointment.
    EventList eventList = 
  (EventList)PIM.getInstance().openPIMList
  (PIM.EVENT_LIST, PIM.READ_WRITE);
Event event = eventList.createEvent();
event.setRepeat(recurring);
Change appointment information:
  • Invoke the appropriate set method, such as setString() to replace an existing value with a new one.
  • Invoke Event.countValues() to determine if a value is already set for the field.
  • Use the corresponding set method, such as setString() to change an existing value.
    if (event.countValues(Event.LOCATION) > 0) 
{
  event.setString(Event.LOCATION, 0, 
  Event.ATTR_NONE, "Board Room");
}
Save an appointment:
  • Before you save the appointment, to identify appointment fields that have changed since the appointment was last saved, invoke Event.isModified().
  • Invoke Event.commit().
    if(event.isModified()) 
{
  event.commit();
}

Retrieve calendar entry information

Import the required classes and interfaces. 

javax.microedition.pim.Event
javax.microedition.pim.EventList
javax.microedition.pim.PIM

Invoke EventList.items() to retrieve an enumeration of appointments.

EventList eventList = 
  (EventList)PIM.getInstance().openPIMList(PIM.EVENT_LIST,
                                           PIM.READ_ONLY); 
Enumeration e = eventList.items();

Invoke PIMItem.getFields() to retrieve an array of IDs of fields that have data for a particular task. Invoke PIMItem.getString() to retrieve the field values. 

while (e.hasMoreElements()) 
{
   Event event = (Event)e.nextElement();
   int[] fieldIds = event.getFields();
   int id;
   for(int index = 0; index < fieldIds.length; ++index) 
   {
      id = fieldIds[index];
      if(e.getPIMList().getFieldDataType(id) == STRING) 
      {
         for(int j=0; j < event.countValues(id); ++j) 
         {
            String value = event.getString(id, j);
            System.out.println(event.getFieldLable(id) + "=" + value);
         }
      }
   }
}

Export a calendar entry

Import the required classes and interfaces. 

import java.io.ByteArrayOutputStream;
import java.util.Enumeration;
import javax.microedition.pim.Event;
import javax.microedition.pim.EventList;
import javax.microedition.pim.PIM;

Invoke PIM.supportedSerialFormats() specifying the list type (PIM.EVENT_LIST), to retrieve a string array of supported serial formats.

String[] dataFormats = PIM.supportedSerialFormats(PIM.EVENT_LIST);

Use an output stream writer to export calendar entries from the BlackBerry device to a supported serial format, such as iCal.

Invoke toSerialFormat() to write an item in serial format. The enc parameter specifies the character encoding to use when writing to the output stream. Supported character encodings include “UTF8,” “ISO-8859-1,” and “UTF-16BE”. This parameter cannot be null.

EventList eventList = 
   (EventList)PIM.getInstance().openPIMList( PIM.EVENT_LIST, PIM.READ_ONLY );
ByteArrayOutputStream bytestream = new ByteArrayOutputStream();
Enumeration e = eventList.items();
while (e.hasMoreElements()) 
{
   Event event = (Event)e.nextElement();
   PIM.getInstance().toSerialFormat(event, bytestream, "UTF8", dataFormats[0]);
}

Import a calendar entry

Import the required classes and interfaces. 

import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import javax.microedition.pim.Event;
import javax.microedition.pim.EventList;
import javax.microedition.pim.PIM;

Invoke PIM.getInstance().fromSerialFormat() to return an array of PIMItem objects.

Invoke EventList.importEvent() to add a new calendar entry.

//Convert an existing entry into a iCal and then 
//import the iCal as a new entry
String[] dataFormats = PIM.supportedSerialFormats();

//Write entry to iCal
ByteArrayOutputStream os = new ByteArrayOutputStream();
PIM.getInstance().toSerialFormat(event, os, "UTF8", dataFormats[0]);

//Import entry from iCal
ByteArrayInputStream is = new ByteArrayInputStream(os.toByteArray());
PIMItem[] pi = PIM.getInstance().fromSerialFormat(is, "UTF8");
EventList eventList = 
   (EventList)PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE);
Event event2 = eventList.importEvent((Event)pi[0]);

Retrieve multiple lists of calendar entries

The first element in the array of lists is the default list.

Import the javax.microedition.pim.PIM class.

Invoke PIM.listPIMLists(int pimListType).

String[] allLists = PIM.listPIMLists(PIM.EVENT_LIST);

Notify a BlackBerry device application when a list of calendar entries changes

Import the required classes and interfaces. 

import javax.microedition.pim.EventList;
import javax.microedition.pim.PIM;
import net.rim.blackberry.api.pdap.BlackBerryPIMList;
import net.rim.blackberry.api.pdap.PIMListListener;

Implement the PIMListListener interface.

public class MyEventListListener implements PIMListListener {...}

Invoke BlackBerryPIMList.addListener() to register to receive notifications of changes to a list of calendar entries.

BlackBerryPIMList eventList = 
    (BlackBerryPIMList)PIM.getInstance().openPIMList(PIM.EVENT_LIST, 
                                                     PIM.READ_WRITE);
eventList.addListener(new MyEventListListener());

Notify a BlackBerry device application when the default list of calendar entries changes

When an update occurs to the list of services on a BlackBerry device, the list of PIM databases on a device may change. This action may result in the creation of a new default list of calendar entries.

Import the required classes and interfaces. 

import javax.microedition.pim.PIM;
import net.rim.blackberry.api.pdap.BlackBerryPIM;
import net.rim.blackberry.api.pdap.ListChangeListener;

Implement the ListChangeListener interface.

public class MyListChangeListener implements ListChangeListener {...}

Invoke BlackBerryPIM.addListChangeListener() to register to receive notifications of changes to a default PIM list.

ListChangeListener listener = new MyListChangeListener();
((BlackBerryPIM) PIM.getInstance()).addListChangeListener(listener);

To have the application always use the default PIMList, store a reference to the desired PIMList and design the ListChangeListener.defaultListChanged() method to update the reference when the default list changes.

Update a calendar entry with no notification

You can update a calendar entry on a BlackBerry device without sending notifications to the entry's participants.

Import the required classes and interfaces. 

import java.util.*;
import javax.microedition.pim.*;
import net.rim.blackberry.api.pdap.BlackBerryEvent;
import net.rim.blackberry.api.pdap.BlackBerryEventList;
import net.rim.blackberry.api.pdap.BlackBerryPIMItem;

Invoke PIM.openPIMList() to open a list of calendar entries as a BlackBerryEventList object. 

BlackBerryEventList eventList = null;
try 
{ 
   eventList = (BlackBerryEventList) 
      PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE); 
}
catch (PIMException e) 
{
   // Handle exception
}

Retrieve a BlackBerryEvent object from the list of entries.

Enumeration events = eventList.items();
BlackBerryEvent event = (BlackBerryEvent) events.nextElement();

Modify the entry. 

if (eventList.isSupportedField(Event.SUMMARY)) 
{
   event.addString(Event.NOTE, Event.ATTR_NONE, "Remember to bring food");
}

Invoke BlackBerryPIMItem.commit() and specify the flag BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES to save your changes. 

if(event.isModified()) 
{
   try
   {
      int result;
      result = 
       ((BlackBerryPIMItem) event).commit(BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES);
   }
   catch (PIMException e) 
   {
      // Handle exception
   }
}

If you specify BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES when committing changes to a calendar entry, notification is not sent unless the calendar entry is a new meeting or meeting participants have been added since the last update (meeting participants must be notified about the meeting in order to accept the meeting invitation). If notification was sent, BlackBerryPIMItem.commit() returns BlackBerryEvent.MEETING_RECORD_NOT_FOUND or BlackBerryEvent.INVITEE_LIST_CHANGED. 

BlackBerryEventList eventList = null;
try 
{ 
   eventList = (BlackBerryEventList) 
      PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE); 

   Enumeration events = eventList.items();
   BlackBerryEvent event = (BlackBerryEvent) events.nextElement();
               
   if (eventList.isSupportedField(Event.SUMMARY)) 
   {
      event.addString(Event.NOTE, Event.ATTR_NONE, "Remember to bring food");
   }
               
   if(event.isModified()) 
   {
      int result;
      result = 
         ((BlackBerryPIMItem) event).commit(BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES);
   }
}
catch (PIMException e) 
{
   // Handle exception
}

Remove a calendar entry with no notification

You can remove a calendar entry on a BlackBerry device without sending notifications to the entry's participants.

Import the required classes and interfaces.

import java.util.*;
import javax.microedition.pim.*;
import net.rim.blackberry.api.pdap.BlackBerryEvent;
import net.rim.blackberry.api.pdap.BlackBerryEventList;

Invoke PIM.openPIMList() to open a list of calendar entries as a BlackBerryEventList object. 

BlackBerryEventList eventList = null;
try 
{ 
   eventList = (BlackBerryEventList) 
      PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE); 
}
catch (PIMException e) 
{
   // Handle exception
}

Retrieve a BlackBerryEvent object from the list of entries. 

Enumeration events = eventList.items();
BlackBerryEvent event = (BlackBerryEvent) events.nextElement();

Invoke BlackBerryEventList.removeElement() and specify the flag BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES to remove the entry without notification. 

try
{
   eventList.removeEvent(event, BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES);
}
catch (PIMException e)
{
   // handle exception
{
If an error occurs when you try to remove the event, the method throws a PIMException. 
BlackBerryEventList eventList = null;
try 
{ 
   eventList = (BlackBerryEventList) 
      PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE); 

   Enumeration events = eventList.items();
   BlackBerryEvent event = (BlackBerryEvent) events.nextElement();

   eventList.removeEvent(event, BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES);           
}
catch (PIMException e) 
{
   // Handle exception
}