Edit

Application Menu

  • Article

The Application Menu is the main menu for an application that implements the Windows Ribbon framework.

Introduction

The Application Menu is composed of a drop-down button control that displays a menu containing Commands that expose functionality related to a complete project, such as an entire document, picture, or movie. Examples include the New, Open, Save, and Exit Commands.

The following screen shot illustrates the Application Menu.

screen shot of the application menu and recent items list of the paint for windows 7 ribbon.

Components of the Application Menu

The Application Menu is a mandatory element in any Ribbon application. The entry point into the Application Menu is a distinctive button that appears as the first item in the Tab row, as shown in the following screen shot.

Note

Windows 8 and newer: Application Menu button image changed to label: File. We recommend that you do not use File as the label for any of your own tabs.

 

screen shot of the application menu button of wordpad for windows 7.

When clicked, this button displays the rich menu that is shown in the following screen shot (the Application Menu from WordPad for Windows 7).

screen shot of the application menu menu of wordpad for windows 7.

Note

There is no impact on the tab set when the Application Menu button is clicked; instead, the focus enters the menu.

 

The Application Menu contains two panes: a list of Commands represented by one or more MenuGroup elements, and a Recent Items list represented by an ApplicationMenu.RecentItems element.

Application Menu MenuGroup

The ApplicationMenu element must contain at least one MenuGroup child element that exposes a list of application-level commands. If multiple MenuGroup elements are declared, a divider line is drawn between the groups, as shown in the following screen shot.

screen shot of an application menu menugroup.

The following is a list of constraints for a MenuGroup element of an Application Menu:

When a Button is used in a MenuGroup, the value of Command.LabelTitle is displayed in the menu and the values of Command.TooltipTitle and Command.TooltipDescription are displayed as the tooltip, as shown in the following screen shot.

screen shot of a button control in an application menu.

When a Drop-Down Button, Split Button, Drop-Down Gallery, or Split Button Gallery is used in the Application Menu, the menu portion is displayed as a flyout that covers and conceals the Recent items pane.

For Split Button and Drop-Down Button controls, the value of Command.LabelDescription is shown inline in the flyout menu to visually assist users with discovering the Command functionality. The displayed value of Command.LabelDescription is programmatically broken over a two-line span, and an attempt is made to fit the value exactly over the Recent items pane beneath. If the Command.LabelDescription value does not fit, the flyout will expand to accommodate the longest Command.Comment value in the MenuGroup.

The following screen shot illustrates these behaviors in a Split Button flyout.

screen shot of a list control flyout in an application menu.

With a Drop-Down Gallery and a Split Button Gallery, only a label and an image are shown.

Sizing the Application Menu

Sizing of the Application Menu is handled by the Ribbon framework. If very long strings are supplied for the value of Command.LabelTitle or Command.LabelDescription, or a long list of Commands is used, the menu will adjust its size to accommodate the contents. Some forms of adjustment include expanding the size of flyouts or menu panes, and adding pan viewers when scrolling is required.

Application Menu Properties

The Ribbon framework defines a collection of property keys for the Application Menu control.

Typically, an Application Menu property is updated in the ribbon UI by invalidating the Command associated with the control through a call to the IUIFramework::InvalidateUICommand method. The invalidation event is handled and the property updates are defined by the IUICommandHandler::UpdateProperty callback method.

The IUICommandHandler::UpdateProperty callback method is not executed and the application is not queried for an updated property value until the property is required by the framework. For example, the framework requires the property when a tab is activated and a control is revealed in the ribbon UI, or when a tooltip is displayed.

Property key Notes
UI_PKEY_TooltipDescription Can only be updated through invalidation.
UI_PKEY_TooltipTitle Can only be updated through invalidation.

 

Windows Ribbon Framework Control Library

ApplicationMenu markup element