Customizing the Office (2007) Ribbon User Interface for Developers (Part 1 of 3)

http://msdn2.microsoft.com/en-us/library/ms406046.aspx

Customizing the Office (2007) Ribbon User Interface for Developers (Part 1 of 3)

Summary: Learn how to customize the Ribbon user interface (UI) in the 2007 Microsoft Office release. Also learn how new features in Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System support RAD development of Ribbon customizations. (40 printed pages)

Frank Rice, Microsoft Corporation

Ken Getz, MCW Technologies, LLC

Published: May 2006

Updated: October 2006

Applies to: Microsoft Office Access 2007, Microsoft Office Excel 2007, Microsoft Office Outlook 2007, Microsoft Office PowerPoint 2007, Microsoft Office Word 2007, Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System, Microsoft Visual Studio 2005

Contents

• An Improved User Interface

• New Ways to Enhance the User's Experience

• What About Existing Solutions?

• Customizing the Ribbon UI for Most Office Applications

• Using Callbacks

• Two Ways to Customize the Ribbon UI

• Adding Document-Based Add-ins to the Ribbon UI

• UI Customization in Access 2007

• Creating an Access Application-Level Custom Ribbon

• Loading Customizations at Run Time

• Ribbon Customization Scenarios for Other Applications

• Using COM Add-ins to Modify the Ribbon UI

• Working with Existing Command-Bar Add-Ins

• Dynamically Updating the Ribbon UI

• Loading Images

• Conclusion

• Additional Resources

An Improved User Interface

Many of the applications in the 2007 Microsoft Office system have a new look. The Ribbon user interface (UI) feature replaces the current system of layered menus, toolbars, and task panes with a simpler system optimized for efficiency and discoverability. The new UI has improved context menus, Enhanced ScreenTips, a Mini toolbar, and keyboard shortcuts that help to improve user efficiency and productivity.

Note:

The Ribbon UI is implemented in several applications in the 2007 Microsoft Office release, including Microsoft Office Access 2007, Microsoft Office Excel 2007, Microsoft Office PowerPoint 2007, and Microsoft Office Word 2007. The Ribbon is also available in Microsoft Office Outlook 2007 while you edit an Outlook item. You can customize the Ribbon UI through a combination of XML markup and any Microsoft .NET Framework–based language that is supported in Microsoft Visual Studio. You can also customize the Ribbon UI by using Microsoft Visual Basic for Applications (VBA), Microsoft Visual C++, and Microsoft Visual Basic 6.0.

New Ways to Enhance the User's Experience

Developers have taken advantage of the tools and programming structures in earlier versions of Office to extend the UI in creative ways. For example, the command bars object model enabled developers to build rich solutions in their custom Office applications. Continuing in that tradition, Ribbon extensibility, or RibbonX, introduces an innovative model that you can use to enhance the user experience. You use extensible markup language (XML) and one of several conventional programming languages to manipulate the components that make up the Ribbon UI. Because XML is plain text, you can create customization files in any text editor, which simplifies work with the UI. You can also reuse custom Ribbon UI files with a minimum of adjustments because each application uses the same programming model.

Figure 1. The Ribbon UI in applications in the 2007 Office release

Using XML markup files to customize the UI greatly reduces the need for complex add-ins based on the command bars object model. However, add-ins written for previous versions of Office will continue to work in the Ribbon UI with little or no modification.

What About Existing Solutions?

In previous versions of Office, developers used the command bars object model to build the Visual Basic code that modified the UI. In the 2007 release of Office, this legacy code continues to work in most cases without modification. However, changes made to toolbars in Microsoft Office 2003 now appear on an Add-Ins tab. The type of customization that appears depends on the original design of the add-in. For example, Office creates a Menu Commands group that contains items added to the previous menu structure (such as the File menu, the Insert menu, and the Tools menu). Office also creates a Toolbar Commands group that contains items added to the previous built-in toolbars (such as the Standard toolbar, the Formatting toolbar, and the Picture toolbar). In addition, custom toolbars that are added by an add-in or 　document appear in the Custom Toolbars group on the Add-Ins tab.

Customizing the Ribbon UI for Most Office Applications

You can create a custom application-level Ribbon UI in Word 2007, in Excel 2007, or in PowerPoint 2007 in the following ways:

• By using COM add-ins in managed or unmanaged code

• By using application-specific add-ins, such as .ppam and .xlam files

• By using templates (.dotm files) in Word 2007

Note:
Access 2007 and Outlook 2007 implement Ribbon customizations in slightly different ways than the other Office applications do.

In a typical scenario, code in a COM add-in contains a procedure that returns XML markup from an external customization file or from XML contained in the code itself. When the application starts, the add-in loads and runs the code that returns the XML markup. The code validates the XML markup against an XSD schema (though that is optional), and then loads the XML into memory and applies it to the Ribbon UI. The modified Ribbon UI then appears. Ribbon UI commands and controls use callback procedures to run code in the add-in.

Document-level customizations use the same XML markup and an Office Open XML Formats file with one of these extensions: .docx, .docm, .xlsx, .xlsm, .pptx, or .pptm. For these solutions, you create a customization file that contains the XML markup and save it to a folder. You then modify the parts in the Office Open XML Formats container to point to the customization file. When you open the 　document in the Office application, the application loads the customization file into memory and applies it to the Ribbon UI. The commands and controls then call code contained in the 　document to provide functionality.

Using Callbacks

You specify callbacks to update properties and perform actions from your UI at run time. For example, to specify an action that occurs when the user clicks a button on the Ribbon, you must supply the onAction callback function for the button. The RibbonX markup looks like this:

Xml

Copy Code

<button id="myButton" onAction="MyButtonOnAction" />

This markup tells Office to call the MyButtonOnAction method when the button is clicked. The MyButtonOnAction method has a specific signature depending on your choice of languages; here is an example:

C#

Copy Code

public void MyButtonOnAction (IRibbonControl control){    if (control.Id == "myButton")    {        System.Windows.Forms.MessageBox.Show("Button clicked!");    }}

Note:
Depending on how you create your customization, you may need to add a reference to the System.Windows.Forms assembly to call the MessageBox.Show method.

The MyButtonOnAction procedure must be declared as public. The control parameter carries the unique id and tag properties of the control, which enables you to use the same callback procedure for multiple controls.

Note:
All attributes in the Ribbon XML customization markup use the camel-casing convention, which capitalizes the first character of each word except the first word—examples include onAction and insertBeforeMso.

Two Ways to Customize the Ribbon UI

Applications that support the Ribbon (except Access 2007, as described later in this article) provide two ways to customize the Ribbon UI by using XML markup: by using Office Open XML Formats files that contain XML markup, or by using COM add-ins that contain XML markup. (In the case of Outlook, only COM add-ins can customize the Ribbon UI.) Any changes that you specify in this XML markup add incrementally to the existing Ribbon UI. For example, providing XML markup that identifies a custom tab adds a single tab to the existing tabs in the host application.

All controls in RibbonX markup must include one of the following identifiers.

Table 1. One of these identifiers must be used with all controls

Identifier	Description
id	Specifies a unique identifier for the control. Used with custom controls. This identifier is passed as a property on an IRibbonControl to callback functions.
idMso	Specifies the identifier of a built-in control.
idQ	Specifies a qualified identifier, prefixed with a namespace abbreviation, as in the following example. Xml Copy Code <customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui" xmlns:x="myNameSpace"><button idQ="x:myButton" … />

Note:
The example uses the namespace x so that two different add-ins can add to the same custom group—they just need to refer to that custom group by its qualified name.

General Format of XML Markup Files

You can use XML markup to customize the Ribbon UI. The following example shows the general format of an XML markup file that customizes the Ribbon UI in Word 2007. Examples in the following sections use this markup.

Xml

