plotruler 0.1.3__py3-none-any.whl

plotruler/win_hittest.py

@@ -0,0 +1,292 @@
+"""Win32 shim that gives the frameless overlay native window behavior.
+
+A frameless window has no native frame, so Windows refuses to move,
+resize, or snap it, and external tools like GridMove cannot grab it. On
+its own, answering WM_NCHITTEST with HTCAPTION gives dragging but not
+snapping, because Qt's FramelessWindowHint creates the window as
+WS_POPUP and the OS will not run its modal move loop for such a window.
+
+The fix has three parts, all in this module:
+
+1. Give the window the native overlapped-window style bits (WS_CAPTION,
+   WS_THICKFRAME, WS_MAXIMIZEBOX, ...) so Windows treats it as an
+   ordinary application window. This is what makes it snappable.
+2. Hide the actual frame by answering WM_NCCALCSIZE and collapsing the
+   non-client area, so the native title bar and borders are never drawn.
+3. Answer WM_NCHITTEST so the custom title bar behaves as a caption and
+   the edges resize natively, and WM_GETMINMAXINFO so the window's
+   minimum size is respected and maximizing fills the work area exactly.
+
+Windows-only. On other platforms every function is a no-op.
+"""
+
+import ctypes
+import sys
+
+try:
+    from ctypes import wintypes
+except (ImportError, OSError):
+    wintypes = None
+
+from PySide6.QtCore import QPoint
+
+# ctypes.wintypes imports fine on every platform (it is only a module of
+# struct types); ctypes.windll is what is Windows-only. So wintypes being
+# non-None is not proof we are on Windows, and a windll call on Linux dies
+# with AttributeError. Gate every Win32 path in this file on the real OS.
+_IS_WINDOWS = sys.platform == "win32" and wintypes is not None
+
+debug_enabled = False
+
+
+def _debug(msg):
+    if debug_enabled:
+        import sys
+
+        print("[hittest]", msg, file=sys.stderr, flush=True)
+
+
+WM_NCHITTEST = 0x0084
+WM_NCLBUTTONDBLCLK = 0x00A3
+WM_NCCALCSIZE = 0x0083
+WM_GETMINMAXINFO = 0x0024
+
+HTCLIENT = 1
+HTCAPTION = 2
+HTLEFT = 10
+HTRIGHT = 11
+HTTOP = 12
+HTTOPLEFT = 13
+HTTOPRIGHT = 14
+HTBOTTOM = 15
+HTBOTTOMLEFT = 16
+HTBOTTOMRIGHT = 17
+
+GWL_STYLE = -16
+GWL_EXSTYLE = -20
+WS_POPUP = 0x80000000
+WS_CAPTION = 0x00C00000
+WS_THICKFRAME = 0x00040000
+WS_SYSMENU = 0x00080000
+WS_MINIMIZEBOX = 0x00020000
+WS_MAXIMIZEBOX = 0x00010000
+WS_OVERLAPPEDWINDOW = (
+    WS_CAPTION | WS_THICKFRAME | WS_SYSMENU | WS_MINIMIZEBOX | WS_MAXIMIZEBOX
+)
+WS_EX_TOOLWINDOW = 0x00000080
+WS_EX_TOPMOST = 0x00000008
+WS_EX_LAYERED = 0x00080000
+
+SWP_NOSIZE = 0x0001
+SWP_NOMOVE = 0x0002
+SWP_NOZORDER = 0x0004
+SWP_NOACTIVATE = 0x0010
+SWP_FRAMECHANGED = 0x0020
+
+# Window placement show commands for WINDOWPLACEMENT.showCmd.
+SW_HIDE = 0
+SW_SHOW = 5
+SW_SHOWNORMAL = 1
+SW_SHOWMAXIMIZED = 3
+
+
+class MINMAXINFO(ctypes.Structure):
+    _fields_ = [
+        ("ptReserved", wintypes.POINT),
+        ("ptMaxSize", wintypes.POINT),
+        ("ptMaxPosition", wintypes.POINT),
+        ("ptMinTrackSize", wintypes.POINT),
+        ("ptMaxTrackSize", wintypes.POINT),
+    ]
+
+
+class NCCALCSIZE_PARAMS(ctypes.Structure):
+    _fields_ = [
+        ("rgrc", wintypes.RECT * 3),
+        ("lppos", ctypes.c_void_p),
+    ]
+
+
+def _local_point(window, lparam):
+    """Convert a WM_* cursor lParam to the window's local coordinates."""
+    x = ctypes.c_short(lparam & 0xFFFF).value
+    y = ctypes.c_short((lparam >> 16) & 0xFFFF).value
+    # lParam is in physical screen pixels; Qt geometry is logical, so
+    # scale down before mapping into the widget.
+    dpr = window.devicePixelRatioF()
+    logical = QPoint(int(x / dpr), int(y / dpr))
+    return window.mapFromGlobal(logical)
+
+
+def window_rect(window):
+    """Return the window's on-screen rect in physical pixels, or None.
+
+    Uses GetWindowRect, which reports the actual displayed bounds. This
+    matters for a maximized or aero-snapped window, where Qt's geometry()
+    returns the pre-snap "restore" rect rather than where the window is
+    really sitting on screen.
+    """
+    if not _IS_WINDOWS:
+        return None
+    try:
+        hwnd = int(window.winId())
+        rect = wintypes.RECT()
+        if not ctypes.windll.user32.GetWindowRect(hwnd, ctypes.byref(rect)):
+            return None
+        return rect.left, rect.top, rect.right, rect.bottom
+    except Exception:
+        return None
+
+
+class WINDOWPLACEMENT(ctypes.Structure):
+    _fields_ = [
+        ("length", wintypes.UINT),
+        ("flags", wintypes.UINT),
+        ("showCmd", wintypes.UINT),
+        ("ptMinPosition", wintypes.POINT),
+        ("ptMaxPosition", wintypes.POINT),
+        ("rcNormalPosition", wintypes.RECT),
+    ]
+
+
+def set_window_rect(window, rect, show=SW_SHOW):
+    """Place the window at a physical (left, top, right, bottom) rect.
+
+    Uses SetWindowPlacement, which sets the bounds and the window state
+    together. That is what makes a snapped window restore correctly: a
+    plain move/resize after show() is overridden by Windows re-applying
+    its stored snap restore position, whereas SetWindowPlacement overrides
+    that stored position in one atomic call.
+    """
+    if not _IS_WINDOWS:
+        return
+    try:
+        hwnd = int(window.winId())
+        left, top, right, bottom = rect
+        placement = WINDOWPLACEMENT()
+        placement.length = ctypes.sizeof(WINDOWPLACEMENT)
+        placement.flags = 0
+        placement.showCmd = show
+        placement.ptMinPosition.x = 0
+        placement.ptMinPosition.y = 0
+        placement.ptMaxPosition.x = 0
+        placement.ptMaxPosition.y = 0
+        placement.rcNormalPosition.left = left
+        placement.rcNormalPosition.top = top
+        placement.rcNormalPosition.right = right
+        placement.rcNormalPosition.bottom = bottom
+        ctypes.windll.user32.SetWindowPlacement(hwnd, ctypes.byref(placement))
+    except Exception:
+        return
+
+
+def apply_native_overlapped_style(window):
+    """Give the window real overlapped-window styles for snapping.
+
+    Qt's FramelessWindowHint produces WS_POPUP, which throws away the
+    shell behavior attached to the frame styles (snapping, taskbar
+    interaction, the move loop). Replace WS_POPUP with the standard
+    overlapped-window styles. The frame is never drawn because
+    WM_NCCALCSIZE collapses it.
+    """
+    if not _IS_WINDOWS:
+        return
+    hwnd = int(window.winId())
+    user32 = ctypes.windll.user32
+    style = user32.GetWindowLongW(hwnd, GWL_STYLE) & 0xFFFFFFFF
+    style = (style & ~WS_POPUP) | WS_OVERLAPPEDWINDOW
+    style &= 0xFFFFFFFF
+    # Win32 styles are signed 32-bit; convert before calling back.
+    if style >= 0x80000000:
+        style -= 0x100000000
+    user32.SetWindowLongW(hwnd, GWL_STYLE, style)
+    # Asking for a frame recalculation makes Windows re-query the frame
+    # (WM_NCCALCSIZE) so the collapsed client rect takes effect at once.
+    user32.SetWindowPos(
+        hwnd,
+        None,
+        0,
+        0,
+        0,
+        0,
+        SWP_FRAMECHANGED
+        | SWP_NOMOVE
+        | SWP_NOSIZE
+        | SWP_NOZORDER
+        | SWP_NOACTIVATE,
+    )
+
+
+def current_styles(window):
+    """Return the window's live style and extended-style words, if any."""
+    if not _IS_WINDOWS:
+        return None, None
+    try:
+        hwnd = int(window.winId())
+        user32 = ctypes.windll.user32
+        style = user32.GetWindowLongW(hwnd, GWL_STYLE) & 0xFFFFFFFF
+        exstyle = user32.GetWindowLongW(hwnd, GWL_EXSTYLE) & 0xFFFFFFFF
+        return style, exstyle
+    except Exception:
+        return None, None
+
+
+def handle_native_event(window, event_type, message):
+    """Route a native event to its handler; returns (handled, result)."""
+    if not _IS_WINDOWS or event_type != b"windows_generic_MSG":
+        return False, 0
+    try:
+        msg = wintypes.MSG.from_address(int(message))
+    except (TypeError, ValueError):
+        return False, 0
+    if msg.message == WM_NCHITTEST:
+        local = _local_point(window, msg.lParam)
+        code = window.hit_test_code(local)
+        _debug(f"NCHITTEST at {local.x()},{local.y()} -> HT{code}")
+        return True, code
+    if msg.message == WM_NCLBUTTONDBLCLK:
+        # The default is the system menu; we want maximize/restore like a
+        # real title bar.
+        if window.hit_test_code(_local_point(window, msg.lParam)) == HTCAPTION:
+            window.toggle_maximize()
+        return True, 0
+    if msg.message == WM_NCCALCSIZE:
+        # Collapse the non-client area so no native frame is drawn.
+        _collapse_frame(msg)
+        return True, 0
+    if msg.message == WM_GETMINMAXINFO:
+        _set_min_max_info(window, msg.lParam)
+        return True, 0
+    return False, 0
+
+
+def _collapse_frame(msg):
+    """Make the client area fill the whole window (no native frame)."""
+    if not msg.lParam:
+        return
+    if msg.wParam:
+        params = NCCALCSIZE_PARAMS.from_address(int(msg.lParam))
+        window_rect = params.rgrc[1]
+        # The proposed client rect (rgrc[0]) becomes the window rect.
+        params.rgrc[0].left = window_rect.left
+        params.rgrc[0].top = window_rect.top
+        params.rgrc[0].right = window_rect.right
+        params.rgrc[0].bottom = window_rect.bottom
+
+
+def _set_min_max_info(window, lparam):
+    """Enforce minimum size and a maximized size that fills the work area."""
+    if not lparam:
+        return
+    mmi = MINMAXINFO.from_address(int(lparam))
+    dpr = window.devicePixelRatioF()
+    mmi.ptMinTrackSize.x = int(window.minimumWidth() * dpr)
+    mmi.ptMinTrackSize.y = int(window.minimumHeight() * dpr)
+    # With the frame collapsed, a normal maximized window would overhang
+    # the screen by the frame width. Pin the maximized size to the work
+    # area so maximize and snap fill it exactly.
+    work = window.screen().availableGeometry()
+    mmi.ptMaxSize.x = int(work.width() * dpr)
+    mmi.ptMaxSize.y = int(work.height() * dpr)
+    mmi.ptMaxPosition.x = int(work.x() * dpr)
+    mmi.ptMaxPosition.y = int(work.y() * dpr)

