util.platformSupport module

What’s done differently on macOS, Windows and Linux: the key shortcuts are made with (Command on the Mac, Control elsewhere), showing a file in the Finder (or Explorer, or the file manager), moving a file to the Trash (or Recycle Bin), putting a picture on the clipboard, where logs go, and the like. A program asks this module, rather than testing sys.platform itself.

Nothing here imports the rest of util, so anything in it can use this.

Code author: Rob Kremer <robkremer@me.com>

util.platformSupport.MAC = True

Whether this is macOS.

util.platformSupport.WINDOWS = False

Whether this is Windows.

util.platformSupport.LINUX = False

Whether this is Linux (or another Unix with X11 or Wayland).

util.platformSupport.SHORTCUT = 'Command'

The Tk modifier key shortcuts are made with: eg, f"<{SHORTCUT}-KeyPress-z>". (Tk accepts “Command” off the Mac too, but no key there makes it.)

util.platformSupport.SHORTCUT_LABEL = 'Command'

SHORTCUT’s name in a menu item’s accelerator (Tk on the Mac shows “Command” as ⌘).

util.platformSupport.ALT = 'Option'

The Tk modifier for the Option key (on the Mac) or Alt (elsewhere).

util.platformSupport.ALT_LABEL = 'Option'

ALT’s name in a menu item’s accelerator.

util.platformSupport.shortcut(key: str, shift: bool = False, alt: bool = False, label: str | None = None) → tuple[str, str]

A key shortcut: key with Command (on the Mac) or Control (elsewhere).

Parameters:

• key – The key’s Tk keysym, eg: “z”, “equal”, “0”. With shift, give the shifted keysym (eg: “Z”).

• shift – Whether it’s with Shift too.

• alt – Whether it’s with Option (Alt) too.

• label – How the key’s shown in the accelerator (by default: key, upper-cased, or eg “+” for “equal”).

Returns:

(the Tk event sequence to bind, the menu accelerator): eg, for “z”, (“<Command-KeyPress-z>”, “Command-Z”) on the Mac and (“<Control-KeyPress-z>”, “Ctrl+Z”) elsewhere.

util.platformSupport.altKey(key: str, label: str | None = None) → tuple[str, str]

Returns:

(the Tk event sequence, the menu accelerator) for key with Option (on the Mac) or Alt (elsewhere): eg, (“<Alt-KeyPress-v>”, “Alt+V”).

util.platformSupport._launch(cmd: list[str]) → None

util.platformSupport.openFile(path: str) → None

Open path (a file or folder) as if it were double-clicked: a folder in the Finder (Explorer, the file manager), a file in its application.

Raises:

OSError – If it can’t be.

util.platformSupport.reveal(path: str) → None

Show path in the Finder (Explorer, the file manager): a file selected in its folder (on Linux, its folder is opened), a folder opened.

Raises:

OSError – If it can’t be.

util.platformSupport.TRASH_NAME = 'Trash'

What the place deleted files go is called here.

util.platformSupport.moveToTrash(path: str) → None

Move a file (or folder) to the Trash – the Recycle Bin, on Windows – where it can be put back from.

Raises:

OSError – If it can’t be moved there (nothing’s deleted then).

util.platformSupport._trashMac(path: str) → None

util.platformSupport._trashWindows(path: str) → None

util.platformSupport._trashFreedesktop(path: str) → None

util.platformSupport.logFolder(program: str) → str

Parameters:

program – The program’s name, eg: “Semantic Nets”.

Returns:

The folder the program’s logs belong in (not made): eg, “~/Library/Logs/<program>” on the Mac, “%LOCALAPPDATA%<program>Logs” on Windows, “~/.local/state/<program>” on Linux.

util.platformSupport.documentsFolder() → str

Returns:

The user’s Documents folder: on Windows, wherever it really is (eg: in OneDrive); on Linux, XDG’s (eg: from xdg-user-dir DOCUMENTS), if it’s set up; else ~/Documents.

util.platformSupport.pdfToPNG(pdfPath: str, pngPath: str, dpi: int) → None

Make a PNG of a PDF’s first page, at dpi dots per inch: with sips on the Mac; elsewhere with the pypdfium2 and Pillow packages.

Raises:

RuntimeError – If it can’t be made (eg: they aren’t installed).

util.platformSupport.copyPNG(pngPath: str) → None

Put a PNG on the clipboard: with osascript on the Mac; on Windows as a PNG and a bitmap (for programs that don’t take PNGs: that needs Pillow); on Linux with wl-copy (Wayland) or xclip (X11).

Raises:

RuntimeError – If it can’t be done.

util.platformSupport._copyPNGWindows(pngPath: str) → None

util.platformSupport.WINDOW_BACKGROUND = 'systemWindowBackgroundColor'

The Tk color of a window’s background (the Mac’s and Windows’ system colors only exist there).

util.platformSupport.setDPIAware() → None

On Windows, say the program draws for the screen’s resolution itself, so Windows doesn’t scale its windows up (blurred) on a high-resolution screen. Call it before the first Tk window is made. Elsewhere it does nothing.

util.platformSupport.setUpLook(root: Any) → None

Choose a ttk theme that fits in: on Linux, “clam” (Tk’s “default” there looks dated); the Mac’s and Windows’ own native themes are left as they are.

Parameters:

root – The Tk root (or any widget).