Ty Anderson

Customizing Microsoft Word ribbons and toolbars: VB.NET, C#

Beauty comes from within. This is true with add-ins as much as it is true with people. But with add-ins, there is a greater need to advertise their beauty via a customized user interface. Without a nice UI, the user might never 1) notice your add-in’s existence and 2) initiate any of the add-in’s beautiful features.

A popular user interface customization is custom ribbons and custom toolbars. I think you know what these are and we’ll cover how to create both of them for Microsoft Word.

We’ll start with Ribbon and work our way back to the legacy toolbars (aka CommandBars).

Creating custom ribbons for Word 2013 – 2007

There are three main scenarios for custom ribbons. They are:

  1. Create a new ribbon: adds an additional tab to the Word Ribbon.
  2. Customize an existing Word ribbon: your customizations integrate with an existing tab.
  3. Create a context-sensitive one: the custom ribbon tab only displays when a specific context is active (e.g. editing headers and footers in a Word document).

Mastering these three scenarios covers Pareto Principle and will make you appear like a Word UI customization master. Add some experience and you will be. Let’s take the scenarios one-by-one.

Create a custom Word ribbon that adds a new tab

I think this is the most common type of customization. I don’t have a large sample of developers to back me up. It’s just my preference. I think it is typically less confusing to the user because the new ribbon tab is conspicuous. It’s easy for my users to notice and find the Word addin’s commands.

Let’s build a tab like the one I showed in my last article: Customizing Word User Interface.

A custom Word ribbon tab

