Customizing Microsoft Office commandbars
with custom controls in VB.NET, C#, C++

Toolbar Controls
for Microsoft® Office

Add-in Express Home > Toolbar Controls for Microsoft Office > Online Guide > Insight of Toolbar Controls

This page explains nuts and bolts of of Toolbar Controls for Microsoft Office, which is part of Add-in Express for Office and .net. To make the text below easy to read, let's define three terms, namely:

• Command bar controls are controls such as a command bar button and command bar combo box provided by the Office object model. These controls are built-in Office controls and they are supported by Add-in Express.
• Non-Office controls are any controls, both .NET built-in and third-party controls, such as tree-views, grids, edit boxes, combo boxes, labels, images, user controls, etc. Usually, you use these controls on forms of your Windows applications.
• Advanced command bar control is an instance or ADXCommandBarAdvancedControl or the ADXCommandBarAdvancedControl class itself (depending on the context).

Further on this page you will find information about:

• What is ADXCommandBarAdvancedControl
• Hosting any .NET controls
• Toolbar Controls is a set of control adapters
• ADXCommandBarAdvancedControl properties
• Control adapters

Note. This feature cannot be used to customize a CommandBar control shown in the Ribbon user interface.

What is ADXCommandBarAdvancedControl

If you have developed at least one add-in based on Add-in Express, you probably ran into ADXCommandBarAdvancedControl when adding command bar controls to your command bars. Yes, it is that strange item of the Add button on the ADXCommandBarControl collection editor.

This plug-in gives you a chance to use any non-Office controls such as tree-views, grids, labels, edit and combo boxes, diagrams on any Office command bars. Now you can add ADXCommandBarAdvancedControl, an advanced command bar control, to your command bar and bind it to any non-Office control you placed on the add-in module. As a result, you will have your grid, tree-view or image placed on your command bar.

Hosting any .NET controls

In addition to properties common for Office command bar controls, ADXCommandBarAdvancedControl has one more property. It is the Control property, the most important one. With this property, you can select a non-Office control to place it on your command bar. Have a look at the picture below. The add-in module contains five controls - MyCalendar, MyDataGrid, MyNumericUpDown, MyTreeView and MyUserControl. The Control property asks you to select one of these controls. If you select MyUserControl, your add-in adds MyUserControl to your command bar. With the Control property, DXCommandBarAdvancedControl becomes a host for your non-Office controls.

On .NET, ADXCommandBarAdvancedControl supports all controls based on System.Windows.Forms.Control. So, on your command bars, you can use both built-in controls and third-party controls based on System.Windows.Forms.Control. Just add them to the add-in module, add an advanced command bar control to your command bar and select your non-Office control in the Control property of ADXCommandBarAdvancedControl.

The Toolbar Controls is a set of control adapters

You may ask us what the Toolbar Controls described above does, if ADXCommandBarAdvancedControl is already included in Add-in Express. In general, ADXCommandBarAdvancedControl is still abstract in Add-in Express, but it is implemented by the Toolbar Controls if it is plugged into Add-in Express. So, our answer is: the Toolbar Controls for Microsoft Office implements ADXCommandBarAdvancedControl for each Office application.

The Toolbar Controls adds a new tab, "Toolbar Controls for Microsoft Office", to the Toolbox and places several components on the tab (see the picture below). The Toolbar Controls supports each Office application by special components that we call Control Adapters. Only Control Adapters know how to add your controls to applications specific command bars. So, the Control Adapters are the Toolbar Controls itself.

In Express editions of Visual Studio, you need to add the control adapters manually.

The add-in module can contain control adapters only. For example, you should add an ADXExcelControlAdapter to the add-in module if you want to use non-Office controls in your Excel add-in. To use non-Office controls on several Office applications you should add several control adapters. For example, if you need to use your controls in your add-in that supports Outlook, Excel, and Word, you should add three control adapters: ADXExcelControlAdapter, ADXWordControlAdapter, and ADXOutlookControlAdapter to the add-in module.

ADXCommandBarAdvancedControl properties

The Toolbar Controls implements the ADXCommandBarAdvancedControl class. In addition to properties common for all command bar controls, ADXCommandBarAdvancedControl provides two special properties related to the Toolbar Controls.

The Control property

The Control property binds its ADXCommandBarAdvancedControl to a non-Office control and can be used at design-time as well as at run-time. To place your non-Office control on your command bar you just select your control in the Control property at design-time, or set the Control property to an instance of your control at run-time:

VB.NET

  Private Sub AddinModule_AddinInitialize( _
      ByVal sender As System.Object, _
      ByVal e As System.EventArgs) Handles MyBase.AddinInitialize
      BossCheckbox = New System.Windows.Forms.CheckBox
      Me.AdxCommandBarAdvancedControl1.Control = BossCheckbox
   End Sub

The ActiveInstance property

The ActiveInstance property is read-only and returns the instance of the Control that was created for the current context. For example, you can initialize your control for the active Inspector by handling the InspectorActivate event:

VB.NET

   Private Sub adxOutlookEvents_InspectorActivate( _
      ByVal sender As System.Object, ByVal inspector As System.Object,
      ByVal folderName As System.String) _ 
         Handles adxOutlookEvents.InspectorActivate

      Dim ChkBox As System.Windows.Forms.CheckBox = _
         Me.AdxCommandBarAdvancedControl1.ActiveInstance
      If ChkBox IsNot Nothing Then ChkBox.Enabled = False
   End Sub

Please note, the ActiveInstance property is not actual in most cases when you'd like to use it. You can always use any window activate events such as the InspectorActivate event of Outlook and WindowActivate event of Word. The table below shows you the order of event processing by the example of the Outlook Inspector window opened by the user.

Control adapters

AAll Office applications have different window architectures. All Office windows themselves are different. All our control adapters have a unified programming interface but different internal architectures that take into account the windows architecture of the corresponding applications. All features of all control adapters are described below.

Outlook

Outlook has two main windows - Explorer and Inspector windows. The user can open several Explorer and Inspector windows. Our Outlook control adapter supports non-Office controls on both the Explorer and Inspector windows, and creates an instance of your control whenever the user opens a new Explorer or Inspector window.

Please note, if Word is used as an e-mail editor, Outlook uses MS Word as an Inspector window. In this case, Word is running in a separate process. It does not provide any ways to control all instances of your control. So, there is one feature with Word as an e-mail editor: the Outlook control adapter hides all instances of your control on all inactive Word Inspector windows, but shows them once the Inspector is activated. See also a sample project showing how to add a custom .NET control to Outlook commandbar.

Excel

In spite of the fact that Excel allows placing its windows on the Task Bar, all its commandbars work like in MDI applications. So, your controls are created only once, when Excel is started. However, you can still use the WorkbookActivate, WindowActivate and SheetActivate events to initialize your non-Office controls according to the context.

Word

Word creates its commandbars for all document windows, so your non-Office controls are instanced whenever the user opens a new window or a document. We recommend using the WindowActivate event to initialize your control for the current window.

PowerPoint

Notwithstanding the fact that PowerPoint makes possible placing its windows on the Task Bar, PowerPoint is an MDI application. So, your controls are created only once, when PowerPoint is started. However, you can still use the WindowActivate event to initialize your non-Office controls according to the context.