Skip to content
Pauta6.1.0

Welcome page

The page shown when there is no session to restore, and the answer to “what do I do now?”. The text rules are in Editora’s ui/WelcomeText.java and the strings under welcome.*.

Rules on this page 11
IDLevelRule
Rules
WELC-01SHOULD
An app that opens files or projects in tabs shows a Welcome page when there is no session to restore.
WELC-02SHOULD
An app whose window is its content, and can start with nothing in it (a list with no items, a viewer with nothing open), shows its own empty state in place of a Welcome page (WELC-01), with the same ingredients: the ways in, each with its chord.
Behavior
WELC-03SHOULD
The Welcome page is shown at startup when there is no session to restore (so always with --no-session), by the view.welcome command (Help → Welcome Page where the app has a Help menu, in the place DOCS-07 gives it), and when a switch to another project leaves the tab strip empty (Editora’s project swap). In an app that can start straight into one view, as Editora does for a standalone diff, that startup suppresses the page while its worker reads the files.
WELC-04SHOULD
Closing the last tab does not bring the Welcome page back. The empty content area shows its own quiet hint instead: the app’s ways in, each with its chord (in Editora: Open File, Open Folder, Command Palette and Welcome Page), and takes focus so chords still reach the window.
WELC-05SHOULD
The page is rebuilt on every show, so the recents, the Projects and Git toggles, the keymap and the theme are current. A refresh keeps the focus where it was.
WELC-06SHOULD
The recent lists offer no file that no longer exists and no project whose root is gone. Remote files are kept unchecked.
WELC-07SHOULD
Remove from recent files asks first, through the caller, then refreshes the page.
WELC-08SHOULD
The digits 1 to 9 open the numbered entries: typed characters only, with no modifier, so chords and Enter are untouched.
WELC-09SHOULD
In an app with saved remote sites, they appear as their own section; a click opens the connection form prefilled. The section is hidden when there are none.
WELC-10SHOULD
The Welcome page’s Customize links run the commands that pick the keymap and the app theme (Editora’s are keymap.select and theme.setAppTheme); a change made there re-renders the page, chords included.
WELC-11SHOULD
The Welcome tab is not a document: its menu is Close only, with no Save, Rename or Pin, and the title bar shows the app or project name, not a file.
  • WELC-01 SHOULD An app that opens files or projects in tabs shows a Welcome page when there is no session to restore.
  • WELC-02 SHOULD An app whose window is its content, and can start with nothing in it (a list with no items, a viewer with nothing open), shows its own empty state in place of a Welcome page (WELC-01), with the same ingredients: the ways in, each with its chord.
    • Check (by hand): start the app with nothing in it and read the empty state’s keys. An app that always opens into content (a terminal with its shell, a radio, a monitor) has no empty state to judge.
    • Reference: Torrenta ui/Welcome.java; Mirada ui/ViewerWindow.java (offerToOpen, viewer.emptyHint); both are described under In the apps.
  1. 1Identity. The app icon at 64 px beside the name (2.4 em, bold) and the README's one-line tagline, muted. One centered column, at most 640 px wide and never narrower than 340; a longer window scrolls.
  2. 2Start actions, each an existing command: New File, Open File, Open Folder as a Project (only with Projects on), Clone Git Repository (only with Git on), and the Command Palette always last, the gateway to everything else. Accent links with no box; the icon sits in a 26 px column so every label starts at the same x, and the whole row answers a click.
  3. 3Chord, right-aligned past a 32 px gap, in the keyboard color, from the active keymap. Unbound: no chord. Open File shows find-file's chord in the Emacs keymap, where that is the key to learn. The hovered row tints and the chord becomes a chip.
  4. 4Entry number. The first nine recent entries, projects first, are numbered in the keyboard color; typing that digit opens the entry. Projects come in the order of their most recent file.
  5. 5Recent file row. The name keeps its width; a chip names the project (or the host of a remote file); the folder is muted, relative to the project root, with ~ for home, and elides from its start so the part that differs stays visible. The full path is the row's tooltip; right-click offers Copy Path and Remove from recent files.
  6. 6Disclosure. Five rows per list; the rest wait behind "Show N more", which becomes "Show fewer".
  7. 7Customize. The active keymap and app theme by name; each link runs the picker command. Under an Emacs-style keymap a caption explains the notation. On a first run, with nothing recent, this block moves up under Start.
  8. 8Help and footer. Documentation, What's New (the release notes) and the Doctor. Then the version, the home page and the license; a dev build adds its commit on its own line once the lookup, which runs git off the FX thread, has answered.
PropertyValueReference
KindA real tab content in its own closeable “Welcome” tab, so the tab strip handles switching and closing; not an overlayWelcomePane implements TabContent, MainController.addWelcomeTab
Column640 px max, 340 px min, 48 px margin, centered in a scroll pane; below the minimum the page scrolls sidewaysCOLUMN_WIDTH, MIN_COLUMN_WIDTH, MARGIN
ZoomEvery px size is multiplied by the text zoom and the fonts are em, so zoom scales the layout, not only the wordssetFontScale, .welcome-*
Surface-color-bg-default, the UI surface, not the editor’s; its tab takes the same fill.welcome-pane, .ui-surface-tab
HeaderIcon 64 px; title 2.4 em bold; tagline -color-fg-muted.welcome-title, .welcome-caption
Section heading1.15 em bold, padding 28 0 8 0.welcome-section
LinksHyperlink in -color-accent-fg, no border, underlined only on hover or keyboard focus; visited stays the accent.welcome-action, .welcome-link
Action rowIcon column 26 px, gap 12 to the label, at least 32 px to the chord; hover fills -color-bg-subtle with 6 px radius, insets 8 px past the rowWelcomePane.action, .welcome-action-row
Chord-state-key, 0.9 em; on hover a -state-key-bg chip, radius 4.welcome-key
Recent rowNumber -state-key 0.8 em; folder -color-fg-muted 0.9 em with a leading ellipsis; project chip muted on -color-bg-subtle, radius 3.welcome-entry-number, .welcome-recent-dir, .recent-project-name
Lists5 rows, then a flat disclosure buttonCOLLAPSED_RECENT_LIMIT, addCollapsed
FocusThe first recent entry, or New File when there is none, with no focus ring; Enter and Space open itrequestFocus, focusPage

Applies to: an app with a Welcome page (WELC-01).

  • WELC-03 SHOULD The Welcome page is shown at startup when there is no session to restore (so always with --no-session), by the view.welcome command (Help → Welcome Page where the app has a Help menu, in the place DOCS-07 gives it), and when a switch to another project leaves the tab strip empty (Editora’s project swap). In an app that can start straight into one view, as Editora does for a standalone diff, that startup suppresses the page while its worker reads the files.
    • Check (code): those three paths open the one Welcome tab, and where the app has a Help menu, a row inside it runs view.welcome; a startup that goes straight to a view holds a flag that skips the page.
    • Reference: Editora MainController.addWelcomeTab, showWelcomeIfNoTabs; WindowSessionCoordinator (suppressWelcome). Editora’s menu row is in View, not in Help yet (MenuBarModel). The app template shows the page when there is no session to restore (ui/DocumentTabs.java), registers view.welcome (ui/Commands.java) and lists it in the Help menu (ui/AppMenus.java; SessionAndWelcomeFxTest, theWelcomePageIsInHelpClosesAloneAndIsRebuiltWhenShown); it has no project swap and no view to start straight into.
  • WELC-04 SHOULD Closing the last tab does not bring the Welcome page back. The empty content area shows its own quiet hint instead: the app’s ways in, each with its chord (in Editora: Open File, Open Folder, Command Palette and Welcome Page), and takes focus so chords still reach the window.
    • Check (code): closing the last tab shows the hint in the empty content area, not the Welcome page, and gives it the focus; opening a tab hides it. A test that asserts it is the surest evidence.
    • Reference: Editora ui/EditorEmptyState.java, EditorEmptyStateFxTest; the app template’s ui/DocumentTabs.java (emptyHint, which lists its ways in with their chords and takes focus when the last tab closes).
  • WELC-05 SHOULD The page is rebuilt on every show, so the recents, the Projects and Git toggles, the keymap and the theme are current. A refresh keeps the focus where it was.
  • WELC-06 SHOULD The recent lists offer no file that no longer exists and no project whose root is gone. Remote files are kept unchecked.
    • Check (code): the recent files pass through the same filter as the toolbar’s dropdown; projects are kept only when their root is a directory.
    • Reference: Editora RecentFiles.showable, WelcomePane.
  • WELC-07 SHOULD Remove from recent files asks first, through the caller, then refreshes the page.
  • WELC-08 SHOULD The digits 1 to 9 open the numbered entries: typed characters only, with no modifier, so chords and Enter are untouched.
    • Check (code): the digit handler is on KEY_TYPED and ignores Ctrl, Alt and Meta.
    • Reference: Editora WelcomePane.onKeyTyped.
  • WELC-09 SHOULD In an app with saved remote sites, they appear as their own section; a click opens the connection form prefilled. The section is hidden when there are none.
    • Check (code): the page adds a Remote Sites section only when the saved-sites list is not empty.
    • Reference: Editora WelcomePane (remoteSites, welcome.remote).
  • WELC-10 SHOULD The Welcome page’s Customize links run the commands that pick the keymap and the app theme (Editora’s are keymap.select and theme.setAppTheme); a change made there re-renders the page, chords included.
    • Check (code): the two Customize links run the app’s keymap and theme picker commands through the registry, and applying a keymap or a theme refreshes the Welcome page.
    • Reference: Editora WelcomePane (customizeRow), refreshed by SettingsReapply.
  • WELC-11 SHOULD The Welcome tab is not a document: its menu is Close only, with no Save, Rename or Pin, and the title bar shows the app or project name, not a file.
    • Check (code): the Welcome tab’s context menu holds one Close item.
    • Reference: Editora MainController.addWelcomeTab; the app template’s ui/DocumentTabs.java, whose Welcome tab’s menu holds buffer.close alone, is not pinned, and leaves the title to the project and the app.
KeyEnglish
welcome.tabWelcome
welcome.taglineA keyboard-driven programmer’s editor
welcome.startStart
welcome.newFile / welcome.openFileNew File / Open File…
welcome.openFolder / welcome.cloneOpen Folder as a Project… / Clone Git Repository…
welcome.recentProjects / welcome.recentFiles / welcome.remoteRecent Projects / Recent Files / Remote Sites
welcome.noRecentNo recent files yet. Open a file or a folder to start, or run editora FILE in a terminal.
welcome.recent.showMore / welcome.recent.showFewerShow {0} more / Show fewer
welcome.entryNumberPress {0} to open (accessible help)
welcome.customize / welcome.keymap / welcome.themeCustomize / Keymap / Theme
welcome.notation.emacsChords use Emacs notation: C- is Ctrl, M- is Alt, S- is Shift. Pick another keymap above to see your platform’s notation.
welcome.help / welcome.documentation / welcome.whatsNew / welcome.doctorHelp / Documentation / What’s New / Doctor: Check External Tools
welcome.versionVersion {0}
welcome.pageWelcome Page (the row in the empty editor’s hint, WELC-04; the menu row takes the command’s title, command.view.welcome)
Editora's Welcome tab
Editora: Start actions with their chords, Recent Projects and Recent Files numbered 1 and 2, Customize below.

Torrenta has no documents to come back to, so its welcome is an empty state over the table until the first torrent (ui/Welcome.java, bound to the list being empty): a drop zone that says “Drop a .torrent, a magnet or a link anywhere”, the four keys that matter with their chords (open a .torrent file, add what is on the clipboard, filter or run a command, Settings), the clipboard’s magnet or link offered with an Add it button when there is one, and where downloads go with a change link. Nothing on it takes focus: the keys are the way in. Mirada, with no folder open, shows an empty state too (offerToOpen in ui/ViewerWindow.java): a hint that names the Open command’s chord (“Open an image with {0}, or drop one here”), buttons for the Open Image… and Open Folder… commands and a Documentation link. Termina, Modula and nux open straight into their content and have neither.

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