Basic wrapping of Windows controls

exception pywinauto.controls.hwndwrapper.ControlNotEnabled

Bases: RuntimeError

Raised when a control is not enabled

exception pywinauto.controls.hwndwrapper.ControlNotVisible

Bases: RuntimeError

Raised when a control is not visible

class pywinauto.controls.hwndwrapper.DialogWrapper(hwnd)

Bases: pywinauto.controls.hwndwrapper.HwndWrapper

Wrap a dialog

ClientAreaRect(*args, **kwargs)
HideFromTaskbar(*args, **kwargs)
IsInTaskbar(*args, **kwargs)
RunTests(*args, **kwargs)
ShowInTaskbar(*args, **kwargs)
WriteToXML(*args, **kwargs)
can_be_label = True

Return the client area rectangle

From MSDN: The client area of a control is the bounds of the control, minus the nonclient elements such as scroll bars, borders, title bars, and menus.


Close the dialog forcefully using WM_QUERYENDSESSION and return the result

Window has let us know that it doesn’t want to die - so we abort this means that the app is not hung - but knows it doesn’t want to close yet - e.g. it is asking the user if they want to save.

friendlyclassname = 'Dialog'

Hide the dialog from the Windows taskbar


Check whether the dialog is shown in the Windows taskbar

Thanks to David Heffernan for the idea: A window is represented in the taskbar if: It has no owner and it does not have the WS_EX_TOOLWINDOW extended style, or it has the WS_EX_APPWINDOW extended style.

run_tests(tests_to_run=None, ref_controls=None)

Run the tests on dialog


Show the dialog in the Windows taskbar


Write the dialog an XML file (requires elementtree)

class pywinauto.controls.hwndwrapper.HwndMeta(name, bases, attrs)

Bases: pywinauto.base_wrapper.BaseMeta

Metaclass for HwndWrapper objects

static find_wrapper(element)

Find the correct wrapper for this native element

class pywinauto.controls.hwndwrapper.HwndWrapper(element_info)

Bases: pywinauto.base_wrapper.BaseWrapper

Default wrapper for controls.

All other wrappers are derived from this.

This class wraps a lot of functionality of underlying windows API features for working with windows.

Most of the methods apply to every single window type. For example you can click() on any window.

Most of the methods of this class are simple wrappers around API calls and as such they try do the simplest thing possible.

An HwndWrapper object can be passed directly to a ctypes wrapped C function - and it will get converted to a Long with the value of it’s handle (see ctypes, _as_parameter_).


Return the .NET name of the control

click(button='left', pressed='', coords=(0, 0), double=False, absolute=False)

Simulates a mouse click on the control

This method sends WM_* messages to the control, to do a more ‘realistic’ mouse click use click_input() which uses mouse_event() API to perform the click.

This method does not require that the control be visible on the screen (i.e. it can be hidden beneath another window and it will still work).


Returns the client rectangle of window

The client rectangle is the window rectangle minus any borders that are not available to the control for drawing.

Both top and left are always 0 for this method.

This method returns a RECT structure, Which has attributes - top, left, right, bottom. and has methods width() and height(). See win32structures.RECT for more information.


Return the client rect for each item in this control

It is a list of rectangles for the control. It is frequently over-ridden to extract all rectangles from a control with multiple items.

It is always a list with one or more rectangles:

  • First elemtent is the client rectangle of the control
  • Subsequent elements contain the client rectangle of any items of the control (e.g. items in a listbox/combobox, tabs in a tabcontrol)

Close the window

Code modified from


Close the window by pressing Alt+F4 keys.

close_click(button='left', pressed='', coords=(0, 0), double=False)

Perform a click action that should make the window go away

The only difference from click is that there are extra delays before and after the click action.


Return the Context Help ID of the window


Return the .NET type of the control


Write some debug text over the window

double_click(button='left', pressed='', coords=(0, 0))

Perform a double click action

drag_mouse(button='left', press_coords=(0, 0), release_coords=(0, 0), pressed='')

Drag the mouse


Returns the Extended style of window

Return value is a long.

Combination of WS_* and specific control specific styles. See HwndWrapper.has_style() to easily check if the window has a particular style.


Return the font of the window

The font of the window is used to draw the text of that window. It is a structure which has attributes for font name, height, width etc.

See win32structures.LOGFONTW for more information.


Return the font for each item in this control

It is a list of fonts for the control. It is frequently over-ridden to extract all fonts from a control with multiple items.

It is always a list with one or more fonts:

  • First elemtent is the control font
  • Subsequent elements contain the font of any items of the control (e.g. items in a listbox/combobox, tabs in a tabcontrol)

Return the .NET type of the control (full, uncut)


Return a handle to the active window within the process


Return the control in the process of this window that has the Focus


Get the show state and Maximized/minimzed/restored state

Returns a value that is a union of the following

  • SW_HIDE the window is hidden.
  • SW_MAXIMIZE the window is maximized
  • SW_MINIMIZE the window is minimized
  • SW_RESTORE the window is in the ‘restored’ state (neither minimized or maximized)
  • SW_SHOW The window is not hidden

Get the first child toolbar if it exists

handle = None

Return True if the control has the specified extended style


Check the window is in focus (foreground)


Check the keyboard focus on this control.


Return True if the control has the specified style


Whether the window is active or not


Return true if the control is a top level window


Indicate whether the window is maximized or not


Indicate whether the window is minimized or not


Indicate whether the window is normal (i.e. not minimized and not maximized)


Whether the window is unicode or not

A window is Unicode if it was registered by the Wide char version of RegisterClass(Ex).


Maximize the window


Return the menu of the control

menu_item(path, exact=False)

Return the menu item specified by path

Path can be a string in the form “MenuItem->MenuItem->MenuItem...” where each MenuItem is the text of an item at that level of the menu. E.g.


spaces are not important so you could also have written...

File -> Export -> Export As PNG

Return the menu items for the dialog

If there are no menu items then return an empty list

menu_select(path, exact=False)

Find a menu item specified by the path

The full path syntax is specified in: controls.menuwrapper.Menu.get_menu_path()


Minimize the window

move_mouse(coords=(0, 0), pressed='', absolute=False)

Move the mouse by WM_MOUSEMOVE

move_window(x=None, y=None, width=None, height=None, repaint=True)

Move the window to the new coordinates

  • x Specifies the new left position of the window. Defaults to the current left position of the window.
  • y Specifies the new top position of the window. Defaults to the current top position of the window.
  • width Specifies the new width of the window. Defaults to the current width of the window.
  • height Specifies the new height of the window. Default to the current height of the window.
  • repaint Whether the window should be repainted or not. Defaults to True
notify_parent(message, controlID=None)

Send the notification message to parent of this control


Return the owner window for the window if it exists

Returns None if there is no owner.


Return owned enabled Popup window wrapper if shown.

If there is no enabled popups at that time, it returns self. See MSDN reference:

Please do not use in production code yet - not tested fully

post_message(message, wparam=0, lparam=0)

Post a message to the control message queue and return

press_mouse(button='left', coords=(0, 0), pressed='')

Press the mouse button

release_mouse(button='left', coords=(0, 0), pressed='')

Release the mouse button


Restore the window to its previous state (normal or maximized)

right_click(pressed='', coords=(0, 0))

Perform a right click action

scroll(direction, amount, count=1, retry_interval=None)

Ask the control to scroll itself

direction can be any of “up”, “down”, “left”, “right” amount can be one of “line”, “page”, “end” count (optional) the number of times to scroll

send_chars(chars, with_spaces=True, with_tabs=True, with_newlines=True)

Silently send a character string to the control in an inactive window

If a virtual key with no corresponding character is encountered (e.g. VK_LEFT, VK_DELETE), a KeySequenceError is raised. Consider using the method send_keystrokes for such input.

send_keystrokes(keystrokes, with_spaces=True, with_tabs=True, with_newlines=True)

Silently send keystrokes to the control in an inactive window

It parses modifiers Shift(+), Control(^), Menu(%) and Sequences like “{TAB}”, “{ENTER}” For more information about Sequences and Modifiers navigate to module keyboard

Due to the fact that each application handles input differently and this method is meant to be used on inactive windows, it may work only partially depending on the target app. If the window being inactive is not essential, use the robust type_keys method.

send_message(message, wparam=0, lparam=0)

Send a message to the control and wait for it to return

send_message_timeout(message, wparam=0, lparam=0, timeout=None, timeoutflags=<MagicMock name='mock.win32defines.SMTO_NORMAL' id='140124679165712'>)

Send a message to the control and wait for it to return or to timeout

If no timeout is given then a default timeout of .01 of a second will be used.


Application data is data from a previous run of the software

It is essential for running scripts written for one spoke language on a different spoken language


Set the focus to this control.

Bring the window to the foreground first. The system restricts which processes can set the foreground window ( so the mouse cursor is removed from the screen to prevent any side effects.


Set the keyboard focus to this control.


Set the window transparency from 0 to 255 by alpha attribute

set_window_text(text, append=False)

Set the text of the window


Returns the style of window

Return value is a long.

Combination of WS_* and specific control specific styles. See HwndWrapper.has_style() to easily check if the window has a particular style.


Extra data associted with the window

This value is a long value that has been associated with the window and rarely has useful data (or at least data that you know the use of).


Backend specific function to wait for idle state of a thread or a window


Extend default properties list.

exception pywinauto.controls.hwndwrapper.InvalidWindowHandle(hwnd)

Bases: RuntimeError

Raised when an invalid handle is passed to HwndWrapper


Get the properties of all the controls as a list of dictionaries