RFR: 8354478: Improve StageStyle documentation

[John Hendrikx]

On Sun, 13 Apr 2025 15:24:43 GMT, Thiago Milczarek Sayao <tsayao at openjdk.org> wrote:

> Improve StageStyle Documentation
> 
> - Update `StageStyle.UTILITY`:
> Clarified that UTILITY stages may impose platform-specific restrictions on window states, such as preventing maximize, minimize (iconify), and fullscreen operations.
> 
> - Update `StageStyle.UNDECORATED`:
> Improved the description to clarify that although UNDECORATED removes standard window decorations (title bar, borders, and controls), window operations like minimize, maximize, and fullscreen may still be allowed programmatically or via platform-specific functions such as key shortcuts or menu options.
> 
> - Remove mention of solid white background:
> This seems to be not true anymore, even withou a `Scene` (or there's a bug)

modules/javafx.graphics/src/main/java/javafx/stage/StageStyle.java line 44:

> 42:      * This style allows window operations such as resize, minimize, maximize
> 43:      * and fullscreen to be either programmatically controlled or achieved through
> 44:      * platform-specific functions, such as key shortcuts or menu options.

It looks like you intend the 2nd part to be a new paragraph:
Suggestion:

     * Defines a {@code Stage} style with no window decorations, such as a title bar,
     * borders, or window controls.
     * <p>
     * This style allows window operations such as resize, minimize, maximize
     * and fullscreen to be either programmatically controlled or achieved through
     * platform-specific functions, such as key shortcuts or menu options.

modules/javafx.graphics/src/main/java/javafx/stage/StageStyle.java line 62:

> 60:      * Utility stages may restrict window operations like maximize, minimize,
> 61:      * and fullscreen depending on the platform. They are designed to float above
> 62:      * primary windows without acting as a main application stage.

Suggestion:

     * Defines a lightweight {@code Stage} with minimal decorations, intended for
     * supporting tasks such as tool palettes.
     * <p>
     * Utility stages may restrict window operations like maximize, minimize,
     * and fullscreen depending on the platform. They are designed to float above
     * primary windows without acting as a main application stage.

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

PR Review Comment: https://git.openjdk.org/jfx/pull/1776#discussion_r2042142761
PR Review Comment: https://git.openjdk.org/jfx/pull/1776#discussion_r2042143396