Package limn.components

package limn.components

Ready-to-use components (Label, Button, TextField, Checkbox/Switch, Dialog) and the light/dark Theme.

The discrete-choice widgets answer setSelectedIndex the same way

ListView, TabbedPane, ComboBox, SegmentedControl and ButtonGroup spell one operation with one name, and it means one thing in all five.

• An out-of-range index throws IndexOutOfBoundsException, exactly as List.get does and for the same reason: an index computed from a search that found nothing, a filter that emptied the data, or a value restored from saved state is a caller's bug, and clamping it selects the wrong thing quietly. A caller holding a computed index checks it against the count first.
• -1 is not an argument. Where "nothing is selected" is a real state (a list of records need not have a current record), a clearSelection() names it: ListView and ButtonGroup have one. A TabbedPane holding tabs, a ComboBox and a SegmentedControl always have exactly one selection and so offer none.
• A programmatic set fires the change listener, the same one a click fires. A listener describes the selection, not the mouse, so a detail pane bound to it stays right without knowing where the change came from.
• Setting the index that is already selected changes nothing and fires nothing. That early return is load-bearing, not an optimization. A single UI thread rules out two concurrent entries, never two nested ones: widget A's listener writing widget B, whose listener writes A back, recurses on one stack until it overflows. The bounce dies on the first return instead, which is the whole reason a two-way binding between two of these controls terminates. Do not delete the guard as redundant with the thread rule.

Keyboard traversal is not bound by the first rule: arrowing past either end of a strip lands on the end, because that is what the key means, not what an index means.

Related Packages

Package	Description
limn.components.chart	Charts: BarChart, LineChart and DonutChart, over a shared Chart that carries the data, the palette, the legend, the tooltip, the click callback and the animation.
limn.components.text	The headless editing engine behind the text components: TextEditModel owns the buffer, the caret, the anchor-based selection, line movement with a sticky goal column and bounded undo/redo, stepping by grapheme cluster so combining marks and ZWJ emoji are never split.

