taskbargap

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 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, which is specific about the configurations it has never run on.

Quickstart

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:

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

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:

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

• On Windows 11 the gap is measured from the buttons the taskbar actually draws; elsewhere it is a corroborated reading or a guess, and measured=False is not a safe edge. Windows 11 draws its taskbar in XAML, and the legacy ReBarWindow32 / MSTaskListWClass windows there report a width that can be wrong rather than missing: too narrow to hold the buttons they contain, and blind to the Widgets button, which in a left-aligned layout sits a few pixels left of the clock. The library therefore reads the taskbar's own UI Automation tree, which has one element per drawn button with its screen rectangle, and returns a span between those elements with measured=True. Where there is more than one empty span it takes the rightmost unless that is a sliver (under 40% of the widest), so a left-aligned bar gives the space between the last app button and Widgets, and a centred bar the space right of the cluster. The reading is cached for 3s unless something the cheap reads can see has changed, and costs ~20-30ms when taken.

  Without that tree (Windows 10, Server, a replacement shell, Explorer mid-restart) the legacy windows are used. Their edge is checked against the number of windows that must own a button, and when the arithmetic is impossible you get measured=False plus the more conservative of the two estimates. That is honesty, not safety. A measured=False edge is still a guess and may still overlap buttons. If covering an icon would be unacceptable for your app, treat measured=False as "don't draw here" rather than "draw here carefully".

• 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.