Skip to main content
BuyLog In
WinForms Controls
Search in…
Docs > Controls and Libraries > Ribbon, Bars and Menu > Ribbon > Galleries > Dropdown Galleries
All docs
V24.1
WinForms Controls
.NET/.NET Core Support
Prerequisites
What's Installed
Build an Application
Controls and Libraries
Forms and User Controls
Messages, Notifications, and Dialogs
Editors and Simple Controls
Ribbon, Bars and Menu
Bars
Ribbon
Get Started
The Ribbon UI
Visual Elements
Items and Item Links
Ribbon Styles
Galleries
In-Ribbon Galleries
Dropdown Galleries
Main Menus
Ribbon Control Designer
Runtime Capabilities
Miscellaneous
Known Issues
Accessibility Support
Popup Menus
Radial Menu
Common Features
Examples
Application UI Manager
Docking Library
Data Grid
Vertical Grid
Property Grid
Pivot Grid
Tree List
Gantt Control
Chart Control
Diagrams
Gauges
Map Control
Scheduler
Spreadsheet
Rich Text Editor
Spell Checker
Form Layout Managers
Navigation Controls
Printing-Exporting
PDF Viewer
Reporting
Office File API
Snap
TreeMap Control
Sunburst Control
Sankey Diagram Control
Heatmap Control
Common Features
Security Considerations
UI Templates
Desktop & Web App UI Framework (Powered by EF Core)
Get More Help
API Reference
Download CHM

Dropdown Galleries

  • 5 minutes to read

Dropdown galleries are displayed within popup windows when clicking dropdown buttons of In-Ribbon Galleries. Typically, dropdown galleries are extended versions of In-Ribbon Galleries.

A gallery popup window displaying a dropdown gallery is represented by the GalleryDropDown control. The dropdown gallery itself is specified by the GalleryDropDown.Gallery property, which is of the InDropDownGallery type (a descendant of the StandaloneGallery and BaseGallery classes).

The figure below illustrates a dropdown gallery.

CD_InRibbonGallery_ClickDropdownButton_Popup

The current topic covers the specifics of gallery popups and their embedded galleries. To learn about customizing gallery items, see Gallery Items.

The GalleryDropDown control is a descendant of the PopupMenu class, and thus it can be invoked as a standalone context menu. Use the GalleryDropDown.ShowPopup method to accomplish this.

Each In-Ribbon Gallery contains a Dropdown button, which when clicked, invokes an automatically generated or custom gallery popup window - a GalleryDropDown control with an embedded gallery. By default, a gallery popup is automatically generated on clicking the In-Ribbon gallery’s dropdown button, as follows:

  1. A new GalleryDropDown control is automatically created.
  2. The contents of the source In-Ribbon gallery are copied to the dropdown gallery (GalleryDropDown.Gallery). Gallery groups and items are copied by references.
  3. The InRibbonGallery.InitDropDownGallery event fires. The e.PopupGallery event parameter allows you to access and customize the current dropdown gallery. The e.PopupGallery.GalleryDropDown event parameter allows you to customize the current GalleryDropDown control.
  4. The GalleryDropDown control is displayed onscreen as a popup window.

Gallery items can be checked and unchecked. This feature is controlled by the BaseGallery.ItemCheckMode property. By default, changing the check states of items in the automatically generated dropdown gallery does not affect the check states of corresponding items in the In-Ribbon Gallery. To enable check state synchronization, set the InDropDownGallery.SynchWithInRibbonGallery property to true. You can access and enable this property using the InitDropDownGallery event’s e.PopupGallery.SynchWithInRibbonGallery parameter. The InDropDownGallery.SynchWithInRibbonGallery property is not supported for custom gallery popups.

In specific instances, you may wish to display a custom gallery popup (instead of the automatically generated gallery popup) on clicking the In-Ribbon Gallery’s Dropdown button. To accomplish this:

  1. Manually create a GalleryDropDown control at design time (by dropping it from the Toolbox, or in the Ribbon Designer Gallery Page), or at runtime.
  2. Bind the GalleryDropDown control to the RibbonGalleryBarItem.GalleryDropDown property.

Creating a custom gallery is useful if you want to implement a popup version of an In-Ribbon gallery beforehand; for instance, at design time.

The following happens when clicking the In-Ribbon gallery’s dropdown button, provided that a custom GalleryDropDown control is specified.

  1. The InRibbonGallery.InitDropDownGallery event fires; its PopupGallery parameter refers to the gallery of the bound GalleryDropDown control, and the PopupGallery.GalleryDropDown parameter refers to the control itself. You can handle the InitDropDownGallery event to dynamically customize the gallery popup (for instance, add additional commands below the embedded gallery; see the last section on this page to learn more).
  2. The GalleryDropDown control appears onscreen.

Like an In-Ribbon Gallery, a gallery embedded in the GalleryDropDown control (GalleryDropDown.Gallery) consists of groups of items. For gallery items which represent images, it’s possible to display captions and descriptions, implement hints and hover images. A click on a gallery item fires the BaseGallery.ItemClick event. You need to handle this event, or alternatively, the GalleryDropDown.GalleryItemClick event, to respond to item clicking. See Gallery Items for more information.

If a dropdown gallery contains two or more groups (BaseGallery.Groups), the group filtering feature is enabled by default. In this mode, the Group Filter panel is displayed at the top of the GalleryDropDown control. When this panel is clicked, a Group Filter menu is opened, which by default contains check boxes that correspond to the existing gallery groups and which control the visibility of the groups. Unchecking a check box hides a corresponding group; checking the check box makes the group visible:

Ribbon_GroupFilter

To specify the text displayed within the Group Filter panel, use the gallery’s StandaloneGallery.FilterCaption inherited property. If you need to add custom menu items to the Group Filter menu, you can handle the BaseGallery.FilterMenuPopup event. This event fires before the menu is displayed onscreen, and it allows you to access and customize the menu.

In specific instances, you may want to disable the group filtering feature. To do this, set the StandaloneGallery.AllowFilter property to false.

The initial size of the GalleryDropDown control is calculated based upon the values of the embedded gallery’s BaseGallery.RowCount and BaseGallery.ColumnCount properties. These properties specify the number of rows and columns of gallery items.

An end-user is not able to resize the GalleryDropDown control by default. To enable this feature, use the InDropDownGallery.SizeMode property.

A gallery popup (GalleryDropDown) can display custom menu items (bar items) below the embedded gallery: buttons, check items, submenus, static text, editors, etc.

CD_InRibbonGallery_ClickDropdownButton_PopupWithCommands

To add these commands to the automatically generated gallery popup, handle the InRibbonGallery.InitDropDownGallery event and add specific bar items to the ItemLinks collection of the e.PopupGallery.GalleryDropDown event parameter.

For a custom GalleryDropDown control, the ItemLinks collection can be populated at design time using the Sub Menus and Popup Menus Page page of the RibbonControl’s Designer. If you need to add bar items to the collection dynamically, handle the InRibbonGallery.InitDropDownGallery event.

See Also