[ViewVC] Diff of: cvs/rxvt-unicode/doc/rxvtperl.3.txt

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.20 by root, Wed Jan 11 01:00:04 2006 UTC vs.
Revision 1.45 by root, Thu Nov 2 17:37:47 2006 UTC

…		…
12	# start a rxvt using it:	12	# start a rxvt using it:
13		13
14	rxvt --perl-lib $HOME -pe grab_test	14	rxvt --perl-lib $HOME -pe grab_test
15		15
16	DESCRIPTION	16	DESCRIPTION
17	Everytime a terminal object gets created, extension scripts specified	17	Every time a terminal object gets created, extension scripts specified
18	via the "perl" resource are loaded and associated with it.	18	via the "perl" resource are loaded and associated with it.
19		19
20	Scripts are compiled in a 'use strict' and 'use utf8' environment, and	20	Scripts are compiled in a 'use strict' and 'use utf8' environment, and
21	thus must be encoded as UTF-8.	21	thus must be encoded as UTF-8.
22		22
…		…
29		29
30	You can activate them like this:	30	You can activate them like this:
31		31
32	rxvt -pe <extensionname>	32	rxvt -pe <extensionname>
33		33
		34	Or by adding them to the resource for extensions loaded by default:
		35
		36	URxvt.perl-ext-common: default,automove-background,selection-autotransform
		37
34	selection (enabled by default)	38	selection (enabled by default)
35	(More) intelligent selection. This extension tries to be more	39	(More) intelligent selection. This extension tries to be more
36	intelligent when the user extends selections (double-click). Right	40	intelligent when the user extends selections (double-click and
37	now, it tries to select urls and complete shell-quoted arguments,	41	further clicks). Right now, it tries to select words, urls and
38	which is very convenient, too, if your ls supports	42	complete shell-quoted arguments, which is very convenient, too, if
39	"--quoting-style=shell".	43	your ls supports "--quoting-style=shell".
40		44
		45	A double-click usually selects the word under the cursor, further
		46	clicks will enlarge the selection.
		47
		48	The selection works by trying to match a number of regexes and
		49	displaying them in increasing order of length. You can add your own
		50	regexes by specifying resources of the form:
		51
		52	URxvt.selection.pattern-0: perl-regex
		53	URxvt.selection.pattern-1: perl-regex
		54	...
		55
		56	The index number (0, 1...) must not have any holes, and each regex
		57	must contain at least one pair of capturing parentheses, which will
		58	be used for the match. For example, the following adds a regex that
		59	matches everything between two vertical bars:
		60
		61	URxvt.selection.pattern-0: \\\|([^\|]+)\\\|
		62
		63	Another example: Programs I use often output "absolute path: " at
		64	the beginning of a line when they process multiple files. The
		65	following pattern matches the filename (note, there is a single
		66	space at the very end):
		67
		68	URxvt.selection.pattern-0: ^(/[^:]+):\
		69
		70	You can look at the source of the selection extension to see more
		71	interesting uses, such as parsing a line from beginning to end.
		72
41	It also offers the following bindable keyboard command:	73	This extension also offers following bindable keyboard commands:
42		74
43	rot13	75	rot13
44	Rot-13 the selection when activated. Used via keyboard trigger:	76	Rot-13 the selection when activated. Used via keyboard trigger:
45		77
46	URxvt.keysym.C-M-r: perl:selection:rot13	78	URxvt.keysym.C-M-r: perl:selection:rot13
47		79
48	option-popup (enabled by default)	80	option-popup (enabled by default)
49	Binds a popup menu to Ctrl-Button2 that lets you toggle (some)	81	Binds a popup menu to Ctrl-Button2 that lets you toggle (some)
50	options at runtime.	82	options at runtime.
51		83
		84	Other extensions can extend this popup menu by pushing a code
		85	reference onto "@{ $term-"{option_popup_hook} }>, which gets called
		86	whenever the popup is being displayed.
		87
		88	It's sole argument is the popup menu, which can be modified. It
		89	should either return nothing or a string, the initial boolean value
		90	and a code reference. The string will be used as button text and the
		91	code reference will be called when the toggle changes, with the new
		92	boolean value as first argument.
		93
		94	The following will add an entry "myoption" that changes
		95	"$self-"{myoption}>:
		96
		97	push @{ $self->{term}{option_popup_hook} }, sub {
		98	("my option" => $myoption, sub { $self->{myoption} = $_[0] })
		99	};
		100
