SetWindowsHookEx(WH_SHELL, ...): What is the meaning of event HSHELL_WINDOWREPLACED?

Question

If I register a hook via SetWindowsHookEx(WH_SHELL, ShellProc, ...), what is the meaning of event HSHELL_WINDOWREPLACED? (My Google-fu fails me. I have searched high and low!)

Win32 Docs:

SetWindowsHookEx(): https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-setwindowshookexw
ShellProc (callback): https://learn.microsoft.com/en-us/windows/win32/winmsg/shellproc

The offical docs read: A top-level window is being replaced. Weirdly, they also say: Windows 2000: Not supported. Does that mean only supported before or after Win2K?

I created a test driver to watch a Microsoft Windows session, but I was never able to trigger this mysterious event.

I also found a similar event here:

RegisterShellHookWindow: https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-registershellhookwindow

... that says:

HSHELL_WINDOWREPLACING: A handle to the window replacing the top-level window.
HSHELL_WINDOWREPLACED: A handle to the window being replaced.

The "not supported" language in the parameters or requirements section always means that it is not supported with that version and earlier. If something is being removed there is a much more prominent notice near the top of the page (and generally says that something is under consideration for removal and shouldn't be used going forward). Actual removal where something no longer works is a very much more rare thing with Microsoft), they are generally very serious about backwards compatibility. — SoronelHaetir, Mar 06 '22 at 16:53
The notification is sent when a window stops responding to messages, and the system replaces it with a faded-out version ("ghost" window). — Jonathan Potter, Mar 06 '22 at 19:16
@JonathanPotter Great comment! If you post as an answer, I am happy to mark as the correct answer. — kevinarpe, Mar 07 '22 at 16:44

score 2 · Accepted Answer · answered Mar 07 '22 at 19:28

In this instance, the term "replace" refers to the occasions when a window stops responding to messages ("hangs") and, after a certain period, Windows hides it and replaces it on-screen with a faded-out copy (called a "ghost window").

Windows does this so that, even when the app is not processing messages, the user can interact with the ghost window to move it around and try to close it.

The wParam value is the handle of the hung window (the one being replaced) and the lParam value is the handle of the ghost window (its replacement).

If the window starts responding again, the notification is sent again, with the window handles swapped around.

If a window becomes responsive again, will this event (`HSHELL_WINDOWREPLACED`) occur again, but arguments reversed? Or will the replacement window be destoyed via `HSHELL_WINDOWDESTROYED`? — kevinarpe, Mar 11 '22 at 16:35

SetWindowsHookEx(WH_SHELL, ...): What is the meaning of event HSHELL_WINDOWREPLACED?

1 Answers1