Package limn.backend

Interface NativeWindow

All Superinterfaces:

AutoCloseable

All Known Subinterfaces:

WindowPeer

All Known Implementing Classes:

HeadlessWindow, StubWindow

public sealed interface NativeWindow
extends AutoCloseable
permits WindowPeer

A top-level native window. Sizes exposed to the toolkit are in logical points; the backend multiplies by the monitor's content scale (a float: 1.0, 1.25, 1.5, 2.0…) to obtain physical framebuffer pixels. All methods are UI-thread-only unless noted.

This is the application's view of a window, which the 1.0 contract freezes. What the toolkit asks of a window below it (input, frames, the input method, owned popups) is WindowPeer's, in the incubating layer; every window is one, which is why this interface is sealed: an application uses windows, and a backend implements them there.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	NativeWindow.ContentScaleListener	Notified when the window moves to a monitor with a different content scale.

Method Summary

Modifier and Type	Method	Description
default AccessibilityBridge	accessibility()
Backend	backend()
default ScreenRect	bounds()
default void	captureNextFrame(Path pngFile)	Captures the next rendered frame to a PNG file, creating the parent directories if they are missing: the --screenshot path.
void	captureNextFrame(Consumer<Image> sink)	Captures the next rendered frame (post-flush, pre-swap) and hands the pixels to sink: a per-window screenshot without touching the frame callback, and without a file.
Clipboard	clipboard()
void	close()	Same as requestClose(); actual destruction happens in the loop/backend.
ClosePolicy	closePolicy()
@Nullable CloseRequestHandler	closeRequestHandler()
float	contentScale()
default float	cursorX()
default float	cursorY()
default @Nullable Display	display()
default void	enterFullscreen()	Makes the window fullscreen without changing the display's mode: native fullscreen on macOS, a borderless window covering the monitor at its current mode on Windows and X11, and the compositor's fullscreen on Wayland.
void	enterFullscreen(int width, int height, int refreshRate)	Makes the window fullscreen on the monitor it occupies, in one of two ways, chosen by whether the call names a display mode.
default void	enterFullscreen(Resolution mode)	Makes the window fullscreen at mode, switching the display to it: the exclusive fullscreen a game asks for, on every platform but Wayland, which changes no display's mode.
void	exitFullscreen()	Leaves fullscreen of either kind, and does nothing for a window that is not fullscreen.
FileDialogs	fileDialogs()
void	focus()	Brings this window to the front and gives it input focus.
int	framebufferHeight()
int	framebufferWidth()
void	hide()
boolean	isClosed()
boolean	isFullscreen()	Whether the window is fullscreen, of either kind.
default boolean	isMaximized()
default boolean	isMinimized()
boolean	isModalBlocked()
boolean	isVisible()
Launcher	launcher()
float	logicalHeight()
float	logicalToScreenFactor()
float	logicalWidth()
default void	maximize()	Maximizes the window: it fills the screen's work area, keeping its frame.
default void	minimize()	Minimizes the window: it leaves the screen and stays in the desktop's dock or task bar, from where the user brings it back.
default long	nativeHandle()	This window's handle in the platform's own terms: an HWND on Windows, an NSWindow on macOS, an xcb_window_t or wl_surface on Linux.
default Subscription	observeState(Consumer<WindowState> listener)	Observes the window's state: the listener is told each time the window is shown or hidden, minimized, maximized or restored, enters or leaves fullscreen, is moved or changes size, whether the application did it or the user.
void	overrideContentScale(float scale)	Forces the rendering content scale, ignoring the monitor's.
default PointerMode	pointerMode()
Printer	printer()
void	requestClose()	Asks the window to close (processed by the event loop).
void	requestFrame()	Marks the window dirty so the loop renders a frame for it.
default void	restore()	Puts a minimized or a maximized window back to the size and the place it had before.
int	screenX()
int	screenY()
default void	setAboveSystemChrome(boolean above)	Raises this window above the OS chrome so it can cover the whole display.
default void	setAccessibility(AccessibilityBridge bridge)	Hands this window the platform accessibility bridge an application chose for it.
void	setClosePolicy(ClosePolicy policy)	Sets what a user's close does once it is allowed: dispose the window (the default), hide it, or end the application.
void	setCloseRequestHandler(@Nullable CloseRequestHandler handler)	Sets the handler asked whether this window may close: when the user closes it (the OS close button, Alt-F4, Cmd-W), and when the application is ending (Backend.requestQuit()).
void	setContentScaleListener(NativeWindow.ContentScaleListener listener)	Registers a listener for runtime monitor/content-scale changes.
default void	setCursor(@Nullable Cursor cursor)	Sets the mouse cursor shown while the pointer is over this window.
default void	setCursorPosition(float x, float y)	Warps the pointer to (x, y) in logical points relative to this window's content area.
default void	setIcon(Image... icons)	Sets the window icon (title bar / taskbar) from one or more candidate sizes; the platform picks the closest (16–48px covers the common slots).
default void	setImageCursor(@Nullable ImageCursor cursor)	Shows a custom ImageCursor instead of the current standard shape; null clears it and restores the last shape.
default void	setMousePassthrough(boolean passthrough)	Makes the window transparent to MOUSE input: clicks, wheel and hover pass through to whatever sits beneath it, for overlay/HUD windows whose empty (usually transparent) regions must not steal the desktop's mouse.
default void	setOpacity(float opacity)	Sets the whole-window opacity in [0..1] at the compositor level, the fade primitive behind Scene.fadeWindow(float, double, java.lang.Runnable).
default void	setPointerMode(@Nullable PointerMode mode)	Sets how this window treats the pointer: visibility, confinement, relative capture.
void	setScreenPosition(int x, int y)	Moves the window (native screen coordinates; see logicalToScreenFactor()).
void	setSize(int width, int height)	Resizes the window to the given size in logical points.
default void	setSizeLimits(int minWidth, int minHeight, int maxWidth, int maxHeight)	Constrains user resizing to the given bounds in logical points; pass <= 0 for any bound to leave it unconstrained.
void	setTitle(String title)	Sets the native title bar text.
void	show()
default SizeLimits	sizeLimits()
default WindowState	state()
String	title()
default void	toFront()	Brings the window in front of the others and gives it the keyboard, whatever state it is in: shown if it was hidden, restored if it was minimized.

