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

class systa.windows.classname_search(search, case_sensitive=True)¶

Search windows with a classname.

Parameters

search (str | Pattern) –
The classname to look for. Can be one of:
- str: Interpreted as an fnmatch() style wildcard lookup.
- re.pattern: A regex match against window classname.
case_sensitive (bool) – Whether the match has to be case sensitive or not. Defaults to True.

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 or a Point 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.

See Microsoft’s docs for more info about window class names.

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.

get_monitor(number)¶

Get the specified monitor.

This method only gets monitors that this window is on.

To get any monitor regardless if you have an instance of a window on it, see systa.monitors.get_monitor().

Returns: None if the monitor does not exist or the window is not on it.
Parameters: number (int) –
Return type: Optional[systa.backend.monitors.SystaMonitor]

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.

send_to_monitor(number)¶

Moves window to the specified monitor.

Window is sized to fill whole monitor.

Returns: True if move successful, False if not.
Parameters: number (int) –
Return type: bool

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.idleness(seconds, call_count_limit=1)¶

System has been idle for so many seconds.

Parameters

seconds (float) – Number of seconds to consider system idle. Maximum resolution of systa.events.store.Store.msg_loop_timeout
call_count_limit (int) – How many times to call the function after idle time has been reached. The event loop runs every systa.events.store.Store.msg_loop_timeout milliseconds. If we didn’t have this parameter every time the event loop ran and the user was still idle, the user’s function would be called over and over again.

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

See also

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.

See also

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.idle_time_gte(seconds)¶

System has been idle for at least X seconds.

Parameters: seconds (float) – Minimum number of seconds we require system to be idle for.

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(width=None, height=None, area=None)¶

Include only windows of width, height dimensions or area less than provided.

If area is provided, width and height 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.
width (Optional[int]) – Width
height (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.sanity(return_val, output=None)¶

A filter for testing stuff!

Parameters

return_val (bool) – This value will be returned when the filter is evaluated.
output (Optional[str]) – If provided, this value will be printed each time the filter is evaluated.

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=None, event_info=None, context=<factory>)¶

The data structure returned to the user’s function.

Parameters

window (Optional[systa.windows.Window]) – A systa.windows.Window instance associated with the event.
event_info (Optional[systa.events.types.CallbackReturn]) – The raw data provided to us by Windows when the event fired.
context (Optional[Dict[Any, Any]]) – A general purpose dict for transferring info between users of this data.

Return type

None

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]]

Other types¶

class systa.types.Point(x, y)¶

Represents an X, Y coordinate.

Parameters

x (int) –
y (int) –

Return type

None

__iter__()¶

You can iterate across a Point.

This allows you to to unpack a point into a function call that takes an x and a y.

class systa.types.Rect(origin: systa.types.Point, end: systa.types.Point)¶

Parameters

origin (systa.types.Point) –
end (systa.types.Point) –

Return type

None

__iter__()¶

You can iterate across a Rect.

This allows you to to unpack a point into a function call that takes an x1, y1, x2, y2.

above_rect(rect)¶

Is the provided rectangle above this Rect?

The edges cannot overlap.

Parameters: rect (systa.types.Rect) – The rectangle you want to compare to.
Return type: bool

property area¶: Area of rectangle.

below_rect(rect)¶

Is the provided rectangle below this Rect?

The edges cannot overlap.

Parameters: rect (systa.types.Rect) – The rectangle you want to compare to.
Return type: bool

property bottom_edge¶: Bottom edge of rectangle.

contains_point(point)¶

Does the rectangle contain the provided Point?

A Point on the edge of a rectangle is considered contained in that rectangle.

>>> from systa.types import Point, Rect
>>> r = Rect.from_coords(0, 0, 10, 10)
>>> r.contains_point(Point(0, 1))
True
>>> r.contains_point(Point(20, 11))
False

Parameters: point (systa.types.Point) –
Return type: bool

contains_rect(rect)¶

Does the rectangle contain the provided Rect?

The provided Rect has to be completely within this rectangle to be considered contained.

A Rect with an edge on the edge of this rectangle is considered contained in that rectangle.

>>> from systa.types import Point, Rect
>>> r = Rect.from_coords(0, 0, 10, 10)
>>> r.contains_rect(Rect.from_coords(0, 0, 5, 5))
True
>>> r.contains_rect(Rect.from_coords(0, 0, 11, 10))
False

Parameters: rect (systa.types.Rect) – The rectangle you want to compare to.
Return type: bool

static from_coords(x1, y1, x2, y2)¶

Create an instance with the provided dimensions.

>>> from systa.types import Rect
>>> Rect.from_coords(0, 0, 10, 10)
Rect(origin=Point(x=0, y=0), end=Point(x=10, y=10))

Parameters

x1 (int) – Top left x value.
y1 (int) – Top left y value.
x2 (int) – Bottom right x value.
y2 (int) – Bottom right y value.

Return type

systa.types.Rect

property half_height¶

Get tuple splitting width in have.

Returns a two-tuple such that each element represents a coordinate on top/bottom off horizontal center line. Handles even and odd widths.

See also

split_value()

property half_width¶

Get tuple splitting width in have.

Returns a two-tuple such that each element represents a coordinate on left/right off vertical center line. Handles even and odd widths.

See also

split_value()

property height¶: Height of rectangle.

intersection_rect(rect)¶

Representing the area of overlap between the provided rect and this retangle.

