Add commnadbar button, Outlook 2007 ribbon bar, tabs.
Building Outlook addin / plug-in in Delphi.

Add-in Express Home > Add-in Express VCL > Online Guide > Building Outlook plugins

Outlook add-ins in Delphi

Outlook is a target application for Add-in Express. In this view, Add-in Express offers additional features for Outlook, namely for:

• Extending Outlook 2007 UI
• Enhancing Outlook To-Do bar and Navigation pane
• Customizing Outlook forms and views

When building Outlook add-ins / plugins you frequently need to add one or more command bars of your own and populate them as well as built-in command bars with commandbar controls. Sometimes you need to add a property page. True, it can be done by implementing IDTExtensibility2, but it requires deep understanding of the Outlook Object Model as well as thorough testing under different Outlook versions. To simplify these tasks for Outlook developers, Add-in Express VCL provides a special wizard and several Outlook specific classes that allow extending Outlook menus and toolbars at the application level and extending property pages for folders and the main Options page.

Step #1 – Build an Outlook COM add-in project

To build an Outlook COM add-in project, in the Borland Delphi IDE, close all opened projects, choose File | New | Others menu item, select the Add-in Express VCL tab in the New Items window, and double-click the MS Outlook COM add-in icon to start the wizard.

 
Enter your project name, the add-in coclass name and the destination folder for the add-in project in the wizard window, and click Next.

 
Additionally, the Outlook Add-in wizard allows creating property pages for the Options (Tools | Options menu) and folder Properties dialogs.

 
The wizard builds and opens the Outlook COM add-in project in the Delphi IDE.

 
The add-in project includes the following items:

• The project source files (ProjectName.*).
• The type library files: binary (ProjectName.tlb) and Object Pascal unit (ProjectName_TLB.pas).
• The Outlook COM add-in module (ProjectName_IMPL.pas and ProjectName_IMPL.dfm) discussed in the next step. 
• The Outlook Property Page (PropertPage_IMPL.pas and PropertPage_IMPL.dfm) described in Step #10 - Adding folder property pages .

Step #2 – Add-in Express COM Add-in module

The COM Add-in module (MyOutlookAddin1_IMPL.pas and MyOutlookAddin1_IMPL.dfm) is the core part of the COM add-in project. It is the container of the Add-in Express components, which allow you to concentrate on the functionality of your add-in. You specify add-in properties in the module's properties, add Add-in Express components to the module's designer, and write the functional code of your add-in in this module. The code for MyAddin1_IMPL.pas is as follows:

unit MyOutlookAddin1_IMPL;
interface
uses
  SysUtils, ComObj, ComServ, 
  ActiveX, Variants, adxAddIn, 
  MyOutlookAddin1_TLB, Outlook2000;
type
  TcoMyOutlookAddin1 = class(TadxAddin, IcoMyOutlookAddin1)
  end;
  TAddInModule = class(TadxCOMAddInModule)
    procedure adxCOMAddInModuleAddInInitialize(Sender: TObject);
    procedure adxCOMAddInModuleAddInFinalize(Sender: TObject);
  private
  protected
    procedure NameSpaceOptionsPagesAdd(ASender: TObject;
      const Pages: PropertyPages; const Folder: MAPIFolder); override;
  public
  end;
var
  adxcoMyOutlookAddin1: TAddInModule;
implementation
{$R *.dfm}
procedure TAddInModule.adxCOMAddInModuleAddInInitialize(Sender: TObject);
begin
  adxcoMyOutlookAddin1 := Self;
end;
procedure TAddInModule.adxCOMAddInModuleAddInFinalize(Sender: TObject);
begin
  adxcoMyOutlookAddin1 := nil;
end;
procedure TAddInModule.NameSpaceOptionsPagesAdd(ASender: TObject;
  const Pages: PropertyPages; const Folder: MAPIFolder);
  function GetFullFolderName(const AFolder: MAPIFolder): string;
  var
    IDisp: IDispatch;
    Folder: MAPIFolder;
  begin
    Result := '';
    Folder := AFolder;
    while Assigned(Folder) do begin
      Result := '\' + Folder.Name + Result;
      IDisp := Folder.Parent;
      IDisp.QueryInterface(IID_MAPIFolder, Folder);
    end;
    if Result <> '' then Delete(Result, 1, 1);
  end;
begin
  Pages.Add('MyOutlookAddin1.coPropertyPage1', 'My Property Page');