52	selection-popup (enabled by default)	101	selection-popup (enabled by default)
53	Binds a popup menu to Ctrl-Button3 that lets you convert the	102	Binds a popup menu to Ctrl-Button3 that lets you convert the
54	selection text into various other formats/action (such as uri	103	selection text into various other formats/action (such as uri
55	unescaping, perl evalution, web-browser starting etc.), depending on	104	unescaping, perl evaluation, web-browser starting etc.), depending
56	content.	105	on content.
		106
		107	Other extensions can extend this popup menu by pushing a code
		108	reference onto "@{ $term-"{selection_popup_hook} }>, which gets
		109	called whenever the popup is being displayed.
		110
		111	It's sole argument is the popup menu, which can be modified. The
		112	selection is in $_, which can be used to decide whether to add
		113	something or not. It should either return nothing or a string and a
		114	code reference. The string will be used as button text and the code
		115	reference will be called when the button gets activated and should
		116	transform $_.
		117
		118	The following will add an entry "a to b" that transforms all "a"s in
		119	the selection to "b"s, but only if the selection currently contains
		120	any "a"s:
		121
		122	push @{ $self->{term}{selection_popup_hook} }, sub {
		123	/a/ ? ("a to be" => sub { s/a/b/g }
		124	: ()
		125	};
57		126
58	searchable-scrollback<hotkey> (enabled by default)	127	searchable-scrollback<hotkey> (enabled by default)
59	Adds regex search functionality to the scrollback buffer, triggered	128	Adds regex search functionality to the scrollback buffer, triggered
60	by a hotkey (default: "M-s"). When in search mode, normal terminal	129	by a hotkey (default: "M-s"). While in search mode, normal terminal
61	input/output is suspended.	130	input/output is suspended and a regex is displayed at the bottom of
		131	the screen.
62		132
63	"/" starts an incremental regex search, "n" searches further, "p" or	133	Inputting characters appends them to the regex and continues
64	"N" jump to the previous match, "G" jumps to the bottom and clears	134	incremental search. "BackSpace" removes a character from the regex,
65	the history, "enter" leaves search mode at the current position and	135	"Up" and "Down" search upwards/downwards in the scrollback buffer,
66	"escape" returns to the original position.	136	"End" jumps to the bottom. "Escape" leaves search mode and returns
		137	to the point where search was started, while "Enter" or "Return"
		138	stay at the current position and additionally stores the first match
		139	in the current line into the primary selection.
		140
		141	The regex defaults to "(?i)", resulting in a case-insensitive
		142	search. To get a case-sensitive search you can delete this prefix
		143	using "BackSpace" or simply use an uppercase character which removes
		144	the "(?i)" prefix.
		145
		146	See perlre for more info about perl regular expression syntax.
		147
		148	readline (enabled by default)
		149	A support package that tries to make editing with readline easier.
		150	At the moment, it reacts to clicking shift-left mouse button by
		151	trying to move the text cursor to this position. It does so by
		152	generating as many cursor-left or cursor-right keypresses as
		153	required (the this only works for programs that correctly support
		154	wide characters).
		155
		156	To avoid too many false positives, this is only done when:
		157
		158	- the tty is in ICANON state.
		159	- the text cursor is visible.
		160	- the primary screen is currently being displayed.
		161	- the mouse is on the same (multi-row-) line as the text cursor.
		162
		163	The normal selection mechanism isn't disabled, so quick successive
		164	clicks might interfere with selection creation in harmless ways.
		165
		166	selection-autotransform
		167	This selection allows you to do automatic transforms on a selection
		168	whenever a selection is made.
		169
		170	It works by specifying perl snippets (most useful is a single "s///"
		171	operator) that modify $_ as resources:
		172
		173	URxvt.selection-autotransform.0: transform
		174	URxvt.selection-autotransform.1: transform
		175	...
		176
		177	For example, the following will transform selections of the form
		178	"filename:number", often seen in compiler messages, into "vi
		179	+$filename $word":
		180
		181	URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
		182
		183	And this example matches the same,but replaces it with vi-commands
		184	you can paste directly into your (vi :) editor:
		185
		186	URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
		187
		188	Of course, this can be modified to suit your needs and your editor
		189	:)
		190
		191	To expand the example above to typical perl error messages ("XXX at
		192	FILENAME line YYY."), you need a slightly more elaborate solution:
		193
		194	URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
		195	URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
		196
		197	The first line tells the selection code to treat the unchanging part
		198	of every error message as a selection pattern, and the second line
		199	transforms the message into vi commands to load the file.
		200
		201	tabbed
		202	This transforms the terminal into a tabbar with additional
		203	terminals, that is, it implements what is commonly referred to as
		204	"tabbed terminal". The topmost line displays a "[NEW]" button,
		205	which, when clicked, will add a new tab, followed by one button per
		206	tab.
		207
		208	Clicking a button will activate that tab. Pressing Shift-Left and
		209	Shift-Right will switch to the tab left or right of the current one,
		210	while Shift-Down creates a new tab.
		211
		212	The tabbar itself can be configured similarly to a normal terminal,
		213	but with a resource class of "URxvt.tabbed". In addition, it
		214	supports the following four resources (shown with defaults):
		215
		216	URxvt.tabbed.tabbar-fg: <colour-index, default 3>
		217	URxvt.tabbed.tabbar-bg: <colour-index, default 0>
		218	URxvt.tabbed.tab-fg: <colour-index, default 0>
		219	URxvt.tabbed.tab-bg: <colour-index, default 1>
		220
		221	See COLOR AND GRAPHICS in the rxvt(1) manpage for valid indices.
		222
		223	matcher
		224	Uses per-line display filtering ("on_line_update") to underline text
		225	matching a certain pattern and make it clickable. When clicked with
		226	the mouse button specified in the "matcher.button" resource (default
		227	2, or middle), the program specified in the "matcher.launcher"
		228	resource (default, the "urlLauncher" resource, "sensible-browser")
		229	will be started with the matched text as first argument. The default
		230	configuration is suitable for matching URLs and launching a web
		231	browser, like the former "mark-urls" extension.
		232
		233	The default pattern to match URLs can be overridden with the
		234	"matcher.pattern.0" resource, and additional patterns can be
		235	specified with numbered patterns, in a manner similar to the
		236	"selection" extension. The launcher can also be overridden on a
		237	per-pattern basis.
		238
		239	Example configuration:
		240
		241	URxvt.perl-ext: default,matcher
		242	URxvt.urlLauncher: sensible-browser
		243	URxvt.matcher.button: 1
		244	URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
		245	URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:\|$)
		246	URxvt.matcher.launcher.2: gvim +$2 $1
		247
		248	xim-onthespot
		249	This (experimental) perl extension implements OnTheSpot editing. It
		250	does not work perfectly, and some input methods don't seem to work
		251	well with OnTheSpot editing in general, but it seems to work at
		252	leats for SCIM and kinput2.
		253
		254	You enable it by specifying this extension and a preedit style of
		255	"OnTheSpot", i.e.:
		256
		257	rxvt -pt OnTheSpot -pe xim-onthespot
		258
		259	kuake<hotkey>
		260	A very primitive quake-console-like extension. It was inspired by a
		261	description of how the programs "kuake" and "yakuake" work: Whenever
		262	the user presses a global accelerator key (by default "F10"), the
		263	terminal will show or hide itself. Another press of the accelerator
		264	key will hide or show it again.
		265
		266	Initially, the window will not be shown when using this extension.
		267
		268	This is useful if you need a single terminal thats not using any
		269	desktop space most of the time but is quickly available at the press
		270	of a key.
		271
		272	The accelerator key is grabbed regardless of any modifiers, so this
		273	extension will actually grab a physical key just for this function.
		274
		275	If you want a quake-like animation, tell your window manager to do
		276	so (fvwm can do it).
		277
		278	automove-background
		279	This is basically a very small extension that dynamically changes
		280	the background pixmap offset to the window position, in effect
		281	creating the same effect as pseudo transparency with a custom
		282	pixmap. No scaling is supported in this mode. Example:
		283
		284	rxvt -pixmap background.xpm -pe automove-background
		285
		286	block-graphics-to-ascii
		287	A not very useful example of filtering all text output to the
		288	terminal by replacing all line-drawing characters (U+2500 .. U+259F)
		289	by a similar-looking ascii character.
67		290
68	digital-clock	291	digital-clock
69	Displays a digital clock using the built-in overlay.	292	Displays a digital clock using the built-in overlay.
70		293
71	mark-urls	294	remote-clipboard
72	Uses per-line display filtering ("on_line_update") to underline	295	Somewhat of a misnomer, this extension adds two menu entries to the
73	urls.	296	selection popup that allows one ti run external commands to store
		297	the selection somewhere and fetch it again.
74		298
75	block-graphics-to-ascii	299	We use it to implement a "distributed selection mechanism", which
76	A not very useful example of filtering all text output to the	300	just means that one command uploads the file to a remote server, and
77	terminal, by replacing all line-drawing characters (U+2500 ..	301	another reads it.
78	U+259F) by a similar-looking ascii character.	302
		303	The commands can be set using the "URxvt.remote-selection.store" and
		304	"URxvt.remote-selection.fetch" resources. The first should read the
		305	selection to store from STDIN (always in UTF-8), the second should
		306	provide the selection data on STDOUT (also in UTF-8).
		307
		308	The defaults (which are likely useless to you) use rsh and cat:
		309
		310	URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
		311	URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
		312
		313	selection-pastebin
		314	This is a little rarely useful extension that Uploads the selection
		315	as textfile to a remote site (or does other things). (The
		316	implementation is not currently secure for use in a multiuser
		317	environment as it writes to /tmp directly.).
		318
		319	It listens to the "selection-pastebin:remote-pastebin" keyboard
		320	command, i.e.
		321
		322	URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
		323
		324	Pressing this combination runs a command with "%" replaced by the
		325	name of the textfile. This command can be set via a resource:
		326
		327	URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
		328
		329	And the default is likely not useful to anybody but the few people
		330	around here :)
		331
		332	The name of the textfile is the hex encoded md5 sum of the
		333	selection, so the same content should lead to the same filename.
		334
		335	After a successful upload the selection will be replaced by the text
		336	given in the "selection-pastebin-url" resource (again, the % is the
		337	placeholder for the filename):
		338
		339	URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
		340
		341	Note to xrdb users: xrdb uses the C preprocessor, which might
		342	interpret the double "/" characters as comment start. Use "\057\057"
		343	instead, which works regardless of wether xrdb is used to parse the
		344	resource file or not.
