--- rxvt-unicode/doc/rxvt.1.pod 2013/06/05 07:58:17 1.225 +++ rxvt-unicode/doc/rxvt.1.pod 2014/05/18 18:19:10 1.232 @@ -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,75 @@ 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 builtin-string: + +This action is mainly useful to restore string mappings for keys that +have predefined actions in @@RXVT_NAME@@. The exact semantics are a bit +difficult to explain - basically, this action will send the string to the +application that would be sent if @@RXVT_NAME@@ wouldn't have a built-in +action for it. + +An example might make it clearer: @@RXVT_NAME@@ normally pastes the +selection when you press C. With the following bindings, it +would instead emit the (undocumented, but what applications running in the +terminal might expect) sequence C instead: + + URxvt.keysym.S-Insert: builtin-string: + URxvt.keysym.C-S-Insert: builtin: + +The first line disables the paste functionality for that key +combination, and the second reinstates the default behaviour for +C, which would otherwise be overridden. + +Similarly, to let applications gain access to the C (copy to +clipboard) and C (paste clipboard) key combination, you can do +this: + + URxvt.keysym.C-S-c: builtin-string: + URxvt.keysym.C-S-v: builtin-string: + +=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 *DEPRECATED* + +This is a deprecated way of passing key mappings to perl extensions. It is +still supported, but should not be used anymore. + +=back + =item B: I =item B: I @@ -1139,20 +1212,22 @@ Extension names can be prefixed with a C<-> sign to prohibit using them. This can be useful to selectively disable some extensions loaded by default, or specified via the C resource. For -example, C will use all the default extension except +example, C will use all the default extensions except C. -Extension names can also be followed by an argument in angle brackets -(e.g. C<< searchable-scrollback >>, which binds the hotkey for -searchable scrollback to Alt/Meta-s). Mentioning the same extension -multiple times with different arguments will pass multiple arguments to -the extension. +The default set includes the C, C, +C and C extensions, any extensions that define +keybindings via C meta comments, extensions loaded because +their resources/commandline switches were used, and extensions which are +mentioned in B resources. Each extension is looked up in the library directories, loaded if -necessary, and bound to the current terminal instance. +necessary, and bound to the current terminal instance. When the library +search path contains multiple extension files of the same name, then the +first one found will be used. -If both of these resources are the empty string, then the perl -interpreter will not be initialized. The idea behind two options is that +If both of these resources are the empty string, then the perl interpreter +will not be initialized. The rationale for having two options is that B will be used for extensions that should be available to all instances, while B is used for specific instances. @@ -1180,10 +1255,12 @@ Selection auto-transform patterns, see the @@RXVT_NAME@@perl(3) manpage for details. -=item B I +=item B I *DEPRECATED* -Sets the hotkey that starts the incremental scrollback buffer search -(default: C). +This resource is deprecated and will be removed. Use a B resource +instead, e.g.: + + URxvt.keysym.M-s: searchable-scrollback:start =item B: I @@ -1378,6 +1455,12 @@ Pressing B causes the value of the PRIMARY selection to be inserted too. +rxvt-unicode also provides the bindings B and + to interact with the CLIPBOARD selection. The first +binding causes the value of the internal selection to be copied to the +CLIPBOARD selection, while the second binding causes the value of the +CLIPBOARD selection to be inserted. + =back =head1 CHANGING FONTS @@ -1511,8 +1594,8 @@ The RGB cube uses indices 16..79 (16..231) using the following formulas: - index_88 = (r * 4 + g) * 4 + b + 16 # r, g, b = 0..3 - index_256 = (r * 16 + g) * 16 + b + 16 # r, g, b = 0..15 + index_88 = (r * 4 + g) * 4 + b + 16 # r, g, b = 0..3 + index_256 = (r * 6 + g) * 6 + b + 16 # r, g, b = 0..5 The grayscale ramp uses indices 80..87 (232..239), from 10% to 90% in 10% steps (1/26 to 25/26 in 1/26 steps) - black and white are already part of