pywinauto.controls.HwndWrapper

Basic wrapping of Windows controls

exception pywinauto.controls.HwndWrapper.ControlNotEnabled

Bases: exceptions.RuntimeError

Raised when a control is not enabled

exception pywinauto.controls.HwndWrapper.ControlNotVisible

Bases: exceptions.RuntimeError

Raised when a control is nto visible

pywinauto.controls.HwndWrapper.GetDialogPropsFromHandle(hwnd)

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

class pywinauto.controls.HwndWrapper.HwndWrapper(hwnd)

Bases: object

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.

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

Initialize the control

  • hwnd is either a valid window handle or it can be an instance or subclass of HwndWrapper.

If the handle is not valid then an InvalidWindowHandle error is raised.

CaptureAsImage()

Return a PIL image of the control

See PIL documentation to know what you can do with the resulting image

Children()

Return the children of this control as a list

It returns a list of HwndWrapper (or subclass) instances, it returns an empty list if there are no children.

Class()

Return the class name of the window

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

Simulates a mouse click on the control

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

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

ClickInput(button='left', coords=(None, None), double=False, wheel_dist=0)

Click at the specified coordinates

  • button The mouse button to click. One of ‘left’, ‘right’, ‘middle’ or ‘x’ (Default: ‘left’)
  • coords The coordinates to click at.(Default: center of control)
  • double Whether to perform a double click or not (Default: False)
  • wheel_dist The distance to move the mouse week (default: 0)
NOTES:

This is different from Click in that it requires the control to be visible on the screen but performs a more realistic ‘click’ simulation.

This method is also vulnerable if the mouse if moved by the user as that could easily move the mouse off the control before the Click has finished.

ClientRect()

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.

ClientRects()

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

Close the window

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

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

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

ContextHelpID()

Return the Context Help ID of the window

ControlCount()

Return the number of children of this control

ControlID()

Return the ID of the window

Only controls have a valid ID - dialogs usually have no ID assigned.

The ID usually identified the control in the window - but there can be duplicate ID’s for example lables in a dialog may have duplicate ID’s.

DebugMessage(text)

Write some debug text over the window

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

Perform a double click action

DoubleClickInput(button='left', coords=(None, None))

Double click at the specified coordinates

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

Drag the mouse

DrawOutline(colour='green', thickness=2, fill=1, rect=None)

Draw an outline around the window

  • colour can be either an integer or one of ‘red’, ‘green’, ‘blue’ (default ‘green’)
  • thickness thickness of rectangle (default 2)
  • fill how to fill in the rectangle (default BS_NULL)
  • rect the coordinates of the rectangle to draw (defaults to the rectangle of the control.
ExStyle()

Returns the Extended style of window

Return value is a long.

Combination of WS_* and specific control specific styles. See HwndWrapper.HasStyle() 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)
FriendlyClassName()

Return the friendly class name for the control

This differs from the class of the control in some cases. Class() is the actual ‘Registered’ window class of the control while FriendlyClassName() is hopefully something that will make more sense to the user.

For example Checkboxes are implemented as Buttons - so the class of a CheckBox is “Button” - but the friendly class is “CheckBox”

GetFocus()

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

GetProperties()

Return the properties of the control as a dictionary

GetShowState()

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

Return True if the control has the specified extended sytle

HasStyle(style)

Return True if the control has the specified sytle

IsChild(parent)

Return True if this window is a child of ‘parent’.

A window is a child of another window when it is a direct of the other window. A window is a direct descendant of a given window if the parent window is the the chain of parent windows for the child window.

IsDialog()

Return true if the control is a top level window

IsEnabled()

Whether the window is enabled or not

Checks that both the Top Level Parent (probably dialog) that owns this window and the window itself are both enabled.

If you want to wait for a control to become enabled (or wait for it to become disabled) use Application.Wait('visible') or Application.WaitNot('visible').

