deskband11lib 1.5.0__py3-none-win_amd64.whl

deskband11lib/__init__.py

@@ -0,0 +1,32 @@
+"""Host Python UI windows inside the Windows 11 taskbar."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .dpi import enable_per_monitor_dpi_awareness
+from .enums import Easing, HostEventKind, ResultCode, TaskbarAlignment, TaskbarContentPlacement, TaskbarEdge
+from .errors import Deskband11LibError
+from .events import EventHook, HostEvent
+from .host import TaskbarContentHost, is_window_alive
+from .options import STRETCH, TaskbarContentHostOptions
+
+try:
+    __version__ = version("deskband11lib")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "STRETCH",
+    "Deskband11LibError",
+    "Easing",
+    "EventHook",
+    "HostEvent",
+    "HostEventKind",
+    "ResultCode",
+    "TaskbarAlignment",
+    "TaskbarContentHost",
+    "TaskbarContentHostOptions",
+    "TaskbarContentPlacement",
+    "TaskbarEdge",
+    "enable_per_monitor_dpi_awareness",
+    "is_window_alive",
+]

deskband11lib/_bindings.py

@@ -0,0 +1,106 @@
+"""ctypes declarations for deskband11lib.dll, mirroring include/deskband11lib.h."""
+
+from __future__ import annotations
+
+import ctypes
+import functools
+import os
+import sysconfig
+from pathlib import Path
+
+ABI_VERSION = 1
+LIBRARY_PATH_ENVIRONMENT_VARIABLE = "DESKBAND11LIB_LIBRARY_PATH"
+_RUNTIME_IDENTIFIERS = {"win-amd64": "win-x64", "win-arm64": "win-arm64", "win32": "win-x86"}
+
+
+class NativeOptions(ctypes.Structure):
+    _fields_ = [
+        ("struct_size", ctypes.c_uint32),
+        ("animate_layout_changes", ctypes.c_int32),
+        ("high_refresh_rate_mode", ctypes.c_int32),
+        ("layout_animation_easing", ctypes.c_int32),
+        ("track_taskbar_buttons", ctypes.c_int32),
+        ("track_notification_area", ctypes.c_int32),
+        ("preferred_monitor_identity", ctypes.c_int32),
+        ("allow_fixed_slot_resize", ctypes.c_int32),
+        ("placement", ctypes.c_int32),
+        ("manual_slot_priority", ctypes.c_uint32),
+        ("layout_animation_duration", ctypes.c_double),
+        ("preferred_width", ctypes.c_double),
+        ("preferred_height", ctypes.c_double),
+        ("layout_refresh_interval", ctypes.c_double),
+    ]
+
+
+class NativeEvent(ctypes.Structure):
+    _fields_ = [
+        ("kind", ctypes.c_int32),
+        ("result", ctypes.c_int32),
+        ("taskbar_edge", ctypes.c_int32),
+        ("reserved", ctypes.c_int32),
+        ("max_width", ctypes.c_double),
+        ("width", ctypes.c_double),
+        ("height", ctypes.c_double),
+    ]
+
+
+EventCallback = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.POINTER(NativeEvent))
+
+
+def resolve_library_path() -> Path:
+    override = os.environ.get(LIBRARY_PATH_ENVIRONMENT_VARIABLE)
+    if override:
+        return Path(override)
+
+    platform = sysconfig.get_platform()
+    runtime_identifier = _RUNTIME_IDENTIFIERS.get(platform)
+    if runtime_identifier is None:
+        raise OSError(f"deskband11lib does not support the {platform} platform.")
+    return Path(__file__).resolve().parent / "bin" / runtime_identifier / "deskband11lib.dll"
+
+
+@functools.cache
+def load_library() -> ctypes.CDLL:
+    path = resolve_library_path()
+    if not path.is_file():
+        raise OSError(f"The deskband11lib native library was not found at {path}.")
+
+    library = ctypes.CDLL(str(path))
+    _declare_functions(library)
+    abi_version = library.db11l_get_abi_version()
+    if abi_version != ABI_VERSION:
+        raise OSError(f"{path} implements ABI version {abi_version}, but this package requires version {ABI_VERSION}.")
+    return library
+
+
+def get_last_error_message() -> str:
+    library = load_library()
+    size = library.db11l_get_last_error_message(None, 0)
+    buffer = ctypes.create_string_buffer(size)
+    library.db11l_get_last_error_message(buffer, size)
+    return buffer.value.decode("utf-8", "replace")
+
+
+def _declare_functions(library: ctypes.CDLL) -> None:
+    host = ctypes.c_void_p
+    int32_pointer = ctypes.POINTER(ctypes.c_int32)
+    signatures = {
+        "db11l_get_abi_version": (ctypes.c_uint32, []),
+        "db11l_get_last_error_message": (ctypes.c_int32, [ctypes.c_char_p, ctypes.c_int32]),
+        "db11l_options_init": (ctypes.c_int32, [ctypes.POINTER(NativeOptions), ctypes.c_uint32]),
+        "db11l_host_create": (ctypes.c_int32, [ctypes.c_void_p, ctypes.POINTER(NativeOptions), EventCallback, ctypes.c_void_p, ctypes.POINTER(host)]),
+        "db11l_host_destroy": (ctypes.c_int32, [host]),
+        "db11l_host_attach": (ctypes.c_int32, [host]),
+        "db11l_host_attach_when_layout_ready": (ctypes.c_int32, [host]),
+        "db11l_host_detach": (ctypes.c_int32, [host]),
+        "db11l_host_refresh_layout": (ctypes.c_int32, [host]),
+        "db11l_host_poll_event": (ctypes.c_int32, [host, ctypes.POINTER(NativeEvent)]),
+        "db11l_host_is_attached": (ctypes.c_int32, [host, int32_pointer]),
+        "db11l_host_get_taskbar_edge": (ctypes.c_int32, [host, int32_pointer]),
+        "db11l_host_get_taskbar_alignment": (ctypes.c_int32, [host, int32_pointer]),
+        "db11l_is_window_alive": (ctypes.c_int32, [ctypes.c_void_p]),
+    }
+    for name, (result_type, argument_types) in signatures.items():
+        function = getattr(library, name)
+        function.restype = result_type
+        function.argtypes = argument_types

deskband11lib/dpi.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import ctypes
+
+_PER_MONITOR_AWARE_V2 = -4
+
+
+def enable_per_monitor_dpi_awareness() -> bool:
+    """Makes the process per-monitor DPI aware, which hosted windows require.
+
+    Call this before any window is created. Qt 6 already does this. Returns False when the process DPI
+    awareness was set earlier, for example by a UI toolkit or by the manifest of the executable.
+    """
+    user32 = ctypes.WinDLL("user32", use_last_error=True)
+    user32.SetProcessDpiAwarenessContext.argtypes = [ctypes.c_void_p]
+    user32.SetProcessDpiAwarenessContext.restype = ctypes.c_int
+    return user32.SetProcessDpiAwarenessContext(ctypes.c_void_p(_PER_MONITOR_AWARE_V2)) != 0

deskband11lib/enums.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from enum import IntEnum
+from typing import TypeVar
+
+_EnumType = TypeVar("_EnumType", bound=IntEnum)
+
+
+class ResultCode(IntEnum):
+    OK = 0
+    NO_EVENT = 1
+    INVALID_ARGUMENT = -1
+    INVALID_HANDLE = -2
+    WRONG_THREAD = -3
+    INVALID_STATE = -4
+    UNSUPPORTED_DPI_AWARENESS = -5
+    WIN32_ERROR = -6
+    UNEXPECTED = -100
+
+
+class TaskbarContentPlacement(IntEnum):
+    AUTO = 0
+    LEFT_EDGE = 1
+    BEFORE_NOTIFICATION_AREA = 2
+    BEFORE_START_BUTTON = 3
+
+
+class Easing(IntEnum):
+    LINEAR = 0
+    SINE_IN = 1
+    SINE_OUT = 2
+    SINE_IN_OUT = 3
+    QUADRATIC_IN = 4
+    QUADRATIC_OUT = 5
+    QUADRATIC_IN_OUT = 6
+    CUBIC_IN = 7
+    CUBIC_OUT = 8
+    CUBIC_IN_OUT = 9
+    QUARTIC_IN = 10
+    QUARTIC_OUT = 11
+    QUARTIC_IN_OUT = 12
+    QUINTIC_IN = 13
+    QUINTIC_OUT = 14
+    QUINTIC_IN_OUT = 15
+    EXPONENTIAL_IN = 16
+    EXPONENTIAL_OUT = 17
+    EXPONENTIAL_IN_OUT = 18
+    CIRCLE_IN = 19
+    CIRCLE_OUT = 20
+    CIRCLE_IN_OUT = 21
+
+
+class TaskbarEdge(IntEnum):
+    UNKNOWN = 0
+    LEFT = 1
+    TOP = 2
+    RIGHT = 3
+    BOTTOM = 4
+
+    @property
+    def is_vertical(self) -> bool:
+        return self in (TaskbarEdge.LEFT, TaskbarEdge.RIGHT)
+
+
+class TaskbarAlignment(IntEnum):
+    UNKNOWN = 0
+    LEFT = 1
+    CENTER = 2
+
+
+class HostEventKind(IntEnum):
+    NONE = 0
+    ATTACHED = 1
+    ATTACH_FAILED = 2
+    TASKBAR_WINDOW_RECREATED = 3
+    TASKBAR_WINDOW_DISAPPEARED = 4
+    TASKBAR_DPI_CHANGED = 5
+    TASKBAR_WINDOW_RECREATION_REQUIRED = 6
+    TASKBAR_EDGE_CHANGED = 7
+    CONTENT_BOUNDS_CHANGED = 8
+    ERROR = 9
+
+
+def to_enum(enum_type: type[_EnumType], value: int, default: _EnumType | int) -> _EnumType | int:
+    """Converts a value reported by the native library, keeping values added by newer library versions usable."""
+    try:
+        return enum_type(value)
+    except ValueError:
+        return default

deskband11lib/errors.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from ._bindings import get_last_error_message
+from .enums import ResultCode, to_enum
+
+
+class Deskband11LibError(RuntimeError):
+    """Raised when the native library reports an error. result holds the ResultCode of the failure."""
+
+    def __init__(self, result: ResultCode | int, message: str) -> None:
+        super().__init__(message)
+        self.result = result
+
+
+def check_result(result: int) -> int:
+    if result < 0:
+        raise Deskband11LibError(to_enum(ResultCode, result, result), get_last_error_message() or f"The native call failed with result {result}.")
+    return result

deskband11lib/events.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+from .enums import HostEventKind, ResultCode, TaskbarEdge
+
+_logger = logging.getLogger("deskband11lib")
+_ValueType = TypeVar("_ValueType")
+
+
+@dataclass(frozen=True)
+class HostEvent:
+    """An event raised by a TaskbarContentHost.
+
+    max_width, width and height are set for CONTENT_BOUNDS_CHANGED and are in effective pixels.
+    error_message is set when result is negative, for ATTACH_FAILED and ERROR.
+    """
+
+    kind: HostEventKind | int
+    result: ResultCode | int
+    taskbar_edge: TaskbarEdge | int
+    max_width: float = 0.0
+    width: float = 0.0
+    height: float = 0.0
+    error_message: str | None = None
+
+
+class EventHook(Generic[_ValueType]):
+    """Handlers called in the order they were connected. An exception from one handler is logged and does not stop the others."""
+
+    def __init__(self) -> None:
+        self._handlers: list[Callable[[_ValueType], object]] = []
+
+    def connect(self, handler: Callable[[_ValueType], object]) -> Callable[[_ValueType], object]:
+        """Adds a handler and returns it, so connect can also be used as a decorator."""
+        self._handlers.append(handler)
+        return handler
+
+    def disconnect(self, handler: Callable[[_ValueType], object]) -> None:
+        self._handlers.remove(handler)
+
+    def emit(self, value: _ValueType) -> None:
+        for handler in list(self._handlers):
+            try:
+                handler(value)
+            except Exception:
+                _logger.exception("An event handler raised an exception.")

deskband11lib/host.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import ctypes
+import dataclasses
+import logging
+from collections.abc import Callable
+from concurrent.futures import Future
+
+from ._bindings import EventCallback, NativeEvent, get_last_error_message, load_library
+from .enums import HostEventKind, ResultCode, TaskbarAlignment, TaskbarEdge, to_enum
+from .errors import Deskband11LibError, check_result
+from .events import EventHook, HostEvent
+from .options import TaskbarContentHostOptions
+
+_logger = logging.getLogger("deskband11lib")
+
+
+class TaskbarContentHost:
+    """Places a top-level window inside the Windows 11 taskbar and keeps it aligned with the taskbar layout.
+
+    A host belongs to the thread that creates it, and that thread must run a Win32 message loop, such as the
+    main loop of Qt, Tk or wxPython. Call every method on that thread. Events are raised on the same thread
+    from the message loop, never from inside another call to the host.
+
+    The window must be per-monitor DPI aware. Create it hidden and without a frame, attach it, then show it
+    without activating it. When taskbar_window_recreation_required is raised, close the host, create the
+    window again and create a new host for it.
+
+    Events:
+        attached: attach_when_layout_ready() completed.
+        attach_failed: attach_when_layout_ready() failed. The event carries the error message.
+        taskbar_window_recreated: Explorer restarted and recreated the taskbar.
+        taskbar_window_disappeared: The taskbar the window was placed on disappeared, for example because its monitor was disconnected.
+        taskbar_dpi_changed: The system DPI changed. The window has been hidden and detached.
+        taskbar_window_recreation_required: Raised together with each of the three events above.
+        taskbar_edge_changed: The taskbar moved to another screen edge, including the first layout after attaching.
+        content_bounds_changed: The window was given a new size.
+        error: An unexpected error occurred while the host updated the layout.
+    """
+
+    def __init__(self, window_handle: int, options: TaskbarContentHostOptions | None = None) -> None:
+        self._library = load_library()
+        self._window_handle = int(window_handle)
+        self._options = options if options is not None else TaskbarContentHostOptions()
+        self._host_handle: int | None = None
+        self._pending_attaches: list[Future[None]] = []
+        self._event_callback = EventCallback(self._on_native_event)
+
+        self.attached: EventHook[HostEvent] = EventHook()
+        self.attach_failed: EventHook[HostEvent] = EventHook()
+        self.taskbar_window_recreated: EventHook[HostEvent] = EventHook()
+        self.taskbar_window_disappeared: EventHook[HostEvent] = EventHook()
+        self.taskbar_dpi_changed: EventHook[HostEvent] = EventHook()
+        self.taskbar_window_recreation_required: EventHook[HostEvent] = EventHook()
+        self.taskbar_edge_changed: EventHook[HostEvent] = EventHook()
+        self.content_bounds_changed: EventHook[HostEvent] = EventHook()
+        self.error: EventHook[HostEvent] = EventHook()
+        self._event_hooks = {
+            HostEventKind.ATTACHED: self.attached,
+            HostEventKind.ATTACH_FAILED: self.attach_failed,
+            HostEventKind.TASKBAR_WINDOW_RECREATED: self.taskbar_window_recreated,
+            HostEventKind.TASKBAR_WINDOW_DISAPPEARED: self.taskbar_window_disappeared,
+            HostEventKind.TASKBAR_DPI_CHANGED: self.taskbar_dpi_changed,
+            HostEventKind.TASKBAR_WINDOW_RECREATION_REQUIRED: self.taskbar_window_recreation_required,
+            HostEventKind.TASKBAR_EDGE_CHANGED: self.taskbar_edge_changed,
+            HostEventKind.CONTENT_BOUNDS_CHANGED: self.content_bounds_changed,
+            HostEventKind.ERROR: self.error,
+        }
+
+        native_options = self._options.to_native()
+        host_handle = ctypes.c_void_p()
+        check_result(self._library.db11l_host_create(self._window_handle, ctypes.byref(native_options), self._event_callback, None, ctypes.byref(host_handle)))
+        self._host_handle = host_handle.value
+
+    def __enter__(self) -> TaskbarContentHost:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    @property
+    def window_handle(self) -> int:
+        return self._window_handle
+
+    @property
+    def options(self) -> TaskbarContentHostOptions:
+        return dataclasses.replace(self._options)
+
+    @property
+    def is_closed(self) -> bool:
+        return self._host_handle is None
+
+    @property
+    def is_attached(self) -> bool:
+        return self._read_value(self._library.db11l_host_is_attached) != 0
+
+    @property
+    def taskbar_edge(self) -> TaskbarEdge | int:
+        """The edge the taskbar sits on. UNKNOWN until the first layout."""
+        return to_enum(TaskbarEdge, self._read_value(self._library.db11l_host_get_taskbar_edge), TaskbarEdge.UNKNOWN)
+
+    @property
+    def is_taskbar_vertical(self) -> bool:
+        return self.taskbar_edge in (TaskbarEdge.LEFT, TaskbarEdge.RIGHT)
+
+    @property
+    def taskbar_alignment(self) -> TaskbarAlignment | int:
+        return to_enum(TaskbarAlignment, self._read_value(self._library.db11l_host_get_taskbar_alignment), TaskbarAlignment.UNKNOWN)
+
+    def attach(self) -> None:
+        """Attaches the window immediately. Raises Deskband11LibError when the taskbar window cannot be found."""
+        check_result(self._library.db11l_host_attach(self._require_handle()))
+
+    def attach_when_layout_ready(self) -> Future[None]:
+        """Starts attaching once the taskbar layout can be measured and returns immediately.
+
+        The returned future completes on the host thread when attached or attach_failed is raised.
+        """
+        host_handle = self._require_handle()
+        future: Future[None] = Future()
+        self._pending_attaches.append(future)
+        try:
+            check_result(self._library.db11l_host_attach_when_layout_ready(host_handle))
+        except BaseException:
+            self._pending_attaches.remove(future)
+            raise
+        return future
+
+    def detach(self) -> None:
+        """Restores the original parent and style of the window."""
+        check_result(self._library.db11l_host_detach(self._require_handle()))
+
+    def refresh_layout(self) -> None:
+        """Recalculates the layout immediately instead of waiting for the next refresh."""
+        check_result(self._library.db11l_host_refresh_layout(self._require_handle()))
+
+    def close(self) -> None:
+        """Detaches the window when attached and releases the host. Can be called from an event handler."""
+        if self._host_handle is None:
+            return
+
+        check_result(self._library.db11l_host_destroy(self._host_handle))
+        self._host_handle = None
+        pending_attaches, self._pending_attaches = self._pending_attaches, []
+        for future in pending_attaches:
+            future.cancel()
+
+    def _require_handle(self) -> int:
+        if self._host_handle is None:
+            raise Deskband11LibError(ResultCode.INVALID_HANDLE, "The host is closed.")
+        return self._host_handle
+
+    def _read_value(self, function: Callable[..., int]) -> int:
+        value = ctypes.c_int32()
+        check_result(function(self._require_handle(), ctypes.byref(value)))
+        return value.value
+
+    def _on_native_event(self, _user_data: object, native_event_pointer: ctypes._Pointer[NativeEvent]) -> None:
+        # The native caller cannot receive Python exceptions, so failures are logged here.
+        try:
+            self._dispatch_event(self._create_event(native_event_pointer.contents))
+        except Exception:
+            _logger.exception("Failed to dispatch a taskbar host event.")
+
+    @staticmethod
+    def _create_event(native_event: NativeEvent) -> HostEvent:
+        return HostEvent(
+            kind=to_enum(HostEventKind, native_event.kind, native_event.kind),
+            result=to_enum(ResultCode, native_event.result, native_event.result),
+            taskbar_edge=to_enum(TaskbarEdge, native_event.taskbar_edge, TaskbarEdge.UNKNOWN),
+            max_width=native_event.max_width,
+            width=native_event.width,
+            height=native_event.height,
+            error_message=get_last_error_message() if native_event.result < 0 else None,
+        )
+
+    def _dispatch_event(self, event: HostEvent) -> None:
+        event_hook = self._event_hooks.get(event.kind)
+        if event_hook is not None:
+            event_hook.emit(event)
+
+        if event.kind not in (HostEventKind.ATTACHED, HostEventKind.ATTACH_FAILED):
+            return
+
+        pending_attaches, self._pending_attaches = self._pending_attaches, []
+        for future in pending_attaches:
+            if future.done():
+                continue
+            if event.kind == HostEventKind.ATTACHED:
+                future.set_result(None)
+            else:
+                future.set_exception(Deskband11LibError(event.result, event.error_message or "Attaching to the taskbar failed."))
+
+
+def is_window_alive(window_handle: int) -> bool:
+    """Returns whether window_handle still refers to an existing window, for example after Explorer restarted."""
+    return load_library().db11l_is_window_alive(int(window_handle)) != 0

deskband11lib/options.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import ctypes
+import sys
+from dataclasses import dataclass
+
+from ._bindings import NativeOptions, load_library
+from .enums import Easing, TaskbarContentPlacement
+from .errors import check_result
+
+STRETCH = sys.float_info.max
+"""A preferred_width that fills the space left after fixed-width hosts are served."""
+
+
+@dataclass
+class TaskbarContentHostOptions:
+    """Options for a TaskbarContentHost. Sizes are in effective pixels and durations in milliseconds.
+
+    preferred_width is the length along the taskbar and preferred_height the size across it, so on a left or
+    right taskbar they map to the height and the width of the window.
+    """
+
+    preferred_width: float = 360.0
+    """Length along the taskbar. Use STRETCH to fill the space left by fixed-width hosts."""
+
+    preferred_height: float = 48.0
+    """Size across the taskbar, capped by its thickness."""
+
+    placement: TaskbarContentPlacement = TaskbarContentPlacement.AUTO
+    preferred_monitor_identity: int = 0
+    """0 is the primary taskbar. 1 and above are secondary taskbars ordered from left to right."""
+
+    manual_slot_priority: int = 65535
+    """0 to 65535. Lower values are placed first when several hosts share an area. 65535 orders by arrival."""
+
+    allow_fixed_slot_resize: bool = True
+    """Lets fixed-width hosts shrink proportionally when the available space runs out."""
+
+    animate_layout_changes: bool = True
+    high_refresh_rate_mode: bool = True
+    """Matches the animation frame interval to the refresh rate of the monitor."""
+
+    layout_animation_duration: float = 500.0
+    layout_animation_easing: Easing = Easing.CIRCLE_OUT
+    track_taskbar_buttons: bool = True
+    """Measures the taskbar buttons through UI Automation so the window never covers them."""
+
+    track_notification_area: bool = True
+    layout_refresh_interval: float = 500.0
+
+    def to_native(self) -> NativeOptions:
+        if not 0 <= self.manual_slot_priority <= 65535:
+            raise ValueError("manual_slot_priority must be between 0 and 65535.")
+
+        native_options = NativeOptions()
+        check_result(load_library().db11l_options_init(ctypes.byref(native_options), ctypes.sizeof(NativeOptions)))
+        native_options.preferred_width = self.preferred_width
+        native_options.preferred_height = self.preferred_height
+        native_options.placement = int(self.placement)
+        native_options.preferred_monitor_identity = self.preferred_monitor_identity
+        native_options.manual_slot_priority = self.manual_slot_priority
+        native_options.allow_fixed_slot_resize = int(self.allow_fixed_slot_resize)
+        native_options.animate_layout_changes = int(self.animate_layout_changes)
+        native_options.high_refresh_rate_mode = int(self.high_refresh_rate_mode)
+        native_options.layout_animation_duration = self.layout_animation_duration
+        native_options.layout_animation_easing = int(self.layout_animation_easing)
+        native_options.track_taskbar_buttons = int(self.track_taskbar_buttons)
+        native_options.track_notification_area = int(self.track_notification_area)
+        native_options.layout_refresh_interval = self.layout_refresh_interval
+        return native_options

deskband11lib/qt.py

@@ -0,0 +1,151 @@
+"""Hosts PySide6 or PyQt6 widgets in the Windows 11 taskbar."""
+
+from __future__ import annotations
+
+import importlib
+from collections.abc import Callable
+from types import ModuleType
+from typing import Any
+
+from .events import EventHook, HostEvent
+from .host import TaskbarContentHost
+from .options import TaskbarContentHostOptions
+
+_QT_BINDINGS = ("PySide6", "PyQt6")
+
+
+def prepare_widget(widget: Any) -> int:
+    """Turns a top-level widget into a frameless tool window and returns its native window handle.
+
+    The taskbar layout decides the size of the widget, so the minimum size of the widget and of its layout is
+    cleared; otherwise Qt would resize the window back whenever the taskbar gives it less room.
+
+    Call this before the widget is shown. Qt creates a new native window when window flags change, so the
+    flags must not change after the widget is attached.
+    """
+    qt = _import_qt_module(widget, "QtCore").Qt
+    widget.setWindowFlags(widget.windowFlags() | qt.WindowType.FramelessWindowHint | qt.WindowType.Tool)
+    widget.setAttribute(qt.WidgetAttribute.WA_ShowWithoutActivating, True)
+    layout = widget.layout()
+    if layout is not None:
+        layout.setSizeConstraint(_import_qt_module(widget, "QtWidgets").QLayout.SizeConstraint.SetNoConstraint)
+    widget.setMinimumSize(0, 0)
+    return int(widget.winId())
+
+
+class QtTaskbarWidgetController:
+    """Creates a widget, hosts it in the taskbar, and creates it again whenever the taskbar requires it.
+
+    The taskbar destroys the hosted window when Explorer restarts or when the monitor it sits on is
+    disconnected, and the window is detached when the system DPI changes. In each case the controller
+    releases the host, waits recreation_delay milliseconds for the taskbar to settle, then creates a new
+    widget and host. The widget is shown once it is attached.
+
+    start() turns off QGuiApplication.quitOnLastWindowClosed, because the widget is closed and created again
+    while the taskbar recovers. Call start() and stop() on the Qt GUI thread.
+    """
+
+    def __init__(self, create_widget: Callable[[], Any], options: TaskbarContentHostOptions | None = None, recreation_delay: int = 1000) -> None:
+        self._create_widget = create_widget
+        self._options = options
+        self._recreation_delay = recreation_delay
+        self._widget: Any = None
+        self._host: TaskbarContentHost | None = None
+        self._content_size: tuple[int, int] | None = None
+        self._is_running = False
+
+        self.widget_created: EventHook[Any] = EventHook()
+        self.attached: EventHook[HostEvent] = EventHook()
+        self.attach_failed: EventHook[HostEvent] = EventHook()
+        self.taskbar_edge_changed: EventHook[HostEvent] = EventHook()
+        self.error: EventHook[HostEvent] = EventHook()
+
+    @property
+    def widget(self) -> Any:
+        """The current widget, or None while it is being created again."""
+        return self._widget
+
+    @property
+    def host(self) -> TaskbarContentHost | None:
+        return self._host
+
+    def start(self) -> None:
+        if self._is_running:
+            return
+
+        self._is_running = True
+        self._create()
+
+    def stop(self) -> None:
+        self._is_running = False
+        _dispose_widget(self._release())
+
+    def _create(self) -> None:
+        widget = self._create_widget()
+        try:
+            _import_qt_module(widget, "QtGui").QGuiApplication.setQuitOnLastWindowClosed(False)
+            host = TaskbarContentHost(prepare_widget(widget), self._options)
+        except BaseException:
+            _dispose_widget(widget)
+            raise
+
+        self._content_size = None
+        host.content_bounds_changed.connect(self._on_host_content_bounds_changed)
+        host.attached.connect(self._on_host_attached)
+        host.attach_failed.connect(self.attach_failed.emit)
+        host.taskbar_edge_changed.connect(self.taskbar_edge_changed.emit)
+        host.error.connect(self.error.emit)
+        host.taskbar_window_recreation_required.connect(self._on_host_taskbar_window_recreation_required)
+        self._widget = widget
+        self._host = host
+        self.widget_created.emit(widget)
+        host.attach_when_layout_ready()
+
+    def _release(self) -> Any:
+        host, widget = self._host, self._widget
+        self._host = None
+        self._widget = None
+        # Hiding first keeps the detached window from appearing as a top-level window before it is closed.
+        if widget is not None:
+            widget.hide()
+        if host is not None:
+            host.close()
+        return widget
+
+    def _on_host_content_bounds_changed(self, event: HostEvent) -> None:
+        self._content_size = (round(event.width), round(event.height))
+
+    def _on_host_attached(self, event: HostEvent) -> None:
+        widget = self._widget
+        if widget is not None:
+            # Qt fits a top-level widget that was never resized to its size hint when it is first shown, which would undo the size the taskbar layout applied.
+            if self._content_size is not None:
+                widget.resize(*self._content_size)
+            widget.show()
+        self.attached.emit(event)
+
+    def _on_host_taskbar_window_recreation_required(self, _event: HostEvent) -> None:
+        previous_widget = self._release()
+        timer = _import_qt_module(previous_widget, "QtCore").QTimer
+        timer.singleShot(self._recreation_delay, lambda: self._recreate(previous_widget))
+
+    def _recreate(self, previous_widget: Any) -> None:
+        if self._is_running and self._host is None:
+            self._create()
+        _dispose_widget(previous_widget)
+
+
+def _dispose_widget(widget: Any) -> None:
+    if widget is None:
+        return
+
+    widget.close()
+    widget.deleteLater()
+
+
+def _import_qt_module(widget: Any, module_name: str) -> ModuleType:
+    for widget_type in type(widget).__mro__:
+        binding = widget_type.__module__.split(".", 1)[0]
+        if binding in _QT_BINDINGS:
+            return importlib.import_module(f"{binding}.{module_name}")
+    raise TypeError("The widget must be a PySide6 or PyQt6 QWidget.")

deskband11lib-1.5.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: deskband11lib
+Version: 1.5.0
+Summary: Host Python UI windows inside the Windows 11 taskbar.
+Project-URL: Homepage, https://db11l.kagamine-rin.com
+Project-URL: Documentation, https://github.com/airtaxi/Deskband11Lib/blob/master/README.md
+Project-URL: Repository, https://github.com/airtaxi/Deskband11Lib
+Project-URL: Issues, https://github.com/airtaxi/Deskband11Lib/issues
+Author: airtaxi
+License-Expression: MIT
+Keywords: deskband,pyqt6,pyside6,taskbar,widget,windows11
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Desktop Environment
+Requires-Python: >=3.10
+Provides-Extra: pyqt6
+Requires-Dist: pyqt6>=6.5; extra == 'pyqt6'
+Provides-Extra: pyside6
+Requires-Dist: pyside6>=6.5; extra == 'pyside6'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# deskband11lib for Python
+
+[![PyPI](https://img.shields.io/pypi/v/deskband11lib.svg)](https://pypi.org/project/deskband11lib/)
+[![Build and Publish Python Package](https://github.com/airtaxi/Deskband11Lib/actions/workflows/python-package.yml/badge.svg)](https://github.com/airtaxi/Deskband11Lib/actions/workflows/python-package.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/airtaxi/Deskband11Lib/blob/master/LICENSE)
+
+deskband11lib places a Python window inside the Windows 11 taskbar. It finds the free space between the taskbar buttons and the notification area, moves the window there, and keeps it aligned when the taskbar layout changes, when the taskbar moves to another screen edge, and when other hosted windows share the same area.
+
+The package wraps the Deskband11Lib native library through ctypes, so it works with any toolkit that can give you a window handle. A ready-made controller is included for PySide6 and PyQt6.
+
+For how the library measures the taskbar, shares space between several hosted windows, and handles each taskbar position, see the [Deskband11Lib README](https://github.com/airtaxi/Deskband11Lib/blob/master/README.md). Deskband11Lib is also available for WinUI 3 and WPF as NuGet packages.
+
+## Requirements
+
+- Windows 11
+- Python 3.10 or later, x64 or ARM64
+- A per-monitor DPI aware window. Qt 6 is per-monitor DPI aware by default. For Tk and other toolkits, call `deskband11lib.enable_per_monitor_dpi_awareness()` before any window is created.
+
+## Install
+
+```powershell
+pip install deskband11lib
+
+# With PySide6
+pip install "deskband11lib[pyside6]"
+```
+
+## Qt
+
+`QtTaskbarWidgetController` creates your widget, removes its frame, attaches it to the taskbar, and shows it once it is in place.
+
+```python
+import sys
+
+from PySide6.QtWidgets import QApplication, QLabel
+
+from deskband11lib import TaskbarContentHostOptions
+from deskband11lib.qt import QtTaskbarWidgetController
+
+application = QApplication(sys.argv)
+controller = QtTaskbarWidgetController(lambda: QLabel("Hello"), TaskbarContentHostOptions(preferred_width=120))
+controller.start()
+sys.exit(application.exec())
+```
+
+The taskbar destroys hosted windows when Explorer restarts or when the monitor they sit on is disconnected, and hosted windows are detached when the system DPI changes. The controller handles all three cases by closing the old widget and calling your factory again, so keep the widget state you want to preserve outside the widget. Because the widget is closed and created again, `start()` turns off `quitOnLastWindowClosed`; give users another way to exit, such as a context menu.
+
+Connect to the controller hooks to react to the taskbar:
+
+```python
+@controller.taskbar_edge_changed.connect
+def on_taskbar_edge_changed(event):
+    controller.widget.apply_taskbar_orientation(event.taskbar_edge.is_vertical)
+```
+
+[`samples/pyside6_clock.py`](https://github.com/airtaxi/Deskband11Lib/blob/master/bindings/python/samples/pyside6_clock.py) shows a complete widget that follows the taskbar theme and switches its layout for vertical and thin taskbars.
+
+## Any window
+
+`TaskbarContentHost` takes a window handle (HWND) from any toolkit.
+
+```python
+from deskband11lib import TaskbarContentHost, TaskbarContentHostOptions
+
+host = TaskbarContentHost(window_handle, TaskbarContentHostOptions(preferred_width=200))
+host.taskbar_window_recreation_required.connect(on_recreation_required)
+host.attach_when_layout_ready().add_done_callback(lambda future: show_window_without_activation())
+```
+
+Follow these rules when you host a window yourself:
+
+- Create the host on the UI thread and call every method on that thread. The thread must run a Win32 message loop; the main loop of Qt, Tk, or wxPython does.
+- Create the window hidden and without a frame. Show it without activating it after the host attaches.
+- Leave the size and position of the window to the host while it is attached. The host applies them only when the taskbar layout changes, so a size set by the toolkit stays until the next layout change. Toolkits that fit a window to its content when it is first shown need the window resized to the size from the latest `content_bounds_changed` event before it is shown.
+- When `taskbar_window_recreation_required` is raised, close the host, create the window again, and create a new host for it.
+- Call `close()` when you no longer need the host. It restores the original parent and style of the window.
+
+## Events
+
+Each host exposes these hooks. Handlers receive a `HostEvent` and run on the UI thread from the message loop.
+
+| Hook | Raised when |
+| --- | --- |
+| `attached` | `attach_when_layout_ready()` completed. |
+| `attach_failed` | `attach_when_layout_ready()` failed. `error_message` describes why. |
+| `taskbar_window_recreated` | Explorer restarted and created the taskbar again. |
+| `taskbar_window_disappeared` | The taskbar the window sat on disappeared, for example because its monitor was disconnected. |
+| `taskbar_dpi_changed` | The system DPI changed. The window has been hidden and detached. |
+| `taskbar_window_recreation_required` | Raised together with each of the three events above. One handler covers all of them. |
+| `taskbar_edge_changed` | The taskbar moved to another screen edge, including the first layout after attaching. |
+| `content_bounds_changed` | The window received a new size, in effective pixels. |
+| `error` | An unexpected error occurred while the layout was updated. |
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `preferred_width` | `360` | Length along the taskbar in effective pixels: the width on a bottom or top taskbar, the height on a left or right taskbar. `STRETCH` fills the space left by fixed-width hosts. |
+| `preferred_height` | `48` | Size across the taskbar, capped by its thickness. |
+| `placement` | `AUTO` | `AUTO`, `LEFT_EDGE`, `BEFORE_NOTIFICATION_AREA`, or `BEFORE_START_BUTTON`. |
+| `preferred_monitor_identity` | `0` | `0` is the primary taskbar. `1` and above are secondary taskbars ordered from left to right. |
+| `manual_slot_priority` | `65535` | Order among hosts that share an area. Lower values are placed first. `65535` orders by arrival. |
+| `allow_fixed_slot_resize` | `True` | Lets fixed-width hosts shrink proportionally when space runs out. |
+| `animate_layout_changes` | `True` | Animates position and size changes. |
+| `high_refresh_rate_mode` | `True` | Matches the animation frame interval to the monitor refresh rate. |
+| `layout_animation_duration` | `500` | Animation duration in milliseconds. |
+| `layout_animation_easing` | `CIRCLE_OUT` | One of the `Easing` values. |
+| `track_taskbar_buttons` | `True` | Measures the taskbar buttons through UI Automation so the window never covers them. |
+| `track_notification_area` | `True` | Keeps the window away from the notification area. |
+| `layout_refresh_interval` | `500` | Milliseconds between layout refreshes. |
+
+Invalid values raise `Deskband11LibError` with `result` set to `ResultCode.INVALID_ARGUMENT` and a message that names the option.
+
+## Building from source
+
+Clone the [repository](https://github.com/airtaxi/Deskband11Lib). Building the native library requires the .NET 10 SDK and the Visual Studio C++ build tools.
+
+```powershell
+cd bindings/python
+
+# Publish the native library for the running interpreter and stage it in the package
+python scripts/stage_native.py
+
+# Or stage several architectures to build one wheel that covers all of them
+python scripts/stage_native.py win-x64 win-arm64
+
+python -m build --wheel
+```
+
+Set `DESKBAND11LIB_LIBRARY_PATH` to load the native library from another location.
+
+## Tests
+
+```powershell
+pip install -e ".[test,pyside6]"
+pytest
+```
+
+Tests that attach windows to the taskbar of the current session are skipped unless `DESKBAND11LIB_TASKBAR_TESTS` is set to `1`. The Qt tests use PySide6; set `DESKBAND11LIB_QT_BINDING` to `PyQt6` to run them with PyQt6 instead.
+
+## License
+
+MIT

deskband11lib-1.5.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+deskband11lib/__init__.py,sha256=ntAN5QEC3Vw92HtGoExXeVSgPgMyO2szLi2m6BAgkaU,947
+deskband11lib/_bindings.py,sha256=LhSoI01DEONgqhVU8-KkDZl_mc87AXDbbP8S1irZoH0,4348
+deskband11lib/dpi.py,sha256=Sv3ZRQfx1SV7yCvLeWiJz1TOqKvqihqIIvD-3JVPuQ4,717
+deskband11lib/enums.py,sha256=wFhEhVaTm4JN4OJwZa4iOtpkvOZKLFWOmC3p-S2uuV4,1964
+deskband11lib/errors.py,sha256=sNTzpYwnKpsO6CY53IieuUn1UKgEiWWiKG8svfZamZ0,644
+deskband11lib/events.py,sha256=vM51Joe8W9sSTK-akrKv2ET4EvxlSMA31ZaG-DOlIJM,1710
+deskband11lib/host.py,sha256=C3Y9PSlf5zlmVHT-IpeEHvlBqYSLM2Z5Th3fVH0KYcg,9462
+deskband11lib/options.py,sha256=H2_aDyMSLtmT4PJgFHULvdv4VcPuICuAlD-UfzD8CCs,3310
+deskband11lib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+deskband11lib/qt.py,sha256=HeAkW3T7ZbcCe7Azmott36YjUsWLhhkIKNH4E09BYWY,6264
+deskband11lib/bin/win-x64/deskband11lib.dll,sha256=z-aQMEY9X0jf7pRDeqjobNS9NSG4oVFxap_76S5CHlY,2392064
+deskband11lib-1.5.0.dist-info/METADATA,sha256=qou1VsiamrB8qTfKcygnF1Q8V6MhGSO98omI--lCD0s,9008
+deskband11lib-1.5.0.dist-info/WHEEL,sha256=lpoBGaIUIidvvdZ4qRAP61bBKYJdt4FI3WXFL50Gzyo,94
+deskband11lib-1.5.0.dist-info/RECORD,,

deskband11lib-1.5.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64