Share via


Walkthrough: Importing a Form Region That Is Designed in Outlook

This walkthrough demonstrates how to design a form region in Microsoft Office Outlook, and then import the form region into an Outlook add-in project by using the New Form Region wizard. Designing the form region in Outlook makes it possible for you to add native Outlook controls to the form region that bind to Outlook data. After you import the form region, you can handle the events of each control.

Applies to: The information in this topic applies to application-level projects for Outlook 2007 and Outlook 2010. For more information, see Features Available by Office Application and Project Type.

This walkthrough illustrates the following tasks:

  • Designing a form region by using the form region designer in Outlook.

  • Importing a form region into an Outlook add-in project.

  • Handling the events of controls on the form region.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Visual Studio Settings.

Prerequisites

You need the following components to complete this walkthrough:

-

An edition of Visual Studio 2010 that includes the Microsoft Office developer tools. For more information, see [Configuring a Computer to Develop Office Solutions](bb398242\(v=vs.100\).md).
  • Microsoft Office Outlook 2007 or Outlook 2010.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Working with Settings.

link to video For a related video demonstration, see How Do I: Create Outlook Form Regions Using Visual Studio 2008?.

Designing a Form Region by Using the Form Region Designer in Outlook

In this step you will design a form region in Outlook. You will then the save the form region to an easy-to-find location so that you can import it into Visual Studio.

This example form region completely replaces the usual Task form. It provides a way to track the progress of all tasks that must be completed before the main task can be performed (prerequisite tasks). The form region displays a list of the prerequisite tasks, and shows the completion status for each task in the list. Users can add tasks to the list and remove them. They can also refresh the completion status of each task.

To design a form region by using the form region designer in Outlook

  1. Start Microsoft Office Outlook.

  2. Open the forms designer by performing one of the following tasks:

  3. In the Design Form box, click Task, and then click Open.

  4. Create a form region by performing one of the following tasks:

    • In Outlook 2010, on the Developer tab, in the Design group, click New Form Region.

    • In Outlook 2007, on the Developer tab, in the Design group, click Form Region and then New Form Region.

    A new form region opens. If the Field Chooser does not appear, click Field Chooser in the Tools group.

  5. Drag the Subject field and the % Complete field from the Field Chooser to the form region.

  6. In the Tools group, click Control Toolbox to open the Toolbox.

  7. Drag a Label from the Toolbox to the form region. Position the label beneath the Subject and % Complete fields.

  8. Right-click the label, and then click Advanced Properties.

  9. In the Properties window, set the Caption property to This task depends on the following tasks, set the Width property to 200, and then click Apply.

  10. Drag a ListBox control from the Toolbox to the form region. Position the list box beneath the This task depends on the following tasks label.

  11. Select the list box that you just added.

  12. In the Properties window, set Width to 300, and then click Apply.

  13. Drag a Label from the Toolbox to the form region. Position the label beneath the list box.

  14. Select the label that you just added.

  15. In the Properties window, set the Caption property to Select a task to add to the list of dependent tasks, set the Width property to 200, and then click Apply.

  16. Drag a ComboBox control from the Toolbox to the form region. Position the combo box beneath the Select a task to add to the list of dependent tasks label.

  17. Select the combo box that you just added.

  18. In the Properties window, set the Width property to 300, and then click Apply.

  19. Drag a CommandButton control from the Toolbox to the form region. Position the command button next to the combo box.

  20. Select the command button that you just added.

  21. In the Properties window, set Name to AddDependentTask, set Caption to Add Dependent Task, set Width to 100, and then click Apply.

  22. In the Field Chooser, click New.

  23. In the New Field dialog box, type hiddenField in the Name field, and then click OK.

  24. Drag the hiddenField field from the Field Chooser to the form region.

  25. In the Properties window, set Visible to 0 - False, and then click Apply.

  26. Save the form region by performing one of the following tasks:

    • In Outlook 2010, on the Developer tab, in the Design group, click the Save button, and then click Save Form Region As.

    • In Outlook 2007, on the Developer tab, in the Design group, click Form Region, and then click Save Form Region As.

    Name the form region TaskFormRegion and save it to a local directory on your computer.

    Outlook saves the form region as an Outlook Form Storage (.ofs) file. The form region is saved with the name TaskFormRegion.ofs.

  27. Exit Outlook.

