Key Mappings

J has both global and local key maps. There is a single global key map that provides the default key mappings for all buffers. Each buffer also has a local key map that depends on the mode of the buffer. A key assignment defined in the local key map for a given buffer overrides any assignment of the same key (or key combination) in the global key map.

Each entry in a key map defines a binding between a "key combination" and one of j's commands. A key combination may be just a single keystroke, like Backspace or Enter or F2. A key combination may also involve one or more of the four modifier keys (Ctrl, Shift, Alt, and Meta), as in Shift F2 or Ctrl Alt S.

Every time you type a key or key combination, j begins by looking it up in the local key map. If there's no entry for that key or key combination in the local key map, j then looks in the global key map. If it's not found there either, and if the key or key combination corresponds (in j's opinion) to a "normal" character, that character is inserted in the buffer at the location of the caret.

You can use the command describeKey, mapped by default to Alt K and available on the Help menu, to see what command is mapped to a specific key or key combination in the current buffer.

Not all commands have key mappings by default. Even if a command is not mapped to any key or key combination, you can use still execute it with executeCommand, which is mapped by default to Alt X and available on the File menu ("Execute Command..."). You will be prompted to enter the name of the command in the location bar.

The commands writeGlobalKeyMap and writeLocalKeyMap may be used to write out the current global or local key map, as the case may be, to a file you specify, as ordinary text.

The command listBindings, available on the Help menu ("Key Bindings"), displays a list of all the key bindings in effect in the current buffer.

All of j's key assignments may be changed by the user. To replace the global key map, for example, add a line like this to your preferences file:

    globalKeyMap=/home/peter/.j/globalkeys

You can also replace mode-specific key maps:

    JavaMode.keyMap=/home/peter/.j/javakeys

The easiest way to customize a key map is to write out the corresponding default key map using writeGlobalKeyMap or writeLocalKeyMap, edit the resulting file, and then add a line to your preferences file pointing to the modified key map (as in the examples above).

Sometimes it may not be obvious what text string to use to specify a particular key combination. You can use insertKeyText to insert the appropriate text string in the key map you're editing.

A very small number of commands (currently only insertString and help, but there will be more in the future) require (or accept) an argument (which in the current implementation must be a quoted string). Such commands can be added to a key map like this:

    Ctrl Alt X                      insertString("e.printStackTrace();")

Key maps can contain blank lines and comments. A comment is any line whose first non-whitespace character is '#'.

You can use the command reloadKeyMaps to force j to reload your key maps after you have edited them.

J will reload your key maps automatically after you edit them (and save the changes) if you add this line to your preferences file:

    autoReloadKeyMaps = true

The command defaultKeyMaps discards all custom key mappings and returns to j's internal defaults.

You can also use init.lisp to make changes to the default key mappings without having to define a full set of custom key maps.

If you combine custom key maps with ad hoc mappings in init.lisp, note that reloading a key map will discard any ad hoc mappings in the same scope.