The API¶

Here we document all of the useful parts of the API.

Finding windows¶

See Finding Windows for a guide.

systa.windows.current_windows = <systa.windows.CurrentWindows object>¶

A representation of all windows on the system.

An instance of CurrentWindows.

Warning

Prefer this over your own instantiation of CurrentWindows.

class systa.windows.CurrentWindows¶

Represent all windows on a system as a dict-like object.

Behaves similar to collections.defaultdict with a list default factory. This means that if there are no matching windows, you’ll get an empty list. Otherwise you’ll get a list of at least one Window instance.

__contains__(item)¶

Membership checks with WindowLookupType.

Using exact title:

>>> from systa.windows import current_windows
>>> "Untitled - Notepad" in current_windows
True

Using Window instance:

>>> from systa.windows import Window
>>> np = Window("Untitled - Notepad")
>>> np in current_windows
True

Using handle:

>>> np.handle in current_windows
True

Using search predicate:

>>> from systa.windows import regex_search
>>> regex_search(".* - Notepad") in current_windows
True

Param: The window lookup you want to use.
Parameters: item (systa.windows.WindowLookupType) –
Return type: bool

__getitem__(item)¶

Get a Window.

See __contains__() for the types of values you can use to look up windows.

>>> from systa.windows import current_windows
>>> current_windows['Untitled - Notepad']
[Window(handle=..., title="Untitled - Notepad")]

>>> from systa.windows import regex_search
>>> current_windows[regex_search(".* - Notepad")]
[Window(handle=..., title="Untitled - Notepad")]

Param: The window lookup you want to use.
Parameters: item (systa.windows.WindowLookupType) –
Return type: List[systa.windows.Window]

property current_handles¶: A dictionary mapping window handles to their corresponding Window

property current_titles¶: A dictionary mapping title to lists of windows having that title.

property current_windows¶: Iterates over all current windows.

classmethod minimize_all()¶: Minimizes all windows.

class systa.windows.WindowSearchPredicate¶

Inherit from this class to make custom window searching logic.

At the minimum, you just inherit and override the predicate method with your custom logic.

abstract predicate(window)¶

Do logic on the window object to determine if we want to match it.

Parameters: window (systa.windows.Window) – The Window we’re checking.
Returns: True if the window matches, False if does not.
Return type: bool

systa.windows.WindowLookupType¶

The types you can use to lookup windows.

Type	Match method
`Window`	Compares handle to current windows handles
`str`	Wildcard-accepting title match.
`int`	Window with handle exists.
`WindowSearchPredicate`	Matches windows with the logic of the predicate.
`systa.windows.ACTIVE_WINDOW`	Matches the active window.

alias of Union[systa.windows.Window, str, int, systa.windows.WindowSearchPredicate, systa.windows.WindowActiveness]

class systa.windows.regex_search(pattern)¶

Search windows with a regex. Provide a string or a compiled regex.

Parameters: pattern (Union[Pattern, str]) –
Return type: None

Controlling windows¶

class systa.windows.Window(ref, title=None)¶

The main class for getting info from and manipulating windows.

Each window can be represented by this class. Note that, just because you have an instance of this class does not mean the window still exists! You can use the exists property to determine if the window is still around.

Parameters

ref (WindowLookupType) – The handle to the window. This is the one source of truth linking this object to a real window.
title (Optional[str]) –
If you know the current title at time of creating this object, pass it in so we don’t do time-consuming queries to get the window title later.

Note

Generally you can ignore this parameter. It’s mostly useful when doing batch operations with dozens of windows.

Return type

None

__eq__(other)¶

Window equality is determined by the window’s handle.

Parameters: other (systa.windows.Window) –

property absolute_center_coords¶

The absolute coordinates of the center of the window.

Set to a (x, y) tuple to center window at the provided coords.

property active¶

Reports and controls if the window is active.

If True, the window is active and if False, the window is not active.

Setting to False deactivates the window by activating the desktop “window”. Of course, setting to True activates the window.