Method Details

title

String title()

Returns:

the current title

setTitle

void setTitle(String title)

Sets the native title bar text.

logicalWidth

float logicalWidth()

Returns:

width in logical points (framebuffer width ÷ content scale)

logicalHeight

float logicalHeight()

Returns:

height in logical points (framebuffer height ÷ content scale)

framebufferWidth

int framebufferWidth()

Returns:

framebuffer width in physical pixels

framebufferHeight

int framebufferHeight()

Returns:

framebuffer height in physical pixels

contentScale

float contentScale()

Returns:

the content scale in effect for this window: the monitor's, or the forced one. Fractional values (1.25, 1.5, 1.75) are first-class citizens, never assume integer

overrideContentScale

void overrideContentScale(float scale)

Forces the rendering content scale, ignoring the monitor's. Screenshot scenes use it to validate 1.0/1.25/1.5/2.0 rendering on any monitor. Pass 0 to return to the monitor scale.

setSize

void setSize(int width,
 int height)

Resizes the window to the given size in logical points.

setSizeLimits

default void setSizeLimits(int minWidth,
 int minHeight,
 int maxWidth,
 int maxHeight)

Constrains user resizing to the given bounds in logical points; pass <= 0 for any bound to leave it unconstrained. Only affects interactive resizes; setSize(int, int) is not clamped. A window made from a WindowConfig with WindowConfig.minSize(int, int) or WindowConfig.maxSize(int, int) starts with those. The default implementation ignores it (headless/embedding). UI thread only.

sizeLimits

default SizeLimits sizeLimits()

Returns:

the bounds the user may resize this window within, as its configuration or the last setSizeLimits(int, int, int, int) set them; SizeLimits.NONE where the implementation keeps none (headless, embedding)

setIcon

default void setIcon(Image... icons)