Copy Code

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui">  <ribbon>    <tabs>      <tab idMso="TabHome">        <group idMso="GroupFont" visible="false" />      </tab>      <tab id="CustomTab" label="My Tab">        <group id="SampleGroup" label="Sample Group">          <toggleButton id="ToggleButton1" size="large"             label="Large Toggle Button"             getPressed="ThisDocument.MyToggleMacro"            onAction="ThisDocument.MyActionMacro"  />          <checkBox id="CheckBox1" label="A CheckBox"             screentip="This is a check box"             onAction="ThisDocument.MyCheckboxMacro" />          <editBox id="EditBox1" getText="ThisDocument.MyTextMacro"             label="My EditBox" onChange="ThisDocument.MyEditBoxMacro"/>          <comboBox id="Combo1" label="My ComboBox"             onChange="ThisDocument.MyComboBoxMacro">            <item id="Zip1" label="33455" />            <item id="Zip2" label="81611" />            <item id="Zip3" label="31561" />          </comboBox>          <dialogBoxLauncher>            <button id="Launcher1" screentip="My Launcher"               onAction="ThisDocument.MyLauncherMacro" />          </dialogBoxLauncher>        </group>        <group id="MyGroup" label="My Group" >          <button id="Button1" label="My Large Button"             size="large" onAction="ThisDocument.MyButtonMacro" />          <button id="Button2" label="My Normal Button"             size="normal" onAction="ThisDocument.MyOtherButtonMacro" />        </group >      </tab>    </tabs>  </ribbon></customUI>

This XML markup results in a modified Ribbon UI, as the following figure shows.

Figure 2. Sample of Ribbon UI customization in Word

This sample makes the following changes to the Ribbon UI in Word 2007, in the order shown:

1. The sample declares the default namespace for the XML markup.

2. The sample hides the built-in GroupFont group that is located on the built-in Home tab.

3. The sample adds a new CustomTab tab to the right of the last built-in tab, with the label My Tab.

   Note:
   Use the id identifier attribute to create a custom item, such as a custom tab. Use the idMso identifier attribute to refer to a built-in item, such as the TabHome tab.

4. The sample adds a new SampleGroup group to the My Tab tab.

5. The sample adds a large-sized ToogleButton1 button to the My Group group. The markup specifies onAction and getPressed callbacks.

6. The sample adds a CheckBox1 check box to the My Group group with a custom screentip. It also specifies an onAction callback.

7. The sample adds an EditBox1 edit box to the My Group group and specifies an onChange callback.

8. The sample adds a Combo1 combo box to the My Group group with three items and specifies an onChange callback.

9. The sample adds a Launcher1 launcher to the My Group group with the onAction callback set.

   A launcher normally displays a custom dialog box that offers more options to the user.

10. The sample adds a new My Group group to the custom tab.

11. The sample adds a large-sized Button1 button to the My Group group and specifies getText and onAction callbacks.

12. The sample adds a normal-sized Button2 button to the My Group group and specifies an onAction callback.

The easiest way to create RibbonX markup is to use a validating XML editor. Microsoft Visual Studio 2005 provides such an editor that you can use, if you can provide the necessary schema (XSD) file. In this case, you need a current copy of customUI.xsd, which is available in several places. For example, when you install Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System (also known as Visual Studio 2005 Tools for Office Second Edition), it adds the schema to the Visual Studio schema catalog, so the schema is available by default in a Visual Studio project. You can also find the schema at the Microsoft Office Developer Center: Ribbon Web site. In Visual Studio, create a new XML file, and in the Properties window, set the Schemas property to include the customUI.xsd file (or enter the schema reference in the code, as shown in the previous XML 　document). Then, as you enter XML content into the file, you can take advantage of Microsoft IntelliSense technology. You might also find the XML Notepad 2006 download useful; it is available from the Microsoft Download Center. This tool enables you to edit and view XML content in a tree-based format.

Customizing the Ribbon UI by Using Office Open XML Formats Files

At the 　document level, the process for customizing the UI by using XML markup involves the following steps. For more information, see Adding Document-Based Add-ins to the Ribbon UI later in this article. You can follow these steps, using the XML markup described in the previous section.

Note:

Although it is useful to know what is going on within the Office Open XML Formats structure, you may be able to bypass these steps. You can take advantage of the Custom UI Editor, available at OpenXMLDeveloper.org. This tool enables you to open a 　document, insert custom UI, and then save the 　document with the RibbonX markup in place. It performs for you the steps listed in this example. It also enables you to add custom icons to the customUI folder, and makes it easy to refer to these icons. You can download the Custom UI Editor from the OpenXMLDeveloper.org Custom UI Editor Tool Web page.

To customize the Ribbon UI by using Office Open XML Formats files

1. Create a folder on your desktop named customUI.

2. Create the customization file in any text editor by writing XML markup that adds new components to the Ribbon UI, modifies existing components, or hides components. You can use the XML markup from the previous example, to test the behavior. Save the file as customUI.xml (or any other name) in the folder you just created.

3. Validate the XML markup against your custom UI schema (optional).

4. Create a 　document in the Office application, and then save it as an Office Open XML Formats file with one of these extensions: .docx, .docm, .xlsx, .xlsm, .pptm, or .pptx.

   File name extensions for files that contain macros have an "m" suffix. These files can contain procedures that can be called by RibbonX commands and controls.

   Caution:
   You must save the 　document in macro-enabled format if you want to add code that reacts when the user interacts with the Ribbon customization. Documents with this functionality include the .docm, .xlsm, and .pptm formats. For all the examples in this article that include Microsoft Visual Basic for Applications (VBA) code, you must save the host 　document as one of these formats.

5. Exit the Office application.

6. In Microsoft Windows Explorer, add the file name extension .zip to the 　document file name, and then double-click the file to open it as a compressed folder.

7. Add the customization file to the container by dragging the customUI folder from the desktop to the compressed folder.

8. Drag the _rels folder to the desktop. A folder named _rels containing the .rels file appears on the desktop.

9. Open the new folder, and then open the .rels file in a text editor.

10. Between the final <Relationship> element and the closing <Relationships> element, add a line that creates a relationship between the 　document file and the customization file. Ensure that you specify the folder and file names correctly (the Id attribute supplies a unique relationship ID for the customUI—its value is arbitrary).

    Xml

    Copy Code

    <Relationship Type="http://schemas.microsoft.com/office/2006/  relationships/ui/extensibility" Target="/customUI/customUI.xml"   Id="customUIRelID" />

11. Save the .rels file.

12. Drag the .rels file from the desktop to the _rels folder in the compressed file, replacing the existing .rels file.

13. Remove the .zip extension from the container file.

When you open the file in the Office application, the Ribbon UI appears with your customizations. Depending on your application settings, if you use the markup from the previous section in this example, you might receive several warning messages as you open the 　document. Because you have not supplied the code that corresponds to the various callback procedures, you have not really created a complete custom UI yet.

Adding Document-Based Add-ins to the Ribbon UI

The following steps outline the basic process for creating a 　document that contains a simple custom Ribbon UI in Excel 2007 that can call a custom macro:

1. Create a macro-enabled Excel workbook with one macro.

2. Create a file to customize the Ribbon UI by adding one tab, one group, and one button.

3. Create a procedure in VBA that the Ribbon UI calls, in response to the button being clicked.

4. Specify the onAction callback attribute in the button's markup, so that it calls the macro you created in the 　document.

5. Modify the contents of the macro-enabled 　document container so that it contains the file that customizes the UI.

6. Save the macro-enabled file, and then open it in Excel 2007.

Note:
You can follow these same basic steps when creating a macro-enabled Word or PowerPoint 　document.

To create an Excel workbook that is macro-enabled

1. Start Excel 2007.

