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.
The following illustration shows a Popup control that is positioned with respect to a Button that is its parent.
.jpg)
.gif) 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 nearby the related Button control. For the complete sample, see Popup Sample.
<Button HorizontalAlignment="Left" Click="DisplayPopup"
Width="150" Margin="20,10,0,0">
<StackPanel>
<TextBlock>Display Your Popup Text</TextBlock>
<Popup Name="myPopup">
<Border BorderBrush="Beige" BorderThickness="1">
<TextBlock Name="myPopupText" Width="150" Background="LightBlue"
Foreground="Blue" TextWrapping="Wrap" />
</Border>
</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 the 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. For more information, see ComboBox Overview.
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. For an example, see the Animated Popup Sample.
Opacity and Bitmap Effects
The Opacity property for a Popup control has no affect 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. For more information, which includes an example, see Animated Popup Sample.
Defining the Popup Position
The position of the Popup control is determined by the values of the Placement, PlacementTarget, and PlacementRectangle properties. Use the HorizontalOffset and VerticalOffset properties for fine-tuning.
The value of the Placement property defines the origin and orientation of the Popup control when it opens. The property value also specifies how the Popup control repositions itself when its initial placement overlaps screen boundaries. The Placement property uses the PlacementMode enumeration to define its options. For more information about the PlacementMode enumeration values, see How to: Set the Placement Property for a Popup or Tooltip.
The PlacementTarget property defines the parent UIElement, such as a Window or a Button control. When you set this property to null, the Popup control is placed relative to its parent in the visual tree.
The PlacementRectangle property specifies a rectangle that the Popup control uses to position itself when it opens. If you set the PlacementTarget property to a UIElement, the rectangle is defined relative to the element. Otherwise, the rectangle is defined relative to the upper-left corner of the computer screen. If you set the Placement property to Mouse, the value of the PlacementRectangle property has no effect.
You can apply the HorizontalOffset and VerticalOffset properties to fine-tune the position of the Popup control. For more information about how to position a Popup, see How to: Position a Popup.
The following illustration shows how you can use the placement properties to define the position of a Popup control.
.png)
When you create a Popup control, make sure that you define the placement of the Popup before you specify that the Popup is open. The following example sets the IsOpen property to true after the Popup named codePopup is added to the StackPanel control named aStackPanel. When codePopup is added to aStackPanel, aStackPanel becomes the logical parent of codePopup. The codePopup control opens when IsOpen is set to true. For the complete example, see Popup Sample.
private void CreatePopup(object sender, RoutedEventArgs e)
{
Popup codePopup = new Popup();
TextBlock popupText = new TextBlock();
popupText.Text = "Popup Text";
popupText.Background = Brushes.LightBlue;
popupText.Foreground = Brushes.Blue;
codePopup.Child = popupText;
aStackPanel.Children.Add(codePopup);
codePopup.IsOpen = true;
}
Private Sub CreatePopup(ByVal Sender As Object, ByVal e As RoutedEventArgs)
Dim codePopup As Popup = New Popup()
Dim popupText As TextBlock = New TextBlock()
popupText.Text = "Popup Text"
popupText.Background = Brushes.LightBlue
popupText.Foreground = Brushes.Blue
codePopup.Child = popupText
aStackPanel.Children.Add(codePopup)
codePopup.IsOpen = True
End Sub
If you change the previous example so that the IsOpen property is set to true and then you add codePopup to aStackPanel, codePopup opens in the upper-left corner of the computer screen. This behavior occurs because the computer screen is the default logical parent when the IsOpen property is set to true.
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. Also, to provide maximum visibility, the position of the Popup is automatically adjusted by moving it along the PrimaryAxis that is associated with the chosen point.
| Note: |
|---|
When you set the Placement property to Custom, the PlacementRectangle, HorizontalOffset, and VerticalOffset properties have no effect. |
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.
See Also
Tasks
Reference
Popup
PopupPrimaryAxis
PlacementMode
CustomPopupPlacement
CustomPopupPlacementCallback
ToolTip
ToolTipService
Other Resources
Popup How-to Topics
ToolTip How-to Topics
Popup Samples
ToolTip Samples