Popup

The Popup control provides a way to display content in a separate window that floats over the current application window relative to a designated element or screen coordinate.

The following illustration shows a Popup control that is positioned with respect to a Button that is its parent:

The following table lists common tasks for working with the Popup control:

What is a Popup?

A Popup control displays content in a separate window relative to an element or point on the screen. When the Popup is visible, the IsOpen property is set to true.

Creating a Popup

The following example defines a Popup control as the child element of a ToggleButton control. Because a ToggleButton can have only one child element, this example places the text for the ToggleButton and the Popup controls in a StackPanel. The popup's IsOpen property uses data binding to synchronize with the button's IsChecked property. When you click the button, the popup automatically opens or closes. The content displays in a separate window that floats over the application window near the button.

<ToggleButton x:Name="TogglePopupButton" Height="30" Width="150" HorizontalAlignment="Left">
    <StackPanel>
        <TextBlock VerticalAlignment="Center" HorizontalAlignment="Center">
            <Run Text="Is button toggled? " />
            <Run Text="{Binding IsChecked, ElementName=TogglePopupButton}" />
        </TextBlock>

        <Popup Name="myPopup" IsOpen="{Binding IsChecked, ElementName=TogglePopupButton}">
            <Border BorderThickness="1">
                <TextBlock Name="myPopupText" Background="LightBlue" Foreground="Blue" Padding="30">
                Popup Text
                </TextBlock>
            </Border>
        </Popup>
    </StackPanel>
</ToggleButton>

Controls that implement a Popup

You can build Popup controls into other controls. The following controls implement the Popup control for specific uses:

• ToolTip. If you want to create a tooltip for an element, use the ToolTip and ToolTipService classes. For more information, see ToolTip.

• ContextMenu. If you want to create a context menu for an element, use the ContextMenu control. For more information, see ContextMenu.

• ComboBox. If you want to create a selection control that has a drop-down list box that can be shown or hidden, use the ComboBox control.

• Expander. If you want to create a control that displays a header with a collapsible area that displays content, use the Expander control. For more information, see Expander.

Styles and templates

The Popup control provides XAML styling properties that allow you to customize its appearance. The control doesn't define a default template with template parts or visual states, but you can customize its behavior. For more information, see the Popup behavior and appearance section.

Content property

This control uses the Child property as its content property. The Child property represents the single child element that is displayed in the popup window.

Parts

This control doesn't define any template parts.

Visual states

This control doesn't define any visual states.

Popup behavior and appearance

The Popup control provides functionality that enables you to customize its behavior and appearance. For example, you can set open and close behavior, animation, opacity and bitmap effects, and Popup size and position.

Open and close behavior

A Popup control displays its content when the IsOpen property is set to true. By default, Popup stays open until the IsOpen property is set to false. However, you can change the default behavior by setting the StaysOpen property to false. When you set this property to false, the Popup content window has mouse capture. The Popup loses mouse capture and the window closes when a mouse event occurs outside the Popup window.

The Opened and Closed events are raised when the Popup content window is open or closed.

Animation

The Popup control has built-in support for the animations that are typically associated with behaviors like fade-in and slide-in. You can turn on these animations by setting the PopupAnimation property to a PopupAnimation enumeration value. For Popup animations to work correctly, you must set the AllowsTransparency property to true.

You can also apply animations like Storyboard to the Popup control.

Opacity and bitmap effects

The Opacity property for a Popup control has no effect on its content. By default, the Popup content window is opaque. To create a transparent Popup, set the AllowsTransparency property to true.

The content of a Popup doesn't inherit bitmap effects, such as DropShadowBitmapEffect, that you directly set on the Popup control or on any other element in the parent window. For bitmap effects to appear on the content of a Popup, you must set the bitmap effect directly on its content. For example, if the child of a Popup is a StackPanel, set the bitmap effect on the StackPanel.

Popup size

By default, a Popup is automatically sized to its content. When auto-sizing occurs, some bitmap effects might be hidden because the default size of the screen area that is defined for the Popup content doesn't provide enough space for the bitmap effects to display.

Popup content can also be obscured when you set a RenderTransform on the content. In this scenario, some content might be hidden if the content of the transformed Popup extends beyond the area of the original Popup. If a bitmap effect or transform requires more space, you can define a margin around the Popup content to provide more area for the control.

Defining the Popup position

You can position a popup by setting the PlacementTarget, PlacementRectangle, Placement, HorizontalOffset, and VerticalOffsetProperty properties. For more information, see Popup Placement Behavior. When Popup is displayed on the screen, it doesn't reposition itself if its parent is repositioned.

Customizing Popup placement

You can customize the placement of a Popup control by specifying a set of coordinates that are relative to the PlacementTarget where you want the Popup to appear.

To customize placement, set the Placement property to Custom. Then define a CustomPopupPlacementCallback delegate that returns a set of possible placement points and primary axes (in order of preference) for the Popup. The point that shows the largest part of the Popup is automatically selected. For an example, see Specify a Custom Popup Position.

Popup and the visual tree

A Popup control doesn't have its own visual tree; it instead returns a size of 0 (zero) when the MeasureOverride method for Popup is called. However, when you set the IsOpen property of Popup to true, a new window with its own visual tree is created. The new window contains the Child content of Popup. The width and height of the new window can't be larger than 75 percent of the width or height of the screen.

The Popup control maintains a reference to its Child content as a logical child. When the new window is created, the content of Popup becomes a visual child of the window and remains the logical child of Popup. Conversely, Popup remains the logical parent of its Child content.

See also

• ContextMenu
• CustomPopupPlacement
• CustomPopupPlacementCallback
• PlacementMode
• Popup
• PopupPrimaryAxis
• ToolTip
• ToolTipService
• Popup Placement Behavior
• ToolTip