2. Click the Developer tab, and then click Visual Basic.

   Note:
   If you do not see the Developer tab, you must identify yourself as a developer. To do this in your application, click the Microsoft Office Button, click Application Options, click Popular, and then select Show Developer Tab in the Ribbon. This is a global setting that identifies you as a developer in all Office applications that implement the Ribbon UI.

3. In the Visual Basic Editor, double-click ThisWorkbook to open the Code window.

4. Type the following VBA function, and then click the Excel icon in the left corner of the toolbar to return to Excel.

   Visual Basic

   Copy Code

   Sub MyMacro(ByVal control as IRibbonControl)   MsgBox("Hello World")End Sub

5. Save the 　document as a macro-enabled workbook with the file name extension .xlsm.

   Note:
   If you save the 　document as a standard .xlsx 　document, you will not be able to run the macro code. When you save the 　document, you must explicitly select the Save As menu option, and then select Excel Macro-Enabled Workbook (*.xlsm).

6. Exit Excel.

To create the file that contains the XML markup to modify the UI

1. Create a folder on your desktop named customUI.

2. Create a new text file, add the following XML, and then save the file as customUI.XML in the customUI folder on your desktop.

   Xml

   Copy Code

   <customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui">   <ribbon startFromScratch="true">     <tabs>       <tab id="CustomTab" label="My Tab">         <group id="SimpleControls" label="My Group">           <button id="Button1" imageMso="HappyFace" size="large"             label="Large Button"             onAction="ThisWorkbook.MyMacro" />         </group>       </tab>     </tabs>   </ribbon> </customUI>

To modify files contained in the macro-enabled file container

1. In Windows Explorer, find the macro-enabled file you created. Rename the file by adding the .zip extension.

2. In Windows Explorer, double-click the file to open it.

3. Add the customization file to the container by dragging the customUI folder from the desktop to the compressed folder and clicking the Add button when prompted.

4. Drag the _rels folder to the desktop.

5. Open the new folder, and then open the .rels file in a text editor.

6. Add the following text between the last <Relationship> element and the </Relationships> element, and then save and close the file.

   Xml

   Copy Code

   <Relationship Id="customUIRelID" Type="http://schemas.microsoft.com/office/2006/relationships/ui/extensibility" Target="customUI/customUI.xml" />

7. Drag the .rels file from the desktop to the _rels folder in the compressed folder, replacing the existing .rels file.

8. Remove the .zip extension from the container file name.

9. Open the macro-enabled file in Excel 2007. The custom UI replaces the built-in Ribbon UI.

   Note:
   Depending on your security settings, you might see a security warning telling you that macros have been disabled. If you do, click the Options button that appears next to the warning, select Enable this content, and then click OK.

10. Click Large Button. Clicking the button triggers the onAction callback, which calls the macro in the workbook, which displays the "Hello World" message.

Customizing the Ribbon UI with COM Add-Ins

Customizations at the application level result in a modified Ribbon UI that appears in the application regardless of which 　document is open. Generally, COM add-ins make these modifications. You generally have two options for creating COM add-ins by using managed code: You can use the Shared Add-In template that is included with Visual Studio 2005, or you can use Visual Studio 2005 Tools for Office Second Edition, which makes it even easier to create add-ins. The following steps describe the underlying method call sequence for a COM add-in that customizes the Ribbon. Although the concepts are the same no matter how you create the add-in, the specific code that you need to write will be different, as you will see in later sections of this article that walk you through examples that create add-ins, by using both techniques.

To customize the Ribbon UI by using COM add-ins

1. Create a COM add-in project.

   The add-in you create must implement the Extensibility.IDTExtensibility2 interface and the IRibbonExtensibility interface (found in the Microsoft.Office.Core namespace).

2. Build the add-in and Setup project and then install the project.

3. Start the Office application.

When the add-in loads, the IDTExtensibility2::OnConnection event is triggered, which initializes the add-in, just as in previous versions of Office.

Next, Office calls either the QueryInterface method (for unmanaged add-ins) or the QueryService method (for managed add-ins), which determines whether the add-in implements the IRibbonExtensibility interface. If it does, Office calls the IRibbonExtensibility::GetCustomUI method, which returns the XML markup (from an XML customization file or from XML markup embedded in the procedure), and then Office loads the customized Ribbon UI into the application. Finally, the customized UI is ready for the user.

Caution:
Because of the internal architecture of the Ribbon callback mechanism, it is important that you perform no initialization within the GetCustomUI method other than preparing and returning the XML markup for the Ribbon. Specifically, do not display dialog boxes or message windows from within this callback method.

Each control specified in the XML markup exposes its functionality by calls to callback procedures. For example, the XML markup for a button control can specify an onAction attribute that points to a procedure that is executed when the user clicks the button. In most cases, the callback procedure exposes an IRibbonControl interface that identifies the control. The callback might pass other arguments as well, such as a Boolean object that specifies the state of a toggle button as pressed or not pressed. The IRibbonControl interface implements three properties: the Context object, the Id object, and the Tag property. The Context object is the active window that contains the Ribbon that triggers the callback. The Id object is the string identifier of the custom control specified in the markup. The Tag property is a non-unique property that you can optionally specify in the markup.

UI Customization in Access 2007

RibbonX customizations in Access 2007 share some of the same options that the other Office applications have, but with some important differences. Just as with the other applications, you customize the Access Ribbon UI by using XML markup. And like the other applications, you can use external files that contain XML markup or COM add-ins to integrate Ribbon customizations into your application. However, unlike the other Office applications, because Access database files are binary and cannot be opened as Office Open XML Formats files, you cannot customize the Access Ribbon by adding parts to the database file.

Access does provide flexibility in customizing the Ribbon UI. For example, customization markup can be stored in a table, embedded in a VBA procedure, stored in another Access database, or linked to from an Excel worksheet. You can also specify a custom UI for the application as a whole or for specific forms and reports.

The following scenarios can give you an idea of how to customize the Access UI.

Note:
Because these walkthroughs involve changes to the database, you might want to perform these steps in a non-production database, perhaps by using a backup copy of a sample database.

Customizing the Access Ribbon UI

When customizing the Access UI, you have two choices: You can store your customizations in a special table and have Access automatically load the markup for you, or you can store the customizations in a location of your choosing and load the markup manually by calling the Application.LoadCustomUI method.

If you choose to have Access load the customizations for you, you need to store them in a table named USysRibbons. The table should have at least two columns: a 255-character Text column named RibbonName, and a Memo column named RibbonXML. You place the Ribbon name in the RibbonName column, and the Ribbon markup in the RibbonXML column. After you close and re-open the database, you can select the default Ribbon to use in the Access Properties dialog box. You can select a Ribbon to appear when any form or report is selected as a property of the form or report.

If you decide to use a more dynamic technique, you can call the LoadCustomUI method, which loads Ribbon customizations whether the XML content is stored in a table or not. After you have loaded the customizations by calling LoadCustomUI, you can programmatically assign the named customization at run time.

Note:
Customizations that you load by using the LoadCustomUI method are available only while the database is open. You need to call LoadCustomUI each time you open the database. This technique is useful for applications that need to assign custom UI programmatically at run time.

The signature for the LoadCustomUI method is as follows.

expression .LoadCustomUI(CustomUIName As String, CustomUIXML As String)

expression returns an Application object.

CustomUIName is the name of the Custom Ribbon ID to be associated with this markup.

CustomUIXML contains the XML customization markup.

There is an example of using the LoadCustomUI method later in this section.

The following procedure describes, in a generalized manner, how to add application-level customizations in Access. A later section includes a complete walkthrough.

To apply a customized application-level Ribbon at design time

1. Create a table named USysRibbons with columns as described earlier. Add rows for each different Ribbon you want to make available.

2. Close and then reload the database.

3. Click the Microsoft Office Button, and then click Access Options.

4. Click the Current Database option and then, in the Ribbon and Toolbar Options section, click the Ribbon Name drop-down list and click one of the Ribbons.

To remove an existing customization (so that your database uses the default UI), delete the existing Ribbon name from the Ribbon Name list, and leave an empty value for the name of the Ribbon.

The following procedure describes, in a generalized manner, how to add form-level customizations or report-level customizations in Access.

To assign a specific custom Ribbon to a form or report

1. Follow the process described previously to make the customized Ribbon available to the application, by adding the USysRibbons table.

2. Open the form or report in Design view.

3. On the Design tab, click Property Sheet.

4. In the Property window, on the Other tab, click the Ribbon Name drop-down list, and then click one of the Ribbons.

5. Save, close, and then re-open the form or report. The UI you selected is displayed.

   Note:
   The tabs displayed in the Ribbon UI are additive. That is, unless you specifically hide the tabs or set the Start from Scratch attribute to True, the tabs displayed by a form or report's Ribbon UI appear in addition to the existing tabs.

To explore this process further, work through the following examples.

The first part of the example sets an option that reports any errors that exist when you load custom UI (although you are performing these steps in Access, you can perform similar steps in other applications).

Creating an Access Application-Level Custom Ribbon

To create an Access application-level custom ribbon

1. Start Access. Open an existing database, or create a new database.

2. Click the Microsoft Office Button, click Access Options, and then click the Advanced tab.

3. In the General section, select the option Show add-in user interface errors (this option might be in a different location, in different applications).

4. Click OK to close the Access Options dialog box.

   Next, create a table that contains your customization XML markup.

5. With a database open in Access, right-click the Navigation pane. Point to Navigation Options, and then click Show System Objects. (You cannot view the USysRibbons table in the Navigation pane unless this option is set.) Click OK to dismiss the dialog box. The Access system tables appear in the Navigation pane.

6. On the Create tab, click Table Design.

7. Add the following fields to the table.

   Table 2. USysRibbons table field definitions

   Field Name	Type
   ID	AutoNumber
   RibbonName	Text
   RibbonXml	Memo

8. Select the ID field. On the Design tab, select Primary Key.

9. Click the Microsoft Office Button, and then click Save. Name the new table USysRibbons.

10. Right-click the USysRibbons tab, and then click Datasheet View.

11. Add the following data to the fields you created.

    Table 3. USysRibbons table data

    Field Name	Value
    ID	(AutoNumber)
    RibbonName	HideData
    RibbonXml	Xml Copy Code <customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui"> <ribbon startFromScratch="false"> <tabs> <tab idMso="TabCreate" visible="false" /> <tab id="dbCustomTab" label="A Custom Tab" visible="true"> <group id="dbCustomGroup" label="A Custom Group"> <control idMso="Paste" label="Built-in Paste" enabled="true"/> </group> </tab> </tabs> </ribbon></customUI>

    This markup sets the startfromScratch attribute to False, and then hides the built-in Create tab. Next, it creates a custom tab and a custom group, and adds the built-in Paste control to the group.

12. Close the table.

13. Close and then re-open the database.

14. Click the Microsoft Office Button, and then click Access Options.

15. Click the Current Database tab, and scroll down until you find the Ribbon and Toolbar Options section.

16. In the Ribbon Name drop-down list, select HideData. Click OK to dismiss the dialog box.

17. Close and re-open the database.

    The Edit group is no longer displayed, and the Ribbon UI includes the A Custom Tab tab, which contains the A Custom Group group with the Built-in Paste button.

    Figure 3. The Access application-level Ribbon UI
    
    

18. To clean up, repeat the previous few steps to display the Access Options dialog box. Delete the contents of the Ribbon Name option, so that Access displays its default UI after you close and re-open the database.

    Note:
    You can also use a Ribbon from the USysRibbons table to supply the UI for a specific form or report. To do this, open the form or report in Design or Layout mode, and set the form's RibbonName property to the name of the Ribbon you want to use. You must select the form itself, rather than any control or section on the form, before you can set this property.

Loading Customizations at Run Time

If you want to load static customizations at run time, you can store those customizations in the USysRibbons table, and set a form or report's RibbonName property as necessary. But, if you need to create dynamic customizations, call the Application.LoadCustomUI method. The following example creates a Ribbon customization that displays a button for each form in the application, and handles the onAction callback for each button to load the requested form.

To create a dynamic Ribbon customization

1. Load the database that you worked with in the previous section into Access 2007. If your database does not already include more than one form, create a few forms, and add a control or two to each form.

2. On the Create tab, in the Other group, click the drop-down list of the Macro button, and then click Module.

3. In the Visual Basic Editor, on the View menu, click Properties Window.

4. In the Properties window, in the Name property box, change the name of the module to RibbonLoader.

5. In the code window, insert the following code. Even though this method does not return a value, it must be a function—otherwise, you cannot call it from an Access macro.

   Visual Basic

   Copy Code

   Function CreateFormButtons()  Dim xml As String  xml = _   "<customUI xmlns=""http://schemas.microsoft.com/" & _   "office/2006/01/customui"">" & vbCrLf & _   "  <ribbon startFromScratch=""false"">" & vbCrLf & _   "    <tabs>" & vbCrLf & _   "      <tab id=""DemoTab"" label=""LoadCustomUI Demo"">" & _     vbCrLf & _   "        <group id=""loadFormsGroup"" label=""Load Forms"">" & _     vbCrLf & _   "{0}" & vbCrLf & _   "        </group>" & vbCrLf & _   "      </tab>" & vbCrLf & _   "    </tabs>" & vbCrLf & _   "  </ribbon>" & vbCrLf & _   "</customUI>"  Dim template As String  template = "<button id=""load{0}Button"" " & _   "label=""Load {0}"" onAction=""HandleOnAction"" " & _   "tag=""{0}""/>" & vbCrLf    Dim formContent As String  Dim frm As AccessObject  For Each frm In CurrentProject.AllForms    formContent = formContent & _     Replace(template, "{0}", frm.Name)  Next frm    xml = Replace(xml, "{0}", formContent)  Debug.Print xml  On Error Resume Next  ' If you call this code from the AutoExec macro,  ' the only way it can fail is if you have a  ' customization with the same name in the  ' USysRibbons table.  Application.LoadCustomUI "FormNames", xmlEnd Function

   When you run the code, it creates markup that might look like the following XML, if your application contains two forms named Form1 and Form2.

   Xml

   Copy Code

   <customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui">  <ribbon startFromScratch="false">    <tabs>      <tab id="DemoTab" label="LoadCustomUI Demo">        <group id="loadFormsGroup" label="Load Forms">          <button id="loadForm2Button" label="Load Form2"             onAction="HandleOnAction" tag="Form2"/>          <button id="loadForm1Button" label="Load Form1"             onAction="HandleOnAction" tag="Form1"/>        </group>      </tab>    </tabs>  </ribbon></customUI>

   This markup creates a new LoadCustomUI Demo tab that contains a Load Forms group. Within the group, the Ribbon displays a button for each form in the application (Form1 and Form2), and indicates that each button should call the HandleOnAction callback procedure when clicked. In addition, the markup sets the Tag attribute for each button so that it contains the name of the Access form that your code should open.

6. Add the following procedure to the same module. This procedure supplies the callback behavior. It opens the selected form and sets its RibbonName property to the FormNames Ribbon customization.

   Visual Basic

   Copy Code

   Public Sub HandleOnAction(control As IRibbonControl)    ' Load the specified form, and set its    ' RibbonName property so that it displays    ' the custom UI.    DoCmd.OpenForm control.Tag    Forms(control.Tag).RibbonName = "FormNames"End Sub

7. Save the database, and close the Visual Basic Editor.

8. If your application does not contain at least two forms, create forms until the application contains at least two forms.

9. Decide which one of your forms should be your application's startup form, and open that form in Design view.

10. In the Properties window, on the Event tab, find the onLoad event property. Click the ellipsis (...) button to the right of the property value, select Code Builder in the list of options, and then click OK. (If you do not see the Properties window, on the Design tab, click Property Sheet.)

11. In the Visual Basic Editor, modify the Form_Load procedure so that it looks like the following code.

    Visual Basic

    Copy Code

    Private Sub Form_Load()    CreateFormButtons    Me.RibbonName = "FormNames"End Sub

12. On the Tools menu, click References. Select Microsoft Office 12.0 Object Library (you need a reference to this object library to use the IRibbonControl class), and then click OK.

13. Save the database and close the Visual Basic Editor.

14. Click the Microsoft Office Button, and then click Access Options.

15. Click the Current Database tab.

16. In the Application Options section, select your startup form in the Display Form list of forms, and then click OK.

17. Close and re-open the database.

    The startup form opens, along with a custom tab that contains a group that displays a button for each form in your application. Click any of the buttons: Access opens the corresponding form, maintaining the same custom UI.

In addition to the described techniques, you can add Ribbon customizations to Access by using a COM add-in. COM add-ins provide the benefit of adding custom RibbonX functionality as a package without the need to add VBA code to each application. Add-ins are implemented in Access just as they are in other Office applications.

Note:
Although you can use the Visual Studio 2005 Shared Add-In template to create a COM add-in for Access, you cannot use Visual Studio 2005 Tools for Office Second Edition to create COM add-ins for Access. Access is not one of the supported applications in Visual Studio 2005 Tools for Office Second Edition.

Ribbon Customization Scenarios for Other Applications

Consider the following scenarios that illustrate ways to modify the Ribbon UI to fit your needs.

Note:
To demonstrate the behavior of the Ribbon customizations in the following sections, you can use the techniques discussed earlier in this article, in the section titled Customizing the Ribbon UI for Most Office Applications.

Creating Custom Solutions

Although each example you have seen so far modifies the existing Ribbon, you can create your entire UI from scratch. You might do this if you want to build your own UI and design your own custom layout for the Ribbon. If you set the Ribbon element's startFromScratch attribute to True, the Ribbon hides all of its content (so you do not have to do the work to hide everything manually). When you set the startFromScratch attribute to True, it makes the following changes:

• Hides all the existing Ribbon tabs, including the Add-Ins tab

• Modifies the Microsoft Office menu to include only the New, Open, Save, Application Options, and Exit commands

  Caution:
  You can specify in the XML markup file that you want to hide the controls on the Microsoft Office menu. You must explicitly request these alterations in the XML markup by setting the Visible attribute for the particular control to False. Hiding these commands might put the application into an unrecoverable state that you can clear only by closing the application and uninstalling your solution.

Setting the startFromScratch attribute makes no changes to the status bar, which remains present.

The following sample XML markup uses the startFromScratch attribute to customize the Ribbon UI.

Xml

Copy Code

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui" >  <ribbon startFromScratch="true" >    <tabs>      <tab id="CustomTab" label="My Tab" >        <group id="SimpleControls" label="My Group">          <toggleButton id="ToggleButton1"            size="large" label="Large Toggle Button"/>          <button id="Button2" label="My Button " />          <comboBox id="Combo1" label="ComboBox">            <item id="Month1" label="January" />            <item id="Month2" label="February" />            <item id="Month3" label="March" />          </comboBox>        </group>      </tab>    </tabs>  </ribbon></customUI>

This sample hides all of the built-in components in the Ribbon UI and replaces them with a custom tab, one group, and various controls.

Showing and Hiding Tabs

You can use markup like the following sample to show or hide built-in tabs or custom tabs.

Xml

Copy Code

<tab idMso="TabHome" visible="false" />

If you want to programmatically determine whether to show or hide a tab (or other element), you can provide a callback procedure. That is, you can define the element as in the following XML.

Xml

Copy Code

<tab idMso="TabInsert" getVisible="getVisibleCallback" />

Then, in an add-in, or within VBA code, you can provide a procedure that returns a Boolean value that indicates whether the item is visible. For example, you might use code like the following to hide the Insert tab in Word 2007 on weekends.

Visual Basic

Copy Code

Public Sub getVisibleCallback(control As IRibbonControl, _    ByRef visible As Variant)    Select Case DatePart("w", Date)        Case vbSaturday, vbSunday            visible = False        Case Else            visible = True    End SelectEnd Sub

Showing and Hiding Groups

You can use code like the following sample (along with the callback procedure in the previous example) to show or hide built-in groups or custom groups.

Xml

Copy Code

<tab idMso="TabView">  <group idMso="GroupDocumentViews" visible="false" />  <group id="MyCustomGroup" label="Custom Group"     getVisible="getVisibleCallback" /></tab>

Adding Custom Tabs

You can use the following code sample to add custom tabs.

Xml

Copy Code

<tab id="CustomTab" label="My Tab" />

Adding Custom Groups with Controls

You can use the following code sample to add a custom group, and then add built-in controls.

Xml

Copy Code

<group id="CustomGroup" label="My Group">    <toggleButton idMso="Italic" />    <toggleButton idMso="Bold" />    <button idMso="FileSave" /> </group> 

You can use the following code to add a custom group, and then add custom controls.

Xml

Copy Code

<group id="CustomGroup" >    <toggleButton id="MyToggleButton" size="large"      label="Insert My Object"/>    <checkBox id="AllowChanges" label="Allow Changes" />    <dropDown id="ChooseDepartment" showLabel="true"      label="Choose Department">       <item id="Dept1" label="Shipping" />       <item id="Dept2" label="Accounting" />       <item id="Dept3" label="Engineering" />    </dropDown> </group>

Creating a Custom Menu with Nested Menus and Controls

You can use the following code sample to create a custom menu, and then add nested built-in menus and controls and custom menus and controls. This markup also includes two menu separators, with and without text.

Xml

Copy Code

<menu id="MyMenu" label="Test Menu" itemSize="normal">    <toggleButton idMso="Bold"/>    <button id="MenuButton1" label="Button1" />    <menuSeparator id="separator1"/>   <toggleButton id="MenuToggleButton1" label="ToggleButton" />    <button idMso="FileExit"/>    <menu id="Nested1" label="Advanced" itemSize="normal">       <button idMso="Cut"/>       <button idMso="Copy"/>       <button idMso="Paste"/>       <menuSeparator id="separator2" title="Large Buttons Below"/>        <menu id="Nested2" label="Large" itemSize="large">         <button idMso="Cut"/>          <button idMso="Copy"/>         <button idMso="Paste"/>       </menu>    </menu> </menu>

Adding Combo Boxes or Drop-Down Boxes with Nested Items

You can use the following code sample to add a built-in combo box control with items (drop-down controls use the same syntax).

Xml

Copy Code

<comboBox id="ComboBox1" label="ComboBox">     <item id="item1" label="one" imageMso="_1" />     <item id="item2" label="two" imageMso="_2" />     <item id="item3" label="three" imageMso="_3" /> </comboBox>

Adding Custom Gallery Controls with Items

You can use the following code sample to add gallery controls with items, and then add a custom button control.

Xml

Copy Code

<gallery id="MonthGallery" imageMso="DateAndTimeInsert"   label="Pick a Month:" columns="3" rows="4" onAction="InsertMonth" >  <item id="Month1" label="January"/>  <item id="Month2" label="February"/>  <item id="Month3" label="March"/>  <item id="Month4" label="April"/>  <item id="Month5" label="May"/>  <item id="Month6" label="June"/>  <item id="Month7" label="July"/>  <item id="Month8" label="August"/>  <item id="Month9" label="September"/>  <item id="Month10" label="October"/>  <item id="Month11" label="November"/>  <item id="Month12" label="December"/>  <button id="InsertMonthButton"     label="Insert current month" onAction="InsertCurrentMonth"/></gallery>

The following VBA procedures provide callback behavior for the gallery items and the button within the gallery.

