fshot 0.0.8__tar.gz

fshot-0.0.8/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.3
+Name: fshot
+Version: 0.0.8
+Summary: Keyboard-first cross-platform screenshot utility
+Requires-Dist: comtypes>=1.4.16 ; sys_platform == 'win32'
+Requires-Dist: keyboard>=0.13.5 ; sys_platform != 'darwin'
+Requires-Dist: mss>=10.1.0
+Requires-Dist: pillow>=11.3.0
+Requires-Dist: pyobjc-framework-applicationservices>=12.0 ; sys_platform == 'darwin'
+Requires-Dist: pyobjc-framework-cocoa>=12.0 ; sys_platform == 'darwin'
+Requires-Dist: pyobjc-framework-quartz>=12.0 ; sys_platform == 'darwin'
+Requires-Dist: pyside6>=6.10.0
+Requires-Dist: pywin32>=311 ; sys_platform == 'win32'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/codemee/fshot
+Project-URL: Repository, https://github.com/codemee/fshot
+Project-URL: Issues, https://github.com/codemee/fshot/issues
+Description-Content-Type: text/markdown
+
+# FShot
+
+[繁體中文](https://github.com/codemee/fshot/blob/main/README.md) | [English](https://github.com/codemee/fshot/blob/main/README.en.md)
+
+FShot 是以 Python 實作的桌面截圖工具，主打全域快捷鍵、系統匣常駐、多頁籤編輯與快速複製/存檔。目前支援 Windows 與 macOS；平台權限與驗收方式請閱讀 [Cross-Platform Notes](https://github.com/codemee/fshot/blob/main/docs/cross-platform.md)。
+
+## Current Status
+
+- Windows: 主要功能已實作並經手動測試調整。
+- macOS: 已實作 Quartz 全域快捷鍵、螢幕擷取、焦點視窗、視窗/控制項選取與游標擷取。
+- Linux: 僅保留基本架構與部分通用能力，尚未作為主要目標平台。
+
+## Quick Start
+
+FShot 可從 [PyPI](https://pypi.org/project/fshot/) 安裝。不需安裝即可使用 `uvx` 執行最新正式版本：
+
+```powershell
+uvx fshot
+```
+
+第一次執行會從 PyPI 下載套件並建立 uv 快取環境，後續會重用快取。臨時試用建議使用 `uvx`，若要長期使用則安裝為 uv tool。
+
+使用 uv 從 PyPI 安裝：
+
+```powershell
+uv tool install fshot
+fshot
+```
+
+安裝後可直接執行 `fshot`；更新至 PyPI 最新版本：
+
+```powershell
+uv tool upgrade fshot
+```
+
+若要直接從 GitHub 測試 `main` 的最新開發成果：
+
+```powershell
+uv tool install --force "fshot @ git+https://github.com/codemee/fshot.git@main"
+```
+
+從原始碼啟動開發環境：
+
+```powershell
+uv sync
+uv run fshot
+```
+
+程式啟動後會隱藏主視窗並留在系統匣。雙擊系統匣圖示可顯示編輯視窗，右鍵選單可退出。
+工具列的主題按鈕可單擊循環切換「跟隨系統 → 淺色 → 深色」；預設跟隨作業系統配色，選擇會保留至下次啟動。太陽代表淺色、月亮代表深色，分隔排列的太陽與月亮代表跟隨系統。
+語言按鈕可單擊循環切換「跟隨系統 → 繁體中文 → English」，並保留使用者選擇；圖示分別為 `文/A`、`中` 與 `En`。
+工具列按鈕的提示文字會依目前語言顯示，具備快捷鍵的動作也會在提示中列出對應按鍵。
+工具列的鍵盤圖示可設定四種截圖方式及「重複前一次擷取」的全域快捷鍵。每組可選 Ctrl、Shift、Alt 與 A–Z 字母；Shift 必須搭配 Ctrl 或 Alt。「使用預設」會將面板中的五組欄位恢復為預設值；按 OK 且系統註冊成功後才會套用並保留設定，Cancel 不會變更目前快捷鍵。
+
+圖片也可透過拖放或剪貼簿加入編輯器：拖放圖片會以完整檔名建立頁籤、保留來源路徑並在修改後寫回原檔；直接貼上影像或從檔案管理器複製圖片後貼上，會以截圖時間格式建立新的未存檔頁籤。成功存檔後會記住檔案所在資料夾，其他尚未存檔的頁籤會從該資料夾開啟儲存交談窗。Windows/Linux 使用 `Ctrl+V`，macOS 使用 `Command+V`。
+
+## Windows Shortcuts
+
+- `Ctrl+Shift+Q`: 重複前一次的截圖方式（矩形區域與選取的視窗／控制項會沿用前次目標，可在設定面板自訂）
+- `Ctrl+Shift+A`: 擷取目前焦點視窗
+- `Ctrl+Shift+R`: 擷取矩形區域
+- `Ctrl+Shift+F`: 擷取全螢幕
+- `Ctrl+Shift+W`: 選取視窗或控制項後擷取
+
+macOS 使用相同的 `Ctrl+Shift` 字母組合。首次執行時，請依系統提示授予「螢幕錄製」與「輔助使用」權限。目前 FShot 是透過 `uv`／`uvx` 執行，而非封裝成獨立的 macOS App，因此系統設定中的授權對象通常是啟動指令所在的 App，例如「終端機」、iTerm2 或 IDE。授權後請完全結束並重新開啟該 App，再重新執行 FShot。
+
+編輯工具快捷鍵：
+
+- `Alt+P`: 自由畫筆
+- `Alt+L`: 線條
+- `Alt+A`: 箭頭
+- `Alt+R`: 矩形
+- `Alt+T`: 文字
+- `Alt+M`: 馬賽克
+- `Alt+C`: 線條粗細與顏色
+- `Ctrl++` / `Ctrl+=`: 放大
+- `Ctrl+-`: 縮小
+- `Ctrl+0`: 重設縮放
+- `F2`: 直接在目前標籤頁重新命名已存檔的檔案（macOS 使用 `Return`）
+
+已存檔的標籤頁也可直接雙擊名稱進入重新命名；副檔名會保留不變。
+
+## Project Docs
+
+- [PRD](https://github.com/codemee/fshot/blob/main/PRD.md): 原始產品需求。
+- [Architecture](https://github.com/codemee/fshot/blob/main/docs/architecture.md): 專案結構、主要模組與資料流。
+- [Cross-Platform Notes](https://github.com/codemee/fshot/blob/main/docs/cross-platform.md): Windows/macOS/Linux 差異與 macOS 後續實作重點。
+
+## Development
+
+```shell
+uv sync
+uv run pytest -q
+uv run python -m compileall src tests
+```
+
+若 FShot 正在執行，`compileall` 有時會因 `__pycache__` 或 executable 被鎖而失敗；先關閉或停止 `fshot.exe` 後再重跑。

fshot-0.0.8/README.md

@@ -0,0 +1,97 @@
+# FShot
+
+[繁體中文](https://github.com/codemee/fshot/blob/main/README.md) | [English](https://github.com/codemee/fshot/blob/main/README.en.md)
+
+FShot 是以 Python 實作的桌面截圖工具，主打全域快捷鍵、系統匣常駐、多頁籤編輯與快速複製/存檔。目前支援 Windows 與 macOS；平台權限與驗收方式請閱讀 [Cross-Platform Notes](https://github.com/codemee/fshot/blob/main/docs/cross-platform.md)。
+
+## Current Status
+
+- Windows: 主要功能已實作並經手動測試調整。
+- macOS: 已實作 Quartz 全域快捷鍵、螢幕擷取、焦點視窗、視窗/控制項選取與游標擷取。
+- Linux: 僅保留基本架構與部分通用能力，尚未作為主要目標平台。
+
+## Quick Start
+
+FShot 可從 [PyPI](https://pypi.org/project/fshot/) 安裝。不需安裝即可使用 `uvx` 執行最新正式版本：
+
+```powershell
+uvx fshot
+```
+
+第一次執行會從 PyPI 下載套件並建立 uv 快取環境，後續會重用快取。臨時試用建議使用 `uvx`，若要長期使用則安裝為 uv tool。
+
+使用 uv 從 PyPI 安裝：
+
+```powershell
+uv tool install fshot
+fshot
+```
+
+安裝後可直接執行 `fshot`；更新至 PyPI 最新版本：
+
+```powershell
+uv tool upgrade fshot
+```
+
+若要直接從 GitHub 測試 `main` 的最新開發成果：
+
+```powershell
+uv tool install --force "fshot @ git+https://github.com/codemee/fshot.git@main"
+```
+
+從原始碼啟動開發環境：
+
+```powershell
+uv sync
+uv run fshot
+```
+
+程式啟動後會隱藏主視窗並留在系統匣。雙擊系統匣圖示可顯示編輯視窗，右鍵選單可退出。
+工具列的主題按鈕可單擊循環切換「跟隨系統 → 淺色 → 深色」；預設跟隨作業系統配色，選擇會保留至下次啟動。太陽代表淺色、月亮代表深色，分隔排列的太陽與月亮代表跟隨系統。
+語言按鈕可單擊循環切換「跟隨系統 → 繁體中文 → English」，並保留使用者選擇；圖示分別為 `文/A`、`中` 與 `En`。
+工具列按鈕的提示文字會依目前語言顯示，具備快捷鍵的動作也會在提示中列出對應按鍵。
+工具列的鍵盤圖示可設定四種截圖方式及「重複前一次擷取」的全域快捷鍵。每組可選 Ctrl、Shift、Alt 與 A–Z 字母；Shift 必須搭配 Ctrl 或 Alt。「使用預設」會將面板中的五組欄位恢復為預設值；按 OK 且系統註冊成功後才會套用並保留設定，Cancel 不會變更目前快捷鍵。
+
+圖片也可透過拖放或剪貼簿加入編輯器：拖放圖片會以完整檔名建立頁籤、保留來源路徑並在修改後寫回原檔；直接貼上影像或從檔案管理器複製圖片後貼上，會以截圖時間格式建立新的未存檔頁籤。成功存檔後會記住檔案所在資料夾，其他尚未存檔的頁籤會從該資料夾開啟儲存交談窗。Windows/Linux 使用 `Ctrl+V`，macOS 使用 `Command+V`。
+
+## Windows Shortcuts
+
+- `Ctrl+Shift+Q`: 重複前一次的截圖方式（矩形區域與選取的視窗／控制項會沿用前次目標，可在設定面板自訂）
+- `Ctrl+Shift+A`: 擷取目前焦點視窗
+- `Ctrl+Shift+R`: 擷取矩形區域
+- `Ctrl+Shift+F`: 擷取全螢幕
+- `Ctrl+Shift+W`: 選取視窗或控制項後擷取
+
+macOS 使用相同的 `Ctrl+Shift` 字母組合。首次執行時，請依系統提示授予「螢幕錄製」與「輔助使用」權限。目前 FShot 是透過 `uv`／`uvx` 執行，而非封裝成獨立的 macOS App，因此系統設定中的授權對象通常是啟動指令所在的 App，例如「終端機」、iTerm2 或 IDE。授權後請完全結束並重新開啟該 App，再重新執行 FShot。
+
+編輯工具快捷鍵：
+
+- `Alt+P`: 自由畫筆
+- `Alt+L`: 線條
+- `Alt+A`: 箭頭
+- `Alt+R`: 矩形
+- `Alt+T`: 文字
+- `Alt+M`: 馬賽克
+- `Alt+C`: 線條粗細與顏色
+- `Ctrl++` / `Ctrl+=`: 放大
+- `Ctrl+-`: 縮小
+- `Ctrl+0`: 重設縮放
+- `F2`: 直接在目前標籤頁重新命名已存檔的檔案（macOS 使用 `Return`）
+
+已存檔的標籤頁也可直接雙擊名稱進入重新命名；副檔名會保留不變。
+
+## Project Docs
+
+- [PRD](https://github.com/codemee/fshot/blob/main/PRD.md): 原始產品需求。
+- [Architecture](https://github.com/codemee/fshot/blob/main/docs/architecture.md): 專案結構、主要模組與資料流。
+- [Cross-Platform Notes](https://github.com/codemee/fshot/blob/main/docs/cross-platform.md): Windows/macOS/Linux 差異與 macOS 後續實作重點。
+
+## Development
+
+```shell
+uv sync
+uv run pytest -q
+uv run python -m compileall src tests
+```
+
+若 FShot 正在執行，`compileall` 有時會因 `__pycache__` 或 executable 被鎖而失敗；先關閉或停止 `fshot.exe` 後再重跑。

fshot-0.0.8/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "fshot"
+version = "0.0.8"
+description = "Keyboard-first cross-platform screenshot utility"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "comtypes>=1.4.16; sys_platform == 'win32'",
+    "keyboard>=0.13.5; sys_platform != 'darwin'",
+    "mss>=10.1.0",
+    "pillow>=11.3.0",
+    "pyobjc-framework-applicationservices>=12.0; sys_platform == 'darwin'",
+    "pyobjc-framework-cocoa>=12.0; sys_platform == 'darwin'",
+    "pyobjc-framework-quartz>=12.0; sys_platform == 'darwin'",
+    "pyside6>=6.10.0",
+    "pywin32>=311; sys_platform == 'win32'",
+]
+
+[project.scripts]
+fshot = "fshot.app:main"
+
+[project.urls]
+Homepage = "https://github.com/codemee/fshot"
+Repository = "https://github.com/codemee/fshot"
+Issues = "https://github.com/codemee/fshot/issues"
+
+[dependency-groups]
+dev = ["pytest>=8.4.1"]
+
+[build-system]
+requires = ["uv_build>=0.11.25,<0.12.0"]
+build-backend = "uv_build"

fshot-0.0.8/pyproject.toml.orig

@@ -0,0 +1,34 @@
+[project]
+name = "fshot"
+version = "0.0.8"
+description = "Keyboard-first cross-platform screenshot utility"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "comtypes>=1.4.16; sys_platform == 'win32'",
+    "keyboard>=0.13.5; sys_platform != 'darwin'",
+    "mss>=10.1.0",
+    "pillow>=11.3.0",
+    "pyobjc-framework-applicationservices>=12.0; sys_platform == 'darwin'",
+    "pyobjc-framework-cocoa>=12.0; sys_platform == 'darwin'",
+    "pyobjc-framework-quartz>=12.0; sys_platform == 'darwin'",
+    "pyside6>=6.10.0",
+    "pywin32>=311; sys_platform == 'win32'",
+]
+
+[project.scripts]
+fshot = "fshot.app:main"
+
+[project.urls]
+Homepage = "https://github.com/codemee/fshot"
+Repository = "https://github.com/codemee/fshot"
+Issues = "https://github.com/codemee/fshot/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.25,<0.12.0"]
+build-backend = "uv_build"

fshot-0.0.8/src/fshot/__init__.py

@@ -0,0 +1,5 @@
+"""FShot screenshot utility."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.0.8"

fshot-0.0.8/src/fshot/__main__.py

@@ -0,0 +1,4 @@
+from fshot.app import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fshot-0.0.8/src/fshot/app.py

@@ -0,0 +1,372 @@
+from __future__ import annotations
+
+import ctypes
+import sys
+import traceback
+from ctypes import wintypes
+
+from PySide6.QtCore import QAbstractNativeEventFilter, QObject, QTimer, Signal
+from PySide6.QtGui import QAction
+from PySide6.QtWidgets import QApplication, QMenu, QMessageBox, QSystemTrayIcon
+
+from fshot.capture import CaptureService
+from fshot.icons import tray_icon
+from fshot.hotkeys import HotkeyAction, HotkeyCombination, HotkeyStore, validate_hotkeys
+from fshot.i18n import LanguageManager
+from fshot.main_window import EditorWindow
+from fshot.settings import CaptureMode
+from fshot.theme import ThemeManager
+
+if sys.platform == "win32":
+    import win32con
+    import win32gui
+else:  # pragma: no cover - platform branch
+    win32con = None
+    win32gui = None
+
+
+class MSG(ctypes.Structure):
+    _fields_ = [
+        ("hwnd", wintypes.HWND),
+        ("message", wintypes.UINT),
+        ("wParam", wintypes.WPARAM),
+        ("lParam", wintypes.LPARAM),
+        ("time", wintypes.DWORD),
+        ("pt", wintypes.POINT),
+    ]
+
+
+class HotkeyBridge(QObject):
+    captureRequested = Signal(CaptureMode)
+    repeatRequested = Signal()
+
+
+def _activate_window(window) -> None:
+    window.showNormal()
+    window.raise_()
+    window.activateWindow()
+    QApplication.processEvents()
+    if sys.platform == "win32":
+        hwnd = int(window.winId())
+        win32gui.ShowWindow(hwnd, win32con.SW_RESTORE)
+        win32gui.BringWindowToTop(hwnd)
+        win32gui.SetForegroundWindow(hwnd)
+        if win32gui.GetForegroundWindow() == hwnd:
+            return
+        flags = win32con.SWP_NOMOVE | win32con.SWP_NOSIZE | win32con.SWP_SHOWWINDOW
+        win32gui.SetWindowPos(hwnd, win32con.HWND_TOPMOST, 0, 0, 0, 0, flags)
+        win32gui.SetWindowPos(hwnd, win32con.HWND_NOTOPMOST, 0, 0, 0, 0, flags)
+        win32gui.SetForegroundWindow(hwnd)
+
+
+class WindowsHotkeyFilter(QAbstractNativeEventFilter):
+    WM_HOTKEY = 0x0312
+    MOD_ALT = 0x0001
+    MOD_CONTROL = 0x0002
+    MOD_SHIFT = 0x0004
+    MOD_NOREPEAT = 0x4000
+
+    def __init__(self, hwnd: int | None, bridge: HotkeyBridge, bindings) -> None:
+        super().__init__()
+        self.hwnd = hwnd
+        self.bridge = bridge
+        self.bindings = {
+            1001 + index: (combination, mode)
+            for index, (mode, combination) in enumerate(bindings.items())
+        }
+        self.registered_ids: list[int] = []
+
+    def register(self) -> None:
+        ctypes.windll.user32.RegisterHotKey.argtypes = [ctypes.c_void_p, ctypes.c_int, ctypes.c_uint, ctypes.c_uint]
+        ctypes.windll.user32.UnregisterHotKey.argtypes = [ctypes.c_void_p, ctypes.c_int]
+        for hotkey_id, (combination, _mode) in self.bindings.items():
+            modifiers = self.modifiers(combination) | self.MOD_NOREPEAT
+            ok = ctypes.windll.user32.RegisterHotKey(
+                ctypes.c_void_p(self.hwnd or 0),
+                hotkey_id,
+                modifiers,
+                ord(combination.letter),
+            )
+            if not ok:
+                self.unregister()
+                raise ctypes.WinError()
+            self.registered_ids.append(hotkey_id)
+
+    def unregister(self) -> None:
+        for hotkey_id in self.registered_ids:
+            ctypes.windll.user32.UnregisterHotKey(ctypes.c_void_p(self.hwnd or 0), hotkey_id)
+        self.registered_ids.clear()
+
+    def nativeEventFilter(self, event_type, message):
+        event_name = bytes(event_type).decode(errors="ignore") if not isinstance(event_type, str) else event_type
+        if event_name not in {"windows_generic_MSG", "windows_dispatcher_MSG"}:
+            return False, 0
+        msg = MSG.from_address(int(message))
+        if msg.message != self.WM_HOTKEY:
+            return False, 0
+        binding = self.bindings.get(int(msg.wParam))
+        if binding is None:
+            return False, 0
+        _combination, mode = binding
+        if mode == HotkeyAction.REPEAT:
+            self.bridge.repeatRequested.emit()
+        else:
+            self.bridge.captureRequested.emit(mode)
+        return True, 0
+
+    @classmethod
+    def modifiers(cls, combination: HotkeyCombination) -> int:
+        return (
+            (cls.MOD_CONTROL if combination.ctrl else 0)
+            | (cls.MOD_SHIFT if combination.shift else 0)
+            | (cls.MOD_ALT if combination.alt else 0)
+        )
+
+
+class FShotApplication(QObject):
+    def __init__(self, app: QApplication) -> None:
+        super().__init__()
+        self.app = app
+        self.app.setApplicationName("FShot")
+        self.app.setOrganizationName("FShot")
+        self.app.setQuitOnLastWindowClosed(False)
+        self.theme_manager = ThemeManager(self.app)
+        self.language_manager = LanguageManager()
+        self.capture = CaptureService()
+        self.window = EditorWindow(self.theme_manager, self.language_manager)
+        self.hotkey_store = HotkeyStore()
+        self.hotkeys = self.hotkey_store.load()
+        self.bridge = HotkeyBridge()
+        self.bridge.captureRequested.connect(self.capture_mode)
+        self.bridge.repeatRequested.connect(self.repeat_capture)
+        self.tray = self._build_tray()
+        self.language_manager.changed.connect(self._language_changed)
+        self._hotkey_handles: list[object] = []
+        self._native_hotkey_filter: WindowsHotkeyFilter | None = None
+        self._mac_hotkey_listener = None
+        self._capture_in_progress = False
+        self.window.configure_hotkeys(self.hotkeys, self._validate_hotkeys, self._apply_hotkeys)
+        self._register_hotkeys()
+
+    def run(self) -> int:
+        self.tray.show()
+        self.window.hide()
+        return self.app.exec()
+
+    def show_window(self) -> None:
+        _activate_window(self.window)
+
+    def quit(self) -> None:
+        self._unregister_hotkeys()
+        self.tray.hide()
+        self.app.quit()
+
+    def capture_mode(self, mode: CaptureMode) -> None:
+        settings = self.window.capture_settings
+        frozen_selection = None
+
+        def freeze_before_hotkey_returns() -> None:
+            nonlocal frozen_selection
+            frozen_selection = self.capture.prepare_frozen_selection(mode, settings)
+
+        self._start_capture(
+            lambda: self.capture.capture(mode, settings, frozen_selection),
+            before_event_flush=freeze_before_hotkey_returns,
+        )
+
+    def repeat_capture(self) -> None:
+        self._start_capture(lambda: self.capture.repeat(self.window.capture_settings))
+
+    def _start_capture(self, capture, before_event_flush=None) -> None:
+        if self._capture_in_progress:
+            return
+        self._capture_in_progress = True
+        self.window.hide()
+        if before_event_flush is not None:
+            try:
+                before_event_flush()
+            except Exception as exc:  # pragma: no cover - UI guard
+                traceback.print_exc()
+                QMessageBox.warning(
+                    self.window,
+                    "FShot",
+                    self.language_manager.text("capture_failed", error=exc),
+                )
+                self._capture_in_progress = False
+                return
+        QApplication.processEvents()
+
+        def do_capture() -> None:
+            try:
+                image = capture()
+            except Exception as exc:  # pragma: no cover - UI guard
+                traceback.print_exc()
+                QMessageBox.warning(
+                    self.window,
+                    "FShot",
+                    self.language_manager.text("capture_failed", error=exc),
+                )
+                self._capture_in_progress = False
+                return
+            if image is None:
+                self._capture_in_progress = False
+                return
+            self.window.add_shot(image)
+            self.show_window()
+            # Selection completion can post a delayed activation restore after
+            # SetForegroundWindow initially succeeds. Reassert the editor once
+            # that input transaction has fully settled.
+            QTimer.singleShot(200, self.show_window)
+            self.window.copy_current()
+            self._capture_in_progress = False
+
+        QTimer.singleShot(120, do_capture)
+
+    def _build_tray(self) -> QSystemTrayIcon:
+        tray = QSystemTrayIcon(tray_icon(macos=sys.platform == "darwin"), self.app)
+        tray.setToolTip("FShot")
+        menu = QMenu()
+        self.exit_action = QAction(self.language_manager.text("exit"), menu)
+        self.exit_action.triggered.connect(self.quit)
+        menu.addAction(self.exit_action)
+        tray.setContextMenu(menu)
+        tray.activated.connect(self._tray_activated)
+        return tray
+
+    def _language_changed(self, _mode, _effective) -> None:
+        self.exit_action.setText(self.language_manager.text("exit"))
+
+    def _tray_activated(self, reason: QSystemTrayIcon.ActivationReason) -> None:
+        if reason == QSystemTrayIcon.ActivationReason.DoubleClick:
+            self.show_window()
+
+    def _register_hotkeys(self, bindings=None, show_warning: bool = True) -> bool:
+        bindings = bindings or self.hotkeys
+        if sys.platform == "win32":
+            try:
+                self._native_hotkey_filter = WindowsHotkeyFilter(None, self.bridge, bindings)
+                self._native_hotkey_filter.register()
+                self.app.installNativeEventFilter(self._native_hotkey_filter)
+                return True
+            except Exception as exc:
+                self._native_hotkey_filter = None
+                if show_warning:
+                    QMessageBox.warning(self.window, "FShot", f"Native global hotkeys unavailable: {exc}")
+                return False
+
+        if sys.platform == "darwin":
+            try:
+                from fshot.platforms.macos import MacHotkeyListener, accessibility_allowed
+
+                accessibility_allowed(request=True)
+                actions = {combination: action for action, combination in bindings.items()}
+
+                def dispatch(combination) -> None:
+                    action = actions[combination]
+                    if action == HotkeyAction.REPEAT:
+                        self.bridge.repeatRequested.emit()
+                    else:
+                        self.bridge.captureRequested.emit(action)
+
+                self._mac_hotkey_listener = MacHotkeyListener(
+                    dispatch,
+                    tuple(actions),
+                )
+                self._mac_hotkey_listener.start()
+                return True
+            except Exception as exc:
+                if show_warning:
+                    QMessageBox.warning(self.window, "FShot", f"macOS global hotkeys unavailable: {exc}")
+                return False
+
+        try:
+            import keyboard
+        except Exception as exc:  # pragma: no cover - optional dependency guard
+            if show_warning:
+                QMessageBox.warning(self.window, "FShot", f"Global hotkeys unavailable: {exc}")
+            return False
+
+        for action, combination in bindings.items():
+            shortcut = combination.display().lower()
+            try:
+                if action == HotkeyAction.REPEAT:
+                    callback = lambda: self.bridge.repeatRequested.emit()
+                else:
+                    callback = lambda capture_mode=action: self.bridge.captureRequested.emit(capture_mode)
+                handle = keyboard.add_hotkey(shortcut, callback, suppress=True)
+                self._hotkey_handles.append(handle)
+            except Exception as exc:
+                self._unregister_hotkeys()
+                if show_warning:
+                    QMessageBox.warning(self.window, "FShot", f"Could not register {shortcut}: {exc}")
+                return False
+        return True
+
+    def _validate_hotkeys(self, bindings) -> tuple[bool, str]:
+        problem = validate_hotkeys(bindings)
+        if problem:
+            return False, self.language_manager.text(f"hotkey_{problem}")
+        if sys.platform != "win32" or self._native_hotkey_filter is None:
+            return True, ""
+        owned = {combination for combination, _mode in self._native_hotkey_filter.bindings.values()}
+        registered: list[int] = []
+        try:
+            for index, combination in enumerate(bindings.values()):
+                if combination in owned:
+                    continue
+                hotkey_id = 2101 + index
+                ok = ctypes.windll.user32.RegisterHotKey(
+                    ctypes.c_void_p(0),
+                    hotkey_id,
+                    WindowsHotkeyFilter.modifiers(combination)
+                    | WindowsHotkeyFilter.MOD_NOREPEAT,
+                    ord(combination.letter),
+                )
+                if not ok:
+                    return False, self.language_manager.text(
+                        "hotkey_conflict", shortcut=combination.display()
+                    )
+                registered.append(hotkey_id)
+        finally:
+            for hotkey_id in registered:
+                ctypes.windll.user32.UnregisterHotKey(ctypes.c_void_p(0), hotkey_id)
+        return True, ""
+
+    def _apply_hotkeys(self, bindings) -> tuple[bool, str]:
+        valid, message = self._validate_hotkeys(bindings)
+        if not valid:
+            return valid, message
+        previous = self.hotkeys
+        self._unregister_hotkeys()
+        if not self._register_hotkeys(bindings, show_warning=False):
+            self._register_hotkeys(previous, show_warning=False)
+            return False, self.language_manager.text("hotkey_registration_failed")
+        self.hotkeys = dict(bindings)
+        self.hotkey_store.save(self.hotkeys)
+        self.window.configure_hotkeys(self.hotkeys, self._validate_hotkeys, self._apply_hotkeys)
+        return True, ""
+
+    def _unregister_hotkeys(self) -> None:
+        if self._mac_hotkey_listener is not None:
+            self._mac_hotkey_listener.stop()
+            self._mac_hotkey_listener = None
+        if self._native_hotkey_filter is not None:
+            self.app.removeNativeEventFilter(self._native_hotkey_filter)
+            self._native_hotkey_filter.unregister()
+            self._native_hotkey_filter = None
+        try:
+            import keyboard
+        except Exception:
+            return
+        for handle in self._hotkey_handles:
+            try:
+                keyboard.remove_hotkey(handle)
+            except Exception:
+                pass
+        self._hotkey_handles.clear()
+
+
+def main() -> int:
+    app = QApplication(sys.argv)
+    controller = FShotApplication(app)
+    return controller.run()