Creating a New Outlook Add-in Project

In this step, you will create an Outlook add-in project. Later in this walkthrough, you will import the form region into to the project.

To create a new Outlook add-in project

  1. In Visual Studio, create an Outlook add-in project with the name TaskAddIn.

  2. In the New Project dialog box, select Create directory for solution.

  3. Save the project to the default project directory.

    For more information, see How to: Create Office Projects in Visual Studio.

Importing the Form Region

You can import the form region that you designed in Outlook into the Outlook add-in project by using the New Outlook Form Region wizard.

To import the form region into the Outlook add-in project

  1. In Solution Explorer, right-click the TaskAddIn project, point to Add, and then click New Item.

  2. In the Templates pane, select Outlook Form Region, name the file TaskFormRegion, and then click Add.

    The New Outlook Form Region wizard starts.

  3. On the Select how you want to create the form region page, click Import an Outlook Form Storage (.ofs) File, and then click Browse.

  4. In the Existing Outlook Form Region File Location dialog box, browse to the location of TaskFormRegion.ofs, select TaskFormRegion.ofs, click Open, and then click Next.

  5. On the Select the type of form region you want to create page, click Replace-all, and then click Next.

    A replace-all form region replaces the entire Outlook form. For more information about form region types, see Creating Outlook Form Regions.

  6. On the Supply descriptive text and select your display preferences page, click Next.

  7. On the Identify the message classes that will display this form region page, in the Which custom message classes will display this form region field, type IPM.Task.TaskFormRegion, and then click Finish.

    A TaskFormRegion.cs or TaskFormRegion.vb file is added to your project.

Handling the Events of Controls on the Form Region

Now that you have the form region in the project, you can add code that handles the Microsoft.Office.Interop.Outlook.OlkCommandButton.Click event of the button that you added to the form region in Outlook.

Also, add code to the FormRegionShowing event that updates controls on the form region when the form region appears.

