plotruler 0.1.3__py3-none-any.whl

plotruler/format.py

@@ -0,0 +1,262 @@
+"""Number-format options for the readout.
+
+This module is free of any Qt imports so it stays unit-testable and
+portable. The readout can show a value several ways: plain decimals,
+scientific notation (m x 10^n), engineering notation (exponent a
+multiple of 3), E notation (ASCII, the computer friendly form), or SI
+prefixes (12.3 k). "auto" shows plain for everyday magnitudes and
+switches to scientific only for very large or very small values.
+
+precision: a linear axis carries positional precision (how many decimal
+places are meaningful); a log axis carries relative precision (how many
+significant figures). The axis computes both from a pixel-error model and
+hands them in, so this module never has to know about the calibration.
+"""
+
+from math import floor, isfinite, log10
+
+# The format choices, ordered for the tray menu and the number-key
+# shortcuts. These strings are the persistent config keys.
+AUTO = "auto"
+PLAIN = "plain"
+SCIENTIFIC = "scientific"
+ENGINEERING = "engineering"
+E = "e"
+SI = "si"
+
+OPTIONS = (AUTO, PLAIN, SCIENTIFIC, ENGINEERING, E, SI)
+
+NAMES = {
+    AUTO: "Auto",
+    PLAIN: "Plain",
+    SCIENTIFIC: "Scientific",
+    ENGINEERING: "Engineering",
+    E: "E notation",
+    SI: "SI prefixes",
+}
+
+# A value at or above this magnitude (or below its reciprocal) is "huge"
+# (or "tiny") enough that auto switches to scientific notation.
+_HIGH = 1e6
+_LOW = 1e-4
+
+# Cap on significant figures for the exponent styles when the precision
+# comes from a linear axis's positional model (see render()).
+_MAX_SIG_FIGS = 3
+
+# ASCII superscript digits and minus, used to render the exponent in the
+# "x 10^n" styles. Qt renders these as real superscripts.
+_SUPERSCRIPT = {
+    "0": "\u2070",
+    "1": "\u00b9",
+    "2": "\u00b2",
+    "3": "\u00b3",
+    "4": "\u2074",
+    "5": "\u2075",
+    "6": "\u2076",
+    "7": "\u2077",
+    "8": "\u2078",
+    "9": "\u2079",
+    "-": "\u207b",
+}
+
+# SI prefix symbols keyed by the exponent they represent (a multiple of 3).
+_SI_PREFIXES = {
+    30: "Q",
+    27: "R",
+    24: "Y",
+    21: "Z",
+    18: "E",
+    15: "P",
+    12: "T",
+    9: "G",
+    6: "M",
+    3: "k",
+    0: "",
+    -3: "m",
+    -6: "\u00b5",  # micro sign
+    -9: "n",
+    -12: "p",
+    -15: "f",
+    -18: "a",
+    -21: "z",
+    -24: "y",
+    -27: "r",
+    -30: "q",
+}
+
+
+def is_valid(fmt):
+    """True if fmt is one of the known format keys."""
+    return fmt in OPTIONS
+
+
+def superscript(exponent):
+    """Return an integer exponent as superscript digits, e.g. -3 -> ⁻³."""
+    sign = "" if exponent >= 0 else "\u207b"
+    digits = "".join(_SUPERSCRIPT[d] for d in str(abs(exponent)))
+    return sign + digits
+
+
+def _times_ten(exponent):
+    """Render ' x 10^exponent' using the Unicode superscript form."""
+    return " \u00d7 10" + superscript(exponent)
+
+
+def _sig_figs_for_decimals(value, decimals):
+    """Significant figures of a value rounded to `decimals` places.
+
+    The number of significant figures is the span from the most
+    significant digit to the least significant (which sits at the
+    `decimals` place). This lets a positional-precision axis (linear)
+    report equivalent significant figures for the exponent styles.
+    """
+    if decimals is None:
+        return None
+    if value == 0:
+        return 1
+    rounded = round(value, decimals)
+    if rounded == 0:
+        return 1
+    most_sig = floor(log10(abs(rounded)))
+    return max(1, min(15, most_sig + decimals + 1))
+
+
+def _sig(value, sig_figs):
+    """Round value to a number of significant figures as a plain decimal.
+
+    This must never resort to the 'g' format specifier: for a mantissa
+    like 490 with 2 significant figures, '%.2g' yields '4.9e+02', which
+    leaks scientific notation into SI prefixes or engineering mantissas.
+    Instead, compute how many decimal places a value rounded to sig_figs
+    needs and render with a plain fixed-point format.
+    """
+    if value == 0 or not isfinite(value):
+        return str(value)
+    digits = sig_figs - 1 - floor(log10(abs(value)))
+    if digits < 0:
+        digits = 0
+    return f"{value:.{digits}f}"
+
+
+def _plain(value, decimals, sig_figs):
+    """Render a value without scaling, honoring positional or relative
+    precision whichever the axis supplied."""
+    if decimals is not None:
+        return f"{value:.{decimals}f}"
+    return _sig(value, sig_figs)
+
+
+def _strip_zeros(text):
+    """Remove trailing zeros and a trailing point from a mantissa string."""
+    if "." not in text:
+        return text
+    text = text.rstrip("0").rstrip(".")
+    return text or "0"
+
+
+def _scientific(value, sig_figs):
+    """Render value as m x 10^n with 1 <= |m| < 10."""
+    if value == 0 or not isfinite(value):
+        return _plain(value, 0, sig_figs) if value == 0 else str(value)
+    sign = "-" if value < 0 else ""
+    mant = abs(value)
+    exponent = floor(log10(mant))
+    scaled = mant / (10**exponent)
+    text = _strip_zeros(_sig(scaled, sig_figs))
+    if float(text) >= 10:  # rounding pushed the mantissa into the next decade
+        scaled = mant / (10 ** (exponent + 1))
+        text = _strip_zeros(_sig(scaled, sig_figs))
+        exponent += 1
+    return f"{sign}{text}{_times_ten(exponent)}"
+
+
+def _engineering(value, sig_figs):
+    """Render value as m x 10^n with n a multiple of 3 and 1 <= |m| < 1000."""
+    if value == 0 or not isfinite(value):
+        return _plain(value, 0, sig_figs) if value == 0 else str(value)
+    sign = "-" if value < 0 else ""
+    mant = abs(value)
+    exponent = 3 * floor(floor(log10(mant)) / 3)
+    scaled = mant / (10**exponent)
+    text = _strip_zeros(_sig(scaled, sig_figs))
+    if float(text) >= 1000:  # rounding overflowed the mantissa past 1000
+        exponent += 3
+        scaled = mant / (10**exponent)
+        text = _strip_zeros(_sig(scaled, sig_figs))
+    return f"{sign}{text}{_times_ten(exponent)}"
+
+
+def _e_notation(value, sig_figs):
+    """Render value as the ASCII E form, e.g. 1.23e4."""
+    if value == 0 or not isfinite(value):
+        return _plain(value, 0, sig_figs) if value == 0 else str(value)
+    sign = "-" if value < 0 else ""
+    mant = abs(value)
+    exponent = floor(log10(mant))
+    scaled = mant / (10**exponent)
+    text = _strip_zeros(_sig(scaled, sig_figs))
+    if float(text) >= 10:
+        scaled = mant / (10 ** (exponent + 1))
+        text = _strip_zeros(_sig(scaled, sig_figs))
+        exponent += 1
+    return f"{sign}{text}e{exponent}"
+
+
+def _si_prefix(value, sig_figs):
+    """Render value with an SI prefix from the SI-prefix table."""
+    if value == 0 or not isfinite(value):
+        return _plain(value, 0, sig_figs) if value == 0 else str(value)
+    mant = abs(value)
+    exponent = 3 * floor(floor(log10(mant)) / 3)
+    prefix = _SI_PREFIXES.get(exponent, "")
+    scaled = mant / (10**exponent)
+    text = _strip_zeros(_sig(scaled, sig_figs))
+    if float(text) >= 1000:  # rounding spilled into the next prefix band
+        exponent += 3
+        prefix = _SI_PREFIXES.get(exponent, "")
+        scaled = mant / (10**exponent)
+        text = _strip_zeros(_sig(scaled, sig_figs))
+    suffix = (" " + prefix) if prefix else ""
+    return f"{text}{suffix}"
+
+
+def _auto_choose(value):
+    """Pick the format for 'auto': plain unless the value is huge/tiny."""
+    if value == 0:
+        return PLAIN
+    magnitude = abs(value)
+    if magnitude >= _HIGH or magnitude < _LOW:
+        return SCIENTIFIC
+    return PLAIN
+
+
+def render(value, fmt, decimals, sig_figs):
+    """Return value as a string in the given format.
+
+    decimals is the positional precision (None for a log axis); sig_figs
+    is the relative precision (None for a linear axis). One of the two is
+    always provided. An unknown fmt falls back to plain.
+    """
+    if fmt == AUTO:
+        fmt = _auto_choose(value)
+    if fmt == PLAIN or fmt not in NAMES:
+        return _plain(value, decimals, sig_figs)
+    if decimals is not None and sig_figs is None:
+        # A linear axis has positional precision, which for a large value
+        # would balloon into many significant figures (e.g. a whole number
+        # to 1 decimal is ~9 sig figs). That is honest but unreadable, so
+        # clamp the exponent styles to a few figures like a hand readout.
+        sig_figs = _sig_figs_for_decimals(value, decimals)
+        sig_figs = max(2, min(sig_figs, _MAX_SIG_FIGS))
+    if sig_figs is None:
+        sig_figs = _sig_figs_for_decimals(value, decimals) or 3
+    if fmt == SCIENTIFIC:
+        return _scientific(value, sig_figs)
+    if fmt == ENGINEERING:
+        return _engineering(value, sig_figs)
+    if fmt == E:
+        return _e_notation(value, sig_figs)
+    if fmt == SI:
+        return _si_prefix(value, sig_figs)
+    return _plain(value, decimals, sig_figs)

