win-mouse-listener 0.1.0__py3-none-any.whl

win_mouse_listener/__init__.py

@@ -0,0 +1,102 @@
+# -*- coding: utf-8 -*-
+"""Non-blocking Windows mouse listener (Raw Input based).
+
+Public API mirrors the shape of the `mouse` library's event protocol but
+never installs a hook, so callbacks cannot block the mouse.
+
+Quick start
+-----------
+    import win_mouse_listen as wm
+
+    wm.hook(lambda ev: print(ev))      # auto-starts on first hook
+    ...
+    wm.unhook_all()
+    wm.stop()
+"""
+import threading as _threading
+
+from ._types import (
+    LEFT, RIGHT, MIDDLE, X, X2, UP, DOWN, VERTICAL, HORIZONTAL,
+    ButtonEvent, WheelEvent, MoveEvent,
+)
+from ._listener import Listener
+
+__version__ = '0.1.0'
+
+__all__ = [
+    'LEFT', 'RIGHT', 'MIDDLE', 'X', 'X2', 'UP', 'DOWN',
+    'VERTICAL', 'HORIZONTAL',
+    'ButtonEvent', 'WheelEvent', 'MoveEvent',
+    'Listener',
+    'start', 'stop',
+    'hook', 'unhook', 'unhook_all',
+    'poll', 'get_events', 'clear_buffer', 'pending_count',
+    'is_pressed', 'position',
+]
+
+_default = None
+_default_lock = _threading.Lock()
+
+
+def _get_default():
+    global _default
+    with _default_lock:
+        if _default is None:
+            _default = Listener()
+        return _default
+
+
+def start():
+    """Start the default listener (no-op if already running)."""
+    _get_default().start()
+
+
+def stop():
+    """Stop and reset the default listener."""
+    global _default
+    with _default_lock:
+        if _default is not None:
+            _default.stop()
+            _default = None
+
+
+def hook(callback):
+    """Register a callback. Returns the callback for chaining.
+
+    The default listener starts automatically on first use.
+    """
+    return _get_default().hook(callback)
+
+
+def unhook(callback):
+    _get_default().unhook(callback)
+
+
+def unhook_all():
+    _get_default().unhook_all()
+
+
+def poll():
+    """Non-blocking pop of one event. Returns None if empty."""
+    return _get_default().poll()
+
+
+def get_events(max_count=None):
+    """Non-blocking pop of multiple events."""
+    return _get_default().get_events(max_count)
+
+
+def clear_buffer():
+    _get_default().clear_buffer()
+
+
+def pending_count():
+    return _get_default().pending_count()
+
+
+def is_pressed(button=LEFT):
+    return _get_default().is_pressed(button)
+
+
+def position():
+    return _get_default().position()

win_mouse_listener/_listener.py

