window API implementation for X11 environments

This class is invoked as the “window” class in AutoKey scripts. For example, the “autokey.scripting.window.Window.activate()” method documented below is called as “window.activate()” in an AutoKey script.

There are three different implementations of the “window” class, one for GNOME/Wayland environments, one for KDE/Wayland environments, and one for X11. This is the X11 version.

class autokey.scripting.window.Window(mediator)[source]

Basic window management using wmctrl

Note: in all cases where a window title is required (with the exception of wait_for_focus()), two special values of window title are permitted:

activate(title, switchDesktop=False, matchClass=False, by_hex=False)[source]

Activate the specified window, giving it input focus

Usage: window.activate(title, switchDesktop=False, matchClass=False)

If switchDesktop is False (default), the window will be moved to the current desktop and activated. Otherwise, switch to the window’s current desktop and activate it there.

Parameters:

  • title – window title to match against (as case-insensitive substring match)

  • switchDesktop – whether or not to switch to the window’s current desktop

  • matchClass – if True, match on the window class instead of the title

  • by_hex – If true, wmctrl will interpret the title as a hexid

center_window(title=':ACTIVE:', win_width=None, win_height=None, monitor=0, matchClass=False, by_hex=False)[source]

Centers the active (or window selected by title) window. Requires xrandr for getting monitor sizes and offsets.

Parameters:

  • title – Title of the window to center (defaults to using the active window)

  • win_width – Width of the centered window, defaults to screenx/3. Use -1 to center without size change.

  • win_height – Height of the centered window, defaults to screeny/3. Use -1 to center without size change.

  • monitor – Monitor number (0 is primary, listed via xrandr --listactivemonitors etc.)

  • matchClass – if True, match on the window class instead of the title

  • by_hex – If true, wmctrl will interpret the title as a hexid

Raises:

ValueError – If title or desktop is not found by wmctrl

close(title, matchClass=False, by_hex=False)[source]

Close the specified window gracefully

Usage: window.close(title, matchClass=False)

Parameters:

  • title – window title to match against (as case-insensitive substring match)

  • matchClass – if True, match on the window class instead of the title

  • by_hex – If true, wmctrl will interpret the title as a hexid

get_active_class()[source]

Get the class of the currently active window

Usage: window.get_active_class()

Returns:

the class of the currently active window

Return type:

str

get_active_geometry()[source]

Get the geometry of the currently active window. Uses the :ACTIVE: function of wmctrl.

Usage: window.get_active_geometry()

Returns:

a 4-tuple containing the x-origin, y-origin, width and height of the window (in pixels)

Return type:

tuple(int, int, int, int)

get_active_title()[source]

Get the visible title of the currently active window

Usage: window.get_active_title()

Returns:

the visible title of the currentle active window

Return type:

str

get_window_geometry(title, by_hex=False)[source]

Uses wmctrl to return the window geometry of the given window title. Returns where the location of the top left hand corner of the window is and the width/height of the window.

:param title :return: [offsetx, offsety, sizex, sizey] Returns none if no matches are found

get_window_hex(title)[source]

Returns the hexid of the first window to match title.

Parameters:

title – Window title to match for returning hexid

Returns:

Returns hexid of the window to be used for other functions See get_window_geom, visgrep_by_window_id

Returns None if no matches are found

get_window_list(filter_desktop=-1)[source]

Returns a list of windows matching an optional desktop filter, requires wmctrl!

Each list item consists of: [hexid, desktop, hostname, title]

Where the hexid is the ID used for some other functions (like import -window from ImageMagick).

desktop is the number of which desktop (sometimes called workspaces) the window appears upon.

hostname is the hostname of your computer.

title is the title that you would usually see in your window manager of choice.

Parameters:

filter_desktop – String, (usually 0-n) to filter the windows by. Any window not on the given desktop will not be returned.

Returns:

[[hexid1, desktop1, hostname1, title1], [hexid2,desktop2,hostname2,title2], ...etc] Returns [] if no windows are found.

move_to_desktop(title, deskNum, matchClass=False, by_hex=False)[source]

Move the specified window to the given desktop

Usage: window.move_to_desktop(title, deskNum, matchClass=False)

Parameters:

  • title – window title to match against (as case-insensitive substring match)

  • deskNum – desktop to move the window to (note: zero based)

  • matchClass – if True, match on the window class instead of the title

  • by_hex – If true, wmctrl will interpret the title as a hexid

resize_move(title, xOrigin=-1, yOrigin=-1, width=-1, height=-1, matchClass=False, by_hex=False)[source]

Resize and/or move the specified window

Usage: window.resize_move(title, xOrigin=-1, yOrigin=-1, width=-1, height=-1, matchClass=False)

Leaving any of the position/dimension values as the default (-1) will cause that value to be left unmodified.

Parameters:

  • title – window title to match against (as case-insensitive substring match)

  • xOrigin – new x origin of the window (upper left corner)

  • yOrigin – new y origin of the window (upper left corner)

  • width – new width of the window

  • height – new height of the window

  • matchClass – if True, match on the window class instead of the title

  • by_hex – If true, wmctrl will interpret the title as a hexid

set_property(title, action, prop, matchClass=False, by_hex=False)[source]

Set a property on the given window using the specified action

Usage: window.set_property(title, action, prop, matchClass=False)

Allowable actions:

  • add

  • remove

  • toggle

Allowable properties:

  • modal

  • sticky

  • maximized_vert

  • maximized_horz

  • shaded

  • skip_taskbar

  • skip_pager

  • hidden

  • fullscreen

  • above

Parameters:

  • title – window title to match against (as case-insensitive substring match)

  • action – one of the actions listed above

  • prop – one of the properties listed above

  • matchClass – if True, match on the window class instead of the title

  • by_hex – If true, wmctrl will interpret the title as a hexid

switch_desktop(deskNum)[source]

Switch to the specified desktop

Usage: window.switch_desktop(deskNum)

Parameters:

deskNum – desktop to switch to (note: zero based)

wait_for_exist(title, timeOut=5, by_hex=False)[source]

Wait for window with the given title to be created

Usage: window.wait_for_exist(title, timeOut=5)

If the window is in existence, returns True. Otherwise, returns False if the window has not been created by the time the timeout has elapsed.

Parameters:

  • title – title to match against (as a regular expression)

  • timeOut – period (seconds) to wait before giving up

  • by_hex – If true, wmctrl will interpret the title as a hexid

Return type:

boolean

wait_for_focus(title, timeOut=5)[source]

Wait for window with the given title to have focus

Usage: window.wait_for_focus(title, timeOut=5)

If the window becomes active, returns True. Otherwise, returns False if the window has not become active by the time the timeout has elapsed.

Parameters:

  • title – title to match against (as a regular expression)

  • timeOut – period (seconds) to wait before giving up

Return type:

boolean