The API examples shown here are for AutoKey-GTK.

The examples show how to use the various API calls that AutoKey provides.

The example types are as follows:

• Clipboard
• Dialogs
• Engine
• Keyboard
• Mouse
• Store
• System
• Window

• fill_clipboard
• fill_selection
• get_clipboard
• get_selection

fill_clipboard copies the supplied text into the clipboard.

The script does the following:

1. Copies the text 'Hello World' to the clipboard.

2. Waits 0.2 seconds for the clipboard operation to finish. This wait is unlikely to be necessary for small amounts of text, but clipboard operations can be slow.

3. Fetches the text from the clipboard and displays it in an info dialog.

import time
toClip = 'Hello World'
clipboard.fill_clipboard(toClip)

time.sleep(0.2)
fromClip = clipboard.get_clipboard()

dialog.info_dialog(title='Clipboard contents', 
    message=fromClip, width='200') # width is extra Zenity parameter 

fill_selection copies text into the X selection, that is the X11 PRIMARY selection (Technical specification).

The script does the following:

1. Takes the text 'Hello World' and copies it to the PRIMARY selection buffer as the upper case text 'HELLO WORLD'.

2. Waits 0.2 seconds for the clipboard operation to finish. This wait is unlikely to be necessary for small amounts of text, but clipboard operations can be slow.

3. Presses the middle mouse button to paste the text from the selection buffer.

import time
cb = 'hello world'
clipboard.fill_selection(cb.upper())
time.sleep(0.2)
# click on the current cursor position
mouse.click_relative_self(0, 0, 2)  # button 2 is the middle mouse button

The script does the following:

1. Uses get_clipboard to copy the text that is on the clipboard.

2. Waits 0.2 seconds for the clipboard operation to finish. This wait is unlikely to be necessary for small amounts of text, but clipboard operations can be slow.

3. Sends the text the current application as upper case text.

import time
cb = clipboard.get_clipboard()
time.sleep(0.2)
keyboard.send_keys(cb.upper())

The script does the following:

1. Copies the selected text from the current application. If there is an error, the script displays an info dialog that says 'No text selected'.

2. Waits 0.2 seconds for the clipboard operation to finish. This wait is unlikely to be necessary for small amounts of text, but clipboard operations can be slow.

3. Shows the copied text in an info dialog.

import time
try:
    selText = clipboard.get_selection()
    time.sleep(0.2)
    dialog.info_dialog(title='Text from selection', message=selText) 

except:
    dialog.info_dialog(title='No text selected', 
    message='No text in X selection') 

• Calendar dialog
• Directory Chooser dialog
• Information dialog
• Input dialog
• Multiple-selection list menu
• Open File dialog
• Password input dialog
• Save As dialog
• Single-selection list menu

The script does the following:

1. Displays a save as file dialog.

   The dialog returns a tuple that contains the following:

   • An integer value that shows the exit value from the script. This value is 0 for success, an integer for error.

   • A string value that contains the date that was specified on the dialog, using the format YYYY-MM-DD.

2. Displays an information dialog to show one of the following:

   • The error code, if any, from the save as file dialog.

   • The date that was specified on the dialog.

retCode, date = dialog.calendar(title='Choose a date')
if retCode:
	myMessage = 'Dialog exit code was: ' + str(retCode)
	dialog.info_dialog(title='You cancelled the dialog', 
	message=myMessage, 
	width='200')  
            # width is extra zenity parameter. See the zenity manpage for details.
            # this is our fancy faux way of saying:  THIS code BREAKS. it is worthless.


else:
	dialog.info_dialog(title='The date you chose was', message=date)

tuple(int, str) choose_directory(self, title='Select Directory', initialDir='~', **kwargs)

This script does the following:

1. Displays a directory chooser dialog.

   The dialog returns a tuple that contains the following:

   • An integer value that shows the exit value from the script. This value is 0 for success, an integer for error.

   • A string value that contains the full path of the directory that was specified on the dialog.

2. Displays an information dialog to show one of the following:

   • The error code, if any, from the directory chooser dialog.

   • The full path of the directory that was specified on the dialog.