Visual Basic

Copy Code

Sub InsertMonth(control As IRibbonControl, _    selectedId As String, selectedIndex As Integer)    Dim text As String    Select Case control.ID        Case "MonthGallery"            text = monthName(selectedIndex + 1)    End Select    Selection.InsertAfter textEnd SubSub InsertCurrentMonth(control As IRibbonControl)    Select Case control.ID        Case "InsertMonthButton"            text = monthName(DatePart("m", Date))    End Select    Selection.InsertAfter textEnd Sub

Note:
When you define the gallery, all item elements must appear before any button elements.

You can populate gallery controls at run time by using callbacks. You can use the getItemCount callback to determine the number of items to display, the getItemHeight and getItemWidth callbacks to retrieve the height and width of the items in the gallery, the getItemImage and getItemLabel callbacks to retrieve the image and label for each item, and the getSelectedItemID or getSelectedItemIndex callback to retrieve the selected ID or index.

Filling a Drop-Down List Dynamically

You might not know which items to display in a Ribbon control until run time. Callbacks make it possible to supply the values based on current conditions. For example, you might want to display a list of 　document headings. The following example demonstrates how you might provide a list of current 　document headings.

Include the following control in your Ribbon customization.

Xml

Copy Code

<dropDown id="HeadingsDropDown"   getItemCount="GetItemCount"   getItemID="GetItemID"   getItemLabel="GetItemLabel"/>

