taskbargap 0.1.0__py3-none-any.whl

taskbargap/__init__.py

@@ -0,0 +1,26 @@
+"""taskbargap - place a top-most window in the empty Windows taskbar gap.
+
+Windows 10/11 only. See README.md for usage and DESIGN.md for how it works.
+Every coordinate a caller sees is in physical pixels; `Gap.scale` is the taskbar
+monitor's DPI factor, for toolkits that want logical ones.
+
+    import taskbargap
+
+    taskbargap.enable_dpi_awareness()      # once, before creating windows
+    gap = taskbargap.find_gap()            # -> Gap | None
+    taskbargap.place(my_hwnd, align="right")
+"""
+from ._detect import Gap, find_gap
+from ._place import place
+from ._win32 import NotWindowsError, enable_dpi_awareness
+from .watcher import GapWatcher
+
+__version__ = "0.1.0"
+__all__ = [
+    "Gap",
+    "GapWatcher",
+    "NotWindowsError",
+    "enable_dpi_awareness",
+    "find_gap",
+    "place",
+]

taskbargap/_detect.py

@@ -0,0 +1,111 @@
+"""Find the empty span of the taskbar: `Shell_TrayWnd` -> tray edge, button edge."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from . import _win32
+from ._geometry import BUTTON_FRACTION, gap_span, is_on_taskbar
+
+#: The taskbar itself. (Secondary monitors get `Shell_SecondaryTrayWnd`; v0.1
+#: reads the primary taskbar only. See DESIGN.md.)
+TRAY_CLASS = "Shell_TrayWnd"
+#: The notification/clock cluster on the right: the gap's right bound.
+NOTIFY_CLASS = "TrayNotifyWnd"
+#: The app-button strip: the gap's left bound. `ReBarWindow32` hosts it on both
+#: Win10 and stock Win11; `MSTaskListWClass` is the button list itself, checked
+#: as a fallback because some shells (and secondary taskbars, which use
+#: `WorkerW`) host it elsewhere.
+BUTTON_CLASSES = ("ReBarWindow32", "MSTaskListWClass")
+
+
+@dataclass(frozen=True)
+class Gap:
+    """The empty span of the taskbar, in physical pixels.
+
+    `scale` is the DPI factor of the taskbar's monitor, exposed because toolkits
+    that scale window *position* by DPI (pywebview, WinForms) need the logical
+    value: `x_logical = round(gap.left / gap.scale)`.
+
+    `measured` is True when the app-button edge was read from a real window, and
+    False when it came from the fallback heuristic. Check it before trusting the
+    left edge not to sit on top of the buttons.
+    """
+    left: int
+    right: int
+    top: int
+    bottom: int
+    scale: float          # DPI factor of the taskbar's monitor
+    monitor: int          # HMONITOR
+    measured: bool        # True if the button edge came from a real window
+
+    @property
+    def width(self) -> int:
+        return self.right - self.left
+
+    @property
+    def height(self) -> int:
+        return self.bottom - self.top
+
+
+def _button_edge(tray: int, tray_rect: tuple[int, int, int, int]) -> int | None:
+    """Right edge of the app-button strip, or None if nothing measurable exists.
+
+    Every candidate is sanity-checked against the taskbar's own rect rather than
+    trusted on sight: the shell keeps stale and hidden button windows around
+    (this machine has an invisible `MSTaskListWClass`), and during an Explorer
+    restart a live handle can still report a zero rect. Candidates that don't
+    check out are skipped, so a good window later in the list still wins.
+
+    None means "no shell window would tell us", which sends the caller to the
+    heuristic. Stock Windows 11 (26200) does host these windows and moves them
+    with the buttons in both left and centred layouts, so on it the answer is
+    measured either way.
+    """
+    for cls in BUTTON_CLASSES:
+        hwnd = _win32.find_child(tray, cls) or _win32.find_descendant(tray, cls)
+        if not hwnd:
+            continue
+        rect = _win32.window_rect(hwnd)
+        if is_on_taskbar(rect, tray_rect):
+            return rect[2]
+    return None
+
+
+def find_gap(fraction: float = BUTTON_FRACTION) -> Gap | None:
+    """Detect the empty taskbar gap. Returns a `Gap`, or `None` if there isn't one.
+
+    `None` covers every "no gap right now" state: no taskbar (Explorer
+    restarting), no measurable span, an auto-hidden bar mid-slide. Callers
+    can treat it as normal rather than exceptional. It does not swallow bugs:
+    on a non-Windows platform this raises `NotWindowsError`.
+
+    `fraction` overrides the fallback button-edge heuristic used when the button
+    strip can't be measured (native Windows 11).
+    """
+    tray = _win32.find_window(TRAY_CLASS)
+    if not tray:
+        return None
+    rect = _win32.window_rect(tray)
+    if not rect:
+        return None
+    tray_l, tray_t, tray_r, tray_b = rect
+    if tray_r <= tray_l or tray_b <= tray_t:
+        return None      # Explorer restarting: a live handle with a dead rect
+    if (tray_b - tray_t) > (tray_r - tray_l):
+        return None      # docked left/right (Win10): there is no horizontal gap
+
+    notify_rect = _win32.window_rect(_win32.find_child(tray, NOTIFY_CLASS))
+    # The tray cluster's *left* edge is the gap's right bound - and it gets the
+    # same sanity check, so a dead tray rect can't push the gap over the clock.
+    notify_left = notify_rect[0] if is_on_taskbar(notify_rect, rect) else None
+
+    span = gap_span(tray_l, tray_r, notify_left, _button_edge(tray, rect), fraction)
+    if span is None:
+        return None
+    left, right, measured = span
+    return Gap(
+        left=left, right=right, top=tray_t, bottom=tray_b,
+        scale=_win32.window_scale(tray),
+        monitor=_win32.monitor_from_window(tray),
+        measured=measured,
+    )

taskbargap/_geometry.py

@@ -0,0 +1,126 @@
+"""Pure placement geometry: plain ints in, plain ints out, no Windows.
+
+Deliberately free of ctypes so the arithmetic that decides *where the window
+goes* can be unit-tested on any OS. The Win32 half (`_detect`, `_place`) reads
+rects from the shell and hands them to these functions.
+
+All coordinates are physical pixels.
+"""
+from __future__ import annotations
+
+#: Fallback for the app-button edge when a shell hosts no measurable button
+#: window: assume the buttons end 30% of the way across the taskbar. Inherited
+#: from the app this code came from, where it shipped. Stock Windows 11 (26200)
+#: does host those windows, in both left and centred layouts, so this is a
+#: rarely-taken and unvalidated path. `Gap.measured` is False whenever it is used.
+BUTTON_FRACTION = 0.30
+
+ALIGNMENTS = ("left", "center", "right")
+
+
+def is_on_taskbar(
+    rect: tuple[int, int, int, int] | None,
+    tray_rect: tuple[int, int, int, int],
+) -> bool:
+    """Is `rect` a live window rect that actually sits on this taskbar?
+
+    A window handle existing is not evidence that its rect means anything. The
+    shell keeps taskbar children around that are hidden or mid-teardown, and during
+    an Explorer restart `GetWindowRect` happily returns `(0, 0, 0, 0)`. A
+    zero rect read as a button edge puts the gap's left bound at the far left of
+    the screen, i.e. straight over the Start button and every app button.
+
+    So a candidate must be a non-empty rect that overlaps the taskbar's own.
+    Failing this means "couldn't measure", which sends `find_gap()` to its
+    heuristic, which is the honest answer. It deliberately does not reject a plausible
+    edge that leaves no room: a genuinely full taskbar has no gap, and inventing
+    one there would cover real buttons.
+    """
+    if rect is None:
+        return False
+    left, top, right, bottom = rect
+    if right <= left or bottom <= top:
+        return False                                 # degenerate: not a live window
+    tray_left, tray_top, tray_right, tray_bottom = tray_rect
+    if right <= tray_left or left >= tray_right:
+        return False                                 # not horizontally on this bar
+    return not (bottom <= tray_top or top >= tray_bottom)
+
+
+def gap_span(
+    tray_left: int,
+    tray_right: int,
+    notify_left: int | None = None,
+    button_right: int | None = None,
+    fraction: float = BUTTON_FRACTION,
+) -> tuple[int, int, bool] | None:
+    """Compute the empty horizontal span of the taskbar.
+
+    `tray_left`/`tray_right` bound the whole taskbar. `notify_left` is the left
+    edge of the notification/clock cluster (the gap's right bound); `None` means
+    it wasn't found, so the taskbar's own right edge is used. `button_right` is
+    the right edge of the app-button strip (the gap's left bound); `None` means
+    it couldn't be measured, so `fraction` of the taskbar width is assumed.
+
+    Returns `(left, right, measured)` where `measured` is True only when the
+    button edge came from a real window, or `None` when there is no usable span.
+    """
+    if tray_right <= tray_left:
+        return None
+    if button_right is None:
+        left = tray_left + int((tray_right - tray_left) * fraction)
+        measured = False
+    else:
+        left = button_right
+        measured = True
+    right = tray_right if notify_left is None else notify_left
+    # Clamp into the taskbar: a stale or bogus child rect must not produce a
+    # span that reaches off the bar.
+    left = min(max(left, tray_left), tray_right)
+    right = min(max(right, tray_left), tray_right)
+    if right - left <= 0:
+        return None
+    return left, right, measured
+
+
+def fit(
+    gap_left: int,
+    gap_right: int,
+    *,
+    align: str = "right",
+    margin: int = 12,
+    min_width: int = 160,
+    width: int | None = None,
+) -> tuple[int, int] | None:
+    """Compute `(x, width)` for a window inside the span `[gap_left, gap_right)`.
+
+    A `margin` of clear space is kept at each end. `width` is the desired width;
+    `None` means "fill the gap". The result never widens past the gap, so it can
+    never overlap the app buttons or the tray.
+
+    Returns `None` when `min_width` doesn't fit, leaving the caller to decide
+    what that means (hide, shrink, do nothing), because that is policy rather
+    than placement.
+    """
+    if align not in ALIGNMENTS:
+        raise ValueError(f"align must be one of {ALIGNMENTS!r}, got {align!r}")
+    if margin < 0:
+        raise ValueError(f"margin must be >= 0, got {margin!r}")
+    if min_width < 0:
+        raise ValueError(f"min_width must be >= 0, got {min_width!r}")
+    if width is not None and width <= 0:
+        raise ValueError(f"width must be > 0 or None, got {width!r}")
+
+    span = gap_right - gap_left
+    avail = span - 2 * margin
+    if avail < min_width or avail <= 0:
+        return None
+    w = avail if width is None else min(width, avail)
+    w = max(w, min_width)      # avail >= min_width here, so w <= avail always
+    if align == "left":
+        x = gap_left + margin
+    elif align == "center":
+        x = gap_left + (span - w) // 2
+    else:
+        x = gap_right - margin - w
+    return x, w

taskbargap/_place.py

@@ -0,0 +1,74 @@
+"""Move an existing window into the gap as a top-most tool window."""
+from __future__ import annotations
+
+from . import _win32
+from ._detect import Gap, find_gap
+from ._geometry import fit
+
+#: A gap window wants no taskbar button and no Alt-Tab entry, and it must sit in
+#: the top-most band. WS_EX_APPWINDOW is cleared because it would force the
+#: taskbar button back on.
+_EX_ADD = _win32.WS_EX_TOOLWINDOW | _win32.WS_EX_TOPMOST
+_EX_REMOVE = _win32.WS_EX_APPWINDOW
+
+
+def place(
+    hwnd: int,
+    *,
+    align: str = "right",
+    margin: int = 12,
+    min_width: int = 160,
+    width: int | None = None,
+    height: int | None = None,
+    gap: Gap | None = None,
+    nonblocking: bool = False,
+) -> bool:
+    """Size and position `hwnd` inside the taskbar gap as a top-most tool window.
+
+    All sizes are physical pixels. `align` is "left" | "center" | "right".
+    `width` defaults to filling the gap; `height` to the taskbar's own height.
+    Pass `gap` to place against an already-detected gap instead of re-detecting.
+
+    Returns False, and touches nothing, when there is no gap or `min_width`
+    doesn't fit inside it; and False if Windows refuses the move (a window owned
+    by a higher-integrity process, or destroyed since the call began), which is
+    logged. The rectangle it asks for is never wider than the gap, so it cannot
+    ask to cover the app buttons or the tray. Whether "didn't fit" should mean
+    hiding is the caller's call, since that is app policy rather than placement.
+
+    The window is shown with SW_SHOWNA, so placing it never steals focus.
+
+    Call it from the thread that owns `hwnd` (the usual case) and the move has
+    happened by the time it returns. From any other thread pass
+    `nonblocking=True`: the move is posted to the owning thread instead, so a
+    busy or stalled UI thread can't hang the caller. It then takes effect when
+    that thread next pumps messages, and `True` means "asked", not "moved".
+
+    One step has no asynchronous form: applying the tool-window/top-most
+    extended styles sends WM_STYLECHANGED to the owning thread and waits. It
+    only ever runs when the styles aren't already right, that is the first time a
+    given window is placed, so call `place()` (or `GapWatcher.start()`) once
+    from the owning thread and every later call is fully non-blocking.
+    """
+    if not _win32.is_window(hwnd):
+        return False
+    if gap is None:
+        gap = find_gap()
+    if gap is None:
+        return False
+    box = fit(gap.left, gap.right, align=align, margin=margin,
+              min_width=min_width, width=width)
+    if box is None:
+        return False
+    x, w = box
+    h = gap.height if height is None else height
+
+    # Windows only drops an existing taskbar button / Alt-Tab entry when the
+    # window is hidden across the style change, so hide first if we changed it.
+    # A changed style also needs SWP_FRAMECHANGED to take effect on the frame,
+    # which the move below folds in.
+    styled = _win32.set_ex_styles(hwnd, add=_EX_ADD, remove=_EX_REMOVE)
+    if styled:
+        _win32.hide(hwnd, nonblocking)
+    return _win32.move_topmost(hwnd, x, gap.top, w, h, nonblocking=nonblocking,
+                               frame_changed=styled)

taskbargap/_win32.py

@@ -0,0 +1,354 @@
+"""ctypes bindings for the small slice of user32 this library needs.
+
+Two deliberate choices:
+
+* **A private `user32` handle.** We load our own `ctypes.WinDLL("user32")`
+  rather than annotating the process-wide `ctypes.windll.user32`, because a
+  library must not mutate global ctypes state that the host app (pywebview,
+  WinForms, another package) also uses.
+* **Importable anywhere.** No `ctypes.wintypes`, no `windll` at import time, so
+  `import taskbargap` works on any OS and the pure geometry can be tested there.
+  The Windows requirement only bites when you actually call something.
+"""
+from __future__ import annotations
+
+import ctypes
+import logging
+import sys
+
+log = logging.getLogger("taskbargap")
+
+# --- constants ---------------------------------------------------------------
+
+GWL_EXSTYLE = -20
+WS_EX_TOPMOST = 0x00000008
+WS_EX_TOOLWINDOW = 0x00000080
+WS_EX_APPWINDOW = 0x00040000
+WS_EX_NOACTIVATE = 0x08000000
+
+HWND_TOPMOST = -1
+SWP_NOSIZE, SWP_NOMOVE, SWP_NOACTIVATE = 0x0001, 0x0002, 0x0010
+#: Required for a SetWindowLong style change to take effect on the window frame.
+SWP_FRAMECHANGED = 0x0020
+#: Post the change to the owning thread instead of waiting for it to handle it.
+#: Without this, a SetWindowPos/ShowWindow issued from a thread that does not own
+#: the window blocks until the owner pumps its message loop - so a background
+#: watcher would hang for as long as the UI thread is busy.
+SWP_ASYNCWINDOWPOS = 0x4000
+SWP_TOPMOST_ONLY = SWP_NOSIZE | SWP_NOMOVE | SWP_NOACTIVATE
+
+SW_HIDE, SW_SHOW, SW_SHOWNA = 0, 5, 8
+
+MONITOR_DEFAULTTONEAREST = 2
+DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2 = -4
+#: DPI_AWARENESS enum. Per-monitor-v2 also reports as PER_MONITOR_AWARE here.
+DPI_AWARENESS_UNAWARE = 0
+DPI_AWARENESS_SYSTEM_AWARE = 1
+DPI_AWARENESS_PER_MONITOR_AWARE = 2
+
+
+# --- structures (hand-rolled: ctypes.wintypes is Windows-only) ----------------
+
+class RECT(ctypes.Structure):
+    _fields_ = [("left", ctypes.c_long), ("top", ctypes.c_long),
+                ("right", ctypes.c_long), ("bottom", ctypes.c_long)]
+
+
+class MONITORINFO(ctypes.Structure):
+    _fields_ = [("cbSize", ctypes.c_ulong), ("rcMonitor", RECT),
+                ("rcWork", RECT), ("dwFlags", ctypes.c_ulong)]
+
+
+_HWND = ctypes.c_void_p
+_INT = ctypes.c_int
+_UINT = ctypes.c_uint
+_DWORD = ctypes.c_ulong
+_BOOL = ctypes.c_int
+_LPCWSTR = ctypes.c_wchar_p
+
+_user32 = None
+
+
+class NotWindowsError(OSError):
+    """Raised when a Win32 call is attempted on a non-Windows platform."""
+
+
+def user32():
+    """Return the annotated, process-private user32 handle (cached)."""
+    global _user32
+    if _user32 is None:
+        if not sys.platform.startswith("win"):
+            raise NotWindowsError(
+                "taskbargap is Windows-only: it is built on Win32 shell windows "
+                f"(running on {sys.platform!r})")
+        u = ctypes.WinDLL("user32", use_last_error=True)
+        _annotate(u)
+        _user32 = u
+    return _user32
+
+
+def _annotate(u) -> None:
+    """Set argtypes/restypes. Handles are pointer-sized: without this they are
+    truncated to 32 bits on 64-bit Python and every call silently fails."""
+    u.FindWindowW.argtypes = [_LPCWSTR, _LPCWSTR]
+    u.FindWindowW.restype = _HWND
+    u.FindWindowExW.argtypes = [_HWND, _HWND, _LPCWSTR, _LPCWSTR]
+    u.FindWindowExW.restype = _HWND
+    u.GetWindowRect.argtypes = [_HWND, ctypes.POINTER(RECT)]
+    u.GetWindowRect.restype = _BOOL
+    u.IsWindow.argtypes = [_HWND]
+    u.IsWindow.restype = _BOOL
+    u.IsWindowVisible.argtypes = [_HWND]
+    u.IsWindowVisible.restype = _BOOL
+    u.SetWindowPos.argtypes = [_HWND, _HWND, _INT, _INT, _INT, _INT, _UINT]
+    u.SetWindowPos.restype = _BOOL
+    u.ShowWindow.argtypes = [_HWND, _INT]
+    u.ShowWindow.restype = _BOOL
+    u.ShowWindowAsync.argtypes = [_HWND, _INT]
+    u.ShowWindowAsync.restype = _BOOL
+    u.GetWindowLongW.argtypes = [_HWND, _INT]
+    u.GetWindowLongW.restype = ctypes.c_int32
+    u.SetWindowLongW.argtypes = [_HWND, _INT, ctypes.c_int32]
+    u.SetWindowLongW.restype = ctypes.c_int32
+    u.MonitorFromWindow.argtypes = [_HWND, _DWORD]
+    u.MonitorFromWindow.restype = _HWND
+    u.GetMonitorInfoW.argtypes = [_HWND, ctypes.POINTER(MONITORINFO)]
+    u.GetMonitorInfoW.restype = _BOOL
+    try:                                   # Win10 1607+; absent on older builds
+        u.GetDpiForWindow.argtypes = [_HWND]
+        u.GetDpiForWindow.restype = _UINT
+        u.GetDpiForSystem.restype = _UINT
+        u.GetThreadDpiAwarenessContext.restype = ctypes.c_void_p
+        u.GetAwarenessFromDpiAwarenessContext.argtypes = [ctypes.c_void_p]
+        u.GetAwarenessFromDpiAwarenessContext.restype = _INT
+    except AttributeError:
+        pass
+
+
+# --- helpers -----------------------------------------------------------------
+
+def _handle(value) -> int:
+    """Normalise a returned HWND/HMONITOR (int or None) to a plain int."""
+    return int(value or 0)
+
+
+def _as_i32(value: int) -> int:
+    """Window longs are signed 32-bit; style bit-sets are naturally unsigned."""
+    value &= 0xFFFFFFFF
+    return value - 0x100000000 if value > 0x7FFFFFFF else value
+
+
+def find_window(class_name: str) -> int:
+    """Top-level window by class name; 0 if absent."""
+    return _handle(user32().FindWindowW(class_name, None))
+
+
+def find_child(parent: int, class_name: str) -> int:
+    """Direct child by class name; 0 if absent."""
+    return _handle(user32().FindWindowExW(parent, None, class_name, None))
+
+
+def find_descendant(parent: int, class_name: str, max_depth: int = 3) -> int:
+    """Breadth-first search of `parent`'s descendants for a class name; 0 if absent.
+
+    Depth-limited: the taskbar tree is shallow, and an unbounded walk of shell
+    windows is both slow and a good way to hang on a busy Explorer.
+    """
+    u = user32()
+    level = [parent]
+    for _ in range(max_depth):
+        nxt = []
+        for hwnd in level:
+            found = _handle(u.FindWindowExW(hwnd, None, class_name, None))
+            if found:
+                return found
+            child = None
+            while True:
+                child = u.FindWindowExW(hwnd, child, None, None)
+                if not child:
+                    break
+                nxt.append(_handle(child))
+        if not nxt:
+            break
+        level = nxt
+    return 0
+
+
+def window_rect(hwnd: int) -> tuple[int, int, int, int] | None:
+    """`(left, top, right, bottom)` in physical px, or None if the call fails."""
+    if not hwnd:
+        return None
+    r = RECT()
+    if not user32().GetWindowRect(hwnd, ctypes.byref(r)):
+        return None
+    return r.left, r.top, r.right, r.bottom
+
+
+def is_window(hwnd: int) -> bool:
+    return bool(hwnd) and bool(user32().IsWindow(hwnd))
+
+
+def is_window_visible(hwnd: int) -> bool:
+    return bool(hwnd) and bool(user32().IsWindowVisible(hwnd))
+
+
+def monitor_from_window(hwnd: int) -> int:
+    return _handle(user32().MonitorFromWindow(hwnd, MONITOR_DEFAULTTONEAREST))
+
+
+def monitor_rect(hmonitor: int) -> tuple[int, int, int, int] | None:
+    if not hmonitor:
+        return None
+    mi = MONITORINFO()
+    mi.cbSize = ctypes.sizeof(MONITORINFO)
+    if not user32().GetMonitorInfoW(hmonitor, ctypes.byref(mi)):
+        return None
+    r = mi.rcMonitor
+    return r.left, r.top, r.right, r.bottom
+
+
+def system_scale(fallback: float = 1.0) -> float:
+    """DPI factor of the primary monitor (or of the process, if unaware)."""
+    try:
+        dpi = user32().GetDpiForSystem()
+    except (AttributeError, OSError):
+        return fallback
+    return dpi / 96.0 if dpi else fallback
+
+
+def process_dpi_awareness() -> int:
+    """This process's `DPI_AWARENESS_*` value, or PER_MONITOR when unknowable."""
+    u = user32()
+    try:
+        ctx = u.GetThreadDpiAwarenessContext()
+        return u.GetAwarenessFromDpiAwarenessContext(ctx)
+    except (AttributeError, OSError):
+        # Pre-1607: no way to ask, and no per-monitor DPI to get wrong either.
+        return DPI_AWARENESS_PER_MONITOR_AWARE
+
+
+def process_is_dpi_aware() -> bool:
+    """True unless this process is DPI-*un*aware, i.e. gets virtualised coordinates."""
+    return process_dpi_awareness() != DPI_AWARENESS_UNAWARE
+
+
+def window_scale(hwnd: int, fallback: float | None = None) -> float:
+    """DPI factor of the monitor `hwnd` is on, *as this process sees it*.
+
+    The subtlety: `GetDpiForWindow` answers for the **window**, and the taskbar
+    belongs to per-monitor-aware Explorer, so it reports the taskbar monitor's
+    real DPI to anyone who asks, including a process living in a virtualised
+    coordinate space where that number is wrong. Measured on a 175% display:
+    an unaware process is told the taskbar is 168 DPI while it sees a 2194px
+    desktop, and dividing by 1.75 would put the window a third of the way across
+    the screen from where it belongs.
+
+    Only a per-monitor-aware process gets real per-monitor coordinates, so only
+    it may use the window's DPI. Everyone else gets `GetDpiForSystem`, which is
+    documented to answer in the caller's own terms: 96 for an unaware process,
+    the system DPI for a system-aware one, which is exactly the space each of
+    them addresses windows in.
+    """
+    if process_dpi_awareness() == DPI_AWARENESS_PER_MONITOR_AWARE:
+        try:
+            dpi = user32().GetDpiForWindow(hwnd)
+            if dpi:
+                return dpi / 96.0
+        except (AttributeError, OSError):
+            pass
+    return system_scale() if fallback is None else system_scale(fallback)
+
+
+def set_ex_styles(hwnd: int, add: int = 0, remove: int = 0) -> bool:
+    """OR in / mask out extended styles. True if they were actually changed.
+
+    False means either "already correct" or "Windows refused". The caller only
+    needs it to decide whether a frame recalculation is due, and a refusal is
+    logged rather than raised so one un-styleable window can't take down a
+    watcher loop.
+    """
+    u = user32()
+    cur = u.GetWindowLongW(hwnd, GWL_EXSTYLE) & 0xFFFFFFFF
+    new = (cur | add) & ~remove & 0xFFFFFFFF
+    if new == cur:
+        return False
+    ctypes.set_last_error(0)
+    previous = u.SetWindowLongW(hwnd, GWL_EXSTYLE, _as_i32(new))
+    err = ctypes.get_last_error()
+    if previous == 0 and err:          # 0 is a legal previous value; 0 + error is not
+        log.warning("taskbargap: could not set extended styles on window %s "
+                    "(WinError %d) - it may keep its taskbar button", hwnd, err)
+        return False
+    return True
+
+
+def move_topmost(hwnd: int, x: int, y: int, w: int, h: int,
+                 show: int = SW_SHOWNA, nonblocking: bool = False,
+                 frame_changed: bool = False) -> bool:
+    """Move and size a window, pin it to the topmost band, and show it.
+
+    Shown with SW_SHOWNA by default, so it never steals focus. Pass
+    `nonblocking=True` from a thread that doesn't own the window, and
+    `frame_changed=True` after a style change, because Win32 requires SWP_FRAMECHANGED
+    for one to take effect on the window frame, and folding it into this call
+    saves a second round trip to the owning thread.
+
+    Returns whether Windows accepted the request. `ShowWindow`'s return value is
+    the window's *previous* visibility, not a success flag, so it isn't consulted.
+    """
+    u = user32()
+    flags = SWP_NOACTIVATE
+    if nonblocking:
+        flags |= SWP_ASYNCWINDOWPOS
+    if frame_changed:
+        flags |= SWP_FRAMECHANGED
+    ctypes.set_last_error(0)
+    ok = bool(u.SetWindowPos(hwnd, HWND_TOPMOST, x, y, w, h, flags))
+    if not ok:
+        log.warning("taskbargap: could not place window %s (WinError %d)",
+                    hwnd, ctypes.get_last_error())
+    show_window(hwnd, show, nonblocking)
+    return ok
+
+
+def assert_topmost(hwnd: int, nonblocking: bool = False) -> None:
+    """Re-pin to the topmost band without moving, resizing, or activating."""
+    flags = SWP_TOPMOST_ONLY | (SWP_ASYNCWINDOWPOS if nonblocking else 0)
+    user32().SetWindowPos(hwnd, HWND_TOPMOST, 0, 0, 0, 0, flags)
+
+
+def show_window(hwnd: int, show: int, nonblocking: bool = False) -> None:
+    u = user32()
+    (u.ShowWindowAsync if nonblocking else u.ShowWindow)(hwnd, show)
+
+
+def hide(hwnd: int, nonblocking: bool = False) -> None:
+    show_window(hwnd, SW_HIDE, nonblocking)
+
+
+def enable_dpi_awareness() -> bool:
+    """Opt into per-monitor-v2 DPI awareness. Call once, before creating windows.
+
+    Without it, Windows lies to the process about coordinates on any monitor
+    whose scaling differs from the primary, and a window aimed at the taskbar
+    gap lands somewhere else. Falls back to system-DPI awareness on Windows
+    older than 1703.
+
+    Returns whether the process ends up DPI-aware, rather than whether this particular
+    call was the one that did it. Awareness can only be set once per process, so
+    a second call, or a process already aware via its manifest (pywebview, a
+    frozen exe), still answers True rather than reporting a failure that isn't.
+    """
+    u = user32()
+    try:
+        if u.SetProcessDpiAwarenessContext(
+                ctypes.c_void_p(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2)):
+            return True
+    except (AttributeError, OSError):
+        pass
+    try:
+        if u.SetProcessDPIAware():
+            return True
+    except (AttributeError, OSError):
+        pass
+    return process_is_dpi_aware()

taskbargap/watcher.py

@@ -0,0 +1,193 @@
+"""Keep a window fitted to the gap and top-most as the taskbar changes."""
+from __future__ import annotations
+
+import logging
+import threading
+from collections.abc import Callable
+
+from . import _win32
+from ._detect import Gap, find_gap
+from ._place import place
+
+log = logging.getLogger("taskbargap")
+
+#: Ignore sub-pixel-ish jitter in the detected edges; re-place only on a real move.
+MOVE_TOLERANCE = 8
+#: DPI factors are floats; compare with a tolerance, not ==.
+SCALE_TOLERANCE = 0.01
+
+
+class GapWatcher:
+    """Background watcher that re-fits `hwnd` when the taskbar gap changes.
+
+    Apps open and close, Explorer restarts, the screen changes resolution, the
+    window gets dragged to a monitor with different scaling. All of these move
+    the gap out from under a window placed once at startup. The watcher polls
+    (there is no reliable event for "the button strip resized"), re-asserts
+    top-most every tick, and re-places only when the gap has actually moved.
+
+    `on_change(gap)` fires from the watcher thread whenever the gap moves. The
+    initial placement in `start()` doesn't count, and a change is reported even
+    when the new gap is too narrow to place into, because "the gap shrank" is
+    exactly when an app wants to apply its own policy (yield when crowded, hide
+    over fullscreen). A raising callback is logged, not fatal.
+
+    Every window change the loop makes is posted, not sent (SWP_ASYNCWINDOWPOS /
+    ShowWindowAsync), because the window belongs to the app's UI thread: a
+    synchronous SetWindowPos from here would block until that thread pumped its
+    message loop, and a busy one would silently freeze the watcher. The flip
+    side is that a re-fit lands when the app next pumps, which is normal for a GUI app,
+    but nothing moves while the UI thread is blocked.
+
+    Not started automatically. Owns one daemon thread between `start()` and
+    `stop()`; usable as a context manager.
+    """
+
+    def __init__(
+        self,
+        hwnd: int,
+        *,
+        align: str = "right",
+        margin: int = 12,
+        min_width: int = 160,
+        width: int | None = None,
+        height: int | None = None,
+        interval: float = 1.0,
+        on_change: Callable[[Gap], None] | None = None,
+    ) -> None:
+        if interval <= 0:
+            raise ValueError(f"interval must be > 0, got {interval!r}")
+        self.hwnd = hwnd
+        self.align = align
+        self.margin = margin
+        self.min_width = min_width
+        self.width = width
+        self.height = height
+        self.interval = interval
+        self.on_change = on_change
+        self._thread: threading.Thread | None = None
+        # One Event per run, owned by the thread that run started. A shared Event
+        # could be cleared by a restart while an older thread was still inside a
+        # tick, which would revive it and leave two loops fighting over the window.
+        self._stop: threading.Event | None = None
+        self._gap: Gap | None = None
+        self._last_error: BaseException | None = None
+
+    # --- state ---------------------------------------------------------------
+
+    @property
+    def gap(self) -> Gap | None:
+        """The gap as of the last time it changed; None until the first tick."""
+        return self._gap
+
+    @property
+    def running(self) -> bool:
+        return self._thread is not None and self._thread.is_alive()
+
+    @property
+    def last_error(self) -> BaseException | None:
+        """The last exception the loop swallowed, so a caller can surface it.
+
+        The loop keeps going after an error (a transient Win32 failure during an
+        Explorer restart must not silently kill the watcher for the rest of the
+        session), but it does not hide it: every error is logged and kept here.
+        """
+        return self._last_error
+
+    # --- lifecycle -----------------------------------------------------------
+
+    def start(self) -> None:
+        """Place the window now, then start watching.
+
+        The first placement runs synchronously, on *your* thread, on purpose:
+        it is the call that applies the tool-window/top-most styles, and a style
+        change is the one Win32 operation here with no asynchronous form, and it
+        would block the watcher thread until the app pumped messages. Doing it
+        here means the loop only ever moves an already-styled window, which it
+        can do without waiting on anyone.
+
+        Call it from the thread that owns the window (normally the UI thread).
+        """
+        if self.running:
+            raise RuntimeError("GapWatcher is already running")
+        gap = find_gap()
+        if gap is not None:
+            self._gap = gap
+            self._place(gap, nonblocking=False)
+        stop = threading.Event()
+        self._stop = stop
+        self._thread = threading.Thread(
+            target=self._loop, args=(stop,), name="taskbargap-watcher", daemon=True)
+        self._thread.start()
+
+    def stop(self, timeout: float | None = 5.0) -> bool:
+        """Ask the thread to finish and wait for it. Safe to call when stopped.
+
+        Returns whether it actually finished. A thread that outlives `timeout`
+        is kept rather than forgotten, so `running` keeps telling the truth, and it
+        will still exit on its own, because the Event it waits on is its own and
+        stays set no matter how many times the watcher is restarted.
+        """
+        if self._stop is not None:
+            self._stop.set()
+        thread = self._thread
+        if thread is None or thread is threading.current_thread():
+            self._thread = None
+            return True
+        thread.join(timeout)
+        if thread.is_alive():
+            log.warning("taskbargap: watcher thread did not stop within %ss; "
+                        "it will exit after its current tick", timeout)
+            return False
+        self._thread = None
+        return True
+
+    # Annotated by name rather than `typing.Self`, which needs 3.11 or a
+    # typing_extensions dependency. This package has no dependencies and the
+    # floor is 3.10, so the postponed annotation stays a plain string.
+    def __enter__(self) -> GapWatcher:  # noqa: PYI034
+        self.start()
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.stop()
+
+    # --- loop ----------------------------------------------------------------
+
+    def _changed(self, gap: Gap) -> bool:
+        old = self._gap
+        return (
+            old is None
+            or abs(gap.left - old.left) > MOVE_TOLERANCE
+            or abs(gap.right - old.right) > MOVE_TOLERANCE
+            or gap.top != old.top
+            or gap.bottom != old.bottom
+            or abs(gap.scale - old.scale) > SCALE_TOLERANCE
+        )
+
+    def _place(self, gap: Gap, nonblocking: bool) -> bool:
+        return place(self.hwnd, align=self.align, margin=self.margin,
+                     min_width=self.min_width, width=self.width,
+                     height=self.height, gap=gap, nonblocking=nonblocking)
+
+    def _loop(self, stop: threading.Event) -> None:
+        while not stop.wait(self.interval):
+            try:
+                if not _win32.is_window(self.hwnd):
+                    log.debug("taskbargap: window %s is gone, watcher exiting", self.hwnd)
+                    return
+                _win32.assert_topmost(self.hwnd, nonblocking=True)
+                gap = find_gap()
+                if gap is None or not self._changed(gap):
+                    continue
+                self._gap = gap
+                self._place(gap, nonblocking=True)
+                if self.on_change is not None:
+                    try:
+                        self.on_change(gap)
+                    except Exception as exc:            # caller's callback
+                        self._last_error = exc
+                        log.exception("taskbargap: on_change callback raised")
+            except Exception as exc:                    # keep watching
+                self._last_error = exc
+                log.exception("taskbargap: watcher tick failed")

taskbargap-0.1.0.dist-info/METADATA

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: taskbargap
+Version: 0.1.0
+Summary: Find the empty gap in the Windows taskbar and place a top-most window in it, across monitors and DPI.
+Author: paone9
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/paone9/taskbargap
+Project-URL: Issues, https://github.com/paone9/taskbargap/issues
+Project-URL: Changelog, https://github.com/paone9/taskbargap/blob/main/CHANGELOG.md
+Keywords: windows,taskbar,win32,topmost,dpi,widget,taskbar-gap,shell
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Desktop Environment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: ruff==0.16.1; extra == "dev"
+Requires-Dist: bandit==1.9.4; extra == "dev"
+Requires-Dist: pytest==9.1.1; extra == "dev"
+Dynamic: license-file
+
+# taskbargap
+
+[![Platform: Windows 10/11](https://img.shields.io/badge/platform-Windows%2010%20%7C%2011-0078d6)](#honest-limitations)
+[![PyPI](https://img.shields.io/pypi/v/taskbargap)](https://pypi.org/project/taskbargap/)
+[![CI](https://github.com/paone9/taskbargap/actions/workflows/ci.yml/badge.svg)](https://github.com/paone9/taskbargap/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/paone9/taskbargap/actions/workflows/codeql.yml/badge.svg)](https://github.com/paone9/taskbargap/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/paone9/taskbargap/badge)](https://scorecard.dev/viewer/?uri=github.com/paone9/taskbargap)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Find the empty stretch of the Windows taskbar, the gap between your app buttons
+and the system tray, and put a top-most window in it. Correctly, across multiple
+monitors and per-monitor DPI scaling.
+
+Windows leaves that strip unused, so a small always-on widget there costs you no
+screen space. Doing it properly turns out to be fiddly. You have to detect the gap
+across two generations of taskbar internals, handle per-monitor DPI and the
+difference between physical and logical pixels, keep the window fitted as apps
+open and close, and end up with a top-most tool window that owns its input without
+grabbing a taskbar button of its own. This library does that, and nothing else.
+
+> **Windows 10/11 only.** It is built on Win32 APIs, and there is no macOS or Linux
+> build. The package imports anywhere, but calling into it off Windows raises
+> `NotWindowsError`.
+
+## Install
+
+```
+pip install taskbargap
+```
+
+The only dependency is the standard library (`ctypes`). It writes nothing at all:
+no files, no registry keys, no config, no logs. It makes no network calls. See
+[SECURITY.md](SECURITY.md) for the complete list of Win32 calls it makes.
+
+This is an alpha, and it says so on the tin. Before you rely on it, read [what
+has and hasn't been validated](DESIGN.md), which is specific about the
+configurations it has never run on.
+
+## Quickstart
+
+```python
+import taskbargap
+
+taskbargap.enable_dpi_awareness()          # call once, before creating windows
+
+gap = taskbargap.find_gap()                # -> Gap | None
+if gap:
+    print(gap.left, gap.right, gap.width, gap.scale)
+
+# Place a window (by HWND) into the gap, right-aligned near the tray:
+taskbargap.place(my_hwnd, align="right", margin=12)
+```
+
+To keep it fitted as the taskbar changes, when apps open and close, when Explorer
+restarts, when the resolution changes:
+
+```python
+watcher = taskbargap.GapWatcher(my_hwnd, align="right")
+watcher.start()          # places it now, then re-fits on change and re-asserts top-most
+# ...
+watcher.stop()
+```
+
+`start()` places the window immediately, on your thread, and returns. The polling
+happens on a daemon thread afterwards. Pass `on_change=fn` if you want to be told
+when the gap moves, including when it gets too narrow to fit, which is usually
+when an app wants to get out of the way.
+
+## API
+
+| Object | Purpose |
+|--------|---------|
+| `find_gap() -> Gap \| None` | Detect the empty taskbar gap on the primary monitor. `None` if there isn't a usable one. |
+| `place(hwnd, *, align="right", margin=12, min_width=160, width=None, height=None, gap=None, nonblocking=False) -> bool` | Size and position an existing window inside the gap as a top-most tool window. `width` defaults to filling the gap, `height` to the taskbar's own height. False means it did nothing: no gap, `min_width` didn't fit, or Windows refused the move. |
+| `GapWatcher(hwnd, *, align, margin, min_width, width, height, interval=1.0, on_change=None)` | Background watcher that keeps the window fitted and top-most as the taskbar changes. `.start()` / `.stop() -> bool`, or use it as a context manager. |
+| `enable_dpi_awareness() -> bool` | Opt into per-monitor-v2 DPI awareness. Falls back gracefully on old Windows. |
+| `Gap` | Frozen dataclass: `left, right, top, bottom` (physical px), `scale` (DPI factor), `monitor` (HMONITOR), `measured`, plus `width` / `height`. |
+| `NotWindowsError` | Raised by any Win32 call when you're not on Windows. |
+
+### Units, and the DPI contract
+
+Every coordinate you get back is a **physical pixel** in the coordinate space your
+process actually sees. `Gap.scale` is the divisor for toolkits that scale window
+position by DPI, such as pywebview and WinForms:
+
+```python
+x_logical = round(gap.left / gap.scale)
+```
+
+Call `enable_dpi_awareness()` before you create any window. Without it Windows
+virtualises coordinates (a 3840px screen at 175% looks 2194px wide) and a window
+aimed at the gap lands somewhere else.
+
+Whatever you do, `scale` describes the space your process addresses windows in,
+rather than the monitor's spec sheet. That means `1.0` for a DPI-unaware process,
+the system DPI for a system-aware one, and the taskbar monitor's own factor only
+for a per-monitor-aware one. The distinction is not academic: `GetDpiForWindow`
+will happily report the taskbar's real 175% to an unaware caller that sees a
+2194px desktop, and dividing by that number puts the window a third of the screen
+away from where it belongs. The library stays self-consistent in every mode. It is
+only in per-monitor mode that you get real screen pixels and an unscaled window.
+
+## What it deliberately does not do
+
+- No metrics, rendering, or UI. You bring the window, it does the placement.
+- No decision about *whether* to be visible. Fullscreen-hide and yielding to a
+  crowded taskbar are app policy, and `find_gap()` gives you the facts to decide.
+- No cross-platform panels. Windows taskbar only.
+
+## Honest limitations
+
+- **When the button strip can't be measured.** The app-button edge is read from the
+  taskbar's own `ReBarWindow32` and `MSTaskListWClass` windows. On stock Windows 11
+  (build 26200) those exist and track the buttons in both left-aligned and centred
+  layouts, measured here both ways, so the common cases are the measured ones.
+  Where a shell doesn't host them, `find_gap()` falls back to assuming the buttons
+  end 30% across the bar, and sets `measured=False`. Be clear-eyed about that
+  fallback. It is a guess inherited from the app this code was extracted from, it
+  has never run on a real machine, and it can name a left edge that still has
+  buttons on it. Check `Gap.measured` if covering a button would matter to you.
+- **Rects are sanity-checked, so detection degrades rather than lies.** A taskbar
+  child reporting a dead or off-bar rectangle, which happens while Explorer is
+  restarting, is ignored rather than believed, and you get the heuristic with
+  `measured=False`. A plausible edge that leaves no room is respected: a genuinely
+  full taskbar returns `None`, because inventing a gap there would cover buttons.
+- **Primary taskbar only.** Secondary monitors get their own
+  `Shell_SecondaryTrayWnd` bars, and v0.1 reads the primary `Shell_TrayWnd`. The
+  gap you get is on whichever monitor that taskbar is on, at that monitor's DPI.
+- **Horizontal taskbars only.** A taskbar docked left or right, which Windows 10
+  allows, has no horizontal gap worth speaking of, so `find_gap()` returns `None`
+  rather than guess.
+- **The watcher needs your app to pump messages.** It posts its moves rather than
+  sending them, so a busy UI thread can never block it. The flip side is that a
+  re-fit only lands the next time your app processes messages. Normal GUI apps do
+  that constantly, but a wedged one won't move.
+- **Auto-hide taskbars** are not special-cased. You get the gap of the bar wherever
+  it currently is, mid-slide included.
+
+## License
+
+MIT.

taskbargap-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+taskbargap/__init__.py,sha256=dJQg-ealIA9E28PYBr4tOJdOeeRFYXzrjyYkT7xFLNU,795
+taskbargap/_detect.py,sha256=qQLaE_GneBJuriIZSwv80eKcJu0fYo48yZm7Wl_KVGg,4546
+taskbargap/_geometry.py,sha256=o-p9oxjbsVwffZRotvvr7iY_1G_zSMJpdOM3-HpXPJU,5149
+taskbargap/_place.py,sha256=vfLUe2GKN2Ykm42uQsFvcvKkUuTcvXtb8fUS2O4ZW84,3235
+taskbargap/_win32.py,sha256=goTyHeMJdlF6aVh9mdrK6Z7df9rNqxTwafoq9yb3RLI,13298
+taskbargap/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+taskbargap/watcher.py,sha256=VggncibF5rOKMOcM1Q7wIu29mObOw4go_1Xipp4rpEI,8056
+taskbargap-0.1.0.dist-info/licenses/LICENSE,sha256=RFeN2Gtr2SBl8CR4ye_x7X28v7TRk9yNonWzqmS9KTY,1063
+taskbargap-0.1.0.dist-info/METADATA,sha256=dxdqUeTkYbZ0LlIeuGmH4HrXPTRZ4Fe7ZsbyKQoc45s,8751
+taskbargap-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+taskbargap-0.1.0.dist-info/top_level.txt,sha256=rZ5Eb72xtD1gLMm4mreF-pa6CFEpeRgCed_-zW0flVk,11
+taskbargap-0.1.0.dist-info/RECORD,,

taskbargap-0.1.0.dist-info/WHEEL

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

taskbargap-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 paone9
+
+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.

taskbargap-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+taskbargap