Export (0) Print
Expand All

RibbonMenu Interface

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)

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

The RibbonMenu type exposes the following members.

  NameDescription
Public propertyControlSizeGets or sets the size of the menu.
Public propertyDescriptionGets or sets the text that appears on the current menu.
Public propertyDynamicGets or sets a value that indicates whether the menu can be modified at run time.
Public propertyEnabledGets or sets a value that indicates whether this RibbonControl is enabled. (Inherited from RibbonControl.)
Public propertyIdGets a string that Microsoft Office uses to identify this RibbonControl object. (Inherited from RibbonControl.)
Public propertyImageGets or sets the image that is displayed on the menu.
Public propertyImageNameGets or sets the name that you can use in the LoadImage event handler to identify an image for the menu.
Public propertyItemsGets the collection of controls that are on the menu.
Public propertyItemSizeGets or sets the size of the controls on the menu.
Public propertyKeyTipGets or sets the keyboard access key of the menu.
Public propertyLabelGets or sets the text that is displayed by the menu.
Public propertyNameGets or sets the name of this RibbonComponent. (Inherited from RibbonComponent.)
Public propertyOfficeImageIdGets or sets the image to display on the menu, if you want to use a built-in Microsoft Office icon.
Public propertyParentGets a RibbonComponent that represents the parent of this RibbonComponent. (Inherited from RibbonComponent.)
Public propertyPositionGets or sets the position of the menu, if the menu is on the Microsoft Office Menu.
Public propertyRibbonGets the top-level Ribbon object that contains the control hierarchy. (Inherited from RibbonComponent.)
Public propertyRibbonUIInfrastructure. Gets the IRibbonUI instance that is provided by the Microsoft Office application to the Ribbon extensibility code. (Inherited from RibbonComponent.)
Public propertyScreenTipGets or sets tip text that appears when the user moves the pointer over the menu.
Public propertyShowImageGets or sets a value that indicates whether the image that is associated with the menu is visible.
Public propertyShowLabelGets or sets a value that indicates whether the label for the menu is visible.
Public propertySiteGets or sets the ISite associated with the IComponent. (Inherited from IComponent.)
Public propertySuperTipGets or sets multiline tip text that appears when the user moves the pointer over the menu.
Public propertyTagGets or sets application-specific data that is associated with this RibbonComponent. (Inherited from RibbonComponent.)
Public propertyTitleGets or sets the title that is displayed when the user expands a menu that is added to the Microsoft Office Menu.
Public propertyVisibleGets or sets a value that indicates whether this RibbonControl is visible. (Inherited from RibbonControl.)
Top

  NameDescription
Public methodDisposePerforms application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. (Inherited from IDisposable.)
Public methodPerformDynamicLayoutCalls 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 methodPerformLayoutCalls Microsoft.Office.Core.IRibbonUI.InvalidateControl if the RibbonComponent has a parent and layout is not suspended. (Inherited from RibbonComponent.)
Public methodResumeLayout()Reverses the effect of the SuspendLayout method. (Inherited from RibbonComponent.)
Public methodResumeLayout(Boolean)Reverses the effect of the SuspendLayout method. (Inherited from RibbonComponent.)
Public methodSuspendLayoutPrevents the Microsoft Office application from refreshing the state of controls on the Ribbon. (Inherited from RibbonComponent.)
Top

  NameDescription
Public eventDisposedRepresents the method that handles the Disposed event of a component. (Inherited from IComponent.)
Public eventItemsLoadingOccurs when controls or nested menus are loaded into the current menu at run time.
Top

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.

NoteNote

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: http://go.microsoft.com/fwlink/?LinkId=160658.

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);
}
Show:
© 2014 Microsoft