Skip to content
Pauta4.2.0

Toolbars and tooltips

A toolbar is the fast path to commands that are also in the menus and the Command Palette: nothing lives only on it. Every button is a command, so its icon, title and chord come from the registry and the active keymap. Reference: Editora’s ui/Icons.java (button, toolbarButton, name), ui/ToolbarCoordinator.java (the customizable bar), ui/WindowChromeCoordinator.java (collapseToolbarSeparators), ui/ToolWindowManager.java (the tool window stripes) and the .tool-bar, .toolbar-button, .tool-stripe-button and .tooltip rules in app.css.

Rules on this page 12
IDLevelRule
TBAR-01MUST
Every icon-only button has a name: one helper sets its tooltip and its accessible text from the same string.
TBAR-02MUST
Toolbar buttons stay out of the Tab order: the command, the palette and the menus reach the action, and Tab is for the content. The keyboard page has the general focus rules.
TBAR-03MUST
The tooltip names the command and its chord, read from the active keymap and never typed into a string: “Save (C-x C-s)”. An unbound command shows its title alone.
TBAR-04SHOULD
Groups are separated by spacing, not rules: keep the Separator nodes (their padding is the gap) and make the line transparent.
TBAR-05SHOULD
Hiding a button group (Simple mode, a build tool that is not detected) hides the leading, trailing and doubled separators it leaves, so no gap stands on its own, and shows them all again when nothing is hidden.
TBAR-06SHOULD
One chrome band: the menu bar, the toolbar and the tab strip share -color-bg-subtle and draw no hairline between them; the breadcrumb, the bottom stripe and the status bar do the same at the bottom.
TBAR-07SHOULD
A toggle looks on while it is on: a button that opens an overlay (Find, the palette, a split) and the Simple mode button carry the :open pseudo-class while their state holds, so the way back out does not look like the way in.
TBAR-08MUST
The toolbar never holds the only way to an action: every icon in the customizable cluster is also in the menus and the palette.
TBAR-09MAY
The toolbar is customizable: the user reorders, removes and restores its buttons, and the layout is saved in Settings and shared by every window.
TBAR-10MUST
The bar’s right-click menu is one menu, reused across right-clicks, so showing it again moves it, and it closes on a press anywhere, the toolbar included.
TBAR-12SHOULD
Tool window stripes are toolbars: a stripe button is built like a toolbar button, with the chord in its tooltip, accessible text bound to the window’s title, and a right-click menu with Open in Split and Hide.
TBAR-13SHOULD
The right stripe’s first icon lines up with the editor’s first line of text, not with the tab strip.
  1. 1Icon button, 28 px: padding 3 × 5, radius 4, no border, the glyph in -color-fg-muted and -color-fg-default under the pointer. It has a name even though it shows none: the same string is its tooltip and its accessible text.
  2. 2Group gap. A vertical Separator node whose line is transparent: its padding is what separates the groups. No drawn rule.
  3. 3Tooltip. The command's title and its chord in the active keymap, "Save (C-x C-s)". A popup window with the menus' radius 8.
  4. 4Open toggle. A button whose overlay is showing (Find, the palette, a split) wears :open: an accent-subtle fill and the glyph in the accent color. Simple mode's own button does the same while the mode is on.
  5. 5One band. The menu bar, the toolbar and the tab strip sit on -color-bg-subtle with no hairline between them; spacing does the grouping.
  6. 6Pinned tail. The project picker, About and Quit live in their own container beside the ToolBar, so a narrow window overflows the icons (which are all in the menus too) and never the tail.
