Guidelines for Creating Outlook Form Regions

Guidelines for Creating Outlook For...

Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0)

Updated: November 2007

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.

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.

The following information can help you optimize your form regions and avoid potential problems:

Using form region names.
Disabling form region inheritance.
Understanding Types and Message Class Names.
Designing adjoining form regions for the reading pane.
Using optimal icon sizes.

For more information about form regions, see Creating Outlook Form Regions.

Using Form Region Names

There are several names used to describe the form region. It is important to understand the difference between these names and how they affect the form region. The following table describes each name.

Form region name	Description
Form region item name	The name that you specify for the Outlook Form Region item in the Add New Item dialog box. This is the name of the form region code file that appears in Solution Explorer.
FormRegionName property	You specify this name in the Supply descriptive text and select your display preferences page of the New Outlook Form Region wizard. This name appears as the FormRegionName property in the Properties window. Use the FormRegionName property to specify the label that identifies the form region in the Outlook user interface (UI). For separate form regions, this name appears as a button on the Ribbon of the Outlook item. For adjoining form regions, this name appears as header text above the form region.
Microsoft.Office.Tools.Outlook.FormRegionName attribute	When you add an Outlook Form Region item to the project, Visual Studio Tools for Office sets this property to the fully qualified name of the form region. The default fully qualified name is the name of the add-in connected to the name of the form region by a dot—for example, OutlookAddIn1.FormRegion1. This fully qualified name also appears as an attribute at the top of the form region factory class. Use the Microsoft.Office.Tools.Outlook.FormRegionName attribute to uniquely identify the form region across all Outlook add-ins. You cannot change the value of the Microsoft.Office.Tools.Outlook.FormRegionName attribute by renaming the form region item or by changing the FormRegionName property. To change this name, you must modify the Microsoft.Office.Tools.Outlook.FormRegionName attribute in the form region code file.

Form region name

Description

Form region item name

The name that you specify for the Outlook Form Region item in the Add New Item dialog box. This is the name of the form region code file that appears in Solution Explorer.

FormRegionName property

You specify this name in the Supply descriptive text and select your display preferences page of the New Outlook Form Region wizard. This name appears as the FormRegionName property in the Properties window.

Use the FormRegionName property to specify the label that identifies the form region in the Outlook user interface (UI). For separate form regions, this name appears as a button on the Ribbon of the Outlook item.

For adjoining form regions, this name appears as header text above the form region.

Microsoft.Office.Tools.Outlook.FormRegionName attribute

When you add an Outlook Form Region item to the project, Visual Studio Tools for Office sets this property to the fully qualified name of the form region. The default fully qualified name is the name of the add-in connected to the name of the form region by a dot—for example, OutlookAddIn1.FormRegion1.

This fully qualified name also appears as an attribute at the top of the form region factory class.

Use the Microsoft.Office.Tools.Outlook.FormRegionName attribute to uniquely identify the form region across all Outlook add-ins. You cannot change the value of the Microsoft.Office.Tools.Outlook.FormRegionName attribute by renaming the form region item or by changing the FormRegionName property. To change this name, you must modify the Microsoft.Office.Tools.Outlook.FormRegionName attribute in the form region code file.

Disabling Form Region Inheritance

By default, a custom message class inherits all the form region associations of the base message class. For example, a message class named IPM.Task.Contoso derives from IPM.Task. Therefore, IPM.Task.Contoso inherits the form region associations of IPM.Task.

If you do not want the form region to be associated with any derived message classes, set the ExactMessageClass property of the form region to true. For example, if you associate an adjoining form region with IPM.Task and set the ExactMessageClass property to true, the form region will only be appended to the bottom of a standard task form. The form region will not be appended to the bottom of any customized versions of a standard task form.

Understanding Types and Message Class Names

The type name of an Outlook item differs from the message class name of an Outlook item. For example, the type name of an RSS item is Microsoft.Office.Interop.Outlook.PostItem. The message class name of an RSS item is IPM.Post.RSS.

Use the type name to reference an Outlook item in code. For a list of type names, see Associating a Form Region with an Outlook Message Class.

Use the message class name of Outlook items in the New Outlook Form Region wizard to associate the item with the form region. For a list of valid message class names, see Associating a Form Region with an Outlook Message Class.

Designing Adjoining Form Regions for the Reading Pane

You can use the Outlook Reading Pane to preview an Outlook item without opening the item. The Reading Pane is designed for reading only. Therefore, input controls that you add to an adjoining form region, such as a text box, might not behave as expected when the item and form region are open in the Reading Pane.

For example, if an item that has an adjoining form region is open in the Reading Pane, the following situation is possible:

Select some text in a textbox that is on the form region.
Press DELETE.
The entire mail item is deleted instead of the text in the textbox.

If you are designing an adjoining form region that contains input controls, test the controls in the Reading Pane to ensure they work properly. Consider adding custom code that disables controls that do not behave as expected.

Alternatively, you can set the ShowInspectorRead property of the form region to False. This way the form region cannot be used in the Reading Pane.

Using Optimal Icon Sizes

You can specify which icons you want the form region to display by setting icon properties in the Icons property group of the Properties window. Use the following guidelines to achieve the best visual quality: