xmacro tutorial

UPDATE: xmacro is apparently working on Ubuntu 11.04 and subsequent releases now.

UPDATE2: added xmousepos instructions, some other changes.

I'm a huge fan of AutoHotkey. It's an open-source (GPL) program for automating repetitive keystroke and mouse functions. I use it at work for logging onto websites that have multiple login pages as well as data entry. Problem is, it's only written for Windows. There aren't many good Linux equivalents, but I've found one that works if you're willing to experiment with it, and it comes with many distros. It's a series of several small programs collectively called xmacro.

It's a nifty little automation program, but it's all command-line and has some (to me) very strange record and playback characteristics. I'd like to share my limited experience so that any other newbies with the same need might try to take the plunge.

If you're using Linux, I'll assume you know how to install from source files or repositories. (If you have any questions, please feel free to write me.)

The first thing to do is to either record a macro or write one from scratch. Recording the macro was a terribly frustrating experience for me, and I still have no clue how to do it properly, but it's a good starting point for the exercise. To record the mouse movements and keystrokes on your current display, open a terminal window and enter the following:

~$ xmacrorec > testing.macro :0

Press the key you want to use to end the application. This key can be any key,
as long as you don't need it while working with the remote display.
A good choice is Escape.

Humor them. Hit the Esc key. Just remember which key you pressed, because you'll need it!

The chosen quit-key has the keycode: 9
XTest for server ":0.0" is version 2.2.

Skipping stale KeyRelease event. 1
Skipping stale KeyRelease event. 0

Now, what I discovered at this point is that 1) my mouse pointer was moving around on its own in tiny circles and 2) I could not control it at all. I also hit a few keys with no effect whatsoever. (If anyone knows how to keep this from happening, I'd be grateful for some advice.) Even after I hit Escape, the program took a couple of seconds to finally display this:

xmacrorec: pointer and keyboard released.

and gave me back control of the pointer.

So, what got recorded? Here's part of the output of testing.macro. You can see I was hitting a lot of keys randomly and moving the mouse around, even though I did not affect anything on the display as far as I could tell:


MotionNotify 920 601
ButtonPress 1
MotionNotify 920 589
MotionNotify 942 611
MotionNotify 942 603
MotionNotify 938 593
MotionNotify 968 613
MotionNotify 964 605
MotionNotify 964 605
ButtonRelease 1
MotionNotify 886 637
KeyStrPress q
MotionNotify 870 639
KeyStrRelease q
MotionNotify 906 635
KeyStrPress q
MotionNotify 982 617
KeyStrRelease q
MotionNotify 979 598
KeyStrPress q
MotionNotify 901 603
KeyStrRelease q
MotionNotify 840 562
KeyStrPress l
MotionNotify 875 598
KeyStrPress s
KeyStrPress d
MotionNotify 840 578
KeyStrRelease l
MotionNotify 806 560
KeyStrRelease s
KeyStrRelease d
MotionNotify 877 600
KeyStrPress h
MotionNotify 863 610
KeyStrRelease h
MotionNotify 883 601
KeyStrPress l
MotionNotify 881 601
KeyStrPress s
MotionNotify 901 609
KeyStrRelease l
MotionNotify 885 605
KeyStrPress h
MotionNotify 883 605
KeyStrRelease s
KeyStrPress v
MotionNotify 873 609
KeyStrRelease h
MotionNotify 931 612
KeyStrRelease v
MotionNotify 903 612
KeyStrPress semicolon
MotionNotify 925 622
KeyStrPress l
MotionNotify 901 626
KeyStrRelease semicolon
KeyStrRelease l
ButtonPress 1
KeyStrPress h
KeyStrPress v
KeyStrRelease h
KeyStrRelease v
KeyStrPress semicolon
There was a lot more wild flailing recorded, but this gives you the idea.

For the macro to be useful, it needs to be written from scratch. Fortunately, this is not too difficult. The output above gives many useful hints about how xmacro records keystrokes and mouse actions. In fact, the xmacro documentation, such as it is, says the "standard KeySym names are obtained from [X11/keysymdef.h] by removing the XK_ prefix from each name." In my distro (Ubuntu), the file is located at /usr/include/X11/keysymdef.h (just type "locate keysymdef.h"). Examining the file reveals that the authors of xmacro weren't kidding, it's all there.

So now you've got a reference for the keystrokes and mouse movements. It's now a good idea to decide what you want to accomplish and map out the macro from there, as opposed to trying to record your keystrokes blindly.

How do you determine where the mouse is supposed to click? I use xmousepos, part of the xautomation package. Install xautomation, open a terminal, type "xmousepos", place your cursor where you need the position and hit "Enter". The program will return four numbers. The first two are the mouse position in absolute coordinates (on the monitor) and the last two are the relative coordinates (in the window). I'd use the absolute coordinates.

For my first project, I wanted to copy text from a series of web pages and paste the text into another document. I quickly discovered that with no way (to my knowledge) of defining which window I wanted to make active, it was best to have the terminal open on the first workspace, the browser (with all of the pages open in separate tabs) on the second workspace, and the destination file (plain text) on the third workspace. I would then select the text I wanted to copy, switch to the first workspace, and run the macro. The macro would switch to the second workspace, copy the text, move to the third workspace, paste the text, add a return, switch back to the second workspace, close the tab, and position the mouse so I could select the next batch of text to copy.

Here's the macro (topten.macro) I wrote, with annotations in parens. It's a plain text file.

KeyStrPress Control_L    (the first three entries are a Ctrl+Alt+Right, to switch to the second workspace)
KeyStrPress Alt_L
KeyStrPress Right
KeyStrRelease Right    (the next three release the keys in reverse order--very important to release the keys!)
KeyStrRelease Alt_L
KeyStrRelease Control_L

KeyStrPress Control_L    (these two simply do a Ctrl-c to copy the previously selected text)
KeyStrPress c
KeyStrRelease c
KeyStrRelease Control_L

KeyStrPress Control_L    (now switch to the third workspace...)
KeyStrPress Alt_L
KeyStrPress Right
KeyStrRelease Right
KeyStrRelease Alt_L
KeyStrRelease Control_L

KeyStrPress Control_L    (and paste.)
KeyStrPress v
KeyStrRelease v
KeyStrRelease Control_L
KeyStrPress KP_Enter    ("Enter" would work just as well here)
KeyStrRelease KP_Enter

KeyStrPress Control_L    (now switch back to the second workspace...)
KeyStrPress Alt_L
KeyStrPress Left
KeyStrRelease Left
KeyStrRelease Alt_L
KeyStrRelease Control_L

KeyStrPress Control_L    (and close the tab with Ctrl+w)
KeyStrPress w
KeyStrRelease w
KeyStrRelease Control_L

MotionNotify 495 410    (move the mouse to where you want it for the next round)

Like I said, it's best if you know what you want to do and what keystrokes you need in advance.

So, how do you run this thing? It has to be read by the program, so enter the following in the terminal:

cat test.macro | xmacroplay -d 100 :0

The "-d 100" is a delay in milliseconds between commands. The ":0" tells xmacro which display to run the macro on.

BTW, it worked exactly as designed, and I wound up with all of the text in one document.

I hope this was helpful. From the documentation, it looks like there are many ways to simplify the keystroke definitions in the macro, but this worked fine for my first attempt. Overall, I'm very pleased, now that I have a small clue!