emap - the event mapper for X

emap is a client for the X window system which listens for events such as certain keystrokes in the background and executes shell commands or takes other action in response. In addition to being able to create simple hotkeys, emap implements a prefix map, allowing sequences of keys to be bound to actions. emap also passes information on to shell commands via the environment, which lets commands change their behavior based on things such as the currently active application.

* Download Here *

Usage

 emap [-d <display>] -k

This will cause emap to spit out the symbols and modifiers of keys you press. this is purely informative for the user to find out what strings to use in the emap configuration files. Press the 'q' key to quit.

 emap [-d <display>] [-l <file>] [-o] [-v] [-f] <emap files...>

emap's default behavior is to merge all available configuration files and run in the background if there were no fatal errors. emap sources all files which end in .emap and are in the .emap.d or etc/emap.d directories off the users home directory, for example if ones home directory were /home/john then /home/john/etc/emap.d/user.emap would be one of the files read. The command line options modify this behavior as follows:

-o: only use the configuration files on the command line skipping any in the standard places if they exist.
-f: stay in the foreground, this can be useful in scripts when combined with the 'exit' and 'die' actions or to see the output of shell actions.
-v: produce very verbose output on the terminal. this implies -f.
-l <file>: send the output of executed command to file. This is only useful when run in the background, if no log file is set, then the output of commands is discarded.

Configuration

Here is an example of what might occur in a configuration file. text between /* and */ is a comment and ignored.

 key <mod1-a>  {
         string "env" exec env | sort
         string "xt"  exec xterm &
         string "mz"  exec mozilla &
 }
 
 /* this matches the PrintScr key with any modifiers */
 key <*-Print> exec echo DISPLAY=$DISPLAY SCREEN=$SCREEN  FOCUS_APP=$FOCUS_APP

Events

key events started with the 'key' identifier match a single keystroke, the format is <modifier-modifier-key> where key is the KeySym name and modifiers are one of the modifier keys or *, meaning any combination of modifiers. use emap -k to find out the names of keys you wish to map.

string events may only be used after a key event, and is an arbitrary string, the first to match exactly will be executed.

Actions

exec: execute a shell command. the command extends to the next newline. embedded newlines may be escaped by preceding them with a backslash.
exit, die: these cause emap to quit, exit causes it to return with a successful error code, and die with an unsuccessful one.

Environment

The following environment variables are set when an external program is called. they allow you to modify the behavior of your action depending on the state of the server and what app you are currently using.

E_ROOT: This is set to the numerical window id of the root window when the event occurred.
E_WINDOW: This is set to the numerical window id of the currently focused window, which may be a subwindow of another application.
E_MOUSE_WINDOW: This contains the window currently containing the mouse pointer. This may not be the same as E_WINDOW if you have a click-to-focus model.
E_APP_WINDOW: This is set to the numerical id of the top-level window of the currently focused window. by passing this to xprop, you can for example pull out the current URL a web browser is looking at.
E_KEY: Set to the key which caused this action to be executed.
E_STRING: Contains the string following the key which was typed to cause this action to be executed.
E_MOUSE_COORD: set to the coordinates of the mouse (relative to the root window) when the last key in the map was pressed.
E_APP_CLASS: this is set to the class/instance of the current application.
E_SCREEN: the current screen number
DISPLAY: DISPLAY is modified such that any apps started appear on the current screen.

Here are some examples of the environment settings shell commands will see.

 E_APP_CLASS=xterm/XTerm
 E_APP_WINDOW=12582950
 E_KEY=mod1-a
 E_MOUSE_COORD=196,1316
 E_MOUSE_WINDOW=12582950
 E_ROOT=63
 E_STRING=env
 E_WINDOW=12582950
 
 E_APP_CLASS=Mozilla/navigator:browser
 E_APP_WINDOW=14680179
 E_KEY=*-Print
 E_MOUSE_COORD=688,421
 E_MOUSE_WINDOW=14680179
 E_ROOT=63
 E_WINDOW=14680179
 
 E_APP_CLASS=gvim/Gvim
 E_APP_WINDOW=18874486
 E_KEY=*-Print
 E_MOUSE_COORD=520,954
 E_MOUSE_WINDOW=12582950
 E_ROOT=63
 E_WINDOW=18874486

files

The following files are searched for mappings. it is recommended to put personal settings in a file called user.emap

$HOME/.emap.d/*.emap
$HOME/etc/emap.d/*.emap

author

emap was written by John Meacham. It's homepage is http://repetae.net/computer/emap/

Send comments to john@repetae.net

Emap