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.
Where the OS’s way wins
Section titled “Where the OS’s way wins”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, or a deviation recorded in pauta.json (Conformance).
| What | Windows | macOS | Linux | Rules |
|---|---|---|---|---|
| Primary modifier | Ctrl | Cmd, from each keymap’s .mac.json variant | Ctrl | KBD-09, KBD-10, KBD-21 |
| Menu bar | In the title bar | The system menu bar, in a decorated window | In the title bar | WIN-03 |
| Open and save dialogs | The OS’s own (FileChooser) | The OS’s own | The OS’s own | |
| Opening a file or link, showing it in the file manager | Explorer | Finder (open) | xdg-open | |
| Tray icon | AWT SystemTray | AWT SystemTray | StatusNotifierItem | TRAY-01 |
| Notifications | A PowerShell toast | osascript | notify-send | TRAY-09 |
| Start at login | The HKCU Run value | A LaunchAgent | An XDG autostart entry | TRAY-06 |
| Saved secrets | Credential Manager | Keychain | The Secret Service | SET-13 |
| Installers | .msi, winget | .dmg, Homebrew | .deb, .rpm, .AppImage, .tar.gz | REL-11, REL-12, REL-13 |
The same everywhere
Section titled “The same everywhere”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 table above is
the only exception.
- 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
setDisableand 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, withisWindows(),isMac()andisLinux()), and no other class reads theos.nameproperty.- 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/javalists one file. - Reference: no app yet. Every app reads
os.namein several classes, Editora in about fifty; Editora’sprocess/DesktopActions.javahas theOsenum to start from.
- OS-03 SHOULD Tests can run as any OS: the
Osclass 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 4.4.0 · · Changelog · This page in the latest edition