end;
initialization
  TadxFactory.Create(ComServer, TcoMyOutlookAddin1, 
		CLASS_coMyOutlookAddin1, TAddInModule);
end.

The add-in module contains two classes: the “interfaced” class (TcoMyOutlookAddin1 in this case) and the add-in module class (TAddInModule). The “interfaced” class is a descendant of the TadxAddIn class that implements the IDTExtensibility2 interface required by the COM Add-in architecture. Usually, you don't need to change anything in the TadxAddIn class.

The add-in module class implements the add-in functionality. It is an analogue of the Data Module, but unlike the Data Module, the add-in module allows you to set all properties of your Outlook add-in, handle its events, and create toolbars and controls.

Step #3 – Add-in Express COM Add-in designer

The designer of Outlook COM Add-in Module allows setting add-in properties and adding components to the module. To add an Add-in Express component to the AddinModule designer, you select it in the Tool Palette and drag-n-drop onto the designer.

Step #4 – Add a new Explorer CommandBar

Taking into account the specificity of Outlook, Add-in Express provides a special commandbar component, TadxOlExplorerCommandBar, that adds custom command bars or connects to built-in commandbars in the Outlook Explorer windows. The component adds context-sensitivity to your command bars through the FolderName(s) and ItemTypes properties.

To add a command bar to the Outlook Explorer window, use the TadxOlExplorerCommandBar component from the Add-in Express group in the Tool Palette.

 
Select the Add-in Express Outlook Explorer Command Bar component, and, in the Object Inspector window, specify the commandbar name using the CommandBarName property and choose its position. Outlook-specific versions of Add-in Express Command Bar component provides context-sensitive properties. They are FolderName, FolderNames, and ItemTypes.

 
In the screenshot above, you see the Outlook Explorer commandbar that will be shown for every Outlook folder (FolderName = '') the default item types of which are Mail or Task.

Step #5 – Add a new CommandBar button

To add a new button to the Outlook Explorer command bar, in the Object Inspector window, you run the property editor for the Controls property.

The editor allows adding Command Bar controls in a simple way.

Specify the button's Caption property and set the Style property to adxMsoButtonIconAndCaption. To handle the Click event of the button, In the Object Inspector window, switch to the Events tab and add the Click event handler:

procedure TAddInModule.adxCommandBar1Controls0Click(Sender: TObject);
begin
end;

Step #6 – Access Outlook objects

The Add-in Module provides the <HostName>App properties that return the Application object (of the OleVariant type) of the host application the add-in is currently running in. For your convenience, Add-in Express provides the OutlookApp property of the TOutlookApplication type. This allows you to write the following code to the Click event of the button just added.

procedure TAddInModule.adxOlExplorerCommandbar1Controls0Click(Sender: TObject);
begin
  ShowMessage('The subject is ' +
    OleVariant(Self.OutlookApp.ActiveExplorer.Selection.Item(1)).Subject);
end;

Step #7 – Handle Outlook events

Add-in Express has several components that provide the application-level events for the COM Add-in module. To add Outlook events to the add-in, find the TadxOutlookAppEvents component in the Tool Palette and drag-n-drop it onto the module.

With the Outlook Events component, you handle any application-level events of the Outlook. For instance, the following code handles the BeforeFolderSwitch event of the Outlook Explorer class:

procedure TAddInModule.adxOutlookAppEvents1ExplorerBeforeFolderSwitch(
  ASender: TObject; const NewFolder: IDispatch; var Cancel: WordBool);
begin
    ShowMessage('You are switching to the '
      + (NewFolder as MAPIFolder).Name + ' folder');
end;

Step #8 – Add a new Inspector CommandBar

Considering the specificity of Outlook, Add-in Express provide a special command bar component, TadxOlInspectorCommandBar, that offers the same capabilities as its Explorer counterpart: it adds custom command bars or connects to built-in ones in the Outlook Inspector windows. The component adds context-sensitivity to your command bars through the FolderName(s) and ItemTypes properties.

To add a commandbar to Outlook Explorer window, use the TadxOlExplorerCommandBar component from the Add-in Express group in the Tool Palette.

The Inspector commandbar component provides the same properties as the Explorer command bar component. In the screenshot below you see the default values for the Inspector command bar.

