Skip to content
Pauta4.1.0

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 ChoiceDialog for them.
    • Reference: Editora ui/QuickOpen.java (one generic class, instantiated more than seventy times), driven by PickerKeys.
  • 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.
  1. 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.
  2. 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).
  3. 3Match highlight. The characters the fuzzy matcher scored, bold in the accent color; the same MatchText.runs as the palette, so the highlight and the rank never disagree.
  4. 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.
  5. 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.
  6. 6Icon (optional, setItemIcon): a file-type glyph from FileIcons. A per-row class marks state (an unsaved buffer in amber).
  7. 7Key legend. "↵ select" plus any row action's key, rebuilt from the active keymap on every showing.
PropertyValueReference
KindThe palette’s card in the shared in-scene OverlayHost, over the same scrim; never a javafx.stage.PopupQuickOpen.setOverlayHost, OverlayHost
Width620 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
Rows26 px fixed cells; the list hugs its match count, at least 1 row, 12 before it scrollsCELL_HEIGHT, MAX_VISIBLE, resizeList
TitleBold 12 px, -color-fg-muted, over the field.command-palette .palette-title
RowTitle as matched runs, an optional icon before it, the detail in the palette’s muted right-detail styleItemCell, .keybinding
Legend11 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
RankingFuzzyMatch over the search key (the label unless the picker names another, a note’s body for instance); equal scores keep the supplier’s orderfilter
  • 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().
  • 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 setCurrentItem value.
    • Reference: Editora QuickOpen.filter, setCurrentItem.
  • 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 and Ctrl+Home/Ctrl+End (Cmd on 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() then onChoose), PickerKeys.resolve.
  • QOPEN-07 SHOULD Esc, C-g or 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.
  • 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.
  • 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.
  • QOPEN-11 SHOULD The host shows one card at a time; opening a picker replaces whatever card was up.
    • Check (code): the host’s show removes the previous card before it adds the new one, and keeps the original focus owner.
    • Reference: Editora OverlayHost.show.
  • QOPEN-12 SHOULD The picker’s relatives move, accept and cancel with the same keys as the picker.

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.

AppPicked with itReference
EditoraRecent 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 modelsNavigationCoordinator, EditorSettingsCoordinator, DiffCoordinator, DebugCoordinator, BreakpointsPicker
MiradaGo to bookmark…, Open recent folder…: the palette shown over a list of names with a detail per row and an “open” legendCommandPalette.Choices, ViewerWindow
Termina, Torrenta, Modula, nuxCommands only; profiles and other lists are menus or combo boxes todayCommandPalette in each
KeyEnglish
nav.recentFiles.title / .promptJump to Recent File / Type to filter recent files…
palette.theme.appTitle, palette.theme.editorTitle / palette.theme.promptSet App Theme, Set Editor Theme / Type to filter themes…
command.keymap.select / palette.keymap.promptKeymap: Select… / Type to filter keymaps…
palette.setting.pickType to filter…
pickerKeys.select, pickerKeys.open, pickerKeys.cancel{0} select, {0} open, {0} cancel
switcher.headerOpen 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.”).

Editora's keymap picker
Editora: Keymap: Select… over the editor, the title above the field.
Editora's palette filtered to kill commands with Emacs chords
The palette the picker is built from.

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