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 Contacts

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

• Connect to Pocket Outlook.
   
• Retrieve a list of all contacts.

• Retrieve a list of contacts based upon the first letter of their name.
   
• Display a contact.
   
• Add a contact.

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

NOTE To complete this tutorial you'll need the PocketOutlookcomponent from  InTheHand at http://www.inthehand.com.

NOTE I provide a completed version of this application, titled Contacts - 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 Contacts Tutorial application. This template project is included under the Chapter 18 folder in 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 Contacts. The project will be loaded onto your computer.

Step 2: Examining the User Interface

The user interface for the Contacts Tutorial application is comprised of several controls:
a ListBox, four Buttons, and a ComboBox. Figure 18-3 shows the application's interface.

     
     
Figure 18 - 3. The contacts application interface

The ListBox will display available contacts.

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

• The Load button triggers loading a list of all contacts into the ListBox.
   
• The Display button triggers displaying the selected contact. 

• The Add button adds a new contact with predefined values. 

• The Select button retrieves a list of contacts that begin with a specific letter.

The ComboBox provides a list from which the user may select an alphabetical subset of the contacts. The ComboBox has been preloaded with all of the letters of the alphabet.

Step 3: Adding a Reference to PocketOutlook

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.

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 myContacts As OutlookItemCollection

Step 6: Loading a List of All Contacts

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

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

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

Contacts.Items collection.

Listing 18-16. Retrieving a List of All Contacts

Private Sub btnLoad_Click(ByVal sender As System.Object, _
   ByVal e As System.EventArgs) Handles btnLoad.Click

    ' Store the collection of contacts for future use.
     myContacts = poApplication.Contacts.Items

    ' Load the list of contacts.
     LoadContacts()

End Sub

Displaying the list of contacts is triggered at the bottom of the procedureshown in Listing 18-16.  The LoadContacts procedure is a general-purpose procedure that displays the contents of the myContacts collection in a ListBox.

To define the LoadContacts procedure, add the code shown in Listing 18-17 to your form module. The heart of this procedure is the For loop located near its bottom.This loop iterates through all  of the contacts stored within the myContacts collection, adding the FileAs property of each contact  to the ListBox. Remember,myContacts is a collection of contacts. Each item in this collection is a  Contact object, with all of its properties and methods.

Listing 18-17. The LoadContacts Procedure

Sub LoadContacts()
    Dim intCount As Integer
    Dim myContact As Contact

    ' First, make sure that the list box is empty.
      lstContacts.Items.Clear()

    ' Next, load the contacts into the list box.
      For intCount = 0 To myContacts.Count - 1

        myContact = myContacts.Item(intCount)
        lstContacts.Items.Add(myContact.FileAs)
   Next

End Sub

Step 7: Displaying a Contact

The process of displaying a contact is easy because of the functionality provided through  the Pocket Outlook Object Model. Calling the Display method of the Contact object results  in the contact being displayed using the default contact interface.

To display a contact, add the code shown in Listing 18-18 to the Click event procedure of  the Display button.

Listing 18-18. Displaying a Contact

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

    Dim myContact As Contact

    ' Display the selected contact.

    If (lstContacts.SelectedIndex <> -1) Then
        myContact = myContacts.Item(lstContacts.SelectedIndex
        myContact.Display()
End If

End Sub

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

Step 8: Adding a Contact

Adding a contact is a three-step process. First, you need to create the contact. Second, you configure the properties of the contact. Third, you save the contact.

In this tutorial, the contact 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-19 into the Click event of the Add button.

Listing 18-19. Adding a Contact

Private Sub btnAdd_Click(ByVal sender As System.Object, _
   ByVal e As System.EventArgs) Handles btnAdd.Click

    Dim myContact As Contact

    ' Create a new contact.
      myContact = poApplication.CreateContact

    ' Configure the contact.
      With myContact
        .Birthday = CDate("01/01/1960")
        .Body = "This is a sample contact."
        .BusinessTelephoneNumber = "888-555-0001"
        .Categories = "demo"
        .CompanyName = "Acme"
        .Email1Address = "[email protected]"
        .FileAs = "Acme, Joe"
        .FirstName = "Joe"
        .LastName = "Acme"
        .Title = "President"

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

    ' Let the user know that the contact was added.
      MessageBox.Show("contact added...")

End Sub

Step 9: Loading a List of Select Contacts

The last feature that you're going to add to this application is the ability to select a subset  of the contacts list. In this case, you're going to select all of the contacts that begin with a  specific letter-for example, only those contacts that begin with the letter A.

Add the code shown in Listing 18-20 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 contacts that match the desired criteria.

Listing 18-20. Selecting a Subset of the Contacts

Private Sub btnSelect_Click(ByVal sender As System.Object, _
   ByVal e As System.EventArgs) Handles btnSelect.Click

    Dim strQuery As String

    ' Retrieve the selected contacts.
     strQuery = "[FileAs] >= " & ControlChars.Quote & cmbPrefix.Text & _ 
        ControlChars.Quote

   ' Use a range for anything other than contacts beginning with the letter "Z".
    If (cmbPrefix.Text < "Z") Then
        strQuery = strQuery & " AND [FileAs] < " & ControlChars.Quote & _
        cmbPrefix.Items(cmbPrefix.SelectedIndex + 1) & ControlChars.Quote
    End If

    myContacts = poApplication.Contacts.Items.Restrict(strQuery)

    ' Load the list of contacts.
     LoadContacts()

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. 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 contacts that are resident on your device.
    
2. Select a contact from the ListBox. Tap the Display button. The selected contact displays in the default Contacts interface. Close the selected contact.
    
3. Tap the Add button. A message box displays, confirming the addition of the contact. To verify this addition, tap the Load button. The contact for "Acme, Joe" should appear in the ListBox.
    
4. Select a letter from the ComboBox. Tap the Select button. All of the contacts that begin with the selected letter are loaded into the ListBox.

NOTE The availability of contacts that begin with a specific letter is dependent upon the contacts resident on your test device.

HOMEWORK Add a button to this application that will modify an existing contact. The contact to modify is the one selected within the ListBox. Next, we'll turn our attention to accessing, creating, and modifying appointments through the Pocket Outlook Object Model.