How to: Customize the Office Fluent Ribbon by Using a Visual Basic COM Add-in
The ribbon component of the Microsoft Office Fluent user interface in the 2007 and 2010 releases of the Microsoft Office suites gives users a flexible way to work with Office applications. Ribbon Extensibility (RibbonX) uses a simple, text-based, declarative XML markup to create and customize the ribbon.
The code example in this topic shows how to customize the ribbon in Office, no matter what document is open. In the following steps, you create application-level customizations by using a managed COM add-in, and you create the add-in in Microsoft Visual Studio 2005 by using Microsoft Visual Basic 6.0. The project adds a custom tab, a custom group, and a custom button to the ribbon. To complete the procedure, you perform the following tasks.
Create a COM add-in project in Microsoft Visual Basic 6.0 that works with Word 2007.
Add a reference to the IRibbonExtensibility interface.
Implement the only member of the interface, GetCustomUI.
Add the XML customization markup code.
Add the subroutine that is called when the button is clicked.
Test the project.
Troubleshoot the project, if necessary.
Create the COM Add-in in Visual Basic 6.0
In this step you create a COM add-in by using an add-in designer.
Start Microsoft Visual Basic® 6.0 and select Addin as the project type. This adds a designer class to the project (Connect) and a form (frmAddin).
In the Project Explorer window, right-click Connect and then select View Object to open the Designer window. Select Microsoft Word from the Applicationlist.
In the Initial Load Behavior list, select Startup.
In the Project Explorer, right-click MyAddin and then in the Property window, change the name of the add-in to RibbonSampleVB.
Remove frmAddin from the project.
From the Project window, right-click the Connect item and select view code.
Remove all of the code in the designer's code window. This code works for Visual Basic add-ins but not Microsoft Office add-ins.
Add the following statement to the OnConnection method to obtain a reference to Word when the add-in loads:
Set oWD = Application
The next step is optional. If you want to make sure that your add-in is loading when you start Word, you can add the following statement to the OnConnection procedure to be notified that it has. Once you are satisfied that the add-is being loaded, you can remove the line and rebuild the project.
MsgBox "My Addin started in " & Application.Name
Add a Reference to the IRibbonExtensibility Interface
At the top of the code window, add the following statements to set aside memory for the Word Application object that you added earlier, and to create a reference to the ribbon.
Option Explicit Dim oWD As Object Implements IRibbonExtensibility
Implement the IRibbonExtensibility Interface
In this step, you implement the IRibbonExtensibilty interface's only member, GetCustomUI. Add the following procedure at the bottom of the code window.
Public Function IRibbonExtensibility_GetCustomUI(ByVal RibbonID As String) As String IRibbonExtensibility_GetCustomUI = GetRibbonXML() End Function
This procedure calls the GetRibbonXML method that, as its name implies, returns the customization XML to the GetCustomUI method which then adds it to the ribbon to implement when the add-in loads.
Retrieve the XML Customization Code
In this step, you add the GetRibbonXML function. Here, the customization code is stored in a String variable that is returned to the GetCustomUI method.
Public Function GetRibbonXML() As String Dim sRibbonXML As String sRibbonXML = "<customUI xmlns=""http://schemas.microsoft.com/office/2006/01/customui"" >" & _ "<ribbon>" & _ "<tabs>" & _ "<tab id=""CustomTab"" label=""My Tab"">" & _ "<group id=""SampleGroup"" label=""Sample Group"">" & _ "<button id=""Button"" label=""Insert Company Name"" size=""large"" onAction=""InsertCompanyName"" />" & _ "</group >" & _ "</tab>" & _ "</tabs>" & _ "</ribbon>" & _ "</customUI>" GetRibbonXML = sRibbonXML End Function
Add the Procedure That Is Called When You Click the Button
Add the procedure that gets called when you click the custom button:
Public Sub InsertCompanyName(ByVal control As IRibbonControl) ' Inserts the specified text at the beginning of a range. Dim MyText As String Dim MyRange As Object Set MyRange = oWD.ActiveDocument.Range MyText = "Microsoft Corporation" ' Inserts text at the beginning ' of the active document. MyRange.InsertBefore (MyText) End Sub
This procedure creates a reference to a range in the active document and then inserts the company name text into the range.
Test the Project
In this step, you test the add-in.
To make sure the code compiles without error, on the Run menu, click Start with Full Compile.
Once the code compiles without error, save the project and create the RibbonSampleVB.dll by clicking the File menu and then clicking Make RibbonSampleVB.dll.... The designer registers the add-in for you.
Start Word. You should see the My Tab tab to the right of the other tabs.
Click the tab and then click Insert Company Name to insert the company name at the cursor.
Troubleshoot the Project
If you do not see the My Tab tab when you start Word, you might need to add an entry to the Windows registry by completing the following steps. The next few steps contain information about how to modify 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 more 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.
On the desktop, click Start, click Run, and then type regedit.
From the Registry tab, navigate to the following registry key for the add-in: HKCU\Software\Microsoft\Office\Word\AddIns\RibbonXSampleVB.Connect
If the RibbonXSampleVB.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 RibbonXSampleVB.Connect. Add a LoadBehavior DWord and set its value to 3.