retCode, dirName = dialog.choose_directory(title='Choose a directory')

if retCode:
	myMessage = 'Dialog exit code was: ' + str(retCode)
	dialog.info_dialog(title='You cancelled the dialog', 
	message=myMessage, 
	width='200') # width is extra zenity parameter. See the zenity manpage for details.

else:
	dialog.info_dialog(title='The directory you chose was', message=dirName)

This script displays an information dialog.

weather = 'Sunny with some showers'
retCode, user = dialog.info_dialog(title='Weather Forecast', message=weather)

myMessage = retCode + user
dialog.info_dialog(title='Weather Forecast', message=myMessage)

This script does the following:

1. Displays an input dialog.

   The Input dialog returns a tuple that contains the following:

   • An integer value that shows the exit value from the script. This value is 0 for success, an integer for error.

   • A string value that contains the text that was entered on the input dialog.

2. Displays an information dialog to show one of the following:

   • The error code, if any, from the input dialog.

   • The text that was entered on the input dialog.

retCode, userInput = dialog.input_dialog(title='Input required',
	message='Enter a string', 
	default='My string')

if retCode:
	myMessage = 'Dialog exit code was: ' + str(retCode)
	dialog.info_dialog(title='You cancelled the dialog', 
	message=myMessage, width='200') # width is extra zenity parameter 
else:
	dialog.info_dialog(title='The string you entered', message=userInput)  # **

This script does the following:

1. Displays a multiple-selection list.

   The multiple-selection list returns a tuple that contains the following:

   • An integer value that shows the exit value from the script. This value is 0 for success, an integer for error.

   • A list of string values, each one of which is the text of an option that was selected on the dialog.

2. Displays an information dialog to show one of the following:

   • The error code, if any, from the multiple-selection list.

   • A list that contains the text of each item that was selected on the multiple-selection list.

optionShapes = ['Square', 'Triangle', 'Rectangle']

retCode, choices = dialog.list_menu_multi(options=optionShapes, 
	title='Choose all shapes that have four sides', 
	message='Shapes',
	defaults='Square,Rectangle', 
	height='250') # height is extra zenity parameter. See the zenity manpage for details.

if retCode:
	myMessage = 'Dialog exit code was: ' + str(retCode)

	dialog.info_dialog(title='You cancelled the dialog', 
	message=myMessage, 
	width='200')  # width is extra zenity parameter. See the zenity manpage for details.

else:
	myMessage = ''
	for item in choices:
		myMessage = myMessage + '\n' + item

	dialog.info_dialog(title='Your choice was', message=myMessage)

This script does the following:

1. Displays an open file dialog.

   The dialog returns a tuple that contains the following:

   • An integer value that shows the exit value from the script. This value is 0 for success, an integer for error.

   • A string value that contains the full path of the file that was specified on the dialog.

2. Displays an information dialog to show one of the following:

   • The error code, if any, from the open file dialog.

   • The full path of the file that was specified on the dialog.

retCode, fName = dialog.open_file(title='Open File')

if retCode:
	myMessage = 'Dialog exit code was: ' + str(retCode)
	dialog.info_dialog(title='You cancelled the dialog', 
	message=myMessage, 
	width='200')  # width is extra zenity parameter. See the zenity manpage for details.

else:
	dialog.info_dialog(title='The file you chose was', message=fName)

This script does the following:

1. Displays a password input dialog.

   The password input dialog returns a tuple that contains the following:

   • An integer value that shows the exit value from the script. This value is 0 for success, an integer for error.

   • A string value that contains the plain text password that was entered on the dialog.

2. Displays an information dialog to show one of the following:

   • The error code, if any, from the password input dialog.

   • The password that was entered on the password input dialog.

retCode, pwd = dialog.password_dialog(title='Enter password', message='Enter password')

if retCode:
	myMessage = 'Dialog exit code was: ' + str(retCode)
	dialog.info_dialog(title='You cancelled the dialog', 
	message=myMessage, width='200') # width is extra Zenity parameter 
