| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
|---|
| 2 | <html> |
|---|
| 3 | <head> |
|---|
| 4 | <title>J User's Guide - Key Mappings</title> |
|---|
| 5 | <LINK REL="stylesheet" HREF="j.css" TYPE="text/css"> |
|---|
| 6 | </head> |
|---|
| 7 | <body> |
|---|
| 8 | <a href="contents.html">Top</a> |
|---|
| 9 | <hr> |
|---|
| 10 | <h1>Key Mappings</h1> |
|---|
| 11 | <hr> |
|---|
| 12 | <p> |
|---|
| 13 | J has both global and local key maps. There is a single global key map that |
|---|
| 14 | provides the default key mappings for all buffers. Each buffer also has a local |
|---|
| 15 | key map that depends on the <a href="modes.html">mode</a> of the buffer. A key |
|---|
| 16 | assignment defined in the local key map for a given buffer overrides any |
|---|
| 17 | assignment of the same key (or key combination) in the global key map. |
|---|
| 18 | <p> |
|---|
| 19 | Each entry in a key map defines a binding between a "key combination" and one |
|---|
| 20 | of j's commands. A key combination may be just a single keystroke, like |
|---|
| 21 | Backspace or Enter or F2. A key combination may also involve one or more of the |
|---|
| 22 | four modifier keys (Ctrl, Shift, Alt, and Meta), as in Shift F2 or Ctrl Alt S. |
|---|
| 23 | <p> |
|---|
| 24 | Every time you type a key or key combination, j begins by looking it up in the |
|---|
| 25 | local key map. If there's no entry for that key or key combination in |
|---|
| 26 | the local key map, j then looks in the global key map. If it's not found |
|---|
| 27 | there either, and if the key or key combination corresponds (in j's opinion) to |
|---|
| 28 | a "normal" character, that character is inserted in the buffer at the |
|---|
| 29 | location of the caret. |
|---|
| 30 | <p> |
|---|
| 31 | You can use the command <a href="commands.html#describeKey">describeKey</a>, |
|---|
| 32 | mapped by default to Alt K and available on the Help menu, to see what command |
|---|
| 33 | is mapped to a specific key or key combination in the current buffer. |
|---|
| 34 | <p> |
|---|
| 35 | Not all commands have key mappings by default. Even if a command is not mapped |
|---|
| 36 | to any key or key combination, you can use still execute it with |
|---|
| 37 | <a href="commands.html#executeCommand">executeCommand</a>, which is mapped by |
|---|
| 38 | default to Alt X and available on the File menu ("Execute Command..."). You |
|---|
| 39 | will be prompted to enter the name of the command in the location bar. |
|---|
| 40 | <p> |
|---|
| 41 | The commands <a href="commands.html#writeGlobalKeyMap">writeGlobalKeyMap</a> and |
|---|
| 42 | <a href="commands.html#writeLocalKeyMap">writeLocalKeyMap</a> may be used to |
|---|
| 43 | write out the current global or local key map, as the case may be, to a file |
|---|
| 44 | you specify, as ordinary text. |
|---|
| 45 | <p> |
|---|
| 46 | The command <a href="commands.html#listBindings">listBindings</a>, available |
|---|
| 47 | on the Help menu ("Key Bindings"), displays a list of all the key bindings in |
|---|
| 48 | effect in the current buffer. |
|---|
| 49 | <p> |
|---|
| 50 | All of j's key assignments may be changed by the user. To replace the global |
|---|
| 51 | key map, for example, add a line like this to your |
|---|
| 52 | <a href="preferences.html">preferences</a> file: |
|---|
| 53 | <pre> |
|---|
| 54 | globalKeyMap=/home/peter/.j/globalkeys |
|---|
| 55 | </pre> |
|---|
| 56 | This line instructs j to read its global key map from the specified file. This |
|---|
| 57 | file must be in the format written out by |
|---|
| 58 | <a href="commands.html#writeGlobalKeyMap">writeGlobalKeyMap</a> and |
|---|
| 59 | <a href="commands.html#writeLocalKeyMap">writeLocalKeyMap</a>. |
|---|
| 60 | <p> |
|---|
| 61 | You can also replace mode-specific key maps: |
|---|
| 62 | <pre> |
|---|
| 63 | JavaMode.keyMap=/home/peter/.j/javakeys |
|---|
| 64 | </pre> |
|---|
| 65 | If there's no entry in your preferences file for a particular key map, j will |
|---|
| 66 | use its built-in defaults. |
|---|
| 67 | <p> |
|---|
| 68 | The easiest way to customize a key map is to write out the corresponding |
|---|
| 69 | default key map using |
|---|
| 70 | <a href="commands.html#writeGlobalKeyMap">writeGlobalKeyMap</a> or |
|---|
| 71 | <a href="commands.html#writeLocalKeyMap">writeLocalKeyMap</a>, edit the |
|---|
| 72 | resulting file, and then add a line to your |
|---|
| 73 | <a href="preferences.html">preferences</a> file pointing to the modified key |
|---|
| 74 | map (as in the examples above). |
|---|
| 75 | <p> |
|---|
| 76 | Sometimes it may not be obvious what text string to use to specify a particular key |
|---|
| 77 | combination. You can use <a href="commands.html#insertKeyText">insertKeyText</a> |
|---|
| 78 | to insert the appropriate text string in the key map you're editing. |
|---|
| 79 | <p> |
|---|
| 80 | A very small number of commands (currently only |
|---|
| 81 | <a href="commands.html#insertString">insertString</a> and |
|---|
| 82 | <a href="commands.html#help">help</a>, but there will be more in the future) |
|---|
| 83 | require (or accept) an argument (which in the current implementation must be a |
|---|
| 84 | quoted string). Such commands can be added to a key map like this: |
|---|
| 85 | <pre> |
|---|
| 86 | Ctrl Alt X insertString("e.printStackTrace();") |
|---|
| 87 | </pre> |
|---|
| 88 | <p> |
|---|
| 89 | Key maps can contain blank lines and comments. A comment is any line whose |
|---|
| 90 | first non-whitespace character is '#'. |
|---|
| 91 | <p> |
|---|
| 92 | You can use the command |
|---|
| 93 | <a href="commands.html#reloadKeyMaps">reloadKeyMaps</a> to force j to reload |
|---|
| 94 | your key maps after you have edited them. |
|---|
| 95 | <p> |
|---|
| 96 | J will reload your key maps automatically after you edit them (and save the |
|---|
| 97 | changes) if you add this line to your |
|---|
| 98 | <a href="preferences.html">preferences</a> file: |
|---|
| 99 | <pre> |
|---|
| 100 | autoReloadKeyMaps = true</pre> |
|---|
| 101 | <p> |
|---|
| 102 | The command <a href="commands.html#defaultKeyMaps">defaultKeyMaps</a> discards |
|---|
| 103 | all custom key mappings and returns to j's internal defaults. |
|---|
| 104 | <p> |
|---|
| 105 | You can also use <a href="init.lisp.html">init.lisp</a> to make changes to |
|---|
| 106 | the default key mappings without having to define a full set of custom key |
|---|
| 107 | maps. |
|---|
| 108 | <p> |
|---|
| 109 | If you combine custom key maps with ad hoc mappings in init.lisp, note that |
|---|
| 110 | reloading a key map will discard any ad hoc mappings in the same scope. |
|---|
| 111 | </body> |
|---|
| 112 | </html> |
|---|
