Walkthrough: Create a custom tab by using Ribbon XML

Applies to: Visual Studio Visual Studio for Mac

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

Applies to: The information in this topic applies to document-level projects and VSTO Add-in projects for the following applications: Excel; InfoPath 2013 and InfoPath 2010; Outlook; PowerPoint; Project; Visio; Word. For more information, see Features available by Office application and project type.

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 by using the buttons on the Add-Ins tab.

Prerequisites

You need the following components to complete this walkthrough:

• An edition of Visual Studio that includes the Microsoft Office developer tools. For more information, see Configure a computer to develop Office solutions.

• Microsoft Word.

Create the project

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

To create a new project

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

   For more information, see How to: Create Office projects in Visual Studio.

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

Create the VSTO 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

1. On the Project menu, click Add New Item.

2. In the Add New Item dialog box, select Ribbon (XML).

3. 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.

4. In Solution Explorer, right-click ThisAddin.cs or ThisAddin.vb, and then click View Code.

5. 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 override Microsoft.Office.Core.IRibbonExtensibility CreateRibbonExtensibilityObject()
   {
       return new MyRibbon();
   }
   

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

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

Add buttons to the Add-ins tab

The goal for this VSTO 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

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

2. 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>
   

Automate 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

1. In Solution Explorer, right-click MyRibbon.cs or MyRibbon.vb, and then click Open.

2. 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.

   using Word = Microsoft.Office.Interop.Word;
   

   Imports Word = Microsoft.Office.Interop.Word
   

3. 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 void OnTextButton(Office.IRibbonControl control)
   {
       Word.Range currentRange = Globals.ThisAddIn.Application.Selection.Range;
       currentRange.Text = "This text was added by the Ribbon.";
   }
   

   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
   

4. 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 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;
       }
   }
   

   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
   

Testing the VSTO Add-in

When you run the project, Word 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 VSTO Add-in

1. Press F5 to run your project.

2. Confirm that the Add-Ins tab is visible on the ribbon.

3. Click the Add-Ins tab.

4. Confirm that the Content group is visible on the ribbon.

5. Click the Insert Text button in the Content group.

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

6. 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 by using Outlook Form Regions. For more information, see Walkthrough: Design an Outlook form region.

See also

• Ribbon overview
• Ribbon XML
• Walkthrough: Create a custom tab by using the Ribbon Designer