RibbonMenu Interface

Article
06/14/2013

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

Namespace: Microsoft.Office.Tools.Ribbon
Assembly: Microsoft.Office.Tools.Common (in Microsoft.Office.Tools.Common.dll)

Syntax

'Declaration
<GuidAttribute("59dc7f42-aca2-484a-9622-1ee34a6cfd7d")> _
Public Interface RibbonMenu _
    Inherits RibbonControl, RibbonComponent, IComponent, IDisposable

[GuidAttribute("59dc7f42-aca2-484a-9622-1ee34a6cfd7d")]
public interface RibbonMenu : RibbonControl, 
    RibbonComponent, IComponent, IDisposable

The RibbonMenu type exposes the following members.

Properties

	Name	Description
	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	Infrastructure. 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.
	Site	Gets or sets the ISite associated with the IComponent. (Inherited from IComponent.)
	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.)

Top

Methods

	Name	Description
	Dispose	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. (Inherited from IDisposable.)
	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.)

Top

Events

	Name	Description
	Disposed	Represents the method that handles the Disposed event of a component. (Inherited from IComponent.)
	ItemsLoading	Occurs when controls or nested menus are loaded into the current menu at run time.

Top

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 and the .NET Framework 4.5. 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: https://go.microsoft.com/fwlink/?LinkId=160658.

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:

Add a Ribbon (Visual Designer) item to an Office project.
Add a group to the custom tab.
Add a menu to the group.
Set the (Name) property of the menu to CustomerMenu.
Set the Label property of the menu to Customers.
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 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

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);
}

RibbonMenu Interface

Syntax

Properties

Methods

Events

Remarks

Common Tasks

Usage

Examples

See Also

Reference

Other Resources

Additional resources