Skip to content
Pauta5.0.0

Same on every OS

The family exists so that one app can be used the same way on Windows, macOS and Linux (principle 1). This page says where an app may follow the OS’s own way and where it may not, and its rules keep other differences out. Each difference is easy to add on its own: an if (isMac) that hides a menu row, a JavaFX default that orders buttons one way on Windows and another on macOS.

Inside the window, Pauta’s design wins: the same commands, keymaps, look, dialogs and files on every OS. The OS’s own way wins only where the app hands work to the OS or sits in the OS’s own interface, because there the user would be fighting the OS rather than learning the app. The table is the whole list. Any other difference between OSes is a bug: an app records it in pauta.json as pending, with an issue, until it is fixed (Conformance).

WhatWindowsmacOSLinuxRules
Primary modifierCtrlCmd, from each keymap’s .mac.json variantCtrlKBD-09, KBD-10, KBD-21
How a chord is writtenCtrl+Shift+P⇧⌘P, in Apple’s modifier orderCtrl+Shift+P
QuitFile → Quit, the tray’s QuitThe same, plus the app menu’s and the Dock’s Quit, caught as the app’s ownFile → Quit, the tray’s QuitTRAY-04
Menu barIn the title bar, by defaultThe system menu bar, in a decorated windowIn the title bar, by defaultWIN-03
Open and save dialogsThe OS’s own (FileChooser)The OS’s ownThe OS’s own
Opening a file or link, showing it in the file managerExplorerFinder (open)xdg-open
Tray iconAWT SystemTrayAWT SystemTrayStatusNotifierItemTRAY-01
NotificationsA PowerShell toast, shown as Windows PowerShell’sosascript, shown as Script Editor’snotify-send, shown as the app’sTRAY-09
Dock or taskbar badgeNoneThe dock iconA launcher that honors LauncherEntryTRAY-12
Command lineA console launcher, beside the GUI oneThe app’s own launcherThe app’s own launcherCLI-11
Middle-click pasteNoneNoneThe X11 primary selection, in a terminal
Start at loginThe HKCU Run valueA LaunchAgentAn XDG autostart entryTRAY-06
Saved secretsCredential ManagerKeychainThe Secret ServiceSET-13
Screen readerNarrator (UI Automation)VoiceOverNone: JavaFX has no bridge to the Linux accessibility busAccessibility
Installers.msi (unsigned until REL-17 is met), winget on x64.dmg, Homebrew on Apple Silicon.deb, .rpm, .AppImage, .tar.gz; on arm64, .tar.gz (and .deb where the tooling allows)REL-11, REL-12, REL-13

Some differences in the apps today are on no row, so each breaks a rule until it is fixed:

  • Mirada keeps its settings in ~/Library/Application Support and %APPDATA%, not ~/.mirada (SET-07).
  • Torrenta hides its “on metered connections” row on macOS instead of disabling it (OS-01).
  • Editora’s move to the Trash does nothing on Windows, where Mirada and Torrenta use the Recycle Bin (OS-01).
  • No app’s macOS Quit reaches a tray app’s quit yet (TRAY-04), and no app’s flags print on Windows (CLI-11).

Everything else, and in particular:

  • Commands, settings and windows, with the same defaults: OS-01. A keymap’s macOS variant binds the same commands: KBD-21.
  • The look. Inter on every window (ICON-01), not the OS’s UI font; the same AtlantaFX themes (PLAT-05); the same icons on every menu row the app draws (MENU-14).
  • Dialogs. The same buttons in the same order: WIN-11.
  • Files. The config folder is ~/.<app> on every OS (SET-07), not %APPDATA% or ~/Library/Application Support, so the folder a user backs up, syncs or reads about in the docs is the same one.
  • The command line (Command line) and the user docs: one set for all three, which names a difference only where this page lists it.
  • OS-01 MUST Every command, setting and window exists on Windows, macOS and Linux, with the same default. Where the OS can’t do what one asks, it stays where it is, disabled, and says why; it is never hidden. The rows of Where the OS’s way wins are the only exceptions.
    • Why: a user who moves to another OS looks for a feature where they left it. A missing row looks like a different app; a disabled one with a reason explains itself.
    • Check (code): no command, menu row or settings row is registered or added inside an OS check, and no default in the settings model depends on the OS. A row the OS can’t serve calls setDisable and carries its reason (KBD-04 for a command).
    • Reference: Editora ui/SettingsWindow.java (the extended-window row, disabled on macOS “rather than hidden, so its note still explains why”).
  • OS-02 MUST One class answers which OS the app runs on (Os, with isWindows(), isMac() and isLinux()), and no other class reads the os.name property.
    • Why: checks scattered through the code are how apps drift apart on one OS without anyone choosing it. In one class, every difference can be found with one search, and a test can run the app as any OS (OS-03).
    • Check (code): grep -rln '"os.name"' src/main/java lists one file.
    • Command: [ -f pom.xml ] || { echo 'not an app root: no pom.xml here'; exit 1; }; n=$(grep -rl '"os.name"' src/main/java | wc -l); [ "$n" -eq 1 ] || { echo "$n files read os.name (one Os class should):"; grep -rl '"os.name"' src/main/java; false; }
    • Reference: no app yet. Every app reads os.name in several classes, Editora in about fifty; Editora’s process/DesktopActions.java has the Os enum to start from.
  • OS-03 SHOULD Tests can run as any OS: the Os class takes an override, and one test asserts that the command ids, the menu bar’s rows and the settings pages are the same for Windows, macOS and Linux.
    • Why: CI runs the FX tests on one or two OSes (REL-20); with the override, the comparison runs on every pull request on Linux alone.
    • Check (test): a test sets each OS in turn through the override and compares the three lists.
    • Reference: no app yet. Editora’s KeymapsTest (guiKeymapsBindSameCommandSetOnBothPlatforms) does it for the keymaps.

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