prkit 0.1.0__tar.gz

prkit-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.3
+Name: prkit
+Version: 0.1.0
+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: pyside6>=6.11.1
+Requires-Dist: python-xlib>=0.33 ; sys_platform == 'linux'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/codemee/prtools
+Project-URL: Repository, https://github.com/codemee/prtools
+Project-URL: Issues, https://github.com/codemee/prtools/issues
+Description-Content-Type: text/markdown
+
+# PRKit：簡報瑞士刀
+
+[繁體中文](README.md) | [English](README.en.md)
+
+跨平台的系統匣簡報輔助工具。程式不會開啟主視窗，所有設定都在系統匣圖示的右鍵選單中完成。
+
+## 功能
+
+- 聚光燈游標：可調整顏色、透明度與 48–320 px 圓圈大小；Windows 使用真正的系統游標，macOS/Linux 使用不攔截點擊的透明覆蓋層。
+- 按鍵顯示：在游標所在螢幕中央下方顯示單鍵或組合鍵，不會攔截原本的鍵盤輸入。
+- 自動保存：記住兩項功能的啟用狀態與外觀設定。
+- 多螢幕與高 DPI：使用 Qt 邏輯像素定位與繪製。
+
+## 從 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/prtools.git@latest
+prkit
+```
+
+若要固定特定版本，將 `latest` 改成版本標籤，例如 `v0.1.0`。
+
+若安裝後找不到 `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/prtools.git@latest prkit
+```
+
+`uvx` 會在隔離環境中準備並執行程式，不會把 `prkit` 持久安裝到工具目錄。
+
+## 開發
+
+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)。

prkit-0.1.0/README.md

@@ -0,0 +1,84 @@
+# PRKit：簡報瑞士刀
+
+[繁體中文](README.md) | [English](README.en.md)
+
+跨平台的系統匣簡報輔助工具。程式不會開啟主視窗，所有設定都在系統匣圖示的右鍵選單中完成。
+
+## 功能
+
+- 聚光燈游標：可調整顏色、透明度與 48–320 px 圓圈大小；Windows 使用真正的系統游標，macOS/Linux 使用不攔截點擊的透明覆蓋層。
+- 按鍵顯示：在游標所在螢幕中央下方顯示單鍵或組合鍵，不會攔截原本的鍵盤輸入。
+- 自動保存：記住兩項功能的啟用狀態與外觀設定。
+- 多螢幕與高 DPI：使用 Qt 邏輯像素定位與繪製。
+
+## 從 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/prtools.git@latest
+prkit
+```
+
+若要固定特定版本，將 `latest` 改成版本標籤，例如 `v0.1.0`。
+
+若安裝後找不到 `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/prtools.git@latest prkit
+```
+
+`uvx` 會在隔離環境中準備並執行程式，不會把 `prkit` 持久安裝到工具目錄。
+
+## 開發
+
+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)。

prkit-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "prkit"
+version = "0.1.0"
+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'",
+    "pyside6>=6.11.1",
+    "python-xlib>=0.33 ; sys_platform == 'linux'",
+]
+
+[[project.authors]]
+name = "meebox"
+email = "meebox@gmail.com"
+
+[project.scripts]
+prkit = "prkit.app:main"
+prkit-cursor-watchdog = "prkit.cursor_watchdog:main"
+
+[project.urls]
+Homepage = "https://github.com/codemee/prtools"
+Repository = "https://github.com/codemee/prtools"
+Issues = "https://github.com/codemee/prtools/issues"
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.28,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-qt>=4.5.0",
+    "ruff>=0.15.21",
+]

prkit-0.1.0/pyproject.toml.orig