@@ -0,0 +1,366 @@
+# -*- coding: utf-8 -*-
+"""Listener implementation using Raw Input."""
+import ctypes
+import threading
+import time as _time
+import traceback as _tb
+from collections import deque
+
+from ._types import (
+    ButtonEvent, WheelEvent, MoveEvent,
+    LEFT, RIGHT, MIDDLE, X, X2, UP, DOWN,
+)
+from . import _win32 as w
+
+
+class Listener(object):
+    """Non-blocking Windows mouse listener backed by Raw Input.
+
+    Raw Input does not sit in the mouse event chain, so callbacks can be as
+    slow as you like without ever affecting the mouse cursor.
+    """
+
+    def __init__(self, buffer_size=16384, dispatch_queue_size=16384,
+                 debug=False):
+        self._buffer = deque(maxlen=buffer_size)
+        self._dispatch_queue = deque(maxlen=dispatch_queue_size)
+        self._pressed = set()
+        self._handlers = []
+
+        self._shutdown = threading.Event()
+        self._ready = threading.Event()
+        self._running = False
+        self._error = None
+        self._debug = debug
+
+        self._hwnd = None
+        self._hinstance = None
+        self._class_name = None
+        self._wndproc_ref = None
+        self._thread = None
+        self._thread_id = 0
+        self._dispatcher = None
+
+    # ------------------------------------------------------------------ 生命周期
+    def start(self):
+        if self._running:
+            return
+        self._running = True
+        self._error = None
+        self._shutdown.clear()
+        self._ready.clear()
+
+        self._thread = threading.Thread(
+            target=self._message_loop_thread,
+            name='win-mouse-listen', daemon=True)
+        self._thread.start()
+
+        self._dispatcher = threading.Thread(
+            target=self._dispatcher_loop,
+            name='win-mouse-dispatch', daemon=True)
+        self._dispatcher.start()
+
+        if not self._ready.wait(timeout=3.0):
+            raise RuntimeError(
+                "Listener thread did not become ready in time")
+        if self._error:
+            raise RuntimeError(
+                "Failed to start listener: " + self._error)
+
+    def stop(self, timeout=2.0):
+        if not self._running:
+            return
+        self._shutdown.set()
+
+        if self._thread_id:
+            w._user32.PostThreadMessageW(self._thread_id, w.WM_QUIT, 0, 0)
+
+        if self._thread is not None:
+            self._thread.join(timeout=timeout)
+            self._thread = None
+        if self._dispatcher is not None:
+            self._dispatcher.join(timeout=timeout)
+            self._dispatcher = None
+
+        self._running = False
+
+    def __enter__(self):
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.stop()
+        return False
+
+    # ------------------------------------------------------------------ 消息循环线程
+    def _message_loop_thread(self):
+        try:
+            self._thread_id = w._kernel32.GetCurrentThreadId()
+            self._hinstance = w._kernel32.GetModuleHandleW(None)
+
+            def wnd_proc(hwnd, msg, wparam, lparam):
+                return self._on_message(hwnd, msg, wparam, lparam)
+
+            self._wndproc_ref = w.WNDPROC(wnd_proc)
+
+            self._class_name = 'WinMouseListen_{}_{}'.format(
+                id(self), self._thread_id)
+
+            wc = w.WNDCLASSEXW()
+            wc.cbSize        = ctypes.sizeof(w.WNDCLASSEXW)
+            wc.style         = 0
+            wc.lpfnWndProc   = self._wndproc_ref
+            wc.cbClsExtra    = 0
+            wc.cbWndExtra    = 0
+            wc.hInstance     = self._hinstance
+            wc.hIcon         = None
+            wc.hCursor       = None
+            wc.hbrBackground = None
+            wc.lpszMenuName  = None
+            wc.lpszClassName = self._class_name
+            wc.hIconSm       = None
+
+            atom = w._user32.RegisterClassExW(ctypes.byref(wc))
+            if not atom:
+                self._error = 'RegisterClassExW failed: {}'.format(
+                    ctypes.get_last_error())
+                self._ready.set()
+                return
+
+            hwnd = w._user32.CreateWindowExW(
+                0, self._class_name, '', 0,
+                0, 0, 0, 0,
+                w.HWND_MESSAGE, None, self._hinstance, None,
+            )
+            if not hwnd:
+                self._error = 'CreateWindowExW failed: {}'.format(
+                    ctypes.get_last_error())
+                self._ready.set()
+                return
+            self._hwnd = hwnd
+
+            rid = w.RAWINPUTDEVICE()
+            rid.usUsagePage = w.HID_USAGE_PAGE_GENERIC
+            rid.usUsage     = w.HID_USAGE_GENERIC_MOUSE
+            rid.dwFlags     = w.RIDEV_INPUTSINK
+            rid.hwndTarget  = hwnd
+
+            ok = w._user32.RegisterRawInputDevices(
+                ctypes.byref(rid), 1, ctypes.sizeof(w.RAWINPUTDEVICE))
+            if not ok:
+                self._error = 'RegisterRawInputDevices failed: {}'.format(
+                    ctypes.get_last_error())
+                self._ready.set()
+                return
+
+            # 强制为当前线程创建消息队列，确保 PostThreadMessageW 生效
+            msg = w.MSG()
+            w._user32.PeekMessageW(ctypes.byref(msg), None, 0, 0, 0)
+
+            self._ready.set()
+
+            if self._debug:
+                import sys
+                sys.stderr.write(
+                    '[win_mouse_listen] listening hwnd={:#x} tid={}\n'
+                    .format(hwnd, self._thread_id))
+                sys.stderr.flush()
+
+            while True:
+                ret = w._user32.GetMessageW(ctypes.byref(msg), None, 0, 0)
+                if ret <= 0:        # 0 = WM_QUIT, -1 = error
+                    break
+                w._user32.TranslateMessage(ctypes.byref(msg))
+                w._user32.DispatchMessageW(ctypes.byref(msg))
+
+        except Exception:
+            self._error = _tb.format_exc()
+            self._ready.set()
+
+        finally:
+            if self._hwnd:
+                try:
+                    w._user32.DestroyWindow(self._hwnd)
+                except Exception:
+                    pass
+                self._hwnd = None
+            if self._class_name and self._hinstance:
+                try:
+                    w._user32.UnregisterClassW(
+                        self._class_name, self._hinstance)
+                except Exception:
+                    pass
+                self._class_name = None
+
+    # ------------------------------------------------------------------ WndProc
+    def _on_message(self, hwnd, msg, wparam, lparam):
+        if msg == w.WM_INPUT:
+            try:
+                self._handle_wm_input(lparam)
+            except Exception:
+                if self._debug:
+                    _tb.print_exc()
+            return 0
+        if msg == w.WM_DESTROY:
+            w._user32.PostQuitMessage(0)
+            return 0
+        return w._user32.DefWindowProcW(hwnd, msg, wparam, lparam)
+
+    # ------------------------------------------------------------------ Raw Input 解析
+    def _handle_wm_input(self, hrawinput):
+        size = ctypes.c_uint(0)
+        header_size = ctypes.sizeof(w.RAWINPUTHEADER)
+
+        # 第一次调用：取所需缓冲区大小
+        res = w._user32.GetRawInputData(
+            hrawinput, w.RID_INPUT,
+            None, ctypes.byref(size), header_size,
+        )
+        if res == 0xFFFFFFFF or size.value < ctypes.sizeof(w.RAWINPUT):
+            return
+
+        buf = ctypes.create_string_buffer(size.value)
+
+        # 第二次调用：真正读取
+        res = w._user32.GetRawInputData(
+            hrawinput, w.RID_INPUT,
+            buf, ctypes.byref(size), header_size,
+        )
+        if res == 0xFFFFFFFF:
+            return
+
+        raw = ctypes.cast(
+            buf, ctypes.POINTER(w.RAWINPUT)).contents
+        if raw.header.dwType != w.RIM_TYPEMOUSE:
+            return
+
+        self._process_mouse(raw.mouse)
+
+    def _process_mouse(self, mouse):
+        t  = _time.time()
+        bf = mouse.buttons.button_flags.usButtonFlags
+        bd = mouse.buttons.button_flags.usButtonData
+        flags = mouse.usFlags
+        dx, dy = mouse.lLastX, mouse.lLastY
+
+        events = []
+
+        if bf & w.RI_MOUSE_LEFT_BUTTON_DOWN:
+            events.append(ButtonEvent(DOWN, LEFT, t))
+        if bf & w.RI_MOUSE_LEFT_BUTTON_UP:
+            events.append(ButtonEvent(UP, LEFT, t))
+        if bf & w.RI_MOUSE_RIGHT_BUTTON_DOWN:
+            events.append(ButtonEvent(DOWN, RIGHT, t))
+        if bf & w.RI_MOUSE_RIGHT_BUTTON_UP:
+            events.append(ButtonEvent(UP, RIGHT, t))
+        if bf & w.RI_MOUSE_MIDDLE_BUTTON_DOWN:
+            events.append(ButtonEvent(DOWN, MIDDLE, t))
+        if bf & w.RI_MOUSE_MIDDLE_BUTTON_UP:
+            events.append(ButtonEvent(UP, MIDDLE, t))
+        if bf & w.RI_MOUSE_BUTTON_4_DOWN:
+            events.append(ButtonEvent(DOWN, X, t))
+        if bf & w.RI_MOUSE_BUTTON_4_UP:
+            events.append(ButtonEvent(UP, X, t))
+        if bf & w.RI_MOUSE_BUTTON_5_DOWN:
+            events.append(ButtonEvent(DOWN, X2, t))
+        if bf & w.RI_MOUSE_BUTTON_5_UP:
+            events.append(ButtonEvent(UP, X2, t))
+
+        if bf & w.RI_MOUSE_WHEEL:
+            events.append(WheelEvent(ctypes.c_short(bd).value, t))
+        if bf & w.RI_MOUSE_HWHEEL:
+            events.append(WheelEvent(ctypes.c_short(bd).value, t))
+
+        if dx != 0 or dy != 0 or (flags & w.MOUSE_MOVE_ABSOLUTE):
+            pt = w.POINT()
+            w._user32.GetCursorPos(ctypes.byref(pt))
+
+            if flags & w.MOUSE_MOVE_ABSOLUTE:
+                # 绝对模式（触摸板 / RDP）下 lLastX/lLastY 不是相对位移，
+                # 直接给 0，避免误导。
+                rdx = rdy = 0
+            else:
+                rdx, rdy = dx, dy
+
+            events.append(MoveEvent(pt.x, pt.y, t, rdx, rdy))
+
+        if not events:
+            return
+
+        buf = self._buffer
+        dq  = self._dispatch_queue
+        has_handlers = bool(self._handlers)
+
+        for e in events:
+            if isinstance(e, ButtonEvent):
+                if e.event_type == UP:
+                    self._pressed.discard(e.button)
+                else:
+                    self._pressed.add(e.button)
+            buf.append(e)
+            if has_handlers:
+                dq.append(e)
+
+    # ------------------------------------------------------------------ 分发线程
+    def _dispatcher_loop(self):
+        while not self._shutdown.is_set():
+            if not self._dispatch_queue:
+                _time.sleep(0.001)
+                continue
+            try:
+                event = self._dispatch_queue.popleft()
+            except IndexError:
+                continue
+            for h in self._handlers:
+                try:
+                    h(event)
+                except Exception:
+                    if self._debug:
+                        _tb.print_exc()
+
+    # ------------------------------------------------------------------ 公共 API
+    def hook(self, callback):
+        if callback not in self._handlers:
+            self._handlers = self._handlers + [callback]
+        if not self._running:
+            self.start()
+        return callback
+
+    def unhook(self, callback):
+        self._handlers = [h for h in self._handlers if h != callback]
+
+    def unhook_all(self):
+        self._handlers = []
+
+    def poll(self):
+        try:
+            return self._buffer.popleft()
+        except IndexError:
+            return None
+
+    def get_events(self, max_count=None):
+        if max_count is None:
+            events = list(self._buffer)
+            self._buffer.clear()
+            return events
+        out = []
+        for _ in range(max_count):
+            try:
+                out.append(self._buffer.popleft())
+            except IndexError:
+                break
+        return out
+
+    def clear_buffer(self):
+        self._buffer.clear()
+
+    def pending_count(self):
+        return len(self._buffer)
+
+    def is_pressed(self, button=LEFT):
+        return button in self._pressed
+
+    def position(self):
+        pt = w.POINT()
+        w._user32.GetCursorPos(ctypes.byref(pt))
+        return (pt.x, pt.y)

