Export (0) Print
Expand All

Walkthrough: Importing a Form Region That Is Designed in Outlook

Applies to

The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office.

Project type

  • Application-level projects

Microsoft Office version

  • Outlook 2007

For more information, see Features Available by Application and Project Type.

This walkthrough demonstrates how to design a form region in Microsoft Office Outlook, and then import the form region into a Visual Studio Tools for Office 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.

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.

NoteNote:

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.

You need the following components to complete this walkthrough:

  • Visual Studio Tools for Office (an optional component of Visual Studio 2008 Professional and Visual Studio Team System).

  • Microsoft Office Outlook 2007.

NoteNote:

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.

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

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

  2. On the Tools menu, point to Forms, and then click Design a Form.

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

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

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 2007 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 Visual Studio Tools for Office Projects.

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.

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

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

    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 void TaskFormRegion_FormRegionShowing
        (object sender, EventArgs e)
    {
        populateComboBox();
        RefreshTaskListBox();
        this.addDependentTask.Click += new
        Microsoft.Office.Interop.Outlook.
            OlkCommandButtonEvents_ClickEventHandler(AddDependentTask_Click);
    
    }
    

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 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, on the File menu, point to New, 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.

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

Community Additions

ADD
Show:
© 2014 Microsoft