RibbonMenu Interface

  • Article

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
Public property ControlSize Gets or sets the size of the menu.
Public property Description Gets or sets the text that appears on the current menu.
Public property Dynamic Gets or sets a value that indicates whether the menu can be modified at run time.
Public property Enabled Gets or sets a value that indicates whether this RibbonControl is enabled. (Inherited from RibbonControl.)
Public property Id Gets a string that Microsoft Office uses to identify this RibbonControl object. (Inherited from RibbonControl.)
Public property Image Gets or sets the image that is displayed on the menu.
Public property ImageName Gets or sets the name that you can use in the LoadImage event handler to identify an image for the menu.
Public property Items Gets the collection of controls that are on the menu.
Public property ItemSize Gets or sets the size of the controls on the menu.
Public property KeyTip Gets or sets the keyboard access key of the menu.
Public property Label Gets or sets the text that is displayed by the menu.
Public property Name Gets or sets the name of this RibbonComponent. (Inherited from RibbonComponent.)
Public property OfficeImageId Gets or sets the image to display on the menu, if you want to use a built-in Microsoft Office icon.
Public property Parent Gets a RibbonComponent that represents the parent of this RibbonComponent. (Inherited from RibbonComponent.)
Public property Position Gets or sets the position of the menu, if the menu is on the Microsoft Office Menu.
Public property Ribbon Gets the top-level Ribbon object that contains the control hierarchy. (Inherited from RibbonComponent.)
Public property RibbonUI Infrastructure. Gets the IRibbonUI instance that is provided by the Microsoft Office application to the Ribbon extensibility code. (Inherited from RibbonComponent.)
Public property ScreenTip Gets or sets tip text that appears when the user moves the pointer over the menu.
Public property ShowImage Gets or sets a value that indicates whether the image that is associated with the menu is visible.
Public property ShowLabel Gets or sets a value that indicates whether the label for the menu is visible.
Public property Site Gets or sets the ISite associated with the IComponent. (Inherited from IComponent.)
Public property SuperTip Gets or sets multiline tip text that appears when the user moves the pointer over the menu.
Public property Tag Gets or sets application-specific data that is associated with this RibbonComponent. (Inherited from RibbonComponent.)
Public property Title Gets or sets the title that is displayed when the user expands a menu that is added to the Microsoft Office Menu.
Public property Visible Gets or sets a value that indicates whether this RibbonControl is visible. (Inherited from RibbonControl.)

Top

Methods

  Name Description
Public method Dispose Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. (Inherited from IDisposable.)
Public method 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.)
Public method PerformLayout Calls Microsoft.Office.Core.IRibbonUI.InvalidateControl if the RibbonComponent has a parent and layout is not suspended. (Inherited from RibbonComponent.)
Public method ResumeLayout() Reverses the effect of the SuspendLayout method. (Inherited from RibbonComponent.)
Public method ResumeLayout(Boolean) Reverses the effect of the SuspendLayout method. (Inherited from RibbonComponent.)
Public method SuspendLayout Prevents the Microsoft Office application from refreshing the state of controls on the Ribbon. (Inherited from RibbonComponent.)

Top

Events

  Name Description
Public event Disposed Represents the method that handles the Disposed event of a component. (Inherited from IComponent.)
Public event 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. 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:

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

See Also

Reference

Microsoft.Office.Tools.Ribbon Namespace

Other Resources

Ribbon Overview

Ribbon Designer

Ribbon Object Model Overview

How to: Get Started Customizing the Ribbon