Edit

Menu Group

  • Article

The Menu Group organizes related Commands and controls within a menu or toolbar.

Introduction

The Menu Group control, exposed through the MenuGroup markup element, is a logical container for groups of items or Commands in menu-based controls, including the Context Popup Mini-Toolbar.

A label can be specified for a Menu Group through the LabelTitle attribute or Command.LabelTitle property of an associated Command declaration. The value assigned to LabelTitle is rendered as a category header.

The following example demonstrates the Command markup for a Split Button control that includes two Menu Group Command declarations.

<!-- SplitButton -->
<Command Name="cmdSplitButtonGroup"
         Symbol="cmdSplitButtonGroup"
         Comment="SplitButton Group"
         LabelTitle="SplitButton"/>
<Command Name="cmdSplitButton"
         Symbol="cmdSplitButton"
         Comment="SplitButton"
         LabelTitle="SplitButton"/>
<Command Name="cmdSBButtonItem"
         Symbol="cmdSBButtonItem"
         Comment="SBButtonItem"
         LabelTitle="SB ButtonItem"/>
<Command Name="cmdSBButton1"
         Symbol="cmdSBButton1"
         Comment="SBButton1"
         LabelTitle="SB Button">
  <Command.LargeImages>
    <Image Source="res/copyL_32.bmp"/>
  </Command.LargeImages>
  <Command.SmallImages>
    <Image Source="res/copyS_16.bmp"/>
  </Command.SmallImages>
  <Command.LargeHighContrastImages>
    <Image Source="res/copyLHC_32.bmp"/>
  </Command.LargeHighContrastImages>
  <Command.SmallHighContrastImages>
    <Image Source="res/copySHC_16.bmp"/>
  </Command.SmallHighContrastImages>
</Command>
<Command Name="cmdSBMajorItems"
         Comment="Major Items Category"
         LabelTitle="Major Items"/>
<Command Name="cmdSBStandardItems"
         Comment="Standard Items Category"
         LabelTitle="Standard Items"/>

The following example demonstrates the markup required for a SplitButton element with three MenuGroup element declarations, two of which are associated with the Menu Group Commands from the previous example. The Class attribute of the MenuGroup element is used to specify the size of the menu items.

<Group CommandName="cmdSplitButtonGroup">
  <SplitButton CommandName="cmdSplitButton">
    <SplitButton.ButtonItem>
      <Button CommandName="cmdSBButtonItem"/>
    </SplitButton.ButtonItem>
    <SplitButton.MenuGroups>
      <MenuGroup CommandName="cmdSBMajorItems" 
                 Class="MajorItems">
        <Button CommandName="cmdSBButton1"/>
        <Button CommandName="cmdSBButton1"/>
      </MenuGroup>
      <MenuGroup CommandName="cmdSBStandardItems"
                 Class="StandardItems">
        <Button CommandName="cmdSBButton1"/>
        <Button CommandName="cmdSBButton1"/>
      </MenuGroup>
      <MenuGroup Class="StandardItems">
        <Button CommandName="cmdSBButton1"/>
        <Button CommandName="cmdSBButton1"/>
      </MenuGroup>
    </SplitButton.MenuGroups>
  </SplitButton>
</Group>

The following screen shot illustrates the menu (with three Menu Group controls) that is generated from the markup in the previous examples.

screen shot of a menu with three menu group controls.

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

Typically, a Menu Group 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 defined, by the IUICommandHandler::UpdateProperty callback method.

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

Note

In some cases, a property can be retrieved through the IUIFramework::GetUICommandProperty method and set with the IUIFramework::SetUICommandProperty method.

 

The following table lists the property keys that are associated with the Menu Group control.

Property Key Notes
UI_PKEY_Enabled Supports IUIFramework::GetUICommandProperty and IUIFramework::SetUICommandProperty.
UI_PKEY_Keytip Can only be updated through invalidation.
UI_PKEY_Label Can only be updated through invalidation.
UI_PKEY_TooltipDescription Can only be updated through invalidation.
UI_PKEY_TooltipTitle Can only be updated through invalidation.

 

Windows Ribbon Framework Control Library

MenuGroup markup element