Skip to content
Pauta6.1.0

Menus

Two surfaces show the same rows: the menu bar, a browsable map of every command, and right-click menus, what can be done with the thing under the pointer. A row built from the command registry takes its title, icon, chord and enabled state from the command, so it never drifts from the palette or the toolbar. Editora builds its menu bar that way (ui/MenuBarModel.java); its right-click menus are still built by hand, each row with its own title, glyph and action (LazyContextMenu.item). The app template’s ui/CommandMenu.java builds a right-click menu from registered command ids. Reference: Editora’s ui/MainMenuBar.java (menu bar), ui/ContextMenuDismissal.java, ui/LazyContextMenu.java, ui/RowContextMenu.java and ui/TabContextMenu.java (right-click menus), and the .menu-item and .context-menu rules in app.css.

Rules on this page 18
IDLevelRule
Look and feel
MENU-14MAY
A row of a menu the app draws may carry an icon, where a glyph depicts what the row does or names: a command row its command’s glyph, a row that names a thing rather than an action (a recent file, a branch, a project) that thing’s icon, a submenu its family’s. A row with no fitting glyph goes without one rather than borrow another command’s, and a check or radio row carries none, because its mark fills the icon column.
MENU-15MUST
In every menu the app draws itself, a row whose command has a chord in the active keymap shows that chord, in right-click menus, drop-downs and the toolbar’s overflow as in the in-window menu bar: right-aligned in the menu’s chord column, in the keyboard color, the one color the app keeps for chords and key chips (Editora’s token for it is -state-key; ICON-06 says how the color is made), at the size MENU-16 gives. An unbound command leaves the cell empty, never a wrong chord, and a keymap switch rewrites every cell. The menus a platform draws are outside this rule: the macOS system menu bar, whose rows append the chord to the title (MENU-02), and a tray icon’s menu, which shows none.
MENU-16MUST
Every menu the app draws itself (the in-window menu bar, right-click menus, the drop-down of a menu button or a split button, the toolbar’s overflow) draws its titles in Inter 14 px regular and its chords in Inter 11 px at the default zoom, scaled by the UI zoom (WIN-12), whatever node it was opened from: the size is set on .context-menu and its rows’ labels from one value the zoom sets, never inherited from the node. The macOS system menu bar and a tray icon’s menu are the platform’s, drawn in the platform’s font, and outside this rule.
MENU-18SHOULD
At the default zoom a menu row is 34 px high (padding 8 × 12), its icon column is 22 px wide with 8 px to the title, and its chord starts at least 18 px after the title column. The popup’s card has a radius of 8 and a shadow of radius 16 at offset Y 16: the offset is at least the radius.
The menu bar
MENU-01MUST
Every menu-bar item is a command from the registry, with the command’s title (KBD-03), its chord from the active keymap and its enabled state from the command’s gate. A row may show the title without its category prefix (“Save As…” for “File: Save As…”); it never carries a title of its own. The bar assembles and refreshes; it holds no behavior of its own.
MENU-02MUST
Menu-bar rows use no KeyCombination accelerators. In the in-window bar each row is a CustomMenuItem laying out icon, title, spacer and chord. On the macOS system menu bar (useSystemMenuBar) the chord is appended to the title and rows carry no icon.
MENU-03SHOULD
Enablement is re-read every time a menu opens, and titles and chords on a keymap or locale change.
MENU-04SHOULD
An app with a Simple mode shows a shorter menu in it, rebuilt only when the mode actually changes.
MENU-17SHOULD
The in-window menu bar, the one an app shows on Windows and Linux (WIN-03), is reachable from the keyboard in every keymap. JavaFX opens the bar’s first menu on F10 and on a lone Alt; a keymap that binds F10 to something else binds a command that focuses the menu bar instead. So does a terminal app, where a plain F10 goes to the program it runs. The macOS system menu bar is reached with the OS’s own keys and asks nothing of the app.
Right-click menus
MENU-05MUST
In an app with a right-click menu, every list row, tree row, tab, editor and read-only console has one, with the actions for that thing, and every action in a right-click menu is a command (KBD-01). The rule covers the lists, trees, tabs, editors and read-only consoles in the app’s windows. A log shown as text, the Debug Log among them, is a read-only console and has its right-click menu. A list that only navigates, switching what its window shows (a Settings sidebar, a list of pages), has no actions of its own and is outside the rule, as are the overlay list of a picker or a palette and a plain text area in a dialog.
MENU-06MUST
One right-click menu at a time: a right-click while a menu is open replaces it, and the first one closes before the second shows.
MENU-07MUST
A press anywhere outside a right-click menu closes it, including inside the control the menu was opened on. The press is not consumed: a click in a list still selects the row, and a right-click on another row opens that row’s menu straight away. Drop-downs opened by a plain click (menu buttons, choice boxes, the menu bar) keep the stock behavior, and a menu that turned auto-hide off is left alone.
MENU-08MUST
Escape closes a right-click menu and focus goes back where it was. In a terminal app the Escape that closes the menu does not reach the shell.
MENU-09MUST
The Menu key and Shift+F10 open the right-click menu of the selected row, scrolled into view first, so every row action a mouse can reach the keyboard can too. In a view with no rows (an editor, a terminal, an image) they open the focused view’s menu. The chord is the same on macOS, where keyboards have no Menu key: Shift+F10, with no Cmd form.
MENU-10SHOULD
A right-click selects first. In an editor, a right-click outside every selection moves the caret to the click (so Paste lands there); inside a selection it keeps carets and selections (so Cut and Copy act on what was clicked). From the keyboard the target is the caret. In a list, the menu is the clicked row’s.
MENU-11SHOULD
A menu attached to something that exists once per open file is built when first shown, and set up for each showing: an onShowing handler sets the labels, enablement and visibility for this showing, then collapses the separators.
MENU-12SHOULD
A destructive row is styled as dangerous, its text in -color-danger-fg (Editora’s style class for it is danger). What the action does before it destroys anything is not this rule’s: the Confirm dialog rules hold it (CONF-01, CONF-03: it asks first with a button that names it, or is undoable).
MENU-13MAY
In a terminal view, a program that grabbed the mouse owns the right-click; Shift+right-click always opens the menu, and the keyboard request is never contested.

