Chapter 18: Working with POOM

The Pocket Outlook Object Model is the gateway to Outlook-specific data. POOM is not only a fun word to say, but also a powerful resource for developers. POOM allows you to integrate seamlessly your mobile applications into the standard core applications found on every Pocket PC.

Working with Tasks

The Pocket Outlook .NET component provides the ability to work with three facets of the Pocket Outlook data: tasks, contacts, and appointments. I'll start the discussion of this component with tasks.

From the developer's point of view, tasks can be used for a variety of purposes. For example, they could be used within a maintenance application to record follow-up work to be completed. In a delivery system, tasks could be used to note items for the next delivery. A CRM application could record steps to perform for a particular customer.

At the core of the task functionality provided through the Pocket Outlook .NET component from InTheHand is the Tasks property and the Task object. We'll look at each of these items in greater detail next.

The Tasks Property

The Tasks property of the OutlookApplication object provides access to a collection of the tasks that reside on a device. In actuality, the Tasks property furnishes an interface to the Tasks folder, provided through POOM. This property links through to an Items collection that contains all of the tasks.

We'll see several examples later in this section in which the Tasks property along with its Items collection is used to retrieve tasks.

The Task Object

You work with individual tasks through the Task object. Commonly used properties of this object are shown in Table 18-1. Frequently used methods of the Task object are shown in Table 18-2.

Table 18 - 1. Commonly Used Properties of the Task Object
 

PROPERTY	DESCRIPTION
Body	Defines the text of the notes accompanying a task
Categories	Indicates the categories for which a task is assigned
Complete	Indicates whether the task is complete
DateCompleted	Specifies the date that a task was completed
DueDate	Specifies the date that a task is due
Importance	Dictates the importance of a task
IsRecurring	Indicates whether a task is a single instance or recurs
Oid	Defines the unique identifier for a task
ReminderSet	Indicates whether to remind the user of the task
StartDate	Specifies the date that a task starts
Subject	Indicates the subject for a task

Table 18 - 2. Commonly Used Methods of the Task Object

METHOD	DESCRIPTION
Copy	Creates a copy of an existing task
Delete	Deletes a task
Display	Displays a task using the native Task interface
Save	Saves modifications to a task

While these tables might serve you well for reference, a set of practical examples follows that demonstrates commonly performed task-related operations.

Retrieving All Tasks

One of the most common functions involving tasks is the retrieving of a task(s). You can retrieve tasks in several ways:

• As a collection of all tasks
   
• As a subset of all tasks
   
• As a single task

We'll start by looking at how to retrieve all tasks, as it's a frequently used approach and the easiest method for retrieving tasks. Listing 18-1 provides a simple example of retrieving all of the tasks that are resident on a device.

Listing 18-1. Retrieving All of the Tasks

Imports InTheHand.PocketOutlook

[at the module level]
Dim poApplication As New OutlookApplication
Dim myTasks As OutlookItemCollection

Private Sub btnLoad_Click(ByVal sender As System.Object, _
      ByVal e As System.EventArgs) Handles btnLoad.Click
    ' Retrieve all of the tasks.
    myTasks = poApplication.Tasks.Items

End Sub

The key parts to this example are

• The Imports statement, which must be located at the top of a module.
   
• The declaration statement for the OutlookApplication object.
   
• The declaration of the OutlookItemCollection object, which can hold a collection of any Outlook items. In our case, it will hold a collection of tasks.
   
• Loading the collection of tasks from the OutlookApplication object, poApplication, into the OutlookItemCollection, myTasks.

At this point, the collection myTasks contains a set of task objects, one for each task that is resident on your test device. You can loop through this collection to propagate a ListBox or ComboBox, view specific task information, or reference a specific task within the collection.

Retrieving Select Tasks

There are times when you only want to retrieve specific tasks-either a single task, or perhaps a subset of tasks. Happily, it's easy to do using the Restrict method of the Items collection. Listing 18-2 demonstrates retrieving a subset of tasks. This example retrieves only those tasks with the category "demo".

Listing 18-2. Retrieving Select Tasks

Imports InTheHand.PocketOutlook

[at the module level]
Dim poApplication As New OutlookApplication
Dim myTasks As OutlookItemCollection

