ArcGIS Pro 3.1 API Reference Guide
ArcGIS.Desktop.Framework.Contracts Namespace / Gallery Class
Members Example

In This Topic
    Gallery Class
    In This Topic
    Represents an abstract base class for a gallery ribbon control.
    Syntax
    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.0 or higher.
    See Also