Both surfaces draw their rows the same way, and the sizes in the table are the ones at the default zoom. A menu sets its own font size on .context-menu, 14 px at the default zoom, from the one value the UI zoom sets (WIN-12), so it never inherits its owner’s: a popup takes the font of the node it was opened from, and em would resolve against a file tree’s or an 18 px toolbar’s size (Editora’s toolbar menu once rendered a third larger than every other menu in the app).

PropertyValueReference
FontInter 14 px at the default zoom, regular, in every row and label; set on .context-menu from the value the UI zoom sets, never inherited from the owner.context-menu, .context-menu .menu-item .label in app.css; MainMenuBar.UI_FONT_SIZE
Row34 px high: padding 8 × 12, the same in every theme.menu-item { -fx-padding: 8px 12px }
Icon column22 px on every row, so the titles line up: a row’s glyph, a check row’s tick, or empty; 8 px to the titleMainMenuBar.ICON_COLUMN, rowContent
IconOptional; where a row has one, the command’s glyph, the same one as on the toolbar and in the palette (Save is the same floppy everywhere), filled -color-fg-mutedIcons, MenuBarIcons, .toolbar-icon
TitleInter 14 px, -color-fg-default.menu-item-title
ChordRight-aligned in its own column, Inter 11 px, in the keyboard color (-state-key, brace periwinkle); at least 18 px from the title column; in every menu, right-click menus included.menu-item-chord, alignChordColumns
Submenu rowLaid out like a command row, with an invisible chord as wide as the menu’s widest, so the arrow lands at the right edgenestedMenu, .menu-submenu
CardRadius 8; shadow rgba(27,30,42,0.28), the value of a token defined on .root (ICON-08), radius 16, offset Y 16.context-menu
Danger itemText in -color-danger-fg.menu-item.danger
Disabled itemThe theme’s dimmed label, and the icon dimmed with itTermina’s .menu-item:disabled .menu-icon
SeparatorsNever two in a row and none at either end: when items hide, their orphaned separators hide tooLazyContextMenu.collapseSeparators, Torrenta’s MenuSeparators

The shadow’s offset is not cosmetic. A menu is a native window sized to its root including the effect, so a shadow that reaches above the menu is invisible window over the bar the menu hangs from, and the pointer lands on it instead of the next menu button. MENU-18 asks for an offset of at least the radius; Editora pins it with MenuPopupBoundsFxTest.

