Creating Outlook Form Regions
Let’s turn our attention now to Outlook. As previously mentioned, Outlook has a unique extension point that is not available or relevant in Word or Excel; Outlook add-ins are capable of implementing form regions to any message class within Outlook. A message class is best thought of as the various entities that Outlook defines. These include notes, tasks, email, and so on. Put simply, a form region is the principal mechanism for developers to implement custom form fields within an existing form (for example, email, contact, or other custom forms not included in Outlook by default). To continue with the purchase order example from Word, perhaps a purchase order sent by email should have a set of editable fields and another user interface (UI) associated with it. You can implement those fields and UI in Outlook as a form region. The best way to really understand form regions is to jump right into the task of creating one.
Form regions are implemented by first creating an Outlook add-in project and then adding an Outlook Form Region item. This triggers the Form Region Wizard, which captures the information necessary to autogenerate a region class file. The first screen in the wizard is used to indicate whether you want to create a brand-new form region or use an existing one that was designed in Outlook. For this example, select the Design a New Form option.
The second page in the wizard, shown in Figure 22.11, specifies where the region presents itself. There are four options here, with a graphic that illustrates the positioning behavior of the region. Select Adjoining to create the purchase order UI at the bottom of the Outlook email form.
The third page of the wizard (see Figure 22.12) queries for the name of the region and which inspector display modes the region should support. Inspector is the Outlook term for the window used to view and edit a specific message class. For instance, when you compose a new email message in Outlook, you are actually seeing the email inspector in action.
The fourth and final page of the wizard (see Figure 22.13) associates the form region with any of the built-in Outlook message classes or with a custom message class implemented by a third party. For the purposes of this example, select only the Mail Message entry and click the Finish button.
When finished, Visual Studio generates the code to match the form region properties provided in the wizard. You are now ready to construct the UI for your region.
The visual designer for an Outlook form region looks identical to the Windows Forms Designer: It is essentially a blank canvas onto which you drag controls. So at this point, the typical Windows Forms development process kicks in, enabling you to create the behavior and the look and feel as you need.
No other code is necessary for Outlook to display the form region when the associated message class is invoked. For this example, because we selected the mail message class earlier when we executed the Form Region Wizard, the region automatically shows up anytime we create a new email item (as shown in Figure 22.14).
Runtime Events
Outlook form regions are physically created using a factory pattern. This means they aren’t “newed up” via simple instantiation as we did in the earlier Word task pane example. The form region factory code is located in its code-behind class (called, by default, FormRegion1.cs, but this would obviously change depending on how you have named the project item). In this code file, you find a code region labeled Form Region Factory. And that region contains an important event: FormRegionInitializing. It is within the context of this event that you place any code that should be executed when the form region first loads. Again, in this example, this takes place whenever an email item is displayed.
#region Form Region Factory
[Microsoft.Office.Tools.Outlook.
FormRegionMessageClass
(Microsoft.Office.Tools.Outlook.
FormRegionMessageClassAttribute.Note)]
[Microsoft.Office.Tools.Outlook.FormRegionName
("OutlookAddIn2.FormRegion1")]
public partial class FormRegion1Factory
{
//Occurs before the form region is initialized.
//To prevent the form region from appearing, set e.Cancel to true.
//Use e.OutlookItem to get a reference to the current Outlook item.
private void FormRegion1Factory_FormRegionInitializing
(object sender,
Microsoft.Office.Tools.Outlook.
FormRegionInitializingEventArgs e)
{
//Code to fetch purchase order details could go here.
}
}
#endregion
The other important event is FormRegionShowing. As its name suggests, code within this event executes after the form region is initialized but before it is actually displayed.
//Occurs before the form region is displayed.
//Use this.OutlookItem to get a reference to the current Outlook item.
//Use this.OutlookFormRegion to get a reference to the form region.
private void FormRegion1_FormRegionShowing(object sender, System.EventArgs e)
{
//Code to format purchase order details could go here.
}