bring_mouse_to(win_x=None, win_y=None)¶

Moves mouse into window area. Does not activate window.

Parameters

win_x (Optional[int]) – Specify the X position for the mouse. If not provided, centers the mouse on the X-axis of the window.
win_y (Optional[int]) – Specify the Y position for the mouse. If not provided, centers the mouse on the Y-axis of the window.

bring_to_mouse(center=False)¶

Bring window to mouse’s position.

Parameters: center (bool) – If True, then move so that center of window is at mouse’s position, otherwise it’s the top left corner. Defaults to False.
Return type: None

property classname¶: Classname of the window.

property enabled¶

Reports and controls if the window is enabled.

If set to True, the window can accept user input. If set to False the window will not accept user input.

property exists¶

Reports and controls if the window exists.

There is no real-time, live correspondence between a Window object and a real Microsoft Windows window. If you want to check if the window still exists, this will tell you.

Because we’re crazy you can also set this to False to close a window.

Setting to True has no effect.

flash(times=4, interval=750, flags=15)¶

Flashes a window to get your attention.

Parameters

times (int) – The number of times to flash. Defaults to 4.
interval (int) – The flash rate in milliseconds. Defaults to 750ms

flags (int) –

One or more of the win32con.FLASHW_* flags. Combine with the | operator. Defaults to win32con.FLASHW_ALL | win32con.FLASHW_TIMERNOFG.

Constant	Meaning
`FLASHW_ALL`	Flash both the window caption and taskbar button. This is equivalent to setting the FLASHW_CAPTION \| FLASHW_TRAY flags.
`FLASHW_CAPTION`	Flash the window caption.
`FLASHW_STOP`	Stop flashing. The system restores the window to its original state.
`FLASHW_TIMER`	Flash continuously, until the FLASHW_STOP flag is set.
`FLASHW_TIMERNOFG`	Flash continuously until the window comes to the foreground.
`FLASHW_TRAY`	Flash the taskbar button.

property height¶: Reports and controls the window’s height in pixels.

property maximized¶

Reports and controls if the window is maximized.

If set to True, the window is maximized. If set to False, the window is restored.

property minimized¶

Reports and controls if the window is minimized.

IF set to True, the window is minimized. If set to False, the window is restored.

property mouse¶: Returns a modified WindowRelativeMouseController that operates relative to the windows coordinates.

property pid¶: Alias for process_id.

property position¶

Reports and controls the windows origin coordinate X, Y position.

If set to a tuple containing two ints or a Point, the window is instantaneously moved to those coordinates.

If set to a Rect, the window is moved and sized accordingly.

property process_id¶: Return the PID of the window’s process.

property process_path¶: Full path to the process that this window belongs to.

property relative_center_coords¶

The coordinates of the window’s center.

This is relative to the window’s origin point.

property title¶

The title of the window.

Note that, unlike most other window attributes, we cache the title to save time-consuming requests for the title.

Just re-instantiate if you want to see if title has changed.

Check for window title change:

>>> from systa.windows import current_windows, Window
>>> old_instance = Window(123456)
>>> new_instance = Window(old_instance.handle)

Or we can do it this way:

>>> new_instance = current_windows[old_instance]

We do this because during bulk operations like getting all windows, we often also already have the title. When we’re doing operations on large collections of this class it’s very time consuming to constantly be re-retrieving the title, and since the title does not often change, and it is commonly used, it seems best to just cache it.

property visible¶

Reports and controls if the window is visible.

If set to True sets the window to be visible. If set to False sets the window to be hidden.

Warning

This concept of visibility does not have to do with the window being covered by other windows. See here for more info.

static wait_for_window(lookup, max_wait=5)¶

Waits for a lookup to return a window.

Parameters

lookup (WindowLookupType) – The lookup to use to find a window.
max_wait (float) – Wait for up to this many seconds.

Returns

The Window for the lookup.

Raises

ValueError – If the window is not found within max_wait seconds.

property width¶: Reports and controls the windows width in pixels.