plotruler/hotkey.py

@@ -0,0 +1,240 @@
+"""Global hotkey support via the Win32 RegisterHotKey API.
+
+A tray-resident overlay needs a system-wide key to summon and dismiss it
+without the window having focus. On Windows this is RegisterHotKey, which
+posts a WM_HOTKEY message to the thread that registered it. Qt's event
+loop delivers that message to a QAbstractNativeEventFilter, which is how
+we receive it regardless of which window is focused.
+
+The key combination is configurable, not hard-coded, so users can avoid
+collisions with other software (the default is Win+Alt+P for PlotRuler).
+
+Windows-only. On other platforms registration is a no-op.
+"""
+
+import ctypes
+import sys
+
+try:
+    from ctypes import wintypes
+except (ImportError, OSError):
+    wintypes = None
+
+from PySide6.QtCore import QAbstractNativeEventFilter
+
+# ctypes.wintypes imports fine on non-Windows (it is only struct types), so
+# a non-None wintypes does not prove we are on Windows, and calling
+# ctypes.windll on Linux fails with AttributeError. Gate every Win32 path
+# on the real OS.
+_IS_WINDOWS = sys.platform == "win32" and wintypes is not None
+
+MOD_ALT = 0x0001
+MOD_CONTROL = 0x0002
+MOD_SHIFT = 0x0004
+MOD_WIN = 0x0008
+
+MOD_BY_NAME = {
+    "win": MOD_WIN,
+    "alt": MOD_ALT,
+    "ctrl": MOD_CONTROL,
+    "shift": MOD_SHIFT,
+}
+MOD_NAME_BY_BIT = {bit: name for name, bit in MOD_BY_NAME.items()}
+
+WM_HOTKEY = 0x0312
+
+# Default summon key: Win+Alt+P (P for PlotRuler). Unclaimed on stock
+# Windows; the only known collision is PowerToys' optional mouse-pointer
+# crosshairs, which users can remap here.
+DEFAULT_VK = 0x50  # 'P'
+DEFAULT_MODIFIERS = MOD_WIN | MOD_ALT
+
+
+class KeyCombo:
+    """A single key plus its modifiers, in an OS-agnostic form.
+
+    Modifiers are stored as a frozenset of names ("win", "alt", "ctrl",
+    "shift") so they serialize as a stable ordered list. The key is a
+    human name ("P", "F1", "Space") plus its Win32 virtual-key code. The
+    overlay and settings dialog build these; the Win32 GlobalHotkey turns
+    one into a RegisterHotKey call.
+    """
+
+    def __init__(self, modifiers, key_name, vk):
+        self.modifiers = frozenset(modifiers)
+        self.key_name = key_name
+        self.vk = int(vk)
+
+    def text(self):
+        """Return a human-readable form, e.g. 'Win+Alt+P'."""
+        order = ("win", "alt", "ctrl", "shift")
+        parts = [name.title() for name in order if name in self.modifiers]
+        parts.append(self.key_name)
+        return "+".join(parts)
+
+    def win32_modifiers(self):
+        """Return the Win32 modifier bitmask for this combo."""
+        mask = 0
+        for name in self.modifiers:
+            mask |= MOD_BY_NAME.get(name, 0)
+        return mask
+
+    def to_dict(self):
+        """Return a storage-safe dict for this combo."""
+        order = ("win", "alt", "ctrl", "shift")
+        mods = [name for name in order if name in self.modifiers]
+        return {"modifiers": mods, "key": self.key_name, "vk": self.vk}
+
+    def __eq__(self, other):
+        return (
+            isinstance(other, KeyCombo)
+            and self.modifiers == other.modifiers
+            and self.key_name == other.key_name
+            and self.vk == other.vk
+        )
+
+    def __hash__(self):
+        return hash((tuple(sorted(self.modifiers)), self.key_name, self.vk))
+
+    def __repr__(self):
+        return f"KeyCombo({self.text()})"
+
+
+DEFAULT_COMBO = KeyCombo(("win", "alt"), "P", DEFAULT_VK)
+
+
+def combo_from_dict(data):
+    """Build a KeyCombo from a dict, or None if it is malformed."""
+    if not isinstance(data, dict):
+        return None
+    try:
+        modifiers = data["modifiers"]
+        key_name = str(data["key"])
+        vk = int(data["vk"])
+    except (KeyError, TypeError, ValueError):
+        return None
+    clean = [name for name in modifiers if name in MOD_BY_NAME]
+    if not clean or not key_name:
+        return None
+    return KeyCombo(clean, key_name, vk)
+
+
+def qkey_to_vk(qt_key):
+    """Convert a Qt.Key alias to a Win32 virtual-key code.
+
+    For letters and digits Qt already uses the VK code, but function and
+    other special keys use a Qt-specific value that must be mapped. F1-F12
+    are contiguous in Qt (0x01000030..0x0100003B) and in Win32
+    (0x70..0x7B), so they can be computed; the rest come from a table.
+    """
+    # Qt.Key.F1 = 0x01000030 == VK_F1 = 0x70, and both run contiguously.
+    if 0x01000030 <= qt_key <= 0x0100003B:
+        return 0x70 + (qt_key - 0x01000030)
+    special = {
+        0x01000006: 0x2D,  # Insert
+        0x01000007: 0x2E,  # Delete
+        0x01000010: 0x24,  # Home
+        0x01000011: 0x23,  # End
+        0x01000012: 0x25,  # Left
+        0x01000013: 0x26,  # Up
+        0x01000014: 0x27,  # Right
+        0x01000015: 0x28,  # Down
+        0x01000016: 0x21,  # Page Up
+        0x01000017: 0x22,  # Page Down
+        0x01000020: 0x2C,  # PrintScreen
+        0x20: 0x20,  # Space (VK is 0x20, same as Qt)
+    }
+    if qt_key in special:
+        return special[qt_key]
+    # Qt reserves 0x01000000-0x0100FFFF for special keys; below that an
+    # ASCII/ANSI key's value is already the VK code.
+    if 0x01000000 <= qt_key <= 0x0100FFFF:
+        return 0
+    return qt_key
+
+
+def qmodifiers_to_names(qt_modifiers):
+    """Convert a Qt.KeyboardModifier bitmask to modifier names.
+
+    Accepts either a KeyboardModifier flag (from a QKeyEvent) or a plain
+    int bitmask, since the two come back differently through the bindings.
+    Qt5 and Qt6 use different modifier bit values, so we match against the
+    flag enums rather than raw ints.
+    """
+    from PySide6.QtCore import Qt
+
+    flags = Qt.KeyboardModifier
+    value = getattr(qt_modifiers, "value", qt_modifiers)
+    names = []
+    # The Windows key appears to Qt as the Meta modifier.
+    if value & flags.MetaModifier.value:
+        names.append("win")
+    if value & flags.AltModifier.value:
+        names.append("alt")
+    if value & flags.ControlModifier.value:
+        names.append("ctrl")
+    if value & flags.ShiftModifier.value:
+        names.append("shift")
+    return names
+
+
+class GlobalHotkey(QAbstractNativeEventFilter):
+    """Registers one global hotkey and calls a callback when pressed.
+
+    The callback is invoked on the Qt main thread from within the native
+    event filter, so it is safe to manipulate widgets directly.
+    """
+
+    def __init__(self, combo, callback=None):
+        super().__init__()
+        self._combo = combo
+        self._callback = callback
+        self._hotkey_id = 0xBEEF
+        self._registered = False
+
+    def register(self):
+        """Register the hotkey; returns True on success."""
+        if not _IS_WINDOWS:
+            return False
+        if self._registered:
+            return True
+        result = ctypes.windll.user32.RegisterHotKey(
+            None,
+            self._hotkey_id,
+            self._combo.win32_modifiers(),
+            self._combo.vk,
+        )
+        self._registered = bool(result)
+        return self._registered
+
+    def unregister(self):
+        """Remove the hotkey if it was registered."""
+        if self._registered and _IS_WINDOWS:
+            ctypes.windll.user32.UnregisterHotKey(None, self._hotkey_id)
+            self._registered = False
+
+    def set_callback(self, callback):
+        self._callback = callback
+
+    def set_combo(self, combo):
+        """Swap the registered key for a new combo.
+
+        Unregisters the old hotkey, registers the new one, and returns the
+        new registration result.
+        """
+        self.unregister()
+        self._combo = combo
+        return self.register()
+
+    def nativeEventFilter(self, event_type, message):
+        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_HOTKEY and msg.wParam == self._hotkey_id:
+            if self._callback is not None:
+                self._callback()
+            return True, 0
+        return False, 0