win_mouse_listener/_types.py

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+"""Event types and constants, compatible with the `mouse` library."""
+from collections import namedtuple
+
+# Buttons
+LEFT = 'left'
+RIGHT = 'right'
+MIDDLE = 'middle'
+X = 'x'
+X2 = 'x2'
+
+# Event types
+UP = 'up'
+DOWN = 'down'
+
+# Wheel directions (for future use)
+VERTICAL = 'vertical'
+HORIZONTAL = 'horizontal'
+
+ButtonEvent = namedtuple('ButtonEvent', ['event_type', 'button', 'time'])
+WheelEvent = namedtuple('WheelEvent', ['delta', 'time'])
+MoveEvent = namedtuple('MoveEvent', ['x', 'y', 'time', 'dx', 'dy'])
+MoveEvent.__new__.__defaults__ = (0, 0)
+
+
+__all__ = [
+    'LEFT', 'RIGHT', 'MIDDLE', 'X', 'X2',
+    'UP', 'DOWN', 'VERTICAL', 'HORIZONTAL',
+    'ButtonEvent', 'WheelEvent', 'MoveEvent',
+]

win_mouse_listener/_win32.py

@@ -0,0 +1,216 @@
+# -*- coding: utf-8 -*-
+"""Win32 ctypes bindings for the Raw Input API.
+
+Raw Input is a pure-listening mechanism: mouse events are processed by the
+system normally, and a *copy* is delivered to our hidden window as WM_INPUT.
+No hook is inserted into the input chain, so we can never block the mouse.
+"""
+import sys
+import ctypes
+
+if not sys.platform.startswith('win'):
+    raise ImportError("win_mouse_listen is Windows-only.")
+
+_user32 = ctypes.WinDLL('user32', use_last_error=True)
+_kernel32 = ctypes.WinDLL('kernel32', use_last_error=True)
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+WM_INPUT     = 0x00FF
+WM_DESTROY   = 0x0002
+WM_CLOSE     = 0x0010
+WM_QUIT      = 0x0012
+
+HWND_MESSAGE = ctypes.c_void_p(-3)
+
+RIDEV_INPUTSINK  = 0x00000100
+RIDEV_REMOVE     = 0x00000001
+RID_INPUT        = 0x10000003
+RIM_TYPEMOUSE    = 0
+
+HID_USAGE_PAGE_GENERIC    = 0x01
+HID_USAGE_GENERIC_MOUSE   = 0x02
+
+MOUSE_MOVE_RELATIVE = 0x00
+MOUSE_MOVE_ABSOLUTE = 0x01
+
+RI_MOUSE_LEFT_BUTTON_DOWN   = 0x0001
+RI_MOUSE_LEFT_BUTTON_UP     = 0x0002
+RI_MOUSE_RIGHT_BUTTON_DOWN  = 0x0004
+RI_MOUSE_RIGHT_BUTTON_UP    = 0x0008
+RI_MOUSE_MIDDLE_BUTTON_DOWN = 0x0010
+RI_MOUSE_MIDDLE_BUTTON_UP   = 0x0020
+RI_MOUSE_BUTTON_4_DOWN      = 0x0040
+RI_MOUSE_BUTTON_4_UP        = 0x0080
+RI_MOUSE_BUTTON_5_DOWN      = 0x0100
+RI_MOUSE_BUTTON_5_UP        = 0x0200
+RI_MOUSE_WHEEL              = 0x0400
+RI_MOUSE_HWHEEL             = 0x0800
+
+
+# ---------------------------------------------------------------------------
+# Structures
+# ---------------------------------------------------------------------------
+LRESULT = ctypes.c_ssize_t
+WNDPROC = ctypes.WINFUNCTYPE(
+    LRESULT,
+    ctypes.c_void_p,     # HWND
+    ctypes.c_uint,       # UINT
+    ctypes.c_size_t,     # WPARAM
+    ctypes.c_ssize_t,    # LPARAM
+)
+
+
+class POINT(ctypes.Structure):
+    _fields_ = [('x', ctypes.c_long), ('y', ctypes.c_long)]
+
+
+class MSG(ctypes.Structure):
+    _fields_ = [
+        ('hwnd',      ctypes.c_void_p),
+        ('message',   ctypes.c_uint),
+        ('wParam',    ctypes.c_size_t),
+        ('lParam',    ctypes.c_ssize_t),
+        ('time',      ctypes.c_ulong),
+        ('pt',        POINT),
+        ('lPrivate',  ctypes.c_ulong),
+    ]
+
+
+class WNDCLASSEXW(ctypes.Structure):
+    _fields_ = [
+        ('cbSize',        ctypes.c_uint),
+        ('style',         ctypes.c_uint),
+        ('lpfnWndProc',   WNDPROC),
+        ('cbClsExtra',    ctypes.c_int),
+        ('cbWndExtra',    ctypes.c_int),
+        ('hInstance',     ctypes.c_void_p),
+        ('hIcon',         ctypes.c_void_p),
+        ('hCursor',       ctypes.c_void_p),
+        ('hbrBackground', ctypes.c_void_p),
+        ('lpszMenuName',  ctypes.c_wchar_p),
+        ('lpszClassName', ctypes.c_wchar_p),
+        ('hIconSm',       ctypes.c_void_p),
+    ]
+
+
+class RAWINPUTDEVICE(ctypes.Structure):
+    _fields_ = [
+        ('usUsagePage', ctypes.c_ushort),
+        ('usUsage',     ctypes.c_ushort),
+        ('dwFlags',     ctypes.c_ulong),
+        ('hwndTarget',  ctypes.c_void_p),
+    ]
+
+
+class RAWINPUTHEADER(ctypes.Structure):
+    _fields_ = [
+        ('dwType',   ctypes.c_ulong),
+        ('dwSize',   ctypes.c_ulong),
+        ('hDevice',  ctypes.c_void_p),
+        ('wParam',   ctypes.c_size_t),
+    ]
+
+
+class _RAWMOUSE_BUTTONS(ctypes.Structure):
+    _fields_ = [
+        ('usButtonFlags', ctypes.c_ushort),
+        ('usButtonData',  ctypes.c_ushort),
+    ]
+
+
+class _RAWMOUSE_BUTTONS_UNION(ctypes.Union):
+    _fields_ = [
+        ('ulButtons',     ctypes.c_ulong),
+        ('button_flags',  _RAWMOUSE_BUTTONS),
+    ]
+
+
+class RAWMOUSE(ctypes.Structure):
+    _fields_ = [
+        ('usFlags',            ctypes.c_ushort),
+        ('_padding',           ctypes.c_ushort),
+        ('buttons',            _RAWMOUSE_BUTTONS_UNION),
+        ('ulRawButtons',       ctypes.c_ulong),
+        ('lLastX',             ctypes.c_long),
+        ('lLastY',             ctypes.c_long),
+        ('ulExtraInformation', ctypes.c_ulong),
+    ]
+
+
+class RAWINPUT(ctypes.Structure):
+    _fields_ = [
+        ('header', RAWINPUTHEADER),
+        ('mouse',  RAWMOUSE),
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Function signatures
+# ---------------------------------------------------------------------------
+_user32.DefWindowProcW.argtypes = [
+    ctypes.c_void_p, ctypes.c_uint, ctypes.c_size_t, ctypes.c_ssize_t,
+]
+_user32.DefWindowProcW.restype = LRESULT
+
+_user32.GetMessageW.argtypes = [
+    ctypes.POINTER(MSG), ctypes.c_void_p, ctypes.c_uint, ctypes.c_uint,
+]
+_user32.GetMessageW.restype = ctypes.c_int
+
+_user32.PeekMessageW.argtypes = [
+    ctypes.POINTER(MSG), ctypes.c_void_p,
+    ctypes.c_uint, ctypes.c_uint, ctypes.c_uint,
+]
+_user32.PeekMessageW.restype = ctypes.c_int
+
+_user32.TranslateMessage.argtypes = [ctypes.POINTER(MSG)]
+_user32.TranslateMessage.restype  = ctypes.c_int
+
+_user32.DispatchMessageW.argtypes = [ctypes.POINTER(MSG)]
+_user32.DispatchMessageW.restype  = LRESULT
+
+_user32.PostQuitMessage.argtypes = [ctypes.c_int]
+_user32.PostQuitMessage.restype  = None
+
+_user32.PostThreadMessageW.argtypes = [
+    ctypes.c_ulong, ctypes.c_uint, ctypes.c_size_t, ctypes.c_ssize_t,
+]
+_user32.PostThreadMessageW.restype = ctypes.c_int
+
+_user32.RegisterClassExW.argtypes = [ctypes.POINTER(WNDCLASSEXW)]
+_user32.RegisterClassExW.restype  = ctypes.c_ushort
+
+_user32.UnregisterClassW.argtypes = [ctypes.c_wchar_p, ctypes.c_void_p]
+_user32.UnregisterClassW.restype  = ctypes.c_int
+
+_user32.CreateWindowExW.argtypes = [
+    ctypes.c_ulong, ctypes.c_wchar_p, ctypes.c_wchar_p, ctypes.c_ulong,
+    ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int,
+    ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p,
+]
+_user32.CreateWindowExW.restype = ctypes.c_void_p
+
+_user32.DestroyWindow.argtypes = [ctypes.c_void_p]
+_user32.DestroyWindow.restype  = ctypes.c_int
+
+_user32.RegisterRawInputDevices.argtypes = [
+    ctypes.POINTER(RAWINPUTDEVICE), ctypes.c_uint, ctypes.c_uint,
+]
+_user32.RegisterRawInputDevices.restype = ctypes.c_int
+
+_user32.GetRawInputData.argtypes = [
+    ctypes.c_void_p, ctypes.c_uint, ctypes.c_void_p,
+    ctypes.POINTER(ctypes.c_uint), ctypes.c_uint,
+]
+_user32.GetRawInputData.restype = ctypes.c_uint
+
+_user32.GetCursorPos.argtypes = [ctypes.POINTER(POINT)]
+_user32.GetCursorPos.restype  = ctypes.c_int
+
+_kernel32.GetModuleHandleW.argtypes = [ctypes.c_wchar_p]
+_kernel32.GetModuleHandleW.restype  = ctypes.c_void_p
+
+_kernel32.GetCurrentThreadId.restype = ctypes.c_ulong

win_mouse_listener-0.1.0.dist-info/METADATA

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: win-mouse-listener
+Version: 0.1.0
+Summary: Non-blocking Windows mouse listener using Raw Input API
+License: MIT
+Project-URL: Homepage, https://example.invalid/win-mouse-listener
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# win-mouse-listen
+
+基于 **Windows Raw Input API** 的非阻塞鼠标监听模块。协议与 [`mouse`](https://pypi.org/project/mouse/) 库兼容，但**不会插入鼠标事件链**，因此：
+
+- 回调无论多慢，**都不会让鼠标卡顿**；
+- **不需要管理员权限**；
+- 支持按键、滚轮、移动，移动事件额外附带设备原始增量 `dx / dy`，可用于「触顶/触底持续移动」等场景。
+
+---
+
+## 为什么不用 `WH_MOUSE_LL` 钩子
+
+`mouse` 库底层使用 `SetWindowsHookEx(WH_MOUSE_LL)`。虽然它也能全局监听，但它**位于鼠标事件链上**——系统必须等你的钩子返回，才会继续把事件传给其他程序。只要你的回调里出现了锁等待、GIL 争抢、I/O 阻塞，鼠标就会卡。
+
+Raw Input 完全不同：鼠标事件由系统正常处理，同时复制一份 `WM_INPUT` 消息投递给你的隐藏窗口。**你的窗口处理再慢，也不会影响鼠标**。
+
+---
+
+## 安装
+
+```bash
+pip install win-mouse-listen
+```
+
+或从本地 whl 安装：
+
+```bash
+pip install dist/win_mouse_listen-0.1.0-py3-none-any.whl
+```
+
+---
+
+## 快速开始
+
+```python
+import time
+import win_mouse_listen as wm
+
+# 注册回调，第一次 hook 会自动启动监听
+wm.hook(lambda ev: print('event:', ev))
+
+try:
+    while True:
+        time.sleep(1)
+except KeyboardInterrupt:
+    wm.stop()
+```
+
+或者使用类接口：
+
+```python
+from win_mouse_listen import Listener
+
+with Listener() as l:
+    l.hook(print)
+    time.sleep(10)
+```
+
+---
+
+## 事件协议
+
+与 `mouse` 库兼容的 namedtuple：
+
+```python
+ButtonEvent(event_type, button, time)
+WheelEvent(delta, time)
+MoveEvent(x, y, time, dx, dy)
+```
+
+- `event_type`：`'up'` 或 `'down'`
+- `button`：`LEFT` / `RIGHT` / `MIDDLE` / `X` / `X2`
+- `time`：Unix 时间戳（float，秒）
+- `x, y`：屏幕坐标，由 `GetCursorPos` 获取，**钳制在屏幕内**
+- `dx, dy`：本次事件的**设备原始增量**，即使光标已经贴到屏幕边缘，仍会持续给出同方向的非零值
+
+> **注意**：`MoveEvent` 是 5 字段版本，与 `mouse.MoveEvent` 的 3 字段版本**不兼容 `isinstance`**。如果你的代码依赖 `mouse` 库的类型，请改用 duck typing 判断字段。
+
+---
+
+## API
+
+### 回调
+
+```python
+wm.hook(callback)          # 注册回调，返回 callback
+wm.unhook(callback)        # 注销单个回调
+wm.unhook_all()            # 注销所有回调
+```
+
+回调在独立的分发线程中执行，**阻塞回调不会影响鼠标**。
+
+### 生命周期
+
+```python
+wm.start()                 # 显式启动（hook 会自动启动）
+wm.stop()                  # 停止并重置默认监听器
+```
+
+### 非阻塞查询
+
+```python
+wm.poll()                  # 取一个事件，没有则返回 None
+wm.get_events(max_count=None)   # 批量取事件
+wm.clear_buffer()          # 清空缓冲区
+wm.pending_count()         # 当前缓冲的事件数量
+wm.is_pressed(button=LEFT) # 指定按键是否按下
+wm.position()              # 当前鼠标屏幕坐标 (x, y)
+```
+
+---
+
+## 典型用法：检测「触顶 / 触底持续移动」
+
+某些场景下需要判断鼠标已经顶到屏幕边缘，但用户仍在继续往同方向移动。传统做法是用「越界负坐标」反推增量，麻烦又容易出错。使用 `dx / dy` 直接判断即可：
+
+```python
+import win_mouse_listen as wm
+
+SCREEN_TOP_Y = 0
+SCREEN_BOTTOM_Y = 1079
+
+def on_move(ev):
+    if ev.y <= SCREEN_TOP_Y and ev.dy < 0:
+        print('向上越界移动', ev.dy)
+    elif ev.y >= SCREEN_BOTTOM_Y and ev.dy > 0:
+        print('向下越界移动', ev.dy)
+
+wm.hook(on_move)
+```
+
+> 提示：高回报率鼠标每秒会产生数百到上千个 `MoveEvent`，每个事件的 `dx/dy` 通常只有个位数。如果需要按距离阈值触发逻辑，建议在时间窗口内累加。
+
+---
+
+## 限制与注意事项
+
+1. **绝对模式**：触摸板、数位板、RDP 远程桌面等设备上报的是**绝对坐标**（`usFlags & MOUSE_MOVE_ABSOLUTE`）。此时 `lLastX/lLastY` 不是增量，模块会将 `dx/dy` 置 0，避免出现巨大数值。物理鼠标不受影响。
+
+2. **多显示器**：`x, y` 来自 `GetCursorPos`，在虚拟屏幕坐标系下，副屏位于主屏左侧或上方时 `x/y` 本来就可能为负。这和「触顶越界」是两回事。
+
+3. **仅支持 Windows**：模块依赖 `user32.dll`，其他平台会直接 `ImportError`。
+
+4. **不需要管理员**：Raw Input 对普通用户会话开放，无需提权。
+
+---
+
+## 打包
+
+项目根目录执行：
+
+```bash
+pip install build
+python -m build
+```
+
+产物在 `dist/`：
+
+```
+dist/
+├── win_mouse_listen-0.1.0-py3-none-any.whl
+└── win_mouse_listen-0.1.0.tar.gz
+```
+
+本地安装测试：
+
+```bash
+pip install dist/win_mouse_listen-0.1.0-py3-none-any.whl
+```
+
+---
+
+## 项目结构
+
+```
+win_mouse_listen/
+├── __init__.py        # 公共 API 与模块级单例
+├── _types.py          # 事件协议（ButtonEvent / WheelEvent / MoveEvent）
+├── _win32.py          # ctypes 绑定与常量
+└── _listener.py       # 核心监听器实现
+pyproject.toml
+README.md
+```
+
+---
+
+## 设计要点
+
+- **Raw Input 而非全局钩子**：鼠标事件不经过本模块，回调再慢也不会卡鼠标。
+- **隐藏消息窗口**：`HWND_MESSAGE` 类型窗口，不出现在任务栏。
+- **双重缓冲**：内部维护 `deque(maxlen=N)`，满了自动丢弃最旧事件，永不阻塞钩子线程。
+- **无锁读取**：利用 CPython 中 `deque.append/popleft`、`list` 引用替换的原子性，避免在热路径上加锁。
+- **分发线程独立**：用户回调在专用线程执行，隔离用户代码。
+
+---
+
+## License
+
+MIT

win_mouse_listener-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+win_mouse_listener/__init__.py,sha256=FR-fjfJaBoxvAdyuF6mqKbO0fgua4iVxiZq4_FNOryQ,2317
+win_mouse_listener/_listener.py,sha256=JWlpmIsj7JVrV0ds5ISs42cYS4WsE1mogtxEIduiFHg,12461
+win_mouse_listener/_types.py,sha256=dVVreO4Kbrlorz8gzRJXmQABF7dZICg3TZwDEhKAP_g,746
+win_mouse_listener/_win32.py,sha256=oDanjiWks3L6QbgSqHXhZ1qJnXewBLKJOXkOvwmyzTk,6768
+win_mouse_listener-0.1.0.dist-info/METADATA,sha256=R6vnzRl0VMsFKJQ_VhVZ6d2_UqPt5Uzvt5fS9CqWpYM,6262
+win_mouse_listener-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+win_mouse_listener-0.1.0.dist-info/top_level.txt,sha256=pidTNon3_LsMDFmGANGqOq7yHr5xvHpR-lfYYsV09PU,19
+win_mouse_listener-0.1.0.dist-info/RECORD,,

win_mouse_listener-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

win_mouse_listener-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+win_mouse_listener