Popup Overview
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.
This topic contains the following sections.
- What Is a Popup?
- Creating a Popup
- Controls That Implement a Popup
- Popup Behavior and Appearance
- Defining the Popup Position
- Popup and the Visual Tree
- Related Topics
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 Button control. Because a Button can have only one child element, this example places the text for the Button and the Popup controls in a StackPanel. The content of the Popup appears in a TextBlock control, which displays its text in a separate window that floats over the application window near the related Button control.
<Button HorizontalAlignment="Left" Click="DisplayPopup"
Width="150" Margin="20,10,0,0">
<StackPanel>
<TextBlock>Display Your Popup Text</TextBlock>
<Popup Name="myPopup">
<TextBlock Name="myPopupText"
Background="LightBlue"
Foreground="Blue">
Popup Text
</TextBlock>
</Popup>
</StackPanel>
</Button>
<Button Name="ButtonForPopup" HorizontalAlignment="Left"
Click="CreatePopup"
Width="150" Margin="20,10,0,0">
<StackPanel Name="aStackPanel">
<TextBlock>Create Popup</TextBlock>
</StackPanel>
</Button>
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 Overview.
ContextMenu. If you want to create a context menu for an element, use the ContextMenu control. For more information, see ContextMenu Overview.
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 Overview.
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 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.
Popup Size
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 How to: Specify a Custom Popup Position.
Popup and the Visual Tree
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.