RibbonMenu Interface

Definition

Represents a menu on a Ribbon tab or on the Microsoft Office Menu.

public interface class RibbonMenu : IDisposable, Microsoft::Office::Tools::Ribbon::RibbonControl, System::ComponentModel::IComponent
[System.Runtime.InteropServices.Guid("59dc7f42-aca2-484a-9622-1ee34a6cfd7d")]
public interface RibbonMenu : IDisposable, Microsoft.Office.Tools.Ribbon.RibbonControl, System.ComponentModel.IComponent
[<System.Runtime.InteropServices.Guid("59dc7f42-aca2-484a-9622-1ee34a6cfd7d")>]
type RibbonMenu = interface
    interface RibbonControl
    interface RibbonComponent
    interface IComponent
    interface IDisposable
Public Interface RibbonMenu
Implements IComponent, IDisposable, RibbonControl
Attributes
Implements

Examples

The following example demonstrates how to add and populate a sub-menu to an existing menu at run time.

For a richer example that updates controls at run-time and involves getting data from the AdventureWorks sample database using Language-Integrated Queries (LINQ), see Walkthrough: Updating the Controls on a Ribbon at Run Time.

To run this code example, you must first perform the following steps:

  1. Add a Ribbon (Visual Designer) item to an Office project.

  2. Add a group to the custom tab.

  3. Add a menu to the group.

  4. Set the (Name) property of the menu to CustomerMenu.

  5. Set the Label property of the menu to Customers.

  6. Set the Dynamic property of the menu to true.

    This enables you to add and remove controls on the menu at run time after the Ribbon is loaded into the Office application.

private void PopulateCustomerMenu()
{
    // Add two sub-menus to EmployeeMenu and populate each sub-menu
    // First sub-menu
    RibbonMenu subMenu1 = this.Factory.CreateRibbonMenu();
    subMenu1.Dynamic = true;
    subMenu1.Label = "A - M";
    subMenu1.Items.Add(this.Factory.CreateRibbonToggleButton());
    ((RibbonToggleButton)subMenu1.Items.Last()).Label = "Hall, Don";
    subMenu1.Items.Add(this.Factory.CreateRibbonToggleButton());
    ((RibbonToggleButton)subMenu1.Items.Last()).Label = "Valdez, Rachel";
    CustomerMenu.Items.Add(subMenu1);

    // Second sub-menu
    RibbonMenu subMenu2 = this.Factory.CreateRibbonMenu();
    subMenu2.Dynamic = true;
    subMenu2.Label = "N - Z";
    subMenu2.Items.Add(this.Factory.CreateRibbonToggleButton());
    ((RibbonToggleButton)subMenu2.Items.Last()).Label = "Robinson, Alex";
    CustomerMenu.Items.Add(subMenu2);
}
Private Sub PopulateCustomerMenu()
    ' Add two sub-menus to EmployeeMenu and populate each sub-menu
    ' First sub-menu
    Dim subMenu1 As RibbonMenu = Me.Factory.CreateRibbonMenu()
    subMenu1.Dynamic = True
    subMenu1.Label = "A - M"
    subMenu1.Items.Add(Me.Factory.CreateRibbonToggleButton())
    CType(subMenu1.Items.Last(), RibbonToggleButton).Label = "Hall, Don"
    subMenu1.Items.Add(Me.Factory.CreateRibbonToggleButton())
    CType(subMenu1.Items.Last(), RibbonToggleButton).Label = "Valdez, Rachel"
    CustomerMenu.Items.Add(subMenu1)

    ' Second sub-menu
    Dim subMenu2 As RibbonMenu = Me.Factory.CreateRibbonMenu()
    subMenu2.Dynamic = True
    subMenu2.Label = "N - Z"
    subMenu2.Items.Add(Me.Factory.CreateRibbonToggleButton())
    CType(subMenu2.Items.Last(), RibbonToggleButton).Label = "Robinson, Alex"
    CustomerMenu.Items.Add(subMenu2)

End Sub

Remarks

Visual Studio creates a RibbonMenu object when you drag a Menu control from the Office Ribbon Controls tab of the Toolbox onto the Ribbon Designer.

You can create a RibbonMenu at run time by using the CreateRibbonMenu method of the RibbonFactory object.

There are two ways to access the RibbonFactory object:

  • By using the Factory property of the Ribbon class. Use this approach from code in your Ribbon class.

  • By using the Globals.Factory.GetRibbonFactory method. Use this approach from code outside your Ribbon class.

Common Tasks

The following table lists members that are useful for common tasks. All of these tasks can be performed at design time. Some of these tasks can be performed at run time only before the Ribbon is loaded into the Office application or before the control is added to a dynamic menu at run time. For more information, see Ribbon Object Model Overview.