Before we begin, you need to:

  1. Open Visual Studio 2012.
  2. Create a new ADX COM Add-in project using Add-in Express for Office and .net.
  3. Choose your preferred language (I went with VB.NET, you can use C# or C++.NET as well).
  4. Select Office 2003 as the minimum supported Office version.
  5. Select Word (and only Word) as the supported application.

Creating a Word COM add-in

After you create the project, you can crank out an attractive custom ribbon for Microsoft Word 2007, 2010 and 2013 in just a few minutes by completing these steps:

  1. Open the AddinModule in design view. Add a new tab (ADXRibbonTab) to it. Set the following properties for the tab:
    • Name=CustomRibbon
    • Caption=MY RIBBON TAB
    • Ribbons=WordDocument
  2. Add an ImageList control to the AddinModule. It will contain the icons for the ribbon buttons. Leave the name as is but set its ImageSize=32,32. Then add two icons you like to the Images collection. Just make sure the icons are 32 pixels by 32 pixels.
  3. Select the CustomRibbon and use the visual designer to add the following controls and set their properties according the table below
Control Parent Properties & Values
ADXRibbonGroup CustomRibbon Caption=Custom Action Group
ADXRibbonSplitButton1 AdxRibbonGroup1 Caption=Create Doc from Template
ImageList=ImageList1
Size=Large
ADXRibbonMenu ADXSplitButton1 Caption=Options
ADXRibbonButton ADXRibbonMenu1 Caption=Sales Proposal
ADXRibbonButton ADXRibbonMenu1 Caption=Technical Design Document
ADXRibbonButton ADXRibbonMenu1 Caption=Status Report
ADXRibbonButton AdxRibbonGroup1 Caption=Temlate Gallery
ImageList=ImageList1
Image=1Size=Large
ADXRibbonSeparator AdxRibbonGroup1 n/a
ADXRibbonCheckBox AdxRibbonGroup1 Caption=Auto-check for new Templates?

After completing, your custom Word ribbon should look similar to this:

The custom Word ribbon in Visual Studio 2012 at design-time

This ribbon will display to the far right of all Word ribbon tabs. But what if you don’t want to display it there? What if you want it to display just to the right of the HOME tab… loud and proud?

Well, it’s both easy and simple to do. Just select the CustomTab in the designer. Then configure its InsertAfterIdMso property to TabHome.

Confuguring the custom ribbon's properties to display it to the right of the HOME tab

All of the ribbon controls have a control ID. Microsoft provides a nice set of control ID reference docs to help us out.

The custom ribbon with several controls residing right after the HOME tab

You can utilize the InsertBeforeIdMso property to position the custom tab.

Customize an existing Word ribbon

Sometimes it is better to integrate a custom ribbon within an existing one. This is best when your features closely relate to existing ribbon commands. It’s also appropriate when you want to override a standard Word ribbon button’s feature.

Let’s take our custom ribbon and make the following changes to it:

  1. Select the CustomRibbon on the AddinModule.
  2. Change its IdMso property to TabHome.
  3. Select the AdxRibbonGroup1 control (Custom Action Group) in the ribbon designer.
  4. Change its InsertBeforeIdMso property to GroupClipboard. This will cause the group to display as the first group in the HOME tab.

The custom group displays as the first group in the HOME tab

Create a custom context-sensitive ribbon

If you are adding features that should only display in certain contexts, this is the type of ribbon to build. A good example of a context sensitive ribbon is the image editing or table editing ribbons. These ribbons display when you select an image or table respectively. They provide the commands needed to edit them as you see fit.

To make the CustomRibbon display only within a specific Word context just change its Context property.

Changing the Context property to make the custom ribbon display only within a specific Word context

By setting this property, you tell Office to only display the custom ribbon in this specified context.

The custom ribbon display only when the user edits headers and footers

Thus, Microsoft Word does not display them when they are not the current selection.

Creating custom toolbars for Word 2003

Toolbars, also known as CommandBars, are long gone if your solutions only support Office 2007 – Office 2013 (yes, I know Outlook 2007 makes limited use of them). I’ll let you do that if you prefer. But, just know you are significantly reducing your potential user base if you ignore Office 2003 and earlier.

Using Add-in Express, it is easy to support toolbars and ribbons in the same project. This greatly reduces your development & maintenance efforts because you only need single code base for all version of Office 2003 through 2013. Let’s look at how to create custom Word toolbars.

Develop a new Word commandbar

Similar to a ribbon, we can create custom toolbars that fit our needs. They display as a row of controls in a separate “strip” called a CommandBar (users call them a toolbar).

The custom Word commandbar in Visual Studio 2012 at design-time

With Add-in Express, we add an ADXCommandBar control the AddinModule and set the following properties:

  • Name=CustomToolbar
  • CommandBarName = My Custom Toolbar
  • SupportedApps = Word

Now add some controls to the CustomToolbar according to the table below:

Control Parent Properties & Values
ADXCommandBarComboBox CustomToolbar Caption=Select Template
Style=adxMsoComboLabel
Items=Sales Proposal
Technical Design Document
Status Report
AdxCommandBarButton CustomToolbar Caption=Create from Template
ImageList=ImageList2I
mage
=0
Style=adxMsoButtonIconAndCaption
AdxCommandBarButton CustomToolbar Caption=Template Gallery
ImageList=ImageList2
Image=1
Style=adxMsoButtonIconAndCaption
CheckBox AddinModule Caption= Auto-check for new templates?
Label AddinModule n/a
ADXCommandBarAdvancedControl CustomToolbar Control = Label1
ADXCommandBarAdvancedControl CustomToolbar Control = CheckBox1
ADXWordControlAdapter AddinModule n/a

The last three controls are exclusive to Add-in Express. They allow you to host .NET controls in the Office toolbar… something not supported by Visual Studio out-of-box.

A custom toolbar with several controls in Word 2003

By utilizing these controls, I’m able to host a label and checkbox on the custom toolbar. Thus, the toolbar can closely mimic the design of the ribbon.

Customize an existing Word toolbar

You change the toolbar to integrate with an existing toolbar. All you need to do is know the name of the target toolbar and set it as the value of the CommandBarName property. I recommend using our Built-In Controls Scanner (a free utility) to help find the name of the Office 2003 and earlier toolbar and control IDs.

Here, I’ve changed the toolbar to display in Word 2003’s standard toolbar:

Changing the toolbar's properties to display in Word 2003's standard toolbar

Note. The advanced controls do not function when you integrate with a standard Word toolbar. Thus, you need to remove both of the ADXCommandBarAdvancedControl objects for this integration to work.

If you delete the controls, then, at runtime, your custom Word toolbar integrates with the standard toolbar and looks like this:

The custom toolbar integrated with the standard Word toolbar

Sometimes, I miss the old toolbars. Their elegance is their simplicity.

***

That’s all there is to it. We make it easy to build custom Word ribbons and toolbars. Unfortunately, its up to you ine the requirements of your users. That’s not so easy.

Available downloads:

This sample Word addin was developed using Add-in Express for Office and .net:

VB.NET Word add-in

Word add-in development in Visual Studio for beginners:

3 Comments

  • Ken says:

    I created a custom tab for a Word template using Custom UI Editor for Microsoft Office. I’m using W2010 and my client is using W2007 – W2013. The custom tab displays and everything works fine. Someone created a document using the template and then sent it to a W2013 machine without the template. When they opened the document in W2013, the custom tab appeared. It wasn’t functional (which I would expect). But wondering why the custom tab would display. Any help would be greatly appreciated. Thanks. Ken

  • Ty Anderson says:

    Hi Ken

    The Custom UI Editor makes changes to the document’s XML.
    I’m betting the saved document also includes the custom UI from the template.

    Where does the code reside for the custom UI elements?
    In the template?

  • Gyan Sonwane says:

    Great information very good!! appreciates you.

Post a comment

Have any questions? Ask us right now!