Adaptive Classes

class Dpowers.AdaptiveClass

adaptor: Class attribute. This is an instance of a subclass of Dpowers.Adaptor. It determines the backends available for this AdaptiveClass and is shared among all created instances. This Adaptor instance is used internally to access all backend specific functions. Usually you shouldn’t use this attribute, but prefer the AdaptiveClass’ methods.

classmethod adapt(*, group='default', _primary_name=False, **method_infos)

Changes the backend for all instances of this AdaptiveClass, including already created instances (unless adapt_instance() was used).

For parameters see Dpowers.Adaptor.adapt().

adapt_instance(*, group='default', _primary_name=False, **method_infos)

Changes the backend for this instance only.

For parameters see Dpowers.Adaptor.adapt().

Win / Win.Search

class Dpowers.Win(title_or_ID=None, wcls=None, *, pid=None, loc=None, at_least_one=False, limit=None, visible=None)

Subclass of Dpowers.AdaptiveClass.

Associated Adaptor class: Dpowers.WindowAdaptor

How to import:

from Dpowers import Win

# choose the default backend for your system:
Win.adapt()

# alternatively, choose one of the following backends:
Win.adapt('xtools_bash')

How to install dependencies for available backends:

>>> print(Win.install_instructions())
sudo apt install wmctrl xdotool

An object of this class represents one or more graphical windows of your operating system.

When a new instance of this class is created, a search is performed to find all existing windows matching the given parameters. Each window is identified by a unique system-wide identification number (ID). The matching IDs are saved in ascending order as a static list. Use the IDs() method to see them. All methods below will operate on this list of initially found windows.

Two Win() objects are considered identical if their list of IDs() are identical.

classmethod adapt(*, group='default', _primary_name=False, **method_infos): Choose the backend for this class. See AdaptiveClass.adapt(). For parameters see Dpowers.Adaptor.adapt().

__init__(title_or_ID=None, wcls=None, *, pid=None, loc=None, at_least_one=False, limit=None, visible=None)

Parameters:

title_or_ID (str, int) –
- A string is interpreted as the title to search for. The string can be contained anywhere in the window’s title to be considered a match.
- An integer is interpreted as a window ID. Specifying this directly will skip the search and all other parameters are hence ignored.
wcls (str) – Window class to search for. This must be an exact match.
pid (int) – Process ID of the window to search for.
loc (tuple) – Specify screen coordinates (x,y) for this parameter to retrieve the top-most window at that location. Specifying this will ignore all other parameters.
at_least_one (bool) – If set to True, check that at least one matching window has been found.
limit (int) – Maximum number of windows to include into the window object. If more matching windows exist, only the ones with the lowest IDs will be included.
visible (bool) – If set to True, only visible windows will be considered.

Raises:

WindowNotFoundError – If at_least_one is True and no matching window was found.

In order to find the currently active (i.e. topmost) window, simply call this class without parameters:

active_window = Win()

Several different parameters can be passed at once to narrow down the search. A window must fullfill all specified parameters to be a match:

dpowers_doc_win = Win('Dpowers documentation', 'Navigator.firefox')
# searches for windows with
# 'Dpowers documentation' contained in title
# AND
# window class is equal to 'Navigator.firefox' (Firefox browser)

In place of passing a single value for the parameters ID, title, wcls or pid, it is possible to pass a list (or tuple or set) of allowed values instead, which will search for a wider scope of windows:

dpowers_browser_win = Win('Dpowers documentation',
    ('Navigator.firefox','chromium-browser.Chromium-browser'))
# searches for windows with
# 'Dpowers documentation' contained in title
#   AND
# (window class is equal to 'Navigator.firefox'
#  OR window class is equal to 'chromium-browser.Chromium-browser')

In many cases it is desirable to make sure that exactly one matching window is found for each instance to avoid confusion. In other cases it might be useful to operate on a group of windows simultaneously.

Note

If a window was initially found and closed in the meantime, its ID will still be in the internal list of the Win() object. This can result in an Exception when trying to interact with a non-existent window ID. The update() or remove_non_existing() methods can be used to avoid this problem.

update(): Re-perform the initial search for matching existing windows and update this window object’s internal ID list. This removes non-existing windows and searches for new matches.

remove_non_existing(): Cleanse this window object’s internal ID list by removing those that do not exist anymore.

property num: Number (int) of windows found to match the given criteria. Equals zero if there was no match at all.

ID(): Returns the identification number (int) of this window if exactly one match was found. Returns None if no match was found. Raises ValueError if there was more than one matching window.

