How to build Office 2007-2000 add-in / plugin in Delphi.
Customize Ribbon UI, create command bar and task panes.

Add-in Express Home > Add-in Express VCL > Online Guide > Creating your first Office add-in in Delphi

Your first Office COM add-in in Delphi

COM add-in development in Delphi is not a visual process. But Add-in Express VCL makes Office add-in development visual and therefore more comfortable and easy. How can this be achieved? With ease. Let's go!

This page highlights almost every aspect of creating COM add-ins for Microsoft Office 2007 - 2000 applications, namely adding a custom button to Office commandbar, customizing the Office 2007 Ribbon interface, creating task panes, handling host application events and more. You can find the sample add-in described on this page in the Docs \ Samples folder of the Add-in Express install folder. This example shows a COM Add-in project implementing a COM add-in for Excel and Word.

Please keep in mind that note, Add-in Express provides special components for customizing the Outlook GUI, namely for extending Outlook Today, Reading and Navigation pane, for modifying Outlook mail, task and contact forms etc. For more information please see step-by-step instructions for creating a sample Outlook plug-in.

Step #1 – Creating a COM Add-in project in Delphi

You create Add-in Express projects using the wizards located on the Add-in Express VCL tab of the New Item dialog. To access this dialog, open Borland Delphi for Microsoft Windows and choose the File | New | Other item. To create a Microsoft Office COM add-in, you double-click on the Add-in Express COM Add-in icon.

 
When the wizard starts, you choose the project options in the wizard windows. The options include project location, project name, and coclass name. Also, you can add custom task panes (Office 2007 only) to your project: just specify their coclasses and titles.

 
The wizard creates and opens your project in the Delphi IDE.

 
The COM 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 COM add-in module (ProjectName_IMPL.pas and ProjectName_IMPL.dfm) described in the next step

Step #2 – Reviewing the Add-in module

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

unit MyAddin1_IMPL;

interface

uses
  SysUtils, ComObj, ComServ, ActiveX, Variants, adxAddIn, MyAddin1_TLB;

type
  TcoMyAddin1 = class(TadxAddin, IcoMyAddin1)
  end;

  TAddInModule = class(TadxCOMAddInModule)
  private
  protected
  public
  end;

implementation

{$R *.dfm}

initialization
  TadxFactory.Create(ComServer, TcoMyAddin1, CLASS_coMyAddin1,
  TAddInModule);

end. 

The add-in module contains two classes: the “interfaced” class (TcoMyAddin1 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 Office add-in, handle its events, and create toolbars and controls.

Step #3 – Customizing the Add-in module

The COM Add-in module allows setting add-in properties and adding components to the module. Select the module and, in the Object Inspector window, specify the add-in name using the AddinName property. This name will appear in the COM add-ins dialog box of the host applications. Also, choose the SupportedApps property and select Excel and Word.

 
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. You can add the following Add-in Express components to the designer:

• TadxRibbonTab – represents a Ribbon tab in your add-in 
• TadxRibbonQAT – represents the Ribbon Quick Access Toolbar your add-in 
• TadxRibbonOfficeMenu – represents the Ribbon Office Menu in your add-in 
• TadxCommandBar – represents a command bar in your add-in 
• TadxOlExplorerCommandBar – represents an Outlook Explorer command bar in your add-in 
• TadxOlInspectorCommandBar – represents an Outlook Inspector command bar in your add-in 
• TadxBuiltInControl – allows intercepting the action of a built-in control of the host application(s) 
• TadxKeyboardShortcut – allows intercepting application-level keyboard shortcuts 
• TadxOlBarShortcutManager – allows adding Outlook Bar shortcuts and shortcut groups 
• TadxOlFormsManager – embedding custom VCL forms into Outlook windows 
• Application Events – adds or deletes components that provide access to application-level events of the add-in host applications

Step #4 – Adding a new command bar

To add a command bar to your Office add-in, find the TadxCommandBar component in the Tool Palette and drag-n-drop it onto the TadxCOMAddinModule designer.

 
Select the command bar component and, in the Object Inspector window, specify the command bar name using the CommandBarName property. Also, you select its position in the Position property.

 
To display a command bar in Office 2007, you need to explicitly set the UseForRibbon property of the command bar component to True.

Step #5 – Adding a new command bar button

To add a new button to a command bar, in the Object Inspector window, you run the property editor of the Controls property for an appropriate command bar component. The property editor is a simple and easy designer of command bars and their controls.

Specify the button's Caption property and set the Style property to adxMsoButtonIconAndCaption (default value = adxMsoButtonAutomatic). To handle the Click event of the button, in the Object Inspector window, switch to the Events tab and add the Click event handler: The code of the event handler follows below (it's empty as you can see)

