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.

Step-by-Step Tutorial: Working with Tasks

In this step-by-step exercise, you will create an application that demonstrates working with tasks within Pocket Outlook. As part of this exercise, you'll

• Connect to Pocket Outlook.
   
• Retrieve a list of all tasks.
   
• Retrieve a list of tasks based upon their Category property.
   
• Display a task.
   
• Add a task.

This application provides all of the fundamentals of working with tasks within Pocket Outlook.

NOTE To complete this tutorial, you will need the PocketOutlook component from InTheHand, available at http://www.inthehand.com .

NOTE I provide a completed version of this application, titled Tasks - Complete, under the Chapter 18 folder of the Samples folder for this book. See Appendix D for more information on accessing and loading the sample applications.

Step 1: Opening the Project

To simplify this tutorial, I've already created the project and the user interface for the Tasks Tutorial application. This template project is included under the Chapter 18 folder of the Samples folder. To load this project, follow these steps:

1. From the VS .NET IDE Start Page, select to open a project.The Open Project dialog box will be displayed
    
2. Use this dialog box to navigate to the Chapter 18 folder under the Samples folder for this book.
    
3. Select and open the project Tasks. The project will be loaded onto your computer.

Step 2: Examining the User Interface

The user interface for the Tasks Tutorial application comprises several controls: a ListBox, four Buttons, and a TextBox. Figure 18-2 shows the application's interface.

    
 
 Figure 18 - 2. The tasks application interface
 
The ListBox will display available tasks.

The four buttons for the Tasks Tutorial application function as follows:

• The Load button triggers loading a list of all tasks into the ListBox. 
   
• The Display button triggers displaying the selected task.
   
• The Add button adds a new task with predefined values. 
   
• The Select button retrieves a list of tasks for a select category.

The TextBox allows the user to specify the name of a category.

Step 3: Adding a Reference to the PocketOutlook

Component

You need to add a single reference to your application to enable you to work with the Pocket Outlook Object Model from a .NET Compact Framework application. Figure 18-2. The Tasks application interface

To add this reference, perform the following steps:

1. In the Solution Explorer window, right-click the References folder. A pop-up menu displays.
    
2. From the menu, select Add Reference. 
    
3. The Add Reference dialog box displays. Select the InTheHand.PocketOutlook component.
    
4. Click the OK button to add the selected component to your project.

Step 4: Adding the Imports Statement

The first line of code you'll be adding imports the PocketOutlook namespace. This allows you to reference and work with the PocketOutlook elements within your code without having to fully qualify each element.

To import the PocketOutlook namespace, perform the following steps:

1. Open the code window for the form.
    
2. At the top of the module, above the line that declares the

   Form class,

   add the following line of code:

   Imports InTheHand.PocketOutlook

Step 5: Declaring Module-Level Objects

This tutorial uses two module-level object variables. These variables hold instances of the PocketOutlook OutlookApplication and OutlookItemCollection objects.

To define these variables, add the following code to the module level of the form:

Dim poApplication As New OutlookApplication
Dim myTasks As OutlookItemCollection

Step 6: Loading a List of All Tasks

The first functionality that you'll add to the application is to display a list of all tasks. Obtaining this list is simple. Loading the list into your List Box requires nothing more than a For loop for running through the collection.

The first part of this step obtains a list of tasks. While you could simply reference the Tasks collection of the Outlook Application object, you are instead going to retrieve a copy of the Tasks collection into a collection of its own. Having a collection of tasks that matches those tasks displayed in your List Box makes it easier to display the details of an individual task. You'll see more on this later in the tutorial.

The code required to retrieve the Tasks collection is shown in Listing 18-6. Add this code to the Click event procedure of the Load button. In this procedure, you create a copy of the Tasks collection through the Outlook Application. Contacts. Items collection.

Listing 18-6. Retrieving a List of All Tasks

Private Sub btnLoad_Click(ByVal sender As System.Object, _
   ByVal e As System.EventArgs) Handles btnLoad.Click
   
 ' Store the collection of tasks for future use.
   myTasks = poApplication.Tasks.Items
 
 ' Load the list of tasks.
   LoadTasks()

End Sub

