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.
-
executable
¶ Read-only access to the window’s executable.
-
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_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.
-
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
-
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_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.
-
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.
-
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.
-
Window class for Windows¶
-
class
Win32Window
(handle)[source]¶ The Window class is an interface to the Win32 window control and placement.
-
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.
-
classmethod
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 returnTrue
if successful.This class requires the following external programs:
wmctrl
xdotool
xprop
-
cls
¶ Read-only access to the window’s class.
-
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.
-
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_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.
-
full_screen
()[source]¶ Enable full screen mode for this window.
Note: this doesn’t allow transitioning out of full screen mode.
-
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_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.
-
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.
-