IDs(): Returns a tuple of length num containing the IDs of all found windows.

title(): Returns the title (str) of this window if exactly one match was found. Returns None if no match was found. Raises ValueError if there was more than one matching window.

titles(): Returns a tuple of length num containing the titles of all found windows. Use titles_gen() to create a generator instead of a tuple.

wcls(): Returns the window class (str) of this window if exactly one match was found. Returns None if no match was found. Raises ValueError if there was more than one matching window.

wclasses(): Returns a tuple of length num containing the window classes of all found windows. Use wclasses_gen() to create a generator instead of a tuple.

pid(): Returns the process ID (int) of this window if exactly one match was found. Returns None if no match was found. Raises ValueError if there was more than one matching window.

pids(): Returns a tuple of length num containing the process IDs of all found windows. Use pids_gen() to create a generator instead of a tuple.

classmethod screen_res(): Returns the screen resolution in pixels as a tuple (screen_width, screen_height).

width(): Returns the width in pixels (int) of this window if exactly one match was found. Returns None if no match was found. Raises ValueError if there was more than one matching window.

widths(): Returns a tuple of length num containing the widths of all found windows. Use widths_gen() to create a generator instead of a tuple.

height(): Returns the height in pixels (int) of this window if exactly one match was found. Returns None if no match was found. Raises ValueError if there was more than one matching window.

heights(): Returns a tuple of length num containing the heights of all found windows. Use heights_gen() to create a generator instead of a tuple.

geometry()

Returns the 4 border coordinates of this window if exactly one match was found. Returns None if no match was found. Raises ValueError if there was more than one matching window.

The return value is a 4-element tuple containing the window’s border coordinates as int in pixels as follows: (left, top, right, bottom) = (Xmin, Ymin, Xmax, Ymax).

geometries(): Returns a tuple of length num containing the geometries of all found windows. Use geometries_gen() to create a generator instead of a tuple.

info(): Returns the 2-element tuple (title(), wcls()) of this window if exactly one match was found. Returns None if no match was found. Raises ValueError if there was more than one matching window.

infos(): Returns a tuple of length num containing the info() tuples of all found windows. Use infos_gen() to create a generator instead of a tuple.

all_info(): Returns the 5-element tuple (ID(), title(), wcls(), pid(), geometry()) of this window if exactly one match was found. Returns None if no match was found. Raises ValueError if there was more than one matching window.

all_infos(): Returns a tuple of length num containing the all_info() tuples of all found windows. Use all_infos_gen() to create a generator instead of a tuple.

close(all=False)

Closes this window.

Parameters:: all – If set True, apply this command to all found windows.
Raises:: ValueError – If all is False (default) and more than one window matches.

kill(all=False)

Kill (force close) this window.

Parameters:: all – If set True, apply this command to all found windows.
Raises:: ValueError – If all is False (default) and more than one window matches.

minimize(all=False)

Minimize this window.

Parameters:: all – If set True, apply this command to all found windows.
Raises:: ValueError – If all is False (default) and more than one window matches.

maximize(all=False)

Maximize this window.

Parameters:: all – If set True, apply this command to all found windows.
Raises:: ValueError – If all is False (default) and more than one window matches.

max_left(all=False)

Maximize this window to the left side of the screen.

Parameters:: all – If set True, apply this command to all found windows.
Raises:: ValueError – If all is False (default) and more than one window matches.

max_right(all=False)

Maximize this window to the right side of the screen.

Parameters:: all – If set True, apply this command to all found windows.
Raises:: ValueError – If all is False (default) and more than one window matches.

move(x=-1, y=-1, width=-1, height=-1, all=False)

Move and resize this window. Specifying -1 for one of the coordinates will keep the current value (default).

Parameters:

x (int) – New coordinate of left border.
y (int) – New cordinate of top border
width (int) – New width of window.
height (int) – New hight of window.
all – If set True, apply this command to all found windows.

Raises:

ValueError – If all is False (default) and more than one window matches.

activate(all=False)

Activates this window.

Parameters:: all – If set True, apply this command to all found windows.
Raises:: ValueError – If all is False (default) and more than one window matches.

wait_active(timeout=5, pause_when_found=0.05, timestep=0.2)

Wait until the specified window is active. If several windows are matching, wait until any of them is active.

Parameters:

timeout (float) – Seconds to wait before returning anyway.
pause_when_found (float) – Time to sleep after success.
timestep (float) – Interval how often the condition is checked.

Returns:

