Package limn.components

@NullMarked 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 reaches the watchers and not the handler. onSelect is the application's response to the user choosing, and it runs only for a click, a key or an assistive technology's select; a setSelectedIndex from code announces SELECTION/CODE to whoever watches the widget, and to nobody else. A detail pane that must follow the selection wherever it came from watches; a pane that answers the user handles. That is the one rule of Change.Origin, and it is why two of these controls bound to each other through their handlers cannot recurse at all.
• Setting the index that is already selected changes nothing and announces nothing. The guard is on the announcement: a mutator handed the state it already holds says nothing, which is what ends a two-way binding written on the watcher channel on its first echo.

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.date	Dates and times: a field that types one, a grid that shows a month, and the picker that is both.
limn.components.table	A table: columns over a list the application owns, virtualized on both axes.
limn.components.tree	The tree: an outline over children the application provides.

Class	Description
Accelerator	A keyboard shortcut for a MenuItem: one key plus the modifier mask that must be held with it.
Avatar	A person, drawn as a circle: their picture when there is one, and otherwise their initials over a colour of their own.
AvatarGroup	People drawn as a stack of Avatars: the approvers of a document, the members of a team.
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.
Badge	A short status beside or inside something else: "Overdue" in a table's cell, "3" beside an inbox, a dot beside a row's name that says it is unread.
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.
Button.Style	How much a button asks to be pressed, of the three looks a row of buttons is drawn in.
ButtonGroup	Coordinates a set of RadioButtons so that exactly one is selected at a time.
Card	A card: a surface that holds one record, made of parts that are each optional.
Card.MediaFit	How the media is laid out.
Card.Orientation	Where the media goes.
Card.Style	How the card is set apart from what is around it.
Checkbox	Toggle with two visual variants: the classic BOX with a check mark, and the mobile-style SWITCH whose thumb slides.
Checkbox.Variant	How the flag is drawn and published: a box that takes a check mark, or a switch whose knob slides.
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<T>	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.
Dialog.CancelRequest	One question to a dialog's Dialog.onCancel handler: may the dialog close with its cancel result? Answered once, with Dialog.CancelRequest.allow() or Dialog.CancelRequest.refuse(), now or later: a handler that shows a dialog of its own over this one keeps the request and answers from that dialog's result.
Dialog.CancelRequest.Reason	How the user closed the dialog.
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.
Elevation	How far a surface is lifted above what is around it.
ElevationShadow	The shadow of one Elevation in a theme: two layers straight down, since the light is above.
Expander	A section that opens and closes: a header over content that slides out below it.
ExpanderGroup	Keeps at most one of several Expanders open, an accordion: opening one closes the one that was open.
Field	A field of a form around one control: a caption above it, a line under it, and the two states a form has, required and invalid.
ImageView	Displays an Image: a full-color picture, or a monochrome/mask icon when a tint is set.
ImageView.Fit	How the picture is sized into the view's box.
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	What happens to text that does not fit: cut at the box's edge, or ended with an ellipsis.
Label.Role	Which typographic token the text is drawn with, orthogonal to the size step, which decides how big that token is.
Label.VAlign	Where the lines sit vertically in the text region.
ListView<T>	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.DropHandler	Something was dropped between two rows of this list.
ListView.Reorder<T>	Rows of this list were dragged to another place in it.
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).
MenuBar.Placement	Where a bar is shown.
MenuItem	One entry in a Menu: a command, a checkable toggle, a submenu, or a separator.
MenuItem.Role	What an item is to the system, beyond its label: one of the three every application has and a system may keep in a menu of its own, or one of the six editing commands.
PasswordField	TextField that renders every character as a mask dot, with an optional reveal toggle.
Popover	A panel of controls that hangs from a widget and closes when it is done with: a filter panel from a tool bar's button, a column chooser, a short form.
Popover.Alignment	Which edge of the anchor the panel lines up with.
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.
RangeSlider	A horizontal slider of two thumbs that selects a range in [min, max]: a lower value and an upper one over the same track, the span between them filled.
RangeSlider.RangeListener	What hears the range the user set.
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 offset by the scroll position and clipped to the viewport on those axes; the wheel scrolls whenever there is overflow, and so does a pointer drag that rests near one of its edges, or goes past one (see ScrollBar).
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.
SelectionMode	How many rows a list-shaped widget lets the user select: the one vocabulary of ListView, Table and Tree.
Separator	A thin divider line drawn in the theme's Theme.outline color.
Separator.Orientation	Which way the line runs.
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.
Surface	A surface lifted above what is around it: a fill, the shadow its Elevation has in the theme, and one child inside.
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.
TabbedPane.TabCloseRequest	One question to TabbedPane.onTabClose: may this tab close? Answered once, with TabbedPane.TabCloseRequest.allow() or TabbedPane.TabCloseRequest.refuse(), now or later: a handler that shows a dialog keeps the request and answers from its result.
TabbedPane.TabMoveListener	What the user moved: a tab from one place in the order to another.
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.
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.
Tone	Which of the palette's colours a piece of text or a mark is drawn in, said by what it means rather than by the colour: a line that reports a failure is Tone.DANGER, whatever red the palette in force calls danger.
ToolBar	A horizontal strip of controls (buttons, toggles, segmented controls, Separators…) on a rounded Theme.surface background.
Validation	What an application has decided about the value a control holds: nothing yet, wrong, doubtful, accepted, or worth a note.
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.