Data Structures
struct	keysym_charmap
struct	charcodemap
struct	xdo
	The main context. More...
struct	xdo_active_mods
	Represents the list of active modifier keys at the time of an xdo_get_active_modifiers call. More...
struct	xdo_search
	The window search query structure. More...

Typedefs
typedef struct keysym_charmap	keysym_charmap_t
typedef struct charcodemap	charcodemap_t
typedef struct xdo	xdo_t
	The main context.
typedef struct xdo_active_mods	xdo_active_mods_t
	Represents the list of active modifier keys at the time of an xdo_get_active_modifiers call.
typedef struct xdo_search	xdo_search_t
	The window search query structure.

Functions
xdo_t *	xdo_new (char *display)
	Create a new xdo_t instance.
xdo_t *	xdo_new_with_opened_display (Display xdpy, const char display, int close_display_when_freed)
	Create a new xdo_t instance with an existing X11 Display instance.
const char *	xdo_version (void)
	Return a string representing the version of this library.
void	xdo_free (xdo_t *xdo)
	Free and destroy an xdo_t instance.
int	xdo_mousemove (const xdo_t *xdo, int x, int y, int screen)
	Move the mouse to a specific location.
int	xdo_mousemove_relative_to_window (const xdo_t *xdo, Window window, int x, int y)
	Move the mouse to a specific location relative to the top-left corner of a window.
int	xdo_mousemove_relative (const xdo_t *xdo, int x, int y)
	Move the mouse relative to it's current position.
int	xdo_mousedown (const xdo_t *xdo, Window window, int button)
	Send a mouse press (aka mouse down) for a given button at the current mouse location.
int	xdo_mouseup (const xdo_t *xdo, Window window, int button)
	Send a mouse release (aka mouse up) for a given button at the current mouse location.
int	xdo_mouselocation (const xdo_t xdo, int x, int y, int screen_num)
	Get the current mouse location.
int	xdo_mouse_wait_for_move_from (const xdo_t *xdo, int origin_x, int origin_y)
	Wait for the mouse to move from a location.
int	xdo_mouse_wait_for_move_to (const xdo_t *xdo, int dest_x, int dest_y)
	Wait for the mouse to move to a location.
int	xdo_click (const xdo_t *xdo, Window window, int button)
	Send a click for a specific mouse button at the current mouse location.
int	xdo_type (const xdo_t xdo, Window window, char string, useconds_t delay)
	Type a string to the specified window.
int	xdo_keysequence (const xdo_t xdo, Window window, const char keysequence, useconds_t delay)
	Send a keysequence to the specified window.
int	xdo_keysequence_up (const xdo_t xdo, Window window, const char keysequence, useconds_t delay)
	Send key release (up) events for the given key sequence.
int	xdo_keysequence_down (const xdo_t xdo, Window window, const char keysequence, useconds_t delay)
	Send key press (down) events for the given key sequence.
int	xdo_keysequence_list_do (const xdo_t xdo, Window window, charcodemap_t keys, int nkeys, int pressed, int *modifier, useconds_t delay)
	Send a series of keystrokes.
int	xdo_active_keys_to_keycode_list (const xdo_t xdo, charcodemap_t keys, int nkeys)
	Get a list of active keys.
int	xdo_window_wait_for_map_state (const xdo_t *xdo, Window wid, int map_state)
	Wait for a window to have a specific map state.
int	xdo_window_wait_for_size (const xdo_t *xdo, Window window, unsigned int width, unsigned int height, int flags, int to_or_from)
int	xdo_window_move (const xdo_t *xdo, Window wid, int x, int y)
	Move a window to a specific location.
int	xdo_window_translate_with_sizehint (const xdo_t xdo, Window window, int width, int height, int width_ret, int *height_ret)
	Apply a window's sizing hints (if any) to a given width and height.
int	xdo_window_setsize (const xdo_t *xdo, Window wid, int w, int h, int flags)
	Change the window size.
int	xdo_window_setprop (const xdo_t xdo, Window wid, const char property, const char *value)
	Change a window property.
int	xdo_window_setclass (const xdo_t xdo, Window wid, const char name, const char *class)
	Change the window's classname and or class.
int	xdo_window_focus (const xdo_t *xdo, Window wid)
	Focus a window.
int	xdo_window_raise (const xdo_t *xdo, Window wid)
	Raise a window to the top of the window stack.
int	xdo_window_get_focus (const xdo_t xdo, Window window_ret)
	Get the window currently having focus.
