Setting Up Keyboard Shortcuts

Reusable keyboard shortcuts system for PySide6 applications. Provides platform-specific defaults, TOML configuration, and Qt integration.

Copy reusable code from coding_rules_python/reusable/shortcuts/ and tests from coding_rules_python/reusable_tests/.

See also: reusable/shortcuts/README.md for full API reference.

When to Use

PySide6 desktop apps that need customizable keyboard shortcuts
Apps targeting multiple platforms (Linux, Windows, macOS)
Apps where users should be able to edit shortcuts via config file

Quick Start

1. Define Shortcuts

# src/myapp/config.py
from shared.shortcuts import ActionShortcut

DEFAULT_SHORTCUTS = (
    ActionShortcut("new_file", "New File", "Ctrl+N", "Ctrl+N", "Cmd+N"),
    ActionShortcut("save", "Save", "Ctrl+S", "Ctrl+S", "Cmd+S"),
    ActionShortcut("quit", "Quit", "Ctrl+Q", "Ctrl+Q", "Cmd+Q"),
    ActionShortcut("search", "Search", "Ctrl+F"),  # Same on all platforms
)

2. Initialize Manager

from shared.shortcuts import ShortcutManager
from pathlib import Path
import platformdirs

manager = ShortcutManager(
    config_dir=Path(platformdirs.user_config_dir("myapp")),
    app_name="myapp",
    default_shortcuts=DEFAULT_SHORTCUTS,
)

3. Use in Qt

from PySide6.QtGui import QAction, QKeySequence
from PySide6.QtWidgets import QMainWindow

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.shortcut_manager = manager
        self.shortcut_manager.load()
        self._setup_menu()

    def _setup_menu(self):
        file_menu = self.menuBar().addMenu("&File")

        save_action = QAction("&Save", self)
        save_action.setShortcut(QKeySequence(self.shortcut_manager.get_shortcut("save")))
        save_action.triggered.connect(self._save)
        file_menu.addAction(save_action)

Key Concepts

ActionShortcut

Immutable definition of a keyboard shortcut with platform-specific defaults:

ActionShortcut(
    action_id="save",           # Unique ID (snake_case)
    display_name="Save",        # Human-readable name for UI
    default_linux="Ctrl+S",     # Linux default
    default_windows="Ctrl+S",   # Windows default (falls back to Linux if empty)
    default_macos="Cmd+S",      # macOS default (falls back to Linux if empty)
)

Key Sequence Format

Uses Qt's QKeySequence string format:

Modifiers: Ctrl, Shift, Alt, Meta
Special keys: Return (NOT Enter), Backspace, Delete, Tab, Escape, Space, F1-F35
Navigation: Left, Right, Up, Down, Home, End, PageUp, PageDown
Combine with +: Ctrl+Shift+S, Alt+Left

Important: Always use "Return" for the Enter key, NOT "Enter" (which maps to numpad Enter on some platforms).

TOML Config File

Auto-created at <config_dir>/<app_name>_shortcuts.toml:

# Edit keyboard shortcuts using Qt QKeySequence string format.
# MODIFIERS: Ctrl, Shift, Alt, Meta (use '+' to combine)
# SPECIAL KEYS: Return (Enter key), Backspace, Delete, Tab, Escape, Space, F1-F35

[shortcuts]
new_file = "Ctrl+N"
save = "Ctrl+S"
quit = "Ctrl+Q"
search = ""        # Empty string disables the shortcut

Dependencies

[project]
dependencies = [
    "pyside6>=6.10.1",
    "rusty-results>=1.1.1",
    "tomli>=2.2.1",
    "tomli-w>=1.2.0",
]

Files to Copy

From coding_rules_python/reusable/:

shortcuts/__init__.py — public API exports
shortcuts/shortcuts.py — ActionShortcut, ShortcutConfig, ShortcutManager
shortcuts/README.md — full API reference

From coding_rules_python/reusable_tests/ → copy into your tests/:

test_shortcuts_base.py — generic tests for ActionShortcut, ShortcutConfig, validation
test_shortcuts_manager.py — generic tests for ShortcutManager

Update import paths after copying (e.g., reusable.shortcuts → shared.shortcuts, reusable.shortcuts.shortcuts → shared.shortcuts.shortcuts in monkeypatch paths).

Testing

The reusable tests cover all generic behavior. For app-specific tests:

# tests/test_my_shortcuts.py
from reusable_tests.test_shortcuts_base import (
    TestActionShortcut,
    TestShortcutConfig,
    TestShortcutConfigSave,
    TestValidateKeySequence,
)

# Inherit generic tests — they run automatically
class TestMyActionShortcut(TestActionShortcut):
    pass

# Add app-specific tests
class TestMyAppShortcuts:
    def test_default_shortcuts_are_valid(self):
        from myapp.config import DEFAULT_SHORTCUTS
        for shortcut in DEFAULT_SHORTCUTS:
            assert shortcut.action_id
            assert shortcut.display_name

setting-up-shortcuts