|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here.|
The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office.
Microsoft Office version
For more information, see Features Available by Application and Project Type.
The Ribbon Designer is a visual design canvas. Use the Ribbon Designer to add custom tabs, groups, and controls to the Ribbon of a 2007 Microsoft Office system application.
To open the Ribbon Designer, add a Ribbon (Visual Designer) item to your project. You can then use the design tools for the following tasks:
There are some tasks that you cannot accomplish by using the Ribbon Designer. For more information about these tasks and how you can accomplish them, see Ribbon Overview.
For a related video demonstration, see How Do I: Use the Ribbon Designer to Customize the Ribbon in Outlook?.
To use the Ribbon Designer, add a new Ribbon (Visual Designer) item to your project. For more information, see How to: Get Started Customizing the Ribbon.
When you add a new Ribbon (Visual Designer) item, Visual Studio Tools for Office automatically adds the following files to your project:
A Ribbon code file. This file has the name that you specify for the Ribbon (Visual Designer) item in the Add New Item dialog box. Add code to handle Ribbon events to this file.
A Ribbon Designer code file. This file contains code generated by the Ribbon Designer and should not be directly edited.
A Resource file. This file contains the property values of each control on the Ribbon.
If you already have a Ribbon (Visual Designer) item from another project, you can reuse it in your current Visual Studio Tools for Office project by using the Add Existing Item dialog box.
There are three ways to open the Ribbon Designer:
In Solution Explorer, double-click the Ribbon code file.
In Solution Explorer, right-click the Ribbon code file, and then click View Designer.
In Solution Explorer, select the Ribbon code file, and then click Designer on the View menu.
The Ribbon Designer contains a default tab and group. You can remove the default tab and group from the Ribbon Designer. To remove the default group, right-click Group1, and then click Delete. To remove the default tab, right-click an empty area of the design surface, and then click Remove Ribbon Tab.
You can also add new tabs, groups, and controls to the Ribbon Designer. You can find these controls in the Toolbox, in the Office Ribbon Controls group. There are three ways to add controls from the Office Ribbon Controls group to the Ribbon Designer:
Drag a control to an appropriate area on the Ribbon Designer.
Click a control and then click an appropriate area in the Ribbon Designer.
Select an appropriate area in the designer, and then double-click a control in the Toolbox.
Ribbon Design Workflow
Follow these basic steps to design the Ribbon layout:
Controls can be dropped only on groups; you cannot drag a control directly to a tab or to the Ribbon. Groups can be dropped only on tabs; you cannot drag a group directly to a Ribbon.
Arrange controls by dragging them to the correct positions. You can set the properties of a control by using the Properties window.
You cannot drag controls from one tab to another on the Ribbon. If you want to move a control to another tab, you must use the Cut command to remove the control from one tab, and then paste the control on another tab. If you do cut the control and paste it, the event handler stops working. You can reconnect the event handler in the Properties window. For more information, see Properties Window.
Adding Tabs to the Ribbon
There are three ways to add a tab to the Ribbon:
Add a tab from the Toolbox.
Right-click the Ribbon Designer, and then click Add Ribbon Tab.
Open the Tab Collection Editor, and then click Add.
To open the Tab Collection Editor, in the Properties window, select the Tabs property, and then click the ellipsis button .
After you add a tab, you can add groups to contain controls.
Removing Tabs from the Ribbon
There are three ways to remove a tab from the Ribbon:
Right-click the designer, and then click Remove Ribbon Tab.
In the Commands pane of the Properties window, click Remove Ribbon Tab.
Open the Tab Collection Editor, select the tab, and then click Remove.
Changing the Order of Tabs on the Ribbon
To change the order of the tabs, use the Tab Collection Editor. For more information, see How to: Change the Order of Tabs on the Ribbon.
Customizing Built-in Tabs on the Ribbon
A built-in tab is a tab that is already on the Ribbon of a Microsoft Office application. For example, the Data tab is a built-in tab in Excel.
You can add groups and controls to a built-in tab. By default, a custom group appears as the last group on a built-in tab, though you can move it before or after any built-in group on the tab.
You cannot remove built-in groups.
For details about how to customize a built-in tab, see How to: Customize a Built-in Tab.
Adding Groups to a Tab
Groups logically organize controls on the Ribbon. Add groups to tabs. Add all other controls to the group.
Adding Controls to Groups
Add one or more controls to a group. The following table describes each control.
A container that organizes controls in a group. You can add any control to a box except a separator, a group, or a tab. A box can be horizontal or vertical.
A button that starts an action. You can add a button to a group, a button group, a drop-down list, a gallery, a menu, or a split button.
A group that contains one or more buttons, toggle buttons, menus, split buttons, and galleries. You can add a button group to a group or a menu.
A box that is selected or cleared to turn on or off an option.
An edit box with a list box attached. Users can either type or select their choice. The box displays the current selection. Use the Items property to add and remove items at run time before or after the Ribbon is loaded into the Office application.
A list of items that the user can select. The user cannot type a new item in a drop-down list.
Use the Items property to add items to the list. You can add and remove items at run time.
Use the Buttons property to add buttons to the list. However, you cannot add and remove buttons at run time after the Ribbon is loaded into the Office application.
A box in which the user can type text.
A menu that presents an array or grid of visual choices from which users can select. You can control the layout of the selections in the menu. Use the ColumnCount and the RowCount properties to specify the number of rows and columns that will display the items and buttons of the gallery.
Text that you can use to identify controls on the Ribbon.
A drop-down list that can contain any of the following controls:
To add a control to a menu in the Ribbon Designer, click the down arrow in the menu to expose the menu design surface. You can then drag Ribbon controls from the Toolbox onto the menu. To arrange controls, drag them to the desired positions.
To add controls to the RibbonMenu after the Ribbon is loaded into the Office application, you must set the Dynamic property to true before the Ribbon is loaded. For information about how to do this, see Ribbon Object Model Overview.
A thin bar used to separate items in a list. When added to a group, the bar is vertical. When added to a menu, the bar is horizontal.
A button with a menu attached. A split button can contain any of the following controls:
Like the menu, the split button has its own design surface. However, unlike a menu, you can only update the items in a split button before the Ribbon is loaded into the Office application. For information about how to update the items in a split button, see Ribbon Object Model Overview.
A button that appears pressed or not pressed.
The Ribbon Designer enables you to set control properties at design time by using the Properties window. In addition, the Ribbon exposes a strongly typed object model that you can use to get and set the properties of Ribbon controls at run time.
You can double-click any control on the designer to open an event handler for the control's default event. You can create event handlers for all other control events by using the Properties window.
Ribbon events and properties are located in the Microsoft.Office.Tools.Ribbon namespace. The Ribbon (Visual Designer) item automatically adds a reference to this assembly in the project and inserts the appropriate using or Imports statement at the top of the Ribbon code file.
For information about handling Ribbon events and setting the properties of Ribbon controls at run time, see Ribbon Object Model Overview.
You can use the Ribbon Designer to add controls to the menu that opens when you click the Microsoft Office Button. The Microsoft Office Button is in the upper-left corner of Microsoft Office Word, Excel, PowerPoint, and Outlook.
For information about how to customize the menu, see How to: Customize the Microsoft Office Menu.
For more information about the Microsoft Office Button, see the section "The Microsoft Office Button" in the article Developer Overview of the User Interface for the 2007 Microsoft Office System.
You can use keyboard shortcuts to move controls in the Ribbon Designer. Some keyboard shortcuts apply to all controls, and some apply only to controls that have menus.
The keyboard shortcuts that apply to all controls are shown in the following table.
Move a control before the previous control in the list.
Move a control after the next control in the list.
Move the selection from one control to another in the same group. For a drop-down panel, move between the parent control and the controls in the drop-down panel.
Iterate forward through all the controls.
Iterate to the reverse through all the controls.
Delete the selected control or set of controls.
Copy the selected controls.
Cut the selected controls.
Paste controls from the Clipboard.
Select the Toolbox.
Select the parent component.
Select the parent control if the drop-down panel is open and there is a control selected on the drop-down panel.
Close the drop-down panel if the drop-down panel is open and parent control is selected.
Open the drop-down panel.
Select the first control on the drop-down panel if the drop-down panel is open.
Close a drop-down panel.