--- title: "Popup Placement Behavior" description: Learn how to specify the position of a Windows Presentation Foundation Popup relative to a control, the mouse, or the screen by using properties. ms.date: "03/30/2017" helpviewer_keywords: - "popups [WPF]" - "Popup control [WPF], placing" - "placing popups [WPF]" - "positioning popups [WPF]" ms.assetid: fbf642e9-f670-4efd-a7af-a67468a1c8e1 --- # Popup Placement Behavior A control displays content in a separate window that floats over an application. You can specify the position of a relative to a control, the mouse, or the screen by using the , , , , and properties. These properties work together to give you flexibility in specifying the position of the . > [!NOTE] > The and classes also define these five properties and behave similarly. ## Positioning the Popup The placement of a can be relative to a or to the entire screen. The following example creates four controls that are relative to a —in this case, an image. All of the controls have the property set to `image1`, but each has a different value for the placement property. [!code-xaml[PopupPositionSnippet#3](~/samples/snippets/csharp/VS_Snippets_Wpf/PopupPositionSnippet/CS/Window1.xaml#3)] The following illustration shows the image and the controls ![Image with four popup controls](./media/popup-placement-behavior/popup-placement-intro.png "Image with four popups") This simple example demonstrates how to set the and properties, but by using the , , and properties, you have even more control over where the is positioned. ## Definitions of Terms: The Anatomy of a Popup The following terms are useful in understanding how the , , , , and properties relate to each other and the : - Target object - Target area - Target origin - Popup alignment point These terms provide a convenient way to refer to various aspects of the and the control that it is associated with. ### Target Object The *target object* is the element that the is associated with. If the property is set, it specifies the target object. If is not set, and the has a parent, the parent is the target object. If there is no value and no parent, there is no target object, and the is positioned relative to the screen. The following example creates a that is the child of a . The example does not set the property on the . The default value for is , so the appears below the . [!code-xaml[PopupPositionSnippet#1](~/samples/snippets/csharp/VS_Snippets_Wpf/PopupPositionSnippet/CS/Window1.xaml#1)] The following illustration shows that the is positioned relative to the . ![Popup control with no PlacementTarget](./media/popup-placement-behavior/popup-placement-no-placement-target.png "Popup with no PlacementTarget.") The following example creates a that is the child of a , but this time the is set to `ellipse1`, so the popup appears below the . [!code-xaml[PopupPositionSnippet#2](~/samples/snippets/csharp/VS_Snippets_Wpf/PopupPositionSnippet/CS/Window1.xaml#2)] The following illustration shows that the is positioned relative to the . ![Popup positioned relative to an ellipse](./media/popup-placement-behavior/popup-placement-with-placement-target.png "Popup with PlacementTarget") > [!NOTE] > For , the default value of is . For , the default value of is . These values are explained later, in "How the Properties Work Together." ### Target Area The *target area* is the area on the screen that the is relative to. In the previous examples, the is aligned with the bounds of the target object, but in some cases, the is aligned to other bounds, even if the has a target object. If the property is set, the target area is different than the bounds of the target object. The following example creates two objects, each one containing a and a . In both cases, the target object for the is the . The in the first has the set, with its , , , and properties set to 50, 50, 50, and 100, respectively. The in the second does not have the set. As a result, the first is positioned below the and the second is positioned below the . Each also contains a that has the same bounds as the for the first . Note that the does not create a visible element in the application; the example creates a to represent the . [!code-xaml[PopupPositionSnippet#4](~/samples/snippets/csharp/VS_Snippets_Wpf/PopupPositionSnippet/CS/Window1.xaml#4)] The following illustration shows the result of the preceding example. ![Popup with and without PlacementRectangle](./media/popup-placement-behavior/popup-placement-placement-rectangle.png "Popup with and without PlacementRectangle.") ### Target Origin and Popup Alignment Point The *target origin* and *popup alignment point* are reference points on the target area and popup, respectively, that are used for positioning. You can use the and properties to offset the popup from the target area. The and are relative to the target origin and the popup alignment point. The value of the property determines where the target origin and popup alignment point are located. The following example creates a and sets the and properties to 20. The property is set to (the default), so the target origin is the bottom-left corner of the target area and the popup alignment point is the top-left corner of the . [!code-xaml[PopupPositionSnippet#5](~/samples/snippets/csharp/VS_Snippets_Wpf/PopupPositionSnippet/CS/Window1.xaml#5)] The following illustration shows the result of the preceding example. ![Popup placement with target origin alignment point](./media/popup-placement-behavior/popup-placement-target-origin-alignment-point.png "Popup with HorizontalOffset and VerticalOffset.") ## How the Properties Work Together The values of , , and need to be considered together to figure out the correct target area, target origin, and popup alignment point. For example, if the value of is , there is no target object, the is ignored, and the target area is the bounds of the mouse pointer. On the other hand, if is , the or parent determines the target object and determines the target area. The following table describes the target object, target area, target origin, and popup alignment point and indicates whether and are used for each enumeration value. |PlacementMode|Target object|Target area|Target origin|Popup alignment point| |-------------------|-------------------|-----------------|-------------------|---------------------------| ||Not applicable. is ignored.|The screen, or if it is set. The is relative to the screen.|The top-left corner of the target area.|The top-left corner of the .| ||Not applicable. is ignored.|The screen, or if it is set. The is relative to the screen.|The top-left corner of the target area.|The top-left corner of the .| || or parent.|The target object, or if it is set. The is relative to the target object.|The bottom-left corner of the target area.|The top-left corner of the .| || or parent.|The target object, or if it is set. The is relative to the target object.|The center of the target area.|The center of the .| || or parent.|The target object, or if it is set. The is relative to the target object.|Defined by the .|Defined by the .| || or parent.|The target object, or if it is set. The is relative to the target object.|The top-left corner of the target area.|The top-right corner of the .| ||Not applicable. is ignored.|The bounds of the mouse pointer. is ignored.|The bottom-left corner of the target area.|The top-left corner of the .| ||Not applicable. is ignored.|The bounds of the mouse pointer. is ignored.|The top-left corner of the target area.|The top-left corner of the .| || or parent.|The target object, or if it is set. The is relative to the target object.|The top-left corner of the target area.|The top-left corner of the .| || or parent.|The target object, or if it is set. The is relative to the target object.|The top-left corner of the target area.|The top-left corner of the .| || or parent.|The target object, or if it is set. The is relative to the target object.|The top-right corner of the target area.|The top-left corner of the .| || or parent.|The target object, or if it is set. The is relative to the target object.|The top-left corner of the target area.|The bottom-left corner of the .| The following illustrations show the , target area, target origin, and popup alignment point for each value. In each figure, the target area is yellow, and the is blue. ![Popup with Absolute or AbsolutePoint placement](./media/popup-placement-behavior/popup-placement-absolute.png "Placement is Absolute or AbsolutePoint.") ![Popup with Bottom placement](./media/popup-placement-behavior/popup-placement-bottom.png "Placement is Bottom.") ![Popup with Center placement](./media/popup-placement-behavior/popup-placement-center.png "Placement is Center.") ![Popup with Left placement](./media/popup-placement-behavior/popup-placement-left.png "Placement is Left.") ![Popup with Mouse placement](./media/popup-placement-behavior/popup-placement-mouse.png "Placement is Mouse.") ![Popup with MousePoint placement](./media/popup-placement-behavior/popup-placement-mousepoint.png "Placement is MousePoint.") ![Popup with Relative or RelativePoint placement](./media/popup-placement-behavior/popup-placement-relative.png "Placement is Relative or RelativePoint.") ![Popup with Right placement](./media/popup-placement-behavior/popup-placement-right.png "Placement is Right.") ![Popup with Top placement](./media/popup-placement-behavior/popup-placement-top.png "Placement is Top.") ## When the Popup Encounters the Edge of the Screen For security reasons, a cannot be hidden by the edge of a screen. One of the following three things happens when the encounters a screen edge: - The popup realigns itself along the screen edge that would obscure the . - The popup uses a different popup alignment point. - The popup uses a different target origin and popup alignment point. These options are described further later in this section. The behavior of the when it encounters a screen edge depends on the value of the property and which screen edge the popup encounters. The following table summarizes the behavior when the encounters a screen edge for each value. |PlacementMode|Top edge|Bottom edge|Left edge|Right edge| |-------------------|--------------|-----------------|---------------|----------------| ||Aligns to the top edge.|Aligns to the bottom edge.|Aligns to the left edge.|Aligns to the right edge.| ||Aligns to the top edge.|The popup alignment point changes to the bottom-left corner of the .|Aligns to the left edge.|The popup alignment point changes to the top-right corner of the .| ||Aligns to the top edge.|The target origin changes to the top-left corner of the target area and the popup alignment point changes to the bottom-left corner of the .|Aligns to the left edge.|Aligns to the right edge.| ||Aligns to the top edge.|Aligns to the bottom edge.|Aligns to the left edge.|Aligns to the right edge.| ||Aligns to the top edge.|Aligns to the bottom edge.|The target origin changes to the top-right corner of the target area and the popup alignment point changes to the top-left corner of the .|Aligns to the right edge.| ||Aligns to the top edge.|The target origin changes to the top-left corner of the target area (the bounds of the mouse pointer) and the popup alignment point changes to the bottom-left corner of the .|Aligns to the left edge.|Aligns to the right edge.| ||Aligns to the top edge.|The popup alignment point changes to the bottom-left corner of the .|Aligns to the left edge.|The popup alignment point changes to the top-right corner of the popup.| ||Aligns to the top edge.|Aligns to the bottom edge.|Aligns to the left edge.|Aligns to the right edge.| ||Aligns to the top edge.|The popup alignment point changes to the bottom-left corner of the .|Aligns to the left edge.|The popup alignment point changes to the top-right corner of the popup.| ||Aligns to the top edge.|Aligns to the bottom edge.|Aligns to the left edge.|The target origin changes to the top-left corner of the target area and the popup alignment point changes to the top-right corner of the .| ||The target origin changes to the bottom-left corner of the target area and the popup alignment point changes to the top-left corner of the . In effect, this is the same as when is .|Aligns to the bottom edge.|Aligns to the left edge.|Aligns to the right edge.| ### Aligning to the Screen Edge A can align to the edge of the screen by repositioning itself so the entire is visible on the screen. When this occurs, the distance between the target origin and popup alignment point might differ from the values of and . When is , , or , the aligns itself to every screen edge. For example, assume that a has set to and set to 100. If the bottom edge of the screen hides all or part of the , the repositions itself along the bottom edge of the screen and the vertical distance between the target origin and popup alignment point is less than 100. The following illustration demonstrates this. ![Popup that aligns to edge of screen](./media/popup-placement-behavior/popup-placement-relative-screen-edge.png "Popup aligns to the edge of the screen.") ### Changing the Popup Alignment Point If is , , or , the popup alignment point changes when the popup encounters the bottom or right screen edge. The following illustration demonstrates that when the bottom screen edge hides all or part of the , the popup alignment point is the bottom-left corner of the . ![New alignment point due to bottom screen edge](./media/popup-placement-behavior/popup-placement-relative-point-screen-edge.png "Popup encounters bottom edge of the screen and changes the popup alignment point.") The following illustration demonstrates that when the is hidden by the right screen edge, the popup alignment point is the top-right corner of the . ![New popup alignment point due to screen edge](./media/popup-placement-behavior/popup-placement-relative-point-right-screen-edge.png "Popup encounters right edge of the screen and changes the popup alignment point.") If the encounters the bottom and right screen edges, the popup alignment point is the bottom-right corner of the . ### Changing the Target Origin and Popup Alignment Point When is , , , , or , the target origin and popup alignment point change if a certain screen edge is encountered. The screen edge that causes the position to change depends on the value. The following illustration demonstrates that when is and the encounters the bottom screen edge, the target origin is the top-left corner of the target area and the popup alignment point is the bottom-left corner of the . ![New alignment point due to bottom screen edge](./media/popup-placement-behavior/popup-placement-bottom-screen-edge.png "Placement is Bottom and the popup encounters the bottom edge of the screen.") The following illustration demonstrates that when is and the encounters the left screen edge, the target origin is the top-right corner of the target area and the popup alignment point is the top-left corner of the . ![New alignment point due to left screen edge](./media/popup-placement-behavior/popup-placement-left-screen-edge.png "Placement is Left and the popup encounters the left edge of the screen.") The following illustration demonstrates that when is and the encounters the right screen edge, the target origin is the top-left corner of the target area and the popup alignment point is the top-right corner of the . ![New alignment point due to right screen edge](./media/popup-placement-behavior/popup-placement-right-screen-edge.png "Placement is Right and the popup encounters the right edge of the screen.") The following illustration demonstrates that when is and the encounters the top screen edge, the target origin is the bottom-left corner of the target area and the popup alignment point is the top-left corner of the . ![New alignment point due to top screen edge](./media/popup-placement-behavior/popup-placement-top-screen-edge.png "Placement is Top and the popup encounters the top edge of the screen.") The following illustration demonstrates that when is and the encounters the bottom screen edge, the target origin is the top-left corner of the target area (the bounds of the mouse pointer) and the popup alignment point is the bottom-left corner of the . ![new alignment point due to mouse near screen edge](./media/popup-placement-behavior/popup-placement-mouse-screen-edge.png "Placement is Mouse and the popup encounters the bottom edge of the screen.") ### Customizing Popup Placement You can customize the target origin and popup alignment point by setting the property to . Then define a delegate that returns a set of possible placement points and primary axes (in order of preference) for the . The point that shows the largest portion of the is selected. The position of the is automatically adjusted if the is hidden by the edge of the screen. For an example, see [Specify a Custom Popup Position](how-to-specify-a-custom-popup-position.md). ## See also - [Popup Placement Sample](https://github.com/dotnet/docs-desktop/tree/main/dotnet-desktop-guide/samples/snippets/csharp/VS_Snippets_Wpf/PopupPositionSnippet/CS)