Sets the window icon (title bar / taskbar) from one or more candidate sizes; the platform picks the closest (16–48px covers the common slots). No-op where the platform has no per-window icons (macOS uses the app bundle's icon; a Wayland desktop shows the application entry's). The default implementation ignores it (headless/embedding). UI thread only.

setCloseRequestHandler

void setCloseRequestHandler(@Nullable CloseRequestHandler handler)

Sets the handler asked whether this window may close: when the user closes it (the OS close button, Alt-F4, Cmd-W), and when the application is ending (Backend.requestQuit()). It answers through the CloseRequest it is handed, at once or later, so an "unsaved changes" dialog can decide. With no handler, the window agrees. A program's requestClose() bypasses it. null clears. UI thread only.

A window created with an owner (WindowConfig.popup(NativeWindow, int, int) or WindowConfig.ownedBy(limn.backend.NativeWindow): a native dialog, a menu) is not asked when the application ends: its owner speaks for it, and it closes with it.

No default: a backend that ignored it lost an application's "unsaved changes" veto silently. A backend with no close gesture of its own (headless, embedded) keeps the handler, asks it only when the application ends, and says so in its implementation.

Parameters:

handler - the handler, or null for none

closeRequestHandler

@Nullable CloseRequestHandler closeRequestHandler()

Returns:

the handler set with setCloseRequestHandler(limn.backend.CloseRequestHandler), or null for none

setClosePolicy

void setClosePolicy(ClosePolicy policy)

Sets what a user's close does once it is allowed: dispose the window (the default), hide it, or end the application. A program's requestClose() disposes whatever this says. UI thread only.

Parameters:

policy - the policy; never null

Throws:

NullPointerException - if policy is null

closePolicy

ClosePolicy closePolicy()

Returns:

what a user's close does; ClosePolicy.DISPOSE unless set

show

void show()

hide

void hide()

minimize

default void minimize()

Minimizes the window: it leaves the screen and stays in the desktop's dock or task bar, from where the user brings it back. Unlike hide(), the user can reach it again without the application's help. UI thread only.

The default does nothing, which is the answer of a window with no desktop under it; so do maximize(), restore() and the two readings beside them.

maximize

default void maximize()

Maximizes the window: it fills the screen's work area, keeping its frame. A window in fullscreen is left as it is. UI thread only.

restore

default void restore()

Puts a minimized or a maximized window back to the size and the place it had before. A window that is neither is left as it is. UI thread only.

isMinimized

default boolean isMinimized()

Returns:

whether the window is minimized now. Under Wayland a client is not told, and the answer is false

isMaximized

default boolean isMaximized()

Returns:

whether the window is maximized now

bounds

default ScreenRect bounds()

Returns:

the window's content's place and size in native screen coordinates: screenX(), screenY(), and its logical size by logicalToScreenFactor(). UI thread only

state

default WindowState state()

Returns:

where the window is, how large and in which state, now. UI thread only

observeState

default Subscription observeState(Consumer<WindowState> listener)

Observes the window's state: the listener is told each time the window is shown or hidden, minimized, maximized or restored, enters or leaves fullscreen, is moved or changes size, whether the application did it or the user. It is told on the UI thread, after the change and once for it, with the state as it then is; a window the user drags or resizes tells it at each place and size along the way.

The default tells nothing, which is the answer of a window with no desktop under it.

Parameters:

listener - what to tell

Returns:

a handle that unsubscribes; cancelling it twice is a no-op. UI thread only

toFront

default void toFront()

Brings the window in front of the others and gives it the keyboard, whatever state it is in: shown if it was hidden, restored if it was minimized. It is what a click on an application's tray icon or on a "show the window" command calls. Whether a window may come in front of another application's is the desktop's to allow, as for focus(). UI thread only.

setOpacity

default void setOpacity(float opacity)

Sets the whole-window opacity in [0..1] at the compositor level, the fade primitive behind Scene.fadeWindow(float, double, java.lang.Runnable). Affects the entire window uniformly, decorations included. A no-op where the platform's compositor does not support per-window opacity, and under Wayland, which gives a program none; the default implementation ignores it (headless/embedding). UI thread only.

