PopupGallery

The PopupGallery class provides an implementation of galleries that appear within a popup. These galleries are controls that allow for the presentation of items visually within the popup for controls such as a RibbonGallery, PopupButton, or SplitButton. The items act like buttons and are displayed in a scrollable list that can be optionally categorized and filtered.

The items in the gallery could be any sort of object to which a visual representation can be applied. For instance, you may wish to provide visual representations of list styles that can be applied to a selection.

The gallery automatically determines the item size and how wide each column is. You don't need to bother with specifying it yourself.

Variants

This control supports a single variant although the overall appearance of the gallery may be altered by specifying a different initial column count, the optional use of categorization, and the optional use of filtering.

Context	Variant Size	Sample UI
(any)	(any)

Capabilities

The following table gives an overview of the capabilities of the control.

Initial Column Display

The PopupGallery.InitialColumnCount property is used to specify the initial number of columns that should be displayed when the popup that contains the PopupGallery is displayed.

The gallery measures the size of the items for you and determines how wide to ensure the popup is so that the number of columns of items you specify can be displayed.

Resizing the Containing Popup

When a PopupGallery is on a popup, it can optionally work with the popup to support resizing. Once the popup is resized and closed, the next time the popup is displayed, the popup is auto-sized back to its default setting based on the initial column count you specify. This is a requirement of the Ribbon UI Design Guidelines.

To enable popup resizing for a control that has a popup with a PopupGallery on it, set the anchor control's PopupResizeMode to a non-None value. Note that the enumeration used by the resize mode property accepts a ControlResizeMode however only its None, Vertical, and Both options are supported.

Hiding the Selected Value

By default, the SelectedItem will be drawn with a highlight to indicate its selected state to the end user. However, they may be cases where you wish to prevent the end user from seeing any sort of highlighted item in the gallery. To do this, set the IsSelectionHighlightVisible property to false.

Processing Item Clicks and Managing the Selected Value

When an item is clicked, the ItemClick is raised. This event passes arguments that specify which item was clicked. The clicked item becomes the SelectedItem and is passed through as the value to the command for the gallery.

Galleries are designed to support the WPF command model for maintaining the selected value of the control. By default, an ObjectValueCommandParameter is assigned as the CommandParameter of the control.

See the Interaction with Value Controls topic for detailed information on using this command parameter to manage the control's value (selected item) and support live preview.

If you aren't using commands, you can choose to handle to SelectedItemChanged event to be notified when the SelectedItem property is changed.

Supporting Live Preview

When the mouse moves over an item, the item becomes the ActiveItem. Many applications use the currently "active" item to supply a live preview to the end user of what would happen if the item was clicked. Live preview for galleries can be implemented in one of two ways.

If you are using commands, the Interaction with Value Controls topic explains how to support live preview using command can-execute handlers.

Alternatively, if you would rather use events, the ActiveItemChanged event is raised whenever the ActiveItem property is changed.

Categorizing Items

The PopupGallery.CategoryProperty attached property can be assigned to each item. If you choose to show categories in your PopupGallery, the property values you specify will be used to group the items into categories. The list style screenshot above shows categories being used.

This sample XAML code shows how to apply the Category attached property to an item:

<mediaImaging:BitmapImage ribbon:PopupGallery.Category="Recently Used Bullets" UriSource="/Resources/Images/GalleryBulletsType1.png" />
<mediaImaging:BitmapImage ribbon:PopupGallery.Category="Bullet Library" UriSource="/Resources/Images/GalleryBulletsNone.png" />

By default, the categorization feature is disabled in PopupGallery. You can enable it by binding your items to the CategorizedItemsSource property instead of the normal ItemsSource property. This tells PopupGallery to switch to categorized item mode.

Categorized Item Filtering

If you have categorization enabled in your PopupGallery as described above, you can optionally add filtering capabilities. The filter is a button at the top of the PopupGallery that when clicked, shows a menu of available filters.

There is always an All option and then rest of the options are the various category names. The All filter is used by default and does not perform any filtering. When a specific category is chosen as a filter, only the items in that category are displayed.

Use the CanFilter property to determine whether the filtering UI is available to the end user. The current category that is being filtered is available via the FilterCategory property.

Zooming-In on Mouse Over

Galleries support zooming-in on mouse over functionality. This means that as the mouse moves over an item, a popup will appear over the item and it can display an alternate template, provided by the ZoomedInItemTemplate property.

The zoomed-in template should display more detail than the standard item template (from ItemTemplate). Its use is completely optional. Clicks through the zoomed-in popup are transparent an will affect the item under it.

To enable zooming-in, set the ZoomedInItemTemplate or ZoomedInItemTemplateSelector property to a non-null value.

Gallery Item Templates

Items in a Gallery Must Have the Same Width/Height

The item templates used for galleries can be any width/height however the one rule to which you must adhere is that all items within the same gallery must be the same width and height. The layout routines rely on this assumption. Not only that, it makes for a better presentation to the end user.

The best way to ensure this is to explicitly set a width/height on the root element of your item template and the gallery will take care of measuring the additional gallery item border size for you.

Render Items with Templates or Programmatically

The normal way to render an item is to use the ItemTemplate and WPF elements to provide the user interface. However, sometimes you need more control over what is rendered, and must render the item via code.

In those cases, we've added a CustomDrawElement element that can be placed in your item template. Simply attach to its CustomDraw event and in the event handler, draw the item however you need.

Item Screen Tips

Screen tips can be attached to gallery items in their item templates via the various ScreenTipService attached properties.

Alternatively you may use the ItemContainerStyle like this to apply them to the container GalleryItem.

<ribbon:PopupGallery.ItemContainerStyle>
	<Style TargetType="{x:Type ribbon:GalleryItem}">
		<Setter Property="ribbon:ScreenTipService.ScreenTipHeader" Value="{Binding Path=MyScreenTipProperty}" />
	</Style>
</ribbon:PopupGallery.ItemContainerStyle>

Important Members

Since galleries indirectly inherit ItemsControl, you should use the Items or ItemsSource properties to bind the gallery to data. Then use the ItemTemplate or ItemTemplateSelector property to provide templates for the items.

This table lists the important members of the PopupGallery control, other than the ones inherited from ItemsControl.

Sample XAML

This sample XAML code shows how to create a list styles gallery similar to the one in Word. Note that in a real application the items would drawn programmatically using CustomDrawElement instead of rendering them using pre-defined images.

<ribbon:PopupGallery InitialColumnCount="6" CanFilter="True">
	<ribbon:PopupGallery.CategorizedItemsSource>
		<x:Array Type="{x:Type mediaImaging:BitmapImage}">
			<mediaImaging:BitmapImage ribbon:PopupGallery.Category="Recently Used Bullets" UriSource="/Resources/Images/GalleryBulletsType1.png" />
			<mediaImaging:BitmapImage ribbon:PopupGallery.Category="Bullet Library" UriSource="/Resources/Images/GalleryBulletsNone.png" />
			<mediaImaging:BitmapImage ribbon:PopupGallery.Category="Bullet Library" UriSource="/Resources/Images/GalleryBulletsType1.png" />
			<mediaImaging:BitmapImage ribbon:PopupGallery.Category="Bullet Library" UriSource="/Resources/Images/GalleryBulletsType2.png" />
			<mediaImaging:BitmapImage ribbon:PopupGallery.Category="Bullet Library" UriSource="/Resources/Images/GalleryBulletsType3.png" />
			<mediaImaging:BitmapImage ribbon:PopupGallery.Category="Bullet Library" UriSource="/Resources/Images/GalleryBulletsType4.png" />
			<mediaImaging:BitmapImage ribbon:PopupGallery.Category="Bullet Library" UriSource="/Resources/Images/GalleryBulletsType5.png" />
			<mediaImaging:BitmapImage ribbon:PopupGallery.Category="Bullet Library" UriSource="/Resources/Images/GalleryBulletsType6.png" />
			<mediaImaging:BitmapImage ribbon:PopupGallery.Category="Bullet Library" UriSource="/Resources/Images/GalleryBulletsType7.png" />
			<mediaImaging:BitmapImage ribbon:PopupGallery.Category="Document Bullets" UriSource="/Resources/Images/GalleryBulletsType1.png" />
		</x:Array>
	</ribbon:PopupGallery.CategorizedItemsSource>
	<ribbon:PopupGallery.ItemTemplate>
		<DataTemplate>
			<Border Margin="2" BorderBrush="#808080" BorderThickness="1" Background="#FFFFFF" Width="40" Height="40" SnapsToDevicePixels="True">
				<Image Source="{Binding BindsDirectlyToSource=True}" Stretch="None" HorizontalAlignment="Center" VerticalAlignment="Center" SnapsToDevicePixels="True" />
			</Border>
		</DataTemplate>
	</ribbon:PopupGallery.ItemTemplate>
	<ribbon:PopupGallery.ZoomedInItemTemplate>
		<DataTemplate>
			<Border Margin="2" BorderBrush="#808080" BorderThickness="1" Background="#FFFFFF" Width="70" Height="70" SnapsToDevicePixels="True">
				<Image Source="{Binding BindsDirectlyToSource=True}" Stretch="None" HorizontalAlignment="Center" VerticalAlignment="Center" SnapsToDevicePixels="True">
					<Image.LayoutTransform>
						<ScaleTransform ScaleX="2" ScaleY="2" />
					</Image.LayoutTransform>
				</Image>
			</Border>
		</DataTemplate>
	</ribbon:PopupGallery.ZoomedInItemTemplate>
</ribbon:PopupGallery>