79		345
80	example-refresh-hooks	346	example-refresh-hooks
81	Displays a very simple digital clock in the upper right corner of	347	Displays a very simple digital clock in the upper right corner of
82	the window. Illustrates overwriting the refresh callbacks to create	348	the window. Illustrates overwriting the refresh callbacks to create
83	your own overlays or changes.	349	your own overlays or changes.
…		…
98	Argument names also often indicate the type of a parameter. Here are	364	Argument names also often indicate the type of a parameter. Here are
99	some hints on what they mean:	365	some hints on what they mean:
100		366
101	$text	367	$text
102	Rxvt-unicodes special way of encoding text, where one "unicode"	368	Rxvt-unicodes special way of encoding text, where one "unicode"
103	character always represents one screen cell. See row_t for a	369	character always represents one screen cell. See ROW_t for a
104	discussion of this format.	370	discussion of this format.
105		371
106	$string	372	$string
107	A perl text string, with an emphasis on text. It can store all	373	A perl text string, with an emphasis on text. It can store all
108	unicode characters and is to be distinguished with text encoded in a	374	unicode characters and is to be distinguished with text encoded in a
…		…
111	$octets	377	$octets
112	Either binary data or - more common - a text string encoded in a	378	Either binary data or - more common - a text string encoded in a
113	locale-specific way.	379	locale-specific way.
114		380
115	Extension Objects	381	Extension Objects
116	Very perl extension is a perl class. A separate perl object is created	382	Every perl extension is a perl class. A separate perl object is created
117	for each terminal and each extension and passed as the first parameter	383	for each terminal, and each terminal has its own set of extenion
118	to hooks. So extensions can use their $self object without having to	384	objects, which are passed as the first parameter to hooks. So extensions
119	think about other extensions, with the exception of methods and members	385	can use their $self object without having to think about clashes with
		386	other extensions or other terminals, with the exception of methods and
120	that begin with an underscore character "_": these are reserved for	387	members that begin with an underscore character "_": these are reserved
121	internal use.	388	for internal use.
122		389
123	Although it isn't a "urxvt::term" object, you can call all methods of	390	Although it isn't a "urxvt::term" object, you can call all methods of
124	the "urxvt::term" class on this object.	391	the "urxvt::term" class on this object.
125		392
126	It has the following methods and data members:	393	It has the following methods and data members:
…		…
139		406
140	Hooks	407	Hooks
141	The following subroutines can be declared in extension files, and will	408	The following subroutines can be declared in extension files, and will
142	be called whenever the relevant event happens.	409	be called whenever the relevant event happens.
143		410
144	The first argument passed to them is an extension oject as described in	411	The first argument passed to them is an extension object as described in
145	the in the "Extension Objects" section.	412	the in the "Extension Objects" section.
146		413
147	All of these hooks must return a boolean value. If it is true, then the	414	All of these hooks must return a boolean value. If any of the called
148	event counts as being consumed, and the invocation of other hooks is	415	hooks returns true, then the event counts as being consumed, and the
149	skipped, and the relevant action might not be carried out by the C++	416	relevant action might not be carried out by the C++ code.
150	code.
151		417
152	When in doubt, return a false value (preferably "()").	418	When in doubt, return a false value (preferably "()").
153		419
154	on_init $term	420	on_init $term
155	Called after a new terminal object has been initialized, but before	421	Called after a new terminal object has been initialized, but before
156	windows are created or the command gets run. Most methods are unsafe	422	windows are created or the command gets run. Most methods are unsafe
157	to call or deliver senseless data, as terminal size and other	423	to call or deliver senseless data, as terminal size and other
158	characteristics have not yet been determined. You can safely query	424	characteristics have not yet been determined. You can safely query
159	and change resources, though.	425	and change resources and options, though. For many purposes the
		426	"on_start" hook is a better place.
		427
		428	on_start $term
		429	Called at the very end of initialisation of a new terminal, just
		430	before trying to map (display) the toplevel and returning to the
		431	main loop.
		432
		433	on_destroy $term
		434	Called whenever something tries to destroy terminal, when the
		435	terminal is still fully functional (not for long, though).
160		436
161	on_reset $term	437	on_reset $term
162	Called after the screen is "reset" for any reason, such as resizing	438	Called after the screen is "reset" for any reason, such as resizing
163	or control sequences. Here is where you can react on changes to	439	or control sequences. Here is where you can react on changes to
164	size-related variables.	440	size-related variables.
165		441
166	on_start $term	442	on_child_start $term, $pid
167	Called at the very end of initialisation of a new terminal, just	443	Called just after the child process has been "fork"ed.
168	before returning to the mainloop.	444
		445	on_child_exit $term, $status
		446	Called just after the child process has exited. $status is the
		447	status from "waitpid".
169		448
170	on_sel_make $term, $eventtime	449	on_sel_make $term, $eventtime
171	Called whenever a selection has been made by the user, but before	450	Called whenever a selection has been made by the user, but before
172	the selection text is copied, so changes to the beginning, end or	451	the selection text is copied, so changes to the beginning, end or
173	type of the selection will be honored.	452	type of the selection will be honored.
…		…
180	Called whenever a selection has been copied, but before the	459	Called whenever a selection has been copied, but before the
181	selection is requested from the server. The selection text can be	460	selection is requested from the server. The selection text can be
182	queried and changed by calling "$term->selection".	461	queried and changed by calling "$term->selection".
183		462
184	Returning a true value aborts selection grabbing. It will still be	463	Returning a true value aborts selection grabbing. It will still be
185	hilighted.	464	highlighted.
186		465
187	on_sel_extend $term	466	on_sel_extend $term
188	Called whenever the user tries to extend the selection (e.g. with a	467	Called whenever the user tries to extend the selection (e.g. with a
189	double click) and is either supposed to return false (normal	468	double click) and is either supposed to return false (normal
190	operation), or should extend the selection itelf and return true to	469	operation), or should extend the selection itself and return true to
191	suppress the built-in processing.	470	suppress the built-in processing. This can happen multiple times, as
		471	long as the callback returns true, it will be called on every
		472	further click by the user and is supposed to enlarge the selection
		473	more and more, if possible.
192		474
193	See the selection example extension.	475	See the selection example extension.
194		476
195	on_view_change $term, $offset	477	on_view_change $term, $offset
196	Called whenever the view offset changes, i..e the user or program	478	Called whenever the view offset changes, i.e. the user or program
197	scrolls. Offset 0 means display the normal terminal, positive values	479	scrolls. Offset 0 means display the normal terminal, positive values
198	show this many lines of scrollback.	480	show this many lines of scrollback.
199		481
200	on_scroll_back $term, $lines, $saved	482	on_scroll_back $term, $lines, $saved
201	Called whenever lines scroll out of the terminal area into the	483	Called whenever lines scroll out of the terminal area into the
…		…
204		486
205	It is called before lines are scrolled out (so rows 0 .. min ($lines	487	It is called before lines are scrolled out (so rows 0 .. min ($lines
206	- 1, $nrow - 1) represent the lines to be scrolled out). $saved is	488	- 1, $nrow - 1) represent the lines to be scrolled out). $saved is
207	the total number of lines that will be in the scrollback buffer.	489	the total number of lines that will be in the scrollback buffer.
208		490
		491	on_osc_seq $term, $op, $args
		492	Called on every OSC sequence and can be used to suppress it or
		493	modify its behaviour. The default should be to return an empty list.
		494	A true value suppresses execution of the request completely. Make
		495	sure you don't get confused by recursive invocations when you output
		496	an osc sequence within this callback.
		497
		498	"on_osc_seq_perl" should be used for new behaviour.
		499