setCursor

default void setCursor(@Nullable Cursor cursor)

Sets the mouse cursor shown while the pointer is over this window. The scene calls this as the hovered widget changes; null or Cursor.DEFAULT restores the plain arrow. A shape the platform cannot provide falls back to the arrow. The default implementation ignores it (headless/embedding). UI thread only.

focus

void focus()

Brings this window to the front and gives it input focus. UI thread only.

isVisible

boolean isVisible()

Returns:

whether the window is currently visible on screen

isClosed

boolean isClosed()

Returns:

whether this window has already been closed/destroyed

enterFullscreen

void enterFullscreen(int width,
 int height,
 int refreshRate)

Makes the window fullscreen on the monitor it occupies, in one of two ways, chosen by whether the call names a display mode.

Naming no mode, width, height and refreshRate all ≤ 0 as enterFullscreen() passes them, leaves the display in the mode it is in, which is the fullscreen a document, a dashboard or any application that is not a game wants:

• macOS: native fullscreen, what the green button and Control-Command-F do. The window moves to a Space of its own with an animation of most of a second, the menu bar and the title bar slide in when the pointer reaches the top of the screen, and the person can leave it the way they leave any application's. This call returns before the animation ends, and the window reports its new size when AppKit resizes it.
• Windows and X11: a borderless window covering the monitor at the mode it is in, on X11 through the window manager's fullscreen state where it has one.
• Wayland: the compositor's fullscreen.

Naming a mode, a size or a refresh rate or both, is the exclusive fullscreen a game asks for: the display is switched to the mode it lists nearest to the one named, which holds the application for a noticeable moment each way (more than half a second on a Mac), and is switched back by exitFullscreen(). A dimension ≤ 0 beside a named one is the current one. The size is in screen coordinates, as a Resolution's is: pixels on Windows, X11 and Wayland, points on macOS. On macOS the window covers the menu bar and the Dock and has no Space of its own; the mode a Retina display is in is usually not one it can be switched to, so naming the current mode switches to another. Wayland lets no application change the display's mode, and there the window is fullscreen at the compositor's whatever is named.

Losing the focus tells the two apart. A window at a named mode is minimized when another window takes the focus, on every platform, and a switched mode is switched back until the window is restored, which is what a game wants when the person switches away from it. A window at the mode the display is in is not: on Windows, X11 and Wayland it stays fullscreen behind the window that took the focus, as a browser's fullscreen does, and the person comes back to it as they left it; on macOS the person moves to another Space and back.

A window already fullscreen one way and asked for the other leaves the first: a switched mode is switched back before native fullscreen begins, and native fullscreen is left, with its animation, before the mode is switched. The windowed position and size are remembered for exitFullscreen(). UI thread only.

Parameters:

width - width in screen coordinates, or ≤ 0 to name none

height - height in screen coordinates, or ≤ 0 to name none

refreshRate - refresh rate in Hz, or ≤ 0 to name none

enterFullscreen

default void enterFullscreen()

Makes the window fullscreen without changing the display's mode: native fullscreen on macOS, a borderless window covering the monitor at its current mode on Windows and X11, and the compositor's fullscreen on Wayland. The fullscreen of an application rather than a game: it is not minimized when another window takes the focus, but stays fullscreen behind it. See enterFullscreen(int, int, int). UI thread only.

enterFullscreen

default void enterFullscreen(Resolution mode)

Makes the window fullscreen at mode, switching the display to it: the exclusive fullscreen a game asks for, on every platform but Wayland, which changes no display's mode. The normalized form of enterFullscreen(int, int, int) that takes a Resolution, such as one from display().availableResolutions(). To keep the display as it is, call enterFullscreen() instead: on macOS a Retina display's current mode is usually not among those a switch can reach. The window is minimized when another window takes the focus, and the display switched back until it is restored. UI thread only.

Parameters:

mode - the mode to switch to

Throws:

NullPointerException - if mode is null, as it is from a display that lists none

exitFullscreen

void exitFullscreen()

