Allow HWND to be passed to ImageGrab.grab() on Windows by radarhere · Pull Request #8516 · python-pillow/Pillow

radarhere · 2024-10-31T08:21:39Z

Resolves #4415

Adds a handle argument to ImageGrab.grab() that accepts a HDC, allowing for a screenshot of a specific window, rather than the entire screen.

nulano · 2024-11-02T12:47:55Z

src/display.c


-    if (!PyArg_ParseTuple(args, "|ii", &includeLayeredWindows, &all_screens)) {
+    if (!PyArg_ParseTuple(
+            args, "|ii" F_HANDLE, &includeLayeredWindows, &screens, &screen


This seems to be stealing a reference to the HDC and then deleting it, which could violate the DeleteDC documentation, https://learn.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-deletedc#remarks:

An application must not delete a DC whose handle was obtained by calling the GetDC function. Instead, it must call the ReleaseDC function to free the DC.

It would also be more intuitive to accept a HWND argument and get the HDC with the GetDC function or the GetWindowDC function (making sure to release it with ReleaseDC as stated in the documentation).

Ok, I've updated the commit to receive a HWND and use ReleaseDC.

nulano

FWIW not all windows can be captured like this. Notably, Vivaldi (my browser) only shows as a black box of the correct size, and the Windows file explorer is missing its toolbar. Other applications, e.g. PyCharm or Microsoft Spy++, are captured correctly. But I think that is just a limitation of modern Windows applications and nothing we can easily fix.

nulano · 2024-11-04T19:14:55Z

src/PIL/ImageGrab.py

    include_layered_windows: bool = False,
    all_screens: bool = False,
    xdisplay: str | None = None,
+    handle: int | ImageWin.HWND | None = None,


Ok, I've chosen window.

nulano · 2024-11-04T19:44:17Z

src/display.c

    DeleteDC(screen_copy);
-    DeleteDC(screen);
+    if (screens == -1) {
+        ReleaseDC(wnd, screen);


You added this for the error: branch but not for the success branch.

Ok, I've updated the commit to add it or success as well.

nulano · 2024-11-04T19:47:00Z

src/display.c

@@ -351,11 +362,17 @@ PyImaging_GrabScreenWin32(PyObject *self, PyObject *args) {
        dpiAwareness = SetThreadDpiAwarenessContext_function((HANDLE)-3);


We need to match the capturing thread DPI awareness to the target window DPI awareness which can be queried with GetWindowDpiAwarenessContext (also added in Windows 10 version 1607): https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-getwindowdpiawarenesscontext

Without it I get a black border around applications without native DPI scaling support (e.g. Microsoft Spy++).

Ok, I've pushed a commit.

nulano · 2024-11-04T19:52:26Z

Tests/test_imagegrab.py

+        with pytest.raises(OSError):
+            ImageGrab.grab(handle=-1)


Suggested change

with pytest.raises(OSError):

ImageGrab.grab(handle=-1)

with pytest.raises(OSError):

ImageGrab.grab(handle=-1)

with pytest.raises(OSError):

ImageGrab.grab(handle=0)

The value 0 is a special way to refer to the desktop. However, it cannot be captured in the same way as regular windows so it fails, but we can add a test for that.

Thanks. I've added a commit.

nulano · 2024-11-07T19:56:24Z

src/display.c

+                GetWindowDpiAwarenessContext_function(wnd);
+            if (dpiAwarenessContext != NULL) {
+                dpiAwareness =
+                    SetThreadDpiAwarenessContext_function(dpiAwarenessContext);


It should probably never happen that SetThreadDpiAwarenessContext is found but GetWindowDpiAwarenessContext is not.

However, if it somehow does happen, we would then use dpiAwareness before its initialized after measuring the window size. So we should ideally either fallback to PER_MONITOR_AWARE context if GetWindowDpiAwarenessContext is not found, or skip the reset a few lines later.

src/display.c

…available Co-authored-by: Ondrej Baranovič <[email protected]>

for more information, see https://pre-commit.ci

Co-authored-by: Andrew Murray <[email protected]>

Fix GetWindowDpiAwarenessContext NULL check

docs/reference/ImageGrab.rst

src/PIL/ImageGrab.py

Co-authored-by: Hugo van Kemenade <[email protected]>

for more information, see https://pre-commit.ci

adabru · 2026-01-24T13:36:38Z

FWIW not all windows can be captured like this. Notably, Vivaldi (my browser) only shows as a black box of the correct size, and the Windows file explorer is missing its toolbar. Other applications, e.g. PyCharm or Microsoft Spy++, are captured correctly. But I think that is just a limitation of modern Windows applications and nothing we can easily fix.

I have a similar problem with games made with Unity3d where the second and subsequent screenshots just repeat the first screenshot I took from that window. Maybe the limitation could be mentioned in the doc: https://pillow.readthedocs.io/en/stable/reference/ImageGrab.html.

radarhere · 2026-01-24T20:26:44Z

I would like to be able to provide specifics beyond 'Sometimes it doesn't work', but not being a Windows user, I'm unable to easily test further.

If you have a better documentation suggestion, feel free to create a PR for review.

radarhere added Windows Screen grab labels Oct 31, 2024

This was referenced Oct 31, 2024

ImageGrab.grab() doesn't ignore windows layered on top (tooltip, pop-ups, etc.) #8456

Closed

Windows application screenshot #4415

Closed

radarhere force-pushed the imagegrab branch 2 times, most recently from 3c59997 to 72e3f68 Compare October 31, 2024 12:38

nulano suggested changes Nov 2, 2024

View reviewed changes

radarhere force-pushed the imagegrab branch from 72e3f68 to 356c3c1 Compare November 3, 2024 12:33

radarhere changed the title ~~Allow HDC to be passed to ImageGrab.grab() on Windows~~ Allow HWND to be passed to ImageGrab.grab() on Windows Nov 4, 2024

nulano reviewed Nov 4, 2024

View reviewed changes

Allow window to be supplied for ImageGrab.grab() on Windows

607acbf

radarhere force-pushed the imagegrab branch from cfadcd7 to 607acbf Compare November 4, 2024 20:06

Test 0

28e5b92

radarhere force-pushed the imagegrab branch from 4105f0d to 30b2772 Compare November 5, 2024 03:50

Use DPI awareness from window

9622266

radarhere force-pushed the imagegrab branch from 30b2772 to 9622266 Compare November 5, 2024 07:35

Merge branch 'main' into imagegrab

f682197

nulano reviewed Nov 7, 2024

View reviewed changes

Fallback to PER_MONITOR_AWARE

7763350

nulano reviewed Nov 7, 2024

View reviewed changes

src/display.c Outdated Show resolved Hide resolved

radarhere and others added 3 commits November 8, 2024 07:45

Fallback to PER_MONITOR_AWARE if GetWindowDpiAwarenessContext is not …

a44b306

…available Co-authored-by: Ondrej Baranovič <[email protected]>

[pre-commit.ci] auto fixes from pre-commit.com hooks

288d77e

for more information, see https://pre-commit.ci

Fix GetWindowDpiAwarenessContext NULL check

4b88670

nulano mentioned this pull request Nov 7, 2024

Fix GetWindowDpiAwarenessContext NULL check radarhere/Pillow#26

Merged

nulano and others added 3 commits November 7, 2024 22:22

Do not load GetWindowDpiAwarenessContext until its needed

a6c941a

Co-authored-by: Andrew Murray <[email protected]>

Lint fix

acba5c4

Merge pull request #26 from nulano/imagegrab-dynamic-link

c5e89ee

Fix GetWindowDpiAwarenessContext NULL check

hugovk approved these changes Mar 29, 2025

View reviewed changes

docs/reference/ImageGrab.rst Outdated Show resolved Hide resolved

src/PIL/ImageGrab.py Outdated Show resolved Hide resolved

radarhere and others added 2 commits March 30, 2025 07:27

Updated version

e053be3

Co-authored-by: Hugo van Kemenade <[email protected]>

Merge branch 'main' into imagegrab

ca9f4f8

radarhere and others added 4 commits March 30, 2025 22:13

Do not import type checking

80d5b42

Co-authored-by: Hugo van Kemenade <[email protected]>

[pre-commit.ci] auto fixes from pre-commit.com hooks

d2683e0

for more information, see https://pre-commit.ci

Corrected documentation

b4a480f

Added release notes

25af4f1

radarhere merged commit 98e74fd into python-pillow:main Apr 1, 2025
56 of 57 checks passed

radarhere deleted the imagegrab branch April 1, 2025 07:45

radarhere mentioned this pull request Aug 11, 2025

Move imports into TYPE_CHECKING #9123

Merged

	handle: int \| ImageWin.HWND \| None = None,
	window: int \| ImageWin.HWND \| None = None,

	handle: int \| ImageWin.HWND \| None = None,
	window_handle: int \| ImageWin.HWND \| None = None,

		@@ -351,11 +362,17 @@ PyImaging_GrabScreenWin32(PyObject self, PyObject args) {
		dpiAwareness = SetThreadDpiAwarenessContext_function((HANDLE)-3);

Uh oh!

Comments

Conversation

radarhere commented Oct 31, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nulano left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nulano Nov 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adabru commented Jan 24, 2026

Uh oh!

radarhere commented Jan 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

radarhere commented Oct 31, 2024 •

edited

Loading

nulano left a comment •

edited

Loading

nulano Nov 4, 2024 •

edited

Loading