To handle the events of controls on the form region

  1. In Solution Explorer, right-click TaskFormRegion.cs or TaskFormRegion.vb, and then click View Code.

    TaskFormRegion.cs or TaskFormRegion.vb opens in the Code Editor.

  2. Add the following code to the TaskFormRegion class. This code populates the combo box on the form region with the subject line of each task from the Outlook Tasks folder.

    Private Sub populateComboBox()
        Dim Application As New Outlook.Application()
        Dim outlookNameSpace As Outlook.NameSpace = _
        Application.GetNamespace("MAPI")
        Dim taskFolder As Outlook.MAPIFolder = _
        outlookNameSpace.GetDefaultFolder _
            (Microsoft.Office.Interop.Outlook.OlDefaultFolders.olFolderTasks)
        Dim taskItems As Outlook.Items = taskFolder.Items
        Dim task As Outlook.TaskItem
        For Each task In taskItems
            If Not (task.Subject Is Nothing) Then
                comboBox1.AddItem(task.Subject, System.Type.Missing)
            End If
        Next task
        comboBox1.Text = comboBox1.GetItem(0)
    End Sub
    
    private void populateComboBox()
    {
        Outlook.Application Application = new Outlook.Application();
        Outlook.NameSpace outlookNameSpace = Application.GetNamespace("MAPI");
        Outlook.MAPIFolder taskFolder = outlookNameSpace.GetDefaultFolder(
            Microsoft.Office.Interop.Outlook.OlDefaultFolders.olFolderTasks);
        Outlook.Items taskItems = taskFolder.Items;
        foreach (Outlook.TaskItem task in taskItems)
        {
            if (task.Subject != null)
            {
                comboBox1.AddItem(task.Subject, System.Type.Missing);
            }
        }
        comboBox1.Text = comboBox1.GetItem(0);
    }
    
  3. Add the following code to the TaskFormRegion class. This code performs the following tasks:

    • Locates the Microsoft.Office.Interop.Outlook.TaskItem in the Tasks folder by calling the FindTaskBySubjectName helper method and passing the subject of the desired task. You will add the FindTaskBySubjectName helper method in the next step.

    • Adds the Microsoft.Office.Interop.Outlook.TaskItem.Subject and Microsoft.Office.Interop.Outlook.TaskItem.PercentComplete values to the dependent task list box.

    • Adds the subject of the task to the hidden field on the form region. The hidden field stores these values as part of the Outlook item.

    Private Sub AddDependentTask_Click1() Handles addDependentTask.Click
        Dim tempTaskItem As Outlook.TaskItem = FindTaskBySubjectName _
            (comboBox1.Text)
        If Not (tempTaskItem Is Nothing) Then
            Me.listBox1.AddItem(tempTaskItem.PercentComplete.ToString() & _
                "% Complete -- " & tempTaskItem.Subject, System.Type.Missing)
            Me.olkTextBox3.Text = Me.olkTextBox3.Text & "|" & tempTaskItem.Subject
        End If
    End Sub
    
        void AddDependentTask_Click()
        {
            Outlook.TaskItem tempTaskItem = FindTaskBySubjectName(comboBox1.Text);
            if (tempTaskItem != null)
            {
                this.listBox1.AddItem(tempTaskItem.PercentComplete.ToString()
    + "% Complete -- " + tempTaskItem.Subject, System.Type.Missing);
                this.olkTextBox3.Text = this.olkTextBox3.Text + "|" + 
                    tempTaskItem.Subject;
            }
        }
    
  4. Add the following code to the TaskFormRegion class. This code provides the helper method FindTaskBySubjectName that was described in the preceding step.

    Private Function FindTaskBySubjectName(ByVal subjectName As String) _
        As Outlook.TaskItem
        Dim Application As New Outlook.Application()
        Dim outlookNameSpace As Outlook.NameSpace = _
            Application.GetNamespace("MAPI")
        Dim tasksFolder As Outlook.MAPIFolder = _
            outlookNameSpace.GetDefaultFolder _
                (Microsoft.Office.Interop.Outlook.OlDefaultFolders.olFolderTasks)
        Dim taskItems As Outlook.Items = tasksFolder.Items
        Dim taskItem As Outlook.TaskItem
        For Each taskItem In taskItems
            If taskItem.Subject = subjectName Then
                Return taskItem
            End If
        Next taskItem
        Return Nothing
    End Function
    
    private Outlook.TaskItem FindTaskBySubjectName(string subjectName)
    {
        Outlook.Application Application = new Outlook.Application();
        Outlook.NameSpace outlookNameSpace = Application.GetNamespace("MAPI");
        Outlook.MAPIFolder tasksFolder =
            outlookNameSpace.GetDefaultFolder(
        Microsoft.Office.Interop.Outlook.
            OlDefaultFolders.olFolderTasks);
        Outlook.Items taskItems = tasksFolder.Items;
        foreach (Outlook.TaskItem taskItem in taskItems)
        {
            if (taskItem.Subject == subjectName)
            {
                return taskItem;
            }
        }
        return null;
    }
    
  5. Add the following code to the TaskFormRegion class. This code performs the following tasks:

    • Refreshes the list box on the form region with the current completion status of each dependent task.

    • Parses the hidden text field to obtain the subject of each dependent task. It then locates each Microsoft.Office.Interop.Outlook.TaskItem in the Tasks folder by calling the FindTaskBySubjectName helper method and passing the subject of each task.

    • Adds the Microsoft.Office.Interop.Outlook.TaskItem.Subject and Microsoft.Office.Interop.Outlook.TaskItem.PercentComplete values to the dependent task list box.

    Private Sub RefreshTaskListBox()
        listBox1.Clear()
        Dim tempTaskItem As Outlook.TaskItem
        Dim tempArray As [String]() = olkTextBox3.Text.Split(New [Char]() {"|"c})
    
        Dim tempString As String
        For Each tempString In tempArray
            tempTaskItem = FindTaskBySubjectName(tempString)
            If Not (tempTaskItem Is Nothing) Then
                Me.listBox1.AddItem(tempTaskItem.PercentComplete.ToString() & _
                    "% Complete -- " & tempTaskItem.Subject, System.Type.Missing)
            End If
        Next tempString
    End Sub
    
    void RefreshTaskListBox()
    {
        listBox1.Clear();
        Outlook.TaskItem tempTaskItem;
        String[] tempArray = olkTextBox3.Text.Split(new Char[] { '|' });
    
        foreach (string tempString in tempArray)
        {
            tempTaskItem = FindTaskBySubjectName(tempString);
            if (tempTaskItem != null)
            {
                this.listBox1.AddItem(tempTaskItem.PercentComplete.ToString()
                    + "% Complete -- " + tempTaskItem.Subject, 
                        System.Type.Missing);
            }
        }
    }
    
  6. Replace the TaskFormRegion_FormRegionShowing event handler with the following code. This code performs the following tasks:

    • Populates the combo box on the form region with task subjects when the form region appears.

    • Calls the RefreshTaskListBox helper method when the form region appears. This displays any dependent tasks that were added to the list box when the item was previously opened.

    Private Sub TaskFormRegion_FormRegionShowing(ByVal sender As Object, _
        ByVal e As System.EventArgs) Handles MyBase.FormRegionShowing
        populateComboBox()
        RefreshTaskListBox()
    End Sub
    
    private void TaskFormRegion_FormRegionShowing
        (object sender, EventArgs e)
    {
        populateComboBox();
        RefreshTaskListBox();
        this.addDependentTask.Click += new
        Microsoft.Office.Interop.Outlook.
            OlkCommandButtonEvents_ClickEventHandler(AddDependentTask_Click);
    
    }
    

