javax.microedition.pim
Interface ToDoList

All Superinterfaces:

PIMList

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 java.lang.IllegalArgumentException is thrown.

Inherited Method Behavior

A ToDoList only accepts objects implementing the ToDo interface as a parameter to PIMList.items(PIMItem)). A java.lang.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 items(int, long, long) contain only objects implementing a ToDo interface.

Since:

PIM 1.0

See Also:

ToDo

Field Summary

Fields inherited from interface javax.microedition.pim.PIMList

UNCATEGORIZED

Method Summary

ToDo	createToDo() Factory method to create a ToDo entry for this ToDo list.
ToDo	importToDo(ToDo item) Imports the given ToDo into this list by making a new ToDo for the list and filling its information with as much information as it can from the provided ToDo.
java.util.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 item) Removes a specific ToDo from the 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

public ToDo createToDo()

Factory method to create a ToDo entry 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 ToDo.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.

Returns:

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

importToDo

public ToDo importToDo(ToDo item)

Imports the given ToDo into this list 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 an item of 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.

Parameters:

item - the ToDo to import into the list.

Returns:

a newly created ToDo item.

Throws:

java.lang.NullPointerException - If the input ToDo is null.

removeToDo

public void removeToDo(ToDo item)
                throws PIMException

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

Parameters:

item - the ToDo to be removed from the list.

Throws:

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

java.lang.NullPointerException - If the ToDo is null.

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

items

public java.util.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:

java.lang.IllegalArgumentException - If the data type of the field is not DATE (i.e. PIMList.getFieldDataType() 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.

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