class systa.windows.WindowRelativeMouseController(window)¶

A version of pynput.mouse.Controller operating relative to window.

See the pynput docs for more information. The only difference is that moves and positioning are relative to the Window provided.

Parameters: window (Window) – The Window we’re operating relative to.

Events¶

The user’s function will be called with one argument whose value is an instance of the EventData dataclass().

`listen_to` decorators¶

systa.events.decorators.listen_to.any_event(func)¶

Any event.

Note

Generally, you’ll want to save system resources and use a more discerning set of events.

Parameters: func (Callable[[systa.events.types.EventData], None]) –

systa.events.decorators.listen_to.capture_mouse(func)¶

A window has captured the mouse.

Basically, this happens when you click in a window.

See also

lost_mouse_capture()

Parameters: func (Callable[[systa.events.types.EventData], None]) –

systa.events.decorators.listen_to.create(func)¶

A window has been created.

Ok, I lied, it’s when all sorts of objects, including windows have been created.

See also

destroy(), existence_change()

Parameters: func (Callable[[systa.events.types.EventData], None]) –

systa.events.decorators.listen_to.destroy(func)¶

A window has been closed.

Ok, another lie. It could be other types of objects…not just windows.

See also

create(), existence_change()

Parameters: func (Callable[[systa.events.types.EventData], None]) –

systa.events.decorators.listen_to.existence_change(func)¶

A window has been created or destroyed.

Ok, I should stop so many lies. You won’t be surprised to hear that we’re not just talking about windows…

See also

create(), destroy()

Parameters: func (Callable[[systa.events.types.EventData], None]) –

systa.events.decorators.listen_to.location_change(func)¶

An object has changed location, shape, or size.

Parameters: func (Callable[[systa.events.types.EventData], None]) –

systa.events.decorators.listen_to.lost_mouse_capture(func)¶

A window has lost the mouse capture.

This is the window that lost mouse capture when you click somewhere else.

See also

capture_mouse()

Parameters: func (Callable[[systa.events.types.EventData], None]) –

systa.events.decorators.listen_to.maximize(func)¶

There isn’t a maximize event! Wrapper of location_change().

Best we can do is listen to location_change() and then check the window state with Window.maximized. It’s up to the user to check the maximized state with filter_by.is_maximized() or manually with the provided Window object.

Parameters: func (Callable[[systa.events.types.EventData], None]) –

systa.events.decorators.listen_to.minimize(func)¶

Window was minimized

… seealso:: restore()

Parameters: func (Callable[[systa.events.types.EventData], None]) –

systa.events.decorators.listen_to.move_or_sizing_ended(func)¶

A window has been resized.

See also

move_or_sizing_started()

Parameters: func (Callable[[systa.events.types.EventData], None]) –

systa.events.decorators.listen_to.move_or_sizing_started(func)¶

A window is getting resized.

See also

move_or_sizing_ended()

Parameters: func (Callable[[systa.events.types.EventData], None]) –

systa.events.decorators.listen_to.restore(func)¶

Window was restored from minimization.

… seealso:: minimize()

Parameters: func (Callable[[systa.events.types.EventData], None]) –

class systa.events.decorators.listen_to.specified_events(events)¶

Decorator to register a function to listen to the specified events.

Parameters: events (EventsTypes) – The event(s) to listen to.
Return type: None

`filter_by` decorators¶

class systa.events.decorators.filter_by.EventTesterBase¶

By subclassing this your event tests get registered.

For most use cases you can just use the make_filter() decorator instead of subclassing this class.

systa.events.decorators.filter_by.all_filters(*filters)¶

Given a list of filters, pass if all of them pass

Parameters: filters (Callable[[systa.events.types.EventData], bool]) – Provide all the filters you want to check the event with.

systa.events.decorators.filter_by.any_filter(*filters)¶

Given a list of filters, pass if any of them pass.

Parameters: filters (Callable[[systa.events.types.EventData], bool]) – Provide all the filters you want to check the event with.

