Skip to content
Pauta6.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. QOPEN-01 asks for the one picker; every other rule on this page is the picker’s shape and applies to an app that has one. Four of the apps have none (Uses).

Rules on this page 12
IDLevelRule
Rules
QOPEN-01SHOULD
One picker serves every list choice: recent files, themes, keymaps, a setting’s values, a branch to compare with.
QOPEN-02SHOULD
In an app with a picker (a card, opened by a command, for choosing one thing from a list by typing; a Command Palette that lists only commands is not one, and nor is a menu, a combo box or a field’s completion list), 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. That it is never a javafx.stage.Popup is KBD-07.
Behavior
QOPEN-03SHOULD
A picker reads its items fresh on every showing and snapshots them, so typing filters a stable list. A source that answers late (an outline the language server has not returned yet) has the picker read its items again and keep the query (reload() in Editora).
QOPEN-04SHOULD
With nothing typed, a picker’s 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.
QOPEN-05SHOULD
Typing in a picker ranks its rows by fuzzy score, and ties keep the supplier’s order, so rows do not shuffle under the cursor between keystrokes.
QOPEN-06SHOULD
In a picker, the active keymap’s line and page chords move the selection (in Editora, the chords of its nav.lineDown, nav.lineUp, nav.pageDown and nav.pageUp commands), 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.
QOPEN-07SHOULD
The active keymap’s cancel chord, Esc or a click on the scrim cancels a picker, and the overlay host restores focus. In Editora the chord is that of its edit.cancel command, C-g in the Emacs keymap. A picker that previewed something undoes it.
QOPEN-08MAY
A picker previews the highlighted row as the selection moves and undoes the preview on cancel (Editora’s 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. Editora’s theme and keymap pickers do not preview; they apply on Enter.
QOPEN-09MAY
A row action acts on the highlighted row and keeps the picker open (Editora’s breakpoints picker enables or removes one), re-reading the list afterwards and keeping the cursor in place.
QOPEN-10SHOULD
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-11SHOULD
The overlay host a picker shows in holds one card at a time; opening a picker replaces whatever card was up.
QOPEN-12SHOULD
A picker’s relatives, the other list overlays an app has (in Editora the open-files switcher, the find-file field, the multi-select picker, and the branch and stash popups), move, accept and cancel with the same keys as the picker.
  • 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. Editora still asks with a ChoiceDialog in three places: the Git reset mode and the merge parent to revert against (ui/GitWindowCoordinator.java), and the settings backup to restore (ui/SettingsResetFlow.java).
  • QOPEN-02 SHOULD In an app with a picker (a card, opened by a command, for choosing one thing from a list by typing; a Command Palette that lists only commands is not one, and nor is a menu, a combo box or a field’s completion list), 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. That it is never a javafx.stage.Popup is KBD-07.
  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, in the palette's key-chip style (the keyboard color, -state-key, in Editora): 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 key-chip style, -state-key in EditoraItemCell, .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

Applies to: an app with a picker: a card, opened by a command, for choosing one thing from a list by typing (a Command Palette that lists only commands is not one, and nor is a menu, a combo box or a field’s completion list).

  • QOPEN-03 SHOULD A picker reads its items fresh on every showing and snapshots them, so typing filters a stable list. A source that answers late (an outline the language server has not returned yet) has the picker read its items again and keep the query (reload() in Editora).
    • Check (code): showing a picker calls its items supplier, and a late source makes the picker read the items again while it keeps the query (Editora’s show and reload).
    • Reference: Editora QuickOpen.show, QuickOpen.reload.
  • QOPEN-04 SHOULD With nothing typed, a picker’s 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): a picker’s empty query passes the items through unsorted and selects the value in force when the picker was given one (Editora’s setCurrentItem).
    • Reference: Editora QuickOpen.filter, setCurrentItem; the app template’s ui/Picker.java (current), whose theme, keymap and language pickers open on the choice in force (PickerFxTest, helpTitleCurrentValueAndTheEnds).
  • QOPEN-05 SHOULD Typing in a picker ranks its rows by fuzzy score, and ties keep the supplier’s order, so rows do not shuffle under the cursor between keystrokes.
    • Check (code): the last tiebreak of the picker’s sort is the supplier’s index.
    • Reference: Editora QuickOpen.filter.
  • QOPEN-06 SHOULD In a picker, the active keymap’s line and page chords move the selection (in Editora, the chords of its nav.lineDown, nav.lineUp, nav.pageDown and nav.pageUp commands), 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 picker’s key handler moves on the commands the active keymap binds for a line and a page up and down, and on the fixed keys whatever the keymap; the accept path hides the card before it calls the choice handler.
    • Reference: Editora QuickOpen (hide() then onChoose), PickerKeys.resolve, the only picker that asks the keymap. The app template’s ui/Picker.java asks the keymap the same way, through its ui/PickerKeys.java (resolve), and takes Ctrl+Home and Ctrl+End (Cmd on macOS); Mirada’s picker is its palette, whose ui/PaletteKeys.java carries a fixed table of Emacs chords (EMACS) beside the fixed keys. Termina, Torrenta, Modula and nux have no picker (Uses).
  • QOPEN-07 SHOULD The active keymap’s cancel chord, Esc or a click on the scrim cancels a picker, and the overlay host restores focus. In Editora the chord is that of its edit.cancel command, C-g in the Emacs keymap. A picker that previewed something undoes it.
    • Check (code): Esc, the chord the active keymap binds to the cancel command, and a press on the backdrop each hide the picker; hiding gives the focus back to the node that had it before the picker opened; and a picker that previewed a row runs its undo when it is dismissed without a choice. A test that asserts the undo is the surest evidence.
    • Reference: Editora OverlayHost (previousFocus; it cancels on PickerKeys.isCancel), QuickOpenPreviewFxTest (dismissingRestoresWhatWasPreviewed). The app template’s ui/OverlayHost.java cancels its pickers on Esc, on the scrim and on the keymap’s edit.cancel chord (cancelOn), and gives the focus back; none of its pickers previews anything. Ctrl+G is fixed in the EMACS table of Mirada’s ui/PaletteKeys.java.
  • QOPEN-08 MAY A picker previews the highlighted row as the selection moves and undoes the preview on cancel (Editora’s 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. Editora’s theme and keymap pickers do not preview; they apply on Enter.
    • Check (code): a previewing picker previews from its selection listener once it is showing, never for the row it opens on, restores what it previewed when dismissed, and does not restore after a choice. A test that asserts it is the surest evidence.
    • Reference: Editora QuickOpen.setPreview(onPreview, onCancelled), QuickOpenPreviewFxTest.
  • QOPEN-09 MAY A row action acts on the highlighted row and keeps the picker open (Editora’s breakpoints picker enables or removes one), re-reading the list afterwards and keeping the cursor in place.
    • Check (code): a row action’s key runs the action on the highlighted row without hiding the card, and the picker then reads its items again and keeps the cursor on that row. A test that asserts it is the surest evidence.
    • 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.
  • QOPEN-11 SHOULD The overlay host a picker shows in holds one card at a time; opening a picker replaces whatever card was up.
    • Check (code): showing a card in the overlay host removes the previous card before it adds the new one, and keeps the original focus owner (Editora’s OverlayHost.show).
    • Reference: Editora OverlayHost.show.
  • QOPEN-12 SHOULD A picker’s relatives, the other list overlays an app has (in Editora the open-files switcher, the find-file field, the multi-select picker, and the branch and stash popups), 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. The app template’s one relative, its tab switcher (ui/Switcher.java), moves through the same ui/PickerKeys.java and accepts and cancels as its pickers do.

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, breakpoint groups, loaded sources and modules, agent modelsNavigationCoordinator, EditorSettingsCoordinator, DiffCoordinator, DebugCoordinator, BreakpointsPicker, BreakpointGroups, LoadedSourcesPicker
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 (“There are no breakpoints. Click left of a line number to set one.”, status.debug.noBreakpoints).

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 6.1.0 · · Changelog · Permanent link to this page in 6.1.0