@@ -0,0 +1,46 @@
+[project]
+name = "prkit"
+version = "0.1.0"
+description = "A cross-platform system-tray presentation toolkit"
+readme = "README.md"
+authors = [
+    { name = "meebox", email = "meebox@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "pynput>=1.8.2",
+    "pyobjc-framework-cocoa>=12.2.1 ; sys_platform == 'darwin'",
+    "pyside6>=6.11.1",
+    "python-xlib>=0.33 ; sys_platform == 'linux'",
+]
+
+[project.scripts]
+prkit = "prkit.app:main"
+prkit-cursor-watchdog = "prkit.cursor_watchdog:main"
+
+[project.urls]
+Homepage = "https://github.com/codemee/prtools"
+Repository = "https://github.com/codemee/prtools"
+Issues = "https://github.com/codemee/prtools/issues"
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[build-system]
+requires = ["uv_build>=0.11.28,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-qt>=4.5.0",
+    "ruff>=0.15.21",
+]

prkit-0.1.0/src/prkit/__init__.py

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

prkit-0.1.0/src/prkit/__main__.py

@@ -0,0 +1,3 @@
+from prkit.app import main
+
+raise SystemExit(main())

prkit-0.1.0/src/prkit/app.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import sys
+from collections.abc import Sequence
+from contextlib import suppress
+
+from PySide6.QtCore import QObject, QSignalBlocker, QTimer
+from PySide6.QtWidgets import QApplication, QMessageBox
+
+from prkit.keyboard import KeyboardMonitor
+from prkit.overlays import KeystrokeOverlay
+from prkit.settings import SettingsStore, SettingsStoreProtocol
+from prkit.spotlight import SpotlightBackend, create_spotlight
+from prkit.tray import TrayController
+
+
+class AppController(QObject):
+    def __init__(
+        self,
+        app: QApplication,
+        store: SettingsStoreProtocol | None = None,
+        monitor: KeyboardMonitor | None = None,
+        spotlight: SpotlightBackend | None = None,
+    ) -> None:
+        super().__init__()
+        self._app = app
+        self._store = store or SettingsStore()
+        self.settings = self._store.load()
+        self.spotlight = spotlight or create_spotlight(self.settings.spotlight)
+        self.keystroke = KeystrokeOverlay(self.settings.keystroke)
+        self.monitor = monitor or KeyboardMonitor(self)
+        self.tray = TrayController(self.settings, self)
+        self._shutting_down = False
+        self._keystroke_start_pending = False
+
+        self.tray.connect_settings(
+            spotlight_enabled=self.set_spotlight_enabled,
+            spotlight_color=self.set_spotlight_color,
+            spotlight_opacity=self.set_spotlight_opacity,
+            spotlight_size=self.set_spotlight_size,
+            keystroke_enabled=self.set_keystroke_enabled,
+            keystroke_color=self.set_keystroke_color,
+            keystroke_opacity=self.set_keystroke_opacity,
+        )
+        self.tray.exit_requested.connect(self.shutdown)
+        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)
+        self.monitor.all_released.connect(self.keystroke.keys_released)
+        self.monitor.failed.connect(self._keyboard_failed)
+        self._app.aboutToQuit.connect(self.cleanup)
+
+    def start(self) -> None:
+        self.tray.show()
+        self.spotlight.set_enabled(self.settings.spotlight.enabled)
+        if self.settings.keystroke.enabled:
+            self.set_keystroke_enabled(True)
+
+    def set_spotlight_enabled(self, enabled: bool) -> None:
+        try:
+            self.spotlight.set_enabled(enabled)
+        except Exception as error:
+            self._disable_spotlight_ui()
+            self.tray.notify_warning(f"無法啟用聚光燈游標：{error}")
+            return
+        self.settings.spotlight.enabled = enabled
+        self._save()
+
+    def set_spotlight_color(self, color: str) -> None:
+        self.settings.spotlight.color = color
+        self._apply_spotlight_appearance()
+
+    def set_spotlight_opacity(self, opacity: int) -> None:
+        self.settings.spotlight.opacity = opacity
+        self._apply_spotlight_appearance()
+
+    def set_spotlight_size(self, size: int) -> None:
+        self.settings.spotlight.size = size
+        self._apply_spotlight_appearance()
+
+    def _apply_spotlight_appearance(self) -> None:
+        value = self.settings.spotlight
+        try:
+            self.spotlight.set_appearance(value.color, value.opacity, value.size)
+        except Exception as error:
+            self._disable_spotlight_ui()
+            self.tray.notify_warning(f"無法更新聚光燈游標：{error}")
+            return
+        self._save()
+
+    def _disable_spotlight_ui(self) -> None:
+        with suppress(Exception):
+            self.spotlight.set_enabled(False)
+        self.settings.spotlight.enabled = False
+        with QSignalBlocker(self.tray.panel.spotlight_enabled):
+            self.tray.panel.set_spotlight_enabled(False)
+        self._save()
+
+    def set_keystroke_enabled(self, enabled: bool) -> None:
+        if enabled:
+            self._keystroke_start_pending = True
+            if not self.tray.menu.isVisible():
+                QTimer.singleShot(0, self._start_pending_keyboard_monitor)
+            return
+        else:
+            self._keystroke_start_pending = False
+            self.monitor.stop()
+            self.keystroke.hide_now()
+        self.settings.keystroke.enabled = enabled
+        self._save()
+
+    def _start_pending_keyboard_monitor(self) -> None:
+        if not self._keystroke_start_pending:
+            return
+        self._keystroke_start_pending = False
+        success, error = self.monitor.start()
+        if not success:
+            self._disable_keystroke_ui()
+            self.tray.notify_warning(f"無法啟用按鍵顯示：{error or '未知錯誤'}")
+            return
+        self.settings.keystroke.enabled = True
+        self._save()
+
+    def set_keystroke_color(self, color: str) -> None:
+        self.settings.keystroke.color = color
+        self._apply_keystroke_appearance()
+
+    def set_keystroke_opacity(self, opacity: int) -> None:
+        self.settings.keystroke.opacity = opacity
+        self._apply_keystroke_appearance()
+
+    def _apply_keystroke_appearance(self) -> None:
+        value = self.settings.keystroke
+        self.keystroke.set_appearance(value.color, value.opacity)
+        self._save()
+
+    def _keyboard_failed(self, message: str) -> None:
+        self._disable_keystroke_ui()
+        self.tray.notify_warning(f"按鍵監聽已停止：{message}")
+
+    def _disable_keystroke_ui(self) -> None:
+        self._keystroke_start_pending = False
+        self.monitor.stop()
+        self.keystroke.hide_now()
+        self.settings.keystroke.enabled = False
+        with QSignalBlocker(self.tray.panel.keystroke_enabled):
+            self.tray.panel.set_keystroke_enabled(False)
+        self._save()
+
+    def _save(self) -> None:
+        self._store.save(self.settings)
+
+    def shutdown(self) -> None:
+        if self._shutting_down:
+            return
+        self._shutting_down = True
+        self.cleanup()
+        self._app.quit()
+
+    def cleanup(self) -> None:
+        self._keystroke_start_pending = False
+        self.monitor.stop()
+        self.spotlight.set_enabled(False)
+        self.keystroke.hide_now()
+        self.tray.hide()
+
+
+def create_application(arguments: Sequence[str] | None = None) -> QApplication:
+    app = QApplication(list(arguments) if arguments is not None else sys.argv)
+    app.setApplicationName("簡報瑞士刀")
+    app.setOrganizationName("prkit")
+    app.setQuitOnLastWindowClosed(False)
+    return app
+
+
+def main() -> int:
+    app = create_application()
+    if not TrayController.is_available():
+        QMessageBox.critical(None, "簡報瑞士刀", "此桌面環境沒有可用的系統匣。")
+        return 1
+    controller = AppController(app)
+    controller.start()
+    return app.exec()

