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
| ID | Level | Rule |
|---|---|---|
| TBAR-01 | MUST | Every icon-only button has a name: one helper sets its tooltip and its accessible text from
the same string.
|
| 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.
|
| 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.
|
| 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.
|
| 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.
|
| 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.
|
| 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.
|
| 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.
|
| TBAR-13 | SHOULD | The right stripe’s first icon lines up with the editor’s first line of text, not with the
tab strip.
|
Anatomy
Section titled “Anatomy”Main.javapom.xml5
Save (C-x C-s)3
- 1Icon button, 28 px: padding 3 × 5, radius 4, no border, the glyph in
-color-fg-mutedand-color-fg-defaultunder the pointer. It has a name even though it shows none: the same string is its tooltip and its accessible text. - 2Group gap. A vertical
Separatornode whose line is transparent: its padding is what separates the groups. No drawn rule. - 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.
- 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. - 5One band. The menu bar, the toolbar and the tab strip sit on
-color-bg-subtlewith no hairline between them; spacing does the grouping. - 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.
| Property | Value | Reference |
|---|---|---|
| Button | 28 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 |
| Bar | Padding 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 |
| Icon | The 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 :open | Icons, .toolbar-icon, .icon-line, .button:open |
| Group gap | A vertical Separator with its line transparent; its 0.75 em padding is the gap | .tool-bar .separator:vertical > .line |
| Tail | Its own container (.toolbar-tail), same insets and font as the bar, never overflowed | ToolbarOverflowFxTest |
| Tooltip | <title> (<chord>), the chord from KeymapManager.displayChord; only the title when unbound; radius 8 like the menus | ToolbarCoordinator.buildExtraButton, ToolWindowManager.tooltipFor, .tooltip |
| Stripe button | A 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 mode | The 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
Buttonis built byIcons.buttonorIcons.toolbarButton, or passed toIcons.name; none callssetTooltipwithoutsetAccessibleText. - 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.setupButtonandToolbarCoordinator.buildExtraButtonset 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.toolbarButtonor callssetFocusTraversable(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 byWindowToolbar.setupButtonandToolbarCoordinator.buildExtraButton, and the stripe buttons, take focus.
- Check (code): every button on a toolbar is built by
- 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.
- Check (code): the tooltip is built from the command’s title and the keymap’s display chord for its id, and is rebuilt when the keymap changes.
- Reference: Editora
WindowToolbar.setupButton(refreshToolbarTooltips),ToolbarCoordinator.buildExtraButtonandToolWindowManager.tooltipFor; Torrenta’stoolbar.withChord. Mirada’s header buttons use the same “label (key)” form with the key written into the string.
- TBAR-04 SHOULD Groups are separated by spacing, not rules: keep the
Separatornodes (their padding is the gap) and make the line transparent.- Check (code): the stylesheet sets
.tool-bar .separator:vertical > .lineto a transparent border. - Reference: Editora
app.css. Torrenta’s separators still draw a line.
- Check (code): the stylesheet sets
- 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.
- Check (code): every change to a toolbar item’s visibility ends in one pass over the bar’s separators.
- Reference: Editora
WindowChromeCoordinator.collapseToolbarSeparators.
- TBAR-06 SHOULD One chrome band: the menu bar, the toolbar and the tab strip share
-color-bg-subtleand 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
:openpseudo-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:openinapp.css. Torrenta uses:onfor Simple mode and:activefor 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 thecommandIdit 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.
- Check (test): an FX test right-clicks the bar twice and finds one menu, then presses on the bar and elsewhere in the window and finds it closed.
- Reference: Editora
ToolbarCoordinator,ContextMenuDismissal,ToolbarContextMenuDismissFxTest. See Menus, whose rules on icons, chords and the 14 px font (MENU-16) hold for this menu too.
- 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
accessibleTextPropertyis bound to the tool window’s title. - Reference: Editora
ToolWindowManager.register,tooltipFor.
- Check (code): the stripe button’s tooltip comes from the same title-and-chord format, and its
- TBAR-13 SHOULD The right stripe’s first icon lines up with the editor’s first line of text, not with the
tab strip.
- Check (test): an FX test compares the first stripe button’s top with the editor’s first line.
- Reference: Editora
ToolWindowStripeAlignmentFxTest.
In the apps
Section titled “In the apps”- Editora: the customizable cluster, the pinned tail, the stripes.
- Torrenta: the same
Icons.toolbarButtonandIcons.name, 32 px buttons, Simple mode as:on; its separators still draw a line. - Mirada: a
HeaderBartitle 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.


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