--- rxvt-unicode/doc/rxvt.1.pod 2014/04/26 14:07:36 1.227 +++ rxvt-unicode/doc/rxvt.1.pod 2014/04/27 19:43:46 1.228 @@ -1043,78 +1043,82 @@ @@RXVT_NAME@@ to start. If it isn't specified then the current working directory will be used; option B<-cd>. -=item BI: I +=item BI: I -Compile I: Associate I with keysym I. The -intervening resource name B cannot be omitted. +Compile I: Associate I with keysym I. The intervening +resource name B cannot be omitted. -The format of I is "I<(modifiers-)key>", where I can be -any combination of B, B, B, B, -B, B, B, B, B, B, B, B, -and the abbreviated B, B, B, B, B, B, B, B, B<1>, -B<2>, B<3>, B<4>, B<5>. +Using this resource, you can map key combinations such as +C to various actions, such as outputting a different +string than would normally result from that combination, making the +terminal scroll up or down the way you want it, or any other thing an +extension might provide. + +The key combination that triggers the action, I, has the following format: + + (modifiers-)key + +Where I can be any combination of B, B, +B, B, B, B, B, B, B, +B, B, B, and the abbreviated B, B, B, B, +B, B, B, B, B<1>, B<2>, B<3>, B<4>, B<5>. The B, B and B modifiers are usually aliased to whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr keys are being mapped. B is a synthetic modifier mapped to the current application keymap mode state. -The spellings of I can be obtained by using B(1) command or -searching keysym macros from B and -omitting the prefix B. Alternatively you can specify I by its hex -keysym value (B<0x0000 - 0xFFFF>). Note that the lookup of Is is not -performed in an exact manner; however, the closest match is assured. +Due the the large number of modifier combinations, a key mapping will +match if I the specified identifiers are being set, and no other +key mappings with those and more bits are being defined. That means that +defining a mapping for C will automatically provide definitions for +C, C and so on, unless some of those are defined mappings +themselves. See the C action, below, for a way to work around +this when this is a problem. + +The spelling of I depends on your implementation of X. An easy way to +find a key name is to use the B(1) command. You can find a list by +looking for the C macros in the B include file (omit +the C prefix). Alternatively you can specify I by its hex keysym +value (B<0x0000 - 0xFFFF>). -I may contain escape values (C<\n>: newline, C<\000>: octal +As with any resource value, the I string may contain backslash +escape sequences (C<\n>: newline, C<\\>: backslash, C<\000>: octal number), see RESOURCES in C for further details. -You can define a range of keysyms in one shot by -loading the C perl extension and providing a I -with pattern B, where the delimiter `/' -should be a character not used by the strings. +An action starts with an action prefix that selects a certain type +of action, followed by a colon. An action strings without colons is +interpreted as a literal string to pass to the tty (as if they were +prefixed with C). -Its usage can be demonstrated by an example: +The following action prefixes are known - extensions can provide +additional prefixes: - URxvt.keysym.M-C-0x61: list|\033<|abc|> +=over 4 -The above line is equivalent to the following three lines: +=item string:STRING - URxvt.keysym.Meta-Control-0x61: \033 - URxvt.keysym.Meta-Control-0x62: \033 - URxvt.keysym.Meta-Control-0x63: \033 +If the I starts with C (or otherwise contains no colons), +then the remaining C will be passed to the program running in the +terminal. For example, you could replace whatever Shift-Tab outputs by the +string C followed by a newline: -If I takes the form of C, the specified B -is interpreted and executed as @@RXVT_NAME@@'s control sequence. For -example the following means "change the current locale to C -when Control-Meta-c is being pressed": + URxvt.keysym.Shift-Tab: string:echo rm -rf /\n - URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007 +This could in theory be used to completely redefine your keymap. -If I takes the form C, then the specified B -is passed to the C perl handler. See the @@RXVT_NAME@@perl(3) -manpage. For example, the F extension (activated via -C<@@RXVT_NAME@@ -pe selection>) listens for C events: - - URxvt.keysym.M-C-c: perl:selection:rot13 - -Due the the large number of modifier combinations, a defined key mapping -will match if I the specified identifiers are being set, and -no other key mappings with those and more bits are being defined. That -means that defining a key map for C will automatically provide -definitions for C, C and so on, unless some of those are defined -mappings themselves. - -Unfortunately, this will override built-in key mappings. For example -if you overwrite the C key you will disable @@RXVT_NAME@@'s -C mapping. To re-enable that, you can poke "holes" into the -user-defined keymap using the C replacement: +=item command:STRING - URxvt.keysym.Insert: - URxvt.keysym.S-Insert: builtin: +If I takes the form of C, the specified B +is interpreted and executed as @@RXVT_NAME@@'s control sequence (basically +the opposite of C - instead of sending it to the program running +in the terminal, it will be treated as if it were program output). This is +most useful to feed command sequences into @@RXVT_NAME@@. -The first line defines a mapping for C and I combination -of modifiers. The second line re-establishes the default mapping for -C. +For example the following means "change the current locale to C +when Control-Meta-c is being pressed": + + URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007 The following example will map Control-Meta-1 and Control-Meta-2 to the fonts C and C<9x15bold>, so you can have some limited @@ -1129,6 +1133,63 @@ URxvt.keysym.M-C-3: command:\033[8;25;80t URxvt.keysym.M-C-4: command:\033[8;48;110t +=item builtin: + +The builtin action is the action that @@RXVT_NAME@@ would execute if no +key binding existed for the key combination. The obvious use is to undo +the effect of existing bindings. The not so obvious use is to reinstate +bindings when another binding overrides too many modifiers. + +For example if you overwrite the C key you will disable +@@RXVT_NAME@@'s C mapping. To re-enable that, you can poke +"holes" into the user-defined keymap using the C replacement: + + URxvt.keysym.Insert: + URxvt.keysym.S-Insert: builtin: + +The first line defines a mapping for C and I combination +of modifiers. The second line re-establishes the default mapping for +C. + +=item EXTENSION:STRING + +An action of this form passes the B to the @@RXVT_NAME@@perl(3) +extension of the same name. The extension will be loaded automatically if +neccessary. + +Not all extensions define key actions, but popular extensions that do +include the I and I extensions (documented in their +own manpages, @@RXVT_NAME@@-selection(1) and @@RXVT_NAME@@-matcher(1), +respectively). + +From the silly examples department, this will rot13-"encrypt" +@@RXVT_NAME@@'s selection when Alt-Control-c is pressed on typical PC +keyboards: + + URxvt.keysym.M-C-c: selection:rot13 + +=item perl:STRING + +This is a deprecated way of passing key mappings to perl extensions. It is +still supported, but should not be used anymore. + +=back + +In addition, you can define a range of keysyms in one shot by loading +the C perl extension and providing a I with pattern +B, where the delimiter `/' should be a +character not used by the strings. + +Its usage can be demonstrated by an example: + + URxvt.keysym.M-C-0x61: list|\033<|abc|> + +The above line is equivalent to the following three lines: + + URxvt.keysym.Meta-Control-0x61: \033 + URxvt.keysym.Meta-Control-0x62: \033 + URxvt.keysym.Meta-Control-0x63: \033 + =item B: I =item B: I