Edit

Split Button Gallery

  • Article

The Split Button Gallery is a composite control that contains a primary button which exposes a single default item or Command, and a secondary button which when clicked displays the rest of the item or Command collection in a mutually exclusive drop-down list.

Details

This control is useful for exposing closely related items in cases where an obvious default is available and where the individual items can be represented by an image, text, or both.

The following screen shot illustrates the Ribbon Split Button Gallery in Microsoft Paint.

screen shot of a splitbuttongallery control in the microsoft paint ribbon.

The Ribbon framework defines a collection of property keys for the Split Button Gallery control.

Typically, a Split Button Gallery 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 Split Button Gallery control.

Property Key Notes
UI_PKEY_BooleanValue Supports IUIFramework::GetUICommandProperty and IUIFramework::SetUICommandProperty.
UI_PKEY_Categories Supports IUIFramework::GetUICommandProperty and IUIFramework::SetUICommandProperty.
UI_PKEY_Enabled Supports IUIFramework::GetUICommandProperty and IUIFramework::SetUICommandProperty.
UI_PKEY_ItemsSource 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_LargeHighContrastImage Can only be updated through invalidation.
UI_PKEY_LargeImage Can only be updated through invalidation.
UI_PKEY_SelectedItem(only valid for an item gallery)
 Supports IUIFramework::GetUICommandProperty and IUIFramework::SetUICommandProperty. Note: If the Command associated with the control is invalidated through a call to IUIFramework::InvalidateUICommand, the framework queries this property when UI_INVALIDATIONS_VALUE is passed as the value of flags.
UI_PKEY_SmallHighContrastImage Can only be updated through invalidation.
UI_PKEY_SmallImage Can only be updated through invalidation.
UI_PKEY_TooltipDescription Can only be updated through invalidation.
UI_PKEY_TooltipTitle Can only be updated through invalidation.

SplitButtonGallery markup element

Working with Galleries

Gallery Sample