int	xdo_window_wait_for_focus (const xdo_t *xdo, Window window, int want_focus)
	Wait for a window to have or lose focus.
int	xdo_window_get_pid (const xdo_t *xdo, Window window)
	Get the PID owning a window.
int	xdo_window_sane_get_focus (const xdo_t xdo, Window window_ret)
	Like xdo_window_get_focus, but return the first ancestor-or-self window * having a property of WM_CLASS.
int	xdo_window_activate (const xdo_t *xdo, Window wid)
	Activate a window.
int	xdo_window_wait_for_active (const xdo_t *xdo, Window window, int active)
	Wait for a window to be active or not active.
int	xdo_window_map (const xdo_t *xdo, Window wid)
	Map a window.
int	xdo_window_unmap (const xdo_t *xdo, Window wid)
	Unmap a window.
int	xdo_get_window_location (const xdo_t xdo, Window wid, int x_ret, int y_ret, Screen *screen_ret)
	Get a window's location.
int	xdo_get_window_size (const xdo_t xdo, Window wid, unsigned int width_ret, unsigned int *height_ret)
	Get a window's size.
int	xdo_window_get_active (const xdo_t xdo, Window window_ret)
	Get the currently-active window.
int	xdo_set_number_of_desktops (const xdo_t *xdo, long ndesktops)
	Set the number of desktops.
int	xdo_get_number_of_desktops (const xdo_t xdo, long ndesktops)
	Get the current number of desktops.
int	xdo_set_current_desktop (const xdo_t *xdo, long desktop)
	Switch to another desktop.
int	xdo_get_current_desktop (const xdo_t xdo, long desktop)
	Get the current desktop.
int	xdo_set_desktop_for_window (const xdo_t *xdo, Window wid, long desktop)
	Move a window to another desktop Uses _NET_WM_DESKTOP of the EWMH spec.
int	xdo_get_desktop_for_window (const xdo_t xdo, Window wid, long desktop)
	Get the desktop a window is on.
int	xdo_window_search (const xdo_t xdo, const xdo_search_t search, Window *windowlist_ret, int nwindows_ret)
	Search for windows.
unsigned char *	xdo_getwinprop (const xdo_t xdo, Window window, Atom atom, long nitems, Atom type, int size)
	Generic property fetch.
unsigned int	xdo_get_input_state (const xdo_t *xdo)
	Get the current input state.
const keysym_charmap_t *	xdo_keysym_charmap (void)
	If you need the keysym-to-character map, you can fetch it using this method.
const char **	xdo_symbol_map (void)
	If you need the symbol map, use this method.
xdo_active_mods_t *	xdo_get_active_modifiers (const xdo_t *xdo)
	Get the currently-active modifiers.
int	xdo_clear_active_modifiers (const xdo_t xdo, Window window, xdo_active_mods_t active_mods)
	Send any events necesary to clear the the active modifiers.
int	xdo_set_active_modifiers (const xdo_t xdo, Window window, const xdo_active_mods_t active_mods)
	Send any events necessary to make these modifiers active.
void	xdo_free_active_modifiers (xdo_active_mods_t *active_mods)
	Free the data allocated by xdo_get_active_modifiers.

Detailed Description

Typedef Documentation

typedef struct xdo_active_mods xdo_active_mods_t

Represents the list of active modifier keys at the time of an xdo_get_active_modifiers call.

See Also: xdo_get_active_modifiers; xdo_free_active_modifiers

typedef struct xdo_search xdo_search_t

The window search query structure.

See Also: xdo_window_search

Function Documentation

int xdo_active_keys_to_keycode_list	(	const xdo_t *	xdo,
		charcodemap_t **	keys,
		int *	nkeys
	)

Get a list of active keys.

Uses XQueryKeymap.

Parameters

keys	Pointer to the array of charcodemap_t that will be allocated by this function.
nkeys	Pointer to integer where the number of keys will be stored.

int xdo_clear_active_modifiers	(	const xdo_t *	xdo,
		Window	window,
		xdo_active_mods_t *	active_mods
	)

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'

int xdo_click	(	const xdo_t *	xdo,
		Window	window,
		int	button
	)

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.

void xdo_free ( xdo_t * xdo )

Free and destroy an xdo_t instance.

If close_display_when_freed is set, then we will also close the Display.

int xdo_get_current_desktop	(	const xdo_t *	xdo,
		long *	desktop
	)

Get the current desktop.

Uses _NET_CURRENT_DESKTOP of the EWMH spec.

