RFR: 8372530: Easier placement of windows with positioning anchor

[Andy Goryachev]

On Tue, 25 Nov 2025 18:58:14 GMT, Michael Strauß <mstrauss at openjdk.org> wrote:

> This enhancement allows `Stage` to be placed on the screen similar to a popup window, where a user-specified positioning anchors defines a point on the stage that should coincide with a given location on the screen. For this purpose, the following new methods are added to `Stage`:
> 
> 
> public class Stage {
>     public void relocate(AnchorPoint screenAnchor, AnchorPoint stageAnchor);
>     public void relocate(AnchorPoint screenAnchor, Insets screenPadding, AnchorPoint stageAnchor, AnchorPolicy);
>     public void relocate(Screen, AnchorPoint screenAnchor, Insets screenPadding, AnchorPoint stageAnchor, AnchorPolicy);
> }
> 
> 
> ## AnchorPoint
> `AnchorPoint` is a point that is either specified in absolute coordinates, or relative to the screen or stage:
> 
> var anchor1 = AnchorPoint.proportional(0.5, 0.5); // center of the screen/stage
> var anchor2 = AnchorPoint.absolute(100, 100); // absolute coordinates within screen/stage
> 
> 
> For example, a stage that sits flush with the bottom-right corner of the screen can be shown as follows:
> 
> var screenAnchor = AnchorPoint.proportional(1, 1); // or use the AnchorPoint.BOTTOM_RIGHT constant
> var stageAnchor = AnchorPoint.proportional(1, 1);
> stage.relocate(screenAnchor, stageAnchor);
> stage.show();
> 
> 
> ## AnchorPolicy
> `AnchorPolicy` controls how the anchor may be adjusted when the preferred placement doesn't fit within the screen bounds:
> 
> 
> public enum AnchorPolicy {
>     FIXED,
>     FLIP_HORIZONTAL,
>     FLIP_VERTICAL,
>     AUTO
> }
> 
> 
> * `FIXED`: always use the provided anchor; only adjust the resulting position to fit within the screen.
> * `FLIP_HORIZONTAL`: if the preferred placement violates horizontal constraints, try a horizontally flipped anchor (e.g. top-left to top-right) before falling back to the original anchor.
> * `FLIP_VERTICAL`: likewise for vertical constraints.
> * `AUTO`: automatically choose the most suitable flip:
>    if only horizontal constraints are violated, acts like `FLIP_HORIZONTAL`;
>    if only vertical constraints are violated, acts like `FLIP_VERTICAL`;
>    if both are violated, try a diagonally flipped anchor (both axes) and pick the placement that requires the least adjustment.
> 
> This is useful for popup-like behavior where you have a preferred "opening direction", but want the window to flip to the opposite side of the reference point when there isn’t enough space (e.g. "prefer below, but open above if below doesn’t fit").
> 
> ### PopupWindow support
> The new `PopupWindow.anchorPolicy` property adds the same "flip the anchor when it...

So far looks very good.  I'll continue testing tomorrow.

FYI:
I've added new options to the Popup/Stage pages in the standalone Monkey Tester on a separate branch:

https://github.com/andy-goryachev-oracle/MonkeyTest/tree/window.relocation

modules/javafx.graphics/src/main/java/javafx/stage/AnchorPolicy.java line 52:

> 50:      * is biased towards the edge that is closer to the anchor.
> 51:      */
> 52:     FIXED,

should we mention that this one corresponds to the default behavior?

modules/javafx.graphics/src/main/java/javafx/stage/AnchorPolicy.java line 90:

> 88:      * If this is not possible, the window is biased towards the edge that is closer to the anchor.
> 89:      */
> 90:     AUTO

Is there a need for something like NONE, where the dev wants to force a particular behavior regardless of the constraints, even if the popup spans the screens?
(I don't suppose we do, but wanted to ask)

modules/javafx.graphics/src/main/java/javafx/stage/PopupWindow.java line 645:

> 643:      * horizontally or vertically, or an anchor location may be selected automatically.
> 644:      * <p>
> 645:      * If no alternative anchor location yields a better placement, the specified {@code anchorLocation} is used.

what happens when the policy is set to `null`?

-------------

PR Review: https://git.openjdk.org/jfx/pull/1986#pullrequestreview-3568254143
PR Review Comment: https://git.openjdk.org/jfx/pull/1986#discussion_r2611224413
PR Review Comment: https://git.openjdk.org/jfx/pull/1986#discussion_r2611229483
PR Review Comment: https://git.openjdk.org/jfx/pull/1986#discussion_r2611919699