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 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
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 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
Opacity and Bitmap Effects
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
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 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.