In this post, I talk about one of my favorite utilities I use regularly – AutoKey. AutoKey is a real life saver and a great productivity boost for me. There are not much articles about AutoKey and even those few cover very few of its features. I intend to talk about some of my favorite features which I use regularly. I use AutoKey’s GTK version in Ubuntu but most of the points in the post will be applicable to other Linux variants and KDE.
What is AutoKey
AutoKey’s homepage describes it concisely as : "AutoKey is a desktop automation utility for Linux and X11. It allows the automation of virtually any task by responding to typed abbreviations and hotkeys. It offers a full-featured GUI that makes it highly accessible for novices, as well as a scripting interface offering the full flexibility and power of the Python language.".
If you have used AutoHotKey in Windows, then you will be immediately comfortable in AutoKey. (If not, you should check it out !) . AutoKey uses Python as the scripting language instead of AutoHotKey’s custom scripting language. But the potential and functionality are very similar.
AutoKey can be used in multiple scenarios :
a) Text Substitution : Replace a short abbreviation with a long expansion. Eg adr with your full address.
b) Hotkeys : If you are a keyboard person like me, use it open various program. For eg I use windows+c for opening chrome, windows+g to open gedit etc. Alternatively, you can make AutoKey "send" hotkeys to the applications. (Eg make it press ctrl+s automatically).
c) Automation : AutoKey supports Python scripts and has a very useful API’s to control windows, clipboard and mouse. So you can use it to automate any thing you can imagine !
The biggest advantage of AutoKey is that it works across all applications. So I can add a keyword which expands to a code snippet and use it in multiple applications – say in vim and also in gedit without any extra work.
Installation
You can read all about the utility at AutoKey’s homepage. The Google code page is the recent (and active) one even though most links in net points to a sourceforge page.
There are many ways to install AutoKey and it depends on your OS. For Ubuntu, the easiest way is to install using the update manager. I would suggest using the update manager as it will install the dependencies automatically. If you want to be in the latest code then the best solution is to add AutoKey PPA to your system. Instructions for adding the PPA is in the linked page. I would recommend getting the latest version (0.70) as it has lot of new features and some important bug fixes. Of course, if you use any other Linux variant, you can always install from AutoKey’s source at the download page.
Starting AutoKey
You can start AutoKey in Ubuntu by Applications -> Accessories -> AutoKey. Or in command line (for GTK) as /usr/bin/autokey-gtk. Once it is started , you will see an blue icon with "A" in the tray.
Once you start using AutoKey , you will prefer to start it when the system starts. For Ubuntu (GTK) AutoKey, System -> Preferences -> Startup Applications , enter "/usr/bin/autokey-gtk" as an additional startup entry. Note : AutoKey also has an option in its preference to start automatically but it did not work for me.
Some Basics
AutoKey appears in the tray as a blue colored icon with "A" in it. Most of the time, it runs passively , reading your keystrokes. Right click on the icon and make sure that the checkbox "Enable Expansions" is checked. Only then AutoKey will perform the expansions. To make any changes, you need to access its configuration dialog box. To get it , right click on the AutoKey icon and select "Configure".
The configure window will look like this. 
AutoKey Usage : Phrases
Phrases are the easiest way to start with AutoKey. You can consider this feature as a powerful text expansion. For eg you can enter the string "adr" and get it expanded to your whole address.
Phrases : Example 1
Lets take a simple example. Whenever I type the string "akr" , I want it to expand to "Auto key rocks !" . To get this , open the AutoKey config editor. Create a new phrase by File -> Create -> New Phrase (Or Ctrl + N) . Give the phrase a valid name. (Eg AutoKey). In the phrase box (the large text box – which is actually an editor !) , type "Auto Key Rocks !". In the "Phrase Settings" section, click on the "Set" button near "Abbreviation". Type the abbreviation as "akr" . Your screen will look like the image at the bottom. Click "OK" and click on "Save" button. Congrats , you have created your first phrase.
Lets now test it out. Open gedit (or kate or some editor) and type akr. Watch it expand to "Auto key rocks !". Now try it in vim. Try it in Firefox. Try it in Open Office. Watch it work at all the places.
Phrases : Example 2
Now let us make it slightly more complex. Lets say we want a tab in between each word. (Auto Key Rocks ! ). To do that, select the phrase you just created. In the editor box, type the following. "Auto<tab>Key<tab>Rocks<tab>!" . Thats right. When AutoKey sees <tab> it expands it to the actual tab character. Now save the phrase again and try it .
Tab is not the only hotkey that AutoKey supports. It supports virtually all the special keys in the keyboard. You can get all of them at AutoKey’s Hotkey’s page .
Phrases : Example 3
Another of my favorite feature is "Match phrase case to typed abbreviation" . To try it out, give "Auto Key Rocks !" (ie remove those tabs) in the editor box. Click on "Set" button of "Abbreviation" . Select the checkbox “Match phrase case to typed abbreviation". The next checkbox "Ignore case of typed abbreviation" should be automatically become checked. If not check it. Save the phrase. The dialog must look like the image below.
Now experiment with various ways of typing the abbreviation.
"akr" auto key rocks !
"Akr" Auto key rocks !
"AKr" Auto Key Rocks !
"AKR" AUTO KEY ROCKS !
Phrases : Example 4
Another thing to try is to give hotkey to the phrase. Of course, it does not make much sense for this small phrase. If you have a large paragraph and want it copied in a single command , then hotkey is the way to go. Again , hotkeys are very useful when using Scripts. (Which I will discuss shortly)
Before setting a hotkey, the usual caveats apply – make sure it does not clash with other applications’ functionality (Eg ctrl+s for expanding phrases is a bad idea !) . Also if you are using Hotkeys make sure it is memorable.
As a simple example, lets make "Auto key rocks" when we press ctrl+alt+q. To do that , click "Set" near "Hotkey". You will get a dialog. Click on "ctrl" , "alt". Now to set "Q" , click on "Press to set" and type "Q". Press "Ok" and save the phrase. Your screen will look the image below . Now type "ctrl+alt+q" in any application and watch it become "Auto key rocks !".
Phrases : Example 5
Let us suppose you want your abbreviation to work only in one application. This can be achieved using "Window Filter". Let us take an example. You want akr to be expanded in Gedit only. Notice that any document (new or existing) opened in Gedit ends with the word gedit. We will use that as our filter. To achieve that , select the phrase and click on "Set" near "Window Filter". Enter ".*gedit" as the filter. There are two things to note here .
a) The filter is actually a regular expression which has lot of expressive power.
b) The regular expression must match the whole window name. Just having "gedit" will not match a gedit window.
Phrases : Example 6
One of the common ways I use Phrase is to expand code snippets. For eg when I type cppincs , then I automatically the following snippet. It works whether in vim or in gedit. (If you use primarily vim, then checkout vim plugins like snippetsEmu or snipMate ).
#include <iostream>
#include <string>
#include <vector>
#include <set>
#include <map>
#include <algorithm>using namespace std;
int main()
{
return 0;
}
Phrases : Example 7
You can use AutoKey to enter username and password automatically. A simple example is to have a phrase like “username<tab>password<enter>”.
Misc Phrases Features
There are some other options in Phrases menu. These features are applicable to scripts also.
a) "Always Prompt before pasting this phrase" – If checked, when you type the abbreviation , you will see a confirm from AutoKey. Only when you confirm it will be expanded. I doubt , you will ever select it.
b) Show in Tray menu : If you select this option, your phrase will be visible when you right click on the AutoKey icon. I guess , this will be useful when you dont assign an abbreviation or hotkey for a phrase. But again, why will you ever do that ?
Misc Abbreviation Features
When you click on "Set" near "Abbreviation" you will see lot of options. Again, the same description applies to scripts also.
a) Remove typed abbreviation : It is usually checked. This means you are actually asking for a text substitution. ie "akr" becomes "Auto key rocks !" . If you uncheck it, then "akr" becomes "akrAuto Key Rocks !".
b) Omit trigger character : Typically the phrase is expanded when you type a space or press enter. If you select this option, they will be ignored.
c) We already discussed "Match phrase case to typed abbreviation" and "Ignore case of typed abbreviation" in Example 3.
d) "Trigger when typed as part of word" and "Trigger immediately" : These two work in conjunction. If both are checked, the abbreviation is expanded immediately without waiting for space or enter.
AutoKey Usage : Scripts
Scripts are the coolest feature in AutoKey. AutoKey uses Python as the scripting language for automation. If you don’t know Python, you should really learn it ! AutoKey has an excellent set of API to make your code a breeze. Scripts come into play when you want to do more complex things than simple substitution. Examples include : bringing the current time in the document automatically, adding selected word automatically to Google calendar etc. In fact you can even show some rudimentary GUI to user. Most of the features in scripts are similar to phrase features.
Scripts : Example 1
This example is from AutoKey’s sample scripts page. Lets say you want to bring the current date and time whenever you typed the word "date" in any application. File -> Create -> New Script (or Ctrl + Shift + n) . You will be see a editor with full Python code highlighting. Enter the following script
output = system.exec_command("date")
keyboard.send_keys(output)
The screen should look like this : 
Note that in this case, system was already imported. If you want to use some other package, you might want to import it first. Give "date" as the abbreviation. Save the script and type "date" in any application and watch it magically become current time (Eg Wed Apr 14 21:14:27 CDT 2010 ) . Of course, you can have a hotkey assigned for the script too !
Scripts : Example 2
One of my favorite way of using AutoKey is to use it as a way to invoke applications. I am more of a keyboard person and like to do everything without touching the mouse. For eg , when I press "super+c" , Chrome gets started. Lets try it now.
In a new script , press the following code and assign "super+c" as the hotkey. Super is nothing but the windows key on the keyboard. After saving it , when you press "windows(super) + c" , Chrome starts !
import subprocess
subprocess.Popen(["/usr/bin/google-chrome"])
You can note that there are two ways of invoking commands. "system" is the old way of invoking it. It works well when you want to wait for the output of the command. "subprocess" is much more flexible. I have used "Popen" which is typically used to start a program and you want to wait for it to end.
Scripts : Example 3
Alternatively, you might want to use AutoKey to open some folders or files based on a hotkey. Eg open your "Ubuntu One" folder with a hotkey or open some excel sheet. A generic way (Obtained from the discussion here ) is given below. xdg-open intelligently, opens the file/folder using the appropriate viewer/program.
import subprocess
subprocess.call([‘xdg-open’, ‘PATH_TO_FILE_OR_DIR’])
Scripts : Example 4
There are lot of interesting ways to use the full power of Python. Some clever usage can be seen at Favorite scripts 1 , and Favorite scripts 2 .
Scripts : Example 5
AutoKey has a powerful API to control windows, clipboard, mouse etc. For eg, you make a particular window come to foreground (see window.activate) , get the selected text, get contents of clipboard, add a text to clipboard etc. You can check the AutoKey API reference. You can also check out some sample scripts .
Another neat feature is to provide a lib folder and AutoKey will import all files in that folder. I have not tried this feature, but I think it should work. To get that Edit -> Preferences -> Script Engine.
Folders
AutoKey uses folders to organize the phrases and scripts. You can either create a new top level folder or some nested folders. This concept is quite easy to use. I group the phrases and scripts based on their functionality and intent. You can use any organization that works for you.
Trays
The concept of tray is another useful feature – Although, I rarely use it. There are two ways to add a phrase or script to the tray. First is to add the phrase/script within the "Tray Phrases" folder. Other way is to check the checkbox "Show in tray menu" (for both phrase and script). In both the scenarios, when you right click on the AutoKey icon, you will see them. My guess is that this will be useful if you did not set a hotkey or abbreviation.
Preferences
AutoKey has a intuitive preferences menu. Common things to do are :
a) Enable "Prompt for unsaved changes" checkbox in "General" tab. If unchecked, the phrase/script changes are automatically saved.
b) Also check "Enable undo by pressing backspace". This means when you want to type a text which is a abbreviation (eg akr) without getting expanded, then you type the string,let it expand and press the backspace immediately. It will give the abbreviation without the expansion.
c) Another thing to change is default hotkey to get AutoKey’s config window. It is usually ctrl+k which interferes with Firefox’s search button.
d) Check out other options and enable as you feel fit.
Miscellaneous Stuff
1. Autokey works by catching you keystrokes and doing the expansion or script execution. This has many implications which you will notice when you use AutoKey a lot. For eg when you copy paste a text with an abbreviation , it will not expand as you did not "type" it. Similarly you can cause a abbreviation to be not expanded if you use your left/right keys. Of course, using backspace within an abbreviation still results in proper expansion.
2. Previous versions of AutoKey had a nifty hotkey called cursor which will place the cursor at that position. It is not supported. For a workaround , see this Ubuntu forums thread. To give it here ,
firstPart = "First part of the text. Cursor ->"
secondPart = "<- second part"
keyboard.send_keys(firstPart + secondPart)
keyboard.send_key("<left>", len(secondPart))
3. If you want to see all the AutoKey topics and responses , check out their mailing list topics.
4. AutoKey now uses a json file for configuration. It is located at ~/.config/AutoKey/AutoKey.json. Enjoy playing with it ! This also means that if you want to use the same settings across users , just create a symlink to the same file. If you want to share across multiple machines use Dropbox or Ubuntu One. For more details, check this AutoKey thread.
5. If you face any issues when using it, follow the instructions at the Troubleshooting page before shooting a mail. That said, I have to say that AutoKey mailing list is very active and helpful !
6. This is a post from LifeHacker on snippits , another tool similar to AutoKey. I would not recommend it (as I had a hard time even installing it). But the point is , you should be able to use most of the things done in the video and more using AutoKey. Use that video as an exercise for testing your AutoKey skills 🙂
7. There is another project called IronAHK that is going on which brings AHK to Linux. It is not yet ready for prime time. If you are a AutoHotKey user , may be you will find it useful.
Good Discussions In AutoKey’s Mailing List
I notice that AutoKey’s mailing list occasionally bring up some creative way of using AutoKey. I hope to keep this section as a live one which catalogs the discussions that bring out a new facet of AutoKey. .
1. Can I exclude windows in Window Filter?
Yes. See here .
2. How to get a script to invoke an abbreviation ?
See here .
3. Restrictions in using modules in AutoKey scripts :
Acknowledgements
I have liberally used resources from AutoKey’s wiki pages and its mailing list. I learned lot of very interesting points from AutoKey’s mailing list. I have linked to some of them and given the essential point of the thread in some places. If you are using AutoKey , then you must join the list. It is a very helpful and active list.
In conclusion , AutoKey is a very neat utility . Clever use of it will tremendously improve your productivity. I hope this post helped to use it better ! Have fun with AutoKey !
Update [04-15-2010]: Corrected a mistake pointed out by Chris. If “Prompt for unsaved changes” checkbox is unchecked, changes are saved automatically. You don’t lose the changes as I wrote.
God, Your Book Is Great !! 