ascript 1.3.27__py3-none-win_amd64.whl

ascript/windows/window/Window.py

@@ -0,0 +1,747 @@
+"""Native Windows window discovery, control, input and capture helpers."""
+
+from __future__ import annotations
+
+import ctypes
+import math
+import os
+import re
+import time
+from ctypes import wintypes
+from enum import Enum, auto
+from typing import List, NamedTuple, Optional, Sequence, Union
+
+import psutil
+import win32con
+import win32gui
+import win32process
+import win32ui
+from PIL import Image, ImageGrab
+from ..hardware import Mouse
+
+
+_USER32 = ctypes.windll.user32
+
+
+def _enable_dpi_awareness() -> None:
+    try:
+        setter = _USER32.SetProcessDpiAwarenessContext
+        setter.argtypes = (ctypes.c_void_p,)
+        setter.restype = wintypes.BOOL
+        setter(ctypes.c_void_p(-4))
+        return
+    except (AttributeError, OSError):
+        pass
+    try:
+        ctypes.windll.shcore.SetProcessDpiAwareness(2)
+    except (AttributeError, OSError):
+        try:
+            _USER32.SetProcessDPIAware()
+        except (AttributeError, OSError):
+            pass
+
+
+_enable_dpi_awareness()
+
+_IS_HUNG_APP_WINDOW = getattr(_USER32, "IsHungAppWindow", None)
+if _IS_HUNG_APP_WINDOW is not None:
+    _IS_HUNG_APP_WINDOW.argtypes = (wintypes.HWND,)
+    _IS_HUNG_APP_WINDOW.restype = wintypes.BOOL
+
+_DWM_GET_WINDOW_ATTRIBUTE = None
+try:
+    _DWM_GET_WINDOW_ATTRIBUTE = ctypes.windll.dwmapi.DwmGetWindowAttribute
+    _DWM_GET_WINDOW_ATTRIBUTE.argtypes = (
+        wintypes.HWND, wintypes.DWORD, ctypes.c_void_p, wintypes.DWORD
+    )
+    _DWM_GET_WINDOW_ATTRIBUTE.restype = ctypes.c_long
+except (AttributeError, OSError):
+    pass
+
+_DWMWA_EXTENDED_FRAME_BOUNDS = 9
+_PW_CLIENTONLY = 0x1
+_PW_RENDERFULLCONTENT = 0x2
+
+
+class _GUITHREADINFO(ctypes.Structure):
+    _fields_ = [
+        ("cbSize", wintypes.DWORD),
+        ("flags", wintypes.DWORD),
+        ("hwndActive", wintypes.HWND),
+        ("hwndFocus", wintypes.HWND),
+        ("hwndCapture", wintypes.HWND),
+        ("hwndMenuOwner", wintypes.HWND),
+        ("hwndMoveSize", wintypes.HWND),
+        ("hwndCaret", wintypes.HWND),
+        ("rcCaret", wintypes.RECT),
+    ]
+
+
+class WindowRect(NamedTuple):
+    """A rectangle in physical screen coordinates."""
+
+    left: int
+    top: int
+    right: int
+    bottom: int
+    width: int
+    height: int
+
+    @classmethod
+    def from_ltrb(cls, left: int, top: int, right: int, bottom: int) -> "WindowRect":
+        return cls(left, top, right, bottom, right - left, bottom - top)
+
+
+class WindowCaptureFormat(Enum):
+    PIL = auto()
+    NUMPY = auto()
+    OPENCV = auto()
+
+    def convert(self, pil_image: Image.Image):
+        if self is WindowCaptureFormat.PIL:
+            return pil_image
+        import numpy as np
+
+        array = np.asarray(pil_image)
+        if self is WindowCaptureFormat.NUMPY:
+            return array
+        if self is WindowCaptureFormat.OPENCV:
+            return array[:, :, ::-1].copy()
+        raise ValueError(f"Unsupported capture format: {self!r}")
+
+
+class Window:
+    """A lightweight wrapper around a top-level Windows HWND."""
+
+    def __init__(self, hwnd: int):
+        if not isinstance(hwnd, int) or isinstance(hwnd, bool):
+            raise TypeError("hwnd must be an integer")
+        self.hwnd = hwnd
+        self._pid: Optional[int] = None
+
+    def __repr__(self) -> str:
+        try:
+            return f"<Window title={self.title!r} process={self.process_name!r} hwnd={self.hwnd}>"
+        except (OSError, win32gui.error):
+            return f"<Window hwnd={self.hwnd} invalid>"
+
+    def __bool__(self) -> bool:
+        return self.is_valid
+
+    def __eq__(self, other) -> bool:
+        return isinstance(other, Window) and self.hwnd == other.hwnd
+
+    def __hash__(self) -> int:
+        return hash(self.hwnd)
+
+    @staticmethod
+    def _compile_title_pattern(title_re: Optional[str]):
+        if title_re is None:
+            return None
+        if not isinstance(title_re, str):
+            raise TypeError("title_re must be a string or None")
+        try:
+            return re.compile(title_re)
+        except re.error as exc:
+            raise ValueError(f"invalid title regular expression: {exc}") from exc
+
+    @classmethod
+    def active(cls) -> Optional["Window"]:
+        hwnd = win32gui.GetForegroundWindow()
+        return cls(hwnd) if hwnd else None
+
+    @staticmethod
+    def screen_size() -> tuple[int, int]:
+        """Return the virtual desktop size, including secondary monitors."""
+        return (
+            int(_USER32.GetSystemMetrics(78)),
+            int(_USER32.GetSystemMetrics(79)),
+        )
+
+    @classmethod
+    def find_all(
+        cls,
+        title_re: Optional[str] = None,
+        process_name: Optional[str] = None,
+        class_name: Optional[str] = None,
+        visible_only: bool = True,
+    ) -> List["Window"]:
+        pattern = cls._compile_title_pattern(title_re)
+        process_filter = process_name.casefold() if process_name else None
+        results: List[Window] = []
+
+        def callback(hwnd, _):
+            try:
+                if visible_only and not win32gui.IsWindowVisible(hwnd):
+                    return True
+                candidate = cls(hwnd)
+                if class_name is not None and candidate.class_name != class_name:
+                    return True
+                if process_filter is not None and process_filter not in candidate.process_name.casefold():
+                    return True
+                if pattern is not None and pattern.search(candidate.title) is None:
+                    return True
+                results.append(candidate)
+            except (OSError, psutil.Error, win32gui.error):
+                pass
+            return True
+
+        win32gui.EnumWindows(callback, None)
+        return results
+
+    @classmethod
+    def find(
+        cls,
+        title_re: Optional[str] = None,
+        process_name: Optional[str] = None,
+        class_name: Optional[str] = None,
+        visible_only: bool = True,
+        timeout: float = 0,
+    ) -> Optional["Window"]:
+        if isinstance(timeout, bool) or not isinstance(timeout, (int, float)):
+            raise TypeError("timeout must be a number")
+        timeout = float(timeout)
+        if timeout < 0 or not math.isfinite(timeout):
+            raise ValueError("timeout must be finite and non-negative")
+        deadline = time.monotonic() + timeout
+        while True:
+            matches = cls.find_all(title_re, process_name, class_name, visible_only)
+            if matches:
+                return matches[0]
+            remaining = deadline - time.monotonic()
+            if timeout == 0 or remaining <= 0:
+                return None
+            time.sleep(min(0.2, remaining))
+
+    def find_children(
+        self,
+        title_re: Optional[str] = None,
+        class_name: Optional[str] = None,
+        visible_only: bool = True,
+    ) -> List["Window"]:
+        """Return descendant windows matching stable window attributes."""
+        if not self.is_valid:
+            return []
+        pattern = self._compile_title_pattern(title_re)
+        results: List[Window] = []
+
+        def callback(hwnd, _):
+            try:
+                if visible_only and not win32gui.IsWindowVisible(hwnd):
+                    return True
+                candidate = Window(int(hwnd))
+                if class_name is not None and candidate.class_name != class_name:
+                    return True
+                if pattern is not None and pattern.search(candidate.title) is None:
+                    return True
+                results.append(candidate)
+            except (OSError, psutil.Error, win32gui.error):
+                pass
+            return True
+
+        win32gui.EnumChildWindows(self.hwnd, callback, None)
+        return results
+
+    def find_child(
+        self,
+        title_re: Optional[str] = None,
+        class_name: Optional[str] = None,
+        visible_only: bool = True,
+        timeout: float = 0,
+    ) -> Optional["Window"]:
+        """Find the first matching descendant, optionally waiting for it."""
+        if isinstance(timeout, bool) or not isinstance(timeout, (int, float)):
+            raise TypeError("timeout must be a number")
+        timeout = float(timeout)
+        if timeout < 0 or not math.isfinite(timeout):
+            raise ValueError("timeout must be finite and non-negative")
+        deadline = time.monotonic() + timeout
+        while True:
+            matches = self.find_children(title_re, class_name, visible_only)
+            if matches:
+                return matches[0]
+            remaining = deadline - time.monotonic()
+            if timeout == 0 or remaining <= 0:
+                return None
+            time.sleep(min(0.2, remaining))
+
+    @classmethod
+    def launch(
+        cls,
+        name: Optional[str] = None,
+        path: Optional[str] = None,
+        allow_multiple: bool = False,
+        timeout: float = 15,
+    ) -> Optional["Window"]:
+        from .launcher import Launcher
+
+        if not name and not path:
+            raise ValueError("name or path is required")
+        if isinstance(timeout, bool) or not isinstance(timeout, (int, float)):
+            raise TypeError("timeout must be a number")
+        timeout = float(timeout)
+        if timeout < 0 or not math.isfinite(timeout):
+            raise ValueError("timeout must be finite and non-negative")
+
+        resolved_path, process_name = Launcher.get_info(name=name, path=path)
+        launch_target = resolved_path or path
+        if not process_name and launch_target:
+            process_name = os.path.basename(launch_target)
+        title_filter = name if name and not process_name else None
+        existing = cls.find_all(
+            title_re=title_filter, process_name=process_name, visible_only=False
+        )
+        if existing and not allow_multiple:
+            existing[0].activate()
+            return existing[0]
+
+        if not Launcher.run(name=name, path=launch_target):
+            return None
+
+        old_handles = {window.hwnd for window in existing}
+        deadline = time.monotonic() + timeout
+        while True:
+            current = cls.find_all(
+                title_re=title_filter, process_name=process_name, visible_only=False
+            )
+            candidates = (
+                [window for window in current if window.hwnd not in old_handles]
+                if allow_multiple else current
+            )
+            if candidates:
+                candidates[0].activate()
+                return candidates[0]
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return existing[0] if existing else None
+            time.sleep(min(0.2, remaining))
+
+    @property
+    def is_valid(self) -> bool:
+        return bool(win32gui.IsWindow(self.hwnd))
+
+    @property
+    def title(self) -> str:
+        return win32gui.GetWindowText(self.hwnd)
+
+    @property
+    def class_name(self) -> str:
+        return win32gui.GetClassName(self.hwnd)
+
+    @property
+    def pid(self) -> int:
+        if self._pid is None:
+            _, self._pid = win32process.GetWindowThreadProcessId(self.hwnd)
+        return self._pid
+
+    @property
+    def process_path(self) -> str:
+        try:
+            return psutil.Process(self.pid).exe()
+        except (psutil.Error, OSError):
+            return "Unknown"
+
+    @property
+    def process_name(self) -> str:
+        try:
+            return psutil.Process(self.pid).name()
+        except (psutil.Error, OSError):
+            return "Unknown"
+
+    @property
+    def is_visible(self) -> bool:
+        if not self.is_valid or not win32gui.IsWindowVisible(self.hwnd):
+            return False
+        left, top, right, bottom = win32gui.GetWindowRect(self.hwnd)
+        return right > left and bottom > top and left > -30000 and top > -30000
+
+    @property
+    def is_minimized(self) -> bool:
+        return bool(win32gui.IsIconic(self.hwnd))
+
+    @property
+    def is_maximized(self) -> bool:
+        return bool(win32gui.IsZoomed(self.hwnd))
+
+    @property
+    def is_responding(self) -> bool:
+        if not self.is_valid:
+            return False
+        if _IS_HUNG_APP_WINDOW is not None:
+            return not bool(_IS_HUNG_APP_WINDOW(self.hwnd))
+        return self._check_responding_via_timeout()
+
+    def _check_responding_via_timeout(self) -> bool:
+        try:
+            win32gui.SendMessageTimeout(
+                self.hwnd, win32con.WM_NULL, 0, 0,
+                win32con.SMTO_ABORTIFHUNG | win32con.SMTO_BLOCK, 100,
+            )
+            return True
+        except win32gui.error:
+            return False
+
+    @property
+    def is_always_on_top(self) -> bool:
+        style = win32gui.GetWindowLong(self.hwnd, win32con.GWL_EXSTYLE)
+        return bool(style & win32con.WS_EX_TOPMOST)
+
+    @property
+    def rect(self) -> WindowRect:
+        native = win32gui.GetWindowRect(self.hwnd)
+        if _DWM_GET_WINDOW_ATTRIBUTE is not None:
+            visual = wintypes.RECT()
+            result = _DWM_GET_WINDOW_ATTRIBUTE(
+                self.hwnd, _DWMWA_EXTENDED_FRAME_BOUNDS,
+                ctypes.byref(visual), ctypes.sizeof(visual),
+            )
+            if result == 0 and visual.right > visual.left and visual.bottom > visual.top:
+                return WindowRect.from_ltrb(
+                    visual.left, visual.top, visual.right, visual.bottom
+                )
+        return WindowRect.from_ltrb(*native)
+
+    @property
+    def client_rect(self) -> WindowRect:
+        left, top, right, bottom = win32gui.GetClientRect(self.hwnd)
+        screen_left, screen_top = win32gui.ClientToScreen(self.hwnd, (left, top))
+        return WindowRect.from_ltrb(
+            screen_left, screen_top,
+            screen_left + right - left, screen_top + bottom - top,
+        )
+
+    def set_rect(
+        self, x: Optional[int] = None, y: Optional[int] = None,
+        width: Optional[int] = None, height: Optional[int] = None,
+    ):
+        for value, label in ((x, "x"), (y, "y"), (width, "width"), (height, "height")):
+            if value is not None and (not isinstance(value, int) or isinstance(value, bool)):
+                raise TypeError(f"{label} must be an integer or None")
+        if (width is not None and width <= 0) or (height is not None and height <= 0):
+            raise ValueError("width and height must be greater than zero")
+
+        visual = self.rect
+        native_left, native_top, native_right, native_bottom = win32gui.GetWindowRect(self.hwnd)
+        left_inset = visual.left - native_left
+        top_inset = visual.top - native_top
+        horizontal_insets = (visual.left - native_left) + (native_right - visual.right)
+        vertical_insets = (visual.top - native_top) + (native_bottom - visual.bottom)
+        desired_x = visual.left if x is None else x
+        desired_y = visual.top if y is None else y
+        desired_width = visual.width if width is None else width
+        desired_height = visual.height if height is None else height
+        win32gui.SetWindowPos(
+            self.hwnd, 0, desired_x - left_inset, desired_y - top_inset,
+            desired_width + horizontal_insets, desired_height + vertical_insets,
+            win32con.SWP_NOZORDER | win32con.SWP_NOACTIVATE,
+        )
+        return self
+
+    def move(self, x: int, y: int):
+        return self.set_rect(x=x, y=y)
+
+    def resize(self, width: int, height: int):
+        return self.set_rect(width=width, height=height)
+
+    def activate(self) -> bool:
+        if not self.is_valid:
+            return False
+        win32gui.ShowWindow(self.hwnd, win32con.SW_RESTORE if self.is_minimized else win32con.SW_SHOW)
+        try:
+            win32gui.SetForegroundWindow(self.hwnd)
+        except win32gui.error:
+            foreground = win32gui.GetForegroundWindow()
+            current_thread = _USER32.GetCurrentThreadId()
+            target_thread, _ = win32process.GetWindowThreadProcessId(self.hwnd)
+            foreground_thread = win32process.GetWindowThreadProcessId(foreground)[0] if foreground else 0
+            attached = []
+            try:
+                for thread_id in {target_thread, foreground_thread}:
+                    if thread_id and thread_id != current_thread and _USER32.AttachThreadInput(current_thread, thread_id, True):
+                        attached.append(thread_id)
+                win32gui.BringWindowToTop(self.hwnd)
+                win32gui.SetForegroundWindow(self.hwnd)
+            except win32gui.error:
+                return False
+            finally:
+                for thread_id in reversed(attached):
+                    _USER32.AttachThreadInput(current_thread, thread_id, False)
+        return win32gui.GetForegroundWindow() == self.hwnd
+
+    def set_always_on_top(self, toggle: bool = True):
+        z_order = win32con.HWND_TOPMOST if bool(toggle) else win32con.HWND_NOTOPMOST
+        win32gui.SetWindowPos(
+            self.hwnd, z_order, 0, 0, 0, 0,
+            win32con.SWP_NOMOVE | win32con.SWP_NOSIZE | win32con.SWP_NOACTIVATE,
+        )
+        return self
+
+    def minimize(self):
+        win32gui.ShowWindow(self.hwnd, win32con.SW_MINIMIZE)
+        return self
+
+    def is_active(self) -> bool:
+        return win32gui.GetForegroundWindow() == self.hwnd
+
+    def placement(self):
+        return win32gui.GetWindowPlacement(self.hwnd)
+
+    def frame(self, x=None, y=None, w=None, h=None):
+        return self.set_rect(x=x, y=y, width=w, height=h)
+
+    def mize_mini(self):
+        return self.minimize()
+
+    def mize_max(self):
+        win32gui.ShowWindow(self.hwnd, win32con.SW_MAXIMIZE)
+        return self
+
+    def mize_normal(self):
+        win32gui.ShowWindow(self.hwnd, win32con.SW_NORMAL)
+        return self
+
+    def to_dict(self):
+        return {
+            "hwnd": self.hwnd,
+            "name": self.class_name,
+            "class_name": self.class_name,
+            "title": self.title,
+            "rect": (self.rect.left, self.rect.top, self.rect.right, self.rect.bottom),
+            "placement": self.placement(),
+            "is_active": self.is_active(),
+        }
+
+    def close(self) -> bool:
+        return bool(win32gui.PostMessage(self.hwnd, win32con.WM_CLOSE, 0, 0))
+
+    def kill(self) -> bool:
+        try:
+            psutil.Process(self.pid).kill()
+            return True
+        except (psutil.Error, OSError):
+            return False
+
+    @staticmethod
+    def _normalize_capture_rect(rect, client: WindowRect) -> WindowRect:
+        if rect is None:
+            return client
+        if isinstance(rect, WindowRect):
+            target = rect
+        elif isinstance(rect, Sequence) and not isinstance(rect, (str, bytes)) and len(rect) == 4:
+            left, top, right, bottom = map(int, rect)
+            target = WindowRect.from_ltrb(left, top, right, bottom)
+        else:
+            raise TypeError("rect must be WindowRect, (left, top, right, bottom), or None")
+        left = max(client.left, target.left)
+        top = max(client.top, target.top)
+        right = min(client.right, target.right)
+        bottom = min(client.bottom, target.bottom)
+        if right <= left or bottom <= top:
+            raise ValueError("capture rect does not overlap the window client area")
+        return WindowRect.from_ltrb(left, top, right, bottom)
+
+    def _capture_client_printwindow(self, width: int, height: int) -> Optional[Image.Image]:
+        hwnd_dc = mfc_dc = save_dc = bitmap = None
+        try:
+            hwnd_dc = win32gui.GetWindowDC(self.hwnd)
+            mfc_dc = win32ui.CreateDCFromHandle(hwnd_dc)
+            save_dc = mfc_dc.CreateCompatibleDC()
+            bitmap = win32ui.CreateBitmap()
+            bitmap.CreateCompatibleBitmap(mfc_dc, width, height)
+            save_dc.SelectObject(bitmap)
+            rendered = _USER32.PrintWindow(
+                self.hwnd, save_dc.GetSafeHdc(), 0x1 | 0x2,
+            )
+            if not rendered:
+                return None
+            info = bitmap.GetInfo()
+            bits = bitmap.GetBitmapBits(True)
+            return Image.frombuffer(
+                "RGB", (info["bmWidth"], info["bmHeight"]),
+                bits, "raw", "BGRX", 0, 1,
+            ).copy()
+        finally:
+            if bitmap is not None:
+                try:
+                    win32gui.DeleteObject(bitmap.GetHandle())
+                except win32gui.error:
+                    pass
+            if save_dc is not None:
+                save_dc.DeleteDC()
+            if mfc_dc is not None:
+                mfc_dc.DeleteDC()
+            if hwnd_dc is not None:
+                win32gui.ReleaseDC(self.hwnd, hwnd_dc)
+
+    def capture(
+        self, save_path: Optional[str] = None,
+        format: WindowCaptureFormat = WindowCaptureFormat.PIL,
+        rect: Optional[Union[WindowRect, Sequence[int]]] = None,
+        force_activate: bool = True,
+    ):
+        """Capture the client area; *rect* uses physical screen coordinates."""
+        if not isinstance(format, WindowCaptureFormat):
+            raise TypeError("format must be a WindowCaptureFormat value")
+        if not self.is_valid:
+            return None
+        previous = win32gui.GetForegroundWindow() if force_activate else 0
+        try:
+            if force_activate:
+                self.activate()
+            client = self.client_rect
+            if client.width <= 0 or client.height <= 0:
+                return None
+            target = self._normalize_capture_rect(rect, client)
+            image = self._capture_client_printwindow(client.width, client.height)
+            if image is None:
+                if not self.is_visible:
+                    return None
+                image = ImageGrab.grab(
+                    bbox=(client.left, client.top, client.right, client.bottom),
+                    all_screens=True,
+                ).convert("RGB")
+            crop = (
+                target.left - client.left, target.top - client.top,
+                target.right - client.left, target.bottom - client.top,
+            )
+            image = image.crop(crop)
+            if save_path:
+                image.save(os.fspath(save_path))
+            return format.convert(image)
+        except (OSError, ValueError, win32gui.error):
+            return None
+        finally:
+            if force_activate and previous and previous != self.hwnd and win32gui.IsWindow(previous):
+                try:
+                    win32gui.SetForegroundWindow(previous)
+                except win32gui.error:
+                    pass
+
+    def _client_point(self, x: int, y: int, is_relative: bool) -> tuple[int, int]:
+        if not isinstance(x, int) or isinstance(x, bool) or not isinstance(y, int) or isinstance(y, bool):
+            raise TypeError("x and y must be integers")
+        return (x, y) if is_relative else win32gui.ScreenToClient(self.hwnd, (x, y))
+
+    def _get_lparam(self, x: int, y: int, is_relative: bool = True) -> int:
+        client_x, client_y = self._client_point(x, y, is_relative)
+        return ((client_y & 0xFFFF) << 16) | (client_x & 0xFFFF)
+
+    @staticmethod
+    def _button_messages(button: str):
+        if not isinstance(button, str):
+            raise TypeError("button must be a string")
+        token = button.casefold()
+        swapped = bool(_USER32.GetSystemMetrics(23))
+        if token == "primary":
+            token = "right" if swapped else "left"
+        elif token == "secondary":
+            token = "left" if swapped else "right"
+        mapping = {
+            "left": (win32con.WM_LBUTTONDOWN, win32con.WM_LBUTTONUP, win32con.MK_LBUTTON),
+            "right": (win32con.WM_RBUTTONDOWN, win32con.WM_RBUTTONUP, win32con.MK_RBUTTON),
+            "middle": (win32con.WM_MBUTTONDOWN, win32con.WM_MBUTTONUP, win32con.MK_MBUTTON),
+        }
+        if token not in mapping:
+            raise ValueError("button must be left, middle, right, primary or secondary")
+        return mapping[token]
+
+    def click(
+        self, x: int, y: int, clicks: int = 1, interval: float = 0.1,
+        button: str = "primary", move_duration: float = 0.0,
+        duration: float = 0.0, offset: int = 0, *, is_relative: bool = True,
+    ):
+        """Post background mouse messages without moving the physical pointer."""
+        # Keep the historical positional API while accepting the documented
+        # ``is_relative=`` keyword. This also handles ``click(x, y, False, 'right')``.
+        if isinstance(clicks, bool):
+            legacy_is_relative = clicks
+            legacy_button = interval if isinstance(interval, str) else button
+            clicks, interval, button, is_relative = 1, 0.1, legacy_button, legacy_is_relative
+        if not isinstance(clicks, int) or isinstance(clicks, bool) or clicks < 1:
+            raise ValueError("clicks must be a positive integer")
+        for value, label in ((interval, "interval"), (duration, "duration"), (move_duration, "move_duration")):
+            if isinstance(value, bool) or not isinstance(value, (int, float)) or value < 0:
+                raise ValueError(f"{label} must be a non-negative number")
+        if not isinstance(offset, int) or isinstance(offset, bool) or offset < 0:
+            raise ValueError("offset must be a non-negative integer")
+        if move_duration or offset:
+            if is_relative:
+                x, y = win32gui.ClientToScreen(self.hwnd, (x, y))
+            Mouse.click(
+                x, y, clicks=clicks, interval=interval, button=button,
+                move_duration=move_duration, duration=duration, offset=offset,
+            )
+            return self
+        lparam = self._get_lparam(x, y, is_relative)
+        down, up, state = self._button_messages(button)
+        for index in range(clicks):
+            win32gui.PostMessage(self.hwnd, win32con.WM_MOUSEMOVE, 0, lparam)
+            win32gui.PostMessage(self.hwnd, down, state, lparam)
+            if duration:
+                time.sleep(duration)
+            win32gui.PostMessage(self.hwnd, up, 0, lparam)
+            if interval and index + 1 < clicks:
+                time.sleep(interval)
+        return self
+
+    def long_click(
+        self, x: int, y: int, duration: float = 1.0,
+        is_relative: bool = True, button: str = "left",
+    ):
+        return self.click(x, y, is_relative=is_relative, button=button, duration=duration)
+
+    def drag(
+        self, x1: int, y1: int, x2: int, y2: int, duration: float = 0.5,
+        is_relative: bool = True, button: str = "left",
+    ):
+        if isinstance(duration, bool) or not isinstance(duration, (int, float)) or duration < 0:
+            raise ValueError("duration must be a non-negative number")
+        start_x, start_y = self._client_point(x1, y1, is_relative)
+        end_x, end_y = self._client_point(x2, y2, is_relative)
+        down, up, state = self._button_messages(button)
+        start = self._get_lparam(start_x, start_y, True)
+        win32gui.PostMessage(self.hwnd, win32con.WM_MOUSEMOVE, 0, start)
+        win32gui.PostMessage(self.hwnd, down, state, start)
+        steps = max(1, min(240, round(max(duration, 0.01) * 60)))
+        started = time.perf_counter()
+        try:
+            for step in range(1, steps + 1):
+                progress = step / steps
+                current_x = round(start_x + (end_x - start_x) * progress)
+                current_y = round(start_y + (end_y - start_y) * progress)
+                current = self._get_lparam(current_x, current_y, True)
+                win32gui.PostMessage(self.hwnd, win32con.WM_MOUSEMOVE, state, current)
+                delay = started + duration * progress - time.perf_counter()
+                if delay > 0:
+                    time.sleep(delay)
+        finally:
+            end = self._get_lparam(end_x, end_y, True)
+            win32gui.PostMessage(self.hwnd, up, 0, end)
+        return self
+
+    def _text_target(self) -> int:
+        """Return the focused child control for this window's GUI thread."""
+        thread_id, _ = win32process.GetWindowThreadProcessId(self.hwnd)
+        info = _GUITHREADINFO(cbSize=ctypes.sizeof(_GUITHREADINFO))
+        try:
+            if _USER32.GetGUIThreadInfo(thread_id, ctypes.byref(info)) and info.hwndFocus:
+                return int(info.hwndFocus)
+        except (AttributeError, OSError):
+            pass
+        return self.hwnd
+
+    def type_text(self, text: str, interval: float = 0.01):
+        """Post UTF-16 WM_CHAR messages to the focused child control."""
+        if not isinstance(text, str):
+            raise TypeError("text must be a string")
+        if isinstance(interval, bool) or not isinstance(interval, (int, float)) or interval < 0:
+            raise ValueError("interval must be a non-negative number")
+        encoded = text.encode("utf-16-le", errors="surrogatepass")
+        units = [int.from_bytes(encoded[index:index + 2], "little")
+                 for index in range(0, len(encoded), 2)]
+        target = self._text_target()
+        for index, unit in enumerate(units):
+            win32gui.PostMessage(target, win32con.WM_CHAR, unit, 1)
+            if interval and index + 1 < len(units):
+                time.sleep(interval)
+        return self