PropertyValueReference
Button28 px high: padding 3 × 5, radius 4, style classes button-icon flat toolbar-button; every control on the bar is pinned to 28 px, combos and menu buttons included.toolbar-button, .tool-bar .combo-box-base
BarPadding 5 1 2 6 (asymmetric: the tab strip below adds its own inset); 18 px font for the bar’s own labels, controls inside it at 14 px; -color-bg-subtle, no rule above or below.tool-bar, .menu-bar, .tool-bar
IconThe command’s glyph, 17 px drawn (Torrenta) or a kit glyph at the toolbar scale (Editora); -color-fg-muted, -color-fg-default on hover, -color-accent-fg while :openIcons, .toolbar-icon, .icon-line, .button:open
Group gapA vertical Separator with its line transparent; its 0.75 em padding is the gap.tool-bar .separator:vertical > .line
TailIts own container (.toolbar-tail), same insets and font as the bar, never overflowedToolbarOverflowFxTest
Tooltip<title> (<chord>), the chord from KeymapManager.displayChord; only the title when unbound; radius 8 like the menusToolbarCoordinator.buildExtraButton, ToolWindowManager.tooltipFor, .tooltip
Stripe buttonA toolbar button on the tool window rail: min 24 px, padding 9 × 5, radius 6, 8 px apart on a 30 px rail; the same muted, hover and :open colors; the bottom stripe adds a 14 px label.tool-stripe-button, ToolWindowManager.register
Customize modeThe bar tinted -color-accent-subtle, a move cursor, the dragged button at 0.4 opacity, a 2 px accent insertion line on the drop target’s edge.tool-bar.toolbar-customizing, .toolbar-drop-before
  • TBAR-01 MUST Every icon-only button has a name: one helper sets its tooltip and its accessible text from the same string.
    • Why: a hand-rolled button gets the tooltip and forgets the name, which is how Editora once had seven copies of the helper drifting apart, and how a screen reader comes to announce “button”.
    • Check (code): every icon-only Button is built by Icons.button or Icons.toolbarButton, or passed to Icons.name; none calls setTooltip without setAccessibleText.
    • Reference: Editora ui/Icons.java (button, toolbarButton, name); Torrenta’s copy of all three. nux sets both by hand on its ”?” button for the same reason. Editora doesn’t yet on its main toolbar: WindowToolbar.setupButton and ToolbarCoordinator.buildExtraButton set the tooltip only.
  • TBAR-02 MUST Toolbar buttons stay out of the Tab order: the command, the palette and the menus reach the action, and Tab is for the content. The keyboard page has the general focus rules.
    • Check (code): every button on a toolbar is built by Icons.toolbarButton or calls setFocusTraversable(false).
    • Reference: Editora Icons.toolbarButton, used by the tool window toolbars (Git, Diff, Markdown lint); Termina’s search bar buttons; Mirada’s header buttons. Editora doesn’t yet on its main toolbar: the buttons built by WindowToolbar.setupButton and ToolbarCoordinator.buildExtraButton, and the stripe buttons, take focus.
  • TBAR-03 MUST The tooltip names the command and its chord, read from the active keymap and never typed into a string: “Save (C-x C-s)”. An unbound command shows its title alone.
  • TBAR-04 SHOULD Groups are separated by spacing, not rules: keep the Separator nodes (their padding is the gap) and make the line transparent.
    • Check (code): the stylesheet sets .tool-bar .separator:vertical > .line to a transparent border.
    • Reference: Editora app.css. Torrenta’s separators still draw a line.
  • TBAR-05 SHOULD Hiding a button group (Simple mode, a build tool that is not detected) hides the leading, trailing and doubled separators it leaves, so no gap stands on its own, and shows them all again when nothing is hidden.
  • TBAR-06 SHOULD One chrome band: the menu bar, the toolbar and the tab strip share -color-bg-subtle and draw no hairline between them; the breadcrumb, the bottom stripe and the status bar do the same at the bottom.
    • Why: three rules within forty pixels read as clutter, not structure.
    • Check (by hand): look at the top and the bottom of a window in a light and a dark theme for a line between the bands.
    • Reference: Editora app.css (.menu-bar, .tool-bar).
  • TBAR-07 SHOULD A toggle looks on while it is on: a button that opens an overlay (Find, the palette, a split) and the Simple mode button carry the :open pseudo-class while their state holds, so the way back out does not look like the way in.
    • Check (code): each such button sets a pseudo-class from its state, and the stylesheet gives that state a fill.
    • Reference: Editora MainController.OPEN, WindowChromeCoordinator (Simple mode), .button:open in app.css. Torrenta uses :on for Simple mode and :active for the alternative speed limit.
  • TBAR-08 MUST The toolbar never holds the only way to an action: every icon in the customizable cluster is also in the menus and the palette.
    • Why: that is what makes it safe to hide icons in a narrow window and to let the user remove them.
    • Check (code): every toolbar catalog item runs a registered command that a menu also lists.
    • Reference: Editora toolbar/ToolbarCatalog.java: each item carries the commandId it runs; the only items without one are declared special widgets, such as the Recent menu button (ToolbarCatalogTest).
  • TBAR-09 MAY The toolbar is customizable: the user reorders, removes and restores its buttons, and the layout is saved in Settings and shared by every window.
    • Check (test): FX tests drive customize mode, reorder and removal.
    • Reference: Editora ui/ToolbarCoordinator.java, ToolbarCustomizeModeFxTest, ToolbarCustomizationFxTest. The cluster is a list of catalog ids in Settings (toolbarLayout), sanitized on read. The bar’s right-click menu offers Customize Toolbar… (or Done), Configure… (the Settings page) and Restore Default. In customize mode the bar tints, buttons drag to reorder with an accent insertion line and drag off the bar to remove; Escape leaves the mode.
  • TBAR-10 MUST The bar’s right-click menu is one menu, reused across right-clicks, so showing it again moves it, and it closes on a press anywhere, the toolbar included.
  • TBAR-12 SHOULD Tool window stripes are toolbars: a stripe button is built like a toolbar button, with the chord in its tooltip, accessible text bound to the window’s title, and a right-click menu with Open in Split and Hide.
    • Check (code): the stripe button’s tooltip comes from the same title-and-chord format, and its accessibleTextProperty is bound to the tool window’s title.
    • Reference: Editora ToolWindowManager.register, tooltipFor.
  • TBAR-13 SHOULD The right stripe’s first icon lines up with the editor’s first line of text, not with the tab strip.
  • Editora: the customizable cluster, the pinned tail, the stripes.
  • Torrenta: the same Icons.toolbarButton and Icons.name, 32 px buttons, Simple mode as :on; its separators still draw a line.
  • Mirada: a HeaderBar title bar with flat icon buttons around the file name, stroked symbolic icons in the text color, tooltips of the form “label (key)”; each button’s accessible text is set by hand, and the buttons are out of the Tab order.
  • Termina: no main toolbar (its tabs are in the title bar); the search bar’s buttons are 24 × 22 flat icons with tooltips, out of the Tab order.
Editora editing a Java file with the project tree and status bar
Editora's toolbar: grouped icons on the chrome band, the project picker and Quit pinned at the right.
Mirada with its file name and folder in a HeaderBar title bar, an info panel and a thumbnail strip
Mirada's HeaderBar: flat icon buttons around the file name.

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