pywinauto.controls.hwndwrapper

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

pywinauto.controls.hwndwrapper.GetDialogPropsFromHandle(hwnd)

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

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_).

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).

client_rect()

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.

client_rects()

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(wait_time=0)

Close the window

Code modified from http://msdn.microsoft.com/msdnmag/issues/02/08/CQA/

close_alt_f4()

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.

context_help_id()

Return the Context Help ID of the window

debug_message(text)

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

exstyle()

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.

font()

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.

fonts()

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)
get_active()

Return a handle to the active window within the process

get_focus()

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

get_show_state()

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_toolbar()

Get the first child toolbar if it exists

handle = None
has_exstyle(exstyle)

Return True if the control has the specified extended style

has_keyboard_focus()

Check the keyboard focus on this control.

has_style(style)

Return True if the control has the specified style

is_active()

Whether the window is active or not

is_dialog()

Return true if the control is a top level window

is_maximized()

Indicate whether the window is maximized or not

is_minimized()

Indicate whether the window is minimized or not

is_normal()

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

is_unicode()

Whether the window is unicode or not

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

maximize()

Maximize the window

menu()

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.

File->Export->ExportAsPNG

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

File -> Export -> Export As PNG
menu_items()

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()

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

owner()

Return the owner window for the window if it exists

Returns None if there is no owner

popup_window()

Return owned enabled Popup window wrapper if shown.

If there is no enabled popups at that time, it returns self. See MSDN reference: https://msdn.microsoft.com/en-us/library/windows/desktop/ms633515.aspx

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

post_command(commandID)
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()

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(message, with_spaces=True, with_tabs=True, with_newlines=True)

Silently send a string to the control

Parses modifiers Shift(+), Control(^), Menu(%) and Sequences like “{TAB}”, “{Enter}” For more information about Sequences and Modifiers navigate to keyboard.py

send_command(commandID)
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='140631365225328'>)

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.

set_application_data(appdata)

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_focus()

Set the focus to this control.

Bring the window to the foreground first if necessary. The system restricts which processes can set the foreground window (https://msdn.microsoft.com/en-us/library/windows/desktop/ms633539(v=vs.85).aspx) so the mouse cursor is removed from the screen to prevent any side effects.

set_keyboard_focus()

Set the keyboard focus to this control.

set_transparency(alpha=120)

Set the window transparency from 0 to 255 by alpha attribute

set_window_text(text, append=False)

Set the text of the window

style()

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.

user_data()

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).

wait_for_idle()

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

writable_props

Extend default properties list.

exception pywinauto.controls.hwndwrapper.InvalidWindowHandle(hwnd)

Bases: RuntimeError

Raised when an invalid handle is passed to HwndWrapper

pywinauto.controls.hwndwrapper.get_dialog_props_from_handle(hwnd)

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