systa.events.decorators.filter_by.apply_filter(f, data)¶

Use a filter as a simple boolean test function.

If you want to use one of the filters in the filter_by module as a simple boolean test of a EventData object, you can use this function.

>>>
>> apply_filter(require_size_is_less_than, your_data_object)
True

Parameters

f (Callable[[systa.events.types.EventData], bool]) –
data (systa.events.types.EventData) –

systa.events.decorators.filter_by.exclude_system_windows(data)¶

Filters out common, probably uninteresting window titles.

There’s a lot of windows like “OleMainThreadWndName” or “Default IME” that you likely you don’t care about. Use this filter to exclude them.

Parameters: data (systa.events.types.EventData) –

systa.events.decorators.filter_by.exclude_window_events(window_events)¶

Given a list of title/event pairs, excludes those events from those windows.

Parameters: window_events (Iterable[Tuple[str, Literal[Literal[40960], Literal[45055], Literal[1], Literal[2147483647], Literal[32786], Literal[32791], Literal[32789], Literal[32768], Literal[32785], Literal[32781], Literal[32769], Literal[32801], Literal[32802], Literal[32803], Literal[32804], Literal[32805], Literal[32806], Literal[33023], Literal[32773], Literal[32784], Literal[32771], Literal[32800], Literal[32808], Literal[32807], Literal[32809], Literal[32787], Literal[32793], Literal[32779], Literal[32780], Literal[32783], Literal[32772], Literal[32774], Literal[32775], Literal[32776], Literal[32777], Literal[32770], Literal[32778], Literal[32816], Literal[32788], Literal[32792], Literal[32782], Literal[257], Literal[511], Literal[2], Literal[32790], Literal[9], Literal[8], Literal[13], Literal[12], Literal[32], Literal[17], Literal[16], Literal[15], Literal[14], Literal[255], Literal[3], Literal[7], Literal[6], Literal[5], Literal[4], Literal[23], Literal[22], Literal[11], Literal[10], Literal[19], Literal[18], Literal[1], Literal[21], Literal[20], Literal[19968], Literal[20223], Literal[29952], Literal[30207]]]]) –

systa.events.decorators.filter_by.is_maximized(data)¶

Filters out windows that are not maximized

Parameters: data (systa.events.types.EventData) –

systa.events.decorators.filter_by.make_filter(test_func=None, *, exclude_sys_windows=True, require_existing_window=True, capture_invalid_window_handle_error=True)¶

Decorator to make a function into a filter on an event’s data.

Using the default values for the arguments:

@make_filter
def some_func(data: eventData)

Changing argument values:

@make_filter(capture_invalid_window_handle_error=False)
def some_other_func(data: EventData):
    pass

Parameters

test_func – The decorated function.
exclude_sys_windows – If True, will use built-in heuristics to filter out events for windows used by Windows internally. Defaults to True.
require_existing_window – If True, will filter out events for windows that no longer exist. Note that this doesn’t guarantee that the window doesn’t disappear between the time your function starts and you want to do something with the window in your function. It does guarantees your function won’t get called if the window disappears between the time the event happens and Windows calls our code…which is what seems to be the most likely case. Defaults to True.
capture_invalid_window_handle_error – If a window disappears by the time you try to do something with it, we’ll automatically handle the error for you. Note that if you need to do some sort of cleanup action in your function, you want to set this option to False and handle the error yourself. Defaults to True..

Return type

Callable[[Callable[[systa.events.types.EventData], bool]], Callable[[systa.events.types.EventData], bool]]

systa.events.decorators.filter_by.require_origin_within(rect)¶

Require window’s origin (upper left corner) to be within rectangle.

Parameters: rect (systa.types.Rect) –

systa.events.decorators.filter_by.require_size_is_less_than(x=None, y=None, area=None)¶

Include only windows of x, y dimensions or area less than provided.

If area is provided, x and y are ignored and are not needed. You can just do:

@filter_by.require_size_is_less_than(area=250000)
def f(data: EventData):
    ...

Parameters

