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 2013 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 Customizing Development Settings in Visual Studio.

Prerequisites

You need the following components to complete this walkthrough:

• An edition of Visual Studio 2013 that includes the Microsoft Office developer tools. For more information, see Configuring a Computer to Develop Office Solutions.

• Outlook 2013 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 Customizing Development Settings in Visual Studio.

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. In Outlook, on the Developer tab, click Design a Form. For more information, see How to: Show the Developer Tab on the Ribbon.

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

4. In Outlook, on the Developer tab, in the Design group, click 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. In Outlook, on the Developer tab, in the Design group, click the Save button, 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 NewOutlook 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, on the Home tab, click New Items, 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, on the Home tab, click New Items, click More Items, and then click Choose Form.

6. 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.

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

8. 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.

9. Save and close the Primary Task item.

10. Reopen the Dependent Task item in Outlook.

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

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

13. 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:

• To learn more about how to design the appearance of a form region by dragging managed controls onto a visual designer, see Walkthrough: Designing an Outlook Form Region.

• To learn about how to customize the Ribbon of an Outlook item, see Customizing a Ribbon for Outlook.

• To learn more about how to add a custom task pane to Outlook, see Custom Task Panes.

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

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