Gallery Class—ArcGIS Pro

Gallery Class

In This Topic

Represents an abstract base class for a gallery ribbon control.

Syntax

C#
Visual Basic (Declaration)

public abstract class Gallery : PlugIn, System.ComponentModel.INotifyPropertyChanged

Public MustInherit Class Gallery 
   Inherits PlugIn
   Implements System.ComponentModel.INotifyPropertyChanged

Remarks

A Gallery is a control that displays a collection of related items or Commands in the Ribbon. If there are too many items in the gallery, an expand arrow is provided to display the rest of the collection in an expanded pane. Galleries typically provide a richer representation of the choices offered, each often representing a preview of the result if chosen. Galleries can be organized to show multiple rows and columns simultaneously and are excellent choices when you don’t want to be constrained by the smaller one dimensional area offered by a menu.

Galleries can present a condensed grid within the ribbon itself using the in-line gallery representation. The items presented in this way are often either the most common or most recently used items depending on the implementation. The actual contents of a gallery are normally populated at runtime. The Gallery declaration below is populated entirely at runtime. Relatively static aspects such as the caption, the dropdown image, the tooltip, and the number of columns, are specified declaratively.

Gallery items are typically modeled through the GalleryItem class. GalleryItems have the following properties: Icon, LargeIcon, Text, Group, and Tooltip. Custom GalleryItems can be created through inheritance to encapsulate any additional properties and/or behavior as needed.

Gallery items are represented in the UI via an ItemTemplate. Galleries (and ComboBoxes) can specify a custom template in their declaration. A simple default template is used for all galleries and combo boxes that do not specify one. The default item template for galleries assumes a collection of GalleryItems; if you are using your own item template, you can fill the collection with whatever type is appropriate. Note, when specifying a custom template, you must list the file and its key. Also, if you want grouping, make sure the objects expose a public Group property of type string as the binding logic uses this.

To better support a responsive UI experience, the framework provides a waiting spinner and loading message on the gallery’s dropdown when it is trying to asynchronously load a large number of items. The LoadingMessage can be updated at runtime or set statically using the loadingMessage attribute. Note, to get this default behavior, no heavy code should be put in the gallery’s constructor since it will block the UI thread and prevent the spinner from showing up. The loading message only appears in drop down galleries (not in-inline).

All items added to the ItemCollection must be created on the main UI thread as these ultimately become the content of buttons added to the gallery popup control.

Declaring Galleries in DAML:

            <galleries>
              <gallery id="acme_BasemapGallery" 
                     className="BasemapGallery" 
                     caption="Basemap" 
                     itemsInRow="3" 
                     helpContextID="120000190" 
                     itemWidth="140" 
                     dataTemplateFile="pack://application:,,,/Acme;component/Styles/GalleryTemplates.xaml"
                     templateID="BasemapItemTemplate" 
                     showItemCaption="true" 
                     resizable="true" 
                     smallImage="pack://application:,,,/Acme;component/Images/Basemap16.png"
                     largeImage="pack://application:,,,/Acme;component/Images/Basemap32.png">
                <tooltip>Choose a basemap for your map.

The basemap is the reference data that displays under the notes and 
                         other GIS data you have added to the map.
                </tooltip>
              </gallery>
            </galleries>

Galleries can also be nested to produce a gallery of galleries. This is accomplished by adding a gallery element within the gallery’s declaration.

DAML attributes
id	Required identifier.
caption	The gallery heading.
extendedCaption	A more descriptive title.
condition	Automatically disable the button if the condition is not satisfied.
loadOnClick	Delay creating the actual control until it has been clicked. Default is true.
disableIfBusy	Automatically disable the button if the application is busy. Default true.
loadingMessage	Temporary message appearing while Pane is initializing.
helpContextID	The help topic to show.
smallImage	Image (16x16) used when button is small and middle size.
largeImage	Image (32x32) used when button is large size.
overlaySmallImage	Optional image overlay.
overlayLargeImage	Optional image overlay.
dataTemplateFile	The path to the file containing the custom item template.
templateID	The template ID in the dataTemplateFile.
menuStyle	Single column.
resizable	Controls whether the gallery's drop down window is expandable. Default is true.
itemsInRow	The number of items per row.
itemWidth	The width of the gallery items. Default is 32 pixels.
dropDownHeight	The height of drop down gallery.
showGroup	Specifies whether the items should be categorized according to their group. Default is false.
showItemCaption	Used with the default item template to hide or show the item's text below its image. Default is true.
className	Required class identifier. Optionally include namespace if not in default namespace.
assembly	Assembly name if not in the default assembly.
publicKeyToken	The necessary public key token if the assembly is strongly named.
version	The version of the dll if the assembly is strongly named.

Example

class BasemapGallery : Gallery
{
  private bool _initialized;
  
  protected override void OnDropDownOpened()
  {
     LoadItems());
  }
            
  private void LoadItems()
  {
      if (_initialized)
       return;
       
    for (int x = 0; x < 28; x++)
    {
      GalleryItem galleryItem = new GalleryItem("GalleryItem " + x.ToString(), null, "tip: " + x.ToString());
      this.Add(galleryItem);
    }
    
    _initialized = true;
  }
            
  protected override void OnClick(GalleryItem item)
  {
    System.Windows.MessageBox.Show(item.Text);
  }
}

Inheritance Hierarchy

System.Object
   ArcGIS.Desktop.Framework.Contracts.PropertyChangedBase
      ArcGIS.Desktop.Framework.Contracts.PlugIn
         ArcGIS.Desktop.Framework.Contracts.Gallery

Requirements

Target Platforms: Windows 11, Windows 10

ArcGIS Pro version: 3 or higher.

Reference

Gallery Members
ArcGIS.Desktop.Framework.Contracts Namespace

Send feedback