Library documentation

class xdo.mouse_location

mouse_location(x, y, screen_num)

screen_num

Alias for field number 2

x

Alias for field number 0

y

Alias for field number 1

class xdo.mouse_location2

mouse_location2(x, y, screen_num, window)

screen_num

Alias for field number 2

window

Alias for field number 3

x

Alias for field number 0

y

Alias for field number 1

class xdo.window_location

window_location(x, y, screen)

screen

Alias for field number 2

x

Alias for field number 0

y

Alias for field number 1

class xdo.window_size

window_size(width, height)

height

Alias for field number 1

width

Alias for field number 0

class xdo.input_mask

input_mask(shift, lock, control, mod1, mod2, mod3, mod4, mod5)

control

Alias for field number 2

lock

Alias for field number 1

mod1

Alias for field number 3

mod2

Alias for field number 4

mod3

Alias for field number 5

mod4

Alias for field number 6

mod5

Alias for field number 7

shift

Alias for field number 0

class xdo.Xdo(display=None)[source]
version()[source]
move_mouse(x, y, screen=0)[source]

Move the mouse to a specific location.

Parameters:
  • x – the target X coordinate on the screen in pixels.
  • y – the target Y coordinate on the screen in pixels.
  • screen – the screen (number) you want to move on.
move_mouse_relative_to_window(window, x, y)[source]

Move the mouse to a specific location relative to the top-left corner of a window.

Parameters:
  • x – the target X coordinate on the screen in pixels.
  • y – the target Y coordinate on the screen in pixels.
move_mouse_relative(x, y)[source]

Move the mouse relative to it’s current position.

Parameters:
  • x – the distance in pixels to move on the X axis.
  • y – the distance in pixels to move on the Y axis.
mouse_down(window, button)[source]

Send a mouse press (aka mouse down) for a given button at the current mouse location.

Parameters:
  • window – The window you want to send the event to or CURRENTWINDOW
  • button – The mouse button. Generally, 1 is left, 2 is middle, 3 is right, 4 is wheel up, 5 is wheel down.
mouse_up(window, button)[source]

Send a mouse release (aka mouse up) for a given button at the current mouse location.

Parameters:
  • window – The window you want to send the event to or CURRENTWINDOW
  • button – The mouse button. Generally, 1 is left, 2 is middle, 3 is right, 4 is wheel up, 5 is wheel down.
get_mouse_location()[source]

Get the current mouse location (coordinates and screen number).

Returns:a namedtuple with x, y and screen_num fields
get_window_at_mouse()[source]

Get the window the mouse is currently over

get_mouse_location2()[source]

Get all mouse location-related data.

Returns:a namedtuple with x, y, screen_num and window fields
wait_for_mouse_move_from(origin_x, origin_y)[source]

Wait for the mouse to move from a location. This function will block until the condition has been satisified.

Parameters:
  • origin_x – the X position you expect the mouse to move from
  • origin_y – the Y position you expect the mouse to move from
wait_for_mouse_move_to(dest_x, dest_y)[source]

Wait for the mouse to move to a location. This function will block until the condition has been satisified.

Parameters:
  • dest_x – the X position you expect the mouse to move to
  • dest_y – the Y position you expect the mouse to move to
click_window(window, button)[source]

Send a click for a specific mouse button at the current mouse location.

Parameters:
  • window – The window you want to send the event to or CURRENTWINDOW
  • button – The mouse button. Generally, 1 is left, 2 is middle, 3 is right, 4 is wheel up, 5 is wheel down.
click_window_multiple(window, button, repeat=2, delay=100000)[source]

Send a one or more clicks for a specific mouse button at the current mouse location.

Parameters:
  • window – The window you want to send the event to or CURRENTWINDOW
  • button – The mouse button. Generally, 1 is left, 2 is middle, 3 is right, 4 is wheel up, 5 is wheel down.
  • repeat – number of repetitions (default: 2)
  • delay – delay between clicks, in microseconds (default: 100k)
enter_text_window(window, string, delay=12000)[source]

Type a string to the specified window.

If you want to send a specific key or key sequence, such as “alt+l”, you want instead send_keysequence_window(...).

Parameters:
  • window – The window you want to send keystrokes to or CURRENTWINDOW
  • string – The string to type, like “Hello world!”
  • delay – The delay between keystrokes in microseconds. 12000 is a decent choice if you don’t have other plans.
send_keysequence_window(window, keysequence, delay=12000)[source]

Send a keysequence to the specified window.

This allows you to send keysequences by symbol name. Any combination of X11 KeySym names separated by ‘+’ are valid. Single KeySym names are valid, too.

Examples:
“l” “semicolon” “alt+Return” “Alt_L+Tab”

If you want to type a string, such as “Hello world.” you want to instead use xdo_enter_text_window.

Parameters:
  • window – The window you want to send the keysequence to or CURRENTWINDOW
  • keysequence – The string keysequence to send.
  • delay – The delay between keystrokes in microseconds.
