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)[source]

The base Window class for controlling and placing windows.

classname

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

close()[source]

Close the window (if possible).

cls_name

Alias of classname.

executable

Read-only access to the window’s executable.

classmethod get_all_windows()[source]

Get a list of all windows.

get_containing_monitor()[source]

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()[source]

Get the foreground window.

classmethod get_matching_windows(executable=None, title=None)[source]

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()[source]

Method to get the window’s normalized position.

This is useful when working with multiple monitors.

Returns:normalized position
Return type:Rectangle
get_position()[source]

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

Returns:window position
Return type:Rectangle
classmethod get_window(id)[source]

Get a Window object given a window id.

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

handle

Protected access to handle attribute.

id

Protected access to id attribute.

is_maximized

Whether the window is currently maximized.

is_minimized

Whether the window is currently minimized.

is_visible

Whether the window is currently visible.

This may be indeterminable for some windows.

matches(context)[source]

Whether the window matches the given context.

maximize()[source]

Maximize the window (if possible).

minimize()[source]

Minimize the window (if possible).

move(rectangle, animate=None)[source]

Move the window, optionally animating its movement.

Parameters:
  • rectangle (Rectangle) – new window position and size
  • animate (str) – name of window mover
name

Protected access to name attribute.

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()[source]

Restore the window if it is minimized or maximized.

set_focus()[source]

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()[source]

Set the window as the foreground (active) window.

set_normalized_position(rectangle, monitor=None)[source]

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)[source]

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

Parameters:rectangle (Rectangle) – window position
title

Read-only access to the window’s title.

class FakeWindow(id)[source]

Fake Window class used when no implementation is available.

close()[source]

Close the window (if possible).

classmethod get_all_windows()[source]

Get a list of all windows.

classmethod get_foreground()[source]

Get the foreground window.

get_position()[source]

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

Returns:window position
Return type:Rectangle
is_maximized

Whether the window is currently maximized.

is_minimized

Whether the window is currently minimized.

is_visible

Whether the window is currently visible.

This may be indeterminable for some windows.

maximize()[source]

Maximize the window (if possible).

minimize()[source]

Minimize the window (if possible).

restore()[source]

Restore the window if it is minimized or maximized.

set_focus()[source]

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()[source]

Set the window as the foreground (active) window.

set_position(rectangle)[source]

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

Parameters:rectangle (Rectangle) – window position

Window class for Windows

class Win32Window(handle)[source]

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

classmethod get_all_windows()[source]

Get a list of all windows.

classmethod get_foreground()[source]

Get the foreground window.

classmethod get_matching_windows(executable=None, title=None)[source]

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()[source]

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

Returns:window position
Return type:Rectangle
is_enabled

Shortcut to win32gui.IsWindowEnabled() function.

is_maximized

Whether the window is currently maximized.

is_minimized

Shortcut to win32gui.IsIconic() function.

is_valid

Shortcut to win32gui.IsWindow() function.

is_visible

Shortcut to win32gui.IsWindowVisible() function.

set_focus()[source]

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()[source]

Set the window as the foreground (active) window.

set_position(rectangle)[source]

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

Parameters:rectangle (Rectangle) – window position

Window class for X11

class X11Window(id)[source]

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()[source]

Close the window (if possible).

cls

Read-only access to the window’s class.

classmethod get_all_windows()[source]

Get a list of all windows.

classmethod get_foreground()[source]

Get the foreground window.

classmethod get_matching_windows(executable=None, title=None)[source]

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()[source]

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

Returns:window position
Return type:Rectangle
is_focused

Whether the window has input focus.

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

Return type:bool
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
is_maximized

Whether the window is currently maximized.

is_minimized

Whether the window is currently minimized.

is_visible

Whether the window is currently visible.

This may be indeterminable for some windows.

maximize()[source]

Maximize the window (if possible).

minimize()[source]

Minimize the window (if possible).

restore()[source]

Restore the window if it is minimized or maximized.

role

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

Returns:role
Return type:str
set_focus()[source]

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()[source]

Set the window as the foreground (active) window.

set_position(rectangle)[source]

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

Parameters:rectangle (Rectangle) – window position
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
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)[source]

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

close()[source]

Close the window (if possible).

full_screen()[source]

Enable full screen mode for this window.

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

classmethod get_all_windows()[source]

Get a list of all windows.

get_attribute(attribute)[source]

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()[source]

Get the foreground window.

classmethod get_matching_windows(executable=None, title=None)[source]

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()[source]

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

Returns:window position
Return type:Rectangle
get_properties()[source]

Method to get the properties of a macOS window.

Return type:dict
Returns:window properties
is_maximized

Whether the window is currently maximized.

is_minimized

Whether the window is currently minimized.

is_visible

Whether the window is currently visible.

This may be indeterminable for some windows.

maximize()[source]

Maximize the window (if possible).

minimize()[source]

Minimize the window (if possible).

restore()[source]

Restore the window if it is minimized or maximized.

set_focus()[source]

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()[source]

Set the window as the foreground (active) window.

set_position(rectangle)[source]

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

Parameters:rectangle (Rectangle) – window position