QuickOpen picker
The picker for every “choose one from a list” moment: recent files, themes, keymaps, a setting’s values, a branch to compare with. It is the Command Palette card with a title over the field and a prompt in it, so a list choice is made the way a command is run: type a few letters, Enter. The keyboard page states the rule; this page is the shape.
- QOPEN-01 SHOULD One picker serves every list choice: recent files, themes, keymaps, a setting’s values, a
branch to compare with.
- Check (code): those choices are instances of one generic picker class; there is no second list-picker class or
ChoiceDialogfor them. - Reference: Editora
ui/QuickOpen.java(one generic class, instantiated more than seventy times), driven byPickerKeys.
- Check (code): those choices are instances of one generic picker class; there is no second list-picker class or
- QOPEN-02 SHOULD The picker is the palette’s card in the shared in-scene overlay host, with a title naming the
command over the field and a prompt in the field; never a
javafx.stage.Popup.- Check (code): the picker shows its card through the overlay host and sets a title and a prompt text.
- Reference: Editora
QuickOpen.setOverlayHost,ui/OverlayHost.java; the Spec table below.
Anatomy
Section titled “Anatomy”- 1Title. The command that opened the picker ("Jump to Recent File", "Set App Theme"), bold 12 px in the muted color. This is what tells the picker apart from the palette, which has no title.
- 2Query field with a prompt per picker: "Type to filter recent files…", "Type to filter themes…". The Emacs caret keys work in it (
TextInputKeymap.installShared). - 3Match highlight. The characters the fuzzy matcher scored, bold in the accent color; the same
MatchText.runsas the palette, so the highlight and the rank never disagree. - 4Selected row. The first match, or with nothing typed the value in force when the picker knows it (
setCurrentItem), so a settings picker opens on the current value. - 5Detail, right-aligned and muted: the file's folder, a branch's upstream, "current". It gives way with an ellipsis; the title keeps its width and never wraps.
- 6Icon (optional,
setItemIcon): a file-type glyph fromFileIcons. A per-row class marks state (an unsaved buffer in amber). - 7Key legend. "↵ select" plus any row action's key, rebuilt from the active keymap on every showing.
| Property | Value | Reference |
|---|---|---|
| Kind | The palette’s card in the shared in-scene OverlayHost, over the same scrim; never a javafx.stage.Popup | QuickOpen.setOverlayHost, OverlayHost |
| Width | 620 px; a picker may ask for its own width and a minimum number of rows (a registry browser with one entry still gets a roomy box) | DEFAULT_WIDTH, setPreferredSize |
| Rows | 26 px fixed cells; the list hugs its match count, at least 1 row, 12 before it scrolls | CELL_HEIGHT, MAX_VISIBLE, resizeList |
| Title | Bold 12 px, -color-fg-muted, over the field | .command-palette .palette-title |
| Row | Title as matched runs, an optional icon before it, the detail in the palette’s muted right-detail style | ItemCell, .keybinding |
| Legend | 11 px muted under the list | .command-palette .palette-hint |
| Card | -color-bg-overlay, radius 12, 1 px -color-border-default, padding 6: the palette’s | .command-palette |
| Ranking | FuzzyMatch over the search key (the label unless the picker names another, a note’s body for instance); equal scores keep the supplier’s order | filter |
Behavior
Section titled “Behavior”- QOPEN-03 SHOULD The items are read fresh on every showing and snapshotted, so typing filters a stable list. A
source that answers late (an outline the language server has not returned yet) calls
reload().- Check (code):
showcalls the items supplier;reloadre-reads it and keeps the query. - Reference: Editora
QuickOpen.show,QuickOpen.reload.
- Check (code):
- QOPEN-04 SHOULD With nothing typed the list keeps the supplier’s own order (recency for recent files, document
order for symbols), with the current value pre-selected when there is one.
- Check (code): the empty query passes the items through unsorted and selects the
setCurrentItemvalue. - Reference: Editora
QuickOpen.filter,setCurrentItem.
- Check (code): the empty query passes the items through unsorted and selects the
- QOPEN-05 SHOULD Typing ranks by fuzzy score, and ties keep the supplier’s order, so rows do not shuffle under
the cursor between keystrokes.
- Check (code): the sort’s last tiebreak is the supplier’s index.
- Reference: Editora
QuickOpen.filter.
- QOPEN-06 SHOULD The active keymap’s line and page chords (
nav.lineDown,nav.pageUp, …) move the selection, as do ↑ ↓, Page Up/Down andCtrl+Home/Ctrl+End(Cmdon macOS), which always work; plain Home and End stay with the field’s caret. Enter or a click on a row chooses; the card hides first, then the choice runs, so focus is already back where it belongs.- Check (code): the accept path hides the card before it calls the choice handler.
- Reference: Editora
QuickOpen(hide()thenonChoose),PickerKeys.resolve.
- QOPEN-07 SHOULD Esc,
C-gor a click on the scrim cancels, and the host restores focus. A picker that previewed something undoes it.- Check (test): a test previews a row, dismisses the picker and finds the preview undone.
- Reference: Editora
OverlayHost(previousFocus),QuickOpenPreviewFxTest(dismissingRestoresWhatWasPreviewed).
- QOPEN-08 MAY A picker previews the highlighted row as the selection moves and undoes the preview on cancel
(Recent Locations shows each place and returns to the origin on Esc). A preview without an undo is worse than none,
and nothing is previewed for the row the picker opens on, only for one the user moved to. The theme and keymap
pickers do not preview; they apply on Enter.
- Check (test): opening previews nothing, moving previews, choosing does not restore.
- Reference: Editora
QuickOpen.setPreview(onPreview, onCancelled),QuickOpenPreviewFxTest.
- QOPEN-09 MAY A row action acts on the highlighted row and keeps the picker open (the breakpoints picker
enables or removes one), re-reading the list afterwards and keeping the cursor in place.
- Check (test): a row action runs on the highlighted row and the picker stays up.
- Reference: Editora
QuickOpen.addRowAction(key, legend, action),QuickOpenPreviewFxTest(aRowActionActsOnTheHighlightedRowAndKeepsThePickerOpen).
- QOPEN-10 SHOULD A picker that can open on an empty list shows a placeholder sentence in it, never a blank
card. A picker with nothing to offer may instead say so in the status line and not open.
- Check (code): each picker whose source can be empty either calls
setPlaceholderor returns beforeshowwith a status message. - Reference: Editora
QuickOpen.setPlaceholder(BreakpointsPicker);NavigationCoordinator(status.nav.noRecentLocations).
- Check (code): each picker whose source can be empty either calls
- QOPEN-11 SHOULD The host shows one card at a time; opening a picker replaces whatever card was up.
- Check (code): the host’s
showremoves the previous card before it adds the new one, and keeps the original focus owner. - Reference: Editora
OverlayHost.show.
- Check (code): the host’s
- QOPEN-12 SHOULD The picker’s relatives move, accept and cancel with the same keys as the picker.
- Check (code): each relative maps its keys through
PickerKeys. - Reference: Editora
Switcher,FileFinder,MultiSelectPicker,BranchPopup,GitStashPopup.
- Check (code): each relative maps its keys through
The relatives: the Open Files Switcher lists tabs in tab order, opens on the current one and closes a file with
C-d or Backspace. FileFinder is the Emacs find-file field with Tab completion. MultiSelectPicker ticks several
rows with Space where exactly one would be wrong. BranchPopup and GitStashPopup are sectioned pickers with their
own actions.
| App | Picked with it | Reference |
|---|---|---|
| Recent files (with file icons), recent locations (previewed), bookmarks, the structure outline, tool windows, open files, projects, keymap, app and editor theme, spell language, a setting’s values (opened on the current value), branches, tags and commits to compare with, remotes, commit message history, the kill ring, Occur lines, external tools, macros, the debug main class, breakpoints, agent models | NavigationCoordinator, EditorSettingsCoordinator, DiffCoordinator, DebugCoordinator, BreakpointsPicker | |
| Go to bookmark…, Open recent folder…: the palette shown over a list of names with a detail per row and an “open” legend | CommandPalette.Choices, ViewerWindow | |
| Termina, Torrenta, Modula, nux | Commands only; profiles and other lists are menus or combo boxes today | CommandPalette in each |
| Key | English |
|---|---|
nav.recentFiles.title / .prompt | Jump to Recent File / Type to filter recent files… |
palette.theme.appTitle, palette.theme.editorTitle / palette.theme.prompt | Set App Theme, Set Editor Theme / Type to filter themes… |
command.keymap.select / palette.keymap.prompt | Keymap: Select… / Type to filter keymaps… |
palette.setting.pick | Type to filter… |
pickerKeys.select, pickerKeys.open, pickerKeys.cancel | {0} select, {0} open, {0} cancel |
switcher.header | Open Files |
A title names the command; a prompt starts with “Type to filter” and ends with an ellipsis. A placeholder says what is missing and what to do (“No breakpoints set. Click a line number to add one.”).
In the apps
Section titled “In the apps”

Pauta 2.0.2 · · Changelog · This page in the latest edition