Private Sub btnSelect_Click(ByVal sender As System.Object, _
   ByVal e As System.EventArgs) Handles btnSelect.Click
   
    Dim strCategory As String
    Dim strQuery As String
   
    ' Retrieve the selected tasks.
    strCategory = "demo"
    strQuery = "[Categories] = " & ControlChars.Quote & strCategory & _
       ControlChars.Quote
    myTasks = poApplication.Tasks.Items.Restrict(strQuery)

End Sub

Much of the preparatory work is identical to that required to retrieve all of the tasks. You still need to add the Imports statement, declare the OutlookApplication object variable, and declare the OutlookItemCollection object variable.

The code used to select only the tasks you're interested in is located near the bottom of Listing 18-2. There you build a query string, which is nothing more than the WHERE part of a SQL SELECT statement. This query string is subsequently used with the Restrict method to retrieve only those tasks in which you're interested.

NOTE You can restrict tasks based upon any property provided through the Task object.

Displaying a Task

One of the cool features provided through POOM is the ability to display Pocket Outlook data in its native application interface-that's to say, just like it would appear to users had they gone into the Tasks application and selected to view a particular task.

POOM includes a method, Display, which is provided through the Pocket Outlook .NET component. Listing 18-3 demonstrates working with this method.

Listing 18-3. Displaying a Task

Imports InTheHand.PocketOutlook

[at the module level]
Dim poApplication As New OutlookApplication
Dim myTasks As OutlookItemCollection

Private Sub btnDisplay_Click(ByVal sender As System.Object,
   ByVal e As System.EventArgs) Handles btnDisplay.Click
    
   Dim myTask As Task

 ' Retrieve all of the tasks.
   myTasks = poApplication.Tasks.Items

 ' Display the first task.
   myTask = myTasks.Item(0)
   myTask.Display()
End Sub

As with the two previous examples, you start by adding the Imports statement and declaring the variables for OutlookApplication and OutlookItemCollection.

At the bottom of Listing 18-3 you'll see that all of the tasks are first retrieved. From this collection of tasks, you extract a single task, the first, into a Task object variable. This object provides the Display method, which in turn is called to display the selected task.

Adding a Task

Adding a new task is a three-step process. First, you need to create a new task. Second, you need to configure the task. Third, you need to save the task.Listing  18-4 demonstrates adding a task.

Listing 18-4. Adding a Task

Imports InTheHand.PocketOutlook

[at the module level]
Dim poApplication As New OutlookApplication

Private Sub btnAdd_Click(ByVal sender As System.Object, _
  ByVal e As System.EventArgs) Handles btnAdd.Click
  
  Dim myTask As Task
  
' Create a new task.
  myTask = poApplication.CreateTask

' Configure the task.
    With myTask
        .Body = "This is a sample task."
        .Categories = "demo"
        .DueDate = Today.Date
        .Importance = Importance.High
        .ReminderOptions = ReminderOptions.Dialog
        .ReminderSet = True
        .StartDate = Today.Date
        .Subject = "sample task"

        ' Finally, save the task.
        .Save()
    End With

End Sub

As with all of the previous examples, you start by adding the Imports statement and declaring the variables for OutlookApplication and OutlookItemCollection.

At the bottom of Listing 18-4 you'll see the three steps that I described. First, the CreateTask method of the OutlookApplication object is used to create your new task. Second, properties of the new task are loaded. Third, the Task object's Save method is called to save the task.

Modifying a Task

Modifying a task is similar to adding a task, only instead of creating a new task, you load a Task object with an existing task. Listing 18-5 shows how to modify a task.

Listing 18-5.Modifying a Task

Imports InTheHand.PocketOutlook

[at the module level]
Dim poApplication As New OutlookApplication
Dim myContacts As OutlookItemCollection

Private Sub btnModify_Click(ByVal sender As System.Object, _
   ByVal e As System.EventArgs) Handles btnModify.Click
   
   Dim myTask As Task

 ' Retrieve all of the tasks.
   myContacts = poApplication.Tasks.Items
   
 ' Modify the first task.
   myTask = myTasks.Item(0)
   With myTask
       .Body = "This is updated content."
       .Save()
    End With

End Sub

Once again, you start by adding the Imports statement, declaring the variables for OutlookApplication and OutlookItemCollection. At the bottom of Listing 18-5  you'll see where the task is first retrieved (along with all other tasks) and then loaded into the Task object. At this point, you can modify any of the Task object's properties. Finish the modification process by calling the Task object's Save method.

Now that you've seen the basics of working with tasks, let's pull it all together in a comprehensive example.