area (Optional[int]) – Total area in pixels.
x (Optional[int]) – Width
y (Optional[int]) – Height

systa.events.decorators.filter_by.require_title(title, case_sensitive=True)¶

Filters on window title.

Accepts wildcards in the style of Unix shell-style wildcards.

I.e. @filter_by.title("*Notepad") will match any window title that ends in “Notepad”.

Pattern	Meaning
`*`	matches everything
`?`	matches any single character
`[seq]`	matches any character in seq
`[!seq]`	matches any character not in seq

Parameters

title (str) – The title to match.
case_sensitive – If False will be case insensitive. Defaults to True

systa.events.decorators.filter_by.require_titled_window(data)¶

Filters out windows that do not have a title.

Parameters: data (systa.events.types.EventData) –

systa.events.decorators.filter_by.require_window(data)¶

Exclude events that do not have a window.

Most likely you won’t need this since the default make_filter() decorator already does this check, but this is provided for cases when not using that decorator.

Parameters: data (systa.events.types.EventData) –

systa.events.decorators.filter_by.touches_monitors(*monitor_numbers, exclusive=False)¶

Window touches at least all the provided monitors.

Parameters

exclusive (bool) – If True require window to be only on those monitors, otherwise window can be on other monitors in addition to monitor_numbers.
monitor_numbers (int) – Provide the number of each monitor you want to check.

Event types¶

class systa.events.types.EventData(window, event_info)¶

The data structure returned to the user’s function.

Parameters

window (Optional[systa.windows.Window]) –
event_info (systa.events.types.CallbackReturn) –

Return type

None

event_info: systa.events.types.CallbackReturn¶: The raw data provided to us by Windows when the event fired.

window: Optional[systa.windows.Window]¶: A systa.windows.Window instance associated with the event.

class systa.events.types.CallbackReturn(hook_handle, event, event_name, window_handle, object_id, child_id, thread, time_ms)¶

The data given to us by Windows when it calls our callback.

Parameters

hook_handle (int) –
event (systa.events.types.EventType) –
event_name (systa.events.types.EventTypeNamesType) –
window_handle (int) –
object_id (systa.events.types.ObjIdType) –
child_id (int) –
thread (int) –
time_ms (int) –

Return type

None

systa.events.types.EventType¶

Literal values used to select events.

alias of Literal[Literal[40960], Literal[45055], Literal[1], Literal[2147483647], Literal[32786], Literal[32791], Literal[32789], Literal[32768], Literal[32785], Literal[32781], Literal[32769], Literal[32801], Literal[32802], Literal[32803], Literal[32804], Literal[32805], Literal[32806], Literal[33023], Literal[32773], Literal[32784], Literal[32771], Literal[32800], Literal[32808], Literal[32807], Literal[32809], Literal[32787], Literal[32793], Literal[32779], Literal[32780], Literal[32783], Literal[32772], Literal[32774], Literal[32775], Literal[32776], Literal[32777], Literal[32770], Literal[32778], Literal[32816], Literal[32788], Literal[32792], Literal[32782], Literal[257], Literal[511], Literal[2], Literal[32790], Literal[9], Literal[8], Literal[13], Literal[12], Literal[32], Literal[17], Literal[16], Literal[15], Literal[14], Literal[255], Literal[3], Literal[7], Literal[6], Literal[5], Literal[4], Literal[23], Literal[22], Literal[11], Literal[10], Literal[19], Literal[18], Literal[1], Literal[21], Literal[20], Literal[19968], Literal[20223], Literal[29952], Literal[30207]]

systa.events.types.EventTypeNamesType¶

The central part of internal API.

This represents a generic version of type ‘origin’ with type arguments ‘params’. There are two kind of these aliases: user defined and special. The special ones are wrappers around builtin collections and ABCs in collections.abc. These must have ‘name’ always set. If ‘inst’ is False, then the alias can’t be instantiated, this is used by e.g. typing.List and typing.Dict.

