Walkthrough: Creating a Custom Tab by Using Ribbon XML

Article
11/16/2012

Applies to
The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office. Project type Document-level projects Application-level projects Microsoft Office version Excel 2007 Word 2007 Outlook 2007 PowerPoint 2007 For more information, see Features Available by Application and Project Type.

The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office.

Project type

Document-level projects
Application-level projects

Microsoft Office version

Excel 2007
Word 2007
Outlook 2007
PowerPoint 2007

For more information, see Features Available by Application and Project Type.

This walkthrough demonstrates how to create a custom Ribbon tab by using the Ribbon (XML) item.

This walkthrough illustrates the following tasks:

Adding buttons to the Add-Ins tab. The Add-Ins tab is the default tab that is defined in the Ribbon XML file.
Automating Microsoft Office Word 2007 by using the buttons on the Add-Ins tab.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Visual Studio Settings.

Prerequisites

You need the following components to complete this walkthrough:

Visual Studio Tools for Office (an optional component of Visual Studio 2008 Professional and Visual Studio Team System).
Microsoft Office Word 2007.

Visual Studio Tools for Office is installed by default with the listed versions of Visual Studio. To check whether it is installed, see Installing Visual Studio Tools for Office.

link to video For a related video demonstration, see How Do I: Use the Ribbon Designer to Customize the Ribbon in Excel?.

Creating the Project

The first step is to create a Word 2007 add-in project. You will later customize the Add-Ins tab of this document.

To create a new project

Create a Word Add-in project with the name MyRibbonAddIn.

Ensure that you use the Word Add-in project template for the 2007 Microsoft Office system. For more information, see How to: Create Visual Studio Tools for Office Projects.

Visual Studio opens the ThisAddIn.cs or ThisAddIn.vb code file and adds the MyRibbonAddIn project to Solution Explorer.

Creating the Add-Ins Tab

To create the Add-Ins tab, add a Ribbon (XML) item to your project. Later in this walkthrough, you will add some buttons to this tab.

To create the Add-Ins tab

On the Project menu, click Add New Item.
In the Add New Item dialog box, select Ribbon (XML).
Change the name of the new Ribbon to MyRibbon, and click Add.

The MyRibbon.cs or MyRibbon.vb file opens in the designer. An XML file that is named MyRibbon.xml is also added to your project.
In Solution Explorer, right-click ThisAddin.cs or ThisAddin.vb, and then click View Code.

Add the following code to the ThisAddin class. This code overrides the CreateRibbonExtensibilityObject method and returns the Ribbon XML class to the Office application.

Protected Overrides Function CreateRibbonExtensibilityObject() As  _
Microsoft.Office.Core.IRibbonExtensibility
    Return New MyRibbon()
End Function

protected override Microsoft.Office.Core.IRibbonExtensibility CreateRibbonExtensibilityObject()
{
    return new MyRibbon();
}

In Solution Explorer, right-click the MyRibbonAddIn project and then click Build. Verify that the project builds without errors.

Adding Buttons to the Add-Ins Tab

The goal for this add-in is to give users a way to add boilerplate text and a specific table to the active document. To provide the user interface, add two buttons to the Add-Ins tab by modifying the Ribbon XML file. Later in this walkthrough, you will define callback methods for the buttons. For more information about the Ribbon XML file, see Ribbon XML.

To add buttons to the Add-Ins tab

In Solution Explorer, right-click MyRibbon.xml and then click Open.

Replace the contents of the tab element with the following XML. This XML changes the label of the default control group to Content, and it adds two new buttons with the labels Insert Text and Insert Table.

<tab idMso="TabAddIns">
    <group id="ContentGroup" label="Content">
        <button id="textButton" label="Insert Text"
             screentip="Text" onAction="OnTextButton"
             supertip="Inserts text at the cursor location."/>
        <button id="tableButton" label="Insert Table"
             screentip="Table" onAction="OnTableButton"
             supertip="Inserts a table at the cursor location."/>
    </group>
</tab>

Automating the Document by Using the Buttons

You must add onAction callback methods for the Insert Text and Insert Table buttons to perform actions when the user clicks them. For more information about callback methods for Ribbon controls, see Ribbon XML.

To add callback methods for the buttons