Parameters

desktop pointer to long where the current desktop number is stored.

int xdo_get_desktop_for_window	(	const xdo_t *	xdo,
		Window	wid,
		long *	desktop
	)

Get the desktop a window is on.

Uses _NET_WM_DESKTOP of the EWMH spec.

Parameters

wid	the window to query
deskto	pointer to long where the desktop of the window is stored

unsigned int xdo_get_input_state ( const xdo_t * xdo )

Get the current input state.

This is a mask value containing any of the following: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, or Mod5Mask.

Returns: the input mask

int xdo_get_number_of_desktops	(	const xdo_t *	xdo,
		long *	ndesktops
	)

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

int xdo_get_window_location	(	const xdo_t *	xdo,
		Window	wid,
		int *	x_ret,
		int *	y_ret,
		Screen **	screen_ret
	)

Get a window's location.

Parameters

wid	the window to query
x_ret	pointer to int where the X location is stored. If NULL, X is ignored.
y_ret	pointer to int where the Y location is stored. If NULL, X is ignored.
screen_ret	Pointer to Screen* where the Screen* the window on is stored. If NULL, this parameter is ignored.

int xdo_get_window_size	(	const xdo_t *	xdo,
		Window	wid,
		unsigned int *	width_ret,
		unsigned int *	height_ret
	)

Get a window's size.

Parameters

wid	the window to query
width_ret	pointer to unsigned int where the width is stored.
height_ret	pointer to unsigned int where the height is stored.

unsigned char* xdo_getwinprop	(	const xdo_t *	xdo,
		Window	window,
		Atom	atom,
		long *	nitems,
		Atom *	type,
		int *	size
	)

Generic property fetch.

Parameters

window	the window to query
atom	the Atom to request
nitems	the number of items
type	the type of the return
size	the size of the type

Returns: data consisting of 'nitems' items of size 'size' and type 'type' will need to be cast to the type before using.

int xdo_keysequence	(	const xdo_t *	xdo,
		Window	window,
		const char *	keysequence,
		useconds_t	delay
	)

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

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.

int xdo_keysequence_down	(	const xdo_t *	xdo,
		Window	window,
		const char *	keysequence,
		useconds_t	delay
	)

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

See Also: xdo_keysequence

int xdo_keysequence_list_do	(	const xdo_t *	xdo,
		Window	window,
		charcodemap_t *	keys,
		int	nkeys,
		int	pressed,
		int *	modifier,
		useconds_t	delay
	)

Send a series of keystrokes.

Parameters

window	The window to send events to or CURRENTWINDOW
keys	The array of charcodemap_t entities to send.
nkeys	The length of the keys parameter
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.

int xdo_keysequence_up	(	const xdo_t *	xdo,
		Window	window,
		const char *	keysequence,
		useconds_t	delay
	)

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

See Also: xdo_keysequence

const keysym_charmap_t* xdo_keysym_charmap ( void )

If you need the keysym-to-character map, you can fetch it using this method.

See Also: keysym_charmap_t

int xdo_mouse_wait_for_move_from	(	const xdo_t *	xdo,
		int	origin_x,
		int	origin_y
	)

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

int xdo_mouse_wait_for_move_to	(	const xdo_t *	xdo,
		int	dest_x,
		int	dest_y
	)

Wait for the mouse to move to a location.

This function will block until the condition has been satisfied.

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

int xdo_mousedown	(	const xdo_t *	xdo,
		Window	window,
		int	button
	)

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.

int xdo_mouselocation	(	const xdo_t *	xdo,
		int *	x,
		int *	y,
		int *	screen_num
	)

Get the current mouse location.

Parameters

x	integer pointer where the X coordinate will be stored
y	integer pointer where the Y coordinate will be stored
screen_num	integer pointer where the screen number will be stored

int xdo_mousemove	(	const xdo_t *	xdo,
		int	x,
		int	y,
		int	screen
	)

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.

int xdo_mousemove_relative	(	const xdo_t *	xdo,
		int	x,
		int	y
	)

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.

int xdo_mousemove_relative_to_window	(	const xdo_t *	xdo,
		Window	window,
		int	x,
		int	y
	)

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.

int xdo_mouseup	(	const xdo_t *	xdo,
		Window	window,
		int	button
	)

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.

xdo_t* xdo_new ( char * display )

Create a new xdo_t instance.

Parameters

display the string display name, such as ":0". If null, uses the environment variable DISPLAY.