Second rectangle overlaps from bottom right:

>>> rect_a = Rect(Point(0, 0), Point(10, 10))
>>> rect_b = Rect(Point(1, 1), Point(11, 11))
>>> rect_a.intersection_rect(rect_b)
Rect(origin=Point(x=1, y=1), end=Point(x=10, y=10))

First rectangle complete contains second rectangle:

>>> rect_b = Rect(Point(2, 2), Point(5, 5))
>>> rect_a.intersection_rect(rect_b) == rect_b
True

Second rectangle overlaps from top left.

>>> rect_b = Rect(Point(-1, -1), Point(5, 5))
>>> rect_a.intersection_rect(rect_b)
Rect(origin=Point(x=0, y=0), end=Point(x=5, y=5))

Second rectangle same as first rectangle.

>>> rect_b = Rect(Point(0, 0), Point(10, 10))
>>> rect_a.intersection_rect(rect_b) == rect_a == rect_b
True

Parameters: rect (systa.types.Rect) – Get intersection with this rect.
Return type: systa.types.Rect

intersects_rect(rect)¶

Does the provided rectangle intersect our rectangle in any way?

Parameters: rect (systa.types.Rect) – The rectangle you want to compare to.
Return type: bool

property left_edge¶: Left edge of rectangle.

left_of_rect(rect)¶

Is the provided rectangle to the left of this Rect?

The edges cannot overlap.

Parameters: rect (systa.types.Rect) – The rectangle you want to compare to.
Return type: bool

property left_rect¶

Get a Rect encompassing the left half of this instance.

>>> from systa.types import Point, Rect
>>> Rect(origin=Point(0, 0), end=Point(10, 10)).left_rect
Rect(origin=Point(x=0, y=0), end=Point(x=5, y=10))

property lower_rect¶

Get a Rect encompassing the bottom half of this instance.

>>> from systa.types import Point, Rect
>>> Rect(origin=Point(0, 0), end=Point(10, 10)).lower_rect
Rect(origin=Point(x=0, y=6), end=Point(x=10, y=10))

number_pixels_overlapped_by(rect)¶

Pixels of overlap between this rect and the other rect.

>>> rect_a = Rect(Point(0, 0), Point(10, 10))
>>> rect_b = Rect(Point(1, 1), Point(11, 11))
>>> rect_a.number_pixels_overlapped_by(rect_b)
81

Parameters: rect (systa.types.Rect) – Rect you want to compare this rect to.
Return type: int

property right_edge¶: Right edge of rectangle.

right_of_rect(rect)¶

Is the provided rectangle to the right of this Rect?

The edges cannot overlap.

Parameters: rect (systa.types.Rect) – The rectangle you want to compare to.
Return type: bool

property right_rect¶

Get a Rect encompassing the right half of this instance.

>>> from systa.types import Point, Rect
>>> Rect(origin=Point(0, 0), end=Point(10, 10)).right_rect
Rect(origin=Point(x=6, y=0), end=Point(x=10, y=10))

classmethod split_value(val)¶

Splits a value into two, returning a tuple of (floor, ceil).

The goal is that the values do not overlap so that, for example, when you split the number 10, you get (5, 6) not (5, 5)

>>> Rect.split_value(10)
(5, 6)
>>> Rect.split_value(11)
(5, 6)

Parameters: val (int) –
Returns
Return type: Tuple[int, int]

property top_edge¶: Top edge of rectangle.

property upper_rect¶

Get a Rect encompassing the top half of this instance.

>>> from systa.types import Point, Rect
>>> Rect(origin=Point(0, 0), end=Point(10, 10)).upper_rect
Rect(origin=Point(x=0, y=0), end=Point(x=10, y=5))

property width¶: Width of rectangle.

Helpers¶

class systa.backend.monitors.SystaMonitor(x, y, width, height, width_mm=None, height_mm=None, name=None, work_area=None)¶

Info about a monitor.

Lifted and modified from screeninfo.

Parameters

x (int) –
y (int) –
width (int) –
height (int) –
width_mm (Optional[int]) –
height_mm (Optional[int]) –
name (Optional[str]) –
work_area (Optional[systa.types.Rect]) –

Return type

None

work_area: Optional[systa.types.Rect] = None¶: This should be the desktop coordinates excluding the taskbar.

systa.backend.monitors.enumerate_monitors()¶

Get all the monitors on the system.

Slightly modified from screeninfo to return work area.

Return type: Iterator[systa.backend.monitors.SystaMonitor]

systa.backend.monitors.get_monitor(number)¶

Helper function to get a specific monitor by its number.

Parameters: number (int) –
Return type: Optional[systa.backend.monitors.SystaMonitor]

systa.utils.composed(*decs)¶

Combine multiple decorators into one.

from systa.utils import composed
from systa.events import listen_to

our_listener = composed(listen_to.destroy, listen_to.restore, listen_to.location_change)

@our_listener
def our_func(data: EventData):
    ...

Releases

Dev Releases

Changelog

The API¶

Finding windows¶

Controlling windows¶

Events¶

`listen_to` decorators¶

`filter_by` decorators¶

Event types¶

Other types¶

Helpers¶

Releases

Dev Releases

Changelog

The API¶

Finding windows¶

Controlling windows¶

Events¶

listen_to decorators¶

filter_by decorators¶

Event types¶

Other types¶

Helpers¶

`listen_to` decorators¶

`filter_by` decorators¶