The rules of this section hold for every menu the app draws itself: the menu bar, right-click menus, the drop-down of a menu button or a split button, and the toolbar’s overflow. The menus a platform draws (the macOS system menu bar, a tray icon’s menu) show text only; there the chord is appended to the title (MENU-02) and the tray shows neither.

Applies to: an app with a menu bar.

  1. 1Menu button. Padding 3 × 10 on a bar with 4 px side insets; the bar and the toolbar share one -color-bg-subtle band with no rule under it.
  2. 2Icon column, 22 px. A row may wear the glyph that depicts its command; where none fits, the cell stays empty and the titles still line up.
  3. 3Title, 14 px Inter, the command's title with its category prefix dropped ("Save", not "File: Save") unless two rows would then read the same. Editora drops the prefix only where two words or more are left ("File: Save As…" reads "Save As…"), so its File menu still reads "File: Save" (editor/MenuTitles.java).
  4. 4Chord column. Inter 11 px, periwinkle, right-aligned into one column per menu (not app-wide), read from the active keymap. Drawn by the app, not a JavaFX accelerator: Emacs chords are multi-key, which a KeyCombination cannot express, and on macOS an accelerator would bypass the key dispatcher.
  5. 5Unbound command. An empty chord cell, never a wrong chord. A live keymap switch rewrites every cell.
  6. 6Submenu row. Icon, title and an invisible chord as wide as the menu's widest, so its arrow sits at the right edge instead of halfway across.
  7. 7Card. Radius 8; the shadow falls below the menu (offset ≥ radius), so nothing invisible covers the bar.
Editora's View menu open with toggle commands and their chords
Editora's View menu in an earlier build: chords in one periwinkle column, but every title repeats the menu's name.

Applies to: an app with a right-click menu: a menu the app builds and opens on a right-click, the Menu key or Shift+F10, over something in one of its windows. The stock Cut, Copy and Paste menu that JavaFX gives a text field does not make an app one, and neither does a tray icon’s menu, which the platform draws: nux has both and no right-click menu.

The mockup is an editor tab’s menu, shortened; Editora’s has twenty-one rows.

  1. 1Anchored at the pointer. The menu's top-left corner is the click. From the keyboard (Menu key or Shift+F10) it opens under the selected row, a quarter of the way in and never off a narrow one, or just below the caret in an editor; never in the middle of the control.
  2. 2Icon and chord. A row wears its command's own icon where one fits, and its chord when it has one, in the same periwinkle column as the menu bar's. A CheckMenuItem has no icon: its tick lives in the graphic column.
  3. 3Grayed, not hidden. An action that does not apply right now (Save on an unchanged file, Reveal on an unsaved one) stays in place, dimmed. Only a row that cannot apply to this thing at all is hidden (the Git submenu on an untitled buffer).
  4. 4Separators group the rows; one that hiding has left alone hides too.
  5. 5Submenu for a family of actions (Git: stage, unstage, revert, compare, history), with its own icon.
  6. 6Labels follow state. Encrypt… becomes Lock File on an encrypted buffer, Pin Tab becomes Unpin Tab. Decided on every showing, not when the menu was built.
PropertyValueReference
Kindjavafx.scene.control.ContextMenu, auto-hide on, hide on Escape on: a popup window, unlike the paletteTabContextMenu, ConsoleContextMenu
Opens atThe pointer; from the keyboard, the selected row’s bottom edge at min(width ÷ 4, 48) px in, or under the caretRowContextMenu.anchorX, ContextMenuTarget
FontInter 14 px at the default zoom, set on .context-menu from one value the UI zoom sets, so it never inherits the owner’s fontapp.css
Rows34 px (padding 8 × 12); icon column 22 px; glyph scaled 0.8 from a 24 dp Material path, or a 16-unit line glyphIcons.ICON_SCALE, Icons.line
CardRadius 8, shadow radius 16 at offset Y 16.context-menu
DismissalAny press outside the menu, in any window; the next right-click; EscapeContextMenuDismissal, ContextMenuDismissalFxTest
MarkerA showing menu opened by a right-click or the Menu key carries the window property editora.rightClickMenuContextMenuDismissal.RIGHT_CLICK_MENU
Termina window with a menu bar, a tab strip under it and a tab context menu
Termina's tab menu: an icon on every row, following Editora's convention.
Editora's View menu open with toggle commands and their chords
Editora's in-window menu bar with the chord column, in an earlier build whose titles repeat the menu's name.

Pauta 6.1.0 · · Changelog · Permanent link to this page in 6.1.0