else:
	dialog.info_dialog(title='The password you entered', message=pwd)

This script does the following:

1. Displays a save as file dialog.

   The dialog returns a tuple that contains the following:

   • An integer value that shows the exit value from the script. This value is 0 for success, an integer for error.

   • A string value that contains the full path of the file that was specified on the dialog.

2. Displays an information dialog to show one of the following:

   • The error code, if any, from the save as file dialog.

   • The full path of the file that was specified on the dialog.

retCode, fName = dialog.open_file(title='Save As')

if retCode:
	myMessage = 'Dialog exit code was: ' + str(retCode)
	dialog.info_dialog(title='You cancelled the dialog', 
	message=myMessage, 
	width='200') # width is extra zenity parameter. See the zenity manpage for details.

else:
	dialog.info_dialog(title='You chose to save file', message=fName)

This script does the following:

1. Displays a single-selection list.

   The single-selection list menu returns a tuple that contains the following:

   • An integer value that shows the exit value from the script. This value is 0 for success, an integer for error.

   • A string value that contains the text of the selection from the dialog.

2. Displays an information dialog to show one of the following:

   • The error code, if any, from the single-selection list.

   • The text of the item that was selected on the single-selection list.

optionColours = ['Blue', 'Red', 'Green', 'Yellow']

retCode, choice = dialog.list_menu(options=optionColours, 
	title='Choose your favourite colour', 
	message='Colours', 
	default=None,
	width='200',  # width is an extra zenity parameter. See the zenity manpage for details.
	height='250') # height is an extra zenity parameter. See the zenity manpage for details.

if retCode:
	myMessage = 'Dialog exit code was: ' + str(retCode)
	dialog.info_dialog(title='You cancelled the dialog', 
	message=myMessage, 
	width='200')  # width is an extra zenity parameter. See the zenity manpage for details.

else:
	dialog.info_dialog(title='Your choice was', message=choice)

• run_script

This script does the following:

• Runs the foo AutoKey script from any other script.
• Raises an exception if the foo script doesn't exist.

engine.run_script("foo")

• Fake key press
• Press key
• Release key
• Send key
• Send keys
• Wait for key press

Fake key presses can be useful to send key presses if an application does not respond to Send key.

This script sends '<down>' five times.

keyboard.fake_keypress('<down>', repeat=5)

press_key makes AutoKey hold down a key until it is specifically released.

This script presses <ctrl>, then sends 'd' five times, and then releases <ctrl>.

See Release key

keyboard.press_key('<ctrl>')
keyboard.send_key('d', repeat=5)
keyboard.release_key('<ctrl>')

release_key releases a key that has previously been pressed by press_key.

See Press_key

keyboard.press_key('<ctrl>')
keyboard.fake_keypress('d', repeat=5)
keyboard.release_key('<ctrl>')

send_key sends a single keystroke one or more times.

send_key doesn't press the Shift key on keys that have more than one value on them, so those will be lower-case.

Since send_key sends a single keystroke, you cannot use it on its own to send keys that are modified with Ctrl, Shift, or Alt, for example. If you want to use modifiers, use either send_keys or press_key.

The script sends 'z' three times.

keyboard.send_key('z',repeat=3)

send_keys sends a sequence of keystrokes.

send_keys presses the Shift key on keys that have more than one value on them, so those will be upper-case. Single-value keys will be lower-case even if the Caps Lock key is enabled. If you want to send single-value keys in upper-case, tell AutoKey to send a press of the Shift key before a press of the single-value key.

The script sends 'Hello World!'.

keyboard.send_keys('Hello World!')

This script does the following:

1. Waits for the user to press <ctrl>+d.

   The function returns a boolean.

2. Displays an information dialog to show one of the following:

   • The error code, if any, from the wait_for_keypress function.

   • A message to say that you have pressed <ctrl>+d.

You cannot use this function to wait for modifier keys, such as <ctrl>, on their own

retCode = keyboard.wait_for_keypress('d',modifiers=['<ctrl>'],timeOut=5)