The Win() object for the active window in case of success.
False in case of a timeout.

wait_not_active(timeout=5, timestep=0.2)

Same as wait_active(), but reversed. It waits until the specified window(s) is (are) not active anymore.

Returns:

True in case of success.
False in case of a timeout.

wait_exist(timeout=5, pause_when_found=0.05, timestep=0.2, min_wincount=1, max_wincount=None)

Waits until the number of matching windows is between min_wincount and max_wincount. By default, this means at least one matching window must exist.

Parameters:

timeout (float) – Seconds to wait before returning anyway.
pause_when_found (float) – Time to sleep after success.
timestep (float) – Interval how often the condition is checked.
min_wincount (int) – Minimum number of matching windows necessary to continue.
max_wincount – Maximum number of matching windows to continue. If set to None (default), there is no maximum.

Returns:

The Win() object containing all matching windows in case of success.
False in case of a timeout.

wait_not_exist(timeout=5, timestep=0.2)

Wrapper for wait_exist() with min_wincount = max_wincount = 0.

Returns:

True in case of success.
False in case of a timeout.

wait_num_change(num_change, timeout=5, pause_when_found=0.05, timestep=0.2)

Wrapper for wait_exist(). Waits until the number of currently matching windows has changed by num_change (relative to the initial found number num).

Parameters:

num_change (int) – A positive or negative integer.

Returns:

The Win() object of the newly found window(s) if num_change is positive.
The Win() object of the closed window(s) if num_change is negative. (These do not exist anymore.)
False in case of a timeout.

Useful when opening a new window if other windows of the same class are already existing, see for example: Launch the browser and simultaneously redirect key presses.

wait_exist_activate(timeout=5, timestep=0.2)

Wait until at least one matching window exists and activate it immediately.

Returns:

The Win() object for the found window.
False in case of timeout or if activate failed.

class Dpowers.Win.Search: Subclass of Dpowers.windowpower.windowobjects.WindowSearch, using the same adaptor instance (and thus the same backend) as Dpowers.Win.

Icon

class Dpowers.Icon

Subclass of Dpowers.AdaptiveClass.

Associated Adaptor class: Dpowers.IconAdaptor

How to import:

from Dpowers import Icon

# choose the default backend for your system:
Icon.adapt()

# alternatively, choose one of the following backends:
Icon.adapt('pystray')
Icon.adapt('yad_bash')

How to install dependencies for available backends:

>>> print(Icon.install_instructions())
pip install -U pystray pillow
sudo apt install yad

classmethod adapt(*, group='default', _primary_name=False, **method_infos): Choose the backend for this class. See AdaptiveClass.adapt(). For parameters see Dpowers.Adaptor.adapt().

menuitem(text=None, func=None)

Adds a new entry to the icon’s context menu.

Parameters:

text (str) – Text of the menu entry. If omitted func.__name__ will be used as text (underscores are replaced by space).
func – Function to execute when clicking this menu entry.

additem(func): A decorator to apply menuitem() directly onto a function.

TriggerManager

class Dpowers.TriggerManager(timeout=60, buffer=4)

Subclass of Dpowers.AdaptiveClass.

Associated Adaptor class: Dpowers.HookAdaptor

How to import:

from Dpowers import TriggerManager

# choose the default backend for your system:
TriggerManager.adapt()

# alternatively, choose one of the following backends:
TriggerManager.adapt('evdev')
TriggerManager.adapt('pynput')

How to install dependencies for available backends:

>>> print(TriggerManager.install_instructions())
pip install -U pynput

classmethod adapt(*, group='default', _primary_name=False, **method_infos): Choose the backend for this class. See AdaptiveClass.adapt(). For parameters see Dpowers.Adaptor.adapt().

KeyWaiter

class Dpowers.KeyWaiter(*args, eventmap=None, keys=True, buttons=False, press=True, release=False, write_rls=True, join_events=False, **kwargs)

Subclass of Dpowers.AdaptiveClass.

Associated Adaptor class: Dpowers.HookAdaptor

How to import:

from Dpowers import KeyWaiter

# choose the default backend for your system:
KeyWaiter.adapt()

# alternatively, choose one of the following backends:
KeyWaiter.adapt('evdev')
KeyWaiter.adapt('pynput')

How to install dependencies for available backends:

>>> print(KeyWaiter.install_instructions())
pip install -U pynput

classmethod adapt(*, group='default', _primary_name=False, **method_infos): Choose the backend for this class. See AdaptiveClass.adapt(). For parameters see Dpowers.Adaptor.adapt().