alias of Literal[EVENT_OBJECT_ACCELERATORCHANGE, EVENT_OBJECT_CLOAKED, EVENT_OBJECT_CONTENTSCROLLED, EVENT_OBJECT_CREATE, EVENT_OBJECT_DEFACTIONCHANGE, EVENT_OBJECT_DESCRIPTIONCHANGE, EVENT_OBJECT_DESTROY, EVENT_OBJECT_DRAGSTART, EVENT_OBJECT_DRAGCANCEL, EVENT_OBJECT_DRAGCOMPLETE, EVENT_OBJECT_DRAGENTER, EVENT_OBJECT_DRAGLEAVE, EVENT_OBJECT_DRAGDROPPED, EVENT_OBJECT_END, EVENT_OBJECT_FOCUS, EVENT_OBJECT_HELPCHANGE, EVENT_OBJECT_HIDE, EVENT_OBJECT_HOSTEDOBJECTSINVALIDATED, EVENT_OBJECT_IME_HIDE, EVENT_OBJECT_IME_SHOW, EVENT_OBJECT_IME_CHANGE, EVENT_OBJECT_INVOKED, EVENT_OBJECT_LIVEREGIONCHANGED, EVENT_OBJECT_LOCATIONCHANGE, EVENT_OBJECT_NAMECHANGE, EVENT_OBJECT_PARENTCHANGE, EVENT_OBJECT_REORDER, EVENT_OBJECT_SELECTION, EVENT_OBJECT_SELECTIONADD, EVENT_OBJECT_SELECTIONREMOVE, EVENT_OBJECT_SELECTIONWITHIN, EVENT_OBJECT_SHOW, EVENT_OBJECT_STATECHANGE, EVENT_OBJECT_TEXTEDIT_CONVERSIONTARGETCHANGED, EVENT_OBJECT_TEXTSELECTIONCHANGED, EVENT_OBJECT_UNCLOAKED, EVENT_OBJECT_VALUECHANGE, EVENT_OEM_DEFINED_START, EVENT_OEM_DEFINED_END, EVENT_SYSTEM_ALERT, EVENT_SYSTEM_ARRANGMENTPREVIEW, EVENT_SYSTEM_CAPTUREEND, EVENT_SYSTEM_CAPTURESTART, EVENT_SYSTEM_CONTEXTHELPEND, EVENT_SYSTEM_CONTEXTHELPSTART, EVENT_SYSTEM_DESKTOPSWITCH, EVENT_SYSTEM_DIALOGEND, EVENT_SYSTEM_DIALOGSTART, EVENT_SYSTEM_DRAGDROPEND, EVENT_SYSTEM_DRAGDROPSTART, EVENT_SYSTEM_END, EVENT_SYSTEM_FOREGROUND, EVENT_SYSTEM_MENUPOPUPEND, EVENT_SYSTEM_MENUPOPUPSTART, EVENT_SYSTEM_MENUEND, EVENT_SYSTEM_MENUSTART, EVENT_SYSTEM_MINIMIZEEND, EVENT_SYSTEM_MINIMIZESTART, EVENT_SYSTEM_MOVESIZEEND, EVENT_SYSTEM_MOVESIZESTART, EVENT_SYSTEM_SCROLLINGEND, EVENT_SYSTEM_SCROLLINGSTART, EVENT_SYSTEM_SOUND, EVENT_SYSTEM_SWITCHEND, EVENT_SYSTEM_SWITCHSTART, EVENT_UIA_EVENTID_START, EVENT_UIA_EVENTID_END, EVENT_UIA_PROPID_START, EVENT_UIA_PROPID_END]

Releases

Dev Releases

Changelog

The API¶

Finding windows¶

Controlling windows¶

Events¶

`listen_to` decorators¶

`filter_by` decorators¶

Event types¶

Releases

Dev Releases

Changelog

The API¶

Finding windows¶

Controlling windows¶

Events¶

listen_to decorators¶

filter_by decorators¶

Event types¶

`listen_to` decorators¶

`filter_by` decorators¶