ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/doc/rxvt.1.pod
(Generate patch)

Comparing rxvt-unicode/doc/rxvt.1.pod (file contents):
Revision 1.225 by sf-exg, Wed Jun 5 07:58:17 2013 UTC vs.
Revision 1.262 by root, Mon Feb 13 17:29:02 2023 UTC

… …
84far greater than those listed. For example: `@@RXVT_NAME@@ --loginShell --color1 84far greater than those listed. For example: `@@RXVT_NAME@@ --loginShell --color1
85Orange'. 85Orange'.
86 86
87The following options are available: 87The following options are available:
88 88
89=over 4 89=over
90 90
91=item B<-help>, B<--help> 91=item B<-help>, B<--help>
92 92
93Print out a message describing available options. 93Print out a message describing available options.
94 94
… …
108of graphical corruption. This is harmless, but we can't do anything about 108of graphical corruption. This is harmless, but we can't do anything about
109this, so watch out] 109this, so watch out]
110 110
111=item B<-visual> I<visualID> 111=item B<-visual> I<visualID>
112 112
113Compile I<frills>: Use the given visual (see e.g. C<xdpyinfo> for possible 113Compile I<frills>: Use the given visual (see e.g. C<xdpyinfo> for
114visual ids). 114possible visual ids) instead of the default, and also allocate a private
115colormap. All visual types except for DirectColor are supported.
115 116
116=item B<-geometry> I<geom> 117=item B<-geometry> I<geom>
117 118
118Window geometry (B<-g> still respected); resource B<geometry>. 119Window geometry (B<-g> still respected); resource B<geometry>.
119 120
… …
126Turn on/off jump scrolling (allow multiple lines per refresh); resource B<jumpScroll>. 127Turn on/off jump scrolling (allow multiple lines per refresh); resource B<jumpScroll>.
127 128
128=item B<-ss>|B<+ss> 129=item B<-ss>|B<+ss>
129 130
130Turn on/off skip scrolling (allow multiple screens per refresh); resource B<skipScroll>. 131Turn on/off skip scrolling (allow multiple screens per refresh); resource B<skipScroll>.
132
133=item B<-fps> I<number>
134
135Compile I<frills>: Set the refresh interval (in frames per second or
136negative seconds); resource B<refreshRate>.
131 137
132=item B<-fade> I<number> 138=item B<-fade> I<number>
133 139
134Fade the text by the given percentage when focus is lost. Small values 140Fade the text by the given percentage when focus is lost. Small values
135fade a little only, 100 completely replaces all colours by the fade 141fade a little only, 100 completely replaces all colours by the fade
… …
219 225
220=item B<-ls>|B<+ls> 226=item B<-ls>|B<+ls>
221 227
222Start as a login-shell/sub-shell; resource B<loginShell>. 228Start as a login-shell/sub-shell; resource B<loginShell>.
223 229
230=item B<-mc> I<milliseconds>
231
232Specify the maximum time between multi-click selections.
233
224=item B<-ut>|B<+ut> 234=item B<-ut>|B<+ut>
225 235
226Compile I<utmp>: Inhibit/enable writing a utmp entry; resource 236Compile I<utmp>: Inhibit/enable writing a utmp entry; resource
227B<utmpInhibit>. 237B<utmpInhibit>.
228 238
… …
306 316
307=item B<-override-redirect> 317=item B<-override-redirect>
308 318
309Compile I<frills>: Sets override-redirect on the window; resource 319Compile I<frills>: Sets override-redirect on the window; resource
310B<override-redirect>. 320B<override-redirect>.
321
322=item B<-dockapp>
323
324Sets the initial state of the window to WithdrawnState, which makes
325window managers that support this extension treat it as a dockapp.
311 326
312=item B<-sbg> 327=item B<-sbg>
313 328
314Compile I<frills>: Disable the usage of the built-in block graphics/line 329Compile I<frills>: Disable the usage of the built-in block graphics/line
315drawing characters and just rely on what the specified fonts provide. Use 330drawing characters and just rely on what the specified fonts provide. Use
… …
370=item B<-pt> I<style> 385=item B<-pt> I<style>
371 386
372Compile I<XIM>: input style for input method; B<OverTheSpot>, 387Compile I<XIM>: input style for input method; B<OverTheSpot>,
373B<OffTheSpot>, B<Root>; resource B<preeditType>. 388B<OffTheSpot>, B<Root>; resource B<preeditType>.
374 389
390If the perl extension C<xim-onthespot> is used (which is the default),
391then additionally the C<OnTheSpot> preedit type is available.
392
375=item B<-im> I<text> 393=item B<-im> I<text>
376 394
377Compile I<XIM>: input method name. resource B<inputMethod>. 395Compile I<XIM>: input method name. resource B<inputMethod>.
378 396
379=item B<-imlocale> I<string> 397=item B<-imlocale> I<string>
… …
393Change the meaning of triple-click selection with the left mouse 411Change the meaning of triple-click selection with the left mouse
394button. Only effective when the original (non-perl) selection code is 412button. Only effective when the original (non-perl) selection code is
395in-use. Instead of selecting a full line it will extend the selection to 413in-use. Instead of selecting a full line it will extend the selection to
396the end of the logical line only. resource B<tripleclickwords>. 414the end of the logical line only. resource B<tripleclickwords>.
397 415
416=item B<-dpb>|B<+dpb>
417
418Compile frills: Disable (or enable) emitting bracketed paste mode
419sequences (default enabled). Bracketed paste mode allows programs
420to detect when something is pasted. Since more and more programs
421abuse this, these sequences can be disabled. The command sequences to
422enable and query paste mode will still work, but the actual bracket
423sequences will no longer be emitted. You can also toggle this from the
424ctrl-middle-mouse-button menu; resource B<disablePasteBrackets>.
425
398=item B<-insecure> 426=item B<-insecure>
399 427
400Enable "insecure" mode, which currently enables most of the escape 428Enable "insecure" mode, which currently enables most of the escape
401sequences that echo strings. See the resource B<insecure> for more 429sequences that echo strings. See the resource B<insecure> for more
402info. 430info.
… …
414 442
415=item B<-ssr>|B<+ssr> 443=item B<-ssr>|B<+ssr>
416 444
417Turn on/off secondary screen scroll (default enabled); resource 445Turn on/off secondary screen scroll (default enabled); resource
418B<secondaryScroll>. 446B<secondaryScroll>.
447
448=item B<-rm> I<mode>
449
450Compile I<frills>: Sets long line rewrapping behaviour on window resizes
451to one of B<auto> (the default), B<always> or B<never>. The latter two
452modes do the obvious, B<auto> rewraps (acts like B<always>) if scrollback
453is non-empty, and wings lines (acts like B<never>) otherwise; resource
454B<rewrapMode>.
419 455
420=item B<-hold>|B<+hold> 456=item B<-hold>|B<+hold>
421 457
422Turn on/off hold window after exit support. If enabled, @@RXVT_NAME@@ 458Turn on/off hold window after exit support. If enabled, @@RXVT_NAME@@
423will not immediately destroy its window when the program executed within 459will not immediately destroy its window when the program executed within
… …
501 close $pty; 537 close $pty;
502 538
503 # now communicate with rxvt 539 # now communicate with rxvt
504 my $slave = $pty->slave; 540 my $slave = $pty->slave;
505 while (<$slave>) { print $slave "got <$_>\n" } 541 while (<$slave>) { print $slave "got <$_>\n" }
542
543Note that, despite what the name might imply, the file descriptor does not
544need to be a pty, it can be a bi-directional pipe as well (e.g. a unix
545domain or tcp socket). While tty operations cannot be done in this case,
546B<@@RXVT_NAME@@> can still be remote controlled with it:
547
548 use Socket;
549 use Fcntl;
550
551 socketpair my $URXVT, my $slave, Socket::AF_UNIX, Socket::SOCK_STREAM, Socket::PF_UNSPEC;
552 fcntl $slave, Fcntl::F_SETFD, 0;
553 system "exec @@RXVT_NAME@@ -pty-fd " . (fileno $slave) . " &";
554 close $slave;
555
556 syswrite $URXVT, "Type a secret password: ";
557 my $secret = do { local $/ = "\r"; <$URXVT> };
558 print "Not so secret anymore: $secret\n";
506 559
507=item B<-pe> I<string> 560=item B<-pe> I<string>
508 561
509Comma-separated list of perl extension scripts to use (or not to use) in 562Comma-separated list of perl extension scripts to use (or not to use) in
510this terminal instance. See resource B<perl-ext> for details. 563this terminal instance. See resource B<perl-ext> for details.
… …
538be used. Command-line arguments can be used to override resource 591be used. Command-line arguments can be used to override resource
539settings. The following resources are supported (you might want to 592settings. The following resources are supported (you might want to
540check the @@RXVT_NAME@@perl(3) manpage for additional settings by perl 593check the @@RXVT_NAME@@perl(3) manpage for additional settings by perl
541extensions not documented here): 594extensions not documented here):
542 595
543=over 4 596=over
544 597
545=item B<depth:> I<bitdepth> 598=item B<depth:> I<bitdepth>
546 599
547Compile I<xft>: Attempt to find a visual with the given bit depth; 600Compile I<xft>: Attempt to find a visual with the given bit depth;
548option B<-depth>. 601option B<-depth>.
… …
649 702
650B<False>: specify that everything is to be displayed, even 703B<False>: specify that everything is to be displayed, even
651if the refresh is too fast for the human eye to read anything (or the 704if the refresh is too fast for the human eye to read anything (or the
652monitor to display anything); option B<+ss>. 705monitor to display anything); option B<+ss>.
653 706
707=item B<refreshRate:> I<number>
708
709Compile I<frills>: When positive, sets the maximum refreshes per second
710(the default is C<60>). When zero or negative, sets the minimum interval
711between refreshes, negated. That is, positive numbers limit the number
712of refreshes per second to that number, similar to a fps limiter in
713games. A negative number gets negated and directly sets the minimum
714interval between refreshes, that is, C<10> and C<-0.1> both specify
715the same refresh interval (likewise C<50> and C<0.02>). Finally, zero
716makes @@RXVT_NAME@@ refresh as fast as possible. Fractional values are
717supported; option B<-fps>.
718
654=item B<fading:> I<number> 719=item B<fading:> I<number>
655 720
656Fade the text by the given percentage when focus is lost; option B<-fade>. 721Fade the text by the given percentage when focus is lost; option B<-fade>.
657 722
658=item B<fadeColor:> I<colour> 723=item B<fadeColor:> I<colour>
… …
781 846
782B<True>: start as a login shell by prepending a `-' to B<argv[0]> of 847B<True>: start as a login shell by prepending a `-' to B<argv[0]> of
783the shell; option B<-ls>. B<False>: start as a normal sub-shell 848the shell; option B<-ls>. B<False>: start as a normal sub-shell
784[default]; option B<+ls>. 849[default]; option B<+ls>.
785 850
851=item B<multiClickTime:> I<number>
852
853Specify the maximum time in milliseconds between multi-click select
854events. The default is 500 milliseconds; option B<-mc>.
855
786=item B<utmpInhibit:> I<boolean> 856=item B<utmpInhibit:> I<boolean>
787 857
788B<True>: inhibit writing record into the system log file B<utmp>; 858B<True>: inhibit writing record into the system log file B<utmp>;
789option B<-ut>. B<False>: write record into the system log file B<utmp> 859option B<-ut>. B<False>: write record into the system log file B<utmp>
790[default]; option B<+ut>. 860[default]; option B<+ut>.
… …
833Align the B<top>, B<bottom> or B<centre> [default] of the scrollbar 903Align the B<top>, B<bottom> or B<centre> [default] of the scrollbar
834thumb with the pointer on middle button press/drag. 904thumb with the pointer on middle button press/drag.
835 905
836=item B<scrollTtyOutput:> I<boolean> 906=item B<scrollTtyOutput:> I<boolean>
837 907
838B<True>: scroll to bottom when tty receives output; option B<-si>. 908B<True>: scroll to bottom when tty receives output; option B<+si>.
839B<False>: do not scroll to bottom when tty receives output; option 909B<False>: do not scroll to bottom when tty receives output; option
840B<+si>. 910B<-si>.
841 911
842=item B<scrollWithBuffer:> I<boolean> 912=item B<scrollWithBuffer:> I<boolean>
843 913
844B<True>: scroll with scrollback buffer when tty receives new lines (i.e. 914B<True>: scroll with scrollback buffer when tty receives new lines (i.e.
845try to show the same lines) and B<scrollTtyOutput> is False; option 915try to show the same lines) and B<scrollTtyOutput> is False; option
… …
853are not passed onto the shell; option B<-sk>. B<False>: do not scroll to 923are not passed onto the shell; option B<-sk>. B<False>: do not scroll to
854bottom when a non-special key is pressed; option B<+sk>. 924bottom when a non-special key is pressed; option B<+sk>.
855 925
856=item B<saveLines:> I<number> 926=item B<saveLines:> I<number>
857 927
858Save I<number> lines in the scrollback buffer [default 64]. This 928Save I<number> lines in the scrollback buffer [default 1000]; option B<-sl>.
859resource is limited on most machines to 65535; option B<-sl>.
860 929
861=item B<internalBorder:> I<number> 930=item B<internalBorder:> I<number>
862 931
863Internal border of I<number> pixels. This resource is limited to 100; 932Internal border of I<number> pixels. This resource is limited to 100;
864option B<-b>. 933option B<-b>.
… …
927 996
928=item B<pointerColor2:> I<colour> 997=item B<pointerColor2:> I<colour>
929 998
930Mouse pointer background colour. 999Mouse pointer background colour.
931 1000
1001=item B<pointerShape:> I<string>
1002
1003Compile I<frills>: Specifies the name of the mouse pointer shape
1004[default B<xterm>]. See the macros in the B<X11/cursorfont.h> include
1005file for possible values (omit the C<XC_> prefix).
1006
932=item B<pointerBlankDelay:> I<number> 1007=item B<pointerBlankDelay:> I<number>
933 1008
934Specifies number of seconds before blanking the pointer [default 2]. Use a 1009Specifies number of seconds before blanking the pointer [default 2]. Use a
935large number (e.g. C<987654321>) to effectively disable the timeout. 1010large number (e.g. C<987654321>) to effectively disable the timeout.
936 1011
… …
962 1037
963B<< BACKSLASH `"'&()*,;<=>?@[]^{|} >> 1038B<< BACKSLASH `"'&()*,;<=>?@[]^{|} >>
964 1039
965=item B<preeditType:> I<style> 1040=item B<preeditType:> I<style>
966 1041
967B<OverTheSpot>, B<OffTheSpot>, B<Root>; option B<-pt>. 1042B<OnTheSpot>, B<OverTheSpot>, B<OffTheSpot>, B<Root>; option B<-pt>.
968 1043
969=item B<inputMethod:> I<name> 1044=item B<inputMethod:> I<name>
970 1045
971I<name> of inputMethod to use; option B<-im>. 1046I<name> of inputMethod to use; option B<-im>.
972 1047
… …
990 1065
991Change the meaning of triple-click selection with the left mouse 1066Change the meaning of triple-click selection with the left mouse
992button. Instead of selecting a full line it will extend the selection to 1067button. Instead of selecting a full line it will extend the selection to
993the end of the logical line only; option B<-tcw>. 1068the end of the logical line only; option B<-tcw>.
994 1069
1070=item B<disablePasteBrackets:> I<boolean>
1071
1072Prevent emission of paste bracket sequences; option B<-dpb>.
1073
995=item B<insecure:> I<boolean> 1074=item B<insecure:> I<boolean>
996 1075
997Enables "insecure" mode. Rxvt-unicode offers some escape sequences that 1076Enable "insecure" mode. Rxvt-unicode offers some escape sequences that
998echo arbitrary strings like the icon name or the locale. This could be 1077echo arbitrary strings like the icon name or the locale. This could be
999abused if somebody gets 8-bit-clean access to your display, whether 1078abused if somebody gets 8-bit-clean access to your display, whether
1000through a mail client displaying mail bodies unfiltered or through 1079through a mail client displaying mail bodies unfiltered or through
1001write(1) or any other means. Therefore, these sequences are disabled by 1080write(1) or any other means. Therefore, these sequences are disabled by
1002default. (Note that many other terminals, including xterm, have these 1081default. (Note that many other terminals, including xterm, have these
… …
1020 1099
1021=item B<secondaryScreen:> I<boolean> 1100=item B<secondaryScreen:> I<boolean>
1022 1101
1023Turn on/off secondary screen (default enabled). 1102Turn on/off secondary screen (default enabled).
1024 1103
1104=item B<rewrapMode:> I<mode>
1105
1106Sets long line rewrap behaviour on window resize to one of B<auto>
1107(default), B<always> or B<never>.
1108
1025=item B<secondaryScroll:> I<boolean> 1109=item B<secondaryScroll:> I<boolean>
1026 1110
1027Turn on/off secondary screen scroll (default enabled). If this 1111Turn on/off secondary screen scroll (default enabled). If this
1028option is enabled, scrolls on the secondary screen will change the 1112option is enabled, scrolls on the secondary screen will change the
1029scrollback buffer and, when secondaryScreen is off, switching 1113scrollback buffer and, when secondaryScreen is off, switching
… …
1041Sets the working directory for the shell (or the command specified via 1125Sets the working directory for the shell (or the command specified via
1042B<-e>). The I<path> must be an absolute path and it must exist for 1126B<-e>). The I<path> must be an absolute path and it must exist for
1043@@RXVT_NAME@@ to start. If it isn't specified then the current working 1127@@RXVT_NAME@@ to start. If it isn't specified then the current working
1044directory will be used; option B<-cd>. 1128directory will be used; option B<-cd>.
1045 1129
1046=item B<keysym.>I<sym>: I<string> 1130=item B<keysym.>I<sym>: I<action>
1047 1131
1048Compile I<frills>: Associate I<string> with keysym I<sym>. The 1132Compile I<frills>: Associate I<action> with keysym I<sym>. The intervening
1049intervening resource name B<keysym.> cannot be omitted. 1133resource name B<keysym.> cannot be omitted.
1050 1134
1051The format of I<sym> is "I<(modifiers-)key>", where I<modifiers> can be 1135Using this resource, you can map key combinations such as
1052any combination of B<ISOLevel3>, B<AppKeypad>, B<Control>, B<NumLock>, 1136C<Ctrl-Shift-BackSpace> to various actions, such as outputting a different
1053B<Shift>, B<Meta>, B<Lock>, B<Mod1>, B<Mod2>, B<Mod3>, B<Mod4>, B<Mod5>, 1137string than would normally result from that combination, making the
1054and the abbreviated B<I>, B<K>, B<C>, B<N>, B<S>, B<M>, B<A>, B<L>, B<1>, 1138terminal scroll up or down the way you want it, or any other thing an
1055B<2>, B<3>, B<4>, B<5>. 1139extension might provide.
1140
1141The key combination that triggers the action, I<sym>, has the following format:
1142
1143 (modifiers-)key
1144
1145Where I<modifiers> can be any combination of the following full or
1146abbreviated modifier names:
1147
1148=begin table
1149
1150 B<ISOLevel3> B<I>
1151 B<AppKeypad> B<K>
1152 B<Control> B<C>
1153 B<NumLock> B<N>
1154 B<Shift> B<S>
1155 B<Meta> B<M> I<or> B<A>
1156 B<Lock> B<L>
1157 B<Mod1> B<1>
1158 B<Mod2> B<2>
1159 B<Mod3> B<3>
1160 B<Mod4> B<4>
1161 B<Mod5> B<5>
1162
1163=end table
1056 1164
1057The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to 1165The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to
1058whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr 1166whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr
1059keys are being mapped. B<AppKeypad> is a synthetic modifier mapped to the 1167keys are being mapped. B<AppKeypad> is a synthetic modifier mapped to the
1060current application keymap mode state. 1168current application keymap mode state.
1061 1169
1062The spellings of I<key> can be obtained by using B<xev>(1) command or 1170Due the the large number of modifier combinations, a key mapping will
1063searching keysym macros from B</usr/X11R6/include/X11/keysymdef.h> and 1171match if I<at least> the specified identifiers are being set, and no other
1172key mappings with those and more bits are being defined. That means that
1173defining a mapping for C<a> will automatically provide definitions for
1174C<Meta-a>, C<Shift-a> and so on, unless some of those are defined mappings
1175themselves. See the C<builtin:> action, below, for a way to work around
1176this when this is a problem.
1177
1178The spelling of I<key> depends on your implementation of X. An easy way to
1179find a key name is to use the B<xev>(1) command. You can find a list by
1180looking for the C<XK_> macros in the B<X11/keysymdef.h> include file (omit
1064omitting the prefix B<XK_>. Alternatively you can specify I<key> by its hex 1181the C<XK_> prefix). Alternatively you can specify I<key> by its hex keysym
1065keysym value (B<0x0000 - 0xFFFF>). Note that the lookup of I<sym>s is not 1182value (B<0x0000 - 0xFFFF>).
1066performed in an exact manner; however, the closest match is assured.
1067 1183
1068I<string> may contain escape values (C<\n>: newline, C<\000>: octal 1184As with any resource value, the I<action> string may contain backslash
1185escape sequences (C<\n>: newline, C<\\>: backslash, C<\000>: octal
1069number), see RESOURCES in C<man 7 X> for further details. 1186number), see RESOURCES in C<man 7 X> for further details.
1070 1187
1071You can define a range of keysyms in one shot by 1188An action starts with an action prefix that selects a certain type
1072loading the C<keysym-list> perl extension and providing a I<string> 1189of action, followed by a colon. An action string without colons is
1073with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where the delimiter `/' 1190interpreted as a literal string to pass to the tty (as if it was
1191prefixed with C<string:>).
1192
1193The following action prefixes are known - extensions can provide
1194additional prefixes:
1195
1196=over
1197
1198=item string:STRING
1199
1200If the I<action> starts with C<string:> (or otherwise contains no colons),
1201then the remaining C<STRING> will be passed to the program running in the
1202terminal. For example, you could replace whatever Shift-Tab outputs by the
1203string C<echo rm -rf /> followed by a newline:
1204
1205 URxvt.keysym.Shift-Tab: string:echo rm -rf /\n
1206
1207This could in theory be used to completely redefine your keymap.
1208
1209In addition, for actions of this type, you can define a range of
1210keysyms in one shot by loading the C<keysym-list> perl extension and
1211providing an I<action> with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where
1074should be a character not used by the strings. 1212the delimiter `/' should be a character not used by the strings.
1075 1213
1076Its usage can be demonstrated by an example: 1214Its usage can be demonstrated by an example:
1077 1215
1078 URxvt.keysym.M-C-0x61: list|\033<|abc|> 1216 URxvt.keysym.M-C-0x61: list|\033<|abc|>
1079 1217
1080The above line is equivalent to the following three lines: 1218The above line is equivalent to the following three lines:
1081 1219
1082 URxvt.keysym.Meta-Control-0x61: \033<a> 1220 URxvt.keysym.Meta-Control-0x61: string:\033<a>
1083 URxvt.keysym.Meta-Control-0x62: \033<b> 1221 URxvt.keysym.Meta-Control-0x62: string:\033<b>
1084 URxvt.keysym.Meta-Control-0x63: \033<c> 1222 URxvt.keysym.Meta-Control-0x63: string:\033<c>
1085 1223
1224=item command:STRING
1225
1086If I<string> takes the form of C<command:STRING>, the specified B<STRING> 1226If I<action> takes the form of C<command:STRING>, the specified B<STRING>
1087is interpreted and executed as @@RXVT_NAME@@'s control sequence. For 1227is interpreted and executed as @@RXVT_NAME@@'s control sequence (basically
1228the opposite of C<string:> - instead of sending it to the program running
1229in the terminal, it will be treated as if it were program output). This is
1230most useful to feed command sequences into @@RXVT_NAME@@.
1231
1088example the following means "change the current locale to C<zh_CN.GBK> 1232For example the following means "change the current locale to C<zh_CN.GBK>
1089when Control-Meta-c is being pressed": 1233when Control-Meta-c is being pressed":
1090 1234
1091 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007 1235 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007
1092 1236
1093If I<string> takes the form C<perl:STRING>, then the specified B<STRING> 1237The following example will map Control-Meta-1 and Control-Meta-2 to
1094is passed to the C<on_user_command> perl handler. See the @@RXVT_NAME@@perl(3) 1238the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
1095manpage. For example, the F<selection> extension (activated via 1239font-switching at runtime:
1096C<@@RXVT_NAME@@ -pe selection>) listens for C<selection:rot13> events:
1097 1240
1098 URxvt.keysym.M-C-c: perl:selection:rot13 1241 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007
1242 URxvt.keysym.M-C-2: command:\033]50;9x15bold\007
1099 1243
1100Due the the large number of modifier combinations, a defined key mapping 1244Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more
1101will match if I<at least> the specified identifiers are being set, and 1245info):
1102no other key mappings with those and more bits are being defined. That
1103means that defining a key map for C<a> will automatically provide
1104definitions for C<Meta-a>, C<Shift-a> and so on, unless some of those are defined
1105mappings themselves.
1106 1246
1107Unfortunately, this will override built-in key mappings. For example 1247 URxvt.keysym.M-C-3: command:\033[8;25;80t
1248 URxvt.keysym.M-C-4: command:\033[8;48;110t
1249
1250=item builtin:
1251
1252The builtin action is the action that @@RXVT_NAME@@ would execute if no
1253key binding existed for the key combination. The obvious use is to undo
1254the effect of existing bindings. The not so obvious use is to reinstate
1255bindings when another binding overrides too many modifiers.
1256
1108if you overwrite the C<Insert> key you will disable @@RXVT_NAME@@'s 1257For example if you overwrite the C<Insert> key you will disable
1109C<Shift-Insert> mapping. To re-enable that, you can poke "holes" into the 1258@@RXVT_NAME@@'s C<Shift-Insert> mapping. To re-enable that, you can poke
1110user-defined keymap using the C<builtin:> replacement: 1259"holes" into the user-defined keymap using the C<builtin:> replacement:
1111 1260
1112 URxvt.keysym.Insert: <my insert key sequence> 1261 URxvt.keysym.Insert: <my insert key sequence>
1113 URxvt.keysym.S-Insert: builtin: 1262 URxvt.keysym.S-Insert: builtin:
1114 1263
1115The first line defines a mapping for C<Insert> and I<any> combination 1264The first line defines a mapping for C<Insert> and I<any> combination
1116of modifiers. The second line re-establishes the default mapping for 1265of modifiers. The second line re-establishes the default mapping for
1117C<Shift-Insert>. 1266C<Shift-Insert>.
1118 1267
1119The following example will map Control-Meta-1 and Control-Meta-2 to 1268=item builtin-string:
1120the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
1121font-switching at runtime:
1122 1269
1123 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007 1270This action is mainly useful to restore string mappings for keys that
1124 URxvt.keysym.M-C-2: command:\033]50;9x15bold\007 1271have predefined actions in @@RXVT_NAME@@. The exact semantics are a bit
1272difficult to explain - basically, this action will send the string to the
1273application that would be sent if @@RXVT_NAME@@ wouldn't have a built-in
1274action for it.
1125 1275
1126Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more 1276An example might make it clearer: @@RXVT_NAME@@ normally pastes the
1127info): 1277selection when you press C<Shift-Insert>. With the following bindings, it
1278would instead emit the (undocumented, but what applications running in the
1279terminal might expect) sequence C<ESC [ 2 $> instead:
1128 1280
1129 URxvt.keysym.M-C-3: command:\033[8;25;80t 1281 URxvt.keysym.S-Insert: builtin-string:
1130 URxvt.keysym.M-C-4: command:\033[8;48;110t 1282 URxvt.keysym.C-S-Insert: builtin:
1283
1284The first line disables the paste functionality for that key
1285combination, and the second reinstates the default behaviour for
1286C<Control-Shift-Insert>, which would otherwise be overridden.
1287
1288Similarly, to let applications gain access to the C<C-M-c> (copy to
1289clipboard) and C<C-M-v> (paste clipboard) key combination, you can do
1290this:
1291
1292 URxvt.keysym.C-M-c: builtin-string:
1293 URxvt.keysym.C-M-v: builtin-string:
1294
1295=item EXTENSION:STRING
1296
1297An action of this form invokes the action B<STRING>, if any, provided
1298by the @@RXVT_NAME@@perl(3) extension B<EXTENSION>. The extension will
1299be loaded automatically if necessary.
1300
1301Not all extensions define actions, but popular extensions that do
1302include the I<selection> and I<matcher> extensions (documented in their
1303own manpages, @@RXVT_NAME@@-selection(1) and @@RXVT_NAME@@-matcher(1),
1304respectively).
1305
1306From the silly examples department, this will rot13-"encrypt"
1307@@RXVT_NAME@@'s selection when Alt-Control-c is pressed on typical PC
1308keyboards:
1309
1310 URxvt.keysym.M-C-c: selection:rot13
1311
1312=item perl:STRING *DEPRECATED*
1313
1314This is a deprecated way of invoking commands provided by perl
1315extensions. It is still supported, but should not be used anymore.
1316
1317=back
1131 1318
1132=item B<perl-ext-common>: I<string> 1319=item B<perl-ext-common>: I<string>
1133 1320
1134=item B<perl-ext>: I<string> 1321=item B<perl-ext>: I<string>
1135 1322
1136Comma-separated list(s) of perl extension scripts (default: C<default>) to 1323Comma-separated list(s) of perl extension scripts (default: C<default>) to
1137use in this terminal instance; option B<-pe>. 1324use in this terminal instance; option B<-pe>.
1138 1325
1139Extension names can be prefixed with a C<-> sign to prohibit using 1326Extension names can be prefixed with a C<-> sign to remove them again, in
1140them. This can be useful to selectively disable some extensions loaded 1327case they had been specified earlier. This can be useful to selectively
1141by default, or specified via the C<perl-ext-common> resource. For 1328disable some extensions loaded by default, or specified via the
1142example, C<default,-selection> will use all the default extension except 1329C<perl-ext-common> resource. For example, C<default,-selection> will use
1143C<selection>. 1330all the default extensions except C<selection>.
1144 1331
1145Extension names can also be followed by an argument in angle brackets 1332To prohibit autoloading of extensions, you can prefix them with C</>,
1146(e.g. C<< searchable-scrollback<M-s> >>, which binds the hotkey for 1333which will make urxvt refuse to automatically load them (this can be
1147searchable scrollback to Alt/Meta-s). Mentioning the same extension 1334overridden, however, by specifying the extension name again without a
1148multiple times with different arguments will pass multiple arguments to 1335prefix, though). This does not prohibit extensions themselves loading
1149the extension. 1336other extensions. For example, C<default,/background> will keep the
1337C<background> extension from being loaded when a background OSC sequence
1338is received.
1339
1340The default set includes the C<selection>, C<option-popup>,
1341C<selection-popup>, C<readline>, C<searchable-scrollback> and
1342C<confirm-paste> extensions, as well as any extensions which are mentioned
1343in B<keysym> resources.
1344
1345Any extension such that a corresponding resource is given on the
1346command line is automatically appended to B<perl-ext>.
1150 1347
1151Each extension is looked up in the library directories, loaded if 1348Each extension is looked up in the library directories, loaded if
1152necessary, and bound to the current terminal instance. 1349necessary, and bound to the current terminal instance. When the library
1350search path contains multiple extension files of the same name, then the
1351first one found will be used.
1153 1352
1154If both of these resources are the empty string, then the perl 1353If both of these resources are the empty string, then the perl interpreter
1155interpreter will not be initialized. The idea behind two options is that 1354will not be initialized. The rationale for having two options is that
1156B<perl-ext-common> will be used for extensions that should be available to 1355B<perl-ext-common> will be used for extensions that should be available to
1157all instances, while B<perl-ext> is used for specific instances. 1356all instances, while B<perl-ext> is used for specific instances.
1158 1357
1159=item B<perl-eval>: I<string> 1358=item B<perl-eval>: I<string>
1160 1359
… …
1178=item B<< selection-autotransform.I<idx> >>: I<perl-transform> 1377=item B<< selection-autotransform.I<idx> >>: I<perl-transform>
1179 1378
1180Selection auto-transform patterns, see the @@RXVT_NAME@@perl(3) manpage 1379Selection auto-transform patterns, see the @@RXVT_NAME@@perl(3) manpage
1181for details. 1380for details.
1182 1381
1183=item B<searchable-scrollback:> I<keysym> 1382=item B<searchable-scrollback:> I<keysym> *DEPRECATED*
1184 1383
1185Sets the hotkey that starts the incremental scrollback buffer search 1384This resource is deprecated and will be removed. Use a B<keysym> resource
1186(default: C<M-s>). 1385instead, e.g.:
1386
1387 URxvt.keysym.M-s: searchable-scrollback:start
1187 1388
1188=item B<url-launcher>: I<string> 1389=item B<url-launcher>: I<string>
1189 1390
1190Specifies the program to be started with a URL argument. Used by the 1391Specifies the program to be started with a URL argument. Used by the
1191C<selection-popup> and C<matcher> perl extensions. 1392C<selection-popup> and C<matcher> perl extensions.
… …
1204Turn on/off ISO 14755 (default enabled). 1405Turn on/off ISO 14755 (default enabled).
1205 1406
1206=item B<iso14755_52:> I<boolean> 1407=item B<iso14755_52:> I<boolean>
1207 1408
1208Turn on/off ISO 14755 5.2 mode (default enabled). 1409Turn on/off ISO 14755 5.2 mode (default enabled).
1209
1210=back
1211
1212=head1 BACKGROUND IMAGE OPTIONS AND RESOURCES
1213
1214=over 4
1215
1216=item B<-pixmap> I<file[;oplist]>
1217
1218=item B<backgroundPixmap:> I<file[;oplist]>
1219
1220Compile I<pixbuf>: Use the specified image file as the window's
1221background and also optionally specify a colon separated list of
1222operations to modify it. Note that you may need to quote the C<;>
1223character when using the command line option, as C<;> is usually a
1224metacharacter in shells. Supported operations are:
1225
1226=over 4
1227
1228=item B<WxH+X+Y>
1229
1230sets scale and position. B<"W" / "H"> specify the horizontal/vertical
1231scale (percent), and B<"X" / "Y"> locate the image centre (percent). A
1232scale of 0 disables scaling.
1233
1234=item B<op=tile>
1235
1236enables tiling
1237
1238=item B<op=keep-aspect>
1239
1240maintain the image aspect ratio when scaling
1241
1242=item B<op=root-align>
1243
1244use the position of the terminal window relative to the root window as
1245the image offset, simulating a root window background
1246
1247=back
1248
1249The default scale and position setting is C<100x100+50+50>.
1250Alternatively, a predefined set of templates can be used to achieve
1251the most common setups:
1252
1253=over 4
1254
1255=item B<style=tiled>
1256
1257the image is tiled with no scaling. Equivalent to 0x0+0+0:op=tile
1258
1259=item B<style=aspect-stretched>
1260
1261the image is scaled to fill the whole window maintaining the aspect
1262ratio and centered. Equivalent to 100x100+50+50:op=keep-aspect
1263
1264=item B<style=stretched>
1265
1266the image is scaled to fill the whole window. Equivalent to 100x100
1267
1268=item B<style=centered>
1269
1270the image is centered with no scaling. Equivalent to 0x0+50+50
1271
1272=item B<style=root-tiled>
1273
1274the image is tiled with no scaling and using 'root' positioning.
1275Equivalent to 0x0:op=tile:op=root-align
1276
1277=back
1278
1279If multiple templates are specified the last one wins. Note that a
1280template overrides all the scale, position and operations settings.
1281
1282If used in conjunction with pseudo-transparency, the specified pixmap
1283will be blended over the transparent background using alpha-blending.
1284
1285=item B<-tr>|B<+tr>
1286
1287=item B<transparent:> I<boolean>
1288
1289Turn on/off pseudo-transparency by using the root pixmap as background.
1290
1291B<-ip> (B<inheritPixmap>) is still accepted as an obsolete alias but
1292will be removed in future versions.
1293
1294=item B<-tint> I<colour>
1295
1296=item B<tintColor:> I<colour>
1297
1298Tint the transparent background with the given colour. Note that a
1299black tint yields a completely black image while a white tint yields
1300the image unchanged.
1301
1302=item B<-sh> I<number>
1303
1304=item B<shading:> I<number>
1305
1306Darken (0 .. 99) or lighten (101 .. 200) the transparent background.
1307A value of 100 means no shading.
1308
1309=item B<-blr> I<HxV>
1310
1311=item B<blurRadius:> I<HxV>
1312
1313Apply gaussian blur with the specified radius to the transparent
1314background. If a single number is specified, the vertical and
1315horizontal radii are considered to be the same. Setting one of the
1316radii to 1 and the other to a large number creates interesting effects
1317on some backgrounds. The maximum radius value is 128. An horizontal or
1318vertical radius of 0 disables blurring.
1319
1320=item B<path:> I<path>
1321
1322Specify the colon-delimited search path for finding background image files.
1323 1410
1324=back 1411=back
1325 1412
1326=head1 THE SCROLLBAR 1413=head1 THE SCROLLBAR
1327 1414
… …
1351=head1 THE SELECTION: SELECTING AND PASTING TEXT 1438=head1 THE SELECTION: SELECTING AND PASTING TEXT
1352 1439
1353The behaviour of text selection and insertion/pasting mechanism is similar 1440The behaviour of text selection and insertion/pasting mechanism is similar
1354to I<xterm>(1). 1441to I<xterm>(1).
1355 1442
1356=over 4 1443=over
1357 1444
1358=item B<Selecting>: 1445=item B<Selecting>:
1359 1446
1360Left click at the beginning of the region, drag to the end of the region 1447Left click at the beginning of the region, drag to the end of the region
1361and release; Right click to extend the marked region; Left double-click 1448and release; Right click to extend the marked region; Left double-click
… …
1376B<Meta> modifier) to be inserted as if it had been typed on the keyboard. 1463B<Meta> modifier) to be inserted as if it had been typed on the keyboard.
1377 1464
1378Pressing B<Shift-Insert> causes the value of the PRIMARY selection to be 1465Pressing B<Shift-Insert> causes the value of the PRIMARY selection to be
1379inserted too. 1466inserted too.
1380 1467
1468rxvt-unicode also provides the bindings B<Ctrl-Meta-c> and
1469<Ctrl-Meta-v> to interact with the CLIPBOARD selection. The first
1470binding causes the value of the internal selection to be copied to the
1471CLIPBOARD selection, while the second binding causes the value of the
1472CLIPBOARD selection to be inserted.
1473
1381=back 1474=back
1382 1475
1383=head1 CHANGING FONTS 1476=head1 CHANGING FONTS
1384 1477
1385Changing fonts (or font sizes, respectively) via the keypad is not yet 1478Changing fonts (or font sizes, respectively) via the keypad is not yet
… …
1402and character codes using the keyboard. It consists of 4 parts. The 1495and character codes using the keyboard. It consists of 4 parts. The
1403first part is available if rxvt-unicode has been compiled with 1496first part is available if rxvt-unicode has been compiled with
1404C<--enable-frills>, the rest is available when rxvt-unicode was compiled 1497C<--enable-frills>, the rest is available when rxvt-unicode was compiled
1405with C<--enable-iso14755>. 1498with C<--enable-iso14755>.
1406 1499
1407=over 4 1500=over
1408 1501
1409=item * 5.1: Basic method 1502=item * 5.1: Basic method
1410 1503
1411This allows you to enter unicode characters using their hexcode. 1504This allows you to enter unicode characters using their hexcode.
1412 1505
… …
1473In addition to the default foreground and background colours, 1566In addition to the default foreground and background colours,
1474B<@@RXVT_NAME@@> can display up to 88/256 colours: 8 ANSI colours plus 1567B<@@RXVT_NAME@@> can display up to 88/256 colours: 8 ANSI colours plus
1475high-intensity (potentially bold/blink) versions of the same, and 72 (or 1568high-intensity (potentially bold/blink) versions of the same, and 72 (or
1476240 in 256 colour mode) colours arranged in an 4x4x4 (or 6x6x6) colour RGB 1569240 in 256 colour mode) colours arranged in an 4x4x4 (or 6x6x6) colour RGB
1477cube plus a 8 (24) colour greyscale ramp. 1570cube plus a 8 (24) colour greyscale ramp.
1571
1572B<@@RXVT_NAME@@> supports direct 24-bit fg/bg RGB colour escapes
1573C< ESC [ 38 ; 2 ; R ; G ; Bm > / C< ESC [ 48 ; 2; R ; G ; Bm >. However the
1574number of 24-bit colours that can be used is limited: an internal 7x7x5 (256
1575colour mode) or 6x6x4 (88 colour mode) colour cube is used to index into the
157624-bit colour space. When indexing collisions happen, the nearest old colour in
1577the cube will be adapted to the new 24-bit RGB colour. That means one cannot
1578use many similar 24-bit colours. It's typically not a problem in common
1579scenarios.
1478 1580
1479Here is a list of the ANSI colours with their names. 1581Here is a list of the ANSI colours with their names.
1480 1582
1481=begin table 1583=begin table
1482 1584
… …
1509The following text gives values for the standard 88 colour mode (and 1611The following text gives values for the standard 88 colour mode (and
1510values for the 256 colour mode in parentheses). 1612values for the 256 colour mode in parentheses).
1511 1613
1512The RGB cube uses indices 16..79 (16..231) using the following formulas: 1614The RGB cube uses indices 16..79 (16..231) using the following formulas:
1513 1615
1514 index_88 = (r * 4 + g) * 4 + b + 16 # r, g, b = 0..3 1616 index_88 = (r * 4 + g) * 4 + b + 16 # r, g, b = 0..3
1515 index_256 = (r * 16 + g) * 16 + b + 16 # r, g, b = 0..15 1617 index_256 = (r * 6 + g) * 6 + b + 16 # r, g, b = 0..5
1516 1618
1517The grayscale ramp uses indices 80..87 (232..239), from 10% to 90% in 10% 1619The grayscale ramp uses indices 80..87 (232..239), from 10% to 90% in 10%
1518steps (1/26 to 25/26 in 1/26 steps) - black and white are already part of 1620steps (1/26 to 25/26 in 1/26 steps) - black and white are already part of
1519the RGB cube. 1621the RGB cube.
1520 1622
… …
1583 1685
1584=head1 ENVIRONMENT 1686=head1 ENVIRONMENT
1585 1687
1586B<@@RXVT_NAME@@> sets and/or uses the following environment variables: 1688B<@@RXVT_NAME@@> sets and/or uses the following environment variables:
1587 1689
1588=over 4 1690=over
1589 1691
1590=item B<TERM> 1692=item B<TERM>
1591 1693
1592Normally set to C<rxvt-unicode>, unless overwritten at configure time, via 1694Normally set to C<rxvt-unicode>, unless overwritten at configure time, via
1593resources or on the command line. 1695resources or on the command line.
… …
1664 1766
1665=back 1767=back
1666 1768
1667=head1 FILES 1769=head1 FILES
1668 1770
1669=over 4 1771=over
1670 1772
1671=item B</usr/lib/X11/rgb.txt> 1773=item B</usr/lib/X11/rgb.txt>
1672 1774
1673Colour names. 1775Colour names.
1674 1776
… …
1679@@RXVT_NAME@@(7), @@RXVT_NAME@@c(1), @@RXVT_NAME@@d(1), @@RXVT_NAME@@-extensions(1), 1781@@RXVT_NAME@@(7), @@RXVT_NAME@@c(1), @@RXVT_NAME@@d(1), @@RXVT_NAME@@-extensions(1),
1680@@RXVT_NAME@@perl(3), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5) 1782@@RXVT_NAME@@perl(3), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5)
1681 1783
1682=head1 CURRENT PROJECT COORDINATOR 1784=head1 CURRENT PROJECT COORDINATOR
1683 1785
1684=over 4 1786=over
1685 1787
1686=item Project Coordinator 1788=item Project Coordinator
1687 1789
1688Marc A. Lehmann <rxvt-unicode@schmorp.de>. 1790Marc A. Lehmann <rxvt-unicode@schmorp.de>.
1689 1791
… …
1691 1793
1692=back 1794=back
1693 1795
1694=head1 AUTHORS 1796=head1 AUTHORS
1695 1797
1696=over 4 1798=over
1697 1799
1698=item John Bovey 1800=item John Bovey
1699 1801
1700University of Kent, 1992, wrote the original Xvt. 1802University of Kent, 1992, wrote the original Xvt.
1701 1803

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines