API of win32_window_monitor

class win32_window_monitor.EventHookHandle(handle: HANDLE, proc: Callable[[HANDLE, DWORD, HWND, LONG, LONG, DWORD, DWORD], None])

Bases: object

Event hook handle used to stop listening for the event, must remain alive while listening for events.

unhook()

Stops listening for events registered for this handle.

class win32_window_monitor.HookEvent(value)

Bases: NamedInt

Event constants for set_event_hook() and its callback. Names are identical to Windows SDK, with EVENT_ prefix stripped.

See https://learn.microsoft.com/en-us/windows/win32/winauto/event-constants for a detailed and accurate description of each event.

Extends int to allow wrapping of any event id: HookEvent(0x1234), even if it is missing in the constant declared below.

AIA_END = 0xAFFF

End of the range for Accessibility Interoperability Alliance (AIA) WinEvent

AIA_START = 0xA000

Start of the range for Accessibility Interoperability Alliance (AIA) WinEvent

MAX = 0x7FFFFFFF

highest possible event id.

MIN = 0x1

Lowest possible event id.

OBJECT_ACCELERATORCHANGE = 0x8012

An object’s KeyboardShortcut property changed.

OBJECT_CLOAKED = 0x8017

Sent when a window is cloaked. A cloaked window still exists but is invisible to the user.

OBJECT_CONTENTSCROLLED = 0x8015

A window object’s scrolling has ended.

OBJECT_CREATE = 0x8000

An object has been created.

OBJECT_DEFACTIONCHANGE = 0x8011

An object’s DefaultAction property has changed.

OBJECT_DESCRIPTIONCHANGE = 0x800D

An object’s Description property has changed.

OBJECT_DESTROY = 0x8001

An object has been destroyed.

OBJECT_DRAGCANCEL = 0x8022

The user has ended a drag operation before dropping the dragged element on a drop target.

OBJECT_DRAGCOMPLETE = 0x8023

The user dropped an element on a drop target.

OBJECT_DRAGDROPPED = 0x8026

The user dropped an element on a drop target.

OBJECT_DRAGENTER = 0x8024

The user dragged an element into a drop target’s boundary.

OBJECT_DRAGLEAVE = 0x8025

The user dragged an element out of a drop target’s boundary.

OBJECT_DRAGSTART = 0x8021

The user started to drag an element.

OBJECT_END = 0x80FF

The highest object event value.

OBJECT_FOCUS = 0x8005

An object has received the keyboard focus.

OBJECT_HELPCHANGE = 0x8010

An object’s Help property has changed.

OBJECT_HIDE = 0x8003

An object is hidden.

OBJECT_HOSTEDOBJECTSINVALIDATED = 0x8020

A window that hosts other accessible objects has changed the hosted objects.

OBJECT_IME_CHANGE = 0x8029

The size or position of an IME window has changed.

OBJECT_IME_HIDE = 0x8028

An IME window has become hidden.

OBJECT_IME_SHOW = 0x8027

An IME window has become visible.

OBJECT_INVOKED = 0x8013

An object has been invoked; for example, the user has clicked a button.

OBJECT_LIVEREGIONCHANGED = 0x8019

An object that is part of a live region has changed.

OBJECT_LOCATIONCHANGE = 0x800B

An object has changed location, shape, or size.

OBJECT_NAMECHANGE = 0x800C

An object’s Name property has changed.

OBJECT_PARENTCHANGE = 0x800F

An object has a new parent object.

OBJECT_REORDER = 0x8004

A container object has added, removed, or reordered its children.

OBJECT_SELECTION = 0x8006

The selection within a container object has changed.

OBJECT_SELECTIONADD = 0x8007

A child within a container object has been added to an existing selection.

OBJECT_SELECTIONREMOVE = 0x8008

An item within a container object has been removed from the selection.

OBJECT_SELECTIONWITHIN = 0x8009

Numerous selection changes have occurred within a container object.

OBJECT_SHOW = 0x8002

A hidden object is shown.

OBJECT_STATECHANGE = 0x800A

An object’s state has changed.

OBJECT_TEXTEDIT_CONVERSIONTARGETCHANGED = 0x8030

The conversion target within an IME composition has changed.

OBJECT_TEXTSELECTIONCHANGED = 0x8014

An object’s text selection has changed.

OBJECT_UNCLOAKED = 0x8018

Sent when a window is uncloaked.

OBJECT_VALUECHANGE = 0x800E

An object’s Value property has changed.

OEM_DEFINED_END = 0x1FF
OEM_DEFINED_START = 0x101

Range of event constant values reserved for OEMs.

SYSTEM_ALERT = 0x2

An alert has been generated.

SYSTEM_ARRANGMENTPREVIEW = 0x8016

A preview rectangle is being displayed.

SYSTEM_CAPTUREEND = 0x9

A window has lost mouse capture.

SYSTEM_CAPTURESTART = 0x8

A window has received mouse capture.

SYSTEM_CONTEXTHELPEND = 0xD

A window has exited context-sensitive Help mode.

SYSTEM_CONTEXTHELPSTART = 0xC

A window has entered context-sensitive Help mode.

SYSTEM_DESKTOPSWITCH = 0x20

The active desktop has been switched.

SYSTEM_DIALOGEND = 0x11

A dialog box has been closed.

SYSTEM_DIALOGSTART = 0x10

A dialog box has been displayed.

SYSTEM_DRAGDROPEND = 0xF

An application is about to exit drag-and-drop mode.

SYSTEM_DRAGDROPSTART = 0xE

An application is about to enter drag-and-drop mode.

SYSTEM_END = 0xFF

The highest system event value.

SYSTEM_FOREGROUND = 0x3

The foreground window has changed.

SYSTEM_MENUEND = 0x5

A menu from the menu bar has been closed.

SYSTEM_MENUPOPUPEND = 0x7

A pop-up menu has been closed.

SYSTEM_MENUPOPUPSTART = 0x6

A pop-up menu has been displayed.

SYSTEM_MENUSTART = 0x4

A menu item on the menu bar has been selected.

SYSTEM_MINIMIZEEND = 0x17

A window object is about to be restored.

SYSTEM_MINIMIZESTART = 0x16

A window object is about to be minimized.

SYSTEM_MOVESIZEEND = 0xB

The movement or resizing of a window has finished.

SYSTEM_MOVESIZESTART = 0xA

A window is being moved or resized.

SYSTEM_SCROLLINGEND = 0x13

Scrolling has ended on a scroll bar.

SYSTEM_SCROLLINGSTART = 0x12

Scrolling has started on a scroll bar.

SYSTEM_SOUND = 0x1

A sound has been played.

SYSTEM_SWITCHEND = 0x15

The user has released ALT+TAB.

SYSTEM_SWITCHSTART = 0x14

The user has pressed ALT+TAB, which activates the switch window.

UIA_EVENTID_END = 0x4EFF

End of range reserved for UI Automation event identifiers.

UIA_EVENTID_START = 0x4E00

Start of range reserved for UI Automation event identifiers.

UIA_PROPID_END = 0x75FF

End of range reserved for UI Automation property-changed event identifiers.

UIA_PROPID_START = 0x7500

Start of range reserved for UI Automation property-changed event identifiers.

class win32_window_monitor.NamedInt(value)

Bases: int

Kind of a enum that allows wrapping of any integer value, but report the name when matching a declared class constant field.

See https://docs.python.org/3/reference/datamodel.html#customizing-class-creation for an example of the logic used to convert integer constant to actual instance of the class.

property name

Name of the enum value, or None for unknown int value.

For example HookEvent.SYSTEM_FOREGROUND.name returns ‘SYSTEM_FOREGROUND’

classmethod names()

Returns an iterator over the list of the .name of each enum value.

property value

The integer value of the enum.

For example HookEvent.SYSTEM_FOREGROUND.value returns 0x0003

classmethod values()

Returns an iterator over the list of all enums that have .name and .value property.

class win32_window_monitor.ObjectId(value)

Bases: NamedInt

Object ids constants for set_event_hook() callback id_object parameter. Names are identical to Windows SDK, with OBJID_ prefix stripped.

See https://learn.microsoft.com/en-us/windows/win32/winauto/object-identifiers for a detailed and accurate description of each events.

Extends int to allow wrapping of any event id: ObjectId(0x1234), even if it is missing in the constant declared below.

ALERT = 0xFFFFFFF6

An alert associated with a window or an application.

CARET = 0xFFFFFFF8

The text insertion bar (caret) in the window.

CLIENT = 0xFFFFFFFC

The window’s client area.

CURSOR = 0xFFFFFFF7

The mouse pointer.

HSCROLL = 0xFFFFFFFA

The window’s horizontal scroll bar.

MENU = 0xFFFFFFFD

The window’s menu bar.

NATIVEOM = 0xFFFFFFF0

Third-party applications expose their object model.

QUERYCLASSNAMEIDX = 0xFFFFFFF4

Oleacc.dll uses this internally.

SIZEGRIP = 0xFFFFFFF9

The window’s size grip.

SOUND = 0xFFFFFFF5

A sound object.

SYSMENU = 0xFFFFFFFF

The window’s system menu.

TITLEBAR = 0xFFFFFFFE

The window’s title bar.

VSCROLL = 0xFFFFFFFB

The window’s vertical scroll bar.

WINDOW = 0x0

The window itself.

win32_window_monitor.get_hwnd_process_id(event_thread_id: DWORD, hwnd: HWND, log_error=True) → int | None

Returns the processId of the given window handle in the given thread, or None on error.

win32_window_monitor.get_process_filename(process_id: int, log_error=True) → str | None

Returns the full process path for the given process_id, or None on error.

win32_window_monitor.get_window_title(hwnd: HWND) → str

Returns the window title of the given window handle, or an empty string on error.

win32_window_monitor.init_com()
win32_window_monitor.post_quit_message(exit_code: int = 0)
win32_window_monitor.post_quit_message_on_break_signal()

Install signal handler to exit the application when CTRL+C or CTRL+Break is pressed.

Exiting the application is done by sending the WM_QUIT message (via post_quit_message), which causes the Windows message loop of run_message_loop() that receives it to exit.

This is a contextmanager for use with the with statement.

win32_window_monitor.run_message_loop()

Runs WIN32 message loop (user32.GetMessageW) until WM_QUIT is received.

win32_window_monitor.set_win_event_hook(on_event_func: Callable[[HANDLE, DWORD, HWND, LONG, LONG, DWORD, DWORD], None], event_type: int | HookEvent) → EventHookHandle

Set a global event hook for the given event_type.

Throws an OSError exception created by ctypes.WinError() on failure.

See https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-setwineventhook for detail.

IMPORTANT: the returned handle must remain alive while listening for events. ctypes dynamically generates a function which is registered to Windows and redirect to Python code. The life-time of this function is tied to the EventHookHandle. Failure to do that may cause a crash.

Uses the returned handle unhook() method to stop listening for the registered event.

Parameters:
Returns:

registered event hook handle, must remain alive while listening for events (see function description).