In Solution Explorer, right-click MyRibbon.cs or MyRibbon.vb, and then click Open.
Add the following code to the top of the MyRibbon.cs or MyRibbon.vb file. This code creates an alias for the Microsoft.Office.Interop.Word namespace.
```
Imports Word = Microsoft.Office.Interop.Word
```
```
using Word = Microsoft.Office.Interop.Word;
```

Add the following method to the MyRibbon class. This is a callback method for the Insert Text button that adds a string to the active document at the current location of the cursor.

Public Sub OnTextButton(ByVal control As Office.IRibbonControl)
    Dim currentRange As Word.Range = Globals.ThisAddIn.Application.Selection.Range
    currentRange.Text = "This text was added by the Ribbon." 
End Sub

public void OnTextButton(Office.IRibbonControl control)
{
    Word.Range currentRange = Globals.ThisAddIn.Application.Selection.Range;
    currentRange.Text = "This text was added by the Ribbon.";
}

Add the following method to the MyRibbon class. This is a callback method for the Insert Table button that adds a table to the active document at the current location of the cursor.

Public Sub OnTableButton(ByVal control As Office.IRibbonControl)
    Dim missing As Object = System.Type.Missing

    Dim currentRange As Word.Range = Globals.ThisAddIn.Application.Selection.Range
    Dim newTable As Word.Table = Globals.ThisAddIn.Application.ActiveDocument.Tables.Add( _
               currentRange, 3, 4)

    ' Get all of the borders except for the diagonal borders. 
    Dim borders() As Word.Border = New Word.Border(6) {}
    borders(0) = newTable.Borders(Word.WdBorderType.wdBorderLeft)
    borders(1) = newTable.Borders(Word.WdBorderType.wdBorderRight)
    borders(2) = newTable.Borders(Word.WdBorderType.wdBorderTop)
    borders(3) = newTable.Borders(Word.WdBorderType.wdBorderBottom)
    borders(4) = newTable.Borders(Word.WdBorderType.wdBorderHorizontal)
    borders(5) = newTable.Borders(Word.WdBorderType.wdBorderVertical)

    ' Format each of the borders. 
    For Each border As Word.Border In borders
        border.LineStyle = Word.WdLineStyle.wdLineStyleSingle
        border.Color = Word.WdColor.wdColorBlue
    Next 
End Sub

public void OnTableButton(Office.IRibbonControl control)
{
    object missing = System.Type.Missing;
    Word.Range currentRange = Globals.ThisAddIn.Application.Selection.Range;
    Word.Table newTable = Globals.ThisAddIn.Application.ActiveDocument.Tables.Add(
    currentRange, 3, 4, ref missing, ref missing);

    // Get all of the borders except for the diagonal borders.
    Word.Border[] borders = new Word.Border[6];
    borders[0] = newTable.Borders[Word.WdBorderType.wdBorderLeft];
    borders[1] = newTable.Borders[Word.WdBorderType.wdBorderRight];
    borders[2] = newTable.Borders[Word.WdBorderType.wdBorderTop];
    borders[3] = newTable.Borders[Word.WdBorderType.wdBorderBottom];
    borders[4] = newTable.Borders[Word.WdBorderType.wdBorderHorizontal];
    borders[5] = newTable.Borders[Word.WdBorderType.wdBorderVertical];

    // Format each of the borders. 
    foreach (Word.Border border in borders)
    {
        border.LineStyle = Word.WdLineStyle.wdLineStyleSingle;
        border.Color = Word.WdColor.wdColorBlue;
    }
}

Testing the Add-In

When you run the project, Word 2007 opens and the tab named Add-Ins appears on the Ribbon. Click the Insert Text and Insert Table buttons on the Add-Ins tab to test the code.

To test your add-in

Press F5 to run your project.
Confirm that the Add-Ins tab is visible on the Ribbon.
Click the Add-Ins tab.
Confirm that the Content group is visible on the Ribbon.
Click the Insert Text button in the Content group.

A string is added to the document at the current location of the cursor.
Click the Insert Table button in the Content group.

A table is added to the document at the current location of the cursor.

Next Steps

You can learn more about how to customize the Office UI from these topics:

Customize the Ribbon of a different Office application. For more information about the applications that support customizing the Ribbon, see Ribbon Overview.
Customize the Ribbon of an Office application by using the Ribbon Designer. For more information, see Ribbon Designer.
Create a custom actions pane. For more information, see Actions Pane Overview.
Customize the UI of Microsoft Office Outlook 2007 by using Outlook Form Regions. For more information, see Walkthrough: Designing an Outlook Form Region.