Package limn.components

Enum Class DisplayMode

java.lang.Object
java.lang.Enum<DisplayMode>
limn.components.DisplayMode
All Implemented Interfaces:
Serializable, Comparable<DisplayMode>, Constable
public enum DisplayMode extends Enum<DisplayMode>
Where a surface that floats above the page is actually drawn: in a window of its own, or as an overlay inside the window that owns it. Dialog, PopupMenu, ComboBox and ColorPickerButton all answer this question, and they answer it the same way.

It is a preference, never a guarantee. Two platforms cannot hold one of these in a window of its own, and on them NATIVE_WINDOW is not available at all:

  • Wayland, where a client cannot place a toplevel at an anchor. A menu window would open near the middle of the display wearing whatever frame the compositor puts on toplevels, which is worse than any overlay. See ADR 028.
  • macOS exclusive fullscreen, where a second window taking focus minimizes the fullscreen owner.

So a surface asked for NATIVE_WINDOW may be drawn in-scene anyway, and each of the four types has a displayMode() that answers what actually happened rather than what was requested. Code that branches on presentation must read that one; code that reads back the setter is reading its own wish.

Why it is worth choosing rather than inheriting. An in-scene surface is contained by the window: it cannot extend past the edge, it composites with what is behind it, and a screenshot of the window contains it. A native one is none of those things, and the last point is not only a testing convenience: anything that records, streams or captures a window records a native popup as absent. An application that documents itself with screenshots, or one whose window is deliberately the whole of its presentation, wants IN_SCENE on purpose and on every platform, not only where the platform forces it.

  • Enum Constant Details

    • NATIVE_WINDOW

      public static final DisplayMode NATIVE_WINDOW
      A separate window, positioned against the anchor. The default everywhere it is possible, because it is what the platform's own menus and dialogs do: it can extend past the owner's edge, and the compositor gives it the shadow and the stacking every other application gets.

    • IN_SCENE

      public static final DisplayMode IN_SCENE
      An overlay drawn inside the owner's window. Always available, on every platform, and the only presentation on the two that cannot position a window at an anchor.

  • Method Details

    • values

      public static DisplayMode[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static DisplayMode valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null