Package limn.backend

Interface NativeWindow

All Superinterfaces:
AutoCloseable
public interface NativeWindow extends AutoCloseable
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.

  • 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. The default implementation ignores it (headless/embedding). UI thread only.

    • 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; some Wayland compositors ignore it). The default implementation ignores it (headless/embedding). UI thread only.

    • setCloseRequestHandler

      default void setCloseRequestHandler(BooleanSupplier handler)
      Consulted when the user asks to close the window (the OS close button, Alt-F4, Cmd-W): return false to veto and keep the window open, e.g. to show an "unsaved changes" dialog first, closing later via requestClose(), which (like every programmatic close) bypasses the handler. null clears. The default implementation ignores it (headless/embedding). UI thread only.

    • show

      void show()

    • hide

      void hide()

    • 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; the default implementation ignores it (headless/embedding). UI thread only.

    • setCursor

      default void setCursor(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.

    • setImeEnabled

      default void setImeEnabled(boolean enabled)
      Enables or disables the platform input method (IME) for this window. The scene turns it on while a text-editing widget holds focus and off otherwise, so composition keys never leak into non-text UI. A no-op where the platform has no IME control; the default implementation ignores it (headless/embedding). UI thread only.

    • setPreeditCaretRect

      default void setPreeditCaretRect(float x, float y, float width, float height)
      Positions the IME candidate/composition window at the caret, so it follows the text being edited. x/y/width/height are in logical points relative to the window's content area (the scene feeds the focused widget's caretRect). A no-op where unsupported; the default implementation ignores it (headless/embedding). UI thread only.

    • resetPreedit

      default void resetPreedit()
      Cancels any in-progress IME composition held by the platform for this window. The scene calls it when focus leaves a text-editing widget, so a composition started there can never commit into whatever is focused next. A no-op where unsupported or when nothing is being composed; the default implementation ignores it (headless/embedding). 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)
      Enters exclusive (mode-setting) fullscreen on the monitor the window currently occupies. Pass width/height ≤ 0 to keep the monitor's current resolution (no mode switch); pass refreshRate ≤ 0 for the monitor default. The previous windowed geometry is remembered for exitFullscreen(). UI thread only.
      Parameters:
      width - target width in physical pixels, or ≤ 0 for current
      height - target height in physical pixels, or ≤ 0 for current
      refreshRate - target refresh in Hz, or ≤ 0 for the default

    • enterFullscreen

      default void enterFullscreen()
      Enters exclusive fullscreen at the monitor's current resolution. UI thread only.

    • enterFullscreen

      default void enterFullscreen(Resolution mode)
      Enters exclusive fullscreen at mode on the current display, the normalized form of enterFullscreen(int, int, int) that reuses a Resolution (e.g. one from display().availableResolutions()). UI thread only.

    • exitFullscreen

      void exitFullscreen()
      Restores the previous windowed geometry (no-op if not fullscreen). UI thread only.

    • isFullscreen

      boolean isFullscreen()
      Returns:
      whether the window is currently in exclusive 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

    • registerChildPopup

      default void registerChildPopup(NativeWindow child)
      Registers a child popup to be closed automatically when this window closes, so a combo/menu popup can never outlive its parent.

      Registers it as NativeWindow.PopupKind.TRANSIENT, which is what a dropdown or a menu is. A window of its own has to say so: see registerChildPopup(NativeWindow, PopupKind).

    • registerChildPopup

      void registerChildPopup(NativeWindow child, NativeWindow.PopupKind kind)
      Registers a child popup and says what it is; see NativeWindow.PopupKind, which is the whole reason this overload exists.

    • unregisterChildPopup

      void unregisterChildPopup(NativeWindow child)
      Unregisters a child popup that closed on its own.

    • setFrameCallback

      void setFrameCallback(FrameCallback callback)
      Registers the per-frame render callback.

    • setInput

      void setInput(WindowInput input)
      Registers the input sink (usually the scene). See WindowInput.

    • backend

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

    • 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()).

    • supportsAbsolutePositioning

      default boolean supportsAbsolutePositioning()
      Whether screenX(), screenY() and setScreenPosition(int, int) actually work on this platform. When false the getters report a placeholder and the setter is ignored: a window is placed by the desktop and never learns where it went.

      Ask this before drawing anything outside a window that has to line up with something inside it: a dropdown's list, a menu cascade, a tooltip. Those are not windows in their own right; they are the owner's content, escaping the frame because most desktops offer no other way to overflow it. Where the answer is false there is no such way, and the content has to be drawn in the scene instead, clipped to the owner.

      A window that is genuinely a window (a document, a dialog, a palette) needs no such check. It has no position to agree with, so letting the desktop place it is the right outcome rather than a fallback.

      true by default, because every platform Limn ran on before Wayland could do this and a backend that says nothing is one of those. Wayland is the first that cannot: absolute window position is absent from the protocol by design, not missing from an implementation, so this can never become universally true again.

    • 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(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(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. 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 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.

    • 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