prkit-0.1.0/src/prkit/cursor_watchdog.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import ctypes
+import sys
+from ctypes import wintypes
+
+SPI_SETCURSORS = 0x0057
+SYNCHRONIZE = 0x00100000
+WAIT_OBJECT_0 = 0
+INFINITE = 0xFFFFFFFF
+
+
+def restore_system_cursors() -> None:
+    ctypes.windll.user32.SystemParametersInfoW(SPI_SETCURSORS, 0, None, 0)
+
+
+def watch(parent_pid: int, stop_event_name: str) -> int:
+    kernel32 = ctypes.windll.kernel32
+    kernel32.OpenProcess.restype = wintypes.HANDLE
+    kernel32.OpenEventW.restype = wintypes.HANDLE
+    parent = kernel32.OpenProcess(SYNCHRONIZE, False, parent_pid)
+    stop_event = kernel32.OpenEventW(SYNCHRONIZE, False, stop_event_name)
+    if not parent or not stop_event:
+        restore_system_cursors()
+        if parent:
+            kernel32.CloseHandle(parent)
+        if stop_event:
+            kernel32.CloseHandle(stop_event)
+        return 1
+    try:
+        handles = (wintypes.HANDLE * 2)(parent, stop_event)
+        result = kernel32.WaitForMultipleObjects(2, handles, False, INFINITE)
+        if result == WAIT_OBJECT_0:
+            restore_system_cursors()
+    finally:
+        kernel32.CloseHandle(parent)
+        kernel32.CloseHandle(stop_event)
+    return 0
+
+
+def main() -> int:
+    if sys.platform != "win32" or len(sys.argv) != 3:
+        return 2
+    return watch(int(sys.argv[1]), sys.argv[2])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

