How to: Customize the Ribbon UI by using a Managed COM Add-in
The Ribbon user interface (UI) in the 2007 release of Microsoft® Office suites offers users a flexible way to work with Office applications. Ribbon Extensibility (RibbonX) uses text-based, declarative XML markup that simplifies creating and customizing the Ribbon UI. This sample demonstrates how to add create a custom Ribbon UI that appears in the Office application regardless of the document that is open. In the following steps, you create application-level customizations using a managed COM add-in which we create in Microsoft Visual Studio® 2005 using Microsoft Visual C#®. The project adds a custom tab, a custom group, and button to the Ribbon UI that when clicked, inserts a company name into a Word 2007 document. You will:
Create the XML customization file.
Create a managed COM add-in project in Visual Studio 2005 with C#.
Add the XML customization file to the project as an embedded resource.
Implement the IRibbonExtensibility interface.
Create a callback method that is triggered when the button is clicked.
In this step you add code to the Extensibility.IDTExtensibility2::OnConnection to create a reference to the Word application at runtime. You also implement the only member of the IRibbonExtensibility interface: GetCustomUI:
In the Solution Explorer, right-click Connect.cs, and click View Code.
After the Connect method, add the following declaration, which creates a reference to the Word Application object:
private MSword.Application applicationObject;
Add the following line to the OnConnection method. This statement creates an instance of the Word Application object:
At the end of the public class Connect statement, add a comma, and then type IRibbonExtensibility.
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 and point to Implement Interface, and then click Implement Interface Explicitly. This adds a stub for the GetCustomUI method. The implementation looks like this:
Insert the following statement into the GetCustomUI method, overwriting the existing code:
Insert the following method below the GetCustommUI method:
private string GetResource(string resourceName)
Assembly asm = Assembly.GetExecutingAssembly();
foreach (string name in asm.GetManifestResourceNames())
System.IO.TextReader tr = new System.IO.StreamReader(asm.GetManifestResourceStream(name));
//Debug.Assert(tr != null);
string resource = tr.ReadToEnd();
The GetCustomUI method calls the GetResource method. The GetResource method sets a reference to this assembly during runtime and then
loops through the embedded resource until it finds the one named customUI.xml. It then creates an instance of the StreamReader object
that reads the embedded file containing the XML markup. The procedure passes the XML back to the GetCustomUI method which returns the XML
to the Ribbon UI. Alternately, you can also construct a string that contains the XML markup and read it directly into the GetCustomUI method.
Following the GetResource method, add this method. This method inserts the company name into the document at the beginning of the page:
public void InsertCompanyName(IRibbonControl control)
// Inserts the specified text at the beginning of a range or selection.
MyText = "Microsoft Corporation";
MSword.Document doc = applicationObject.ActiveDocument;
//Inserts text at the beginning of the active document.
object startPosition = 0;
object endPosition = 0;
MSword.Range r = (MSword.Range)doc.Range(
ref startPosition, ref endPosition);
Click the My Tab tab and then click Insert Company Name. The company name is inserted into the document at the cursor
location. If you do not see the customized Ribbon UI, you may need to add an entry to the Microsoft Windows registry. To do this, perform the following steps:
The next few steps contain information about modifying the registry. Before you modify the registry, be sure to back it up and
make sure that you understand how to restore the registry if a problem occurs. For information about how to back up, restore, and edit the
registry, search for the following article in the Microsoft Knowledge Base: 256986 Description of the Microsoft Windows Registry
In the Solution Explorer, right-click the setup project, RibbonXSampleCSSetup, point to View, and then click Registry.
From the Registry tab, navigate to the following registry key for the add-in: HKCU\Software\Microsoft\Office\Word\AddIns\RibbonXSampleCS.Connect
If the RibbonXSampleCS.Connect key does not exist, you can create it. To do so, right-click the Addins folder, point to New, and then
click Key. Name the key RibbonXSampleCS.Connect. Add a LoadBehavior DWord and set its value to 3.