Window classes

Dragonfly’s Window classes are interfaces to the window control and placement APIs for the current platform. Currently the Windows, macOS and X11 (Linux) platforms are supported.

The FakeWindow class will be used on unsupported platforms.

Base Window class

class BaseWindow(id)

The base Window class for controlling and placing windows.

property classname

Read-only access to the window’s class name.

close()

Close the window (if possible).

property cls_name

Alias of classname.

property executable

Read-only access to the window’s executable.

classmethod get_all_windows()

Get a list of all windows.

get_containing_monitor()

Method to get the Monitor containing the window.

This checks which monitor contains the center of the window.

Returns:

containing monitor

Return type:

Monitor

classmethod get_foreground()

Get the foreground window.

classmethod get_matching_windows(executable=None, title=None)

Find windows with a matching executable or title.

Window searches are case-insensitive.

If neither parameter is be specified, then it is effectively the same as calling get_all_windows().

Parameters:

• executable (str) – – part of the filename of the application’s executable to which the target window belongs; not case sensitive.

• title (str) – – part of the title of the target window; not case sensitive.

Return type:

list

get_normalized_position()

Method to get the window’s normalized position.

This is useful when working with multiple monitors.

Returns:

normalized position

Return type:

Rectangle

get_position()

Method to get the window’s position as a Rectangle object.

Returns:

window position

Return type:

Rectangle

classmethod get_window(id)

Get a Window object given a window id.

Given the same id, this method will return the same object.

property handle

Protected access to handle attribute.

property id

Protected access to id attribute.

property is_maximized

Whether the window is currently maximized.

property is_minimized

Whether the window is currently minimized.

property is_visible

Whether the window is currently visible.

This may be indeterminable for some windows.

matches(context)

Whether the window matches the given context.

maximize()

Maximize the window (if possible).

minimize()

Minimize the window (if possible).

move(rectangle, animate=None)

Move the window, optionally animating its movement.

Parameters:

• rectangle (Rectangle) – new window position and size

• animate (str) – name of window mover

property name

Protected access to name attribute.

property pid

Read-only access to the window’s process ID.

This will be the PID of the window’s process, not any subprocess.

If the window has no associated process id, this will return None.

Returns:

pid

Return type:

int | None

restore()

Restore the window if it is minimized or maximized.

set_focus()

Set the window as the active window without raising it.

Note: this method will behave like set_foreground() in environments where this isn’t possible.

set_foreground()

Set the window as the foreground (active) window.

set_normalized_position(rectangle, monitor=None)

Method to get the window’s normalized position.

This is useful when working with multiple monitors.

Parameters:

• rectangle (Rectangle) – window position

• monitor (Monitor) – monitor to normalize to (default: the first one).

set_position(rectangle)

Method to set the window’s position using a Rectangle object.

Parameters:

rectangle (Rectangle) – window position

property title

Read-only access to the window’s title.

class FakeWindow(id)

Fake Window class used when no implementation is available.

close()

Close the window (if possible).

classmethod get_all_windows()

Get a list of all windows.

classmethod get_foreground()

Get the foreground window.

get_position()

Method to get the window’s position as a Rectangle object.

Returns:

window position

Return type:

Rectangle

property is_maximized

Whether the window is currently maximized.

property is_minimized

Whether the window is currently minimized.

property is_visible

Whether the window is currently visible.

This may be indeterminable for some windows.

maximize()

Maximize the window (if possible).

minimize()

Minimize the window (if possible).

restore()

Restore the window if it is minimized or maximized.

set_focus()

Set the window as the active window without raising it.

Note: this method will behave like set_foreground() in environments where this isn’t possible.

set_foreground()

Set the window as the foreground (active) window.

set_position(rectangle)

Method to set the window’s position using a Rectangle object.

Parameters:

rectangle (Rectangle) – window position

Window class for Windows

class Win32Window(handle)

The Window class is an interface to the Win32 window control and placement.

close()

Close the window (if possible).

classmethod get_all_windows()

Get a list of all windows.

classmethod get_foreground()

Get the foreground window.

classmethod get_matching_windows(executable=None, title=None)

Find windows with a matching executable or title.

Window searches are case-insensitive.

If neither parameter is be specified, then it is effectively the same as calling get_all_windows().

Parameters:

• executable (str) – – part of the filename of the application’s executable to which the target window belongs; not case sensitive.

• title (str) – – part of the title of the target window; not case sensitive.

Return type:

list

get_position()

Method to get the window’s position as a Rectangle object.

Returns:

window position

Return type:

Rectangle

property is_enabled

Shortcut to win32gui.IsWindowEnabled() function.

property is_maximized

