Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Task list

View or change a task

Import the required classes and interfaces.

import java.util.Enumeration;
import javax.microedition.pim.PIM;
import javax.microedition.pim.ToDo;
import javax.microedition.pim.ToDoList;
import net.rim.blackberry.api.invoke.Invoke;
import net.rim.blackberry.api.invoke.TaskArguments;

Create an instance of a ToDoList and store it in an Enumeration.

ToDoList tdl = (ToDoList)PIM.getInstance().openPIMList(PIM.TODO_LIST, 
   PIM.READ_WRITE);
Enumeration todos = tdl.items();

Create a ToDo object using an element from the Enumeration.

ToDo todo = (ToDo)todos.nextElement();

Invoke Invoke.invokeApplication() using the APP_TYPE_TASKS field, and a new TaskArguments object created using the ARG_VIEW field and the ToDo object.

Invoke.invokeApplication(Invoke.APP_TYPE_TASKS, 
   new TaskArguments(TaskArguments.ARG_VIEW, todo));

Create a new blank task

Import the required classes and interfaces.

import net.rim.blackberry.api.invoke.Invoke;
import net.rim.blackberry.api.invoke.TaskArguments;

Invoke Invoke.invokeApplication() using the APP_TYPE_TASKS field, and a new TaskArguments object created using the ARG_NEW field.

Invoke.invokeApplication(Invoke.APP_TYPE_TASKS, 
   new TaskArguments( TaskArguments.ARG_NEW));

Create a new populated task

Import the required classes and interfaces.

import java.util.Enumeration;
import javax.microedition.pim.PIM;
import javax.microedition.pim.ToDo;
import javax.microedition.pim.ToDoList;
import net.rim.blackberry.api.invoke.Invoke;
import net.rim.blackberry.api.invoke.TaskArguments;

Create an instance of a ToDoList.

ToDoList tdl = (ToDoList)PIM.getInstance().openPIMList(PIM.TODO_LIST, 
   PIM.READ_WRITE);

Invoke createToDo() to create a new ToDo object and add information to the new ToDo object.

ToDo todo = tdl.createToDo();
todo.addString(ToDo.SUMMARY, 0, "Walk the Dog");

Invoke Invoke.invokeApplication() using the APP_TYPE_TASKS field, and a new TaskArguments object created using the ARG_NEW field and the new ToDo object.

Invoke.invokeApplication(Invoke.APP_TYPE_TASKS, 
   new TaskArguments( TaskArguments.ARG_NEW, todo));

Open a task list

Import the required classes and interfaces.

import javax.microedition.pim.PIM;
import javax.microedition.pim.PIMException;
import javax.microedition.pim.ToDoList;

Invoke PIM.openPIMList() and provide as parameters the type of list to open (PIM.TODO_LIST) and the access mode with which to open the list (READ_WRITE, READ_ONLY, or WRITE_ONLY).

ToDoList todoList = null;
try 
{
   todoList = (ToDoList)PIM.getInstance().openPIMList(PIM.TODO_LIST, 
      PIM.READ_WRITE);
} 
catch (PimException e) 
{
   // handle exception here 
}

Create a task

Import the required classes and interfaces.

import javax.microedition.pim.ToDo;
import javax.microedition.pim.ToDoList;

Invoke ToDoList.createToDo()on a task list.

ToDo task = todoList.createToDo();

Add task information

Import the required classes and interfaces.

import java.util.Date;
import javax.microedition.pim.PIMList;
import javax.microedition.pim.ToDo;
import javax.microedition.pim.ToDoList;

Before you set or retrieve a field, verify that the item supports the field by invoking ToDoList.isSupportedField(int).

Invoke PIMList.getFieldDataType(int) to retrieve the field data type.

Invoke one of the following methods to set the field data:

  • addString()
  • addDate()
  • addInt()
  • addBoolean()
  • addBinary()
if (todoList.isSupportedField(ToDo.SUMMARY)) 
{
   task.addString(ToDo.SUMMARY, ToDo.ATTR_NONE, "Create project plan");
}

if (todoList.isSupportedField(ToDo.DUE)) 
{
   Date date = new Date();
   task.addDate(ToDo.DUE, ToDo.ATTR_NONE, (date + 17280000));
}

if (todoList.isSupportedField(ToDo.NOTE)) 
{
   task.addString(ToDo.NOTE, ToDo.ATTR_NONE, "Required for meeting");
}

if (todoList.isSupportedField(ToDo.PRIORITY)) 
{
   task.addInt(Todo.PRIORITY, ToDo.ATTR_NONE, 2);
}

Change task information

Import the required classes and interfaces.

import javax.microedition.pim.ToDo;
import javax.microedition.pim.ToDoList;

To replace an existing value with a new value, invoke the appropriate set method, such as ToDo.setString().

To determine if a value is already set for the field, invoke ToDo.countValues().

if (task.countValues(ToDo.SUMMARY) > 0) 
{
   task.setString(ToDo.SUMMARY, 0, ToDo.ATTR_NONE, "Review notes");
}

Create code to manage a FieldFullException that a method such as addString() throws when a value already exists.

Save a task

Import the required classes and interfaces.

import javax.microedition.pim.ToDo;
import javax.microedition.pim.ToDoList;