if retCode:
	myMessage = 'Wait for keypress exit code was: ' + str(retCode)
	dialog.info_dialog(title='You pressed <ctrl>+d', 
	message=myMessage, 
	width='200') # width is extra Zenity parameter.  See the zenity manpage for details.
else:
	myMessage = 'Wait for keypress exit code was: ' + str(retCode)
	dialog.info_dialog(title='Timeout', message=myMessage)

• Click_absolute
• Click_relative
• Click_relative_self
• Wait_for_click

click_absolute sends a mouse click relative to the whole screen.

The script clicks the left mouse button at position x=200, y=300 relative to the screen.

# mouse buttons: left=1, middle=2, right=3
mouse.click_absolute(200, 300, 1)

click_relative sends a mouse click relative to the active window.

The script clicks the left mouse button at position x=200, y=300 on the current window.

# mouse buttons: left=1, middle=2, right=3
mouse.click_relative(200, 300, 1)

click_relative sends a mouse click relative to the current mouse cursor position.

The script waits for 4 seconds and then clicks the left mouse button at position x=100, y=150 relative to the current mouse cursor position.

import time
time.sleep(4)
# mouse buttons: left=1, middle=2, right=3
mouse.click_relative_self(100, 150, 1)

wait_for_click waits for a mouse button to be clicked. You specify which mouse button to wait for and the maximum time to wait.

The script waits for a maximum of 10 seconds for a left click. When the click is detected the script displays a dialog.

# mouse buttons: left=1, middle=2, right=3
mouse.wait_for_click(1, timeOut=10)
dialog.info_dialog(title='Click detected', message='You clicked the left button')

• Get global value
• Get value
• Has key
• Remove global value
• Remove value
• Set global value
• Set value
• Example

This script sets global value "myValue" to "hello" and then gets the value that has been set and displays it in an info dialog.

Global values can be accessed by all AutoKey scripts. The values are available in future AutoKey sessions.

store.set_global_value("myValue","hello")
x = store.get_global_value("myValue")
dialog.info_dialog(title='Value of global value myValue', 
    message=x, width='200') 

This script sets local value "myLocalValue" to "My local value" and then gets the value that has been set and displays it in an info dialog.

Local script variables can be accessed only by the script that wrote them. The values are available in future AutoKey sessions.

Script variables can be accessed only by the script that wrote them. The values are available in future AutoKey sessions.

store.set_value("myValue","hello")
x = store.get_value("myValue")
dialog.info_dialog(title='Value of local value myValue', 
    message=x, width='200') 

This script checks to see if a value has been stored by checking to see if the key is defined. This function makes no differentiation between a local and global value in regards to the Store. The function returns a boolean of true or false.

if store.has_key("myValue"):
    dialog.info_dialog(title="Value Exists?",message="true")

This script does the following:

1. Sets global value "myValue" to "hello"

2. Gets the value that has been set and displays it in an info dialog

3. Removes global value "myValue"

4. Attempts to get the value of "myValue", but fails because "myValue" no longer exists.

store.set_global_value("myValue","hello")
x = store.get_global_value("myValue")

dialog.info_dialog(title='Value of global value myValue', 
    message=x, width='200') # width is extra Zenity parameter 

store.remove_global_value("myValue")

try:
    y = store.get_global_value("myValue")
    dialog.info_dialog(title='Value of global value myValue', 
        message=y, width='200') # width is extra Zenity parameter 

except TypeError:
    dialog.info_dialog(title='Global value myValue', 
        message="myValue does not exist", width='200') # width is extra Zenity parameter 

This script does the following:

1. Sets local value "myValue" to "hello"

2. Gets the value that has been set and displays it in an info dialog

3. Removes local value "myValue"

4. Attempts to get the value of "myValue", but fails because "myValue" no longer exists.

store.set_value("myValue","hello")
x = store.get_value("myValue")

dialog.info_dialog(title='Value of local value myValue', 
    message=x, width='200') # width is extra Zenity parameter 

store.remove_value("myValue")

