prkit 0.1.0__py3-none-any.whl

prkit/__init__.py

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

prkit/__main__.py

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

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/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/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/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))

prkit/keys.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import sys
+from collections.abc import Hashable
+from dataclasses import dataclass, field
+
+MODIFIER_ORDER = ("Ctrl", "⌘", "Alt", "⌥", "Shift", "Meta")
+
+SPECIAL_KEYS = {
+    "alt": "⌥" if sys.platform == "darwin" else "Alt",
+    "alt_l": "⌥" if sys.platform == "darwin" else "Alt",
+    "alt_r": "⌥" if sys.platform == "darwin" else "Alt",
+    "alt_gr": "AltGr",
+    "backspace": "Backspace",
+    "caps_lock": "Caps Lock",
+    "cmd": "⌘" if sys.platform == "darwin" else "Meta",
+    "cmd_l": "⌘" if sys.platform == "darwin" else "Meta",
+    "cmd_r": "⌘" if sys.platform == "darwin" else "Meta",
+    "ctrl": "Ctrl",
+    "ctrl_l": "Ctrl",
+    "ctrl_r": "Ctrl",
+    "delete": "Delete",
+    "down": "↓",
+    "end": "End",
+    "enter": "Enter",
+    "esc": "Esc",
+    "f1": "F1",
+    "f2": "F2",
+    "f3": "F3",
+    "f4": "F4",
+    "f5": "F5",
+    "f6": "F6",
+    "f7": "F7",
+    "f8": "F8",
+    "f9": "F9",
+    "f10": "F10",
+    "f11": "F11",
+    "f12": "F12",
+    "home": "Home",
+    "insert": "Insert",
+    "left": "←",
+    "media_next": "Next Track",
+    "media_play_pause": "Play/Pause",
+    "media_previous": "Previous Track",
+    "page_down": "Page Down",
+    "page_up": "Page Up",
+    "pause": "Pause",
+    "print_screen": "Print Screen",
+    "right": "→",
+    "scroll_lock": "Scroll Lock",
+    "shift": "Shift",
+    "shift_l": "Shift",
+    "shift_r": "Shift",
+    "space": "Space",
+    "tab": "Tab",
+    "up": "↑",
+}
+
+
+def key_identity(key: object) -> Hashable:
+    name = getattr(key, "name", None)
+    if name:
+        return ("name", name)
+    vk = getattr(key, "vk", None)
+    if vk is not None:
+        return ("vk", vk)
+    char = getattr(key, "char", None)
+    if char is not None:
+        return ("char", char)
+    return ("object", str(key))
+
+
+def key_label(key: object) -> str:
+    name = getattr(key, "name", None)
+    if name:
+        return SPECIAL_KEYS.get(name, name.replace("_", " ").title())
+    char = getattr(key, "char", None)
+    if char is not None:
+        if char == " ":
+            return "Space"
+        return char.upper() if len(char) == 1 and char.isalpha() else char
+    text = str(key)
+    if text.startswith("Key."):
+        text = text[4:]
+    return SPECIAL_KEYS.get(text, text.replace("_", " ").title())
+
+
+@dataclass(slots=True)
+class KeyChordTracker:
+    _pressed: dict[Hashable, str] = field(default_factory=dict)
+
+    def press(self, key: object) -> str | None:
+        identity = key_identity(key)
+        if identity in self._pressed:
+            return None
+        self._pressed[identity] = key_label(key)
+        return self.label
+
+    def release(self, key: object) -> bool:
+        self._pressed.pop(key_identity(key), None)
+        return not self._pressed
+
+    def clear(self) -> None:
+        self._pressed.clear()
+
+    @property
+    def label(self) -> str:
+        labels = list(dict.fromkeys(self._pressed.values()))
+        modifiers = [label for label in MODIFIER_ORDER if label in labels]
+        ordinary = [label for label in labels if label not in MODIFIER_ORDER]
+        return " + ".join([*modifiers, *ordinary])

prkit/mac_keyboard.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from CoreFoundation import (
+    CFMachPortCreateRunLoopSource,
+    CFRunLoopAddSource,
+    CFRunLoopGetCurrent,
+    CFRunLoopRun,
+    CFRunLoopStop,
+    kCFRunLoopDefaultMode,
+)
+from Quartz import (
+    CGEventGetFlags,
+    CGEventGetIntegerValueField,
+    CGEventMaskBit,
+    CGEventTapCreate,
+    CGEventTapEnable,
+    CGPreflightListenEventAccess,
+    kCGEventFlagMaskAlternate,
+    kCGEventFlagMaskCommand,
+    kCGEventFlagMaskControl,
+    kCGEventFlagMaskShift,
+    kCGEventFlagsChanged,
+    kCGEventKeyDown,
+    kCGEventKeyUp,
+    kCGEventTapOptionListenOnly,
+    kCGHeadInsertEventTap,
+    kCGHIDEventTap,
+    kCGKeyboardEventKeycode,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class MacKey:
+    name: str | None = None
+    char: str | None = None
+    vk: int | None = None
+
+
+SPECIAL_KEYCODES = {
+    36: "enter",
+    48: "tab",
+    49: "space",
+    51: "backspace",
+    53: "esc",
+    54: "cmd_r",
+    55: "cmd_l",
+    56: "shift_l",
+    57: "caps_lock",
+    58: "alt_l",
+    59: "ctrl_l",
+    60: "shift_r",
+    61: "alt_r",
+    62: "ctrl_r",
+    117: "delete",
+    123: "left",
+    124: "right",
+    125: "down",
+    126: "up",
+}
+
+CHARACTER_KEYCODES = {
+    0: "a",
+    1: "s",
+    2: "d",
+    3: "f",
+    4: "h",
+    5: "g",
+    6: "z",
+    7: "x",
+    8: "c",
+    9: "v",
+    11: "b",
+    12: "q",
+    13: "w",
+    14: "e",
+    15: "r",
+    16: "y",
+    17: "t",
+    18: "1",
+    19: "2",
+    20: "3",
+    21: "4",
+    22: "6",
+    23: "5",
+    25: "9",
+    26: "7",
+    28: "8",
+    29: "0",
+    31: "o",
+    32: "u",
+    34: "i",
+    35: "p",
+    37: "l",
+    38: "j",
+    40: "k",
+    24: "=",
+    27: "-",
+    30: "]",
+    33: "[",
+    39: "'",
+    41: ";",
+    42: "\\",
+    43: ",",
+    44: "/",
+    45: "n",
+    46: "m",
+    47: ".",
+    50: "`",
+}
+
+MODIFIER_FLAGS = {
+    55: kCGEventFlagMaskCommand,
+    56: kCGEventFlagMaskShift,
+    58: kCGEventFlagMaskAlternate,
+    59: kCGEventFlagMaskControl,
+}
+
+
+class MacKeyboardListener:
+    """Passive macOS event monitor that cannot consume or alter keystrokes."""
+
+    def __init__(
+        self,
+        on_press: Callable[[object], None],
+        on_release: Callable[[object], None],
+    ) -> None:
+        self._on_press = on_press
+        self._on_release = on_release
+        self._thread: threading.Thread | None = None
+        self._loop: object | None = None
+        self._ready = threading.Event()
+        self._error: str | None = None
+        self._pressed_modifiers: set[int] = set()
+        self._pressed_keycodes: set[int] = set()
+
+    def start(self) -> tuple[bool, str | None]:
+        if not CGPreflightListenEventAccess():
+            return False, "請在系統設定的「輸入監控」中允許 ChatGPT"
+        self._ready.clear()
+        self._error = None
+        self._thread = threading.Thread(target=self._run, name="prkit-mac-keyboard", daemon=True)
+        self._thread.start()
+        if not self._ready.wait(timeout=2):
+            return False, "鍵盤事件監聽啟動逾時"
+        return self._error is None, self._error
+
+    def stop(self) -> None:
+        loop, self._loop = self._loop, None
+        if loop is not None:
+            CFRunLoopStop(loop)
+        self._thread = None
+        self._pressed_modifiers.clear()
+        self._pressed_keycodes.clear()
+
+    def _run(self) -> None:
+        mask = (
+            CGEventMaskBit(kCGEventKeyDown)
+            | CGEventMaskBit(kCGEventKeyUp)
+            | CGEventMaskBit(kCGEventFlagsChanged)
+        )
+        tap = CGEventTapCreate(
+            kCGHIDEventTap,
+            kCGHeadInsertEventTap,
+            kCGEventTapOptionListenOnly,
+            mask,
+            self._handle_event,
+            None,
+        )
+        if tap is None:
+            self._error = "無法建立 macOS 唯讀鍵盤事件監看器"
+            self._ready.set()
+            return
+        source = CFMachPortCreateRunLoopSource(None, tap, 0)
+        self._loop = CFRunLoopGetCurrent()
+        CFRunLoopAddSource(self._loop, source, kCFRunLoopDefaultMode)
+        CGEventTapEnable(tap, True)
+        self._ready.set()
+        CFRunLoopRun()
+
+    def _handle_event(
+        self, proxy: object, event_type: int, event: object, refcon: object
+    ) -> object:
+        del proxy, refcon
+        keycode = int(CGEventGetIntegerValueField(event, kCGKeyboardEventKeycode))
+        if event_type == kCGEventFlagsChanged:
+            self._update_modifiers(int(CGEventGetFlags(event)))
+            if keycode == 57:
+                self._press_transient_key(keycode)
+            return event
+        key = self._key(keycode)
+        if key is None:
+            return event
+        if event_type == kCGEventKeyDown:
+            self._pressed_keycodes.add(keycode)
+            self._on_press(key)
+        elif event_type == kCGEventKeyUp and keycode in self._pressed_keycodes:
+            self._release_key(keycode)
+        return event
+
+    def _update_modifiers(self, flags: int) -> None:
+        for keycode, flag in MODIFIER_FLAGS.items():
+            is_pressed = bool(flags & flag)
+            was_pressed = keycode in self._pressed_modifiers
+            if is_pressed and not was_pressed:
+                self._pressed_modifiers.add(keycode)
+                self._pressed_keycodes.add(keycode)
+                self._on_press(self._key(keycode))
+            elif not is_pressed and was_pressed:
+                self._pressed_modifiers.remove(keycode)
+                self._pressed_keycodes.discard(keycode)
+                self._on_release(self._key(keycode))
+
+    def _press_transient_key(self, keycode: int) -> None:
+        key = self._key(keycode)
+        if key is None:
+            return
+        self._pressed_keycodes.add(keycode)
+        self._on_press(key)
+        self._release_key(keycode)
+
+    def _release_key(self, keycode: int) -> None:
+        if keycode not in self._pressed_keycodes:
+            return
+        self._pressed_keycodes.remove(keycode)
+        self._on_release(self._key(keycode))
+
+    @staticmethod
+    def _key(keycode: int) -> MacKey | None:
+        if keycode == 255:
+            return None
+        name = SPECIAL_KEYCODES.get(keycode)
+        return (
+            MacKey(name=name, vk=keycode)
+            if name
+            else MacKey(char=CHARACTER_KEYCODES.get(keycode, f"Key {keycode}"), vk=keycode)
+        )