If you want to raise an exception immediately if a window is not enabled then you can use the HwndWrapper.VerifyEnabled(). HwndWrapper.VerifyReady() raises if the window is not both visible and enabled.

IsUnicode()

Whether the window is unicode or not

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

IsVisible()

Whether the window is visible or not

Checks that both the Top Level Parent (probably dialog) that owns this window and the window itself are both visible.

If you want to wait for a control to become visible (or wait for it to become hidden) use Application.Wait('visible') or Application.WaitNot('visible').

If you want to raise an exception immediately if a window is not visible then you can use the HwndWrapper.VerifyVisible(). HwndWrapper.VerifyActionable() raises if the window is not both visible and enabled.

Maximize()

Maximize the window

Menu()

Return the menu of the control

MenuItem(path)

Return the menu item specifed 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
MenuItems()

Return the menu items for the dialog

If there are no menu items then return an empty list

MenuSelect(path)

Select the menuitem specifed in path

Minimize()

Minimize the window

MoveMouse(pressed='left', coords=(0, 0))

Move the mouse

MoveWindow(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
NotifyParent(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

Parent()

Return the parent of this control

Note that the parent of a control is not necesarily a dialog or other main window. A group box may be the parent of some radio buttons for example.

To get the main (or top level) window then use HwndWrapper.TopLevelParent().

PopupWindow()

Return any owned Popups

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

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

Post a message to the control message queue and return

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

Press the mouse button

PressMouseInput(button='left', coords=(None, None))

Press a mouse button using SendInput

ProcessID()

Return the ID of process that owns this window

Rectangle()

Return the rectangle of window

The rectangle is the rectangle of the control on the screen, coordinates are given from the top left of the screen.

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.

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

Release the mouse button

ReleaseMouseInput(button='left', coords=(None, None))

Release the mouse button

Restore()

Restore the window

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

Perform a right click action

RightClickInput(coords=(None, None))

Right click at the specified coords

Scroll(direction, amount, count=1)

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

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

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

SendMessageTimeout(message, wparam=0, lparam=0, timeout=None, timeoutflags=0)

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 .4 of a second will be used.

SetApplicationData(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 langauge

SetFocus()

Set the focus to this control

Bring the window to the foreground first if necessary.

SetWindowText(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.HasStyle() to easily check if the window has a particular style.

Texts()

Return the text for each item of this control”

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

It is always a list with one or more strings:

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

Return the top level window of this control

The TopLevel parent is different from the parent in that the Parent is the window that owns this window - but it may not be a dialog/main window. For example most Comboboxes have an Edit. The ComboBox is the parent of the Edit control.

This will always return a valid window handle (if the control has no top level parent then the control itself is returned - as it is a top level window already!)

TypeKeys(keys, pause=None, with_spaces=False, with_tabs=False, with_newlines=False, turn_off_numlock=True)

Type keys to the window using SendKeys

This uses the SendKeys python module from http://www.rutherfurd.net/python/sendkeys/ .This is the best place to find documentation on what to use for the keys

UserData()

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

VerifyActionable()

Verify that the control is both visible and enabled

Raise either ControlNotEnalbed or ControlNotVisible if not enabled or visible respectively.

VerifyEnabled()

Verify that the control is enabled

Check first if the control’s parent is enabled (skip if no parent), then check if control itself is enabled.

VerifyVisible()

Verify that the control is visible

Check first if the control’s parent is visible. (skip if no parent), then check if control itself is visible.

WindowText()

Window text of the control

Quite a few contorls have other text that is visible, for example Edit controls usually have an empty string for WindowText but still have text displayed in the edit window.

can_be_label = False
friendlyclassname = None
handle = None
has_title = True
windowclasses = []
exception pywinauto.controls.HwndWrapper.InvalidWindowHandle(hwnd)

Bases: exceptions.RuntimeError

Raised when an invalid handle is passed to HwndWrapper

Initialise the RuntimError parent with the mesage

Previous topic

pywinauto.controls.common_controls

Next topic

pywinauto.controls.menuwrapper

This Page