javax.microedition.pim
Interface ToDoList

All Superinterfaces:

PIMList

All Known Subinterfaces:

BlackBerryToDoList

public interface ToDoList
extends PIMList

Represents a ToDo list containing ToDo items.

A ToDo List is responsible for determining which of the fields from a ToDo are retained when a ToDo is persisted into the List. A ToDo List does not have to retain all of the fields in a ToDo when the ToDo is persisted into the List. See the ToDo interface for a description of the fields available for a specific ToDo. The fields that are supported by a particular ToDo List can be queried through the method PIMList.isSupportedField(int). If a field ID that is not in the ToDo interface is provided as the parameter to the PIMList.isSupportedField(int) method, a IllegalArgumentException is thrown.

Inherited Method Behavior

A ToDoList only accepts objects implementing the ToDo interface as a parameter to PIMList.items(PIMItem). A IllegalArgumentException is thrown by this method if the input parameter does not implement the ToDo interface.

Enumerations returned by PIMList.items(), PIMList.items(PIMItem), and ToDoList.items(int, long, long) contain only objects implementing a ToDo interface.

RIM Implementation Notes

The RIM extension functionality for ToDo Lists are defined in BlackBerryToDoList. Any instance of ToDoList that is retrieved from PIM.openPIMList() when specified pimListType==PIM.TODO_LIST will be an instance of BlackBerryToDoList and can be successfully casted to BlackBerryToDoList, if desired, in order to use the RIM extension functionality. When a ToDo object is created by or retrieved from a BlackBerryToDoList then it will necessarily be an instance of BlackBerryToDo and will support all RIM extension fields and attributes defined therein.

The PDA Profile specification (JSR-75) for the J2ME(TM) Platform

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

See Also:

ToDo, BlackBerryToDoList

Since:

BlackBerry API 4.0.0, PIM 1.0

Field Summary

Fields inherited from interface javax.microedition.pim.PIMList

UNCATEGORIZED

Method Summary
ToDo	createToDo() Factory method to create a ToDo for this todo list.
ToDo	importToDo(ToDo todo) Imports the given ToDo into this todo list.
Enumeration	items(int field, long startDate, long endDate) Return an enumeration of all the ToDos in the list where the value of the specified date field falls in the range from startDate to endDate, inclusive.
void	removeToDo(ToDo todo) Removes a ToDo from this list.

Methods inherited from interface javax.microedition.pim.PIMList

addCategory, close, deleteCategory, getArrayElementLabel, getAttributeLabel, getCategories, getFieldDataType, getFieldLabel, getName, getSupportedArrayElements, getSupportedAttributes, getSupportedFields, isCategory, isSupportedArrayElement, isSupportedAttribute, isSupportedField, items, items, items, itemsByCategory, maxCategories, maxValues, renameCategory, stringArraySize

Method Detail

createToDo

ToDo createToDo()

Factory method to create a ToDo for this todo list. The ToDo is empty upon creation with none of its fields containing any data (i.e. a call to the method getFields() returns an array of zero length). Even though it is initially empty, the ToDo is capable of containing data for exactly those fields that this list supports. Note that creation of the ToDo does not add the ToDo to the list from which the item was created; a specific call to PIMItem.commit() must be made to commit the item and its data to the list.

RIM Implementation Note: If the runtime type of this ToDo List is BlackBerryToDoList then the returned ToDo will be an instance of BlackBerryToDo and will support all RIM extension fields and attributes defined in BlackBerryToDo; if desired, the returned ToDo may be casted to BlackBerryToDo to use any RIM extension methods defined there.

Returns:

a new, empty ToDo object associated with this list. However, the ToDo is still not persistent in the list until a call to commit() for the ToDo is made.

See Also:

ToDoList.importToDo(ToDo), ToDoList.removeToDo(ToDo)

Since:

BlackBerry API 4.0.0

importToDo

ToDo importToDo(ToDo todo)

Imports the given ToDo into this todo list. This is done by making a new ToDo for the list and filling its information with as much information as it can from the provided ToDo. If the input ToDo is already in the list, a new ToDo is still created with information similar to the input item (but not necessarily identical).

Note that not all data from the input ToDo may be supported in the new ToDo due to field restrictions for the list instance. In this case, data fields not supported are not transferred to the new ToDo object.

Also note that creation of the ToDo does not add the ToDo to this list; a specific call to PIMItem.commit() must be made to commit the item and its data to the list.

RIM Implementation Note: If the runtime type of this ToDo List is BlackBerryToDoList then the returned ToDo will be an instance of BlackBerryToDo and will support all RIM extension fields and attributes defined in BlackBerryToDo; if desired, the returned ToDo may be casted to BlackBerryToDo to use any RIM extension methods defined there.

Parameters:

todo - the ToDo to import into the list.

Returns:

a newly created ToDo, as described above.

Throws:

NullPointerException - if todo is null.

See Also:

ToDoList.createToDo(), ToDoList.removeToDo(ToDo)

Since:

BlackBerry API 4.0.0

items

Enumeration items(int field,
                  long startDate,
                  long endDate)
                  throws PIMException

Return an enumeration of all the ToDos in the list where the value of the specified date field falls in the range from startDate to endDate, inclusive. The field must have a data type of DATE. The items are in sorted and ascending order from the start date to the end date.

Parameters:

field - the date field on which the matching is based; Must be ToDo.DUE or ToDo.COMPLETION_DATE.

startDate - the inclusive start date to begin looking for todos on or after this date, returned in milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

endDate - the inclusive stop date to end looking for todos beyond this date, returned in milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

Returns:

an enumeration of all the ToDos with specified date field between startDate and endDate

Throws:

IllegalArgumentException - If the data type of the field is not DATE (i.e. PIMList.getFieldDataType(int) for the field does not return PIMItem.DATE), or if endDate is less than startDate.

PIMException - If the operation is unsupported, an error occurs, or is no longer accessible or closed.

SecurityException - if the application is not given permission to write to the ToDo list or the list is opened WRITE_ONLY.

See Also:

PIMList.items(), PIMList.items(PIMItem), PIMList.items(String), PIMList.itemsByCategory(String)

Since:

BlackBerry API 4.0.0

removeToDo

void removeToDo(ToDo todo)
                throws PIMException

Removes a ToDo from this list. The item must already exist in the list for this method to succeed.

Parameters:

todo - the ToDo to be removed from the list.

Throws:

PIMException - If an error occurs removing the item or the list is no longer accessible or closed.

NullPointerException - If todo is null.

SecurityException - if the application is not given permission to write to the ToDo list or the list is opened READ_ONLY.

See Also:

ToDoList.createToDo(), ToDoList.importToDo(ToDo)

Since:

BlackBerry API 4.0.0