209	on_osc_seq $term, $string	500	on_osc_seq_perl $term, $string
210	Called whenever the ESC ] 777 ; string ST command sequence (OSC =	501	Called whenever the ESC ] 777 ; string ST command sequence (OSC =
211	operating system command) is processed. Cursor position and other	502	operating system command) is processed. Cursor position and other
212	state information is up-to-date when this happens. For	503	state information is up-to-date when this happens. For
213	interoperability, the string should start with the extension name	504	interoperability, the string should start with the extension name
214	and a colon, to distinguish it from commands for other extensions,	505	and a colon, to distinguish it from commands for other extensions,
215	and this might be enforced in the future.	506	and this might be enforced in the future.
216		507
217	Be careful not ever to trust (in a security sense) the data you	508	Be careful not ever to trust (in a security sense) the data you
218	receive, as its source can not easily be controleld (e-mail content,	509	receive, as its source can not easily be controlled (e-mail content,
219	messages from other users on the same system etc.).	510	messages from other users on the same system etc.).
220		511
221	on_add_lines $term, $string	512	on_add_lines $term, $string
222	Called whenever text is about to be output, with the text as	513	Called whenever text is about to be output, with the text as
223	argument. You can filter/change and output the text yourself by	514	argument. You can filter/change and output the text yourself by
…		…
250	display code is run after this hook, and takes precedence.	541	display code is run after this hook, and takes precedence.
251		542
252	on_refresh_end $term	543	on_refresh_end $term
253	Called just after the screen gets redrawn. See "on_refresh_begin".	544	Called just after the screen gets redrawn. See "on_refresh_begin".
254		545
255	on_keyboard_command $term, $string	546	on_user_command $term, $string
256	Called whenever the user presses a key combination that has a	547	Called whenever a user-configured event is being activated (e.g. via
257	"perl:string" action bound to it (see description of the keysym	548	a "perl:string" action bound to a key, see description of the keysym
258	resource in the rxvt(1) manpage).	549	resource in the rxvt(1) manpage).
		550
		551	The event is simply the action string. This interface is assumed to
		552	change slightly in the future.
		553
		554	on_resize_all_windows $tern, $new_width, $new_height
		555	Called just after the new window size has been calculated, but
		556	before windows are actually being resized or hints are being set. If
		557	this hook returns TRUE, setting of the window hints is being
		558	skipped.
		559
		560	on_x_event $term, $event
		561	Called on every X event received on the vt window (and possibly
		562	other windows). Should only be used as a last resort. Most event
		563	structure members are not passed.
		564
		565	on_root_event $term, $event
		566	Like "on_x_event", but is called for events on the root window.
259		567
260	on_focus_in $term	568	on_focus_in $term
261	Called whenever the window gets the keyboard focus, before	569	Called whenever the window gets the keyboard focus, before
262	rxvt-unicode does focus in processing.	570	rxvt-unicode does focus in processing.
263		571
264	on_focus_out $term	572	on_focus_out $term
265	Called wheneever the window loses keyboard focus, before	573	Called whenever the window loses keyboard focus, before rxvt-unicode
266	rxvt-unicode does focus out processing.	574	does focus out processing.
267		575
		576	on_configure_notify $term, $event
		577	on_property_notify $term, $event
268	on_key_press $term, $event, $keysym, $octets	578	on_key_press $term, $event, $keysym, $octets
269	on_key_release $term, $event, $keysym	579	on_key_release $term, $event, $keysym
270	on_button_press $term, $event	580	on_button_press $term, $event
271	on_button_release $term, $event	581	on_button_release $term, $event
272	on_motion_notify $term, $event	582	on_motion_notify $term, $event
…		…
276	terminal If the hook returns true, then the even will be ignored by	586	terminal If the hook returns true, then the even will be ignored by
277	rxvt-unicode.	587	rxvt-unicode.
278		588
279	The event is a hash with most values as named by Xlib (see the	589	The event is a hash with most values as named by Xlib (see the
280	XEvent manpage), with the additional members "row" and "col", which	590	XEvent manpage), with the additional members "row" and "col", which
281	are the row and column under the mouse cursor.	591	are the (real, not screen-based) row and column under the mouse
		592	cursor.