Task Member
Display an image on the menu. Use the Image or ImageName property.

You can also reuse images that appear in built-in Ribbon controls. To do this, set OfficeImageId to the ID of a built-in Microsoft Office image that you want to display as the icon for the menu.
Change the size of the menu. Set the ControlSize property to the value you want. For example, for a large menu, set it to Microsoft.Office.Core.RibbonControlSize.RibbonControlSizeLarge.
Change the size of items in the menu. Set the ItemSize property to the value you want. For example, to display larger items, set it to Microsoft.Office.Core.RibbonControlSize.RibbonControlSizeLarge.
Enable changes to the menu at run time (for example, to enable controls to be added to the menu at run time). Set the Dynamic property to true.
Access the controls in the menu, add controls to the menu, or remove controls from the menu. Use the Items property.
Add a menu to the Microsoft Office Menu, a group, or to another control that can contain menus. Add a RibbonMenu to the Items property of the Microsoft Office Menu, group, or control.

Note

This interface is implemented by the Visual Studio Tools for Office runtime. It is not intended to be implemented in your code. For more information, see Visual Studio Tools for Office Runtime Overview.

Usage

This documentation describes the version of this type that is used in Office projects that target the .NET Framework 4 or later. In projects that target the .NET Framework 3.5, this type might have different members and the code examples provided for this type might not work. For documentation about this type in projects that target the .NET Framework 3.5, see the following reference section in the Visual Studio 2008 documentation: http://go.microsoft.com/fwlink/?LinkId=160658.

Properties

ControlSize

Gets or sets the size of the menu.

Description

Gets or sets the text that appears on the current menu.

Dynamic

Gets or sets a value that indicates whether the menu can be modified at run time.

Enabled

Gets or sets a value that indicates whether this RibbonControl is enabled.

(Inherited from RibbonControl)
Id

Gets a string that Microsoft Office uses to identify this RibbonControl object.

(Inherited from RibbonControl)
Image

Gets or sets the image that is displayed on the menu.

ImageName

Gets or sets the name that you can use in the LoadImage event handler to identify an image for the menu.

Items

Gets the collection of controls that are on the menu.

ItemSize

Gets or sets the size of the controls on the menu.

KeyTip

Gets or sets the keyboard access key of the menu.

Label

Gets or sets the text that is displayed by the menu.

Name

Gets or sets the name of this RibbonComponent.

(Inherited from RibbonComponent)
OfficeImageId

Gets or sets the image to display on the menu, if you want to use a built-in Microsoft Office icon.

Parent

Gets a RibbonComponent that represents the parent of this RibbonComponent.

(Inherited from RibbonComponent)
Position

Gets or sets the position of the menu, if the menu is on the Microsoft Office Menu.

Ribbon

Gets the top-level Ribbon object that contains the control hierarchy.

(Inherited from RibbonComponent)
RibbonUI

Gets the IRibbonUI instance that is provided by the Microsoft Office application to the Ribbon extensibility code.

(Inherited from RibbonComponent)
ScreenTip

Gets or sets tip text that appears when the user moves the pointer over the menu.

ShowImage

Gets or sets a value that indicates whether the image that is associated with the menu is visible.

ShowLabel

Gets or sets a value that indicates whether the label for the menu is visible.

SuperTip

Gets or sets multiline tip text that appears when the user moves the pointer over the menu.

Tag

Gets or sets application-specific data that is associated with this RibbonComponent.

(Inherited from RibbonComponent)
Title

Gets or sets the title that is displayed when the user expands a menu that is added to the Microsoft Office Menu.

Visible

Gets or sets a value that indicates whether this RibbonControl is visible.

(Inherited from RibbonControl)

Methods

PerformDynamicLayout()

Calls the Microsoft.Office.Core.IRibbonUI.InvalidateControl method of the parent control if the RibbonComponent has a dynamic parent, such as a dynamic menu, and layout is not suspended.

(Inherited from RibbonComponent)
PerformLayout()

Calls Microsoft.Office.Core.IRibbonUI.InvalidateControl if the RibbonComponent has a parent and layout is not suspended.

(Inherited from RibbonComponent)
ResumeLayout()

Reverses the effect of the SuspendLayout() method.

(Inherited from RibbonComponent)
ResumeLayout(Boolean)

Reverses the effect of the SuspendLayout() method.

(Inherited from RibbonComponent)
SuspendLayout()

Prevents the Microsoft Office application from refreshing the state of controls on the Ribbon.

(Inherited from RibbonComponent)

Events

ItemsLoading

Occurs when controls or nested menus are loaded into the current menu at run time.

Applies to