Before you commit your changes, invoke isModified() to determine whether any task fields have changed since the task was last saved.

Invoke commit().

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

Retrieve task information

Import the required classes and interfaces.

import java.util.Enumeration;
import javax.microedition.pim.PIM;
import javax.microedition.pim.ToDo;
import javax.microedition.pim.ToDoList;

Invoke ToDoList.items() on the task list to retrieve an enumeration.

ToDoList todoList = 
   (ToDoList)PIM.getInstance().openToDoList(PIM.TODO_LIST, PIM.READ_ONLY);
Enumeration enum = todoList.items();

Invoke ToDo.getFields() to retrieve an array of IDs for fields that have data for a particular ToDo item.

Invoke PIMItem.getString() to retrieve the field values.

while (enum.hasMoreElements()) 
{
   ToDo task = (ToDo)enum.nextElement();
   int[] fieldIds = task.getFields();
   int id;
   for(int index = 0; index < fieldIds.length; ++index) 
   {
      id = fieldIds[index];
      if(task.getPIMList().getFieldDataType(id) == STRING) 
      {
         for(int j=0; j < task.countValues(id); ++j) 
         {
            String value = task.getString(id, j);
            System.out.println(task.getFieldLable(id) + "=" + value);
         }
      }
   }
}

Export a task

Import the required classes and interfaces.

import java.io.ByteArrayOutputStream;
import java.util.Enumeration;
import javax.microedition.pim.PIM;
import javax.microedition.pim.ToDo;
import javax.microedition.pim.ToDoList;

Use an output stream writer to export tasks from the BlackBerry device to a supported serial format.

To retrieve a string array of supported serial formats, invoke PIM.supportedSerialFormats(), and then specify the list type (PIM.TODO_List).

To write an item to a serial format, invoke PIM.getInstance().toSerialFormat. The enc parameter specifies the character encoding to use when writing to the output stream. Supported character encodings include "UTF8," "ISO-8859-1," and "UTF-16BE." This parameter cannot be null.

ToDoList todoList = 
   (ToDoList)PIM.getInstance().openPIMList(PIM.TODO_LIST, PIM.READ_ONLY);
ByteArrayOutputStream byteStream = new ByteArrayOutputStream();
String[] dataFormats = PIM.getInstance().supportedSerialFormats(PIM.TODO_LIST);
Enumeration e = todoList.items();
while (e.hasMoreElements()) 
{
   ToDo task = (ToDo)e.nextElement();
   PIM.getInstance().toSerialFormat(task, byteStream, "UTF8", dataFormats[0]);
}

Import a task

Import the required classes and interfaces.

import java.io.ByteArrayInputStream;
import javax.microedition.pim.PIM;
import javax.microedition.pim.PIMItem;
import javax.microedition.pim.ToDo;
import javax.microedition.pim.ToDoList;

Invoke PIM.getInstance().fromSerialFormat() to return an array of PIMItem objects. The enc parameter specifies the character encoding to use when writing to the output stream. Supported character encodings include "UTF8," "ISO-8859-1," and "UTF-16BE." This parameter cannot be null.

Invoke ToDoList.importToDo() to create a new task using the PIM items.

String[] dataFormats = PIM.toDoSerialFormats();

// Write task to serial format
ByteArrayOutputStream os = new ByteArrayOutputStream();
PIM.getInstance().toSerialFormat(task, os, "UTF8", dataFormats[0]);

// Import task from serial format
ByteArrayInputStream is = new ByteArrayInputStream(outputStream.toByteArray());
PIMItem[] pi = PIM.getInstance().fromSerialFormat(is, "UTF8");
ToDoList todoList = 
   (ToDoList)PIM.getInstance().openPIMList(PIM.TODO_LIST, PIM.READ_WRITE);
ToDo task2 = todoList.importToDo((ToDo)pi[0]);
task2.commit();

Delete a task

Import the required classes and interfaces.

import java.util.Enumeration;
import javax.microedition.pim.PIM;
import javax.microedition.pim.ToDo;
import javax.microedition.pim.ToDoList;

Invoke PIM.getInstance to create a ToDoList object.

ToDoList todoList = (ToDoList)PIM.getInstance().openToDoList(PIM.TODO_LIST, 
   PIM.READ_ONLY);

Invoke ToDoList.removeToDo() to delete the task.

todoList.removeToDo(task);

Close the task list

Import the required classes and interfaces.

import javax.microedition.pim.PIMException;
import javax.microedition.pim.ToDoList;

Invoke ToDoList.close().

Create code that manages exceptions.

try 
{ 
   todoList.close(); 
} 
catch (PIMException e) 
{ 
   // Handle exception
}

Notify a BlackBerry device application when a list of tasks changes

Import the required classes and interfaces.

import javax.microedition.pim.PIM;
import net.rim.blackberry.api.pdap.PIMListListener;
import net.rim.blackberry.api.pdap.BlackBeryPIMList;

Implement the PIMListListener interface.

class MyTaskListListener implements PIMListListener {...}

Invoke BlackBerryPIMList.addListener() to register to receive notifications of changes to a task list.

BlackBerryPIMList taskList = 
   (BlackBerryPIMList)PIM.getInstance().openPIMList(PIM.TODO_LIST, 
   PIM.READ_WRITE);
taskList.addListener(new MyTaskListListener());