282		593
283	"on_key_press" additionally receives the string rxvt-unicode would	594	"on_key_press" additionally receives the string rxvt-unicode would
284	output, if any, in locale-specific encoding.	595	output, if any, in locale-specific encoding.
285		596
286	subwindow.	597	subwindow.
		598
		599	on_client_message $term, $event
		600	on_wm_protocols $term, $event
		601	on_wm_delete_window $term, $event
		602	Called when various types of ClientMessage events are received (all
		603	with format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
287		604
288	Variables in the "urxvt" Package	605	Variables in the "urxvt" Package
289	$urxvt::LIBDIR	606	$urxvt::LIBDIR
290	The rxvt-unicode library directory, where, among other things, the	607	The rxvt-unicode library directory, where, among other things, the
291	perl modules and scripts are stored.	608	perl modules and scripts are stored.
…		…
299		616
300	$urxvt::TERM	617	$urxvt::TERM
301	The current terminal. This variable stores the current "urxvt::term"	618	The current terminal. This variable stores the current "urxvt::term"
302	object, whenever a callback/hook is executing.	619	object, whenever a callback/hook is executing.
303		620
304	*	621	@urxvt::TERM_INIT
		622	All code references in this array will be called as methods of the
		623	next newly created "urxvt::term" object (during the "on_init"
		624	phase). The array gets cleared before the code references that were
		625	in it are being executed, so references can push themselves onto it
		626	again if they so desire.
		627
		628	This complements to the perl-eval command line option, but gets
		629	executed first.
		630
		631	@urxvt::TERM_EXT
		632	Works similar to @TERM_INIT, but contains perl package/class names,
		633	which get registered as normal extensions after calling the hooks in
		634	@TERM_INIT but before other extensions. Gets cleared just like
		635	@TERM_INIT.
305		636
306	Functions in the "urxvt" Package	637	Functions in the "urxvt" Package
307	urxvt::fatal $errormessage	638	urxvt::fatal $errormessage
308	Fatally aborts execution with the given error message. Avoid at all	639	Fatally aborts execution with the given error message. Avoid at all
309	costs! The only time this is acceptable is when the terminal process	640	costs! The only time this is acceptable is when the terminal process
…		…
317	Using this function has the advantage that its output ends up in the	648	Using this function has the advantage that its output ends up in the
318	correct place, e.g. on stderr of the connecting urxvtc client.	649	correct place, e.g. on stderr of the connecting urxvtc client.
319		650
320	Messages have a size limit of 1023 bytes currently.	651	Messages have a size limit of 1023 bytes currently.
321		652
322	$is_safe = urxvt::safe	653	@terms = urxvt::termlist
323	Returns true when it is safe to do potentially unsafe things, such	654	Returns all urxvt::term objects that exist in this process,
324	as evaluating perl code specified by the user. This is true when	655	regardless of whether they are started, being destroyed etc., so be
325	urxvt was started setuid or setgid.	656	careful. Only term objects that have perl extensions attached will
		657	be returned (because there is no urxvt::term objet associated with
		658	others).
326		659
327	$time = urxvt::NOW	660	$time = urxvt::NOW
328	Returns the "current time" (as per the event loop).	661	Returns the "current time" (as per the event loop).
329		662
330	urxvt::CurrentTime	663	urxvt::CurrentTime
331	urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,	664	urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask,
332	Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,	665	Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask,
333	Button5Mask, AnyModifier	666	Button5Mask, AnyModifier
		667	urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, ButtonPressMask,
		668	ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask,
		669	PointerMotionHintMask, Button1MotionMask, Button2MotionMask,
		670	Button3MotionMask, Button4MotionMask, Button5MotionMask,
		671	ButtonMotionMask, KeymapStateMask, ExposureMask, VisibilityChangeMask,
		672	StructureNotifyMask, ResizeRedirectMask, SubstructureNotifyMask,
		673	SubstructureRedirectMask, FocusChangeMask, PropertyChangeMask,
		674	ColormapChangeMask, OwnerGrabButtonMask
		675	urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify,
		676	EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose,
		677	GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify,
		678	UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify,
		679	ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify,
		680	CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest,
		681	SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
334	Various constants for use in X calls and event processing.	682	Various constants for use in X calls and event processing.
335		683
336	RENDITION	684	RENDITION
337	Rendition bitsets contain information about colour, font, font styles	685	Rendition bitsets contain information about colour, font, font styles
338	and similar information for each screen cell.	686	and similar information for each screen cell.
…		…
359	$background = urxvt::GET_BASEBG $rend	707	$background = urxvt::GET_BASEBG $rend
360	Return the foreground/background colour index, respectively.	708	Return the foreground/background colour index, respectively.
361		709
362	$rend = urxvt::SET_FGCOLOR $rend, $new_colour	710	$rend = urxvt::SET_FGCOLOR $rend, $new_colour
363	$rend = urxvt::SET_BGCOLOR $rend, $new_colour	711	$rend = urxvt::SET_BGCOLOR $rend, $new_colour
		712	$rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
364	Replace the foreground/background colour in the rendition mask with	713	Replace the foreground/background colour in the rendition mask with
365	the specified one.	714	the specified one.
366		715
367	$value = urxvt::GET_CUSTOM $rend	716	$value = urxvt::GET_CUSTOM $rend
368	Return the "custom" value: Every rendition has 5 bits for use by	717	Return the "custom" value: Every rendition has 5 bits for use by
…		…
382		731
383	The "urxvt::term" Class	732	The "urxvt::term" Class
384	$term = new urxvt::term $envhashref, $rxvtname, [arg...]	733	$term = new urxvt::term $envhashref, $rxvtname, [arg...]
385	Creates a new terminal, very similar as if you had started it with	734	Creates a new terminal, very similar as if you had started it with
386	system "$rxvtname, arg...". $envhashref must be a reference to a	735	system "$rxvtname, arg...". $envhashref must be a reference to a
387	%ENV>-like "hash which defines the environment of the new terminal.	736	%ENV-like hash which defines the environment of the new terminal.
388	"
389		737
390	>Croaks (and probably outputs an error message) if the new instance	738	Croaks (and probably outputs an error message) if the new instance
391	couldn't be created. Returns "undef" if the new instance didn't	739	couldn't be created. Returns "undef" if the new instance didn't
392	initialise perl, and the terminal object otherwise. The "init" and	740	initialise perl, and the terminal object otherwise. The "init" and
393	"start" hooks will be called during this call.	741	"start" hooks will be called before this call returns, and are free
		742	to refer to global data (which is race free).
394		743
395	$term->destroy	744	$term->destroy
396	Destroy the terminal object (close the window, free resources etc.).	745	Destroy the terminal object (close the window, free resources etc.).
397	Please note that rxvt will not exit as long as any event watchers	746	Please note that rxvt will not exit as long as any event watchers
398	(timers, io watchers) are still active.	747	(timers, io watchers) are still active.
		748
		749	$term->exec_async ($cmd[, @args])
		750	Works like the combination of the "fork"/"exec" builtins, which
		751	executes ("starts") programs in the background. This function takes
		752	care of setting the user environment before exec'ing the command
		753	(e.g. "PATH") and should be preferred over explicit calls to "exec"
		754	or "system".
		755
		756	Returns the pid of the subprocess or "undef" on error.
399		757
400	$isset = $term->option ($optval[, $set])	758	$isset = $term->option ($optval[, $set])
401	Returns true if the option specified by $optval is enabled, and	759	Returns true if the option specified by $optval is enabled, and
402	optionally change it. All option values are stored by name in the	760	optionally change it. All option values are stored by name in the
403	hash %urxvt::OPTION. Options not enabled in this binary are not in	761	hash %urxvt::OPTION. Options not enabled in this binary are not in
404	the hash.	762	the hash.
405		763
406	Here is a a likely non-exhaustive list of option names, please see	764	Here is a likely non-exhaustive list of option names, please see the
407	the source file /src/optinc.h to see the actual list:	765	source file /src/optinc.h to see the actual list:
408		766
409	borderLess console cursorBlink cursorUnderline hold iconic insecure	767	borderLess console cursorBlink cursorUnderline hold iconic insecure
410	intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage	768	intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
411	pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating	769	override-redirect pastableTabs pointerBlank reverseVideo scrollBar
412	scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer	770	scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
413	secondaryScreen secondaryScroll skipBuiltinGlyphs transparent	771	scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
414	tripleclickwords utmpInhibit visualBell	772	transparent tripleclickwords utmpInhibit visualBell
415		773
416	$value = $term->resource ($name[, $newval])	774	$value = $term->resource ($name[, $newval])
417	Returns the current resource value associated with a given name and	775	Returns the current resource value associated with a given name and
418	optionally sets a new value. Setting values is most useful in the	776	optionally sets a new value. Setting values is most useful in the
419	"init" hook. Unset resources are returned and accepted as "undef".	777	"init" hook. Unset resources are returned and accepted as "undef".
…		…
428		786
429	Please note that resource strings will currently only be freed when	787	Please note that resource strings will currently only be freed when
430	the terminal is destroyed, so changing options frequently will eat	788	the terminal is destroyed, so changing options frequently will eat
431	memory.	789	memory.
432		790
433	Here is a a likely non-exhaustive list of resource names, not all of	791	Here is a likely non-exhaustive list of resource names, not all of
434	which are supported in every build, please see the source file	792	which are supported in every build, please see the source file
435	/src/rsinc.h to see the actual list:	793	/src/rsinc.h to see the actual list:
436		794
437	answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont	795	answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
438	borderLess color cursorBlink cursorUnderline cutchars delete_key	796	borderLess color cursorBlink cursorUnderline cutchars delete_key
439	display_name embed ext_bwidth fade font geometry hold iconName	797	display_name embed ext_bwidth fade font geometry hold iconName
440	imFont imLocale inputMethod insecure int_bwidth intensityStyles	798	imFont imLocale inputMethod insecure int_bwidth intensityStyles
441	italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier	799	italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
442	mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2	800	mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
443	perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd	801	perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
444	reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating	802	preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
445	scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput	803	scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
446	scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle	804	scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
		805	secondaryScreen secondaryScroll selectstyle shade term_name title
447	shade term_name title transparent transparent_all tripleclickwords	806	transient_for transparent transparent_all tripleclickwords utmpInhibit
448	utmpInhibit visualBell	807	visualBell
		808
		809	$value = $term->x_resource ($pattern)
		810	Returns the X-Resource for the given pattern, excluding the program
		811	or class name, i.e. "$term->x_resource ("boldFont")" should return
		812	the same value as used by this instance of rxvt-unicode. Returns
		813	"undef" if no resource with that pattern exists.
		814
		815	This method should only be called during the "on_start" hook, as
		816	there is only one resource database per display, and later
		817	invocations might return the wrong resources.
449		818
450	$success = $term->parse_keysym ($keysym_spec, $command_string)	819	$success = $term->parse_keysym ($keysym_spec, $command_string)
451	Adds a keymap translation exactly as specified via a resource. See	820	Adds a keymap translation exactly as specified via a resource. See
452	the "keysym" resource in the rxvt(1) manpage.	821	the "keysym" resource in the rxvt(1) manpage.
453		822
…		…
464	($row, $col) = $term->selection_beg ([$row, $col])	833	($row, $col) = $term->selection_beg ([$row, $col])
465	($row, $col) = $term->selection_end ([$row, $col])	834	($row, $col) = $term->selection_end ([$row, $col])
466	Return the current values of the selection mark, begin or end	835	Return the current values of the selection mark, begin or end
467	positions, and optionally set them to new values.	836	positions, and optionally set them to new values.
468		837
		838	$term->selection_make ($eventtime[, $rectangular])
		839	Tries to make a selection as set by "selection_beg" and
		840	"selection_end". If $rectangular is true (default: false), a
		841	rectangular selection will be made. This is the prefered function to
		842	make a selection.
		843
469	$success = $term->selection_grab ($eventtime)	844	$success = $term->selection_grab ($eventtime)
470	Try to request the primary selection from the server (for example,	845	Try to request the primary selection text from the server (for
471	as set by the next method).	846	example, as set by the next method). No visual feedback will be
		847	given. This function is mostly useful from within "on_sel_grab"
		848	hooks.
472		849
473	$oldtext = $term->selection ([$newtext])	850	$oldtext = $term->selection ([$newtext])
474	Return the current selection text and optionally replace it by	851	Return the current selection text and optionally replace it by
475	$newtext.	852	$newtext.
476		853
…		…
521	$string = $term->locale_decode ($octets)	898	$string = $term->locale_decode ($octets)
522	Convert the given locale-encoded octets into a perl string.	899	Convert the given locale-encoded octets into a perl string.
523		900
524	$term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])	901	$term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
525	XORs the rendition values in the given span with the provided value	902	XORs the rendition values in the given span with the provided value
526	(default: "RS_RVid"). Useful in refresh hooks to provide effects	903	(default: "RS_RVid"), which MUST NOT contain font styles. Useful
527	similar to the selection.	904	in refresh hooks to provide effects similar to the selection.
528		905
529	$term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[,	906	$term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[,
530	$rstyle2]])	907	$rstyle2]])
531	Similar to "scr_xor_span", but xors a rectangle instead. Trailing	908	Similar to "scr_xor_span", but xors a rectangle instead. Trailing
532	whitespace will additionally be xored with the $rstyle2, which	909	whitespace will additionally be xored with the $rstyle2, which
533	defaults to "RS_RVid \| RS_Uline", which removes reverse video again	910	defaults to "RS_RVid \| RS_Uline", which removes reverse video again
534	and underlines it instead.	911	and underlines it instead. Both styles MUST NOT contain font
		912	styles.
535		913
536	$term->scr_bell	914	$term->scr_bell
537	Ring the bell!	915	Ring the bell!
538		916
539	$term->scr_add_lines ($string)	917	$term->scr_add_lines ($string)
…		…
545		923
546	Normally its not a good idea to use this function, as programs might	924	Normally its not a good idea to use this function, as programs might
547	be confused by changes in cursor position or scrolling. Its useful	925	be confused by changes in cursor position or scrolling. Its useful
548	inside a "on_add_lines" hook, though.	926	inside a "on_add_lines" hook, though.
549		927
		928	$term->scr_change_screen ($screen)
		929	Switch to given screen - 0 primary, 1 secondary.
		930
550	$term->cmd_parse ($octets)	931	$term->cmd_parse ($octets)
551	Similar to "scr_add_lines", but the argument must be in the	932	Similar to "scr_add_lines", but the argument must be in the
552	locale-specific encoding of the terminal and can contain command	933	locale-specific encoding of the terminal and can contain command
553	sequences (escape codes) that will be interpreted.	934	sequences (escape codes) that will be interpreted.
554		935
…		…
562	Replaces the event mask of the pty watcher by the given event mask.	943	Replaces the event mask of the pty watcher by the given event mask.
563	Can be used to suppress input and output handling to the pty/tty.	944	Can be used to suppress input and output handling to the pty/tty.
564	See the description of "urxvt::timer->events". Make sure to always	945	See the description of "urxvt::timer->events". Make sure to always
565	restore the previous value.	946	restore the previous value.
566		947
		948	$fd = $term->pty_fd
		949	Returns the master file descriptor for the pty in use, or -1 if no
		950	pty is used.
		951
567	$windowid = $term->parent	952	$windowid = $term->parent
568	Return the window id of the toplevel window.	953	Return the window id of the toplevel window.
569		954
570	$windowid = $term->vt	955	$windowid = $term->vt
571	Return the window id of the terminal window.	956	Return the window id of the terminal window.
		957
		958	$term->vt_emask_add ($x_event_mask)
		959	Adds the specified events to the vt event mask. Useful e.g. when you
		960	want to receive pointer events all the times:
		961
		962	$term->vt_emask_add (urxvt::PointerMotionMask);
		963
		964	$term->focus_in
		965	$term->focus_out
		966	$term->key_press ($state, $keycode[, $time])
		967	$term->key_release ($state, $keycode[, $time])
		968	Deliver various fake events to to terminal.
572		969
573	$window_width = $term->width	970	$window_width = $term->width
574	$window_height = $term->height	971	$window_height = $term->height
575	$font_width = $term->fwidth	972	$font_width = $term->fwidth
576	$font_height = $term->fheight	973	$font_height = $term->fheight
…		…
579	$terminal_columns = $term->ncol	976	$terminal_columns = $term->ncol
580	$has_focus = $term->focus	977	$has_focus = $term->focus
581	$is_mapped = $term->mapped	978	$is_mapped = $term->mapped
582	$max_scrollback = $term->saveLines	979	$max_scrollback = $term->saveLines
583	$nrow_plus_saveLines = $term->total_rows	980	$nrow_plus_saveLines = $term->total_rows
584	$lines_in_scrollback = $term->nsaved	981	$topmost_scrollback_row = $term->top_row
585	Return various integers describing terminal characteristics.	982	Return various integers describing terminal characteristics.
586		983
587	$x_display = $term->display_id	984	$x_display = $term->display_id
588	Return the DISPLAY used by rxvt-unicode.	985	Return the DISPLAY used by rxvt-unicode.
589		986
…		…
591	Returns the LC_CTYPE category string used by this rxvt-unicode.	988	Returns the LC_CTYPE category string used by this rxvt-unicode.
592		989
593	$env = $term->env	990	$env = $term->env
594	Returns a copy of the environment in effect for the terminal as a	991	Returns a copy of the environment in effect for the terminal as a
595	hashref similar to "\%ENV".	992	hashref similar to "\%ENV".
		993
		994	@envv = $term->envv
		995	Returns the environment as array of strings of the form "VAR=VALUE".
		996
		997	@argv = $term->argv
		998	Return the argument vector as this terminal, similar to @ARGV, but
		999	includes the program name as first element.
596		1000
597	$modifiermask = $term->ModLevel3Mask	1001	$modifiermask = $term->ModLevel3Mask
598	$modifiermask = $term->ModMetaMask	1002	$modifiermask = $term->ModMetaMask
599	$modifiermask = $term->ModNumLockMask	1003	$modifiermask = $term->ModNumLockMask
600	Return the modifier masks corresponding to the "ISO Level 3 Shift"	1004	Return the modifier masks corresponding to the "ISO Level 3 Shift"
601	(often AltGr), the meta key (often Alt) and the num lock key, if	1005	(often AltGr), the meta key (often Alt) and the num lock key, if
602	applicable.	1006	applicable.
603		1007
		1008	$screen = $term->current_screen
		1009	Returns the currently displayed screen (0 primary, 1 secondary).
		1010
		1011	$cursor_is_hidden = $term->hidden_cursor
		1012	Returns whether the cursor is currently hidden or not.
		1013
604	$view_start = $term->view_start ([$newvalue])	1014	$view_start = $term->view_start ([$newvalue])
605	Returns the negative row number of the topmost line. Minimum value	1015	Returns the row number of the topmost displayed line. Maximum value
606	is 0, which displays the normal terminal contents. Larger values	1016	is 0, which displays the normal terminal contents. Lower values
607	scroll this many lines into the scrollback buffer.	1017	scroll this many lines into the scrollback buffer.
608		1018
609	$term->want_refresh	1019	$term->want_refresh
610	Requests a screen refresh. At the next opportunity, rxvt-unicode	1020	Requests a screen refresh. At the next opportunity, rxvt-unicode
611	will compare the on-screen display with its stored representation.	1021	will compare the on-screen display with its stored representation.
…		…
624	line, starting at column $start_col (default 0), which is useful to	1034	line, starting at column $start_col (default 0), which is useful to
625	replace only parts of a line. The font index in the rendition will	1035	replace only parts of a line. The font index in the rendition will
626	automatically be updated.	1036	automatically be updated.
627		1037
628	$text is in a special encoding: tabs and wide characters that use	1038	$text is in a special encoding: tabs and wide characters that use
629	more than one cell when displayed are padded with urxvt::NOCHAR	1039	more than one cell when displayed are padded with $urxvt::NOCHAR
630	characters ("chr 65535"). Characters with combining characters and	1040	(chr 65535) characters. Characters with combining characters and
631	other characters that do not fit into the normal tetx encoding will	1041	other characters that do not fit into the normal tetx encoding will
632	be replaced with characters in the private use area.	1042	be replaced with characters in the private use area.
633		1043
634	You have to obey this encoding when changing text. The advantage is	1044	You have to obey this encoding when changing text. The advantage is
635	that "substr" and similar functions work on screen cells and not on	1045	that "substr" and similar functions work on screen cells and not on
…		…
679	Return the row number of the first/last row of the line,	1089	Return the row number of the first/last row of the line,
680	respectively.	1090	respectively.
681		1091
682	$offset = $line->offset_of ($row, $col)	1092	$offset = $line->offset_of ($row, $col)
683	Returns the character offset of the given row\|col pair within	1093	Returns the character offset of the given row\|col pair within
684	the logical line.	1094	the logical line. Works for rows outside the line, too, and
		1095	returns corresponding offsets outside the string.
685		1096
686	($row, $col) = $line->coord_of ($offset)	1097	($row, $col) = $line->coord_of ($offset)
687	Translates a string offset into terminal coordinates again.	1098	Translates a string offset into terminal coordinates again.
688		1099
689	$text = $term->special_encode $string	1100	$text = $term->special_encode $string
690	Converts a perl string into the special encoding used by	1101	Converts a perl string into the special encoding used by
691	rxvt-unicode, where one character corresponds to one screen cell.	1102	rxvt-unicode, where one character corresponds to one screen cell.
692	See "$term->ROW_t" for details.	1103	See "$term->ROW_t" for details.
693		1104
694	$string = $term->special_decode $text	1105	$string = $term->special_decode $text
695	Converts rxvt-unicodes text reprsentation into a perl string. See	1106	Converts rxvt-unicodes text representation into a perl string. See
696	"$term->ROW_t" for details.	1107	"$term->ROW_t" for details.
697		1108
698	$success = $term->grab_button ($button, $modifiermask)	1109	$success = $term->grab_button ($button, $modifiermask[, $window =
		1110	$term->vt])
		1111	$term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
699	Registers a synchronous button grab. See the XGrabButton manpage.	1112	Register/unregister a synchronous button grab. See the XGrabButton
		1113	manpage.
700		1114
701	$success = $term->grab ($eventtime[, $sync])	1115	$success = $term->grab ($eventtime[, $sync])
702	Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or	1116	Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
703	synchronous ($sync is true). Also remembers the grab timestampe.	1117	synchronous ($sync is true). Also remembers the grab timestamp.
704		1118
705	$term->allow_events_async	1119	$term->allow_events_async
706	Calls XAllowEvents with AsyncBoth for the most recent grab.	1120	Calls XAllowEvents with AsyncBoth for the most recent grab.
707		1121
708	$term->allow_events_sync	1122	$term->allow_events_sync
…		…
715	$term->ungrab	1129	$term->ungrab
716	Calls XUngrab for the most recent grab. Is called automatically on	1130	Calls XUngrab for the most recent grab. Is called automatically on
717	evaluation errors, as it is better to lose the grab in the error	1131	evaluation errors, as it is better to lose the grab in the error
718	case as the session.	1132	case as the session.
719		1133
		1134	$atom = $term->XInternAtom ($atom_name[, $only_if_exists])
		1135	$atom_name = $term->XGetAtomName ($atom)
		1136	@atoms = $term->XListProperties ($window)
		1137	($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
		1138	$term->XChangeWindowProperty ($window, $property, $type, $format,
		1139	$octets)
		1140	$term->XDeleteProperty ($window, $property)
		1141	$window = $term->DefaultRootWindow
		1142	$term->XReparentWindow ($window, $parent, [$x, $y])
		1143	$term->XMapWindow ($window)
		1144	$term->XUnmapWindow ($window)
		1145	$term->XMoveResizeWindow ($window, $x, $y, $width, $height)
		1146	($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x,
		1147	$y)
		1148	$term->XChangeInput ($window, $add_events[, $del_events])
		1149	Various X or X-related functions. The $term object only serves as
		1150	the source of the display, otherwise those functions map
		1151	more-or-less directory onto the X functions of the same name.
		1152
720	The "urxvt::popup" Class	1153	The "urxvt::popup" Class
721	$popup->add_title ($title)	1154	$popup->add_title ($title)
722	Adds a non-clickable title to the popup.	1155	Adds a non-clickable title to the popup.
723		1156
724	$popup->add_separator ([$sepchr])	1157	$popup->add_separator ([$sepchr])
…		…
727		1160
728	$popup->add_button ($text, $cb)	1161	$popup->add_button ($text, $cb)
729	Adds a clickable button to the popup. $cb is called whenever it is	1162	Adds a clickable button to the popup. $cb is called whenever it is
730	selected.	1163	selected.
731		1164
732	$popup->add_toggle ($text, $cb, $initial_value)	1165	$popup->add_toggle ($text, $initial_value, $cb)
733	Adds a toggle/checkbox item to the popup. Teh callback gets called	1166	Adds a toggle/checkbox item to the popup. The callback gets called
734	whenever it gets toggled, with a boolean indicating its value as its	1167	whenever it gets toggled, with a boolean indicating its new value as
735	first argument.	1168	its first argument.
736		1169
737	$popup->show	1170	$popup->show
738	Displays the popup (which is initially hidden).	1171	Displays the popup (which is initially hidden).
739		1172
740	The "urxvt::timer" Class	1173	The "urxvt::timer" Class
741	This class implements timer watchers/events. Time is represented as	1174	This class implements timer watchers/events. Time is represented as a
742	a fractional number of seconds since the epoch. Example:	1175	fractional number of seconds since the epoch. Example:
743		1176
744	$term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);	1177	$term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
745	$term->{timer} = urxvt::timer	1178	$term->{timer} = urxvt::timer
746	->new	1179	->new
747	->interval (1)	1180	->interval (1)
748	->cb (sub {	1181	->cb (sub {
749	$term->{overlay}->set (0, 0,	1182	$term->{overlay}->set (0, 0,
750	sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);	1183	sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
751	});	1184	});
752		1185
753	$timer = new urxvt::timer	1186	$timer = new urxvt::timer
754	Create a new timer object in started state. It is scheduled to	1187	Create a new timer object in started state. It is scheduled to fire
755	fire immediately.	1188	immediately.
756		1189
757	$timer = $timer->cb (sub { my ($timer) = @_; ... })	1190	$timer = $timer->cb (sub { my ($timer) = @_; ... })
758	Set the callback to be called when the timer triggers.	1191	Set the callback to be called when the timer triggers.
759		1192
760	$tstamp = $timer->at	1193	$tstamp = $timer->at
761	Return the time this watcher will fire next.	1194	Return the time this watcher will fire next.
762		1195
763	$timer = $timer->set ($tstamp)	1196	$timer = $timer->set ($tstamp)
764	Set the time the event is generated to $tstamp.	1197	Set the time the event is generated to $tstamp.
765		1198
766	$timer = $timer->interval ($interval)	1199	$timer = $timer->interval ($interval)
767	Normally (and when $interval is 0), the timer will automatically	1200	Normally (and when $interval is 0), the timer will automatically
768	stop after it has fired once. If $interval is non-zero, then the	1201	stop after it has fired once. If $interval is non-zero, then the
769	timer is automatically rescheduled at the given intervals.	1202	timer is automatically rescheduled at the given intervals.
770		1203
771	$timer = $timer->start	1204	$timer = $timer->start
772	Start the timer.	1205	Start the timer.
773		1206
774	$timer = $timer->start ($tstamp)	1207	$timer = $timer->start ($tstamp)
775	Set the event trigger time to $tstamp and start the timer.	1208	Set the event trigger time to $tstamp and start the timer.
776		1209
		1210	$timer = $timer->after ($delay)
		1211	Like "start", but sets the expiry timer to c<urxvt::NOW + $delay>.
		1212
777	$timer = $timer->stop	1213	$timer = $timer->stop
778	Stop the timer.	1214	Stop the timer.
779		1215
780	The "urxvt::iow" Class	1216	The "urxvt::iow" Class
781	This class implements io watchers/events. Example:	1217	This class implements io watchers/events. Example:
782		1218
783	$term->{socket} = ...	1219	$term->{socket} = ...
784	$term->{iow} = urxvt::iow	1220	$term->{iow} = urxvt::iow
		1221	->new
		1222	->fd (fileno $term->{socket})
		1223	->events (urxvt::EVENT_READ)
		1224	->start
		1225	->cb (sub {
		1226	my ($iow, $revents) = @_;
		1227	# $revents must be 1 here, no need to check
		1228	sysread $term->{socket}, my $buf, 8192
		1229	or end-of-file;
		1230	});
		1231
		1232	$iow = new urxvt::iow
		1233	Create a new io watcher object in stopped state.
		1234
		1235	$iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
		1236	Set the callback to be called when io events are triggered.
		1237	$reventmask is a bitset as described in the "events" method.
		1238
		1239	$iow = $iow->fd ($fd)
		1240	Set the file descriptor (not handle) to watch.
		1241
		1242	$iow = $iow->events ($eventmask)
		1243	Set the event mask to watch. The only allowed values are
		1244	"urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be ORed
		1245	together, or "urxvt::EVENT_NONE".
		1246
		1247	$iow = $iow->start
		1248	Start watching for requested events on the given handle.
		1249
		1250	$iow = $iow->stop
		1251	Stop watching for events on the given file handle.
		1252
		1253	The "urxvt::iw" Class
		1254	This class implements idle watchers, that get called automatically when
		1255	the process is idle. They should return as fast as possible, after doing
		1256	some useful work.
		1257
		1258	$iw = new urxvt::iw
		1259	Create a new idle watcher object in stopped state.
		1260
		1261	$iw = $iw->cb (sub { my ($iw) = @_; ... })
		1262	Set the callback to be called when the watcher triggers.
		1263
		1264	$timer = $timer->start
		1265	Start the watcher.
		1266
		1267	$timer = $timer->stop
		1268	Stop the watcher.
		1269
		1270	The "urxvt::pw" Class
		1271	This class implements process watchers. They create an event whenever a
		1272	process exits, after which they stop automatically.
		1273
		1274	my $pid = fork;
		1275	...
		1276	$term->{pw} = urxvt::pw
785	->new	1277	->new
786	->fd (fileno $term->{socket})
787	->events (urxvt::EVENT_READ)
788	->start	1278	->start ($pid)
789	->cb (sub {	1279	->cb (sub {
790	my ($iow, $revents) = @_;	1280	my ($pw, $exit_status) = @_;
791	# $revents must be 1 here, no need to check
792	sysread $term->{socket}, my $buf, 8192
793	or end-of-file;
794	});	1281	...
		1282	});
795		1283
796	$iow = new urxvt::iow	1284	$pw = new urxvt::pw
797	Create a new io watcher object in stopped state.	1285	Create a new process watcher in stopped state.
798		1286
799	$iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })	1287	$pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
800	Set the callback to be called when io events are triggered.	1288	Set the callback to be called when the timer triggers.
801	$reventmask is a bitset as described in the "events" method.
802		1289
803	$iow = $iow->fd ($fd)	1290	$pw = $timer->start ($pid)
804	Set the filedescriptor (not handle) to watch.	1291	Tells the watcher to start watching for process $pid.
805		1292
806	$iow = $iow->events ($eventmask)
807	Set the event mask to watch. The only allowed values are
808	"urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be
809	ORed together, or "urxvt::EVENT_NONE".
810
811	$iow = $iow->start
812	Start watching for requested events on the given handle.
813
814	$iow = $iow->stop	1293	$pw = $pw->stop
815	Stop watching for events on the given filehandle.	1294	Stop the watcher.
816		1295
817	ENVIRONMENT	1296	ENVIRONMENT
818	URXVT_PERL_VERBOSITY	1297	URXVT_PERL_VERBOSITY
819	This variable controls the verbosity level of the perl extension.	1298	This variable controls the verbosity level of the perl extension. Higher
820	Higher numbers indicate more verbose output.	1299	numbers indicate more verbose output.
821		1300
822	== 0 - fatal messages	1301	== 0 - fatal messages
823	>= 3 - script loading and management	1302	>= 3 - script loading and management
824	>=10 - all events received	1303	>=10 - all called hooks
		1304	>=11 - hook return values
825		1305
826	AUTHOR	1306	AUTHOR
827	Marc Lehmann <pcg@goof.com>	1307	Marc Lehmann <pcg@goof.com>
828	http://software.schmorp.de/pkg/rxvt-unicode	1308	http://software.schmorp.de/pkg/rxvt-unicode
829		1309

Diff Legend

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

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents): Revision 1.20 by root, Wed Jan 11 01:00:04 2006 UTC vs. Revision 1.45 by root, Thu Nov 2 17:37:47 2006 UTC

Diff Legend

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.20 by root, Wed Jan 11 01:00:04 2006 UTC vs.
Revision 1.45 by root, Thu Nov 2 17:37:47 2006 UTC