Menu Customization

Bars controls like Ribbon and Standalone Toolbars define built-in menus and/or auto-generated context menus to support the default functionality of the control. These menus can be easily customized to add, remove, or update the default menu items.

MenuOpening Event

Each root control defines a MenuOpening event (Ribbon.MenuOpening and StandaloneToolBar.MenuOpening) that is raised with BarMenuEventArgs. Listen for this event to be raised and the associated BarMenuEventArgs.Menu can be customized before it is displayed.

Menu Kind

Inspect the BarMenuEventArgs.Kind property to determine the menu associated with the event. This property value is an enum of type BarMenuKind that clearly designates the purpose of the menu. For example, the options menu of a Ribbon will have a Kind of BarMenuKind.RibbonOptionsButtonMenu.

Owner

Some menus, like a BarMenuKind.ControlContextMenu, will set the BarMenuEventArgs.Owner property to the relevant control associated with the menu. For most menus, this property will be null.

Customizing Default Menus

Several button controls display a default menu, like the Customize menu of the Quick Access ToolBar or the Overflow menu of Standalone Toolbars.

These button controls are typically implementations of BarPopupButtonBase which, itself, derives from Menu. Before the popup of the button is displayed, the MenuOpening event is raised and can be intercepted to customize these menus.

For example, to customize the Customize menu of the Quick Access ToolBar, listen for the Ribbon.MenuOpening event. When raised for the Customize menu...

• BarMenuEventArgs.Kind will be set to the value BarMenuKind.RibbonQuickAccessToolBarCustomizeButtonMenu,
• BarMenuEventArgs.Menu will be set to an instance of RibbonQuickAccessToolBarCustomizeButton (which derives from Menu), and
• BarMenuEventArgs.Owner will be null since the Menu, itself, is the owner.

The RibbonQuickAccessToolBarCustomizeButton.Items collection will be pre-populated with types like BarMenuItem and BarMenuSeparator that define the default items on the menu.

Existing menu items can be modified/removed, and new menu items can be added. The following code shows an event handler for the Ribbon.MenuOpening event that updates the Customize menu to add an additional menu item (via a CreateCustomMenuItem method that you would create):

private void OnRibbonMenuOpening(object sender, BarMenuEventArgs e) {
	// Test for the QAT customize menu
	if (e.Kind == BarMenuKind.RibbonQuickAccessToolBarCustomizeButtonMenu
		&& e.Menu != null) {

		// Add a menu item returned from the custom function
		e.Menu.Items.Add(CreateCustomMenuItem());
	}
}

Customizing a Ribbon Context Menu

The ribbon control auto-generates context menus for most of the controls in it unless a control has a ContextMenu explicitly assigned to it. The auto-generated menu contains items for toggling the visibility of the quick access toolbar, minimizing the ribbon, etc. However, many times it is useful to add custom menu items to a specific control or to certain types of controls.

You can achieve this programmatically by listening for the Ribbon.MenuOpening event. When raised for the context menu of a control...

• BarMenuEventArgs.Kind will be set to the value BarMenuKind.ControlContextMenu,
• BarMenuEventArgs.Menu will be initialized with a BarContextMenu, and
• BarMenuEventArgs.Owner will be set to the control whose context menu is opening.

The BarContextMenu.Items collection will be pre-populated with types like BarMenuItem and BarMenuSeparator that define the default context menu.

Existing menu items can be modified/removed, and new menu items can be added. The following code shows an event handler for the Ribbon.MenuOpening event that updates the context menu to add an additional menu item (via a CreateCustomMenuItem method that you would create):

private void OnRibbonMenuOpening(object sender, BarMenuEventArgs e) {
	// Test for a control context menu
	if (e.Kind == BarMenuKind.ControlContextMenu
		&& e.Owner != null
		&& e.Menu != null) {

		// Add a menu item returned from the custom function
		e.Menu.Items.Add(CreateCustomMenuItem());
	}
}

Blocking the Context Menu on Dynamic Menu Items

As previously mentioned, the ribbon control auto-generates context menus for most of the controls contained within it. This includes all the items displayed in a default menu or context menu. The default menu items are pre-configured to block a context menu, and dynamically generated menu items will typically need the same configuration.

To block the context menu, set the BarControlService.AllowContextMenuProperty attached property to false using the SetAllowContextMenu method.

The following code demonstrates how to configure a menu item to block the context menu:

private BarMenuItem CreateCustomMenuItem() {
	var barMenuItem = new BarMenuItem() { ... };

	// Block the built-in context menu (with commands like "Add to Quick Access Toolbar") from
	// being displayed for this menu item.
	BarControlService.SetAllowContextMenu(barMenuItem, false);

	return barMenuItem;
}