javax.microedition.pim
Interface ToDo

All Superinterfaces:
PIMItem
All Known Subinterfaces:
BlackBerryToDo

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();
                  todoItem.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 = 0
  • STATUS_IN_PROGRESS = 1
  • STATUS_COMPLETED = 2
  • STATUS_WAITING = 3
  • STATUS_DEFERRED = 4

Since:
PDAP 1.0
See Also:
PIMItem, ToDoList

Field Summary
static int CLASS
          Field specifying the desired access class for this contact.
static int CLASS_CONFIDENTIAL
          Constant indicating this contact's class of access is confidential.
static int CLASS_PRIVATE
          Constant indicating this contact's class of access is private.
static int CLASS_PUBLIC
          Constant indicating this contact's class of access is public.
static int COMPLETED
          Represents whether or not a ToDo has been completed.
static int COMPLETION_DATE
          Represents the completion date for a ToDo.
static int DUE
          Represents the due date of the ToDo.
static int NOTE
          Represents a note about the ToDo.
static int PRIORITY
          Represents the priority level of the ToDo.
static int REVISION
          Represents the date and time that this ToDo's information was last modified.
static int SUMMARY
          Contains a summary for the ToDo.
static int UID
          Represents a ToDo's unique ID.
 
Fields inherited from interface javax.microedition.pim.PIMItem
ATTR_NONE, BINARY, BOOLEAN, DATE, EXTENDED_ATTRIBUTE_MIN_VALUE, EXTENDED_FIELD_MIN_VALUE, INT, STRING, STRING_ARRAY
 
Method Summary
 
Methods inherited from interface javax.microedition.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
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 4.0.0

CLASS_CONFIDENTIAL

public static final int CLASS_CONFIDENTIAL
Constant indicating this contact's class of access is confidential.
Since:
JDE 4.0.0

CLASS_PRIVATE

public static final int CLASS_PRIVATE
Constant indicating this contact's class of access is private.
Since:
JDE 4.0.0

CLASS_PUBLIC

public static final int CLASS_PUBLIC
Constant indicating this contact's class of access is public.
Since:
JDE 4.0.0

COMPLETED

public static final int COMPLETED
Represents whether or not a ToDo has been completed.
Since:
JDE 4.0.0

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)
Since:
JDE 4.0.0

DUE

public static final int DUE
Represents the due date of the ToDo.

Since:
JDE 4.0.0

NOTE

public static final int NOTE
Represents a note about the ToDo.

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

Since:
JDE 4.0.0

PRIORITY

public static final int PRIORITY
Represents the priority level of the ToDo.

A value of 0 indicates the highest priority level. A value of 1 indicates normal priority. A value of 2 indicates the lowest priority level.

Since:
JDE 4.0.0

REVISION

public static final int REVISION
Represents the date and time that this ToDo's information was last modified.

Since:
JDE 4.0.0

SUMMARY

public static final int SUMMARY
Contains a summary for the ToDo.
Since:
JDE 4.0.0

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.

Since:
JDE 4.0.0



Copyright 1999-2008 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.