Edit

Popup Overview

  • Article

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. This topic introduces the Popup control and provides information about its use.

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.

Note

A Popup does not automatically open when the mouse pointer moves over its parent object. If you want a Popup to automatically open, use the ToolTip or ToolTipService class. For more information, see ToolTip Overview.

Creating a Popup

The following example shows how to define a Popup control that is 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 content of the Popup is displayed in a separate window that floats over the application window near the related ToggleButton control.

<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:

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 does not 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.

By default, a Popup is automatically sized to its content. When auto-sizing occurs, some bitmap effects may be hidden because the default size of the screen area that is defined for the Popup content does not 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 in order 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 does not 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.

A Popup control does not 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 cannot 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