Application Menu
The Application Menu is the main menu for an application that implements the Windows Ribbon framework.
- Introduction
- Components of the Application Menu
- Sizing the Application Menu
- Application Menu Properties
- Related topics
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.
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.
When clicked, this button displays the rich menu that is shown in the following screen shot (the Application Menu from 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.
The following is a list of constraints for a MenuGroup element of an Application Menu:
All MenuGroup items must be declared with a Class attribute value of
MajorItems.An Application Menu MenuGroup supports only the Button, Drop-Down Button, Split Button, Drop-Down Gallery, and Split Button Gallery controls.
![Important]
Command galleries are the only type of gallery that are supported in the Application Menu. See Working with Galleries, for more information on gallery controls.
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.
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.
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. |
Related topics