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 Appointments

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

• Connect to Pocket Outlook.
   
• Retrieve a list of all appointments.
   
• Retrieve a list of appointments for today, tomorrow, and the next week.
   
• Display an appointment.
   
• Add an appointment.

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

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

NOTE I provide a completed version of this application, titled Appointments - 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 Appointments 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 Appointments. The project will be loaded onto your computer.

Step 2: Examining the User Interface

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

Figure 18 - 4. The appointments application interface

The ListBox will display available appointments.

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

• The Load button triggers loading a list of all appointments into the ListBox.

• The Display button triggers displaying the selected appointment.

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

• The Select button retrieves a list of appointments for today, tomorrow, or the next week.

The ComboBox provides three time-range options from which to choose:
today, tomorrow, and next week. These values have been preloaded.

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.

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

Step 6: Loading a List of All Appointments

The first functionality that you'll add to the application is to display a list of all appointments. 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 appointments. While you could simply reference the Appointments collection of the OutlookApplication object, you are instead going to retrieve a copy of the Appointments collection into a collection of its own. Having a collection of appointments that matches those appointments displayed in your ListBox makes it easier to display the details of an individual appointment. You'll see more on this later in the tutorial.

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

Listing 18-26. Retrieving a List of All Appointments

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

    ' Store the collection of appointments for future use.
     myAppointments = poApplication.Calendar.Items

    ' Load the list of appointments.
     LoadAppointments()

End Sub

Displaying the list of appointments is triggered at the bottom of the procedure shown in Listing 18-26. The LoadAppointments procedure is a general-purpose procedure that displays the contents of the myAppointments collection in a ListBox.

To define the LoadAppointments procedure, add the code shown in Listing 18-27 to your form module. The heart of this procedure is the For loop located near its bottom. This loop iterates through all of the appointments stored within the myAppointments collection, adding the Subject property of each appointment to the ListBox. Remember, myAppointments is a collection of appointments. Each item in this collection is an Appointment object, with all of its properties and methods.

Listing 18-27. The LoadAppointments Procedure

Sub LoadAppointments()
    Dim intCount As Integer
    Dim myAppointment As Appointment

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

    ' Next, load the appointments into the list box.
      For intCount = 0 To myAppointments.Count - 1
         myAppointment = myAppointments.Item(intCount)
         lstAppointments.Items.Add(myAppointment.Subject)
    Next

End Sub

Step 7: Displaying an Appointment

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

To display an appointment, add the code shown in Listing 18-28 to the Click event procedure of the Display button.

Listing 18-28. Displaying an Appointment

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

    Dim myAppointment As Appointment

    ' Display the selected appointment.
      If (lstAppointments.SelectedIndex <> -1) Then
        myAppointment = myAppointments.Item(lstAppointments.SelectedIndex)
        myAppointment.Display()
    End If

End Sub

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

Step 8: Adding an Appointment

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

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

Listing 18-29. Adding an Appointment

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

    Dim myAppointment As Appointment

    ' Create a new appointment.
      myAppointment = poApplication.CreateAppointment

    ' Configure the appointment.
      With myAppointment
        .Body = "This is a sample appointment."
        .Categories = "demo"
        .End = DateAdd(DateInterval.Hour, 1, Now)
        .Location = "New York"
        .Start = Now
        .Subject = "demo appointment"

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

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

End Sub

The key point to bring away from this sample is the configuration of two properties, Start and End. In the case of this sample, you set the start of the appointment to the present time. The end of the appointment is set to 1 hour from now. Obviously, this is an impractical example. Why would anyone want to set an appointment to start right now? Still, you get the idea. The Start and End properties are pivotal items when it comes to appointments, and the daterelated functionality provided through the .NET Compact Framework makes working with dates easy.

Step 9: Loading a List of Select Appointments

The last feature that you're going to add to this application is the ability to select appointments for either today, tomorrow, or the next week.Add the code shown in Listing 18-30 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 a collection of appointments that match the desired criteria.

Listing 18-30. Selecting a Subset of the Appointments

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

    Dim strQuery As String
    Dim tmpDate As Date

  ' Retrieve the selected appointments.
    Select Case cmbDates.Text
       
    Case "today"
            strQuery = "[Start] = " & ControlChars.Quote & _
            Date.Today.ToShortDateString & ControlChars.Quote
       
    Case "tomorrow"
           tmpDate = Date.Today.AddDays(1)
           strQuery = "[Start] = " & ControlChars.Quote & _
           tmpDate.Date.ToShortDateString & ControlChars.Quote
       
    Case "next week"
           tmpDate = Date.Today.AddDays(7)
            strQuery = "[Start] >= " & ControlChars.Quote & _
               Date.Today.ToShortDateString & ControlChars.Quote
            strQuery = strQuery & " AND [Start] < " & ControlChars.Quote & _
           tmpDate.Date.ToShortDateString & ControlChars.Quote
End Select

   myAppointments = poApplication.Calendar.Items.Restrict(strQuery)

    ' Load the list of appointments.
      LoadAppointments()

End Sub

Selecting appointments for today is the easiest. You simply need to set the criteria to the present date. Selecting appointments for tomorrow is only slightly more complicated. Some simple date math is used to add one day to the present date before performing the selection. Selecting the appointments for the next week is by far the most complicated of the three, and even then it's not rocket science. Here a compound select statement along with some date math is used to specify a range of dates for the selection.

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 appointments that are resident on your device.
   
   
2. Select an appointment from the ListBox. Tap the Display button. The selected appointment displays in the default Appointment interface. Close the selected appointment.
   
   
3. Tap the Add button. A message box displays confirming the addition of the appointment. To verify this addition, tap the Load button. The appointment named "This is a sample appointment."should appear in the ListBox.
   
   
4. Select a date range option from the ComboBox. Tap the Select button. All of the appointments for that range are loaded into the ListBox.

NOTE The availability of appointments that fall within a specific timeframe is dependent upon the appointments resident on your test device.

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