Add a new command bar button to the command bar (see Step #5 – Adding a new command bar button).

Now you can show the subject of the currently open mail item using the following code that handles the Click event of the button:

procedure TAddInModule.adxOlInspectorCommandBar1Controls0Click(Sender: TObject);
begin
  ShowMessage('The subject is ' +
    OleVariant(Self.OutlookApp.ActiveInspector.CurrentItem).Subject);
end;

Outlook Inspector Command Bars in Outlook 2007

To display an Inspector command bar in Office 2007 you must explicitly set the UseForRibbon property of the command bar component to True.

Step #9 – Handle events of Outlook Items object

The Outlook2000 unit provides the TItems component (of the TOleServer type). This component provides the following events: OnItemAdd, OnItemChange, and OnItemRemove. To process these events, you add the following declarations and code to the Add-in Module:

  TAddInModule = class(TadxCOMAddInModule)
...
  private
    Items: TItems;
    procedure ItemsAdd(ASender: TObject; const Item: IDispatch);
    function GetItemsConnected(): boolean;
  public
    procedure ConnectItems;
    procedure DisconnectItems;
    property AreItemsConnected: boolean read GetItemsConnected;
  end;
...
procedure TAddInModule.adxCOMAddInModuleAddInStartupComplete(Sender: TObject);
begin
  ConnectItems;
end;
procedure TAddInModule.adxCOMAddInModuleAddInBeginShutdown(Sender: TObject);
begin
    DisconnectItems;
end;
procedure TAddInModule.ConnectItems;
begin
  Items := TItems.Create(nil);
  Items.OnItemAdd := ItemsAdd;
  Items.ConnectTo(
    Self.OutlookApp.GetNamespace('Mapi').
      GetDefaultFolder(olFolderInbox).Items);
end;
procedure TAddInModule.DisconnectItems;
begin
  if not Assigned(Items) then exit;
  Items.Disconnect;
  Items.Free();
  Items := nil;
end;
function TAddInModule.GetItemsConnected: boolean;
begin
  Result := false;
  if Assigned(Items) then
    Result := Items.DefaultInterface <> nil;
end;
procedure TAddInModule.ItemsAdd(ASender: TObject; const Item: IDispatch);
begin
    ShowMessage('The item with subject "'
      + OleVariant(Item).Subject
      + '" has been added to the Inbox folder');
end;

Step #10 – Add folder property pages

Outlook allows you to add custom option pages to the Options dialog box (the Tools | Options menu) and / or to the Properties dialog box of any folder. To automate this task, the Add-in Express wizard provides you with the Option Pages window (see Step #1 – Building an Outlook COM add-in project).

By default, an option page contains two controls only: a label and an edit box.

The edit box shows how to handle the OnChange event and update the corresponding option page. 

procedure TcoPropertyPage1.Edit1Change(Sender: TObject);
begin
  GetPropertyPageSite;
  // TODO - put your code here
  UpdatePropertyPageSite;
end;

You add the TCheckBox component to the Property page, handle its OnClick event following the code template above, and connect or disconnect the TItems component in the Apply method. You initialize the check box using the OnCreate event of the property page:

procedure TcoPropertyPage1.ActiveFormCreate(Sender: TObject);
begin
  CheckBox1.Checked := adxcoMyOutlookAddin1.AreItemsConnected;
end;
function TcoPropertyPage1.Apply: HResult;
begin
  if CheckBox1.Checked then
    adxcoMyOutlookAddin1.ConnectItems
  else
    adxcoMyOutlookAddin1.DisconnectItems;
  FDirty := False;
  Result := S_OK;
end;

Finally, you change the NameSpaceOptionsPagesAdd event handler in the AddinModule code as follows:

procedure TAddInModule.NameSpaceOptionsPagesAdd(ASender: TObject;
  const Pages: PropertyPages; const Folder: MAPIFolder);
...
begin
  if Folder.EntryID =
    Self.OutlookApp.GetNamespace('Mapi').
    GetDefaultFolder(olFolderInbox).EntryID
  then
    Pages.Add('MyOutlookAddin1.coPropertyPage1', 'My Property Page');
end;

Step #11 – Intercept keyboard shortcut

To intercept a keyboard shortcut, you add an ADXKeyboardShortcut component to the COM Add-in Module using the Add Keyboard Shortcut command of the module.

 
In the Object Inspector window you select (or enter) the desired shortcut in the ShortcutText property. We chose the shortcut for the Send button in the mail Inspector's Standard command bar. It is Ctrl+Enter.

HandleShortcuts property

To use keyboard shortcuts, you need to set the HandleShortcuts property of AddinModule to true. Now you handle the Action event of the component:

procedure TAddInModule.adxKeyboardShortcut1Action(Sender: TObject);
begin
  ShowMessage('You`ve pressed ' +
    TadxKeyboardShortcut(Sender).ShortcutText);
end;

Step #12 – Customize the Outlook 2007 Ribbon user interface

To add a new tab to the Outlook 2007 Ribbon, you add the TadxRibbonTab component to the module.

 
In the Object Inspector window, run the editor for the Controls collection of the tab. In the editor, use the toolbar buttons or context menu to add or delete Add-in Express components that form the Ribbon interface of your Outlook add-in. First, you add a Ribbon tab and change its caption to My Ribbon Tab. Then, you select the tab component, add a Ribbon group, and change its caption to My Ribbon Group. Next, you select the group, and add a button group. Finally, you select the button group and add a button. Set the button caption to My Ribbon Button. Use the ImageList and Image properties to set the icon for the button.

 
Now add the event handler to the Click event of the button. Write the following code:

procedure TAddInModule.adxRibbonTab1Controls0Controls0Controls0Click(
	Sender: TObject; const RibbonControl: IRibbonControl);
begin
  adxOlInspectorCommandBar1Controls0Click(nil);
end;

Remember, the TadxRibbonTab Controls editor perform the XML-schema validation automatically, so from time to time you will run into the situation when you cannot add a control to some Ribbon level. It is a restriction of the Ribbon XML-schema.

Note, unlike other Ribbon-based applications, Outlook has numerous ribbons. Please use the Ribbons property of your TadxRibbonTab components to specify the ribbons you customize with your tabs.

Step #13 – Add custom task panes in Outlook 2007

You specify custom task panes in the project wizard (see also Adding a task pane to an existing Add-in Express project). The wizard adds an ActiveX to your project, a TadxCustomTaskPane to the TaskPanes collection of the Add-in Module, and binds the ActiveX to the TadxCustomTaskPane. Here are the TadxCustomTaskPane properties you usually need:

• Title - the caption of your task pane (required!)
• Height, Width - the height and width of your task pane (applies to horizontal and vertical task panes, correspondingly)
• DockPosition - you can dock your task pane to the left, top, right, or bottom edges of the host application window
• ControlProgID - the ActiveX just added

This sample add-in has the following task pane settings:

The TadxCustomTaskPane.Instances collection allows you to access all task pane instances (of the TadxCustomTaskPaneInstance type). When you set, say, the height or dock position of the TadxCustomTaskPane, these properties apply to every TadxCustomTaskPaneInstance that the host application shows. You can also modify these properties on the instance level. To get the instance, you supply TadxCustomTaskPane..Instances.Items property with the TExplorer.or TInspector you get via, say, TOutlookApplication.ActiveWindow.

For instance, the RefreshTaskPane method in the samples' add-in module finds the currently active instance of the task pane and refreshes its InfoString property (it just sets the caption of a label on the task pane control). For the task pane to be refreshed in a consistent manner, this method is called in appropriate event handlers.

procedure TAddInModule.RefreshTaskPane(const ExplorerOrInspector: IDispatch);
var 
  ITaskPane: IMyTaskPane;
  TaskPaneInstance: TadxCustomTaskPaneInstance;
begin
  if (FVersion = '12.0') and (ExplorerOrInspector <> nil) and
     (TaskPanes.Count > 0) then
  begin
    TaskPaneInstance := TaskPanes[0].Instances[ExplorerOrInspector];
    if Assigned(TaskPaneInstance) then begin
      TaskPaneInstance.Control.QueryInterface(IMyTaskPane, ITaskPane);
      if Assigned(ITaskPane) then begin
        ITaskPane.InfoString := 'Subject: ' + 
          GetSubject(ExplorerOrInspector);
        ITaskPane := nil;
      end;
    end;
  end;
end;

Read more about creating custom task panes.

Step #14 – Run the Outlook add-in

Save the add-in project, compile it, close Outlook, and register the add-in using the Run | Register ActiveX Server menu item. Run Outlook and find your option page, command bars, and controls. You find your add-in in the COM Add-ins dialog:

Step #15 – Debugging the Outlook add-in

To debug your add-in, just indicate the add-in host application in the Host Application field in the Project Options window.

Step #16 – Deploying the Outlook add-in

Make sure your setup project registers the add-in DLL. Say, in Inno Setup projects you use the 'regserver' command.

Back to Add-in Express VCL homepage