Record Class BrowserToolkitInfo

java.lang.Object
java.lang.Record
vaadinx.awt.BrowserToolkitInfo
public record BrowserToolkitInfo(int viewportWidth, int viewportHeight, double devicePixelRatio, boolean mac) extends Record
Per-UI snapshot of the browser's client-specific display facts that Toolkit's screen accessors need but a headless server JVM cannot supply: the viewport size, device-pixel ratio, and whether the client is a Mac / iOS device (used to choose the menu-shortcut modifier — META on macOS / iOS, CTRL elsewhere).

Viewport, not physical screen (D_toolkit_screen_size). viewportWidth() / viewportHeight() carry the browser window's inner size (window.innerWidth/Height via ExtendedClientDetails.getWindowInnerWidth()), not the monitor's screen.width/height. The coordinate space our windows place in (Window.setLocation/setBounds → Dialog overlay top/left) is the viewport, so every migrated screen-math idiom — centering, edge-anchored toasts, size-to-fraction-of-screen — only computes correctly against the viewport. Physical monitor size has no placement use in a browser.

Sourced from Vaadin's ExtendedClientDetails — the same client-details channel BrowserTimeZone uses, not a bespoke executeJs. get() reads the cached ExtendedClientDetails synchronously when it is already populated (which it is in any app that wired BrowserTimeZone.fetch() at UI init — the migration guide requires it for dates), so the screen accessors work on any thread, including at frame-construction time on the Vaadin request thread. When the details have not yet been fetched, it parks the calling virtual thread on a refresh round-trip (the WebClipboard VT-park pattern). See D_toolkit_full_surface, D_toolkit_from_client_details.

Live resize tracking (D_toolkit_screen_size). The viewport changes when the user resizes the browser window, so the first cache(UI, BrowserToolkitInfo) for a UI also registers a browser-window resize listener; each resize event replaces the cached snapshot's viewport (dpr / mac carry over) via onBrowserResize(UI, int, int). The registration dies with the UI — no teardown needed. Bounded staleness: resizes between page load and the first get() aren't tracked (no listener yet, and Vaadin doesn't auto-refresh ExtendedClientDetails), so the first read reports load-time values — self-heals from the first read onward, and no UI-init step is required, per D_toolkit_from_client_details.

Cache only real values. A populated/fetched (or test-injected) snapshot is cached per-UI via ComponentUtil.setData(Component, SerializableTriConsumer, T, U); the fallback returned when the browser details are unavailable is never cached, so a later call with details available upgrades to the real value.

Quiet fallback. When the details are neither populated nor fetchable (no current UI, or the caller is off a virtual-thread carrier and the browser has not reported in yet), get() returns DEFAULT and logs at debug — deliberately not EHelper.onUnimplemented(String, String, Object...): screen metrics are implemented, so the default is a graceful not-yet-known degrade (R_best_effort_behaviour/R_layouts_close_enough), and a WARN on a normal construction path would trip the zero-stub-WARN exit gates.

macOS detection is iOS/iPadOS only. mac() is read off navigator.platform the way Vaadin's isIOS() (deprecated in 25.3) did: iPhone / iPod / iPad, or MacIntel with a touch screen (iPadOS reports itself as a Mac). Desktop Mac clients (MacIntel, no touch) fall to CTRL for the menu-shortcut modifier. Accepted limitation (R_best_effort_behaviour/R_layouts_close_enough) — the accelerator modifier is cosmetic; revisit if a migration target needs Cmd accelerators on desktop Mac.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final BrowserToolkitInfo
    DEFAULT
    Fallback returned when the browser details are unavailable.

  • Constructor Summary

    Constructors
    Constructor
    Description
    BrowserToolkitInfo(int viewportWidth, int viewportHeight, double devicePixelRatio, boolean mac)
    Creates an instance of a BrowserToolkitInfo record class.

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    clearCache()
    Drop any cached snapshot for the current UI (test convenience).
    double
    devicePixelRatio()
    Returns the value of the devicePixelRatio record component.
    final boolean
    equals(Object o)
    Indicates whether some other object is "equal to" this one.
    static BrowserToolkitInfo
    get()
    The current UI's browser display snapshot.
    final int
    hashCode()
    Returns a hash code value for this object.
    boolean
    mac()
    Returns the value of the mac record component.
    static void
    setTestInfo(int viewportWidth, int viewportHeight, double devicePixelRatio, boolean mac)
    Inject a deterministic snapshot for the current UI, bypassing the browser round-trip.
    final String
    toString()
    Returns a string representation of this record class.
    int
    viewportHeight()
    Returns the value of the viewportHeight record component.
    int
    viewportWidth()
    Returns the value of the viewportWidth record component.

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • DEFAULT

      public static final BrowserToolkitInfo DEFAULT
      Fallback returned when the browser details are unavailable. A common desktop-viewport ballpark at DPR 1.0, non-Mac (mac() false → the menu shortcut defaults to CTRL).

  • Constructor Details

    • BrowserToolkitInfo

      public BrowserToolkitInfo(int viewportWidth, int viewportHeight, double devicePixelRatio, boolean mac)
      Creates an instance of a BrowserToolkitInfo record class.
      Parameters:
      viewportWidth - the value for the viewportWidth record component
      viewportHeight - the value for the viewportHeight record component
      devicePixelRatio - the value for the devicePixelRatio record component
      mac - the value for the mac record component

  • Method Details

    • get

      public static BrowserToolkitInfo get()
      The current UI's browser display snapshot. Returns the cached value if present; else derives it synchronously from an already-populated ExtendedClientDetails; else, on a virtual-thread carrier, fetches the details (parking the VT) and caches the result; else returns DEFAULT (uncached, debug-logged).

    • setTestInfo

      public static void setTestInfo(int viewportWidth, int viewportHeight, double devicePixelRatio, boolean mac)
      Inject a deterministic snapshot for the current UI, bypassing the browser round-trip. Used by tests; also usable by a host app that already knows the client's display facts. Does NOT install the resize listener — injected snapshots stay exactly as injected until the next injection or clearCache().

    • clearCache

      public static void clearCache()
      Drop any cached snapshot for the current UI (test convenience).

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with the compare method from their corresponding wrapper classes.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • viewportWidth

      public int viewportWidth()
      Returns the value of the viewportWidth record component.
      Returns:
      the value of the viewportWidth record component

    • viewportHeight

      public int viewportHeight()
      Returns the value of the viewportHeight record component.
      Returns:
      the value of the viewportHeight record component

    • devicePixelRatio

      public double devicePixelRatio()
      Returns the value of the devicePixelRatio record component.
      Returns:
      the value of the devicePixelRatio record component

    • mac

      public boolean mac()
      Returns the value of the mac record component.
      Returns:
      the value of the mac record component