- Introduction to Form Regions
- Form Region Types and Custom Message Classes
- Creating an Outlook Forms-Based Form Region
- Outlook Form Region Programmability
- Conclusion
This chapter is from the book
This chapter is from the book
This chapter is from the book
Form Region Types and Custom Message Classes
Table 16-1 summarizes the behaviors and capabilities of the four types of form regions we introduced in the preceding sections. Figure 16-19 shows what the subtasks form region you created in the introduction looks like when it is changed to a Separate form region type. To make this change in Visual Studio, simply click the form region surface in the visual designer and change the FormRegionType property in the property grid. (This property can be a bit hard to find initially; it is a child property of the expandable Manifest property in the property grid.) Now when you open the Task Inspector, an additional Ribbon button appears in the Show group with the name of the separate form region—in this example, Subtasks. Subtasks is not the default page (Task is the default page), but when you click the Subtasks button, the form region page is displayed.
Table 16-1. Behavioral Capabilities of the Four Form Region Types
|
Separate |
Adjoining |
Replacement |
Replace-All |
|
|
Inspector window behavior |
Adds a new page |
Appends to the bottom of the default page |
Replaces the default page |
Replaces all pages |
|
Reading pane behavior |
N/A |
Appends to the bottom of the reading pane |
Replaces the reading pane |
Replaces the reading pane |
|
Can customize standard builtin message classes |
Yes |
Yes |
No—custom message classes only |
No—custom message classes only |
)
Figure 16-19 A Separate form region version of the Subtasks form region.
Built-In and Custom Message Classes
To convert the example form region to a Replacement or Replace-All form region type, you need to learn a little bit more about built-in and custom message classes. The type of all Outlook items is identified by a string value called a message class. Table 16-2 lists the message classes associated with some of the major Outlook item types.
Table 16-2. Built-In Outlook Message Classes
|
Outlook Item Type |
Message Class String |
|
Appointment |
IPM.Appointment |
|
Contact |
IPM.Contact |
|
Distribution List |
IPM.DistList |
|
Journal Entry |
IPM.Activity |
|
Mail Message |
IPM.Note |
|
Post |
IPM.Post |
|
RSS Post |
IPM.Post.RSS |
|
Sharing Invitation |
IPM.Sharing |
|
Task |
IPM.Task |
You can define your own custom message class by defining your own message class string. The message class string must begin with a built-in message class string from Table 16-2 to ensure that you inherit the behavior associated with a built-in message class; Outlook does not support having a “baseless” message class that doesn’t inherit behavior from a built-in Outlook type. Then you append your own unique identifier to the message class string to create a unique message class string. If you want to create a custom message class based on Outlook’s builtin contact type that extends the contact with some information about the Facebook user ID associated with that contact, for example, your message class string might be "IPM.Contact.FacebookAware". The important thing is that your custom message class string start with a built-in message class identifier ("IPM.Contact", for example) and have some additional identifier that won’t be picked by another add-in developer. So you might make it more unique by embedding your company name, as in "IPM.Contact.FacebookAwareAddisonWesley".
You can use these unique string custom message classes to create Outlook items with the Items.Add method on an Outlook Folder object. You can modify the code of the add-in you created in the introduction to edit the ThisAddIn_Startup method so that it creates an Outlook item with a custom message class based on Task, to be called "IPM.Task.MySubTaskAwareTask". Listing 16-3 shows the new ThisAddIn.cs code file.
Listing 16-3. An Outlook Add-In That Creates a New Outlook Item with a Custom Message Class Based on Task
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Xml.Linq;
using Outlook = Microsoft.Office.Interop.Outlook;
using Office = Microsoft.Office.Core;
namespace OutlookAddIn1
{
public partial class ThisAddIn
{
private void ThisAddIn_Startup(object sender,
System.EventArgs e)
{
Outlook.Folder taskList =
Application.Session.GetDefaultFolder(
Outlook.OlDefaultFolders.olFolderTasks)
as Outlook.Folder;
Outlook.TaskItem taskItem = taskList.Items.Add(
"IPM.Task.MySubTaskAwareTask") as Outlook.TaskItem;
taskItem.Subject = "IPM.Task.MySubTaskAwareTask Created On "+
System.DateTime.Now.ToLongDateString();
taskItem.Save();
}
#region VSTO generated code
private void InternalStartup()
{
this.Startup += new System.EventHandler(ThisAddIn_Startup);
}
#endregion
}
}
Now that the Add-in creates a new task with a custom message class on startup, you can modify the form region to be a Replacement form region type. To do this, double-click FormRegion1.cs in the Solution Explorer to activate the form region designer. In the Properties window, pick FormRegion1 in the list of controls. Expand the Manifest section of the Properties window, and set the FormRegion-Type to Replacement.
Now you need to change the FormRegion1Factory so that it associates the form region with the custom message class "IPM.Task.MySubTaskAwareTask" rather than with the built-in message class for a task, "IPM.Task". To do this, you need to edit an attribute of the FormRegion1Factory class. Looking at the FormRegion1Factory class, you see two custom attributes: FormRegionMessage-Class and FormRegionName. FormRegionMessageClass tells the factory what message class to show the form region for. Because you associated the form region with a task when you created it in the form region wizard, the FormRegionMessageClass attribute is set to display for the string specified by the constant Microsoft.Office.Tools.Outlook.FormRegionMessageClassAttribute.Task. This string is a constant string that is set to "IPM.Task". The FormRegionName attribute is set to the fully qualified name of the form region class—in this case, "OutlookAddIn1.FormRegion1". Both custom attributes are shown here:
#region Form Region Factory
[Microsoft.Office.Tools.Outlook.FormRegionMessageClass(
Microsoft.Office.Tools.Outlook.
FormRegionMessageClassAttribute.Task)]
[Microsoft.Office.Tools.Outlook.FormRegionName(
"OutlookAddIn1.FormRegion1")]
public partial class FormRegion1Factory
{
Change the FormRegionMessageClass attribute to take the custom message class string "IPM.Task.MySubTaskAwareTask", as follows:
#region Form Region Factory
[Microsoft.Office.Tools.Outlook.FormRegionMessageClass(
"IPM.Task.MySubTaskAwareTask")]
[Microsoft.Office.Tools.Outlook.FormRegionName(
"OutlookAddIn1.FormRegion1")]
public partial class FormRegion1Factory
{
Now when you run the add-in, a new task with custom message class "IPM.Task.MySubTaskAwareTask" is created in the Startup handler for the addin. When the new task with the custom message class is opened, an Inspector window with the default page replaced is displayed, as shown in Figure 16-20. Note in the Show group on the Ribbon, the default is now the Subtasks form region. The original default page, Task, is no longer visible in the pages that can be shown for the task.
)
Figure 16-20 A Replacement form region version of the Subtasks form region.
Finally, you can go back to the add-in and use the Properties window to set the FormRegionType to Replace-All. When the add-in is run and a task with the custom message class is opened, the Inspector window has all the pages removed except for your form region, as shown in Figure 16-21.
)
Figure 16-21 A Replace-All form region version of the Subtasks form region.