plotruler-0.1.3.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: plotruler
+Version: 0.1.3
+Summary: Read (X, Y) values off an on-screen graph with a translucent overlay
+Project-URL: Homepage, https://github.com/endolith/plotruler
+Project-URL: Repository, https://github.com/endolith/plotruler
+Project-URL: Issues, https://github.com/endolith/plotruler/issues
+Project-URL: Changelog, https://github.com/endolith/plotruler/releases
+Author: endolith
+Maintainer: endolith
+License: MIT License
+        
+        Copyright (c) 2026 endolith
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+License-File: LICENSE
+Keywords: calibration,digitize,digitizer,graph,overlay,plot,readout
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: pyside6==6.11.2
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PlotRuler
+
+A translucent desktop overlay for accurately reading (X, Y) values off a graph
+shown on screen. Calibrate once against the known plot coordinates (click at two
+points on each axis, and type their labeled values), then hover to read
+coordinates anywhere else, and click to copy.
+
+The graph itself is not rendered by PlotRuler — it is whatever other app is on
+screen underneath the overlay (a browser, a PDF viewer, a plotting window, etc.)
+PlotRuler is a **live translucent overlay** that reads through it, not a
+screenshot workflow.
+
+## How it works
+
+Calibration and readout all live in **absolute screen coordinates** (physical
+pixels), not coordinates relative to the overlay window. That is what makes the
+overlay feel stable: you can drag or resize the window and the calibrated graph
+box stays glued to the graph underneath wherever it sits on screen. Windows and
+macOS get this natively; Linux/X11 uses the same absolute-coordinate model.
+
+Each axis is calibrated independently with two reference points — click once at
+a known pixel on the axis, type its labeled value, then repeat for a second
+point. PlotRuler fits a line through those pairs (linear by default, optional
+log), so it works for any graph where the scale is straight-line or log.
+Everything persists to disk (calibration, window position, number format), so
+the overlay reopens already calibrated.
+
+## Features
+
+- **Hover to read** — a crosshair and a (X, Y) readout follow the cursor once
+  calibrated, showing the values under it.
+- **Click to copy** — a click copies the hovered coordinate as e.g.
+  `(12.5, 4.0)` and flashes a confirmation.
+- **Number formats** — plain, scientific, engineering, E-notation, SI
+  (auto/1..6 via the number keys, or the tray menu).
+- **Calibration** — Ctrl+N starts a fresh one; Ctrl+Z undoes a step; Esc
+  cancels. Each axis gets its own linear/log choice.
+- **Custom frameless title bar** — translucent, with minimize, maximize, and
+  (on no-tray systems) a close button.
+- **Tray resident** — sits in the system tray; tray click toggles the overlay.
+
+## Platform comparison
+
+| | Windows | macOS | Linux/X11 |
+|---|---|---|---|
+| Absolute screen coordinates | ✅ native | ✅ native | ✅ (same model) |
+| Overlay readout through the graph | ✅ | ✅ | ✅ |
+| Move / resize the window | ✅ native | ✅ native | ✅ Qt-driven |
+| Calibration survives window move/resize | ✅ | ✅ | ✅ |
+| Global hotkey (Win+Alt+P / Cmd+Alt+P) | ✅ RegisterHotKey | ⏳ | ⏳ deferred (XGrabKey) |
+| System tray | ✅ | ✅ | ⚠️ depends on DE |
+| Build/ship | .exe (PyInstaller) | ⏳ untested | pip / PyPI wheel |
+
+**Wayland is not supported yet.** Wayland forbids absolute screen coordinates by
+design and GNOME refuses the workarounds, so the overlay model cannot work there
+without a window-relative rewrite. Linux requires an **X11** session for now;
+see `LINUX_PLAN.md`.
+
+Notes on the platform table:
+- **macOS is untested.** The architecture is OS-portable (absolute screen
+  coordinates, Qt overlay), and Qt provides a native macOS path, but no macOS
+  build or hotkey code exists in this repo yet. Treat the macOS column as a
+  design feature, not a shipped one.
+- **Global hotkey** — Windows-only today. On Linux the tray (or Ctrl+N/Esc and
+  the title-bar buttons) are the controls; an X11 `XGrabKey` hotkey is a
+  follow-up.
+- **System tray** — always present on Windows; on Linux it depends on the
+  desktop environment. GNOME has no tray by default unless the *AppIndicator
+  and KStatusNotifier* extension is installed. When no tray exists, PlotRuler
+  shows a close button and quits on minimize/close/Esc rather than hiding into
+  an unreachable state.
+
+## Development
+
+```sh
+conda activate plotruler
+python -m plotruler        # run the app
+pytest                     # run tests
+ruff check .               # lint
+ruff format .              # auto-format
+```
+
+## Linux
+
+Linux requires an X11 session (Wayland is deferred — see above). Qt 6.5+
+also needs the `xcb-cursor` system library for the X11 backend, which pip
+cannot install:
+
+```sh
+# Debian / Ubuntu
+sudo apt install libxcb-cursor0
+# Fedora / RHEL
+sudo dnf install xcb-util-cursor
+# Arch
+sudo pacman -S xcb-util-cursor
+```
+
+Install and run (no frozen binary on Linux):
+
+```sh
+pip install plotruler       # or, from source: pip install -e . then plotruler
+plotruler
+```
+
+> PyPI/wheels cannot install system libraries like `libxcb-cursor`; without it
+> the app aborts at first launch. Install it first (commands above). The
+> `build/install_linux.sh` helper also checks for it and fails fast with your
+> distro's package name.
+
+## Releases & publishing
+
+PlotRuler ships through **two channels**:
+
+| Channel | Artifact | Who uses it |
+|---|---|---|
+| **PyPI** (`pip install plotruler`) | wheel (`.whl`) | everyone, all platforms; the Linux and pip path |
+| **GitHub Releases** | `PlotRuler.exe` | Windows users who don't want pip |
+
+Publish a Python release to PyPI:
+
+```sh
+pip install build twine
+./build/publish_pypi.sh --check   # first: upload to TestPyPI and verify
+./build/publish_pypi.sh           # then: upload to PyPI
+```
+
+Requires `TWINE_USERNAME`/`TWINE_PASSWORD` (or a `~/.pypirc`), and an account
+with upload rights for the `plotruler` name. The package supports Python 3.10+
+(down to PySide6 6.11's own floor).
+
+The Windows `.exe` is separate and must be built on Windows.
+
+## Build a stand-alone Windows executable
+
+```sh
+python -m pip install pyinstaller
+python build/build.py
+```
+
+Produces a single-file, windowed `dist/PlotRuler.exe` with a tray icon and
+version metadata. The app bundles Qt, so the exe is ~46 MB but needs no Python
+install to run. This is the artifact you attach to a GitHub release.
+
+See `AGENTS.md` for development conventions.
+
+## License
+
+MIT License (see `LICENSE`).
+
+(This was generated almost entirely by AI under human direction, so likely lacks the human authorship required for copyright in the US and is therefore in the public domain.  MIT license applies anywhere else.)

plotruler-0.1.3.dist-info/RECORD

@@ -0,0 +1,15 @@
+plotruler/__init__.py,sha256=m4YbXPapznnOV6dQ7Fvu3rYku1TPvViZrjhyt-QxXlk,86
+plotruler/__main__.py,sha256=QZZ30UQ20lRlIy8olH2fKym-DJKMD8KkJ8TkPWU0Y_c,3238
+plotruler/core.py,sha256=JrkxEFEwJIWiAPNbmxCOHDIu_ZiPT2lqYceU0I6hkdg,14548
+plotruler/format.py,sha256=iIA2tun9WZCokTgtvhcPbjz_tywG-XoskN8YsK-GHIE,8688
+plotruler/hotkey.py,sha256=9tlI8BkEbgsoP_ODojIHbk3TB4yhsFKxmWjrxXT-chA,8010
+plotruler/overlay.py,sha256=JFRe1MWaLXyxebOoZhXXuZIxf8CN1kZMI6aTQgsSRxk,44465
+plotruler/settings.py,sha256=9Q-OMCKJJgVf1Fay5_rea7PT3HdfLQaxn2MGe_sK-oI,4348
+plotruler/storage.py,sha256=y35jXIMO826kEZVjNgkpHndEOWhJsk016sgxS6LsWok,4360
+plotruler/titlebar.py,sha256=pOSPkM_SJI0taQ7gW_RwdLxqFLndhAEji-oFa7d6kLE,8720
+plotruler/tray.py,sha256=y5IPHF_KiemFzwqLbs5kFzQnZ_FjyqbrvPAehpjVzYk,7104
+plotruler/win_hittest.py,sha256=OnHUyi3iqWDrQfOYOHKacWe6NHzGmL1b1ktiMczb_kA,9756
+plotruler-0.1.3.dist-info/METADATA,sha256=CfTMi8p1O9GBHaaI2C8yV4jeQn9rZ_eFBu_t7SQXZNU,8729
+plotruler-0.1.3.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+plotruler-0.1.3.dist-info/licenses/LICENSE,sha256=9TX-edZF9gflRnx-Y46LPq4k4R1xasFwbGHLvQCTkHI,1066
+plotruler-0.1.3.dist-info/RECORD,,

plotruler-0.1.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

plotruler-0.1.3.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 endolith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+