send_keysequence_window_up(window, keysequence, delay=12000)[source]

Send key release (up) events for the given key sequence

send_keysequence_window_down(window, keysequence, delay=12000)[source]

Send key press (down) events for the given key sequence

send_keysequence_window_list_do(window, keys, pressed=1, modifier=None, delay=120000)[source]

Send a series of keystrokes.

Parameters:
  • window – The window to send events to or CURRENTWINDOW
  • keys – The array of charcodemap_t entities to send.
  • pressed – 1 for key press, 0 for key release.
  • modifier – Pointer to integer to record the modifiers activated by the keys being pressed. If NULL, we don’t save the modifiers.
  • delay – The delay between keystrokes in microseconds.
get_active_keys_to_keycode_list()[source]

Get a list of active keys. Uses XQueryKeymap

wait_for_window_map_state(window, state)[source]

Wait for a window to have a specific map state.

State possibilities:

IsUnmapped - window is not displayed. IsViewable - window is mapped and shown (though may be

clipped by windows on top of it)

IsUnviewable - window is mapped but a parent window is unmapped.

Parameters:
  • window – the window you want to wait for.
  • state – the state to wait for.
wait_for_window_size(window, width, height, flags, to_or_from)[source]
wait_for_window_size_to(window, width, height, flags=0)[source]
wait_for_window_size_from(window, width, height, flags=0)[source]
move_window(window, x, y)[source]

Move a window to a specific location.

The top left corner of the window will be moved to the x,y coordinate.

Parameters:
  • wid – the window to move
  • x – the X coordinate to move to.
  • y – the Y coordinate to move to.
translate_window_with_sizehint(window, width, height)[source]

Apply a window’s sizing hints (if any) to a given width and height.

This function wraps XGetWMNormalHints() and applies any resize increment and base size to your given width and height values.

Parameters:
  • window – the window to use
  • width – the unit width you want to translate
  • height – the unit height you want to translate
Returns:

(width, height)
set_window_size(window, w, h, flags=0)[source]

Change the window size.

Parameters:
  • wid – the window to resize
  • w – the new desired width
  • h – the new desired height
  • flags – if 0, use pixels for units. If SIZE_USEHINTS, then the units will be relative to the window size hints.
set_window_property(window, name, value)[source]

Change a window property.

Example properties you can change are WM_NAME, WM_ICON_NAME, etc.

Parameters:
  • wid – The window to change a property of.
  • name – the string name of the property.
  • value – the string value of the property.
set_window_class(window, name, class_)[source]

Change the window’s classname and or class.

Parameters:
  • name – The new class name. If None, no change.
  • class – The new class. If None, no change.
set_window_urgency(window, urgency)[source]

Sets the urgency hint for a window

set_window_override_redirect(window, override_redirect)[source]

Set the override_redirect value for a window. This generally means whether or not a window manager will manage this window.

If you set it to 1, the window manager will usually not draw borders on the window, etc. If you set it to 0, the window manager

will see it like a normal application window.
focus_window(window)[source]

Focus a window.

See:xdo_activate_window
Parameters:wid – the window to focus.
raise_window(window)[source]

Raise a window to the top of the window stack. This is also sometimes termed as bringing the window forward.

Parameters:wid – The window to raise.
get_focused_window()[source]

Get the window currently having focus.

Parameters:window_ret –

Pointer to a window where the currently-focused window will be stored.

wait_for_window_focus(window, want_focus)[source]

Wait for a window to have or lose focus.

Parameters:
  • window – The window to wait on
  • want_focus – If 1, wait for focus. If 0, wait for loss of focus.
get_pid_window(window)[source]

Get the PID owning a window. Not all applications support this. It looks at the _NET_WM_PID property of the window.

Parameters:window – the window to query.
Returns:the process id or 0 if no pid found.
get_focused_window_sane()[source]

Like xdo_get_focused_window, but return the first ancestor-or-self window * having a property of WM_CLASS. This allows you to get the “real” or top-level-ish window having focus rather than something you may not expect to be the window having focused.

Parameters:window_ret – Pointer to a window where the currently-focused window will be stored.
activate_window(window)[source]

Activate a window. This is generally a better choice than xdo_focus_window for a variety of reasons, but it requires window manager support:

  • If the window is on another desktop, that desktop is switched to.
  • It moves the window forward rather than simply focusing it

Requires your window manager to support this. Uses _NET_ACTIVE_WINDOW from the EWMH spec.

Parameters:wid – the window to activate
wait_for_window_active(window, active=1)[source]

Wait for a window to be active or not active.

Requires your window manager to support this. Uses _NET_ACTIVE_WINDOW from the EWMH spec.

Parameters:
  • window – the window to wait on
  • active – If 1, wait for active. If 0, wait for inactive.
map_window(window)[source]