Leaves fullscreen of either kind, and does nothing for a window that is not fullscreen. A switched mode is switched back and the windowed position and size asked for before this returns, and given back as the window had them: where the window manager answers later, as on X11, a window it gives back maximized when it was not, or elsewhere or at another size, is asked once more when the answer comes. macOS native fullscreen is left with its animation, after this returns, and is left whether the application or the person entered it. UI thread only.

isFullscreen

boolean isFullscreen()

Whether the window is fullscreen, of either kind. On macOS that includes native fullscreen the person entered with the green button, Control-Command-F or the menu, and the answer is where the window is going rather than where its animation has got to: true from the moment enterFullscreen() returns or the person starts the animation, false from the moment exitFullscreen() returns or the person starts leaving. Elsewhere it is whether this window was made fullscreen and has not been told to leave.

Each change of this answer is told to the window's input, through WindowInput.windowFullscreenChanged(boolean), including the changes the person makes on macOS. A window that can never be fullscreen never tells it.

Returns:

whether the window is, or is going to be, fullscreen

isModalBlocked

boolean isModalBlocked()

Returns:

whether this window is currently locked by an active modal (its input is ignored); the scene dims it while true

backend

Backend backend()

Returns:

the backend that owns this window (popup creation, shutdown)

fileDialogs

FileDialogs fileDialogs()

Returns:

the platform's file and folder choosers, owned by this window; FileDialogs.NONE for a window with none (headless, embedded). No default: a backend that answered NONE by omission made every "Open…" in an application silently do nothing. UI thread only.

launcher

Launcher launcher()

Returns:

what hands an address or a file to the system this window is on; Launcher.NONE for a window with no desktop under it (headless, embedded). No default, for the reason fileDialogs() has none: a link that silently opens nothing. UI thread only.

printer

Printer printer()

Returns:

what prints a PDF through the system's own print dialog, owned by this window; Printer.NONE for a window with no printing under it (headless, embedded). No default, for the reason launcher() has none: a "Print…" that silently prints nothing. UI thread only.

clipboard

Clipboard clipboard()

Returns:

the system clipboard

screenX

int screenX()

Returns:

window x in native screen coordinates

screenY

int screenY()

Returns:

window y in native screen coordinates

setScreenPosition

void setScreenPosition(int x,
 int y)

Moves the window (native screen coordinates; see logicalToScreenFactor()).

setMousePassthrough

default void setMousePassthrough(boolean passthrough)

Makes the window transparent to MOUSE input: clicks, wheel and hover pass through to whatever sits beneath it, for overlay/HUD windows whose empty (usually transparent) regions must not steal the desktop's mouse. While enabled this window receives no mouse events at all; poll cursorX()/cursorY() to decide when to turn it back off (e.g. the cursor entered one of the overlay's visible items). Keyboard focus is unaffected. No-op where the platform lacks support.

cursorX

default float cursorX()

Returns:

the cursor's current x in logical points relative to this window's content area; polled, so it works while unfocused or mouse-passthrough (which mutes events). NaN when unsupported. UI thread only.

cursorY

default float cursorY()

Returns:

the cursor's current y; see cursorX()

setPointerMode

default void setPointerMode(@Nullable PointerMode mode)

Sets how this window treats the pointer: visibility, confinement, relative capture. See each PointerMode constant; null means PointerMode.NORMAL. In PointerMode.RELATIVE the window stops receiving WindowInput.mouseMoved(float, float) and receives WindowInput.mouseDelta(float, float) instead. Interactions that capture from a widget must restore NORMAL when they end (release/EXIT/detach); the mode is window state and survives the widget. No-op where unsupported. UI thread only.

pointerMode

default PointerMode pointerMode()

Returns:

the current PointerMode (default PointerMode.NORMAL)

setImageCursor

default void setImageCursor(@Nullable ImageCursor cursor)

Shows a custom ImageCursor instead of the current standard shape; null clears it and restores the last shape. The scene drives this from Widget.setImageCursor(limn.backend.ImageCursor) hover resolution; call it directly only in windowless/manual setups. UI thread only.

