window API implementation for GNOME/Wayland environments

This class is invoked as the “window” class in AutoKey scripts. For example, the “autokey.scripting.window_gnome.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 GNOME/Wayland version.

class autokey.scripting.window_gnome.Window(mediator)

Window management with AutoKey GNOME Shell extension

activate(title, switchDesktop=False, matchClass=False, by_hex=False)

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 – If True, switch to desktop where window resides and activate

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

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

center_window(title=':ACTIVE:', win_width=None, win_height=None, matchClass=False, by_hex=False)

Centers the active (or window selected by title) window.

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.

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

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

close(title, matchClass=False, by_hex=False)

Close the specified window gracefully

Usage: window.close(title, matchClass=False), by_hex=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, interpret the title as a hexid

get_active_class()

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()

Get the geometry of the currently active window.

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()

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, matchClass=False, by_hex=False)

Returns 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.

Parameters:

• title – Window title to match for returning geometry. Use “:ACTIVE:” to specify the window that currently has focus on the desktop.

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

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

Returns:

[offsetx, offsety, sizex, sizey] Returns none if no matches are found

Returns None if no matching window was found

get_window_hex(title)

Returns the hexid of the first window to match title.

Parameters:

title – Window title to match for returning hexid. Use “:ACTIVE:” to specify the window that currently has focus on the desktop.

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)

Returns a list of windows matching an optional desktop filter, requires AutoKey GNOME Shell extension!

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:

(note (filter_desktop) – zero based)

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)

Move window to specified desktop (GNOME workspace)

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

Parameters:

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

• desknum – the number of the desktop (workspace) to which to move this window (note: zero based)

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

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

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

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, interpret the title as a hexid

set_property(title, action, prop, matchClass=False, by_hex=False)

Set a property on the given window using the specified action

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

Allowable actions:

• add

• remove

• toggle

Properties available in the GNOME environment:

• sticky (“add” or “remove” only, no “toggle”)

• maximized_vert

• maximized_horz

• 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, will interpret the title as a hexid

switch_desktop(deskNum)

Switch to the specified desktop (GNOME workspace)

Usage: window.switch_desktop(deskNum)

Parameters:

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

wait_for_exist(title, timeOut=5, by_hex=False)

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, will interpret the title as a hexid

Return type:

boolean

wait_for_focus(title, timeOut=5)

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