Map a window. This mostly means to make the window visible if it is not currently mapped.

Parameters:wid – the window to map.
unmap_window(window)[source]

Unmap a window

Parameters:wid – the window to unmap
minimize_window(window)[source]

Minimize a window

reparent_window(window_source, window_target)[source]

Reparents a window

Parameters:
  • wid_source – the window to reparent
  • wid_target – the new parent window
get_window_location(window)[source]

Get a window’s location.

get_window_size(window)[source]

Get a window’s size.

get_active_window()[source]

Get the currently-active window. Requires your window manager to support this. Uses _NET_ACTIVE_WINDOW from the EWMH spec.

select_window_with_click()[source]

Get a window ID by clicking on it. This function blocks until a selection is made.

set_number_of_desktops(ndesktops)[source]

Set the number of desktops. Uses _NET_NUMBER_OF_DESKTOPS of the EWMH spec.

Parameters:ndesktops – the new number of desktops to set.
get_number_of_desktops()[source]

Get the current number of desktops. Uses _NET_NUMBER_OF_DESKTOPS of the EWMH spec.

Parameters:ndesktops – pointer to long where the current number of desktops is stored
set_current_desktop(desktop)[source]

Switch to another desktop. Uses _NET_CURRENT_DESKTOP of the EWMH spec.

Parameters:desktop – The desktop number to switch to.
get_current_desktop()[source]

Get the current desktop. Uses _NET_CURRENT_DESKTOP of the EWMH spec.

set_desktop_for_window(window, desktop)[source]

Move a window to another desktop Uses _NET_WM_DESKTOP of the EWMH spec.

Parameters:
  • wid – the window to move
  • desktop – the desktop destination for the window
get_desktop_for_window(window)[source]

Get the desktop a window is on. Uses _NET_WM_DESKTOP of the EWMH spec.

If your desktop does not support _NET_WM_DESKTOP, then ‘*desktop’ remains unmodified.

Parameters:wid – the window to query
search_windows(winname=None, winclass=None, winclassname=None, pid=None, only_visible=False, screen=None, require=False, searchmask=0, desktop=None, limit=0, max_depth=-1)[source]

Search for windows.

Parameters:
  • winname – Regexp to be matched against window name
  • winclass – Regexp to be matched against window class
  • winclassname – Regexp to be matched against window class name
  • pid – Only return windows from this PID
  • only_visible – If True, only return visible windows
  • screen – Search only windows on this screen
  • require – If True, will match ALL conditions. Otherwise, windows matching ANY condition will be returned.
  • searchmask – Search mask, for advanced usage. Leave this alone if you don’t kwnow what you are doing.
  • limit – Maximum number of windows to list. Zero means no limit.
  • max_depth – Maximum depth to return. Defaults to -1, meaning “no limit”.
Returns:

A list of window ids matching query.
get_window_property_by_atom(window, atom)[source]
get_window_property(window, name)[source]
get_input_state()[source]

Get the current input state.

Returns:a namedtuple with the following (boolean) fields: shift, lock, control, mod1, mod2, mod3, mod4, mod5
get_symbol_map()[source]

If you need the symbol map, use this method.

The symbol map is an array of string pairs mapping common tokens to X Keysym strings, such as “alt” to “Alt_L”

Returns:array of strings.
get_active_modifiers()[source]

Get a list of active keys. Uses XQueryKeymap.

Returns:list of charcodemap_t instances
clear_active_modifiers(window, mods=None)[source]

Send any events necesary to clear the the active modifiers. For example, if you are holding ‘alt’ when xdo_get_active_modifiers is called, then this method will send a key-up for ‘alt’

set_active_modifiers(window, mods=None)[source]

Send any events necessary to make these modifiers active. This is useful if you just cleared the active modifiers and then wish to restore them after.

get_desktop_viewport()[source]

Get the position of the current viewport.

This is only relevant if your window manager supports _NET_DESKTOP_VIEWPORT.

set_desktop_viewport(x, y)[source]

Set the position of the current viewport.

This is only relevant if your window manager supports _NET_DESKTOP_VIEWPORT

kill_window()[source]

Kill a window and the client owning it.

XDO_FIND_PARENTS = 0
XDO_FIND_CHILDREN = 1
find_window_client()[source]

Find a client window (child) in a given window. Useful if you get the window manager’s decorator window rather than the client window.

get_window_name()[source]

Get a window’s name, if any.

enable_feature()[source]

Enable an xdo feature.

This function is mainly used by libxdo itself, however, you may find it useful in your own applications.

See:XDO_FEATURES
has_feature()[source]

Check if a feature is enabled.

This function is mainly used by libxdo itself, however, you may find it useful in your own applications.

See:XDO_FEATURES
get_viewport_dimensions()[source]

Query the viewport (your display) dimensions

If Xinerama is active and supported, that api internally is used. If Xineram is disabled, we will report the root window’s dimensions for the given screen.