PyWinCtl

Cross-Platform module to get info on and control windows on screen.

With PyWinCtl you can retrieve info or control windows from other open applications, as well as use it as a cross-platform toolkit to manipulate your own application windows.

This module is a Python 3 evolution from asweigart's PyGetWindow module, which adds Linux/X11 and macOS support to the MS Windows-only original module, multi-monitor support, and many additional features; in the hope others can use it, test it or contribute.

My most sincere thanks and acknowledgement. amongst many others (see AUTHORS.txt), to MestreLion, super-ibby, Avasam, macdeport and holychowders for their help and moral boost.

1. Window Features
2. Important macOS notice
3. Important Linux notice
4. Window Change Notifications
5. Important comments
6. Important macOS Apple Script version notice
7. Menu Features
8. Install
9. Support
10. Using this code
11. Test

Window Features

There are three kinds of functions to be used within PyWinCtl: - General, independent functions: These functions can be directly invoked at module level, without the need of referencing a Window object (e.g. pywinctl.getActiveWindow() or pywinctl.getAllTitles()) - Window class: You need a Window object to control or get info on the target window on screen. It is possible to get a Window object by using any of the general methods (e.g. getActiveWidow() or getWindowsWithTitle()). You can also use the window id, as returned by PyQt's self.winId() or tkinter's root.frame(), which is very handy to get the Window object for your own application. - Methods: functions within Window class to get info or perform actions and changes on target window (e.g. window.resizeTo(800, 600) or window.close()) - Properties: Window attributes, getters and setters, that also require to use a Window object (e.g. window.title or window.center = (500, 300))

These features are available at the moment, in all three platforms (Windows, Linux and macOS)

Important macOS notice

macOS doesn't "like" controlling windows from other apps. MacOSWindow() class is based on Apple Script, so it is non-standard, slower and, in some cases, tricky (uses window name as reference, which may change or be duplicate), but it's working fine in most cases. You will likely need to grant permissions on Settings -> Security&Privacy -> Accessibility. Notice some applications will have limited Apple Script support or no support at all, so some or even all methods may fail!

Important Linux notice

The enormous variety of Linux distributions, Desktop Environments, Window Managers, and their combinations, make it impossible to test in all scenarios.

This module has been tested OK in some X11 setups: Ubuntu/Gnome, Ubuntu/KDE, Ubuntu/Unity, Mint/Cinnamon and Raspbian/LXDE. Except for Mint/Cinnamon and Ubuntu 22.04+, sendBehind() method doesn't properly work!

In Wayland (the new GNOME protocol for Ubuntu 22.04+), it is not possible to retrieve the active window nor the list of open windows, so getActiveWindow() and getAllWindows() will not likely work even though unsafe-mode is
enabled (built-in and "official" applications do not populate their Xid nor their X-Window object, so it may work for other applications like Chrome or your own application windows)

In case you find problems in other configs, please open an issue. Furthermore, if you have knowledge in these other configs, do not hesitate to contribute!

Window Change Notifications

Window watchdog sub-class, running in a separate Thread, will allow to define hooks and its callbacks to be notified when some window states change. Accessible through 'watchdog' submodule.

The watchdog will automatically stop when window doesn't exist anymore or main program quits.

isAliveCB:      callback to invoke when window is not alive anymore. Set to None to not to watch this
                Passes the new alive status value (False)

isActiveCB:     callback to invoke if window changes its active status. Set to None to not to watch this
                Passes the new active status value (True/False)

isVisibleCB:    callback to invoke if window changes its visible status. Set to None to not to watch this
                Passes the new visible status value (True/False)

isMinimizedCB:  callback to invoke if window changes its minimized status. Set to None to not to watch this
                Passes the new minimized status value (True/False)

isMaximizedCB:  callback to invoke if window changes its maximized status. Set to None to not to watch this
                Passes the new maximized status value (True/False)

resizedCB:      callback to invoke if window changes its size. Set to None to not to watch this
                Passes the new size (width, height)

movedCB:        callback to invoke if window changes its position. Set to None to not to watch this
                Passes the new position (x, y)

changedTitleCB: callback to invoke if window changes its title. Set to None to not to watch this
                Passes the new title (as string)
                IMPORTANT: In MacOS AppScript version, if title changes, watchdog will stop unless using setTryToFind(True)

changedDisplayCB: callback to invoke if window changes display. Set to None to not to watch this
                  Passes the new display name (as string)

Example:

import pywinctl as pwc
import time

def activeCB(active):
    print("NE