Displaying the list of tasks is triggered at the bottom of the procedure shown in Listing 18-6. The LoadTasks procedure is a general-purpose procedure that displays the contents of the myTasks collection in a ListBox.

To define the LoadTasks procedure, add the code shown in Listing 18-7 to your form module. The heart of this procedure is the For loop located near its bottom. This loop iterates through all of the tasks stored within the myTasks collection, adding the Subject property of each task to the ListBox.Remember, myTasks is a collection of tasks. Each item in this collection is a Task object, with all of its properties and methods.

Listing 18-7. The LoadContacts Procedure

Sub LoadTasks()
   Dim intCount As Integer
   Dim myTask As Task
 
  ' First, make sure that the list box is empty.
   lstTasks.Items.Clear()
  
  ' Next, load the tasks into the list box.
    For intCount = 0 To myTasks.Count - 1
       myTask = myTasks.Item(intCount)
       lstTasks.Items.Add(myTask.Subject
   Next

End Sub

Step 7: Displaying a Task

The process of displaying a task is easy because of the functionality provided through the Pocket Outlook Object Model. Calling the Display method of the Task object results in the task being displayed using the default task interface. To display a task, add the code shown in         Listing 18-8 to the Click event procedure of the Display button.

Listing 18-8. Displaying a Task

Private Sub btnDisplay_Click(ByVal sender As System.Object, _
   ByVal e As System.EventArgs) Handles btnDisplay.Click
   
   Dim myTask As Task
 
 ' Display the selected task.
   If (lstTasks.SelectedIndex <> -1) Then
      myTask = myTasks.Item(lstTasks.SelectedIndex)
      myTask.Display()
    End If

End Sub

Earlier in this tutorial, I mentioned the use of a collection to hold a list of Task objects. This is where that approach pays off. Since the collection myTasks matches the tasks displayed in the ListBox in a one-to-one relationship, it's easy to display a single task. All that you need to do is to create an instance of the task  and then call the Display method of that task.

Step 8: Adding a Task

Adding a task is a three-step process. First, you need to create the task. Second, you configure the properties of the task. Third, you save the task. In this tutorial, the task that is added is predefined, which is to say that the user has no input in the matter. Insert the code shown in  Listing 18-9 into the Click event of the Add button.

Listing 18-9. Adding a Task

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
    ' Let the user know that the task was added.
    MessageBox.Show("task added...")
End Sub

Step 9: Loading a List of Select Tasks

The last feature that you're going to add to this application is the ability to select a subset of the tasks list-in this case, all of the tasks from a specific category. Add the code shown in Listing 18-10 to the Click event of the Select button. At the heart of this procedure are two steps-the building of the selection string and then the use of this string with the Restrict method. The result is the creation of a collection of tasks that match the desired criteria.

Listing 18-10. Selecting a Subset of the Tasks

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

End Sub

Step 10: Testing the Application

Finally, you're ready to test your application. To begin, you need to copy the application to your target device by performing the following steps:

1. span style="font-size: 10.0pt; font-family: Verdana">Select either Pocket  PC Device or Pocket PC Emulator from the Deployment Device combo box.
    
2. Select Release from the Solution Configurations combo box.
    
3. Click the Start button.

Your application copies to the target device along with the PocketOutlook component.

Upon completion, the application starts.

To verify the functionality of your application, perform the following steps:

1. Tap the Load button. After a brief pause, the ListBox is loaded with all of the tasks that are resident on your device.
    
2. Select a task from the ListBox. Tap the Display button. The selected task displays in the default Tasks interface. Close the selected task.
    
3. Tap the Add button. A message box displays confirming the addition of the task. To verify this addition, tap the Load button. The task named "sample task" should appear in the ListBox.
    
4. Enter a category into the TextBox (you can always use the "demo" category, which was added in the previous step). Tap the Select button. All of the tasks that are within this category are loaded into the List Box.

NOTE The availability of tasks for a specific category is dependent upon the tasks resident on your test device.

HOMEWORK Add a button to this application that will modify an existing task. The task to modify is the one selected within the ListBox.

Next, we'll turn our attention to accessing, creating, and modifying contacts through the Pocket Outlook Object Model.