procedure TAddInModule.adxCommandBar1Controls0Click(Sender: TObject);
begin

end;

Step #6 – Accessing host application objects

The Add-in Module provides the HostApplication property that returns 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 <HostName>App properties, say ExcelApp of the TExcelApplication type and WordApp of the TWordApplication type. Together with the HostType property, this allows us to write the following code to the Click event of the button just added.

procedure TAddInModule.adxCommandBar1Controls0Click(Sender: TObject);
begin
    case Self.HostType of
      ohaExcel:
        ShowMessage('The current cell is '
          + Self.ExcelApp.ActiveCell.AddressLocal
            [False, False, xlA1, EmptyParam, EmptyParam]);
      ohaWord:
        if Self.WordApp.Selection <> nil then
          ShowMessage('There are '
            + IntToStr(Self.WordApp.Selection.Words.Count)
            + ' words currently selected');
      else
        ShowMessage(Self.AddInName 
     + ' doesn`t support the current host application');
    end;
end;

Step #7 – Handling host application events

Add-n Express provides several components that provide the application-level events for the COM Add-in Module. To add Excel events to the add-in, find the TadxExcelAppEvents component in the Tool Palette and drag-n-drop it onto the module. The TadxWordAppEvents component supplies the module with Word events.

 
With the Events components, you handle any application-level events of the host application. You might see that the Click event handler in the previous step will fire an exception when there are no workbooks or documents open. To prevent this, you disable the button when a window deactivates and enable it when a window activates. This covers the situations mentioned above. The code is as follows:

procedure TAddInModule.adxExcelAppEvents1WindowActivate(ASender: TObject; 
 const Wb: _Workbook; const Wn: Window);
begin
    adxCommandBar1.Controls[0].Enabled := true;
end;

procedure TAddInModule.adxExcelAppEvents1WindowDeactivate(ASender: TObject;
 const Wb: _Workbook; const Wn: Window);
begin
    adxCommandBar1.Controls[0].Enabled := false;
end;

procedure TAddInModule.adxWordAppEvents1WindowActivate(ASender: TObject; 
 const Doc: _Document; const Wn: Window);
begin
    adxCommandBar1.Controls[0].Enabled := true;
end;

procedure TAddInModule.adxWordAppEvents1WindowDeactivate(ASender: TObject; 
 const Doc: _Document; const Wn: Window);
begin
    adxCommandBar1.Controls[0].Enabled := false;
end;

Step #8 – Handling Excel worksheet events

In the Tool Palette, find the Servers tab and add an instance of TExcelWorksheet to the add-in module. Now you can connect the instance to a worksheet, e.g. the active one.

 
Find the code for handling worksheet events in the code of this add-in.

Step #9 – Customizing the Office 2007 Ribbon user interface

To add a new tab to the Office 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 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 newly added Ribbon button. Write the following code:

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

Remember, the TadxRibbonTab Controls editor performs 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.

Step #10 – Adding an Office 2007 task pane

To add a new task pane to Outlook, Excel, Word and PowerPoint, 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.

Our sample add-in described 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. More about Excel task panes.

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

Step #11 – Running your Office COM add-in

Save the add-in project, compile it, close all applications that you have selected as add-in host applications, and register the add-in via "Run | Register ActiveX Server". Run one of the selected host applications, find your toolbar and click the button. 

You find your add-in in the COM Add-ins dialog:

Step #12 – Debugging the COM 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 #13 – Deploying the COM 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