prkit-0.1.0/src/prkit/icon.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from PySide6.QtCore import QByteArray
+from PySide6.QtGui import QIcon, QPainter, QPixmap
+from PySide6.QtSvg import QSvgRenderer
+
+TRAY_ICON_SVG = b"""<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+<defs><radialGradient id="g"><stop offset="0" stop-color="#fff"/>
+<stop offset=".18" stop-color="#ffb3b3"/><stop offset=".48" stop-color="#f44336"/>
+<stop offset="1" stop-color="#8b0000" stop-opacity=".25"/></radialGradient></defs>
+<circle cx="32" cy="32" r="27" fill="url(#g)"/><circle cx="32" cy="32" r="8" fill="#fff"/>
+</svg>"""
+
+
+def tray_icon() -> QIcon:
+    renderer = QSvgRenderer(QByteArray(TRAY_ICON_SVG))
+    icon = QIcon()
+    for size in (16, 20, 24, 32, 48, 64):
+        pixmap = QPixmap(size, size)
+        pixmap.fill("transparent")
+        painter = QPainter(pixmap)
+        renderer.render(painter)
+        painter.end()
+        icon.addPixmap(pixmap)
+    return icon

prkit-0.1.0/src/prkit/keyboard.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+from PySide6.QtCore import QObject, Signal
+
+from prkit.keys import KeyChordTracker
+
+
+class KeyboardMonitor(QObject):
+    chord_pressed = Signal(str)
+    all_released = Signal()
+    failed = Signal(str)
+
+    def __init__(self, parent: QObject | None = None) -> None:
+        super().__init__(parent)
+        self._listener: Any | None = None
+        self._tracker = KeyChordTracker()
+
+    @property
+    def running(self) -> bool:
+        return self._listener is not None
+
+    def start(self) -> tuple[bool, str | None]:
+        if self._listener is not None:
+            return True, None
+        try:
+            if sys.platform == "darwin":
+                from prkit.mac_keyboard import MacKeyboardListener
+
+                listener = MacKeyboardListener(self._on_press, self._on_release)
+                success, error = listener.start()
+                if not success:
+                    return False, error
+            else:
+                from pynput import keyboard
+
+                listener = keyboard.Listener(on_press=self._on_press, on_release=self._on_release)
+                listener.start()
+                listener.wait()
+            self._listener = listener
+        except Exception as error:  # pynput exposes backend-specific exceptions
+            self._listener = None
+            self._tracker.clear()
+            return False, str(error)
+        return True, None
+
+    def stop(self) -> None:
+        listener, self._listener = self._listener, None
+        self._tracker.clear()
+        if listener is not None:
+            listener.stop()
+
+    def _on_press(self, key: object) -> None:
+        try:
+            label = self._tracker.press(key)
+            if label:
+                self.chord_pressed.emit(label)
+        except Exception as error:
+            self.failed.emit(str(error))
+
+    def _on_release(self, key: object) -> None:
+        try:
+            if self._tracker.release(key):
+                self.all_released.emit()
+        except Exception as error:
+            self.failed.emit(str(error))