setCursorPosition

default void setCursorPosition(float x,
 float y)

Warps the pointer to (x, y) in logical points relative to this window's content area. No input event is synthesized; the next real mouse event reflects the new position. Useful with PointerMode.RELATIVE interactions and edge-wrap schemes; may be restricted by the platform while the window is unfocused, and does nothing under Wayland, which lets no program move the pointer. UI thread only.

setAboveSystemChrome

default void setAboveSystemChrome(boolean above)

Raises this window above the OS chrome so it can cover the whole display. On macOS the menu bar and Dock draw at window levels above an ordinary always-on-top window, so a full-screen transparent overlay would otherwise be occluded by them. When enabled the window floats above that chrome (a cube can fly over the menu bar; transparent regions still show it through, and passthrough keeps it clickable); disabling restores the normal always-on-top level. No-op where the platform needs nothing extra to cover its chrome. UI thread only.

logicalToScreenFactor

float logicalToScreenFactor()

Returns:

multiplier from logical points to native screen coordinates (1.0 on macOS, the monitor scale on Windows/X11), for positioning popups relative to widget bounds

display

default @Nullable Display display()

Returns:

the Display this window currently sits on (the monitor containing the window's centre), or null when headless/embedded. Its Display.workArea() is what external popups clamp against to stay on screen. UI thread only.

captureNextFrame

void captureNextFrame(Consumer<Image> sink)

Captures the next rendered frame (post-flush, pre-swap) and hands the pixels to sink: a per-window screenshot without touching the frame callback, and without a file. Requests a frame, so it works on an idle window. sink runs on the UI thread inside that frame.

The image is display-referred: it is what the composite produced, not scene-referred content awaiting a display transform. See GpuRenderer.captureFramebuffer(java.util.function.Consumer).

captureNextFrame

default void captureNextFrame(Path pngFile)

Captures the next rendered frame to a PNG file, creating the parent directories if they are missing: the --screenshot path.

accessibility

default AccessibilityBridge accessibility()

Returns:

the platform accessibility bridge for this window, or AccessibilityBridge.NONE when it has none.

default on the merits rather than as a compatibility dodge: none is the correct behaviour for a window with no accessibility — a test double, an embedded surface, any future backend on its first day — and getting exactly zero cost by writing nothing is better than getting it by writing the same stub in each.

setAccessibility

default void setAccessibility(AccessibilityBridge bridge)

Hands this window the platform accessibility bridge an application chose for it.

The other half of the seam above, and it was missing: an application could read what a window's bridge was and had no way to say what it should be, so the per-platform bridges ADR 039 makes optional artifacts could be added to a classpath and never installed. It is a setter and not a constructor argument because the Windows bridge needs nativeHandle() to exist before it can be made, and that handle is the window's.

default for the same reason the getter is: a window with no accessibility is a correct window, and ignoring the offer is the correct thing for one to do.

Parameters:

bridge - what to hand a scene bound here, never null

nativeHandle

default long nativeHandle()

This window's handle in the platform's own terms: an HWND on Windows, an NSWindow on macOS, an xcb_window_t or wl_surface on Linux.

Exists for one caller and should have no other: a platform accessibility bridge that has to attach to the window itself. The Windows one replaces the window procedure to answer WM_GETOBJECT; the macOS one will need the NSWindow to reach its content view. Nothing in the toolkit reads this, and an application that finds itself wanting it for anything else is describing a gap in this interface rather than a use for this method.

Returns:

the handle, or 0 where there is none — a test double, an embedded surface, a platform this backend has not been taught

setContentScaleListener

void setContentScaleListener(NativeWindow.ContentScaleListener listener)

Registers a listener for runtime monitor/content-scale changes.

requestFrame

void requestFrame()

Marks the window dirty so the loop renders a frame for it. UI thread only: from a background thread, hop with Ui.post(window::requestFrame).

requestClose

void requestClose()

Asks the window to close (processed by the event loop). Any-thread safe.

close

void close()

Same as requestClose(); actual destruction happens in the loop/backend.

Specified by:

close in interface AutoCloseable