--- rxvt-unicode/doc/rxvt.1.pod 2007/12/12 19:57:13 1.153 +++ rxvt-unicode/doc/rxvt.1.pod 2014/10/11 22:02:50 1.238 @@ -94,15 +94,25 @@ =item B<-display> I -Attempt to open a window on the named X display (B<-d> still -respected). In the absence of this option, the display specified by the -B environment variable is used. +Attempt to open a window on the named X display (the older form B<-d> +is still respected. but deprecated). In the absence of this option, the +display specified by the B environment variable is used. =item B<-depth> I -Compile I: Attempt to find a visual with the given bit depth; +Compile I: Attempt to find a visual with the given bit depth; resource B. +[Please note that many X servers (and libXft) are buggy with +respect to C<-depth 32> and/or alpha channels, and will cause all sorts +of graphical corruption. This is harmless, but we can't do anything about +this, so watch out] + +=item B<-visual> I + +Compile I: Use the given visual (see e.g. C for possible +visual ids). + =item B<-geometry> I Window geometry (B<-g> still respected); resource B. @@ -119,16 +129,6 @@ Turn on/off skip scrolling (allow multiple screens per refresh); resource B. -=item B<-tr>|B<+tr> - -Turn on/off illusion of a transparent window background; resource B. - -B<-ip> is still accepted as an obsolete alias but will be removed in -future versions. - -I - =item B<-fade> I Fade the text by the given percentage when focus is lost. Small values @@ -140,44 +140,11 @@ Fade to this colour when fading is used (see B<-fade>). The default colour is opaque black. resource B. -=item B<-tint> I - -Tint the transparent background pixmap with the given colour when -transparency is enabled with B<-tr>. This only works for -non-tiled backgrounds, currently. See also the B<-sh> option that can be -used to brighten or darken the image in addition to tinting it. -Please note that certain tint colours can be applied on the server-side, -thus yielding performance gain of two orders of magnitude. These colours are: -blue, red, green, cyan, magenta, yellow, and those close to them. Also -pure black and pure white colors essentially mean no tinting; resource -I. Example: - - @@RXVT_NAME@@ -tr -tint blue -sh 40 - -=item B<-sh> I - -Darken (0 .. 100) or lighten (100 .. 200) the transparent -background image in addition to (or instead of) tinting it; -resource I. - -=item B<-blt> I - -Specify background blending type. If background pixmap is specified -at the same time as transparency - such pixmap will be blended over -transparency image, using method specified. Supported values are : -B, B, B - color values averaging, B, -B, B, B, B, B, B, -B, B, B, B, B. The default is -alpha-blending. Compile I; resource I. - -=item B<-blr> I +=item B<-icon> I -Apply Gaussian Blur with the specified radii to the transparent -background image. If single number is specified - both vertical and -horizontal radii are considered to be the same. Setting one of the -radii to 1 and another to a large number creates interesting effects -on some backgrounds. Maximum radius value is 128. Compile I; -resource I. +Compile I: Use the specified image as application icon. This +is used by many window managers, taskbars and pagers to represent the +application window; resource I. =item B<-bg> I @@ -187,13 +154,6 @@ Window foreground colour; resource B. -=item B<-pixmap> I - -Compile I: Specify image file for the background and also -optionally specify its scaling with a geometry string. Note you may need to -add quotes to avoid special shell interpretation of the C<;> in the -command-line; for more details see resource B. - =item B<-cr> I The cursor colour; resource B. @@ -247,7 +207,7 @@ =item B<-is>|B<+is> -Compile I: Bold/Italic font styles imply high intensity +Compile I: Bold/Blink font styles imply high intensity foreground/background (default). See resource B for details. @@ -261,6 +221,10 @@ Start as a login-shell/sub-shell; resource B. +=item B<-mc> I + +Specify the maximum time between multi-click selections. + =item B<-ut>|B<+ut> Compile I: Inhibit/enable writing a utmp entry; resource @@ -275,6 +239,15 @@ Turn on/off scrollbar; resource B. +=item B<-sr>|B<+sr> + +Put scrollbar on right/left; resource B. + +=item B<-st>|B<+st> + +Display rxvt (non XTerm/NeXT) scrollbar without/with a trough; +resource B. + =item B<-si>|B<+si> Turn on/off scroll-to-bottom on TTY output inhibit; resource @@ -291,15 +264,6 @@ This only takes effect if B<-si> is also given; resource B. -=item B<-sr>|B<+sr> - -Put scrollbar on right/left; resource B. - -=item B<-st>|B<+st> - -Display rxvt (non XTerm/NeXT) scrollbar without/with a trough; -resource B. - =item B<-ptab>|B<+ptab> If enabled (default), "Horizontal Tab" characters are being stored as @@ -312,6 +276,10 @@ Blink the cursor; resource B. +=item B<-uc>|B<+uc> + +Make the cursor underlined; resource B. + =item B<-iconic> Start iconified, if the window manager supports that option. @@ -337,13 +305,19 @@ Compile I: Set MWM hints to request a borderless window, i.e. if honoured by the WM, the rxvt-unicode window will not have window -decorations; resource B. +decorations; resource B. If the window manager does not +support MWM hints (e.g. kwin), enables override-redirect mode. =item B<-override-redirect> Compile I: Sets override-redirect on the window; resource B. +=item B<-dockapp> + +Sets the initial state of the window to WithdrawnState, which makes +window managers that support this extension treat it as a dockapp. + =item B<-sbg> Compile I: Disable the usage of the built-in block graphics/line @@ -357,6 +331,13 @@ the display. Useful to work around font rendering problems; resource B. +=item B<-letsp> I + +Compile I: Amount to adjust the computed character width by +to control overall letter spacing. Negative values will tighten up the +letter spacing, positive values will space letters out more. Useful to +work around odd font metrics; resource B. + =item B<-tn> I This option specifies the name of the terminal type to be set in the @@ -452,6 +433,12 @@ it exits. Instead, it will wait till it is being killed or closed by the user; resource B. +=item B<-cd> I + +Sets the working directory for the shell (or the command specified via +B<-e>). The I must be an absolute path and it must exist for +@@RXVT_NAME@@ to start; resource B. + =item B<-xrm> I Works like the X Toolkit option of the same name, by adding the I @@ -544,10 +531,10 @@ starts. @@RXVT_NAME@@ will consult the following files/resources in order, with later settings overwriting earlier ones: - 1. system-wide app-defaults file, either locale-dependent OR global - 2. app-defaults file in $XAPPLRESDIR - 3. RESOURCE_MANAGER property on root-window OR $HOME/.Xdefaults - 4. SCREEN_RESOURCES for the current screen + 1. app-defaults file in $XAPPLRESDIR + 2. $HOME/.Xdefaults + 3. RESOURCE_MANAGER property on root-window of screen 0 + 4. SCREEN_RESOURCES property on root-window of the current screen 5. $XENVIRONMENT file OR $HOME/.Xdefaults- 6. resources specified via -xrm on the commandline @@ -569,6 +556,13 @@ Compile I: Attempt to find a visual with the given bit depth; option B<-depth>. +=item B I + +Compile I: Turn on/off double-buffering for xft (default enabled). +On some card/driver combination enabling it slightly decreases +performance, on most it greatly helps it. The slowdown is small, so it +should normally be enabled. + =item B I Create the window with the specified X window geometry [default 80x24]; @@ -591,7 +585,7 @@ high-intensity (bold = bright foreground, blink = bright background) colours. The canonical names are as follows: 0=black, 1=red, 2=green, 3=yellow, 4=blue, 5=magenta, 6=cyan, 7=white, but the actual colour -names used are listed in the B section. +names used are listed in the B section. Colours higher than 15 cannot be set using resources (yet), but can be changed using an escape command (see @@RXVT_NAME@@(7)). @@ -612,16 +606,21 @@ Use the specified colour to display underlined characters when the foreground colour is the default. -=item B I - -Use the specified colour as the background for reverse video characters -when OPTION_HC is disabled (--disable-frills). - =item B I If set, use the specified colour as the colour for the underline itself. If unset, use the foreground colour. +=item B I + +If set, use the specified colour as the background for highlighted +characters. If unset, use reverse video. + +=item B I + +If set and highlightColor is set, use the specified colour as the +foreground for highlighted characters. + =item B I Use the specified colour for the cursor. The default is to use the @@ -637,7 +636,7 @@ B: simulate reverse video by foreground and background colours; option B<-rv>. B: regular screen colours [default]; option -B<+rv>. See note in B section. +B<+rv>. See note in B section. =item B I @@ -661,16 +660,6 @@ if the refresh is too fast for the human eye to read anything (or the monitor to display anything); option B<+ss>. -=item B I - -Turn on/off illusion of a transparent window background. - -B is still accepted as an obsolete alias but will be removed in -future versions. - -I - =item B I Fade the text by the given percentage when focus is lost; option B<-fade>. @@ -680,24 +669,9 @@ Fade to this colour, when fading is used (see B). The default colour is black; option B<-fadecolor>. -=item B I - -Tint the transparent background pixmap with the given colour; option -B<-tint>. - -=item B I - -Darken (0 .. 100) or lighten (-1 .. -100) the transparent background image -in addition to tinting it; option B<-sh>. - -=item B I - -Specify background blending type; option B<-blt>. - -=item B I +=item B I -Apply Gaussian Blurr with the specified radius to the transparent -background image; option B<-blr>. +Set the application icon pixmap; option B<-icon>. =item B I @@ -713,36 +687,6 @@ The colour of the border around the text area and between the scrollbar and the text. -=item B I - -Use the specified image file for the background and also -optionally specify its scaling with a geometry string B, -(default C<0x0+50+50>) in which B<"W" / "H"> specify the -horizontal/vertical scale (percent), and B<"X" / "Y"> locate the image -centre (percent). A scale of 0 displays the image with tiling. A scale -of 1 displays the image without any scaling. A scale of 2 to 9 specifies -an integer number of images in that direction. No image will be magnified -beyond 10 times its original size. The maximum permitted scale is 1000. -Additional operations can be specified after colon B<:op1:op2...>. -Supported operations are: - - tile force background image to be tiled and not scaled. Equivalent to 0x0, - propscale will scale image keeping proportions, - auto will scale image to match window size. Equivalent to 100x100; - hscale will scale image horizontally to the window size; - vscale will scale image vertically to the window size; - scale will scale image to match window size; - root will tile image as if it was a root window background, auto-adjusting - whenever terminal window moves. - -If used in conjunction with B<-tr> option, the specified pixmap will be -blended over transparency image using either alpha-blending, or any -other blending type, specified with B<-blt "type"> option. - -=item B I - -Specify the colon-delimited search path for finding background image files. - =item B I Select the fonts to be used. This is a comma separated list of font names @@ -774,7 +718,7 @@ The second font is just used to add additional unicode characters not in the base font, likewise the third, which is unfortunately non-bold, but -the bold version of the font does contain less characters, so this is a +the bold version of the font does contain fewer characters, so this is a useful supplement. The third font is an Xft font with aliasing turned off, and the characters @@ -808,23 +752,11 @@ =item B I When font styles are not enabled, or this option is enabled (B, -option B<-is>, the default), bold and italic font styles imply high +option B<-is>, the default), bold/blink font styles imply high intensity foreground/background colours. Disabling this option (B, option B<+is>) disables this behaviour, the high intensity colours are not reachable. -=item B I - -Set mouse selection style to B which is 2.20, B which -is xterm style with 2.20 old word selection, or anything else which -gives xterm style selection. Only effective when the original (non-perl) -selection code is in use. - -=item B I - -Set scrollbar style to B, B, B or B. B is -the author's favourite. - =item B I Set window title string, the default title is the command-line @@ -847,6 +779,8 @@ B: set the urgency hint for the wm on receipt of a bell character. B: do not set the urgency hint [default]. +@@RXVT_NAME@@ resets the urgency hint on every focus change. + =item B I B: use visual bell on receipt of a bell character; option B<-vb>. @@ -858,6 +792,11 @@ the shell; option B<-ls>. B: start as a normal sub-shell [default]; option B<+ls>. +=item B I + +Specify the maximum time in milliseconds between multi-click select +events. The default is 500 milliseconds; option B<-mc>. + =item B I B: inhibit writing record into the system log file B; @@ -879,6 +818,15 @@ This creates a new file in your home directory with the screen contents every time you hit C. +=item B I + +Set scrollbar style to B, B, B or B. B is +the author's favourite. + +=item B I + +Set the scrollbar width in pixels. + =item B I B: enable the scrollbar [default]; option B<-sb>. B: @@ -907,9 +855,10 @@ =item B I -B: scroll with scrollback buffer when tty receives new lines (and -B is False); option B<-sw>. B: do not scroll -with scrollback buffer when tty receives new lines; option B<+sw>. +B: scroll with scrollback buffer when tty receives new lines (i.e. +try to show the same lines) and B is False; option +B<-sw>. B: do not scroll with scrollback buffer when tty receives +new lines; option B<+sw>. =item B I @@ -975,6 +924,11 @@ B: blink the cursor. B: do not blink the cursor [default]; option B<-bc>. +=item B I + +B: Make the cursor underlined. B: Make the cursor a box [default]; +option B<-uc>. + =item B I B: blank the pointer when a key is pressed or after a set number @@ -997,7 +951,7 @@ =item B I The string to send when the backspace key is pressed. If set to B -or unset it will send B (code 127) or, if shifted, B +or unset it will send B (code 127) or, with control, B (code 8) - which can be reversed with the appropriate DEC private mode escape sequence. @@ -1086,8 +1040,8 @@ Turn on/off secondary screen scroll (default enabled). If this option is enabled, scrolls on the secondary screen will change the -scrollback buffer and switching to/from the secondary screen will -instead scroll the screen up. +scrollback buffer and, when secondaryScreen is off, switching +to/from the secondary screen will instead scroll the screen up. =item B: I @@ -1096,77 +1050,89 @@ it exits. Instead, it will wait till it is being killed or closed by the user. -=item BI: I +=item B: I + +Sets the working directory for the shell (or the command specified via +B<-e>). The I must be an absolute path and it must exist for +@@RXVT_NAME@@ to start. If it isn't specified then the current working +directory will be used; option B<-cd>. + +=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. - -I may contain escape values (C<\n>: newline, C<\000>: octal -number), see RESOURCES in C for futher details. +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>). + +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. + +An action starts with an action prefix that selects a certain type +of action, followed by a colon. An action string without colons is +interpreted as a literal string to pass to the tty (as if it was +prefixed with C). -You can define a range of keysyms in one shot by providing a I -with pattern B, where the delimiter `/' -should be a character not used by the strings. +The following action prefixes are known - extensions can provide +additional prefixes: -Its usage can be demonstrated by an example: +=over 4 - URxvt.keysym.M-C-0x61: list|\033 +=item string:STRING -The above line is equivalent to the following three lines: +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: - URxvt.keysym.Meta-Control-0x61: \033 - URxvt.keysym.Meta-Control-0x62: \033 - URxvt.keysym.Meta-Control-0x63: \033 + URxvt.keysym.Shift-Tab: string:echo rm -rf /\n -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": +This could in theory be used to completely redefine your keymap. - URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007 +=item command:STRING -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 at 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: +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@@. - URxvt.keysym.Insert: - URxvt.keysym.S-Insert: builtin: +For example the following means "change the current locale to C +when Control-Meta-c is being pressed": -The first line defines a mapping for C and I combination -of modifiers. The second line re-establishes the default mapping for -C. + 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 @@ -1181,6 +1147,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-M-c: builtin-string: + URxvt.keysym.C-M-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 +necessary. + +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 @@ -1191,36 +1226,38 @@ 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, and extensions which +are mentioned in B resources. + +Any extension such that a corresponding resource is given on the +command line is automatically appended to B. 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. =item B: I Perl code to be evaluated when all extensions have been registered. See -the @@RXVT_NAME@@perl(3) manpage. Due to security reasons, this resource -will be ignored when running setuid/setgid. +the @@RXVT_NAME@@perl(3) manpage. =item B: I Colon-separated list of additional directories that hold extension -scripts. When looking for extensions specified by the C resource, -@@RXVT_NAME@@ will first look in these directories and then in -F<@@RXVT_LIBDIR@@/urxvt/perl/>. Due to security reasons, this resource -will be ignored when running setuid/setgid. +scripts. When looking for perl extensions, @@RXVT_NAME@@ will first look +in these directories, then in C<$URXVT_PERL_LIB>, F<$HOME/.urxvt/ext> and +lastly in F<@@RXVT_LIBDIR@@/urxvt/perl/>. See the @@RXVT_NAME@@perl(3) manpage. @@ -1234,12 +1271,14 @@ 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.: -=item B: I + URxvt.keysym.M-s: searchable-scrollback:start + +=item B: I Specifies the program to be started with a URL argument. Used by the C and C perl extensions. @@ -1253,12 +1292,130 @@ Compile I: Sets override-redirect for the terminal window, making it almost invisible to window managers; option B<-override-redirect>. +=item B I + +Turn on/off ISO 14755 (default enabled). + =item B I Turn on/off ISO 14755 5.2 mode (default enabled). =back +=head1 BACKGROUND IMAGE OPTIONS AND RESOURCES + +=over 4 + +=item B<-pixmap> I + +=item B I + +Compile I: Use the specified image file as the window's +background and also optionally specify a colon separated list of +operations to modify it. Note that you may need to quote the C<;> +character when using the command line option, as C<;> is usually a +metacharacter in shells. Supported operations are: + +=over 4 + +=item B + +sets scale and position. B<"W" / "H"> specify the horizontal/vertical +scale (percent), and B<"X" / "Y"> locate the image centre (percent). A +scale of 0 disables scaling. + +=item B + +enables tiling + +=item B + +maintain the image aspect ratio when scaling + +=item B + +use the position of the terminal window relative to the root window as +the image offset, simulating a root window background + +=back + +The default scale and position setting is C<100x100+50+50>. +Alternatively, a predefined set of templates can be used to achieve +the most common setups: + +=over 4 + +=item B + +the image is tiled with no scaling. Equivalent to 0x0+0+0:op=tile + +=item B + +the image is scaled to fill the whole window maintaining the aspect +ratio and centered. Equivalent to 100x100+50+50:op=keep-aspect + +=item B + +the image is scaled to fill the whole window. Equivalent to 100x100 + +=item B + +the image is centered with no scaling. Equivalent to 0x0+50+50 + +=item B + +the image is tiled with no scaling and using 'root' positioning. +Equivalent to 0x0:op=tile:op=root-align + +=back + +If multiple templates are specified the last one wins. Note that a +template overrides all the scale, position and operations settings. + +If used in conjunction with pseudo-transparency, the specified pixmap +will be blended over the transparent background using alpha-blending. + +=item B<-tr>|B<+tr> + +=item B I + +Turn on/off pseudo-transparency by using the root pixmap as background. + +B<-ip> (B) is still accepted as an obsolete alias but +will be removed in future versions. + +=item B<-tint> I + +=item B I + +Tint the transparent background with the given colour. Note that a +black tint yields a completely black image while a white tint yields +the image unchanged. + +=item B<-sh> I + +=item B I + +Darken (0 .. 99) or lighten (101 .. 200) the transparent background. +A value of 100 means no shading. + +=item B<-blr> I + +=item B I + +Apply gaussian blur with the specified radius to the transparent +background. If a single number is specified, the vertical and +horizontal radii are considered to be the same. Setting one of the +radii to 1 and the other to a large number creates interesting effects +on some backgrounds. The maximum radius value is 128. An horizontal or +vertical radius of 0 disables blurring. + +=item B I + +Specify the colon-delimited search path for finding background image files. + +=back + =head1 THE SCROLLBAR Lines of text that scroll off the top of the B<@@RXVT_NAME@@> window @@ -1314,6 +1471,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 @@ -1404,12 +1567,15 @@ allow this feature, B<@@RXVT_NAME@@> may need to be installed setuid root on some systems or setgid to root or to some other group on others. -=head1 COLORS AND GRAPHICS +=head1 COLOURS AND GRAPHICS In addition to the default foreground and background colours, -B<@@RXVT_NAME@@> can display up to 16 colours (8 ANSI colours plus -high-intensity bold/blink versions of the same). Here is a list of the -colours with their names. +B<@@RXVT_NAME@@> can display up to 88/256 colours: 8 ANSI colours plus +high-intensity (potentially bold/blink) versions of the same, and 72 (or +240 in 256 colour mode) colours arranged in an 4x4x4 (or 6x6x6) colour RGB +cube plus a 8 (24) colour greyscale ramp. + +Here is a list of the ANSI colours with their names. =begin table @@ -1439,52 +1605,80 @@ a number 0-15, as a convenient shorthand to reference the colour name of color0-color15. -In addition to the colours defined above, @@RXVT_NAME@@ offers an -additional 72 colours. The first 64 of those (with indices 16 to 79) -consist of a 4*4*4 RGB colour cube (i.e. I), followed by 8 additional shades of gray (with indices 80 to 87). - -Together, all those colours implement the 88 colour xterm colours. Only -the first 16 can be changed using resources currently, the rest can only -be changed via command sequences ("escape codes"). +The following text gives values for the standard 88 colour mode (and +values for the 256 colour mode in parentheses). + +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 * 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 +the RGB cube. + +Together, all those colours implement the 88 (256) colour xterm +colours. Only the first 16 can be changed using resources currently, the +rest can only be changed via command sequences ("escape codes"). + +Applications are advised to use terminfo or command sequences to discover +number and RGB values of all colours (yes, you can query this...). Note that B<-rv> (B<"reverseVideo: True">) simulates reverse video by always swapping the foreground/background colours. This is in contrast to I(1) where the colours are only swapped if they have not otherwise been specified. For example, -=over 4 - -=item B<@@RXVT_NAME@@ -fg Black -bg White -rv> + @@RXVT_NAME@@ -fg Black -bg White -rv -would yield White on Black, while on I(1) it would yield Black -on White. - -=back +would yield White on Black, while on I(1) it would yield Black on +White. =head2 ALPHA CHANNEL SUPPORT If Xft support has been compiled in and as long as Xft/Xrender/X don't get -their act together, rxvt-unicode will support C -(recommended, but B have 4 digits/component) colour specifications, -in addition to the ones provided by X, where the additional A component -specifies opacity (alpha) values. The minimum value of C<0> is completely -transparent). You can also prefix any color with C<[percent]>, where -C is a decimal percentage (0-100) that specifies the opacity of -the color, where C<0> is completely transparent and C<100> is completelxy -opaque. - -You probably need to specify B<"-depth 32">, too, and have the luck that -your X-server uses ARGB pixel layout, as X is far from just supporting -ARGB visuals out of the box, and rxvt-unicode just fudges around. +their act together, rxvt-unicode will do its own alpha channel management: + +You can prefix any colour with an opaqueness percentage enclosed in +brackets, i.e. C<[percent]>, where C is a decimal percentage +(0-100) that specifies the opacity of the colour, where C<0> is completely +transparent and C<100> is completely opaque. For example, C<[50]red> is a +half-transparent red, while C<[95]#00ff00> is an almost opaque green. This +is the recommended format to specify transparency values, and works with +all ways to specify a colour. + +For complete control, rxvt-unicode also supports +C (exactly four hex digits/component) colour +specifications, where the additional C component specifies opacity +(alpha) values. The minimum value of C<0000> is completely transparent, +while C is completely opaque). The two example colours from +earlier could also be specified as C and +C. + +You probably need to specify B<"-depth 32">, too, to force a visual with +alpha channels, and have the luck that your X-server uses ARGB pixel +layout, as X is far from just supporting ARGB visuals out of the box, and +rxvt-unicode just fudges around. -For example, the following selects an almost completely transparent red +For example, the following selects an almost completely transparent black background, and an almost opaque pink foreground: - @@RXVT_NAME@@ -depth 32 -bg rgba:0000/0000/0000/aaaa -fg "[80]pink" + @@RXVT_NAME@@ -depth 32 -bg rgba:0000/0000/0000/4444 -fg "[80]pink" -I +When not using a background image, then the interpretation of the +alpha channel is up to your compositing manager (most interpret it as +transparency of course). + +When using a background pixmap or pseudo-transparency, then the background +colour will always behave as if it were completely transparent (so the +background image shows instead), regardless of how it was specified, while +other colours will either be transparent as specified (the background +image will show through) on servers supporting the RENDER extension, or +fully opaque on servers not supporting the RENDER EXTENSION. + +Please note that due to bugs in Xft, specifying alpha values might result +in garbage being displayed when the X-server does not support the RENDER +extension. =head1 ENVIRONMENT @@ -1528,18 +1722,29 @@ =item B Used by @@RXVT_NAME@@ to connect to the display and set to the correct -display in its child processes. +display in its child processes if C<-display> isn't used to override. It +defaults to C<:0> if it doesn't exist. =item B The shell to be used for command execution, defaults to C. -=item B +=item B [I] The unix domain socket path used by @@RXVT_NAME@@c(1) and @@RXVT_NAME@@d(1). -Default F<<< $HOME/.rxvt-unicode-I<< > >>>. +Default F<<< $HOME/.urxvt/urxvtd-I<< >> >>>. + +=item B + +Additional F<:>-separated library search path for perl extensions. Will be +searched after B<-perl-lib> but before F<~/.urxvt/ext> and the system library +directory. + +=item B + +See L<@@RXVT_NAME@@perl>(3). =item B @@ -1549,7 +1754,7 @@ =item B -Directory where various X resource files are being located. +Directory where application-specific X resource files are located. =item B @@ -1564,13 +1769,14 @@ =item B -Color names. +Colour names. =back =head1 SEE ALSO -@@RXVT_NAME@@(7), @@RXVT_NAME@@c(1), @@RXVT_NAME@@d(1), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5) +@@RXVT_NAME@@(7), @@RXVT_NAME@@c(1), @@RXVT_NAME@@d(1), @@RXVT_NAME@@-extensions(1), +@@RXVT_NAME@@perl(3), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5) =head1 CURRENT PROJECT COORDINATOR @@ -1578,7 +1784,7 @@ =item Project Coordinator -Marc A. Lehmann L<< >> +Marc A. Lehmann . L @@ -1592,40 +1798,40 @@ University of Kent, 1992, wrote the original Xvt. -=item Rob Nation L<< >> +=item Rob Nation very heavily modified Xvt and came up with Rxvt -=item Angelo Haritsis L<< >> +=item Angelo Haritsis wrote the Greek Keyboard Input (no longer in code) -=item mj olesen L<< >> +=item mj olesen Wrote the menu system. Project Coordinator (changes.txt 2.11 to 2.21) -=item Oezguer Kesim L<< >> +=item Oezguer Kesim Project Coordinator (changes.txt 2.21a to 2.4.5) -=item Geoff Wing L<< >> +=item Geoff Wing Rewrote screen display and text selection routines. Project Coordinator (changes.txt 2.4.6 - rxvt-unicode) -=item Marc Alexander Lehmann L<< >> +=item Marc Alexander Lehmann Forked rxvt-unicode, unicode support, rewrote almost all the code, perl extension, random hacks, numerous bugfixes and extensions. Project Coordinator (Changes 1.0 -) -=item Emanuele Giaquinta L<< >> +=item Emanuele Giaquinta -Pty/tty/utmp/wtmp rewrite, lots of random hacking and bugfixing. +pty/utmp code rewrite, image code improvements, many random hacks and bugfixes. =back