PDAP Public Review Draft

javax.microedition.pim
Interface ToDo

All Superinterfaces:
PIMElement

public interface ToDo
extends PIMElement

Represents a single To Do item in a PIM To Do database. The fields are a subset of the fields in VTODO defined by the vCalendar 1.0 specification from the Internet Mail Consortium (http://www.imc.org). The subset represents those fields necessary to provide enough information about a ToDo item without compromising platform portability.

The ToDo class has many different field IDs that it can support. However, each individual ToDo object supports only fields valid for its associated list. Its ToDoList restricts what fields in a ToDo are retained. This reflects that some native ToDo databases do not support all of the fields available in a ToDo element. The methods PIMList.isSupportedField(int) and PIMList.getSupportedTypes(int) can be used to determine if a particular ToDo field is supported by a ToDoList and therefore persisted when the ToDo is committed to its list. Attempts to set or get data based on field IDs not supported in the ToDo's ToDoList result in a PIMException.

Data

An event contains three types of data:

Named fields are items that are referenced by the explicit field names defined in this class. Named fields appear only once in a single ToDo entry. The data items for fields are only retrieved and set by the get/set methods corresponding to the type of the data associated with the named field (e.g. PIMElement.getString(int) and PIMElement.setString(int, String) are used for ToDo.NOTE since a String value is associated with notes).

Extended fields are fields that does not have a specific field explicitly predefined in the API, but do have field ids assigned by the ToDo list. These fields are implementation dependent and can vary. Users can find out a field id is is extended field through the method PIMList.isExtendedField(int). Users can also find out the data type for the field (PIMElement.getFieldDataType(int)) and the human readable label for the field (PIMElement.getFieldLabel(int)). Extended fields use the same get and set methods as named fields.

Categories are string items. There is no limit to the number of categories that a ToDo can be associated with.

Table: Named Fields

Field IDs Type of Data Associated with Field
NOTE, SUMMARY, UID PIMElement.STRING
PRIORITY PIMElement.INT
COMPLETED, DUE, REVISION PIMElement.DATE

Required Field Support

SUMMARY is the only field that is required to be supported in a ToDo and its List. All other fields may or may not be required by the list. Support for all fields can be determined by the method PIMList.isSupportedField(int).

Inherited Method Behavior

Examples

  ToDoList todoList = null;
  try {
  	todoList = PIM.openToDoList(PIM.READ_WRITE);
  } catch (PIMException e) {
  	// An error occured
  	return;
  }
  
  ToDo todo = todoList.createToDo();
  todo.setString(ToDo.SUMMARY, "Buy going away present for Judy");
  todo.setDate(ToDo.DUE, new Date().getTime());
  todo.setString(ToDo.NOTE, "Judy really likes stained glass and expensive pens");
  todo.setInt(ToDo.PRIORITY, 2);
  // Add a category to this todo
  todo.addToCategory("Work");
  try {
  	todo.commit();
  } catch (PIMException e) {
  	// An error occured
  }
  try {
  	todoList.close();
  } catch (PIMException e) {
  }
 

Since:
PDAP 1.0
See Also:
http://www.imc.org/pdi/pdiproddev.html, ToDoList

Field Summary
static int COMPLETED
          Field ID indicating a ToDo has been completed.
static int DUE
          The Date a ToDo is due.
static int NOTE
          Field ID specifying a more complete description than the SUMMARY for this ToDo.
static int PRIORITY
          Field ID specifying the priority of this ToDo.
static int REVISION
          Field ID specifying the last modification date and time of a ToDo element.
static int SUMMARY
          Field ID specifying the summary or subject for this ToDo.
static int UID
          Field ID specifying a unique ID for a ToDo.
 
Fields inherited from interface javax.microedition.pim.PIMElement
BINARY, DATE, INT, STRING, TYPED_STRING
 
Methods inherited from interface javax.microedition.pim.PIMElement
addToCategory, commit, fromSerialFormat, getBinary, getCategories, getDate, getFieldDataType, getFieldLabel, getFields, getInt, getPIMList, getString, getTypedString, isModified, maxCategories, removeFromCategory, setBinary, setDate, setInt, setString, setTypedString, supportedSerialVersions, toSerialFormat, toSerialFormat
 

Field Detail

DUE

public static final int DUE
The Date a ToDo is due.

Value 1 is assigned to DUE.


COMPLETED

public static final int COMPLETED
Field ID indicating a ToDo has been completed.

Value 2 is assigned to COMPLETED.


SUMMARY

public static final int SUMMARY
Field ID specifying the summary or subject for this ToDo. For example:
"Buy going away present for Judy"

Value 3 is assigned to SUMMARY.


NOTE

public static final int NOTE
Field ID specifying a more complete description than the SUMMARY for this ToDo. For example:
"Judy really likes stained glass and expensive pens"

Value 4 is assigned to NOTE.


PRIORITY

public static final int PRIORITY
Field ID specifying the priority of this ToDo. The priority is a value from zero to nine. Zero specifies an undefined priority, one specifies the highest priority and nine the lowest priority. It is not guaranteed that this value remains unchanged after setting the value and/or persistence of the ToDo element due to underlying native database priority support and mappings to the native priority values.

Value 5 is assigned to PRIORITY.


UID

public static final int UID
Field ID specifying a unique ID for a ToDo. Two ToDos on a specific implemention can use this field to check for identity. This is a read only attribute. The UID is valid only after the ToDo is added to an ToDo list and is valid for the persistent life of the ToDo. Once the ToDo is deleted from the list, the UID may be reused for other ToDo entries. getString(UID) returns null before the event object is added to a list.

Value 6 is assigned to UID.


REVISION

public static final int REVISION
Field ID specifying the last modification date and time of a ToDo element. This field cannot be set through the API (e.g. is read-only). This field is set automatically on adds and updates of a ToDo.

Value 7 is assigned to REVISION.


PDAP 1.0 Spec, Rev. 0.16