Returns: Pointer to a new xdo_t or NULL on failure

xdo_t* xdo_new_with_opened_display	(	Display *	xdpy,
		const char *	display,
		int	close_display_when_freed
	)

Create a new xdo_t instance with an existing X11 Display instance.

Parameters

xdpy	the Display pointer given by a previous XOpenDisplay()
display	the string display name
close_display_when_freed	If true, we will close the display when xdo_free is called. Otherwise, we leave it open.

int xdo_set_active_modifiers	(	const xdo_t *	xdo,
		Window	window,
		const xdo_active_mods_t *	active_mods
	)

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.

int xdo_set_current_desktop	(	const xdo_t *	xdo,
		long	desktop
	)

Switch to another desktop.

Uses _NET_CURRENT_DESKTOP of the EWMH spec.

Parameters

desktop The desktop number to switch to.

int xdo_set_desktop_for_window	(	const xdo_t *	xdo,
		Window	wid,
		long	desktop
	)

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

int xdo_set_number_of_desktops	(	const xdo_t *	xdo,
		long	ndesktops
	)

Set the number of desktops.

Uses _NET_NUMBER_OF_DESKTOPS of the EWMH spec.

Parameters

ndesktops the new number of desktops to set.

const char** xdo_symbol_map ( void )

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.

int xdo_type	(	const xdo_t *	xdo,
		Window	window,
		char *	string,
		useconds_t	delay
	)

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

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.

int xdo_window_activate	(	const xdo_t *	xdo,
		Window	wid
	)

Activate a window.

This is generally a better choice than xdo_window_focus 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

int xdo_window_focus	(	const xdo_t *	xdo,
		Window	wid
	)

Focus a window.

See Also: xdo_window_activate

Parameters

wid	the window to focus.

int xdo_window_get_active	(	const xdo_t *	xdo,
		Window *	window_ret
	)

Get the currently-active window.

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

Parameters

window_ret Pointer to Window where the active window is stored.

int xdo_window_get_focus	(	const xdo_t *	xdo,
		Window *	window_ret
	)

Get the window currently having focus.

Parameters

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

int xdo_window_get_pid	(	const xdo_t *	xdo,
		Window	window
	)

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.

int xdo_window_map	(	const xdo_t *	xdo,
		Window	wid
	)

Map a window.

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

Parameters

wid	the window to map.

int xdo_window_move	(	const xdo_t *	xdo,
		Window	wid,
		int	x,
		int	y
	)

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.

int xdo_window_raise	(	const xdo_t *	xdo,
		Window	wid
	)

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.

int xdo_window_sane_get_focus	(	const xdo_t *	xdo,
		Window *	window_ret
	)

Like xdo_window_get_focus, 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.

int xdo_window_search	(	const xdo_t *	xdo,
		const xdo_search_t *	search,
		Window **	windowlist_ret,
		int *	nwindows_ret
	)

Search for windows.

Parameters

search	the search query.
windowlist_ret	the list of matching windows to return
nwindows_ret	the number of windows (length of windowlist_ret)

See Also: xdo_search_t

int xdo_window_setclass	(	const xdo_t *	xdo,
		Window	wid,
		const char *	name,
		const char *	class
	)

Change the window's classname and or class.

Parameters

name	The new class name. If NULL, no change. The new class. If NULL, no change.

int xdo_window_setprop	(	const xdo_t *	xdo,
		Window	wid,
		const char *	property,
		const char *	value
	)

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.
property	the string name of the property.
value	the string value of the property.

int xdo_window_setsize	(	const xdo_t *	xdo,
		Window	wid,
		int	w,
		int	h,
		int	flags
	)

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.

int xdo_window_translate_with_sizehint	(	const xdo_t *	xdo,
		Window	window,
		int	width,
		int	height,
		int *	width_ret,
		int *	height_ret
	)

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
width_ret	the return location of the translated width
height_ret	the return locatino of the translated height

int xdo_window_unmap	(	const xdo_t *	xdo,
		Window	wid
	)

Unmap a window.

Parameters

wid	the window to unmap

int xdo_window_wait_for_active	(	const xdo_t *	xdo,
		Window	window,
		int	active
	)

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.

int xdo_window_wait_for_focus	(	const xdo_t *	xdo,
		Window	window,
		int	want_focus
	)

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.

int xdo_window_wait_for_map_state	(	const xdo_t *	xdo,
		Window	wid,
		int	map_state
	)

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

wid	the window you want to wait for.
map_state	the state to wait for.

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation