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)
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 | |
|---|---|---|
.gif "Public property") |
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 | |
|---|---|---|
.gif "Public method") |
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 | |
|---|---|---|
.gif "Public event") |
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);
}
See Also
Reference
Microsoft.Office.Tools.Ribbon Namespace