Introduction
In this article I will explain how to add custom property pages to Outlook
2003. PropertyPages can either be added to the Outlook Options dialog box or to
the folder Properties dialog box.
I assume you have a running Outlook Add-In , creating an Outlook Add-In is
beyond the scope of this article. There are plenty of good articles covering
this topic.
OptionsPagesAdd
Event
You need to handle the OptionsPagesAdd
Event to add a custom
property page. This event is either raised by your application object or
by your namespace object. If you want to add a custom property page to
the Outlook Option dialog you have to handle the OptionsPagesAdd
event from the application object, if you want to add it the folder
properties dialog box you handle the event raised by the namespace object.
applicationObject.OptionsPagesAdd +=
new ApplicationEvents_11_OptionsPagesAddEventHandler(
applicationObject_OptionsPagesAdd);
private void applicationObject_OptionsPagesAdd(PropertyPages Pages){}
NameSpace ns = applicationObject.GetNamespace("MAPI");
ns.OptionsPagesAdd +=
new NameSpaceEvents_OptionsPagesAddEventHandler(ns_OptionsPagesAdd);
private void ns_OptionsPagesAdd(
PropertyPages Pages, MAPIFolder Folder){}
Adding a Custom property page
We will use the PropertyPages
add
method to add a
custom property page object to the collection.
Page.Add(object page, string title);
The first parameter of the add method expects an object representing our
custom property page. We create our property page by implementing the the
Outlook.PropertyPage
interface. Furthermore to have a convenient
way of adding controls to our property page we inherit from
System.Windows.Forms.UserControl
.
Creating a custom property class
public class MyOptionPage : System.Windows.Forms.UserControl ,
Outlook.PropertyPage {}
The PropertyPage
Interface expects us to implement three
methods:
public bool Dirty
public void GetPageInfo(ref string HelpFile, ref int
HelpContext)
public void Apply()
The is Dirty
property returns true
if the contents
of your property page have been altered. Microsoft Outlook queries this property
in order to decide if the Apply Button will be visible or not.
With the GetPageInfo
method you can specify the Help file
associated with the property page.
Within the Apply
method you write the code that implements how
to react on user changes. e.g. store the values to the registry, or write config
files etc.
Our custom PropertyPage
would now look something this. I assume
you added a button to the PropertyPage
. The following code is
simplified for better readability. Take a look at the sourcecode for the full
code.
public class MyOptionPage : System.Windows.Forms.UserControl ,
Outlook.PropertyPage
{
private bool isDirty;
public MyOptionPage()
{ InitializeComponent();
isDirty = false;
}
public bool Dirty{get{return isDirty;}}
public void Apply() { MessageBox.Show("Hello World"); }
private void button1_Click(object sender, System.EventArgs e)
{ isDirty = true; }
}
Is it working ?
We can now try to add the custom property page.
Pages.Add(new MyOptionPage(),"Hello");
Our new tab is named "Unnamed"
Even though our new tab is displayed in the property dialog , its name is set
to "Unnamed". For unknown reasons the second parameter of the add
Method is ignored. We need to implement a custom caption property in our
MyOptionPage
class to make Outlook display the desired Tab
Name.
[DispId(-518)]
public string Caption
{
get{return "DEMO";}
}
You have to add using System.Runtime.InteropServices
to be able
to use the DispID
Attribute.
Clicking the button does not enable the Apply button
Another issue we have to fix is the fact that even if press our Button and
thus setting isDirty=true
Outlook is not enabling the Apply
Button.
According to MSDN Microsoft Outlook queries the Dirty
property
in response to the OnStatusChange method of a PropertyPageSite object.
Getting the PropertyPageSite
object
Unfortunately the PropertyPageSite
object is an unsafe private
field , we have to use reflection to get access to it.
Define a member variable private Outlook.PropertyPageSite
ppSite
and put the following code in your Load event of you MyOptionPage
class:
Type myType = typeof(System.Object);
string assembly =
System.Text.RegularExpressions.Regex.Replace(myType.Assembly.CodeBase,
"mscorlib.dll", "System.Windows.Forms.dll");
assembly = System.Text.RegularExpressions.Regex.Replace(
assembly, "file:///", "");
assembly = System.Reflection.AssemblyName.GetAssemblyName(
assembly).FullName;
Type unmanaged =
Type.GetType(System.Reflection.Assembly.CreateQualifiedName(
assembly, "System.Windows.Forms.UnsafeNativeMethods"));
Type oleObj = unmanaged.GetNestedType("IOleObject");
System.Reflection.MethodInfo mi = oleObj.GetMethod("GetClientSite");
object myppSite = mi.Invoke(this, null);
this.ppSite = (Outlook.PropertyPageSite)myppSite;
Calling the OnStatusChange()
method of the PropertyPage
object
When the user clicks our button we now can call the OnStatusChange
method after setting isDirty = false
.
private void button1_Click(object sender, System.EventArgs e)
{ isDirty = true; ppSite.OnStatusChange();}
Final Notes
Adding custom property pages to Outlook 2003 is a little tricky, mainly
because of the not directly exposed PropertyPageSite
object.
I hope you find the article useful and I am looking forward to your feedback.