uppercut-windows-window-capture 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,10 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.egg-info/
4
+ dist/
5
+ build/
6
+ .pytest_cache/
7
+ .DS_Store
8
+ uv.lock
9
+ .env*
10
+ *.pem
@@ -0,0 +1,115 @@
1
+ Metadata-Version: 2.5
2
+ Name: uppercut-windows-window-capture
3
+ Version: 0.1.0
4
+ Summary: Capture one window on Windows with PrintWindow, as a Python module and a command line tool, to PNG or BMP.
5
+ Project-URL: Source, https://github.com/uppercut-labs/py-kit/tree/main/packages/uppercut-windows-window-capture
6
+ Author-email: Uppercut Labs <packages@uppercut-labs.com>
7
+ License-Expression: MIT
8
+ Keywords: ctypes,printwindow,screenshot,window-capture,windows
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: Operating System :: Microsoft :: Windows
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Typing :: Typed
18
+ Requires-Python: >=3.10
19
+ Provides-Extra: pillow
20
+ Requires-Dist: pillow>=10; extra == 'pillow'
21
+ Description-Content-Type: text/markdown
22
+
23
+ # uppercut-windows-window-capture
24
+
25
+ Captures one window on Windows with the Win32 `PrintWindow` call and saves it as PNG or BMP. It finds the window by title, class name or process id, and works as a Python module and as a command line tool. It uses only `ctypes` and the standard library, never brings the window to the front, and can take a series of shots to tell whether a window's picture is changing or stuck. The package imports on macOS and Linux, where every call that needs Windows raises `UnsupportedPlatformError`.
26
+
27
+ ```sh
28
+ pip install uppercut-windows-window-capture
29
+ pip install "uppercut-windows-window-capture[pillow]" # only needed for Capture.to_pil()
30
+ ```
31
+
32
+ ```python
33
+ from uppercut_windows_window_capture import capture_window, find_window
34
+
35
+ window = find_window(title="Untitled - Notepad", timeout=10)
36
+ capture_window(window).save("notepad.png")
37
+ ```
38
+
39
+ ```sh
40
+ uppercut-window-capture --title "Untitled - Notepad" --out notepad.png
41
+ uppercut-window-capture --pid 4242 --client --out client.bmp
42
+ uppercut-window-capture --title "My App" --series 10 --interval 1 --out-dir shots
43
+ ```
44
+
45
+ ## Functions
46
+
47
+ | Function | Returns |
48
+ | --- | --- |
49
+ | `list_windows(visible_only=True)` | every top-level window as a `WindowInfo` |
50
+ | `find_windows(title, class_name, pid, match, visible_only, min_size)` | the `WindowInfo` list that matches every given filter |
51
+ | `find_window(title, class_name, pid, match, prefer_largest, timeout, interval)` | one `WindowInfo`; raises `WindowNotFoundError` after `timeout` seconds |
52
+ | `capture_window(window, client_only, fallback, full_content, crop_to_frame, restore)` | a `Capture`; `window` is a `WindowInfo` or a handle |
53
+ | `capture_series(window, count, interval, min_changed, **capture_options)` | a `SeriesResult` with the shots, the changed-pixel count of each pair and `live` |
54
+ | `watch(grab, count, interval, min_changed)` | the same `SeriesResult`, from any function that returns a `Capture` |
55
+ | `enable_dpi_awareness()` | nothing; call it first on scaled displays so sizes are real pixels |
56
+ | `match_text(text, pattern, mode)` | whether the text matches. Modes: `substring`, `exact`, `glob`, `regex`, all case-insensitive |
57
+ | `select_windows(windows, ...)` | filters a list of `WindowInfo` with the same rules as `find_windows` |
58
+ | `frame_crop_box(window_rect, frame_rect)` | the `(left, top, width, height)` of the visible frame |
59
+ | `encode_png`, `encode_bmp`, `bgra_to_rgb`, `count_changed_pixels` | helpers on raw top-down BGRA bytes |
60
+
61
+ `Capture` has `width`, `height`, `bgra`, `save(path, fmt=None)`, `to_bytes(fmt)`, `to_rgb()`, `to_pil()`, `crop(left, top, width, height)`, `changed_pixels(other)` and `is_blank()`.
62
+
63
+ ### Capture options
64
+
65
+ | Option | Default | Meaning |
66
+ | --- | --- | --- |
67
+ | `client_only` | `False` | Capture the client area only, without title bar and borders |
68
+ | `fallback` | `"bitblt"` | If PrintWindow fails: `"bitblt"` copies from the window's device context, `"screen"` copies the window's rectangle from the screen (anything covering it shows up), `"none"` raises `CaptureFailedError` |
69
+ | `full_content` | `True` | Pass `PW_RENDERFULLCONTENT` so GPU-composed windows render |
70
+ | `crop_to_frame` | `False` | Trim the invisible resize border that the window rectangle includes on Windows 10 and 11 |
71
+ | `restore` | `False` | Show a minimized window again, without activating it, before capturing |
72
+
73
+ ## Command line
74
+
75
+ `uppercut-window-capture` takes `--title`, `--class` or `--pid` (any combination), plus:
76
+
77
+ | Option | Meaning |
78
+ | --- | --- |
79
+ | `--match substring\|exact\|glob\|regex` | How `--title` and `--class` match; default `substring` |
80
+ | `--largest` | Use the largest window when several match |
81
+ | `--wait SECONDS` | Keep looking for the window |
82
+ | `--list` | Print the matching windows and exit |
83
+ | `--client`, `--fallback`, `--no-full-content`, `--crop-frame`, `--restore`, `--dpi-aware` | The capture options above |
84
+ | `--crop X,Y,W,H` | Keep only this rectangle |
85
+ | `--fail-on-blank` | Exit 4 if the capture is one flat colour |
86
+ | `--out FILE`, `--format png\|bmp` | Output file; the format comes from the extension unless given. Default `capture.png` |
87
+ | `--series N`, `--interval SECONDS`, `--min-changed PIXELS`, `--out-dir DIR` | Take N shots, save them as `cap_00`, `cap_01` and so on, and print `LIVE` or `FROZEN` |
88
+
89
+ | Exit code | Meaning |
90
+ | --- | --- |
91
+ | 0 | Captured, or the series is live |
92
+ | 2 | No window matched |
93
+ | 3 | The series is frozen: no pair of shots differed by `--min-changed` pixels |
94
+ | 4 | The capture failed |
95
+ | 5 | Not running on Windows |
96
+ | 64 | Wrong arguments |
97
+
98
+ ## Errors
99
+
100
+ All errors derive from `WindowCaptureError`.
101
+
102
+ | Error | Raised when |
103
+ | --- | --- |
104
+ | `UnsupportedPlatformError` (also a `RuntimeError`) | A window function is used on a system other than Windows |
105
+ | `WindowNotFoundError` (also a `LookupError`) | No window matches, or the handle no longer exists |
106
+ | `CaptureFailedError` | Windows returns no pixels, or the window has no visible area |
107
+
108
+ ## Notes
109
+
110
+ - Some Direct3D and OpenGL windows come back black from `PrintWindow`. Use `Capture.is_blank()` or `--fail-on-blank` to detect it, and try `--fallback screen`.
111
+ - Capturing never activates the window or changes its position.
112
+
113
+ ## License
114
+
115
+ MIT
@@ -0,0 +1,93 @@
1
+ # uppercut-windows-window-capture
2
+
3
+ Captures one window on Windows with the Win32 `PrintWindow` call and saves it as PNG or BMP. It finds the window by title, class name or process id, and works as a Python module and as a command line tool. It uses only `ctypes` and the standard library, never brings the window to the front, and can take a series of shots to tell whether a window's picture is changing or stuck. The package imports on macOS and Linux, where every call that needs Windows raises `UnsupportedPlatformError`.
4
+
5
+ ```sh
6
+ pip install uppercut-windows-window-capture
7
+ pip install "uppercut-windows-window-capture[pillow]" # only needed for Capture.to_pil()
8
+ ```
9
+
10
+ ```python
11
+ from uppercut_windows_window_capture import capture_window, find_window
12
+
13
+ window = find_window(title="Untitled - Notepad", timeout=10)
14
+ capture_window(window).save("notepad.png")
15
+ ```
16
+
17
+ ```sh
18
+ uppercut-window-capture --title "Untitled - Notepad" --out notepad.png
19
+ uppercut-window-capture --pid 4242 --client --out client.bmp
20
+ uppercut-window-capture --title "My App" --series 10 --interval 1 --out-dir shots
21
+ ```
22
+
23
+ ## Functions
24
+
25
+ | Function | Returns |
26
+ | --- | --- |
27
+ | `list_windows(visible_only=True)` | every top-level window as a `WindowInfo` |
28
+ | `find_windows(title, class_name, pid, match, visible_only, min_size)` | the `WindowInfo` list that matches every given filter |
29
+ | `find_window(title, class_name, pid, match, prefer_largest, timeout, interval)` | one `WindowInfo`; raises `WindowNotFoundError` after `timeout` seconds |
30
+ | `capture_window(window, client_only, fallback, full_content, crop_to_frame, restore)` | a `Capture`; `window` is a `WindowInfo` or a handle |
31
+ | `capture_series(window, count, interval, min_changed, **capture_options)` | a `SeriesResult` with the shots, the changed-pixel count of each pair and `live` |
32
+ | `watch(grab, count, interval, min_changed)` | the same `SeriesResult`, from any function that returns a `Capture` |
33
+ | `enable_dpi_awareness()` | nothing; call it first on scaled displays so sizes are real pixels |
34
+ | `match_text(text, pattern, mode)` | whether the text matches. Modes: `substring`, `exact`, `glob`, `regex`, all case-insensitive |
35
+ | `select_windows(windows, ...)` | filters a list of `WindowInfo` with the same rules as `find_windows` |
36
+ | `frame_crop_box(window_rect, frame_rect)` | the `(left, top, width, height)` of the visible frame |
37
+ | `encode_png`, `encode_bmp`, `bgra_to_rgb`, `count_changed_pixels` | helpers on raw top-down BGRA bytes |
38
+
39
+ `Capture` has `width`, `height`, `bgra`, `save(path, fmt=None)`, `to_bytes(fmt)`, `to_rgb()`, `to_pil()`, `crop(left, top, width, height)`, `changed_pixels(other)` and `is_blank()`.
40
+
41
+ ### Capture options
42
+
43
+ | Option | Default | Meaning |
44
+ | --- | --- | --- |
45
+ | `client_only` | `False` | Capture the client area only, without title bar and borders |
46
+ | `fallback` | `"bitblt"` | If PrintWindow fails: `"bitblt"` copies from the window's device context, `"screen"` copies the window's rectangle from the screen (anything covering it shows up), `"none"` raises `CaptureFailedError` |
47
+ | `full_content` | `True` | Pass `PW_RENDERFULLCONTENT` so GPU-composed windows render |
48
+ | `crop_to_frame` | `False` | Trim the invisible resize border that the window rectangle includes on Windows 10 and 11 |
49
+ | `restore` | `False` | Show a minimized window again, without activating it, before capturing |
50
+
51
+ ## Command line
52
+
53
+ `uppercut-window-capture` takes `--title`, `--class` or `--pid` (any combination), plus:
54
+
55
+ | Option | Meaning |
56
+ | --- | --- |
57
+ | `--match substring\|exact\|glob\|regex` | How `--title` and `--class` match; default `substring` |
58
+ | `--largest` | Use the largest window when several match |
59
+ | `--wait SECONDS` | Keep looking for the window |
60
+ | `--list` | Print the matching windows and exit |
61
+ | `--client`, `--fallback`, `--no-full-content`, `--crop-frame`, `--restore`, `--dpi-aware` | The capture options above |
62
+ | `--crop X,Y,W,H` | Keep only this rectangle |
63
+ | `--fail-on-blank` | Exit 4 if the capture is one flat colour |
64
+ | `--out FILE`, `--format png\|bmp` | Output file; the format comes from the extension unless given. Default `capture.png` |
65
+ | `--series N`, `--interval SECONDS`, `--min-changed PIXELS`, `--out-dir DIR` | Take N shots, save them as `cap_00`, `cap_01` and so on, and print `LIVE` or `FROZEN` |
66
+
67
+ | Exit code | Meaning |
68
+ | --- | --- |
69
+ | 0 | Captured, or the series is live |
70
+ | 2 | No window matched |
71
+ | 3 | The series is frozen: no pair of shots differed by `--min-changed` pixels |
72
+ | 4 | The capture failed |
73
+ | 5 | Not running on Windows |
74
+ | 64 | Wrong arguments |
75
+
76
+ ## Errors
77
+
78
+ All errors derive from `WindowCaptureError`.
79
+
80
+ | Error | Raised when |
81
+ | --- | --- |
82
+ | `UnsupportedPlatformError` (also a `RuntimeError`) | A window function is used on a system other than Windows |
83
+ | `WindowNotFoundError` (also a `LookupError`) | No window matches, or the handle no longer exists |
84
+ | `CaptureFailedError` | Windows returns no pixels, or the window has no visible area |
85
+
86
+ ## Notes
87
+
88
+ - Some Direct3D and OpenGL windows come back black from `PrintWindow`. Use `Capture.is_blank()` or `--fail-on-blank` to detect it, and try `--fallback screen`.
89
+ - Capturing never activates the window or changes its position.
90
+
91
+ ## License
92
+
93
+ MIT
@@ -0,0 +1,40 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.25"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "uppercut-windows-window-capture"
7
+ version = "0.1.0"
8
+ description = "Capture one window on Windows with PrintWindow, as a Python module and a command line tool, to PNG or BMP."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = "MIT"
12
+ authors = [{ name = "Uppercut Labs", email = "packages@uppercut-labs.com" }]
13
+ keywords = ["windows", "screenshot", "printwindow", "window-capture", "ctypes"]
14
+ dependencies = []
15
+ classifiers = [
16
+ "Development Status :: 4 - Beta",
17
+ "Intended Audience :: Developers",
18
+ "Operating System :: Microsoft :: Windows",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3.10",
21
+ "Programming Language :: Python :: 3.11",
22
+ "Programming Language :: Python :: 3.12",
23
+ "Programming Language :: Python :: 3.13",
24
+ "Typing :: Typed",
25
+ ]
26
+
27
+ [project.optional-dependencies]
28
+ pillow = ["Pillow>=10"]
29
+
30
+ [project.scripts]
31
+ uppercut-window-capture = "uppercut_windows_window_capture.cli:main"
32
+
33
+ [project.urls]
34
+ Source = "https://github.com/uppercut-labs/py-kit/tree/main/packages/uppercut-windows-window-capture"
35
+
36
+ [tool.hatch.build.targets.wheel]
37
+ packages = ["src/uppercut_windows_window_capture"]
38
+
39
+ [tool.hatch.build.targets.sdist]
40
+ include = ["src", "tests", "README.md"]
@@ -0,0 +1,40 @@
1
+ """Capture one window on Windows with PrintWindow, to PNG or BMP. Imports on every platform."""
2
+
3
+ from .capture import (
4
+ SeriesResult,
5
+ capture_series,
6
+ capture_window,
7
+ enable_dpi_awareness,
8
+ find_window,
9
+ find_windows,
10
+ list_windows,
11
+ watch,
12
+ )
13
+ from .errors import CaptureFailedError, UnsupportedPlatformError, WindowCaptureError, WindowNotFoundError
14
+ from .image import Capture, bgra_to_rgb, count_changed_pixels, encode_bmp, encode_png
15
+ from .matching import WindowInfo, frame_crop_box, match_text, select_windows
16
+
17
+ __all__ = [
18
+ "Capture",
19
+ "CaptureFailedError",
20
+ "SeriesResult",
21
+ "UnsupportedPlatformError",
22
+ "WindowCaptureError",
23
+ "WindowInfo",
24
+ "WindowNotFoundError",
25
+ "bgra_to_rgb",
26
+ "capture_series",
27
+ "capture_window",
28
+ "count_changed_pixels",
29
+ "enable_dpi_awareness",
30
+ "encode_bmp",
31
+ "encode_png",
32
+ "find_window",
33
+ "find_windows",
34
+ "frame_crop_box",
35
+ "list_windows",
36
+ "match_text",
37
+ "select_windows",
38
+ "watch",
39
+ ]
40
+ __version__ = "0.1.0"
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from .cli import main
4
+
5
+ sys.exit(main())
@@ -0,0 +1,215 @@
1
+ """Win32 calls through ctypes. Import this module only on Windows."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import ctypes
6
+ import ctypes.wintypes as wt
7
+ import sys
8
+
9
+ from .errors import CaptureFailedError, UnsupportedPlatformError
10
+ from .matching import WindowInfo
11
+
12
+ if sys.platform != "win32": # pragma: no cover - guarded by the caller as well
13
+ raise UnsupportedPlatformError("window capture works only on Windows")
14
+
15
+ user32 = ctypes.WinDLL("user32", use_last_error=True)
16
+ gdi32 = ctypes.WinDLL("gdi32", use_last_error=True)
17
+ dwmapi = ctypes.WinDLL("dwmapi", use_last_error=True)
18
+
19
+ PW_CLIENTONLY = 0x1
20
+ PW_RENDERFULLCONTENT = 0x2
21
+ SRCCOPY = 0x00CC0020
22
+ CAPTUREBLT = 0x40000000
23
+ DIB_RGB_COLORS = 0
24
+ DWMWA_EXTENDED_FRAME_BOUNDS = 9
25
+ SW_SHOWNOACTIVATE = 4
26
+
27
+ HANDLE = ctypes.c_void_p
28
+ WNDENUMPROC = ctypes.WINFUNCTYPE(wt.BOOL, HANDLE, wt.LPARAM)
29
+
30
+
31
+ class BITMAPINFOHEADER(ctypes.Structure):
32
+ _fields_ = [
33
+ ("biSize", wt.DWORD), ("biWidth", ctypes.c_long), ("biHeight", ctypes.c_long),
34
+ ("biPlanes", wt.WORD), ("biBitCount", wt.WORD), ("biCompression", wt.DWORD),
35
+ ("biSizeImage", wt.DWORD), ("biXPelsPerMeter", ctypes.c_long), ("biYPelsPerMeter", ctypes.c_long),
36
+ ("biClrUsed", wt.DWORD), ("biClrImportant", wt.DWORD),
37
+ ]
38
+
39
+
40
+ class BITMAPINFO(ctypes.Structure):
41
+ _fields_ = [("bmiHeader", BITMAPINFOHEADER), ("bmiColors", wt.DWORD * 3)]
42
+
43
+
44
+ def _sig(func, restype, *argtypes):
45
+ func.restype = restype
46
+ func.argtypes = list(argtypes)
47
+
48
+
49
+ # Explicit signatures keep 64-bit handles from being truncated to 32-bit ints.
50
+ _sig(user32.EnumWindows, wt.BOOL, WNDENUMPROC, wt.LPARAM)
51
+ _sig(user32.IsWindowVisible, wt.BOOL, HANDLE)
52
+ _sig(user32.IsWindow, wt.BOOL, HANDLE)
53
+ _sig(user32.IsIconic, wt.BOOL, HANDLE)
54
+ _sig(user32.ShowWindow, wt.BOOL, HANDLE, ctypes.c_int)
55
+ _sig(user32.GetWindowTextLengthW, ctypes.c_int, HANDLE)
56
+ _sig(user32.GetWindowTextW, ctypes.c_int, HANDLE, wt.LPWSTR, ctypes.c_int)
57
+ _sig(user32.GetClassNameW, ctypes.c_int, HANDLE, wt.LPWSTR, ctypes.c_int)
58
+ _sig(user32.GetWindowThreadProcessId, wt.DWORD, HANDLE, ctypes.POINTER(wt.DWORD))
59
+ _sig(user32.GetWindowRect, wt.BOOL, HANDLE, ctypes.POINTER(wt.RECT))
60
+ _sig(user32.GetClientRect, wt.BOOL, HANDLE, ctypes.POINTER(wt.RECT))
61
+ _sig(user32.ClientToScreen, wt.BOOL, HANDLE, ctypes.POINTER(wt.POINT))
62
+ _sig(user32.GetDC, HANDLE, HANDLE)
63
+ _sig(user32.ReleaseDC, ctypes.c_int, HANDLE, HANDLE)
64
+ _sig(user32.PrintWindow, wt.BOOL, HANDLE, HANDLE, wt.UINT)
65
+ _sig(gdi32.CreateCompatibleDC, HANDLE, HANDLE)
66
+ _sig(gdi32.CreateCompatibleBitmap, HANDLE, HANDLE, ctypes.c_int, ctypes.c_int)
67
+ _sig(gdi32.SelectObject, HANDLE, HANDLE, HANDLE)
68
+ _sig(gdi32.DeleteObject, wt.BOOL, HANDLE)
69
+ _sig(gdi32.DeleteDC, wt.BOOL, HANDLE)
70
+ _sig(gdi32.BitBlt, wt.BOOL, HANDLE, ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int, HANDLE,
71
+ ctypes.c_int, ctypes.c_int, wt.DWORD)
72
+ _sig(gdi32.GetDIBits, ctypes.c_int, HANDLE, HANDLE, wt.UINT, wt.UINT, ctypes.c_void_p,
73
+ ctypes.POINTER(BITMAPINFO), wt.UINT)
74
+ _sig(dwmapi.DwmGetWindowAttribute, ctypes.c_long, HANDLE, wt.DWORD, ctypes.c_void_p, wt.DWORD)
75
+
76
+
77
+ def enable_dpi_awareness() -> None:
78
+ """Make this process report real pixel sizes on scaled displays. Safe to call more than once."""
79
+ try:
80
+ ctypes.windll.user32.SetProcessDpiAwarenessContext(ctypes.c_void_p(-4)) # per-monitor v2
81
+ return
82
+ except (AttributeError, OSError):
83
+ pass
84
+ try:
85
+ ctypes.windll.user32.SetProcessDPIAware()
86
+ except (AttributeError, OSError):
87
+ pass
88
+
89
+
90
+ def _text(hwnd: int) -> str:
91
+ n = user32.GetWindowTextLengthW(hwnd)
92
+ if n <= 0:
93
+ return ""
94
+ buf = ctypes.create_unicode_buffer(n + 1)
95
+ user32.GetWindowTextW(hwnd, buf, n + 1)
96
+ return buf.value
97
+
98
+
99
+ def _class(hwnd: int) -> str:
100
+ buf = ctypes.create_unicode_buffer(256)
101
+ user32.GetClassNameW(hwnd, buf, 256)
102
+ return buf.value
103
+
104
+
105
+ def window_rect(hwnd: int) -> tuple[int, int, int, int]:
106
+ rc = wt.RECT()
107
+ if not user32.GetWindowRect(hwnd, ctypes.byref(rc)):
108
+ raise CaptureFailedError("GetWindowRect failed for window 0x%X" % hwnd)
109
+ return rc.left, rc.top, rc.right, rc.bottom
110
+
111
+
112
+ def frame_rect(hwnd: int) -> tuple[int, int, int, int] | None:
113
+ """The visible frame bounds from the desktop window manager, or None if unavailable."""
114
+ rc = wt.RECT()
115
+ hr = dwmapi.DwmGetWindowAttribute(hwnd, DWMWA_EXTENDED_FRAME_BOUNDS, ctypes.byref(rc), ctypes.sizeof(rc))
116
+ if hr != 0:
117
+ return None
118
+ return rc.left, rc.top, rc.right, rc.bottom
119
+
120
+
121
+ def enumerate_windows() -> list[WindowInfo]:
122
+ found: list[WindowInfo] = []
123
+
124
+ def callback(hwnd, _lparam):
125
+ pid = wt.DWORD()
126
+ user32.GetWindowThreadProcessId(hwnd, ctypes.byref(pid))
127
+ rc = wt.RECT()
128
+ user32.GetWindowRect(hwnd, ctypes.byref(rc))
129
+ found.append(
130
+ WindowInfo(
131
+ hwnd=int(hwnd or 0),
132
+ title=_text(hwnd),
133
+ class_name=_class(hwnd),
134
+ pid=int(pid.value),
135
+ rect=(rc.left, rc.top, rc.right, rc.bottom),
136
+ visible=bool(user32.IsWindowVisible(hwnd)),
137
+ )
138
+ )
139
+ return True
140
+
141
+ user32.EnumWindows(WNDENUMPROC(callback), 0)
142
+ return found
143
+
144
+
145
+ def is_window(hwnd: int) -> bool:
146
+ return bool(user32.IsWindow(hwnd))
147
+
148
+
149
+ def restore_if_minimized(hwnd: int) -> bool:
150
+ """Show a minimized window again without activating it. Returns True if it was minimized."""
151
+ if user32.IsIconic(hwnd):
152
+ user32.ShowWindow(hwnd, SW_SHOWNOACTIVATE)
153
+ return True
154
+ return False
155
+
156
+
157
+ def grab(hwnd: int, *, client_only: bool, fallback: str, full_content: bool) -> tuple[int, int, bytes]:
158
+ """Return (width, height, top-down BGRA bytes with opaque alpha)."""
159
+ rc = wt.RECT()
160
+ getter = user32.GetClientRect if client_only else user32.GetWindowRect
161
+ if not getter(hwnd, ctypes.byref(rc)):
162
+ raise CaptureFailedError("could not read the size of window 0x%X" % hwnd)
163
+ width, height = rc.right - rc.left, rc.bottom - rc.top
164
+ if width <= 0 or height <= 0:
165
+ raise CaptureFailedError("window 0x%X has no visible area (%dx%d)" % (hwnd, width, height))
166
+
167
+ hdc_window = user32.GetDC(hwnd)
168
+ if not hdc_window:
169
+ raise CaptureFailedError("GetDC failed for window 0x%X" % hwnd)
170
+ hdc_mem = gdi32.CreateCompatibleDC(hdc_window)
171
+ hbmp = gdi32.CreateCompatibleBitmap(hdc_window, width, height)
172
+ old = gdi32.SelectObject(hdc_mem, hbmp)
173
+ try:
174
+ flags = (PW_CLIENTONLY if client_only else 0) | (PW_RENDERFULLCONTENT if full_content else 0)
175
+ ok = bool(user32.PrintWindow(hwnd, hdc_mem, flags))
176
+ if not ok and fallback == "bitblt":
177
+ ok = bool(gdi32.BitBlt(hdc_mem, 0, 0, width, height, hdc_window, 0, 0, SRCCOPY))
178
+ elif not ok and fallback == "screen":
179
+ if client_only:
180
+ origin = wt.POINT(0, 0)
181
+ user32.ClientToScreen(hwnd, ctypes.byref(origin))
182
+ sx, sy = origin.x, origin.y
183
+ else:
184
+ sx, sy = rc.left, rc.top
185
+ hdc_screen = user32.GetDC(None)
186
+ try:
187
+ ok = bool(gdi32.BitBlt(hdc_mem, 0, 0, width, height, hdc_screen, sx, sy, SRCCOPY | CAPTUREBLT))
188
+ finally:
189
+ user32.ReleaseDC(None, hdc_screen)
190
+ if not ok:
191
+ raise CaptureFailedError("PrintWindow failed for window 0x%X (fallback: %s)" % (hwnd, fallback))
192
+
193
+ info = BITMAPINFO()
194
+ info.bmiHeader.biSize = ctypes.sizeof(BITMAPINFOHEADER)
195
+ info.bmiHeader.biWidth = width
196
+ info.bmiHeader.biHeight = -height # top-down
197
+ info.bmiHeader.biPlanes = 1
198
+ info.bmiHeader.biBitCount = 32
199
+ info.bmiHeader.biCompression = 0
200
+ buf = ctypes.create_string_buffer(width * height * 4)
201
+ # The bitmap must not be selected into a DC while GetDIBits reads it.
202
+ gdi32.SelectObject(hdc_mem, old)
203
+ old = None
204
+ got = gdi32.GetDIBits(hdc_mem, hbmp, 0, height, buf, ctypes.byref(info), DIB_RGB_COLORS)
205
+ if got != height:
206
+ raise CaptureFailedError("GetDIBits returned %d of %d rows" % (got, height))
207
+ data = bytearray(buf.raw)
208
+ data[3::4] = b"\xff" * (width * height)
209
+ return width, height, bytes(data)
210
+ finally:
211
+ if old:
212
+ gdi32.SelectObject(hdc_mem, old)
213
+ gdi32.DeleteObject(hbmp)
214
+ gdi32.DeleteDC(hdc_mem)
215
+ user32.ReleaseDC(hwnd, hdc_window)