net.rim.blackberry.api.pim
Interface Event

All Superinterfaces:

PIMItem

All Known Subinterfaces:

BlackBerryEvent

Deprecated. In favour of Event.

public interface Event

extends PIMItem

Represents a PIM event.

While this event object contains support for many different fields, the fields supported by a given instance of an event are detailed in the EventList object containing the event. The event list restricts which fields are retained by an event database. If an event list encounters an event that contains unsupported fields, those fields are dropped.

The method PIMList.isSupportedField(int) is used to determine if a specified field is supported by a list. The method PIMList.getSupportedFields() returns an integer array of all fields supported by a given list.

The fields supported by the Event object define a subset of the fields specified in the vEvent object defined by the vCalendar 1.0 specification from the Internet Mail Consortium (http://www.imc.org).

Data

The following table details the explicitly defined fields that may by in an Event. Implementations may extend the field set using extended fields as defined in PIMItem.

Fields	Type of Data Associated with Field
LOCATION, NOTE, SUMMARY, UID	PIMItem.STRING
END, REVISION, START	PIMItem.DATE
ALARM, CLASS	PIMItem.INT

Working with the Event object

The following examples demonstrate how to use the Event object.

Below, a new Event object is created.

         Event event = events.createEvent();
 

To remove an Event, use the remove method. The following example removes an Event from the calendar.

         events.removeEvent(event);
 

Adding data to an Event

When adding data to an event, you first need to ensure that the field and attribute you are adding are supported by the list. Below, the isSupportedField method is used to return whether or not the specified field is supported.

         if (events.isSupportedField(Event.SUMMARY)) {
                 event.addString(Event.SUMMARY, 0, "Meet with customer");
         }
         if (events.isSupportedField(Event.LOCATION)) {
                 event.addString(Event.LOCATION, 0, "Conference Center");
         }

         long start = System.currentTimeMillis() + 8640000;
         if (events.isSupportedField(Event.START)) {
                 event.addDate(Event.START, 0, start);
         }
         if (events.isSupportedField(Event.END)) {
                 event.addDate(Event.END, 0, start + 72000000);
         }
         if (events.isSupportedField(Event.ALARM)) {
                 event.addDate(Event.ALARM, 0, start - 90000);
         }
 

Above, the start date, location, start, end and alarm are added to the event. Note that each field takes a different data type. An exception will be thrown if an incorrect data type is specified and added to the field.

Creating a recurring event

You can use the RepeatRule object to create a recurring event by allowing you to specify a recurrence pattern for the event. The RepeatRule allows you to specify the frequency, interval and number of recurrences for each event.

Below, a RepeatRule is created and associated with a new event. The event will repeat on the 28th day of every month.

         RepeatRule recurring = new RepeatRule();
         recurring.setInt(RepeatRule.FREQUENCY, RepeatRule.MONTHLY); 
         recurring.setInt(RepeatRule.DAY_IN_MONTH, 28); 
 
         events = EventList.open(EventList.READ_WRITE);
         Event event = events.createEvent();
         event.setRepeat(recurring);
 

Saving an Event object

The commit method must be used to save the object to a list. Below, the isModified method is called to indicate whether or not the event has been modified. If so, the commit method is invoked and the event is saved.

         if(event.isModified()) {
                event.commit();
         }
 

RIM Implementation Notes

Setting the NOTE field to the empty string has the same effect as removing that value.

The ALARM field will automatically be set to 15 minutes on creation of the event.

For more information about this class or about the personal information management (PIM) API, refer to The PDA Profile specification (JSR-000075) for the J2ME(TM) Platform.

Since:

PDAP 1.0

See Also:

PIMItem, EventList

Field Summary

static int	ALARM Deprecated. Represents the date and time of the alarm for this event.
static int	CLASS Deprecated. Field specifying the desired access class for this contact.
static int	CLASS_CONFIDENTIAL Deprecated. Constant indicating this contact's class of access is confidential.
static int	CLASS_PRIVATE Deprecated. Constant indicating this contact's class of access is private.
static int	CLASS_PUBLIC Deprecated. Constant indicating this contact's class of access is public.
static int	END Deprecated. Represents the end date of an event.
static int	LOCATION Deprecated. Represents the location of this event (in string format).
static int	NOTE Deprecated. Represents a note about this event.
static int	REVISION Deprecated. Represents the date and time that this event's information was last modified.
static int	START Deprecated. Represents the start date of an event.
static int	SUMMARY Deprecated. Represents the summary for this event.
static int	UID Deprecated. Represents an event's unique ID.

Fields inherited from interface net.rim.blackberry.api.pim.PIMItem

ATTR_NONE, BINARY, BOOLEAN, DATE, EXTENDED_ATTRIBUTE_MIN_VALUE, EXTENDED_FIELD_MIN_VALUE, INT, STRING, STRING_ARRAY

Method Summary

RepeatRule	getRepeat() Deprecated. Returns a RepeatRule object specifying how often and when this event occurs.
void	setRepeat(RepeatRule value) Deprecated. Sets the RepeatRule specifying how often and when this event occurs.

Methods inherited from interface net.rim.blackberry.api.pim.PIMItem

addBinary, addBoolean, addDate, addInt, addString, addStringArray, addToCategory, commit, countValues, getAttributes, getBinary, getBoolean, getCategories, getDate, getFields, getInt, getPIMList, getString, getStringArray, isModified, maxCategories, removeFromCategory, removeValue, setBinary, setBoolean, setDate, setInt, setString, setStringArray

Field Detail

ALARM

public static final int ALARM

Deprecated.

Represents the date and time of the alarm for this event.

Since:

JDE 3.6.0

CLASS

public static final int CLASS

Deprecated.

Field specifying the desired access class for this contact. Data associated with this field is of int type, and can be one of the values CLASS_PRIVATE, CLASS_PUBLIC, or CLASS_CONFIDENTIAL.

Since:

JDE 3.6.0

END

public static final int END

Deprecated.

Represents the end date of an event.

The end date is inclusive. An all day event is indicated when the start date and end date are equal.

Since:

JDE 3.6.0

LOCATION

public static final int LOCATION

Deprecated.

Represents the location of this event (in string format).

Since:

JDE 3.6.0

NOTE

public static final int NOTE

Deprecated.

Represents a note about this event.

The note field contains further details about the event.

Since:

JDE 3.6.0

REVISION

public static final int REVISION

Deprecated.

Represents the date and time that this event's information was last modified.

Since:

JDE 3.6.0

START

public static final int START

Deprecated.

Represents the start date of an event.

The start date is inclusive. An all day event is indicated when the start date and end date are equal.

Since:

JDE 3.6.0

SUMMARY

public static final int SUMMARY

Deprecated.

Represents the summary for this event.

The summary contains information, such as a title, or details, about this event.

Since:

JDE 3.6.0

UID

public static final int UID

Deprecated.

Represents an event's unique ID.

The unique ID field is valid only if the event has been added to an EventList atleast once in the past. If the Event has not yet been added to a list, the UID returns Null.

Since:

JDE 3.6.0

CLASS_CONFIDENTIAL

public static final int CLASS_CONFIDENTIAL

Deprecated.

Constant indicating this contact's class of access is confidential.

Since:

JDE 3.6.0

CLASS_PRIVATE

public static final int CLASS_PRIVATE

Deprecated.

Constant indicating this contact's class of access is private.

Since:

JDE 3.6.0

CLASS_PUBLIC

public static final int CLASS_PUBLIC

Deprecated.

Constant indicating this contact's class of access is public.

Since:

JDE 3.6.0

Method Detail

getRepeat

public RepeatRule getRepeat()

Deprecated.

Returns a RepeatRule object specifying how often and when this event occurs.

Returns:

The RepeatRule object describing how often this Event occurs or null if a RepeatRule has not been set.

Since:

JDE 3.6.0

See Also:

setRepeat(net.rim.blackberry.api.pim.RepeatRule)

setRepeat

public void setRepeat(RepeatRule value)

Deprecated.

Sets the RepeatRule specifying how often and when this event occurs.

Parameters:

value - A RepeatRule object describing how often this Event occurs or null to clear any RepeatRule.

Since:

JDE 4.0.2

See Also:

getRepeat()