Class	Description
Accelerator	A keyboard shortcut for a MenuItem: one key plus the modifier mask that must be held with it.
BackdropPanel	A panel whose background is the content behind it, put through a BackdropEffect: a glass control bar over video, a washed header over a picture, a redacted field.
Button	Push button with the full state set (normal, hover, pressed, disabled, focused) and an Button.onAction(Runnable) fired by click or by Enter/Space while focused.
ButtonGroup	Coordinates a set of RadioButtons so that exactly one is selected at a time.
Checkbox	Toggle with two visual variants: the classic BOX with a check mark, and the mobile-style SWITCH whose thumb slides.
Checkbox.Variant
ColorPicker	Picks a colour the way a graphics application does: a saturation/value field for the current hue, a hue ramp beside it, a before/after swatch, a hex field, and numeric channels in whichever model the user thinks in: RGB, HSV or CMYK.
ColorPicker.Format	Which numeric model the channel row is showing.
ColorPickerButton	A colour, shown as a chip, that opens a ColorPicker in a dialog when clicked: the control an application reaches for when it needs a colour from the user but cannot give up a panel to a whole picker.
ComboBox	Dropdown selector.
ContextMenus	Gives any widget a context menu, and answers what a request for one looks like.
Dialog	A modal (or non-modal) dialog that resolves a CompletionStage with the chosen button's result: never a nested event loop, so show* returns immediately and the stage completes (on the UI thread) later.
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.
ImageView	Displays an Image: a full-color picture, or a monochrome/mask icon when a tint is set (the image's alpha becomes the shape, recolored by the tint, so an icon follows the theme).
ImageView.Fit
Label	Single- or multi-line text.
Label.HAlign	Where a line sits in the text region, on two vocabularies that coexist on purpose.
Label.Overflow
Label.Role	Which typographic token the text is drawn with, orthogonal to the size step, which decides how big that token is.
Label.VAlign
ListView	A vertically scrolling list that virtualizes its rows like a JTable/RecyclerView: only the rows in the viewport get a widget, so a list of a million rows costs the same as one of twenty (layout and paint are O(visible)).
ListView.Adapter	Supplies and (optionally) caches the row widgets of a ListView.
MediaControls	Playback controls for a VideoView: play/pause, a scrub bar and a position clock — the bar every player lays over its picture.
MediaControls.Sound	Whether the mute button and volume slider are offered.
Menu	An ordered list of MenuItems: the reusable content of a PopupMenu (context menu / dropdown), a MenuBar top-level entry, or a submenu.
MenuBar	A horizontal strip of top-level menu titles; the strip itself is drawn in-scene (part of the window chrome).
MenuItem	One entry in a Menu: a command, a checkable toggle, a submenu, or a separator.
PasswordField	TextField that renders every character as a mask dot, with an optional reveal toggle.
PopupMenu	A context menu / dropdown that presents a Menu (with checkable items, separators and cascading submenus) as a real native window: an undecorated, floating, transparent OS window (like a ComboBox popup) that may overflow the owner window exactly like a true OS menu.
ProgressBar	Simple horizontal progress bar.
RadioButton	A single-choice control: a ring that fills with a dot when selected.
ScrollBar	The one scrollbar shared by every scrollable component (ListView, TextArea, ScrollView, …), so they look and behave identically.
ScrollBar.Model	The scroll state the bar reflects and drives.
ScrollBar.Orientation	Which axis the bar controls.
ScrollBar.Policy	When the bar is shown.
ScrollGutters	How much of a scrolling widget's box its scrollbars take, and the settling that decides it.
ScrollGutters.Content	How the content is measured for a candidate viewport.
ScrollGutters.Layout	Whether a bar floats over the content or takes a strip out of it.
ScrollView	Generic scroll container: the child is measured unbounded on the scrolling axes, painted clipped to the viewport and offset by the scroll position; the wheel scrolls whenever there is overflow.
SearchField	A TextField preset for search: a leading magnifier icon inside the field and a trailing coupled clear button (the ComboBox-caret idiom).
SegmentedControl	A row of connected segments with a single selection, a compact alternative to a RadioButton group or tabs.
Separator	A thin divider line drawn in the theme's Theme.outline color.
Separator.Orientation
SizeTokens	The numeric size table: one immutable row per ControlSize step.
Slider	Horizontal slider selecting a value in [min, max].
Spinner	A stepper input for a bounded value, in two modes: Spinner.Mode.NUMERIC: new Spinner(min, max, step) shows a number (decimals inferred from the step); Spinner.Mode.TIME: Spinner.time() shows HH:MM, where the up/down arrows adjust the focused field (hours by 60, minutes by the step) and Left/Right (or a click) move between the two fields.
Spinner.Mode	Numeric value vs.
SplitPane	Two panes and a divider the user drags to share the space between them.
SplitPane.Orientation	Which axis the two panes are arranged along.
Strokes	Quantities that are pixel-locked: identical at every ControlSize step.
TabbedPane	Tabbed panel: a horizontal strip of tab headers over a content area that shows the selected tab.
TabbedPane.TabAlignment	Where the strip sits when the headers are narrower than the pane, named for where it lands in an interface that reads left to right.
TextArea	Multiline text editor: hard line breaks (Enter), arrow navigation across lines with a sticky column, mouse/Shift+arrow selection spanning lines, clipboard shortcuts, blinking cursor, and both scrollbars: draggable thumbs and wheel-responsive.
TextField	Single-line text input: blinking cursor (frame-clock ticker), mouse and Shift+arrow selection, Home/End, Ctrl/Cmd+A/C/V/X through the system clipboard, placeholder, and horizontal scrolling that keeps the cursor visible when the text overflows.
TextField.Validation	Validation state; colors the border (and a caller-supplied message).
Theme	Central design tokens: colors, corner radii, typography and spacing.
Theme.Builder	Collects the colours of a palette and builds one.
Theme.Token	Every colour a palette is made of, as values, so that code which has to treat every tone alike (a serializer, an editor, a contrast report) enumerates them instead of naming them all and getting all but one right.
ThemeFormat	A palette as text, and back, so an application can ship a theme its designer built as a file beside the jar instead of as a recompile.
TokenBox	A SizedBox whose fixed dimensions come from the resolved ControlSize step instead of from a number baked at construction.
TokenBox.Extent	One extent, read off a size step.
TokenColumn	A Column whose gap follows the resolved ControlSize step.
TokenPadding	A Padding whose insets follow the resolved ControlSize step, uniform on all four edges.
TokenRow	A Row whose gap follows the resolved ControlSize step.
Tokens	Pushes resolved SizeTokens spacing into the geometry-only containers, which hold plain floats and therefore cannot follow a size step on their own.
Tokens.Role	Which of the three spacing tokens a container follows.
ToolBar	A horizontal strip of controls (buttons, toggles, segmented controls, Separators…) on a rounded Theme.surface background.
VideoView	Shows the pictures of a VideoStreamSource: each one handed to a device-side picture and composited as one quad in the 2D paint order, so clipping, opacity, overlays and dialogs apply to a video exactly as they apply to a rectangle.
VideoView.Fit	How a picture whose aspect ratio differs from the box's is mapped into it.
Viewport3D	A viewport that renders 3D content into an offscreen RenderTarget (with MSAA) and composites it as a normal 2D layer, proving that GPU-rendered content respects the scene's layering: overlays, dialogs, tooltips and clipping all apply to it because it draws as one quad in the paint order.
Viewport3D.Renderer	Draws the 3D scene into a pass each frame; timeSeconds advances while showing.