Then, in your code (in this case, in a module within the Word 　document's Visual Basic Editor), add the following callback procedures.

Visual Basic

Copy Code

Sub GetItemCount(control As IRibbonControl, ByRef count)    Dim varItems As Variant    varItems = ActiveDocument.GetCrossReferenceItems(wdRefTypeHeading)    count = UBound(varItems)End SubSub GetItemLabel(control As IRibbonControl, index As Integer, _    ByRef label)    Dim varItems As Variant    varItems = ActiveDocument.GetCrossReferenceItems(wdRefTypeHeading)    label = varItems(index + 1)End SubSub GetItemID(control As IRibbonControl, index As Integer, ByRef ID)    ID = "heading" & indexEnd Sub

Now, when you open the drop-down list, it shows all the headers in your 　document.

Grouping Individual Controls

By default, the Ribbon determines the positions of controls that you add to a group. If you want to define the layout of the controls with more precision, you can group the controls within one or more boxes. When you create a box, you specify its orientation (horizontal or vertical). A group can contain multiple boxes, and you can include vertical dividers between the boxes. (The vertical dividers are created by using the separator control, which is used only for vertical boxes.)

The following example sets up three groups, one that uses horizontal boxes, one that uses vertical boxes, and one that uses no boxes. Figure 4 shows the results.

Xml

Copy Code

<group id="CustomGroup1" label="Horizontal Boxes"    insertBeforeMso="GroupClipboard">  <box id="box1" boxStyle="horizontal">    <button id="buttonA1" label="Button1"/>    <button id="buttonA2" label="Button2"/>  </box>  <box id="box2" boxStyle="horizontal">    <button id="buttonAA" label="ButtonA"/>    <button id="buttonAB" label="ButtonB"/>    <button id="buttonAC" label="ButtonC"/>  </box></group><group id="CustomGroup2" label="Vertical Boxes"    insertBeforeMso="GroupClipboard">  <box id="box3" boxStyle="vertical">    <button id="buttonB1" label="Button1"/>    <button id="buttonB2" label="Button2"/>  </box>  <separator id="separator2"/>  <box id="box4" boxStyle="vertical">    <button id="buttonBA" label="ButtonA"/>    <button id="buttonBB" label="ButtonB"/>    <button id="buttonBC" label="ButtonC"/>  </box></group><group id="CustomGroup3" label="No Boxes"    insertBeforeMso="GroupClipboard">  <button id="buttonC1" label="Button1"/>  <button id="buttonC2" label="Button2"/>  <button id="buttonCA" label="ButtonA"/>  <button id="buttonCB" label="ButtonB"/>  <button id="buttonCC" label="ButtonC"/></group>

Figure 4. Different box styles

Using COM Add-ins to Modify the Ribbon UI

You can use COM add-ins to modify the Ribbon UI. When you decide to create a COM add-in that incorporates Ribbon customization and uses managed code, you have two distinct choices. You can create a standard shared add-in, using the Shared Add-In template that comes with Visual Studio 2005. Or, if you have installed Visual Studio 2005 Tools for Office Second Edition, you can create a COM add-in that has several advantages over the standard shared add-in.

Among other advantages, add-ins that you create by using Visual Studio 2005 Tools for Office Second Edition run in separate application domains, and the programming model for these add-ins is simpler, and more maintainable, than that used by the shared add-in template. For more information, see Migrating a Shared Add-in to a Visual Studio Tools for Office Add-In.

Using a Shared Add-in Project to Modify the Ribbon UI

The following example uses a managed COM add-in to add a custom Ribbon UI to Word 2007. The add-in creates a custom tab, a group, and a button. When you click the button, the add-in inserts a company name at the location of the cursor.

To create the add-in solution

1. Start Visual Studio 2005.

2. On the File menu, point to New, and then click Project.

3. In the New Project dialog box, in the Project Types pane, expand Other Project Types, click Extensibility, and then select Shared Add-in.

4. In the Name box, type InsertCompanyAddIn, and then click OK to create the project.

5. On the first page of the Shared Add-in Wizard, click Next.

6. On the Select a Programming Language page, select either Visual C# or Visual Basic, and then click Next.

7. On the Select an Application Host page, clear all of the selections except Microsoft Word, and then click Next.

8. On the Enter a Name and Description page, type InsertCompanyAddIn for the name and Insert Company Name for the description, and then click Next.

9. On the Choose Add-in Options page, select I would like my Add-in to load when the host application loads, click Next, and then click Finish.

Visual Studio creates a new solution that contains two projects—the add-in itself, and a Setup project. (The Setup project enables you to install the add-in on other users' computers, and it makes it easier for you, at design time, to install and uninstall the add-in.)

To interact with Word 2007 and the Ribbon object model, add references to two type libraries.

To add references

1. In Solution Explorer, expand the References folder.

   If you do not see the References folder, on the Project menu, click Show All Files.

2. Delete the Microsoft.Office.Core reference.

3. Right-click the References folder, and then click Add Reference.

4. Click the COM tab, select Microsoft Office 12.0 Object Library, and then click OK.

5. At the top of the open code file, add the following statements to the project.

   Visual Basic

   Copy Code

   Imports Microsoft.Office.CoreImports Word = Microsoft.Office.Interop.Word

   C#

   Copy Code

   using Microsoft.Office.Core;using Word = Microsoft.Office.Interop.Word;

To create an XML customization file

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

2. In the Add New Item dialog box, select XML File. Name the new file Ribbon.xml, and then click Add.

3. In the new XML file, add the following XML markup.

   Xml

   Copy Code

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

4. Save and close the file.

It is easiest to use the XML file if it is treated as a resource within the project's resource file.

To create the XML resource

1. In Solution Explorer, select Ribbon.xml.

2. In the Properties window, select the Build Action property, and then select Embedded Resource in the list of options.

3. On the Project menu, click InsertCompanyAddIn Properties.

4. Click the Resources tab.

5. From Solution Explorer, drag Ribbon.xml onto the Resources design surface.

   This action creates a new file-based resource that contains the XML content. From now on, the Ribbon.xml file is automatically stored as an application resource, and you can retrieve this content by using Visual Basic or Visual C# language features.

6. Close the Resources window. When prompted, click Yes to save the resources.

To access the host application and work with the Ribbon

1. In Solution Explorer, right-click Connect.cs or Connect.vb, and then click View Code.

2. Find the existing declaration for the applicationObject variable, and modify it so that it refers to a Word.Application object. That is, modify the declaration so that it looks like the following code.

   Visual Basic

   Copy Code

   Private applicationObject As Word.Application

   C#

   Copy Code

   private Word.Application applicationObject;

3. Modify the existing first line of the OnConnection method, which creates an instance of the Word.Application object.

   Visual Basic

   Copy Code

   applicationObject = DirectCast(application, Word.Application)

   C#

   Copy Code

   applicationObject =(Word.Application)application;

4. (Visual Basic only) Modify the line of code, near the top of the class, that starts with Implements, adding support for implementing the IRibbonExtensibility namespace. Visual Basic inserts the GetCustomUI procedure automatically.

   Visual Basic

   Copy Code

   Implements Extensibility.IDTExtensibility2, IRibbonExtensibility

5. (C# only) At the end of the public class Connect : statement, add a comma and then type the following interface name.

   C#

   Copy Code

   IRibbonExtensibility

6. (C# only) Right-click the interface you just added, click Implement Interface, and then click Implement Interface Explicitly. This adds a stub for the only IRibbonExtensibility interface member: GetCustomUI.

7. Modify the GetCustomUI method so that it looks like the following code.

   Visual Basic

   Copy Code

   Public Function GetCustomUI(ByVal RibbonID As String) As String _  Implements Microsoft.Office.Core.IRibbonExtensibility.GetCustomUI  Return My.Resources.RibbonEnd Function

   C#

   Copy Code

   string IRibbonExtensibility.GetCustomUI(string RibbonID){  Return Properties.Resources.Ribbon;}

   Caution:

   GetCustomUI should be implemented to return the XML string for your Ribbon customization, and should not be used for initialization. In particular, you should not attempt to display any dialog boxes or message windows in your GetCustomUI implementation. The more appropriate place to do initialization is in the OnConnection method (for shared add-ins) or in the ThisAddIn_Startup method (for add-ins created by using Visual Studio 2005 Tools for Office Second Edition).

8. Add the following method to the class. This method inserts the company name into the 　document at the current cursor location.

   Visual Basic

   Copy Code

   Public Sub InsertCompanyName(ByVal control As Office.IRibbonControl)  ' Inserts the specified text at the current location  ' in the 　document.  Dim companyName As String = "Microsoft Corporation"  applicationObject.Selection.InsertAfter(companyName)End Sub

   C#

   Copy Code

   public void InsertCompanyName(Office.IRibbonControl control){  // Inserts the specified text at the current location   // in the 　document.  string companyName = "Microsoft Corporation";  applicationObject.Selection.InsertAfter(companyName);}

9. On the File menu, click Save All.

10. Exit Word 2007 if it is running.

11. On the Build menu, click Build Solution.

12. In Solution Explorer, right-click InsertCompanyAddInSetup, and then click Build.

13. Right-click InsertCompanyAddInSetup, and then click Install.

    The InsertCompanyAddIn Setup Wizard appears.

14. Click Next on each of the pages, and then click Close on the last screen.

15. Start Word.

    The My Tab tab appears to the right of the other tabs.

16. Click My Tab, and then click Insert Company Name. Word inserts the specified company name into the 　document at the cursor location.

17. Exit Word.

18. In Visual Studio, in Solution Explorer, right-click InsertCompanyAddInSetup, and then click Uninstall.

Using a Visual Studio 2005 Tools for Office Second Edition Project to Modify the Ribbon UI

This example shows how to create the same add-in as in the previous example, but this time by using Visual Studio Tools 2005 Tools for Office Second Edition.

To create the project

1. Start Visual Studio 2005 Tools for Office Second Edition.

2. On the File menu, point to New, and then click Project.

3. In the New Project dialog box, select Visual Basic or Visual C#.

4. In the Project Types pane, expand the Office node, and select 2007 Add-ins.

5. In the Templates pane, select Word Add-in.

6. Name the new add-in InsertCompanyAddIn1, and then click OK to create the new add-in.

Visual Studio creates a new solution containing two projects—the add-in itself, and a Setup project. (The Setup project enables you to install the add-in on other users' computers, and it makes it easier for you to install and uninstall the add-in at design time.)

Note that although the new add-in implements the IExtensibility2 interface, you do not see all the procedures required by this interface. Instead, Visual Studio 2005 Tools for Office Second Edition creates a simple class named ThisAddIn, and provides the procedures you are likely to need. You can add code to the ThisAddIn_Startup method or to the ThisAddin_Shutdown method, as appropriate. For this example, you do not need code in either method. You also do not need to modify code or set references to create the add-in—all the connection work has been done for you.

To add a Ribbon extensibility item

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

2. In the Add New Item dialog box, select Ribbon Support.

3. Click Add to accept the default name (Ribbon1.vb or Ribbon1.cs).

   The template adds an XML file named Ribbon1.xml, and a new class to your project. The XML file contains a very simple customized UI. The new Ribbon1 file contains a commented-out extension of the ThisAddIn class, and a new class named Ribbon1.

4. In Solution Explorer, double-click Ribbon1.xml to open it in the XML editor.

5. Modify the existing XML, so that it looks like the following markup.

   Xml

   Copy Code

   <customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui"           onLoad="onLoad">  <ribbon>    <tabs>      <tab id="CustomTab" label="My Tools Tab">        <group id="SampleGroup" label="Sample Group">          <button id="Button" label="Insert Company Name"             size="large" onAction="InsertCompanyName" />        </group>      </tab>    </tabs>  </ribbon></customUI>

6. Save the XML file and close the XML editor.

It is easiest to use the XML file if it is treated as a resource within the project's resource file.

To create the XML resource

1. On the Project menu, click InsertCompanyAddIn1 Properties.

2. Click the Resources tab.

3. From Solution Explorer, drag Ribbon1.xml onto the Resources design surface.

   This action creates a new file-based resource that contains the XML content. From now on, the Ribbon1.xml file is automatically stored as an application resource, and you can retrieve this content by using Visual Basic or Visual C# language features.

4. Close the Resources window. When prompted, click Yes to save the resources.

To modify the Ribbon code and complete the add-in

1. In Solution Explorer, right-click Ribbon1.vb or Ribbon1.cs, and then click View Code.

2. In the Code Editor, select the partial class named ThisAddIn, and uncomment the partial class.

   The RequestService procedure enables the Visual Studio 2005 Tools for Office Second Edition runtime to determine which class should handle callbacks for the add-in's Ribbon customization. If this procedure is passed a GUID corresponding to the IRibbonExtensibility interface, it returns its IRibbonUI instance, if it has one. If not, it passes control to the RequestService method of its base class.

   Note:
   By default, the RequestService method appears in a comment because your add-in might already include an override for this method (perhaps for the FormRegionStartup interface, or one of the other new extensibility interfaces). If that is the case, you can copy the if block from the commented code into your existing override for this method.

3. In the Ribbon1 class, modify the GetCustomUI procedure so that it returns the XML from the Ribbon1 resource, rather than calling the add-in's GetResourceText procedure.

   Visual Basic

   Copy Code

   Return My.Resources.Ribbon1

   C#

   Copy Code

   return Properties.Resources.Ribbon1;

   Note:

   The add-in template includes, within the Helpers hidden region, a procedure named GetResourceText that retrieves the contents of the XML file for you. Although this procedure does the job you need, it requires you to specify the name of the resource as a string. This technique is somewhat brittle (changes to the resource name would still allow the code to compile, but the add-in would fail at run time), so it is better to add the XML content to the resource file and use the language-specific support for retrieving resources, as shown in these steps. The template includes the GetResourceText procedure so that it can work "out of the box"—when you create and build an add-in, you have a working Ribbon customization without any changes.

4. In the Ribbon1 class, add a public declaration for a variable that can refer to the Word Application object.

   Visual Basic

   Copy Code

   Public Application As Word.Application

   C#

   Copy Code

   public Word.Application Application;

5. In the same file, in the ThisAddIn partial class, immediately below the line of code that creates the instance of the Ribbon1 class, add code that sets the Ribbon1 class' Application property.

   Visual Basic

   Copy Code

   ' In the RequestService method:ribbon.Application = Application

   C#

   Copy Code

   // In the RequestService method:ribbon.Application = Application;

6. Add the following procedure to the Ribbon1 class, so that you can handle the onAction callback for the new button in the Ribbon and insert the company name at the cursor location in the 　document.

   Visual Basic

   Copy Code

   Public Sub InsertCompanyName(ByVal control As IRibbonControl)  ' Inserts the specified text at the current location  ' in the 　document.  Dim companyName As String = "Microsoft Corporation"  Application.Selection.InsertAfter(companyName)End Sub

   C#

   Copy Code

   public void InsertCompanyName(IRibbonControl control){  // Inserts the specified text at the current location   // in the 　document.  string companyName = "Microsoft Corporation";  Application.Selection.InsertAfter(companyName);}

To test the add-in

1. On the File menu, click Save All.

2. Press F5 to run the project, which also starts Word 2007.

3. Click the My Tools Tab tab, and then click Large Button.

   The code inserts the company name at the cursor location in the 　document.

4. Exit Word 2007.

You can build the Setup project and install the add-in just as you did in the previous example. In this case, Visual Studio 2005 Tools for Office Second Edition makes it easier to run (and debug) add-ins. Press F5, and the project runs as you might expect. You can get the same behavior with the shared add-in template—you just need to set the project properties that indicate which application you want to run when you press F5, and select the correct Office application. You might find it instructive to debug the add-in, and add a breakpoint to the code.

Working with Existing Command-Bar Add-Ins

When you create COM add-ins, you usually need a way for users to interact with the add-in. In earlier versions of Office, you accomplished this by adding a menu item or toolbar button to the application by using the command bars object model. In the 2007 release of Office, custom applications continue to work in the Ribbon UI without modification in most cases. However, changes you make with the command bars object model, or with any other technology that modifies the menus or toolbars, such as WordBasic or XLM, appear on a separate Add-Ins tab. This helps users locate the controls they need to work with and the add-ins they used previously.

Figure 5. A custom toolbar button added to the Add-Ins tab in Excel 2007

To make changes to the items on the Ribbon UI, you can use the techniques and code already described. For existing add-ins that change the menu structure, the commands appear on the Add-Ins tab. For information about how to update existing add-ins, see the technical article Migrating a Shared Add-in to a Visual Studio Tools for Office Add-In.

Dynamically Updating the Ribbon UI

Callbacks that return properties of a control (such as the gallery control's getItemCount callback) normally get called only as the Ribbon UI initializes, unless you explicitly force the control to re-initialize. You can force this to happen by storing a reference to the Ribbon in your code, and then calling methods of the Ribbon that invalidate an individual control or the entire Ribbon. To do this, you must add the onLoad attribute, specifying a callback procedure, in the <customUI> element. The onLoad callback is called once, when the RibbonX markup file is successfully loaded. The callback procedure receives an IRibbonUI object as a parameter—your code can cache this reference for later use. The IRibbonUI class provides methods that enable you to invalidate a single control or the entire Ribbon.

To cache the IRibbonUI object so you can update your controls at run time, you might add code like this:

Xml

Copy Code

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui"   onLoad="ribbonLoaded">

In your code (VBA code within a 　document, or perhaps Visual Basic code or C# code in an add-in), add a procedure like the following code.

C#

Copy Code

IRibbonUI myRibbon;public void ribbonLoaded(IRibbonUI ribbon) {  myRibbon = ribbon;}

The IRibbonUI interface exposes the following methods.

Table 4. Methods of the IRibbonUI interface

Method	Action	Description
Invalidate()	callback	Causes all of your custom controls to re-initialize.
InvalidateControl(string controlID)	callback	Causes a particular control to re-initialize.

Loading Images

The <customUI> element's loadImage attribute enables you to specify a callback that can load all images. After you set up this callback procedure, Office calls the callback procedure and passes the string from the image attribute for each control that loads images. You do not need to implement the getImage callback multiple times, such as one time for each control that requires images. For example, a customization might include markup like the following.

Xml

Copy Code

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui"   loadImage="GetImage"><!-- Later in the markup -->   <button id="myButton" image="mypic.jpg" />

To supply the button's image, Office calls the GetImage function. It passes the parameter "mypic.jpg" and expects an IPictureDisp object in return. By using this technique, you can write a single callback procedure that returns all the images your customization needs, without having to write each individual control's getImage callback. Note that the loadImage callback is not called again when you call the Ribbon's Invalidate method or InvalidateControl method. For the controls that need to change images dynamically at run time, use the getImage callback.

For example, you could use the code from the following example to provide your customization's images. The getImage callback method must return a stdole.IPictureDisp type, so you usually need to convert your images to this type. To perform these conversions, you can use the following PictureConverter class, which inherits from the AxHost class.

Visual Basic

Copy Code

Friend Class PictureConverter  Inherits AxHost  Private Sub New()    MyBase.New(String.Empty)  End Sub  Public Shared Function ImageToPictureDisp( _    ByVal image As Image) As stdole.IPictureDisp    Return CType(GetIPictureDispFromPicture(image), _      stdole.IPictureDisp)  End Function  Public Shared Function IconToPictureDisp( _    ByVal icon As Icon) As stdole.IPictureDisp    Return ImageToPictureDisp(icon.ToBitmap())  End Function  Public Shared Function PictureDispToImage( _    ByVal picture As stdole.IPictureDisp) As Image    Return GetPictureFromIPicture(picture)  End FunctionEnd Class

C#

Copy Code

internal class PictureConverter : AxHost{  private PictureConverter() : base(String.Empty) { }  static public stdole.IPictureDisp ImageToPictureDisp(Image image)  {    return (stdole.IPictureDisp)GetIPictureDispFromPicture(image);  }  static public stdole.IPictureDisp IconToPictureDisp(Icon icon)  {    return ImageToPictureDisp(icon.ToBitmap());  }  static public Image PictureDispToImage(stdole.IPictureDisp picture)  {    return GetPictureFromIPicture(picture);  }}

Then, your callback procedure might look something like this, assuming that you had added an icon to your project resources named MyIcon.

Visual Basic

Copy Code

Public Function GetImage( _  ByVal imageName As String) As stdole.IPictureDisp  Return PictureConverter.IconToPictureDisp(My.Resources.MyIcon)End Function

C#

Copy Code

public stdole.IPictureDisp GetImage(string imageName){  return    PictureConverter.IconToPictureDisp(Properties.Resources.MyIcon);}

Note:
Your project must have a reference set to the stdole assembly to run this code. This reference is automatically included in projects created by using Visual Studio 2005 Tools for Office Second Edition.

Conclusion

Customizing the UI in previous versions of Office meant creating COM add-ins or DLL files for each application that shared the add-in. By contrast, the Ribbon feature uses text-based, declarative XML markup that simplifies creating and customizing the Ribbon. With a few lines of XML, you can create just the right interface for the user. Because the XML markup is contained in a single file, modifying the interface as requirements change is much simpler. You can also improve user productivity by putting the commands where users can find them more easily. The Ribbon adds consistency across applications, which reduces the time users spend learning each application.

Additional Resources

To learn more about the products and technologies mentioned or used in this article, see these resources:

• Microsoft Office Developer Center: Visual Studio Tools for Office Developer Portal

• Documentation: Visual Studio Tools for Office

• Forum: Visual Studio Tools for Office

• Information About Designing Office XP Add-ins and Office 2003 Add-ins by Using the .NET Framework

• How to Build an Office COM Add-in by Using Visual Basic .NET

• How to Create Office COM Add-ins by Using VBA and Office Developer