Customizing the Office 2007 Ribbon UI - Part 6

Article
06/28/2006

In this topic on customizing the Ribbon UI, we'll look at different scenarios for customizing the Ribbon at the application-level by using COM add-ins. These modifications could just as easily be applied to a specific document with document-level customizations using Office 2007 Open XML Formats files as described in Part 3 of this series.

Note: I would also highly recommend that you check out the three-part series of articles on customizing the Ribbon at: https://msdn.microsoft.com/en-us/library/aa338202.aspx

First, you'll create the project in Visual Studio using C#. Next, you'll create different customization XML markup files and then embed those into the project. As some of the customizations involve using bitmap icons, you'll need to include three of your favorite 16 x 16 pixel icons. Custom icons for add-ins must be 16 x 16 pixels and be either 16-color or True Color. To get started:

First, create the Visual C# project:
1. Start Visual Studio .NET 2005.
2. On the File menu, click New Project.
3. In the New Project dialog box under Project Types, expand Other Projects, click Extensibility Projects, and then double-click Shared Addin.
4. Type a name for the project. In this sample, type RibbonUISamplesCS.
5. In the first screen of the Shared Add-in Wizard, click Next.
6. In the next screen, select "Create an Add-in using Visual C#", and then click Next.
7. In the next screen, clear all of the selections except Microsoft Word and then click Next.
8. Type a Name and Description for the add-in, and then click Next.
9. In the Choose Add-in Options screen, select "I would like my Add-in to load when the host application loads" and then click Next.
10. Click Finish to complete the wizard.

Now add a reference to Word:
1. In the Solution Explorer, right-click References, and then click Add Reference.

Note: If you don't see the References folder, click the Project menu and then Show All Files.

2. Scroll downward on the .NET tab, press the Ctrl key, and then select Microsoft.Office.Interop.Word.
3. On the COM tab, scroll downward, select Microsoft Office 12.0 Object Library, and then click OK.
4. Next add the following namespace references to the project if they don't already exist. Do this just below the namespace line:

using System;
using Extensibility;
using System.Runtime.InteropServices;
using Microsoft.Office.Core;
using Microsoft.Office.Interop;
using System.Drawing;
using System.Windows.Forms;

Implement the IRibbonExtensibility interface.
1. In the Solution Explorer, right-click Connect.cs, and click View Code.
2. At the end of the public class Connect statement, add a comma, and then type IRibbonExtensibility.

Tip: You can use Microsoft IntelliSense to insert interface methods for you. For example, at the end of the public class Connect : statement, type IRibbonExtensibility, right-click, point to Implement Interface, and then click Implement Interface Explicitly. This adds a stub for the only IRibbonExtensibility interface member: GetCustomUI. The implemented method looks like this:

string IRibbonExtensibility.GetCustomUI(string RibbonID)
{
}

3. Insert the following statement into the GetCustomUI method, overwriting the existing code:

return resource.GetString("customui-1.xml");

4. Above the GetCustomUI method, add this statement that gives you access to the XML markup files which you'll add later:

private ResourceManager resource = new ResourceManager();

5. Add the callback methods that will be used in the different customization files:

#region callbacks-1

public stdole.IPictureDisp ButtonImage(IRibbonControl control)
{
return resource.GetImage("Icon2.bmp");
}

public void ButtonAction(IRibbonControl control)
{
Random r = new Random();
string s = r.Next(100000, 200000).ToString();

Microsoft.Office.Interop.Word.Application wordApp = (Microsoft.Office.Interop.Word.Application)(applicationObject);
wordApp.Selection.InsertAfter("\nContoso Case ID " + s);
}

#endregion callbacks-1

#region callbacks-2

private Boolean randomize = false;
private IRibbonUI myRibbon;

public void ribbonLoaded(IRibbonUI ribbon)
{
myRibbon = ribbon;
}

public stdole.IPictureDisp getSButton(IRibbonControl control)
{
return resource.GetImage("Icon3.bmp");
}

public int bankTellers_getItemCount(IRibbonControl control)
{
return 6;
}

public stdole.IPictureDisp bankTellers_getItemImage(IRibbonControl control, int index)
{
Random r = new Random();

   if (!randomize)
   {
      return resource.GetImage(index + ".bmp");
   }
   else
   {
      return resource.GetImage(r.Next(0, 7).ToString() + ".bmp");
   }
}

public void bankTellers_OnAction(IRibbonControl control, int index)
{
   myRibbon.Invalidate();
   Microsoft.Office.Interop.Word.Application wordApp = (Microsoft.Office.Interop.Word.Application)(applicationObject);
   wordApp.Selection.InsertAfter("Officer #" + (index+1) + " ");
   // MessageBox.Show("You just clicked on Bank Teller #" + (index + 1) + "!");
}

public void toggle_randomize(IRibbonControl control, bool press)
{
randomize = press;
myRibbon.Invalidate();
}

public string getRandomizeLabel(IRibbonControl control)
{
   if (randomize)
   {
      return ("Randomize ON");
   }
   else
   {
      return ("Randomize OFF");
   }
}

#endregion callbacks-2

#region callbacks-3
public stdole.IPictureDisp dinoImage(IRibbonControl control)
{
return resource.GetImage("Icon1.bmp");
}

public stdole.IPictureDisp OnLoadImage(string image)
{
return resource.GetImage(image);
}

#endregion callbacks-3

Now, we'll start creating different customization files, embedding them as resources in the project, and then observing how they impact the Ribbon UI:

1. In a text editor, add the following XML markup:

<?xml version="1.0" encoding="utf-8" ?>
<customUI xmlns="https://schemas.microsoft.com/office/2006/01/customui">
<ribbon>
    <tabs>
      <tab idMso="TabInsert">
        <group id="MyContosoGroup" label="Contoso!" insertAfterMso="GroupHeaderFooter">
          <button id="CInsertCaseID"
                 size="large"
                  label="Case ID Number"
                  screentip="Insert Contoso Case ID Number."
                  onAction="ButtonAction"
                  getImage="ButtonImage" />
        
      </group>
      </tab>
    </tabs>
</ribbon>
</customUI>

2. Close and save the file as customUI-1.xml.
3. In the Solution Explorer in the project, right-click RibbonUISamplesCS, point to Add, and then click Existing Item.
4. Navigate to the customUI-1.xml file you created, select the file, and then click Add.

For each of the customization files you create, you will repeat these steps. After adding each file and before building and installing the project, you'll need to ensure that the GetCustomUI method points to the correct file. So in this instance, the statement in the GetCustomUI method will read:

return resource.GetString("customui-1.xml");

And finally, use the same procedures to add each of the three 16 x 16 bitmaps as Icon1.bmp. Icon2.bmp, and Icon3.bmp, respectively.

Compile both the add-in and its setup project. Before beginning, make sure that Word is closed.
1. In the Project menu, click Build Solution. You will see a message when the build is complete in the system tray in the lower left corner of the window.
2. In the Solution Explorer, right-click RibbonSamplesCSSetup and click Build.
3. Right-click RibbonSamplesCSSetup and click Install. This launches the RibbonSamplesCSSetup Setup Wizard screen.
4. Click Next on all of the screens and then Close on the final screen.
5. Start Word. You should see the "My Tab" tab to the right of the other tabs.

If you have problems with any of this, recheck that the procedures in the project match those in the steps or go back to part 4 in this series of articles for additional troubleshooting steps.

Customizing the Office 2007 Ribbon UI - Part 6

Additional resources