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


Copyright 1999-2004 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.