Whether the window is currently maximized.

property is_minimized

Shortcut to win32gui.IsIconic() function.

property is_valid

Shortcut to win32gui.IsWindow() function.

property is_visible

Shortcut to win32gui.IsWindowVisible() function.

maximize()

Maximize the window (if possible).

minimize()

Minimize the window (if possible).

restore()

Restore the window if it is minimized or maximized.

set_focus()

Set the window as the active window without raising it.

Note: this method will behave like set_foreground() in environments where this isn’t possible.

set_foreground()

Set the window as the foreground (active) window.

set_position(rectangle)

Method to set the window’s position using a Rectangle object.

Parameters:

rectangle (Rectangle) – window position

Window class for X11

class X11Window(id)

The Window class is an interface to the window control and placement APIs for X11.

Window control methods such as close() will return True if successful.

This class requires the following external programs:

• wmctrl

• xdotool

• xprop

close()

Close the window (if possible).

property cls

Read-only access to the window’s class.

classmethod get_all_windows()

Get a list of all windows.

classmethod get_foreground()

Get the foreground window.

classmethod get_matching_windows(executable=None, title=None)

Find windows with a matching executable or title.

Window searches are case-insensitive.

If neither parameter is be specified, then it is effectively the same as calling get_all_windows().

Parameters:

• executable (str) – – part of the filename of the application’s executable to which the target window belongs; not case sensitive.

• title (str) – – part of the title of the target window; not case sensitive.

Return type:

list

get_position()

Method to get the window’s position as a Rectangle object.

Returns:

window position

Return type:

Rectangle

property is_focused

Whether the window has input focus.

This does not work for all window types (e.g. pop up menus).

Return type:

bool

property is_fullscreen

Whether the window is in fullscreen mode.

This does not work for all window types (e.g. pop up menus).

Return type:

bool

property is_maximized

Whether the window is currently maximized.

property is_minimized

Whether the window is currently minimized.

property is_visible

Whether the window is currently visible.

This may be indeterminable for some windows.

maximize()

Maximize the window (if possible).

minimize()

Minimize the window (if possible).

restore()

Restore the window if it is minimized or maximized.

property role

Read-only access to the window’s X11 role attribute.

Returns:

role

Return type:

str

set_focus()

Set the input focus to this window.

This method will set the input focus, but will not necessarily bring the window to the front.

set_foreground()

Set the window as the foreground (active) window.

set_position(rectangle)

Method to set the window’s position using a Rectangle object.

Parameters:

rectangle (Rectangle) – window position

property state

Read-only access to the X window state.

Windows can have multiple states, so this returns a tuple.

This property invokes a (relatively) long-running function, so store the result locally instead of using it multiple times.

If the window does not have the _NET_WM_STATE property, then None will be returned.

Returns:

window state (if any)

Return type:

tuple | None

property type

Read-only access to the window’s X11 type property, if it is set.

Returns:

type

Return type:

str

Window class for macOS

class DarwinWindow(id)

The Window class is an interface to the macOS window control and placement.

close()

Close the window (if possible).

full_screen()

Enable full screen mode for this window.

Note: this doesn’t allow transitioning out of full screen mode.

classmethod get_all_windows()

Get a list of all windows.

get_attribute(attribute)

Method to get an attribute of a macOS window.

Note: this method doesn’t distinguish between multiple instances of the same application.

Parameters:

attribute (string) – attribute name

Returns:

attribute value

classmethod get_foreground()

Get the foreground window.

classmethod get_matching_windows(executable=None, title=None)

Find windows with a matching executable or title.

Window searches are case-insensitive.

If neither parameter is be specified, then it is effectively the same as calling get_all_windows().

Parameters:

• executable (str) – – part of the filename of the application’s executable to which the target window belongs; not case sensitive.

• title (str) – – part of the title of the target window; not case sensitive.

Return type:

list

get_position()

Method to get the window’s position as a Rectangle object.

Returns:

window position

Return type:

Rectangle

get_properties()

Method to get the properties of a macOS window.

Return type:

dict

Returns:

window properties

property is_maximized

Whether the window is currently maximized.

property is_minimized

Whether the window is currently minimized.

property is_visible

Whether the window is currently visible.

This may be indeterminable for some windows.

maximize()

Maximize the window (if possible).

minimize()

Minimize the window (if possible).

restore()

Restore the window if it is minimized or maximized.

set_focus()

Set the window as the active window without raising it.

Note: this method will behave like set_foreground() in environments where this isn’t possible.

set_foreground()

Set the window as the foreground (active) window.

set_position(rectangle)

Method to set the window’s position using a Rectangle object.

Parameters:

rectangle (Rectangle) – window position