Export (0) Print
Expand All

Walkthrough: Automating an Application from Controls on the Ribbon

Note Required applications

The features in this topic are available only if you have the required applications installed.

For more information, see Features Available by Product Combination.

  • One of these development environments:

    VSTO 2005

    -or-

    Visual Studio Team System

    -or-

    Visual Studio 2005 Professional Edition

  • VSTO 2005 SE installed in the development environment

  • 2007 Microsoft Office system

You can create groups of controls on a custom tab in the Ribbon to expose functionality in an application-level add-in, such as automating an application in the 2007 Microsoft Office system.

This walkthrough illustrates the following tasks:

  • Adding several buttons to the Add-Ins tab.

  • Automating Microsoft Office Word 2007 from the buttons on the Ribbon.

  • Testing your project.

NoteNote

The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, select Import and Export Settings on the Tools menu. For more information, see Visual Studio Settings.

You need the following components to complete this walkthrough:

  • One of these two development environments:

    • Microsoft Visual Studio 2005 Tools for the Microsoft Office System (VSTO 2005).

      -or-

    • Visual Studio 2005 Professional.

  • Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System (VSTO 2005 SE).

  • Microsoft Office Word 2007.

Ribbons are implemented in application-level add-ins. Start by creating an add-in project for Word 2007.

To create a new project

  • Create a Word Add-in project with the name MyRibbonAddIn. Make sure 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.

You create the Add-Ins tab by adding a Ribbon 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.

  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 the MyRibbon.cs or MyRibbon.vb file, locate the code comments that start with TODO:, and uncomment the definition of the ThisAddIn class. This code enables Word 2007 to discover and load your custom Ribbon UI. For more information, see Ribbon Extensibility Overview.

    After you uncomment the code, it should resemble the following example.

    // TODO:
    // This is an override of the RequestService method in ThisAddin class.
    // To hook up your custom ribbon uncomment this code.
    public partial class ThisAddIn
    {
        MyRibbon ribbon;
        protected override object RequestService(Guid serviceGuid)
        {
            if (serviceGuid == typeof(Office.IRibbonExtensibility).GUID)
            {
                if (ribbon == null)
                    ribbon = new MyRibbon();
                return ribbon;
            }
    
            return base.RequestService(serviceGuid);
        }
    }
    
    
  5. In Solution Explorer, right-click the MyRibbon project and then click Build. Verify that the project builds without errors.

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, you will 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 Extensibility Overview.

To add buttons to the Add-Ins tab

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

  2. Replace the contents of the tab element with the following XML. This XML changes the label of the default control group, 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>
    

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 Extensibility Overview.

To add callback methods for the buttons

  1. In Solution Explorer, right-click MyRibbon.cs or MyRibbon.vb and 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;
    
    
  3. Delete the OnToggleButton1 method. This method is automatically generated by VSTO 2005 SE, and it is not needed for this walkthrough.

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

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

  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.

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

  • Customize the Ribbon in an add-in for a different application in the 2007 release of Microsoft Office. For more information about the applications that support customizing the Ribbon, see Ribbon Extensibility Overview.

  • Create a custom task pane by using an add-in. For more information, see Custom Task Panes Overview.

Community Additions

ADD
Show:
© 2014 Microsoft