Package limn.backend

Class WindowConfig

java.lang.Object
limn.backend.WindowConfig
public final class WindowConfig extends Object
Initial configuration for a NativeWindow: start from of(java.lang.String, int, int), then change what differs from a plain window with a wither. 

 backend.createWindow(WindowConfig.of("Hello, Limn", 480, 320));
 backend.createWindow(WindowConfig.of("Tools", 300, 500).resizable(false).floating(true));

A class and not a record: a record's canonical constructor is public, so every option added to it broke every caller that listed the options by position, and six of the eleven were booleans a reader could not tell apart. A new option is a new wither here, and no caller changes.

Immutable: every wither returns a copy.

  • Field Details

    • ANY_POSITION

      public static final int ANY_POSITION
      screenX()/screenY() meaning wherever the desktop would put it, which is the default and what every window wanted until one of them had to be reproducible.
      See Also:

  • Method Details

    • of

      public static WindowConfig of(String title, int width, int height)
      A plain window: visible, resizable, decorated, opaque, taking the focus when shown, wherever the desktop puts it. The common case, and where every other one starts.
      Parameters:
      title - title bar text
      width - initial width in logical points
      height - initial height in logical points
      Returns:
      the configuration

    • popup

      public static WindowConfig popup(NativeWindow owner, int width, int height)
      Undecorated, floating, transparent, non-focus-stealing window, created hidden so it can be positioned before NativeWindow.show(): the shape of a combo/menu popup. It is owner's own content drawn outside its frame, so it closes and moves with the owner and stays usable under a modal the owner hosts in its scene; place it with atInOwner(float, float).
      Parameters:
      owner - the window whose content this popup is
      width - initial width in logical points
      height - initial height in logical points
      Returns:
      the configuration
      Throws:
      NullPointerException - if owner is null

    • styled

      public static WindowConfig styled(String title, int width, int height, WindowStyle style, boolean floating, boolean focusOnShow)
      A styled window created hidden (position, then NativeWindow.show()).
      Parameters:
      style - decoration/translucency (see WindowStyle)
      floating - always-on-top
      focusOnShow - whether showing it steals input focus

    • title

      public String title()
      Returns:
      title bar text

    • width

      public int width()
      Returns:
      initial width in logical points

    • height

      public int height()
      Returns:
      initial height in logical points

    • visible

      public boolean visible()
      Returns:
      whether the window starts shown; false for offscreen or screenshot rendering and for a window positioned before NativeWindow.show()

    • resizable

      public boolean resizable()
      Returns:
      whether the user may resize the window

    • decorated

      public boolean decorated()
      Returns:
      whether the window has the native title bar and border (false for popups)

    • floating

      public boolean floating()
      Returns:
      whether the window stays above others (popups, tooltips)

    • transparent

      public boolean transparent()
      Returns:
      whether the framebuffer is transparent: pixels with alpha < 1 composite over whatever is behind the window (rounded popup corners, translucent panels)

    • focusOnShow

      public boolean focusOnShow()
      Returns:
      whether NativeWindow.show() takes the input focus (false keeps it in the parent: combo popups)

    • screenX

      public int screenX()
      Returns:
      initial x in native screen coordinates, or ANY_POSITION

    • screenY

      public int screenY()
      Returns:
      initial y in native screen coordinates, or ANY_POSITION

    • sizeLimits

      public SizeLimits sizeLimits()
      Returns:
      the bounds the user may resize the window within; SizeLimits.NONE unless minSize(int, int) or maxSize(int, int) set one

    • minSize

      public WindowConfig minSize(int width, int height)
      A copy the user cannot make smaller than width×height. A window whose content stops being usable below some size says so here, where the window is made, rather than with NativeWindow.setSizeLimits(int, int, int, int) once it is on screen. The limits bound the user's resizing; a window opened at a size outside them is brought within them as it opens.
      Parameters:
      width - the narrowest, in logical points; 0 leaves the width open
      height - the shortest; 0 leaves the height open
      Returns:
      a copy with that minimum and this configuration's maximum
      Throws:
      IllegalArgumentException - when it would be above a maximum already set

    • maxSize

      public WindowConfig maxSize(int width, int height)
      A copy the user cannot make larger than width×height; see minSize(int, int).
      Parameters:
      width - the widest, in logical points; 0 leaves the width open
      height - the tallest; 0 leaves the height open
      Returns:
      a copy with that maximum and this configuration's minimum
      Throws:
      IllegalArgumentException - when it would be below a minimum already set

    • title

      public WindowConfig title(String newTitle)
      Parameters:
      newTitle - title bar text, and what a window without one is called where the platform names windows (an accessibility tree, a window list)
      Returns:
      a copy with that title
      Throws:
      NullPointerException - if newTitle is null

    • visible

      public WindowConfig visible(boolean newVisible)
      Returns:
      a copy that starts shown or hidden

    • resizable

      public WindowConfig resizable(boolean newResizable)
      Returns:
      a copy the user may, or may not, resize

    • decorated

      public WindowConfig decorated(boolean newDecorated)
      Returns:
      a copy with, or without, the native title bar and border

    • floating

      public WindowConfig floating(boolean newFloating)
      Returns:
      a copy that stays, or does not stay, above other windows

    • transparent

      public WindowConfig transparent(boolean newTransparent)
      Returns:
      a copy with a transparent, or opaque, framebuffer

    • focusOnShow

      public WindowConfig focusOnShow(boolean newFocusOnShow)
      Returns:
      a copy that does, or does not, take the input focus when shown

    • at

      public WindowConfig at(int x, int y)
      A copy created at a given point in native screen coordinates, rather than wherever the desktop decides.

      Placing a window after it exists is NativeWindow.setScreenPosition(int, int) and has always been possible; this is the same thing one step earlier, and the step matters for exactly one reason: a window's content scale is the scale of the monitor it is created on. A window that lands somewhere the caller did not choose is a window whose framebuffer is a size the caller did not choose, and no arithmetic afterwards can undo that — it has to be right at construction. Everything else about placement is cosmetic and belongs to the desktop.

      Not every desktop allows it: see WindowPeer.supportsAbsolutePositioning(). Where it does not, the request is ignored and the window opens where the compositor puts it, which is the same outcome as never asking.

      Parameters:
      x - native screen x, or ANY_POSITION to hand the choice back
      y - native screen y
      Returns:
      a copy carrying the position

    • on

      public WindowConfig on(@Nullable Display display)
      A copy created on a chosen Display, at the origin of its work area.

      The intent-revealing form of at(int, int), and the one worth reaching for: what a caller who cares almost always means is this monitor, because that is what fixes the content scale. A capture harness that must produce the same pixels on a laptop with three monitors as on a runner with one asks for the primary display and stops caring which machine it is.

      Parameters:
      display - the monitor to open on; null (a headless backend's answer) leaves the placement to the desktop, so a caller need not branch
      Returns:
      a copy anchored to that display, or this when there is none

    • ownedBy

      public WindowConfig ownedBy(NativeWindow owner)
      A copy owned by owner: a window in its own right that closes when the owner closes and moves when it moves, and that a modal over the owner blocks like any other window. A non-modal dialog, a floating palette, a video opened from a document. Given at creation, so a platform that makes a child window from its parent has it then.
      Parameters:
      owner - the window this one belongs to
      Returns:
      a copy owned by it
      Throws:
      NullPointerException - if owner is null

    • atInOwner

      public WindowConfig atInOwner(float x, float y)
      A copy created with its top-left corner at a point of its owner's content area, in the owner's logical points: the way a popup is placed against the widget that opened it. The point may lie outside the owner, as a list dropping below the window's bottom edge does. The backend turns it into the platform's position, relative where the platform places a child against its parent, as Wayland does.
      Parameters:
      x - left edge, in the owner's logical points from its content area's left
      y - top edge, in the owner's logical points from its content area's top
      Returns:
      a copy carrying the position
      Throws:
      IllegalStateException - if this configuration has no owner
      IllegalArgumentException - if a coordinate is NaN or infinite

    • owner

      public @Nullable NativeWindow owner()
      Returns:
      the window this one belongs to, or null for a window of the application's own

    • isPopup

      public boolean isPopup()
      Returns:
      whether this is its owner's content drawn outside its frame (popup(limn.backend.NativeWindow, int, int)), rather than a window in its own right that the owner merely owns (ownedBy(limn.backend.NativeWindow))

    • hasPositionInOwner

      public boolean hasPositionInOwner()
      Returns:
      whether atInOwner(float, float) placed it; ownerX() and ownerY() answer then

    • ownerX

      public float ownerX()
      Returns:
      the left edge in the owner's logical points, or NaN when atInOwner(float, float) was not given

    • ownerY

      public float ownerY()
      Returns:
      the top edge in the owner's logical points, or NaN when atInOwner(float, float) was not given

    • equals

      public boolean equals(@Nullable Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object