The Ribbon user interface (UI) in the 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 document. You will:
- Create a COM add-in project in Microsoft Visual Basic 6.0 that works with Word.
- 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, open the Designer window by right-clicking
Connect and then select View Object. Select Microsoft Word from the Applicationlist.
- In the
Initial Load Behavior list, select Startup.
- In the Project Explorer, right-click
MyAddin and 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:
- This step is optional however if you want to be notified that your add-in is actually loading when you start Word, you can add the following statement to the OnConnection procedure. Once you're 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 you added earlier, and to create a reference to the Ribbon UI interface:
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 UI to implement when the add-in loads.
Retrieve the XML customization code
In this step, add the GetRibbonXML function. In this instance, 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. The company name is inserted into the document.
Troubleshoot the project
If you do not see the My Tab tab when you start Word, you may need to add an entry to the Microsoft Windows registry. To do this, perform the following steps:
| Caution
|
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. |
- On the desktop, click
Start, click Run, and type regedit.
- From the
Registry tab, navigate to the following registry key for the add-in: HKCU\Software\Microsoft\Office\Word\AddIns\RibbonXSampleVB.Connect
| Note
|
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. |
Caution
Note