Drop-Down Gallery
The Drop-Down Gallery consists of a button that when clicked displays a drop-down list containing a collection of mutually exclusive items or Commands.
Details
This control is useful for exposing related items or Commands where there is no obvious default, and the individual items can be represented by an image, text, or both.
Support for both vertical and corner gripper bars, or resizing handles, is provided through the DropDownGallery.MenuLayout element.
The following screen shot illustrates the Ribbon Drop-Down Gallery in Microsoft Paint.
Drop-Down Gallery Properties
The Ribbon framework defines a collection of property keys for the Drop-Down Gallery control.
Typically, a Drop-Down 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 Drop-Down Gallery control.
| Property Key | Notes |
|---|---|
| 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. |