net.rim.blackberry.api.pim
Interface ToDo

All Superinterfaces:

PIMItem

Deprecated. In favour of ToDo.

public interface ToDo

extends PIMItem

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.

Data

The following table details the explicitly defined fields that may by in a ToDo. Implementations may extend the field set using extended fields as defined in PIMItem.

Fields	Type of Data Associated with Field
NOTE, SUMMARY, UID	PIMItem.STRING
CLASS, PRIORITY	PIMItem.INT
COMPLETION_DATE, DUE, REVISION	PIMItem.DATE
COMPLETED	PIMItem.BOOLEAN

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.

     if(todoItem.isModified()) {
        todoItem.commit();
      }
 

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.

RIM Implementation Notes

Extended Fields:

Field	Values
STATUS (PIMItem.EXTENDED_FIELD_MIN_VALUE + 9)	STATUS_NOT_STARTED = 1 STATUS_IN_PROGRESS = 2 STATUS_COMPLETED = 3 STATUS_WAITING = 4 STATUS_DEFERRED = 5

Since:

PDAP 1.0

See Also:

PIMItem, ToDoList

Field Summary

static int	CLASS Deprecated. Field specifying the desired access class for this contact.
static int	CLASS_CONFIDENTIAL Deprecated. Constant indicating this contact's class of access is confidential.
static int	CLASS_PRIVATE Deprecated. Constant indicating this contact's class of access is private.
static int	CLASS_PUBLIC Deprecated. Constant indicating this contact's class of access is public.
static int	COMPLETED Deprecated. Represents whether or not a ToDo has been completed.
static int	COMPLETION_DATE Deprecated. Represents the completion date for a ToDo.
static int	DUE Deprecated. Represents the due date of the ToDo.
static int	NOTE Deprecated. Represents a note about the ToDo.
static int	PRIORITY Deprecated. Represents the priority level of the ToDo.
static int	REVISION Deprecated. Represents the date and time that this ToDo's information was last modified.
static int	SUMMARY Deprecated. Contains a summary for the ToDo.
static int	UID Deprecated. Represents a ToDo'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

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

CLASS

public static final int CLASS

Deprecated.

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.

Since:

JDE 3.6.0

COMPLETED

public static final int COMPLETED

Deprecated.

Represents whether or not a ToDo has been completed.

Since:

JDE 3.6.0

COMPLETION_DATE

public static final int COMPLETION_DATE

Deprecated.

Represents the completion date for a ToDo. (i.e. the date on which the ToDo was completed)

Since:

JDE 3.6.0

DUE

public static final int DUE

Deprecated.

Represents the due date of the ToDo.

Since:

JDE 3.6.0

NOTE

public static final int NOTE

Deprecated.

Represents a note about the ToDo.

A note is used to store additional information about the ToDo.

Since:

JDE 3.6.0

PRIORITY

public static final int PRIORITY

Deprecated.

Represents the priority level of the ToDo. A value of 0 indicates highest priority; a value of 1 indicates normal priority; a value of 2 indicates lowest priority.

Since:

JDE 3.6.0

REVISION

public static final int REVISION

Deprecated.

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

Since:

JDE 3.6.0

SUMMARY

public static final int SUMMARY

Deprecated.

Contains a summary for the ToDo.

Since:

JDE 3.6.0

UID

public static final int UID

Deprecated.

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.

Since:

JDE 3.6.0

CLASS_CONFIDENTIAL

public static final int CLASS_CONFIDENTIAL

Deprecated.

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

Since:

JDE 3.6.0

CLASS_PRIVATE

public static final int CLASS_PRIVATE

Deprecated.

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

Since:

JDE 3.6.0

CLASS_PUBLIC

public static final int CLASS_PUBLIC

Deprecated.

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

Since:

JDE 3.6.0