prkit 0.1.1__tar.gz → 0.2.1__tar.gz

prkit-0.2.1/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.3
+Name: prkit
+Version: 0.2.1
+Summary: A cross-platform system-tray presentation toolkit
+Author: meebox
+Author-email: meebox <meebox@gmail.com>
+Requires-Dist: pynput>=1.8.2
+Requires-Dist: pyobjc-framework-cocoa>=12.2.1 ; sys_platform == 'darwin'
+Requires-Dist: pyobjc-framework-quartz>=12.2.1 ; sys_platform == 'darwin'
+Requires-Dist: pyside6>=6.11.1
+Requires-Dist: python-xlib>=0.33 ; sys_platform == 'linux'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/codemee/prkit
+Project-URL: Repository, https://github.com/codemee/prkit
+Project-URL: Issues, https://github.com/codemee/prkit/issues
+Description-Content-Type: text/markdown
+
+# PRKit：簡報瑞士刀
+
+[繁體中文](README.md) | [English](README.en.md)
+
+跨平台的系統匣簡報輔助工具。程式不會開啟主視窗，所有設定都在系統匣圖示的右鍵選單中完成。
+
+## 功能
+
+- 聚光燈游標：可調整顏色、透明度與 48–320 px 圓圈大小；Windows 使用真正的系統游標，macOS/Linux 使用不攔截點擊的透明覆蓋層。
+- 按鍵顯示：在游標所在螢幕中央下方顯示單鍵或組合鍵，不會攔截原本的鍵盤輸入。
+- Caps Lock 狀態：以可拖曳的小圓角矩形顯示 ON／OFF，可設定顯示時間、背景顏色與透明度。
+- macOS 輸入法狀態：可切換為顯示目前的中文／英文輸入來源，與 Caps Lock 燈號分開追蹤。
+- 自動保存：記住各項功能的啟用狀態、外觀設定與 Caps Lock 提示位置。
+- 多螢幕與高 DPI：使用 Qt 邏輯像素定位與繪製。
+
+## 下載桌面版
+
+從 [GitHub Releases](https://github.com/codemee/prkit/releases/latest) 下載，不需另外安裝 Python 或 uv：
+
+| 平台 | 下載檔案 | 啟動方式 |
+| --- | --- | --- |
+| Windows x64 | `PRKit-0.2.1-windows-x64.exe` | 直接開啟執行 |
+| macOS Apple Silicon | `PRKit-0.2.1-macos-arm64.dmg` | 開啟 DMG，將 `PRKit.app` 拖到「Applications」捷徑後啟動 |
+
+Windows 為單一 EXE，已包含執行環境與游標復原 watchdog，不需額外下載檔案。macOS 目前僅提供 Apple Silicon 版。程式啟動後顯示在系統匣／選單列，不會開啟主視窗。
+
+桌面版尚未使用 Windows 發行者憑證或 Apple Developer ID 簽署／公證；macOS 僅使用 ad-hoc 簽章。若系統阻擋你確認來源的下載檔案，請依系統安全提示允許開啟。macOS 按鍵顯示仍需在「輸入監控」允許 `PRKit`；輸入法狀態模式不需此權限。每個下載檔另提供 `.sha256` 校驗檔。
+
+版本標籤會自動觸發 GitHub 雲端打包與成品測試；手動建置可在 Actions 的 **Build desktop apps** 執行，成品在該次執行的 Artifacts。詳細操作見[發佈指南](docs/RELEASING.md)。
+
+## 從 PyPI 安裝
+
+需要先安裝 [uv](https://docs.astral.sh/uv/)，再執行：
+
+```powershell
+uv tool install prkit
+prkit
+```
+
+也可以從已下載的專案目錄安裝：
+
+```powershell
+uv tool install .
+prkit
+```
+
+或直接從 GitHub 安裝最新正式版；`latest` 標籤會在每次正式發布時更新：
+
+```powershell
+uv tool install git+https://github.com/codemee/prkit.git@latest
+prkit
+```
+
+若要固定特定版本，將 `latest` 改成版本標籤，例如 `v0.2.1`。
+
+若安裝後找不到 `prkit` 指令，執行 `uv tool update-shell`，再重新開啟終端機。移除工具可使用 `uv tool uninstall prkit`。
+
+## 使用 uvx 免安裝執行
+
+直接從 PyPI 執行：
+
+```powershell
+uvx prkit
+```
+
+也可以在已下載的專案目錄執行，或直接從 GitHub 執行最新正式版：
+
+```powershell
+uvx --from . prkit
+uvx --from git+https://github.com/codemee/prkit.git@latest prkit
+```
+
+`uvx` 會在隔離環境中準備並執行程式，不會把 `prkit` 持久安裝到工具目錄。
+
+## Caps Lock／輸入法狀態顯示
+
+啟動後，右鍵點擊系統匣圖示，在「Caps Lock／輸入法狀態」勾選「啟用狀態顯示」。此功能可獨立於按鍵顯示使用，啟用時會先顯示目前狀態。
+
+macOS 可在「顯示內容」選擇「Caps Lock 指示燈」或「目前輸入法（中文／英文）」。輸入法模式直接追蹤系統選中的輸入來源：內建注音顯示「中文（注音）」，ABC／美式鍵盤顯示「英文」，其他輸入來源顯示其名稱；使用 Caps Lock、快捷鍵或選單切換都會更新。此模式不需要輸入監控權限，也不會把切換中英文時短暫出現的 Caps Lock 狀態當成大寫鎖定。
+
+- **顯示時間**：設定狀態變化後顯示 1–60 秒；設為 0（「一直顯示」）便會持續顯示目前狀態。
+- **背景顏色與透明度**：透過色塊與滑桿調整，修改時會顯示預覽。
+- **移動位置**：直接用滑鼠左鍵拖曳提示框；拖曳期間暫停隱藏倒數，放開後重新計時並保存位置。下次啟動沿用，若原螢幕已移除則回到可見螢幕。
+
+| 平台 | Caps Lock ON／OFF | 目前輸入法 |
+| --- | --- | --- |
+| Windows | 支援 | 未支援，不顯示選項 |
+| macOS | 支援 | 支援 |
+| Linux X11 | 支援 | 未支援，不顯示選項 |
+| Wayland | 未支援 | 未支援 |
+
+macOS 啟用 Caps Lock 切換輸入方式時，短按切換中英文，按住直到大寫鎖定符號出現才啟用持續大寫。若要跟隨中英文，請選擇輸入法模式；Caps Lock 模式顯示系統鎖定狀態。輸入法模式不推測第三方輸入法在同一來源內的私有中英文狀態。Wayland 啟用時會提示並自動停用。
+
+## 開發
+
+Python 3.12、虛擬環境及相依套件均由 uv 管理：
+
+```powershell
+uv sync
+uv run prkit
+```
+
+品質檢查：
+
+```powershell
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest -q
+```
+
+## 平台注意事項
+
+- Windows：不需要額外權限。啟用聚光燈時會暫時替換系統游標，停用或結束時自動恢復；隨工具一併安裝的獨立 watchdog 會在主程式異常終止時復原游標。
+- macOS：按鍵顯示使用 HID 層的唯讀事件監看，需要在「系統設定 → 隱私權與安全性 → 輸入監控」允許啟動本程式的應用程式（例如 ChatGPT、Terminal 或其他啟動 `prkit` 的終端程式）。監看器不會修改或攔截事件；即使組合鍵被其他快捷鍵工具處理，仍可先顯示按鍵。
+- Linux：完整支援目標為 X11，桌面環境必須提供 StatusNotifierItem 或 XEmbed 系統匣。GNOME 可能需要 AppIndicator 類型的擴充套件。
+- Wayland：受全域輸入與覆蓋層協定限制，按鍵顯示和點擊穿透不保證可用；程式會在選單中顯示警告。
+
+按鍵內容只用於即時畫面顯示，不會寫入設定、檔案或日誌。
+
+實作架構、macOS 原生視窗層級、權限模型與鍵盤事件流程請參閱[技術設計](docs/TECHNICAL.md)。
+
+各版本變更見[版本紀錄](CHANGELOG.md)，雲端打包與 PyPI 發佈程序見[發佈指南](docs/RELEASING.md)。

prkit-0.2.1/README.md

@@ -0,0 +1,122 @@
+# PRKit：簡報瑞士刀
+
+[繁體中文](README.md) | [English](README.en.md)
+
+跨平台的系統匣簡報輔助工具。程式不會開啟主視窗，所有設定都在系統匣圖示的右鍵選單中完成。
+
+## 功能
+
+- 聚光燈游標：可調整顏色、透明度與 48–320 px 圓圈大小；Windows 使用真正的系統游標，macOS/Linux 使用不攔截點擊的透明覆蓋層。
+- 按鍵顯示：在游標所在螢幕中央下方顯示單鍵或組合鍵，不會攔截原本的鍵盤輸入。
+- Caps Lock 狀態：以可拖曳的小圓角矩形顯示 ON／OFF，可設定顯示時間、背景顏色與透明度。
+- macOS 輸入法狀態：可切換為顯示目前的中文／英文輸入來源，與 Caps Lock 燈號分開追蹤。
+- 自動保存：記住各項功能的啟用狀態、外觀設定與 Caps Lock 提示位置。
+- 多螢幕與高 DPI：使用 Qt 邏輯像素定位與繪製。
+
+## 下載桌面版
+
+從 [GitHub Releases](https://github.com/codemee/prkit/releases/latest) 下載，不需另外安裝 Python 或 uv：
+
+| 平台 | 下載檔案 | 啟動方式 |
+| --- | --- | --- |
+| Windows x64 | `PRKit-0.2.1-windows-x64.exe` | 直接開啟執行 |
+| macOS Apple Silicon | `PRKit-0.2.1-macos-arm64.dmg` | 開啟 DMG，將 `PRKit.app` 拖到「Applications」捷徑後啟動 |
+
+Windows 為單一 EXE，已包含執行環境與游標復原 watchdog，不需額外下載檔案。macOS 目前僅提供 Apple Silicon 版。程式啟動後顯示在系統匣／選單列，不會開啟主視窗。
+
+桌面版尚未使用 Windows 發行者憑證或 Apple Developer ID 簽署／公證；macOS 僅使用 ad-hoc 簽章。若系統阻擋你確認來源的下載檔案，請依系統安全提示允許開啟。macOS 按鍵顯示仍需在「輸入監控」允許 `PRKit`；輸入法狀態模式不需此權限。每個下載檔另提供 `.sha256` 校驗檔。
+
+版本標籤會自動觸發 GitHub 雲端打包與成品測試；手動建置可在 Actions 的 **Build desktop apps** 執行，成品在該次執行的 Artifacts。詳細操作見[發佈指南](docs/RELEASING.md)。
+
+## 從 PyPI 安裝
+
+需要先安裝 [uv](https://docs.astral.sh/uv/)，再執行：
+
+```powershell
+uv tool install prkit
+prkit
+```
+
+也可以從已下載的專案目錄安裝：
+
+```powershell
+uv tool install .
+prkit
+```
+
+或直接從 GitHub 安裝最新正式版；`latest` 標籤會在每次正式發布時更新：
+
+```powershell
+uv tool install git+https://github.com/codemee/prkit.git@latest
+prkit
+```
+
+若要固定特定版本，將 `latest` 改成版本標籤，例如 `v0.2.1`。
+
+若安裝後找不到 `prkit` 指令，執行 `uv tool update-shell`，再重新開啟終端機。移除工具可使用 `uv tool uninstall prkit`。
+
+## 使用 uvx 免安裝執行
+
+直接從 PyPI 執行：
+
+```powershell
+uvx prkit
+```
+
+也可以在已下載的專案目錄執行，或直接從 GitHub 執行最新正式版：
+
+```powershell
+uvx --from . prkit
+uvx --from git+https://github.com/codemee/prkit.git@latest prkit
+```
+
+`uvx` 會在隔離環境中準備並執行程式，不會把 `prkit` 持久安裝到工具目錄。
+
+## Caps Lock／輸入法狀態顯示
+
+啟動後，右鍵點擊系統匣圖示，在「Caps Lock／輸入法狀態」勾選「啟用狀態顯示」。此功能可獨立於按鍵顯示使用，啟用時會先顯示目前狀態。
+
+macOS 可在「顯示內容」選擇「Caps Lock 指示燈」或「目前輸入法（中文／英文）」。輸入法模式直接追蹤系統選中的輸入來源：內建注音顯示「中文（注音）」，ABC／美式鍵盤顯示「英文」，其他輸入來源顯示其名稱；使用 Caps Lock、快捷鍵或選單切換都會更新。此模式不需要輸入監控權限，也不會把切換中英文時短暫出現的 Caps Lock 狀態當成大寫鎖定。
+
+- **顯示時間**：設定狀態變化後顯示 1–60 秒；設為 0（「一直顯示」）便會持續顯示目前狀態。
+- **背景顏色與透明度**：透過色塊與滑桿調整，修改時會顯示預覽。
+- **移動位置**：直接用滑鼠左鍵拖曳提示框；拖曳期間暫停隱藏倒數，放開後重新計時並保存位置。下次啟動沿用，若原螢幕已移除則回到可見螢幕。
+
+| 平台 | Caps Lock ON／OFF | 目前輸入法 |
+| --- | --- | --- |
+| Windows | 支援 | 未支援，不顯示選項 |
+| macOS | 支援 | 支援 |
+| Linux X11 | 支援 | 未支援，不顯示選項 |
+| Wayland | 未支援 | 未支援 |
+
+macOS 啟用 Caps Lock 切換輸入方式時，短按切換中英文，按住直到大寫鎖定符號出現才啟用持續大寫。若要跟隨中英文，請選擇輸入法模式；Caps Lock 模式顯示系統鎖定狀態。輸入法模式不推測第三方輸入法在同一來源內的私有中英文狀態。Wayland 啟用時會提示並自動停用。
+
+## 開發
+
+Python 3.12、虛擬環境及相依套件均由 uv 管理：
+
+```powershell
+uv sync
+uv run prkit
+```
+
+品質檢查：
+
+```powershell
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest -q
+```
+
+## 平台注意事項
+
+- Windows：不需要額外權限。啟用聚光燈時會暫時替換系統游標，停用或結束時自動恢復；隨工具一併安裝的獨立 watchdog 會在主程式異常終止時復原游標。
+- macOS：按鍵顯示使用 HID 層的唯讀事件監看，需要在「系統設定 → 隱私權與安全性 → 輸入監控」允許啟動本程式的應用程式（例如 ChatGPT、Terminal 或其他啟動 `prkit` 的終端程式）。監看器不會修改或攔截事件；即使組合鍵被其他快捷鍵工具處理，仍可先顯示按鍵。
+- Linux：完整支援目標為 X11，桌面環境必須提供 StatusNotifierItem 或 XEmbed 系統匣。GNOME 可能需要 AppIndicator 類型的擴充套件。
+- Wayland：受全域輸入與覆蓋層協定限制，按鍵顯示和點擊穿透不保證可用；程式會在選單中顯示警告。
+
+按鍵內容只用於即時畫面顯示，不會寫入設定、檔案或日誌。
+
+實作架構、macOS 原生視窗層級、權限模型與鍵盤事件流程請參閱[技術設計](docs/TECHNICAL.md)。
+
+各版本變更見[版本紀錄](CHANGELOG.md)，雲端打包與 PyPI 發佈程序見[發佈指南](docs/RELEASING.md)。

{prkit-0.1.1 → prkit-0.2.1}/pyproject.toml

@@ -1,12 +1,13 @@
 [project]
 name = "prkit"
-version = "0.1.1"
+version = "0.2.1"
 description = "A cross-platform system-tray presentation toolkit"
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
     "pynput>=1.8.2",
     "pyobjc-framework-cocoa>=12.2.1 ; sys_platform == 'darwin'",
+    "pyobjc-framework-quartz>=12.2.1 ; sys_platform == 'darwin'",
     "pyside6>=6.11.1",
     "python-xlib>=0.33 ; sys_platform == 'linux'",
 ]
@@ -47,6 +48,7 @@ requires = ["uv_build>=0.11.28,<0.12.0"]
 build-backend = "uv_build"
 
 [dependency-groups]
+build = ["pyinstaller>=6.16,<7"]
 dev = [
     "pytest>=9.1.1",
     "pytest-qt>=4.5.0",

{prkit-0.1.1 → prkit-0.2.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "prkit"
-version = "0.1.1"
+version = "0.2.1"
 description = "A cross-platform system-tray presentation toolkit"
 readme = "README.md"
 authors = [
@@ -10,6 +10,7 @@ requires-python = ">=3.12"
 dependencies = [
     "pynput>=1.8.2",
     "pyobjc-framework-cocoa>=12.2.1 ; sys_platform == 'darwin'",
+    "pyobjc-framework-quartz>=12.2.1 ; sys_platform == 'darwin'",
     "pyside6>=6.11.1",
     "python-xlib>=0.33 ; sys_platform == 'linux'",
 ]
@@ -39,6 +40,9 @@ requires = ["uv_build>=0.11.28,<0.12.0"]
 build-backend = "uv_build"
 
 [dependency-groups]
+build = [
+    "pyinstaller>=6.16,<7",
+]
 dev = [
     "pytest>=9.1.1",
     "pytest-qt>=4.5.0",

{prkit-0.1.1 → prkit-0.2.1}/src/prkit/__init__.py

@@ -1,3 +1,3 @@
 """Presentation tools for the system tray."""
 
-__version__ = "0.1.1"
+__version__ = "0.2.1"

{prkit-0.1.1 → prkit-0.2.1}/src/prkit/app.py

@@ -7,8 +7,10 @@ from contextlib import suppress
 from PySide6.QtCore import QObject, QSignalBlocker, QTimer
 from PySide6.QtWidgets import QApplication, QMessageBox
 
+from prkit.capslock import CapsLockMonitor
+from prkit.input_source import InputSourceMonitor
 from prkit.keyboard import KeyboardMonitor
-from prkit.overlays import KeystrokeOverlay
+from prkit.overlays import CapsLockOverlay, KeystrokeOverlay
 from prkit.settings import SettingsStore, SettingsStoreProtocol
 from prkit.spotlight import SpotlightBackend, create_spotlight
 from prkit.tray import TrayController
@@ -21,6 +23,8 @@ class AppController(QObject):
         store: SettingsStoreProtocol | None = None,
         monitor: KeyboardMonitor | None = None,
         spotlight: SpotlightBackend | None = None,
+        capslock_monitor: CapsLockMonitor | None = None,
+        input_source_monitor: InputSourceMonitor | None = None,
     ) -> None:
         super().__init__()
         self._app = app
@@ -28,6 +32,11 @@ class AppController(QObject):
         self.settings = self._store.load()
         self.spotlight = spotlight or create_spotlight(self.settings.spotlight)
         self.keystroke = KeystrokeOverlay(self.settings.keystroke)
+        self.capslock = CapsLockOverlay(self.settings.capslock)
+        self.capslock_monitor = capslock_monitor or CapsLockMonitor(self)
+        self.input_source_monitor = input_source_monitor or InputSourceMonitor(self)
+        if sys.platform != "darwin":
+            self.settings.capslock.mode = "capslock"
         self.monitor = monitor or KeyboardMonitor(self)
         self.tray = TrayController(self.settings, self)
         self._shutting_down = False
@@ -43,6 +52,16 @@ class AppController(QObject):
             keystroke_opacity=self.set_keystroke_opacity,
         )
         self.tray.exit_requested.connect(self.shutdown)
+        self.tray.panel.capslock_enabled_changed.connect(self.set_capslock_enabled)
+        self.tray.panel.capslock_color_changed.connect(self.set_capslock_color)
+        self.tray.panel.capslock_opacity_changed.connect(self.set_capslock_opacity)
+        self.tray.panel.capslock_duration_changed.connect(self.set_capslock_duration)
+        self.tray.panel.capslock_mode_changed.connect(self.set_capslock_mode)
+        self.capslock_monitor.changed.connect(self._show_capslock_state)
+        self.input_source_monitor.changed.connect(self._show_input_source)
+        self.input_source_monitor.failed.connect(self._capslock_failed)
+        self.capslock_monitor.failed.connect(self._capslock_failed)
+        self.capslock.position_changed.connect(self._save_capslock_position)
         self.tray.menu.aboutToShow.connect(self.spotlight.sync_position)
         self.tray.menu.aboutToHide.connect(self._start_pending_keyboard_monitor)
         self.monitor.chord_pressed.connect(self.keystroke.show_chord)
@@ -55,6 +74,65 @@ class AppController(QObject):
         self.spotlight.set_enabled(self.settings.spotlight.enabled)
         if self.settings.keystroke.enabled:
             self.set_keystroke_enabled(True)
+        if self.settings.capslock.enabled:
+            self.set_capslock_enabled(True)
+
+    def set_capslock_enabled(self, enabled: bool) -> None:
+        self.settings.capslock.enabled = enabled
+        self.capslock_monitor.stop()
+        self.input_source_monitor.stop()
+        self.capslock.hide_now()
+        if enabled:
+            if self.settings.capslock.mode == "input_source":
+                self.input_source_monitor.start()
+            else:
+                self.capslock_monitor.start()
+        self._save()
+
+    def set_capslock_mode(self, mode: str) -> None:
+        if mode not in {"capslock", "input_source"}:
+            return
+        if mode == "input_source" and sys.platform != "darwin":
+            return
+        self.settings.capslock.mode = mode
+        combo = self.tray.panel.capslock_mode
+        with QSignalBlocker(combo):
+            combo.setCurrentIndex(combo.findData(mode))
+        self.set_capslock_enabled(self.settings.capslock.enabled)
+
+    def _show_capslock_state(self, state: bool) -> None:
+        if self.settings.capslock.mode == "capslock":
+            self.capslock.show_state(state)
+
+    def _show_input_source(self, name: str) -> None:
+        if self.settings.capslock.mode == "input_source":
+            self.capslock.show_input_source(name)
+
+    def set_capslock_color(self, color: str) -> None:
+        self.settings.capslock.color = color
+        self._apply_capslock_settings()
+
+    def set_capslock_opacity(self, opacity: int) -> None:
+        self.settings.capslock.opacity = opacity
+        self._apply_capslock_settings()
+
+    def set_capslock_duration(self, duration: int) -> None:
+        self.settings.capslock.duration = duration
+        self._apply_capslock_settings()
+
+    def _apply_capslock_settings(self) -> None:
+        self.capslock.apply_settings()
+        self._save()
+
+    def _save_capslock_position(self, x: int, y: int) -> None:
+        self.settings.capslock.x, self.settings.capslock.y = x, y
+        self._save()
+
+    def _capslock_failed(self, message: str) -> None:
+        self.set_capslock_enabled(False)
+        with QSignalBlocker(self.tray.panel.capslock_enabled):
+            self.tray.panel.capslock_enabled.setChecked(False)
+        self.tray.notify_warning(f"無法顯示鍵盤狀態：{message}")
 
     def set_spotlight_enabled(self, enabled: bool) -> None:
         try:
@@ -159,6 +237,9 @@ class AppController(QObject):
 
     def cleanup(self) -> None:
         self._keystroke_start_pending = False
+        self.capslock_monitor.stop()
+        self.input_source_monitor.stop()
+        self.capslock.hide_now()
         self.monitor.stop()
         self.spotlight.set_enabled(False)
         self.keystroke.hide_now()

prkit-0.2.1/src/prkit/capslock.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from typing import Any
+
+from PySide6.QtCore import QObject, QTimer, Signal, Slot
+
+from prkit.platform import is_wayland
+
+
+class CapsLockMonitor(QObject):
+    """Read the actual lock state independently of the keystroke display."""
+
+    changed = Signal(bool)
+    failed = Signal(str)
+    _refresh = Signal()
+
+    def __init__(self, parent: QObject | None = None) -> None:
+        super().__init__(parent)
+        self._read: Callable[[], bool] | None = None
+        self._connection: Any = None
+        self._listener: Any = None
+        self._state: bool | None = None
+        self._timer = QTimer(self)
+        self._timer.setInterval(100)
+        self._timer.timeout.connect(self._poll)
+        self._refresh.connect(self._poll)
+
+    def start(self) -> None:
+        self.stop()
+        try:
+            if sys.platform == "win32":
+                import ctypes
+
+                self._read = lambda: bool(ctypes.windll.user32.GetKeyState(0x14) & 1)
+            elif sys.platform == "darwin":
+                from prkit.mac_capslock import MacCapsLockState
+
+                self._connection = MacCapsLockState()
+                self._read = self._connection.read
+            elif sys.platform.startswith("linux") and not is_wayland():
+                from Xlib import X, display
+
+                self._connection = display.Display()
+                root = self._connection.screen().root
+                self._read = lambda: bool(root.query_pointer().mask & X.LockMask)
+            else:
+                raise RuntimeError("此平台不支援 Caps Lock 狀態偵測（Linux 需要 X11）。")
+            self._poll()
+            if self._read is not None:
+                if sys.platform == "darwin":
+                    self._start_macos_listener()
+                self._timer.start()
+        except Exception as error:
+            self.stop()
+            self.failed.emit(str(error))
+
+    def stop(self) -> None:
+        self._timer.stop()
+        if self._listener is not None:
+            self._listener.stop()
+            self._listener = None
+        self._read = None
+        self._state = None
+        if self._connection is not None:
+            self._connection.close()
+            self._connection = None
+
+    def _start_macos_listener(self) -> None:
+        from prkit.mac_keyboard import MacKeyboardListener
+
+        # Event flags can be transient or disagree with the lock indicator.
+        # Events only wake the Qt thread to query the same source as polling.
+        listener = MacKeyboardListener(
+            on_press=lambda key: None,
+            on_release=lambda key: None,
+            on_capslock=lambda state: self._refresh.emit(),
+        )
+        success, _ = listener.start()
+        if success:
+            self._listener = listener
+        else:
+            listener.stop()
+
+    @Slot(bool)
+    def _set_state(self, state: bool) -> None:
+        if self._read is not None and state != self._state:
+            self._state = state
+            self.changed.emit(state)
+
+    @Slot()
+    def _poll(self) -> None:
+        try:
+            if self._read is None:
+                return
+            self._set_state(self._read())
+        except Exception as error:
+            self.stop()
+            self.failed.emit(str(error))

{prkit-0.1.1 → prkit-0.2.1}/src/prkit/cursor_watchdog.py

@@ -6,6 +6,7 @@ from ctypes import wintypes
 
 SPI_SETCURSORS = 0x0057
 SYNCHRONIZE = 0x00100000
+EVENT_MODIFY_STATE = 0x0002
 WAIT_OBJECT_0 = 0
 INFINITE = 0xFFFFFFFF
 
@@ -14,10 +15,20 @@ def restore_system_cursors() -> None:
     ctypes.windll.user32.SystemParametersInfoW(SPI_SETCURSORS, 0, None, 0)
 
 
-def watch(parent_pid: int, stop_event_name: str) -> int:
+def watch(parent_pid: int, stop_event_name: str, ready_event_name: str | None = None) -> int:
     kernel32 = ctypes.windll.kernel32
     kernel32.OpenProcess.restype = wintypes.HANDLE
+    kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
     kernel32.OpenEventW.restype = wintypes.HANDLE
+    kernel32.OpenEventW.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.LPCWSTR]
+    kernel32.SetEvent.argtypes = [wintypes.HANDLE]
+    kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+    kernel32.WaitForMultipleObjects.argtypes = [
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.HANDLE),
+        wintypes.BOOL,
+        wintypes.DWORD,
+    ]
     parent = kernel32.OpenProcess(SYNCHRONIZE, False, parent_pid)
     stop_event = kernel32.OpenEventW(SYNCHRONIZE, False, stop_event_name)
     if not parent or not stop_event:
@@ -28,6 +39,15 @@ def watch(parent_pid: int, stop_event_name: str) -> int:
             kernel32.CloseHandle(stop_event)
         return 1
     try:
+        if ready_event_name is not None:
+            ready = kernel32.OpenEventW(EVENT_MODIFY_STATE, False, ready_event_name)
+            if not ready:
+                return 1
+            try:
+                if not kernel32.SetEvent(ready):
+                    return 1
+            finally:
+                kernel32.CloseHandle(ready)
         handles = (wintypes.HANDLE * 2)(parent, stop_event)
         result = kernel32.WaitForMultipleObjects(2, handles, False, INFINITE)
         if result == WAIT_OBJECT_0:
@@ -39,9 +59,9 @@ def watch(parent_pid: int, stop_event_name: str) -> int:
 
 
 def main() -> int:
-    if sys.platform != "win32" or len(sys.argv) != 3:
+    if sys.platform != "win32" or len(sys.argv) not in {3, 4}:
         return 2
-    return watch(int(sys.argv[1]), sys.argv[2])
+    return watch(int(sys.argv[1]), sys.argv[2], sys.argv[3] if len(sys.argv) == 4 else None)
 
 
 if __name__ == "__main__":