Working with Popups

Several built-in ribbon controls have popups. Popups in Actipro Ribbon aren't restricted to having just menu items in them. While most of the time you will only place menu items in them, you have the option of displaying any sort of content within a popup.

A popup with two Menu controls in a StackPanel, one with large items and one with small items

All the popup-related properties illustrated below are implementations of attached properties from PopupControlService.

Built-In Controls with Popups

These controls and any controls derived from them have popups:

• PopupButton
• RibbonGallery
• SplitButton

Defining Popup Content

The built-in controls have several properties that are used for defining content.

Hiding the Popup Border

By default, the popup will display a border around its contents. However, sometimes it is necessary to hide the default border. This sort of option is used for the ApplicationMenu since it has a custom draw border.

Set the PopupHasBorder property to false to hide the border.

Popup Content Layout Options

The most common content for a popup is a Menu control, which renders its items as menu items:

<ribbon:PopupButton ImageSourceLarge="/Resources/Images/Paste32.png" ImageSourceSmall="/Resources/Images/Paste16.png" Label="Paste" KeyTipAccessText="V">
	<ribbon:Menu>
		<ribbon:Button ImageSourceSmall="/Resources/Images/Paste16.png" Label="Paste" KeyTipAccessText="P" />
		<ribbon:Button ImageSourceSmall="/Resources/Images/PasteSpecial16.png" Label="Paste Special" KeyTipAccessText="S" />
		<ribbon:Button ImageSourceSmall="/Resources/Images/PasteHyperlink16.png" Label="Paste Hyperlink" KeyTipAccessText="H" />
	</ribbon:Menu>
</ribbon:PopupButton>

However, there are probably times when you wish to create more complex layouts of controls on a popup. In these scenarios, use a Panel as the PopupContent.

For instance, use a native WPF StackPanel to stack a popup header banner image or a PopupGallery on top of a Menu of items. This sort of layout is very often used in popups that contain a PopupGallery because you can place menu items above and below the PopupGallery as needed.

Or use a native WPF StackPanel with horizontal orientation to create a popup with two Menu controls, one on the left of the other with a Separator in between (two columns of menu items).

By using techniques like this (also illustrated throughout the sample project), you can create complex layouts of popup content.

Popup Location

The built-in controls have several properties that can be used to determine where the popup will be displayed in relation to the parent anchor control. These properties correspond in functionality with the similar properties (without Popup in the name) found on the native WPF Popup class.

Making Popups Resizable

With a Contained PopupGallery

The popup has a special gripper that can be used by assigning a value to the PopupResizeMode property. However, the gripper is only intended to work if there is a PopupGallery control contained somewhere in the popup content since there is special resizing logic needed to handle that scenario.

Without a Contained PopupGallery

There may be other scenarios where your popup content doesn't include a PopupGallery control but you still want the popup to be resizable. In this case, leave the PopupResizeMode property its default value of None and wrap your popup content with a ResizableContentControl (located in the Shared Library). This will add a gripper to the content allowing for resizing of the popup.

This is very useful if you want to have a control like a native WPF TextBox be resizable in a SplitButton's popup.

Here is some XAML code showing a sample implementation:

<ribbon:SplitButton ImageSourceLarge="/Resources/Images/Paste32.png" Label="Popup with Resizable Content">
	<shared:ResizableContentControl MinWidth="250" MinHeight="50" MaxWidth="600" MaxHeight="400">
		<TextBox Text="This popup can be resized." AcceptsReturn="True" 
			BorderThickness="0" HorizontalScrollBarVisibility="Visible" VerticalScrollBarVisibility="Visible" />
	</shared:ResizableContentControl>
</ribbon:SplitButton>

Dynamically Generating Popup Content

Actipro Ribbon makes it easy to dynamically create/change a popup's content before the popup is displayed. This feature is most commonly used to customize menu items for a popup that contains a menu.

All the ribbon controls that display popups raise a PopupOpening event right before a popup is displayed. You can attach to this event and in that handler, alter the popup content however you require.

Here is some code showing how to dynamically create a Menu for a popup before it is displayed.

private void OnPopupButtonPopupOpening(object sender, RoutedEventArgs e) {
	RibbonControls.PopupButton popupOwner = (RibbonControls.PopupButton)sender;
						
	// Create a menu with some items
	RibbonControls.Menu menu = new RibbonControls.Menu();
	for (int index = 0; index < 3; index++) {
		RibbonControls.Button button = new RibbonControls.Button();
		button.Label = String.Format("Dynamically created menu item #{0}, created at {1}", index + 1, DateTime.Now);
		menu.Items.Add(button);	
	}
	popupOwner.PopupContent = menu;
}

See the Dynamic Popup Content QuickStart for a live sample of dynamically generating popup content.