Not logged in▾
Log In Register
Forgot Password Resend Validation E-mail
In This Article

PopupButton

The PopupButton control supports display of popups or context menus and can render in multiple display modes.

Screenshot

The various PopupButton display modes

Display Mode

The PopupButton.DisplayMode property supports these display modes, which alter the appearance of the control:

DisplayMode Description
Merged The control will show the content as a normal button, with a popup indicator on the right side. This display mode is also known as a drop-down button and opens a popup/menu when clicked.
CenterMerged The control will show the content as a normal button, with a popup indicator right next to the content. This display mode is also known as a drop-down button and opens a popup/menu when clicked.
Split The control will show the content in a normal button area and a popup indicator in a separate clickable area. This display mode is also known as a split button. It performs a standard button click when clicking the button's content area, and opens a popup/menu when the popup indicator area is clicked.
ButtonOnly The control will show the content as a normal button, and with no popup indicator. This display mode renders the same as a normal Button, while still retaining popup display functionality when clicked. If no popup content or menu is assigned to the control, clicks on the control will behave like a standard Button.
PopupOnly The control will show the popup indicator, but not the content. This display mode opens a popup/menu when clicked.

Popup Content or Context Menu

The PopupMenu can be set to a ContextMenu that you'd like to display when the button is clicked.

Alternatively the PopupContent, PopupContentTemplate, and/or PopupContentTemplateSelector properties can be used to specify content for a popup to show instead.

Note

Setting the PopupMenu property will trigger its ContextMenu to display, even of any of the popup content properties are set. The PopupMenu property takes priority.

The popup content can be automatically focused when opened by setting the IsAutoFocusOnOpenEnabled property to true, which is the default.

Events

The PopupButton.PopupOpened and PopupClosed events are raised when the associated ContextMenu/Popup is opened and closed, respectively.

In addition, the PopupOpening event will be raised before the associated ContextMenu/Popup is opened. Handlers for this event can customize the popup menu or content before it is displayed, or can choose to cancel the open altogether.

Transparency Mode

The PopupButton also supports a transparency mode, which indicates that the background, borders, and/or shades should not be rendered when the button is inactive. A button is considered inactive when it is not defaulted, does not have the keyboard focus, does not have the mouse over it, and is not pressed.

Screenshot

Two identical PopupButton controls with the transparency mode enabled, with the mouse hovered over the bottom one

DataContext for Popup ContextMenu

Because ContextMenu elements are not part of the same visual tree as the associated PopupButton, they do not inherit the DataContext. The PopupButton has been designed to pass its DataContext on to the ContextMenu specified by the PopupMenu. This allows data binding to be used without having to add any additional workarounds.

The data context passed to the context menu is specified by the PopupMenuDataContext property, which is bound to the DataContext by default. This, in effect, extends the current data context to the context menu, while still allowing it to be customized easily as needed.

Placement Target

The placement of the popup is set to the PopupButton itself.

Interop Content

If you wish to display interop content like WinForms controls in the popup content, you must set the PopupAllowsTransparency property to false. When popups allow transparency, WPF cannot render interop content in them.

Important Members

The PopupButton class has these important members:

Member Description

DisplayMode Property

Gets or sets the PopupButtonDisplayMode. The default value is Merged.

HasDropShadow Property

Gets or sets whether the popup will display a drop-shadow effect. The default value is true.

Note

Setting this property to true has no effect if the SystemParameters.DropShadow property is false.

IsAutoFocusOnOpenEnabled Property

Gets or sets a value indicating whether the popup content will be automatically focused when the popup is opened. The default value is true.

IsPopupOpen Property

Gets or sets whether the popup is currently displayed. The default value is false.

IsTransparencyModeEnabled Property

Gets or sets a value indicating whether transparency mode is enabled. The default value is false.

PopupAllowsTransparency Property

Gets or sets the value assigned to the popup's AllowsTransparency property. The default value is true.

When this property is set to false, interop content will be able to render on the popup.

PopupBackground Property

Gets or sets the Brush for the popup's background.

PopupBorderBrush Property

Gets or sets the Brush for the popup's border.

PopupBorderThickness Property

Gets or sets the Thickness for the popup's border.

PopupContent Property

Gets or sets the content that is displayed on the popup for the button. The default value is null.

The PopupMenu property takes precedence over this property. Therefore, if PopupMenu is set, this property is ignored.

PopupContentTemplate Property

Gets or sets the DataTemplate to use for the PopupContent. The default value is null. This property is only useful if your popup content is a data object and not a UI element.

The PopupMenu property takes precedence over this property. Therefore, if PopupMenu is set, this property is ignored.

PopupContentTemplateSelector Property

Gets or sets the DataTemplateSelector to use for the PopupContent. The default value is null. This property is only useful if your popup content is a data object and not a UI element.

The PopupMenu property takes precedence over this property. Therefore, if PopupMenu is set, this property is ignored.

PopupCornerRadius Property

Gets or sets the CornerRadius for the popup's border.

PopupHorizontalOffset Property

Gets or sets the horizontal distance between the target origin and the popup alignment point. The default value is 0.

PopupIndicator Property

Gets or sets the UIElement used in the indicator portion of the button.

PopupIndicatorTemplate Property

Gets or sets the DataTemplate used to present the indicator portion of the button.

PopupIndicatorToolTip Property

Gets or sets the tool-tip object that is displayed for the popup indicator element. The default value is null, which indicates that the standard ToolTip object will be used for the entire button.

PopupMenu Property

Gets or sets the ContextMenu that is displayed as the popup for the button. The default value is null.

This property takes precedence over the PopupContent-related properties. Therefore, if this property is set, the PopupContent-related properties are ignored.

PopupPadding Property

Gets or sets the Thickness for the popup's padding.

PopupVerticalOffset Property

Gets or sets the vertical distance between the target origin and the popup alignment point. The default value is 0.

StaysOpen Property

Gets or sets a value that indicates whether the popup closes when the control is no longer in focus. The default value is false.

Note

This property has no effect when using PopupMenu.