Represents a single ToDo item in a PIM ToDo database.
While the ToDo object contains support for many different fields, the
fields supported by a given instance of a Todo object are
defined in the ToDoList object associated with the
contact. The ToDoList restricts which fields are retained by
a ToDo database. If a ToDoList encounters a
ToDo object that contains unsupported fields, those fields
are dropped.
The summary field is the only field that is guaranteed
to be supported. The PIMList.isSupportedField(int) is invoked to determine if a field
(as specified by the integer argument) is supported by a
ToDoList. Similarly, the PIMList.getSupportedAttributes(int) method is invoked to return an integer
array representing all fields supported by the list.
Working with the ToDo object
The following examples demonstrate how to use the ToDo object.
Below, a new task is created and given the category "Work".
try {
ToDo todoItem = todoList.createToDo();
contact.addToCategory("Work");
} catch(PIMException e) {
// ToDo could not be created
}
To delete the the ToDo from the list, use the
remove method.
todoList.removeToDo(todoItem);
Adding data to a ToDo object
When adding data to a ToDo, 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 the specified field is supported the data will be added to
the contact.
Below, a summary, due date, and priority are given to the ToDo object. 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.
if (todoItem.isSupportedField(ToDo.SUMMARY)) {
todoItem.addString(ToDo.SUMMARY, 0, "Create project plan");
}
if (todoItem.isSupportedField(ToDo.DUE)) {
Date date = new Date();
todoItem.addDate(ToDo.DUE, 0, (date + 17280000));
}
if (todoItem.isSupportedField(ToDo.PRIORITY)) {
todo.addInt(Todo.PRIORITY, 0, 2);
}
Updating data in an existing ToDo
The previous example added new data to an empty field.
Since you can not add data to a field that already contains data,
the countValues method is invoked to determine if the
field is not empty, and the removeValue method is used to remove the data from the field.
if (ToDoItem.countValues() > 0) {
ToDoItem.removeValue(ToDo.NOTE, 0);
}
todo.addString(ToDo.NOTE, 0, "Meeting to begin at noon");
Above, the countValues and removeValue methods are
called before the task's note field value is modified using the
addString method.
Saving a ToDo 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 ToDo's information has been modified. If so, the
commit method is invoked and the task is saved.
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.
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.
COMPLETED
public static final int COMPLETED
Represents whether or not a ToDo has been completed.
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.
COMPLETION_DATE
public static final int COMPLETION_DATE
Represents the completion date for a ToDo. (i.e. the date on which the
ToDo was completed)
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.
DUE
public static final int DUE
Represents the due date of the ToDo.
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 the ToDo.
A note is used to store additional information about the ToDo.
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.
PRIORITY
public static final int PRIORITY
Represents the priority level of the ToDo.
A value of 0 indicates that the priority has not been set. A value of 1
indicates the highest priority level. A value of 9 indicates the lowest
priority level.
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 ToDo'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.
SUMMARY
public static final int SUMMARY
Contains a summary for the ToDo.
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 a ToDo's unique ID.
The unique ID field is valid only if the ToDo has been added to a
ToDoList atleast once in the past. If the
ToDo 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.
Copyright 1999-2002 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved. Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved. Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