try:
    y = store.get_value("myValue")
    dialog.info_dialog(title='Value of local value myValue', 
        message=y, width='200') # width is extra Zenity parameter 

except TypeError:
    dialog.info_dialog(title='Local value myValue', 
        message="myValue does not exist", width='200') # width is extra Zenity parameter 

This script sets global value "myValue" to "hello" and then gets the value that has been set and displays it in an info dialog.

store.set_global_value("myValue","hello")
x = store.get_global_value("myValue")
dialog.info_dialog(title='Value of global value myValue', 
    message=x, width='200') 

This script sets local value "myLocalValue" to "My local value" and then gets the value that has been set and displays it in an info dialog.

Local script variables can be accessed only by the script that wrote them. The values are available in future AutoKey sessions.

store.set_value("myValue","hello")
x = store.get_value("myValue")
dialog.info_dialog(title='Value of local value myValue', 
    message=x, width='200') 

• Create_file
• Exec_command

create_file creates a file in the file system with the specified contents, if any.

The script creates file /tmp/myFile.txt with the contents "Hello World".

system.create_file('/tmp/myFile.txt', contents='Hello World')

exec_command executes a system command.

The script executes the command 'ls /tmp' and captures the output. The script then saves the listing to file '/tmp/myListing.txt'.

output = system.exec_command('ls /tmp/', getOutput=True)
system.create_file('/tmp/myListing.txt', contents=output)

• Activate window
• Close window
• Get class of active window
• Get title of active window
• Get window geometry
• Move window to different desktop
• Resize or move window
• Set window property
• Switch to different desktop
• Wait for window to exist
• Wait for window to have focus

Script 1 activates the window with 'Atom' as part of the window title. If the window is on a different desktop the script automatically changes to that desktop.

Script 2 activates the window with 'atom.Atom' as its class name.

window.activate('Atom', switchDesktop=True)

window.activate('atom.Atom', switchDesktop=True, matchClass=True)

Script 1 closes the window with 'Atom' as part of the window title.

Script 2 closes the window with 'atom.Atom' as its class name.

window.close('Atom')

window.close('atom.Atom', matchClass=True)

This script gets the class of the active window and then displays it in an info dialog.

winClass = window.get_active_class()
dialog.info_dialog(title='Window class', message=winClass)

This script gets the title of the active window and then displays it in an info dialog.

winTitle = window.get_active_title()
dialog.info_dialog(title='Window title', message=winTitle)

This script gets the geometry of the active window and then displays an info dialog that shows the values.

geo = window.get_active_geometry()
    winGeometry = 'X-origin: %s\nY-origin: %s\nWidth: %s\nHeight: %s'  %(geo[0], geo[1], geo[2], geo[3])
    dialog.info_dialog(title='Window geometry', message=winGeometry)

This script moves the 'Unsaved Document' window to desktop three.

window.move_to_desktop('Unsaved Document', 3, matchClass=False) # desktop number is an integer. The first desktop is 0.

This script maximizes horizontally the 'Unsaved Document' window.

window.set_property('Unsaved Document', 'add','maximized_horz', matchClass=False)

This script switches focus to desktop two.

window.switch_desktop(2) # The first desktop is 0.

This script waits up to five seconds for a specified window to exist and then displays an info dialog that shows the exit code.

The exit code is True if the window has focus, False if the script times out.

retCode = window.wait_for_exist('Unsaved Document', timeOut=5)
myMessage = 'Exit code was: ' + str(retCode)
dialog.info_dialog(title='Exit code', message=myMessage)

This script waits five seconds for the Thunderbird window to have focus and then displays an info dialog that shows the exit code.

The exit code is True if the window has focus, False if the script times out.

retCode = window.wait_for_focus('.*Thunderbird', timeOut=5)
myMessage = 'Exit code was: ' + str(retCode)
dialog.info_dialog(title='Exit code', message=myMessage)

This script resizes the 'Unsaved Document' window.

window.resize_move('Unsaved Document', xOrigin=20, yOrigin=20, width=200, height=200, matchClass=False)