SHOW Signed

net.rim.blackberry.api.pim
Interface Event

All Superinterfaces:

PIMItem

public interface Event

extends PIMItem

Represents an Event entry in a PIM Event database.

While the Event object contains support for many different fields, the fields supported by a given instance of an Event object are defined in the EventList object associated with the event. The EventList restricts which fields are retained by an event database. If an EventList encounters an Event object 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).

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 (event.isSupportedField(Event.SUMMARY)) {
                 event.addString(Event.SUMMARY, 0, "Meet with customer");
         }
         if (event.isSupportedField(Event.LOCATION)) {
                 event.addString(Event.LOCATION, 0, "Conference Center");
         }

         Date start = new Date(System.currentTimeMillis() + 8640000);
         if (event.isSupportedField(Event.START)) {
                 event.addDate(Event.START, 0, start);
         }
         if (event.isSupportedField(Event.END)) {
                 event.addDate(Event.END, 0, start + 72000000);
         }
         if (event.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.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Since:

PDAP 1.0

See Also:

PIMItem, EventList

Field Summary

	static int	ALARM Represents the date and time of the alarm for this event.
	static int	CLASS Field specifying the desired access class for this contact.
	static int	CLASS_CONFIDENTIAL Constant indicating this contact's class of access is confidential.
	static int	CLASS_PRIVATE Constant indicating this contact's class of access is private.
	static int	CLASS_PUBLIC Constant indicating this contact's class of access is public.
	static int	END Represents the end date of an event.
	static int	LOCATION Represents the location of this event (in string format).
	static int	NOTE Represents a note about this event.
	static int	REVISION Represents the date and time that this event's information was last modified.
	static int	START Represents the start date of an event.
	static int	SUMMARY Represents the summary for this event.
	static int	UID 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() Returns a RepeatRule object specifying how often and when this event occurs.
	void	setRepeat(RepeatRule value) 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

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

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

CLASS

public static final int CLASS

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.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

END

public static final int END

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.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

LOCATION

public static final int LOCATION

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

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

NOTE

public static final int NOTE

Represents a note about this event.

The note field contains further details about the event.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

REVISION

public static final int REVISION

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

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

START

public static final int START

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.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

SUMMARY

public static final int SUMMARY

Represents the summary for this event.

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

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

UID

public static final int UID

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.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

CLASS_CONFIDENTIAL

public static final int CLASS_CONFIDENTIAL

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

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

CLASS_PRIVATE

public static final int CLASS_PRIVATE

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

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

CLASS_PUBLIC

public static final int CLASS_PUBLIC

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

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Method Detail

getRepeat

public RepeatRule getRepeat()

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.

See Also:

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

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

setRepeat

public void setRepeat(RepeatRule value)

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 3.6

See Also:

getRepeat()

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.