Testing the Outlook Form Region

To test the form region, add tasks to the list of prerequisite tasks on the form region. Update the completion status of a prerequisite task, and then view the updated completion status of the task in the prerequisite task list.

To test the form region

  1. Press F5 to run the project.

    Outlook starts.

  2. In Outlook, create a task by performing one of the following tasks:

    • In Outlook 2010, on the Home tab, click New Items, and then click Task.

    • In Outlook 2007, on the File menu, point to New, and then click Task.

  3. In the task form, type Dependent Task in the Subject field.

  4. On the Task tab of the Ribbon, in the Actions group, click Save & Close.

  5. In Outlook, create an instance of your form region by performing one of the following tasks:

  6. In Outlook 2010, on the Home tab, click New Items, click More Items, and then click Choose Form.

  7. In Outlook 2007, on the File menu, point to New, and then click Choose Form.

  8. In the Choose Form dialog box, click TaskFormRegion, and then click Open.

    The TaskFormRegion form region appears. This form replaces the entire task form. The Select a task to add to the list of dependent tasks combo box is populated with other tasks in the Tasks folder.

  9. On the task form, in the Subject field, type Primary Task.

  10. In the Select a task to add to the list of dependent tasks combo box, select Dependent Task, and then click Add Dependent Task.

    0% Complete -- Dependent Task appears in the This task depends on the following tasks list box. This demonstrates that you successfully handled the Microsoft.Office.Interop.Outlook.OlkCommandButton.Click event of the button.

  11. Save and close the Primary Task item.

  12. Reopen the Dependent Task item in Outlook.

  13. On the Dependent Task form, change the % Complete field to 50%.

  14. On the Task tab of the Dependent Task Ribbon, in the Actions group, click Save & Close.

  15. Reopen the Primary Task item in Outlook.

    50% Complete -- Dependent Task now appears in the This task depends on the following tasks list box.

Next Steps

You can learn more about how to customize the UI of an Outlook application from these topics:

See Also

Tasks

Walkthrough: Designing an Outlook Form Region

How to: Add a Form Region to an Outlook Add-in Project

How to: Prevent Outlook from Displaying a Form Region

How to: Access the Outlook Item that Displays the Form Region

Concepts

Accessing a Form Region at Run Time

Guidelines for Creating Outlook Form Regions

Associating a Form Region with an Outlook Message Class

Custom Actions in Outlook Form Regions

Other Resources

Creating Outlook Form Regions