Outlook Form Regions Overview
The features in this topic are available only if you have the required applications installed.
For more information, see.
Use form regions to add custom functionality to standard Microsoft Office Outlook 2007 forms.
Form regions provide a range of options for presenting your custom user interface (UI):
Customize the default page of any standard form.
Add up to 30 extra pages to any standard form.
Replace or enhance any standard form.
Display custom UI in the Reading Pane in addition to the Inspector.
For more information, see "Customizing Form Pages and Form Regions" in 2007 Office System: Updated Developer Content.
Design the layout of a form region by using the Form Region Designer in Outlook 2007. You can then import the form region into an application-level add-in project and use managed code to handle events in the form region. To finish the form region, define form region properties and associate the form region with an Outlook message class.
For a step-by-step guide, see.
Designing the Layout of the Form Region
Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System (VSTO 2005 SE) does not have a form region design surface. As a result, you design the layout of a form region using the Form Region Designer in Outlook 2007. The Form Region Designer generates an Outlook Form Storage (OFS) file. This file describes the controls on the form region, and the positions of those controls.
Reference this file in your Outlook 2007 add-in project to define event handlers for controls on the form region.
Adding Managed Code Behind a Form Region
To add managed code behind a form region, create an Outlook 2007 add-in project. Add a custom class that implements the Microsoft.Office.Interop.Outlook.FormRegionStartup interface. This custom class is called the form region class. Within the form region class, implement methods to perform the following actions:
Return the OFS file to Outlook.
Handle events raised in the form region.
You must then create an instance of the form region class and pass that new object to Outlook. For more information, see.
Returning the OFS file to Outlook
Outlook calls the FormRegionStartup.GetFormRegionStorage method to obtain the OFS file that describes the form region. To return the OFS file to Outlook, override the FormRegionStartup.GetFormRegionStorage method in the form region class.
When you create an Outlook add-in, you can add the OFS file to the resource collection of the Outlook add-in project. If you do this, you can return the contents of the OFS file to Outlook as a byte array. The following example overrides the FormRegionStartup.GetFormRegionStorage method and returns the contents of an OFS file that is named TaskFormRegion from the resource collection of an add-in project.
Public Function GetFormRegionStorage( _ ByVal FormRegionName As String, _ ByVal Item As Object, _ ByVal LCID As Integer, _ ByVal FormRegionMode As Outlook.OlFormRegionMode, _ ByVal FormRegionSize As Outlook.OlFormRegionSize) As Object _ Implements Outlook.FormRegionStartup.GetFormRegionStorage Application.DoEvents() Select Case FormRegionName Case "TaskFormRegion" Dim ofsBytes As Byte() ofsBytes = My.Resources.TaskFormRegion Return ofsBytes Case Else Return Nothing End Select End Function
If the OFS file is not a resource in your Outlook 2007 add-in project, return the string path of the OFS file. This path can contain environment variables, but the file must be local. The path can be either absolute or relative to the location of the form region manifest. The form region manifest is discussed later in this topic.
Handling Events Raised in the Form Region
Outlook calls the FormRegionStartup.BeforeFormRegionShow method before it displays the form region. Override this method in the form region class to handle events raised by user actions in the form region. Use the FormRegion parameter to obtain the controls defined in the form region.
The following example overrides the BeforeFormRegionShow method. The code in this method assigns controls from the form region to fields defined in the add-in. This code also registers an event handler for a command button on the form region.
Private FormRegion As Outlook.FormRegion Private userForm As UserForm Private OlkTextBox1 As Outlook.OlkTextBox Private WithEvents CommandButton1 As Outlook.OlkCommandButton Public Sub BeforeFormRegionShow( _ ByVal FormRegion As Outlook.FormRegion) _ Implements Outlook.FormRegionStartup.BeforeFormRegionShow Me.FormRegion = FormRegion Me.userForm = FormRegion.Form Try OlkTextBox1 = userForm.Controls.Item("OlkTextBox1") CommandButton1 = userForm.Controls.Item("CommandButton1") Catch ex As Exception MessageBox.Show(ex.ToString()) End Try End Sub
Returning the Form Region Object to Outlook
Outlook queries the add-in to find objects that implement the Microsoft.Office.Interop.Outlook.FormRegionStartup interface. To return one of these objects to Outlook, override the
ThisAddIn class. If you do not return an object that implements the Microsoft.Office.Interop.Outlook.FormRegionStartup interface in this method, Outlook will not locate the form region.
The following example overrides the RequestService method and returns the form region class to Outlook.
Defining Form Region Properties Using a Form Region Manifest
To define the properties of a form region, create a form region manifest.
A form region manifest is an XML file that contains information that Outlook must have to load the form region.
Use the manifest to define properties such as these:
Form region type.
For a step-by-step guide that shows how to create a form region manifest, see 2007 Office System: XML Schema Reference.. For details about the schema, see
Associating the Form Region with an Outlook Message Class
An Outlook message class identifies a standard Outlook form. To specify when the form region appears, associate the form region with one or more message classes. For instance, you might want to display a form region when a user opens a mail item in Outlook. To do this, associate that form region with the IPM.Note message class. Create this association by adding entries to the registry. For more information about message classes, see "Item Types and Message Classes" in 2007 Office System: Updated Developer Content.
A quick way to add entries is to put them in a registry file and then run the file. For an example, see.
The registry modifications must include the following items:
A key for each Outlook message class that is associated with one or more form regions.
An entry for each form region and an associated value that represents the location of the form region manifest.
The following example shows the contents of a registry file. These entries associate an Outlook message class with a form region.
Windows Registry Editor Version 5.00 [HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\FormRegions\IPM.Task] "TaskFormRegion"="C:\\FormRegionWalkthrough\\FormRegionAddIn\\manifest.xml"
You can associate one Outlook message class with several form regions. You can also associate one form region with several Outlook message classes.
You can also create a new custom message class that is based on an existing message class. A new custom message class inherits all the form regions that are associated with the base message class. This also works for end users who create forms by using the form designer in Outlook, if they base the new form on a customized form. Their new forms will inherit the custom form regions that are associated with the base form.