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

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.2 by root, Mon Jan 2 20:35:39 2006 UTC vs.
Revision 1.8 by root, Tue Jan 3 23:41:37 2006 UTC

…		…
1	NAME	1	NAME
2	rxvtperl - rxvt-unicode's embedded perl interpreter	2	rxvtperl - rxvt-unicode's embedded perl interpreter
3		3
4	SYNOPSIS	4	SYNOPSIS
5	* Put your scripts into /opt/rxvt/lib/urxvt/perl-ext/, they will be	5	# create a file grab_test in $HOME:
6	loaded automatically.
7
8	* Scripts are evaluated in a 'use strict' and 'use utf8' environment,
9	and thus must be encoded as UTF-8.
10		6
11	sub on_sel_grab {	7	sub on_sel_grab {
12	warn "you selected ", $_[0]->selection;	8	warn "you selected ", $_[0]->selection;
13	()	9	()
14	}	10	}
15		11
16	1	12	# start a rxvt using it:
		13
		14	rxvt --perl-lib $HOME -pe grab_test
17		15
18	DESCRIPTION	16	DESCRIPTION
19	Everytime a terminal object gets created, scripts specified via the	17	Everytime a terminal object gets created, scripts specified via the
20	"perl" resource are associated with it.	18	"perl" resource are loaded and associated with it.
		19
		20	Scripts are compiled in a 'use strict' and 'use utf8' environment, and
		21	thus must be encoded as UTF-8.
21		22
22	Each script will only ever be loaded once, even in rxvtd, where scripts	23	Each script will only ever be loaded once, even in rxvtd, where scripts
23	will be shared (But not enabled) for all terminals.	24	will be shared (but not enabled) for all terminals.
		25
		26	Prepackaged Extensions
		27	This section describes the extensiosn delivered with this version. You
		28	can find them in /opt/rxvt/lib/urxvt/perl/.
		29
		30	You can activate them like this:
		31
		32	rxvt -pe <extensionname>
		33
		34	selection
		35	Intelligent selection. This extension tries to be more intelligent
		36	when the user extends selections (double-click). Right now, it tries
		37	to select urls and complete shell-quoted arguments, which is very
		38	convenient, too, if your ls supports "--quoting-style=shell".
		39
		40	It also offers the following bindable event:
		41
		42	rot13
		43	Rot-13 the selection when activated. Used via keyboard trigger:
		44
		45	URxvt.keysym.C-M-r: perl:selection:rot13
		46
		47	digital-clock
		48	Displays a digital clock using the built-in overlay.
		49
		50	example-refresh-hooks
		51	Displays a very simple digital clock in the upper right corner of
		52	the window. Illustrates overwriting the refresh callbacks to create
		53	your own overlays or changes.
24		54
25	General API Considerations	55	General API Considerations
26	All objects (such as terminals, time watchers etc.) are typical	56	All objects (such as terminals, time watchers etc.) are typical
27	reference-to-hash objects. The hash can be used to store anything you	57	reference-to-hash objects. The hash can be used to store anything you
28	like. All members starting with an underscore (such as "_ptr" or	58	like. All members starting with an underscore (such as "_ptr" or
29	"_hook") are reserved for internal uses and must not be accessed or	59	"_hook") are reserved for internal uses and MUST NOT be accessed or
30	modified).	60	modified).
31		61
32	When objects are destroyed on the C++ side, the perl object hashes are	62	When objects are destroyed on the C++ side, the perl object hashes are
33	emptied, so its best to store related objects such as time watchers and	63	emptied, so its best to store related objects such as time watchers and
34	the like inside the terminal object so they get destroyed as soon as the	64	the like inside the terminal object so they get destroyed as soon as the
36		66
37	Hooks	67	Hooks
38	The following subroutines can be declared in loaded scripts, and will be	68	The following subroutines can be declared in loaded scripts, and will be
39	called whenever the relevant event happens.	69	called whenever the relevant event happens.
40		70
		71	The first argument passed to them is an object private to each terminal
		72	and extension package. You can call all "urxvt::term" methods on it, but
		73	its not a real "urxvt::term" object. Instead, the real "urxvt::term"
		74	object that is shared between all packages is stored in the "term"
		75	member.
		76
41	All of them must return a boolean value. If it is true, then the event	77	All of them must return a boolean value. If it is true, then the event
42	counts as being consumed, and the invocation of other hooks is	78	counts as being consumed, and the invocation of other hooks is
43	skipped, and the relevant action might not be carried out by the C++	79	skipped, and the relevant action might not be carried out by the C++
44	code.	80	code.
45		81
…		…
72	selection is requested from the server. The selection text can be	108	selection is requested from the server. The selection text can be
73	queried and changed by calling "$term->selection".	109	queried and changed by calling "$term->selection".
74		110
75	Returning a true value aborts selection grabbing. It will still be	111	Returning a true value aborts selection grabbing. It will still be
76	hilighted.	112	hilighted.
		113
		114	on_sel_extend $term
		115	Called whenever the user tries to extend the selection (e.g. with a
		116	double click) and is either supposed to return false (normal
		117	operation), or should extend the selection itelf and return true to
		118	suppress the built-in processing.
		119
		120	See the selection example extension.
77		121
78	on_focus_in $term	122	on_focus_in $term
79	Called whenever the window gets the keyboard focus, before urxvt	123	Called whenever the window gets the keyboard focus, before urxvt
80	does focus in processing.	124	does focus in processing.
81		125
…		…
108	display code is run after this hook, and takes precedence.	152	display code is run after this hook, and takes precedence.
109		153
110	on_refresh_end $term	154	on_refresh_end $term
111	Called just after the screen gets redrawn. See "on_refresh_begin".	155	Called just after the screen gets redrawn. See "on_refresh_begin".
112		156
		157	on_keyboard_command $term, $string
		158	Called whenever the user presses a key combination that has a
		159	"perl:string" action bound to it (see description of the keysym
		160	resource in the rxvt(1) manpage).
		161
		162	Variables in the "urxvt" Package
		163	$urxvt::TERM
		164	The current terminal. Whenever a callback/Hook is bein executed,
		165	this variable stores the current "urxvt::term" object.
		166
113	Functions in the "urxvt" Package	167	Functions in the "urxvt" Package
114	urxvt::fatal $errormessage	168	urxvt::fatal $errormessage
115	Fatally aborts execution with the given error message. Avoid at all	169	Fatally aborts execution with the given error message. Avoid at all
116	costs! The only time this is acceptable is when the terminal process	170	costs! The only time this is acceptable is when the terminal process
117	starts up.	171	starts up.
…		…
124	Using this function has the advantage that its output ends up in the	178	Using this function has the advantage that its output ends up in the
125	correct place, e.g. on stderr of the connecting urxvtc client.	179	correct place, e.g. on stderr of the connecting urxvtc client.
126		180
127	$time = urxvt::NOW	181	$time = urxvt::NOW
128	Returns the "current time" (as per the event loop).	182	Returns the "current time" (as per the event loop).
		183
		184	RENDITION
		185	Rendition bitsets contain information about colour, font, font styles
		186	and similar information for each screen cell.
		187
		188	The following "macros" deal with changes in rendition sets. You should
		189	never just create a bitset, you should always modify an existing one, as
		190	they contain important information required for correct operation of
		191	rxvt-unicode.
		192
		193	$rend = urxvt::DEFAULT_RSTYLE
		194	Returns the default rendition, as used when the terminal is starting
		195	up or being reset. Useful as a base to start when creating
		196	renditions.
		197
		198	$rend = urxvt::OVERLAY_RSTYLE
		199	Return the rendition mask used for overlays by default.
		200
		201	$rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
		202	Return the bit that enabled bold, italic, blink, reverse-video and
		203	underline, respectively. To enable such a style, just logically OR
		204	it into the bitset.
		205
		206	$foreground = urxvt::GET_BASEFG $rend
		207	$background = urxvt::GET_BASEBG $rend
		208	Return the foreground/background colour index, respectively.
		209
		210	$rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
		211	$rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
		212	Replace the foreground/background colour in the rendition mask with
		213	the specified one.
		214
		215	$value = urxvt::GET_CUSTOM ($rend)
		216	Return the "custom" value: Every rendition has 5 bits for use by
		217	extensions. They can be set and changed as you like and are
		218	initially zero.
		219
		220	$rend = urxvt::SET_CUSTOM ($rend, $new_value)
		221	Change the custom value.
129		222
130	The "urxvt::term" Class	223	The "urxvt::term" Class
131	$value = $term->resource ($name[, $newval])	224	$value = $term->resource ($name[, $newval])
132	Returns the current resource value associated with a given name and	225	Returns the current resource value associated with a given name and
133	optionally sets a new value. Setting values is most useful in the	226	optionally sets a new value. Setting values is most useful in the
…		…
174		267
175	$oldtext = $term->selection ([$newtext])	268	$oldtext = $term->selection ([$newtext])
176	Return the current selection text and optionally replace it by	269	Return the current selection text and optionally replace it by
177	$newtext.	270	$newtext.
178		271
179	$term->scr_overlay ($x, $y, $text)	272	#=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
180	Create a simple multi-line overlay box. See the next method for	273	overlay box. See the next method for details. # #=cut
181	details.
182		274
183	$term->scr_overlay_new ($x, $y, $width, $height)	275	sub urxvt::term::scr_overlay { die; my ($self, $x, $y, $text) = @_;
		276
		277	my @lines = split /\n/, $text;
		278
		279	my $w = 0;
		280	for (map $self->strwidth ($_), @lines) {
		281	$w = $_ if $w < $_;
		282	}
		283
		284	$self->scr_overlay_new ($x, $y, $w, scalar @lines);
		285	$self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
		286	}
		287
		288	$term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
184	Create a new (empty) overlay at the given position with the given	289	Create a new (empty) overlay at the given position with the given
185	width/height. A border will be put around the box. If either $x or	290	width/height. $rstyle defines the initial rendition style (default:
		291	"OVERLAY_RSTYLE").
		292
		293	If $border is 2 (default), then a decorative border will be put
		294	around the box.
		295
186	$y is negative, then this is counted from the right/bottom side,	296	If either $x or $y is negative, then this is counted from the
187	respectively.	297	right/bottom side, respectively.
188		298
189	$term->scr_overlay_off	299	This method returns an urxvt::overlay object. The overlay will be
190	Switch the overlay off again.	300	visible as long as the perl object is referenced.
191		301
192	$term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)	302	The methods currently supported on "urxvt::overlay" objects are:
193	Put a single character (specified numerically) at the given overlay
194	position.
195		303
196	$term->scr_overlay_set ($x, $y, $text)	304	$overlay->set ($x, $y, $text, $rend)
197	Write a string at the given position into the overlay.	305	Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts
		306	text in rxvt-unicode's special encoding and an array of
		307	rendition values at a specific position inside the overlay.
		308
		309	$overlay->hide
		310	If visible, hide the overlay, but do not destroy it.
		311
		312	$overlay->show
		313	If hidden, display the overlay again.
198		314
199	$cellwidth = $term->strwidth $string	315	$cellwidth = $term->strwidth $string
200	Returns the number of screen-cells this string would need. Correctly	316	Returns the number of screen-cells this string would need. Correctly
201	accounts for wide and combining characters.	317	accounts for wide and combining characters.
202		318
…		…
207	$string = $term->locale_decode $octets	323	$string = $term->locale_decode $octets
208	Convert the given locale-encoded octets into a perl string.	324	Convert the given locale-encoded octets into a perl string.
209		325
210	$term->tt_write ($octets)	326	$term->tt_write ($octets)
211	Write the octets given in $data to the tty (i.e. as program input).	327	Write the octets given in $data to the tty (i.e. as program input).
212	To pass characters instead of octets, you should convetr you strings	328	To pass characters instead of octets, you should convert your
213	first to the locale-specific encoding using "$term->locale_encode".	329	strings first to the locale-specific encoding using
		330	"$term->locale_encode".
		331
		332	$nrow = $term->nrow
		333	$ncol = $term->ncol
		334	Return the number of rows/columns of the terminal window (i.e. as
		335	specified by "-geometry", excluding any scrollback).
		336
		337	$nsaved = $term->nsaved
		338	Returns the number of lines in the scrollback buffer.
		339
		340	$view_start = $term->view_start ([$newvalue])
		341	Returns the negative row number of the topmost line. Minimum value
		342	is 0, which displays the normal terminal contents. Larger values
		343	scroll this many lines into the scrollback buffer.
		344
		345	$term->want_refresh
		346	Requests a screen refresh. At the next opportunity, rxvt-unicode
		347	will compare the on-screen display with its stored representation.
		348	If they differ, it redraws the differences.
		349
		350	Used after changing terminal contents to display them.
		351
		352	$text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
		353	Returns the text of the entire row with number $row_number. Row 0 is
		354	the topmost terminal line, row "$term->$ncol-1" is the bottommost
		355	terminal line. The scrollback buffer starts at line -1 and extends
		356	to line "-$term->nsaved". Nothing will be returned if a nonexistent
		357	line is requested.
		358
		359	If $new_text is specified, it will replace characters in the current
		360	line, starting at column $start_col (default 0), which is useful to
		361	replace only parts of a line. The font index in the rendition will
		362	automatically be updated.
		363
		364	$text is in a special encoding: tabs and wide characters that use
		365	more than one cell when displayed are padded with urxvt::NOCHAR
		366	characters ("chr 65535"). Characters with combining characters and
		367	other characters that do not fit into the normal tetx encoding will
		368	be replaced with characters in the private use area.
		369
		370	You have to obey this encoding when changing text. The advantage is
		371	that "substr" and similar functions work on screen cells and not on
		372	characters.
		373
		374	The methods "$term->special_encode" and "$term->special_decode" can
		375	be used to convert normal strings into this encoding and vice versa.
		376
		377	$rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
		378	Like "$term->ROW_t", but returns an arrayref with rendition bitsets.
		379	Rendition bitsets contain information about colour, font, font
		380	styles and similar information. See also "$term->ROW_t".
		381
		382	When setting rendition, the font mask will be ignored.
		383
		384	See the section on RENDITION, above.
		385
		386	$length = $term->ROW_l ($row_number[, $new_length])
		387	Returns the number of screen cells that are in use ("the line
		388	length"). Unlike the urxvt core, this returns "$term->ncol" if the
		389	line is joined with the following one.
		390
		391	$bool = $term->is_longer ($row_number)
		392	Returns true if the row is part of a multiple-row logical "line"
		393	(i.e. joined with the following row), which means all characters are
		394	in use and it is continued on the next row (and possibly a
		395	continuation of the previous row(s)).
		396
		397	$line = $term->line ($row_number)
		398	Create and return a new "urxvt::line" object that stores information
		399	about the logical line that row $row_number is part of. It supports
		400	the following methods:
		401
		402	$text = $line->t
		403	Returns the full text of the line, similar to "ROW_t"
		404
		405	$rend = $line->r
		406	Returns the full rendition array of the line, similar to "ROW_r"
		407
		408	$length = $line->l
		409	Returns the length of the line in cells, similar to "ROW_l".
		410
		411	$rownum = $line->beg
		412	$rownum = $line->end
		413	Return the row number of the first/last row of the line,
		414	respectively.
		415
		416	$offset = $line->offset_of ($row, $col)
		417	Returns the character offset of the given row\|col pair within
		418	the logical line.
		419
		420	($row, $col) = $line->coord_of ($offset)
		421	Translates a string offset into terminal coordinates again.
		422
		423	($row, $col) = $line->coord_of ($offset) =item $text =
		424	$term->special_encode $string
		425	Converts a perl string into the special encoding used by
		426	rxvt-unicode, where one character corresponds to one screen cell.
		427	See "$term->ROW_t" for details.
		428
		429	$string = $term->special_decode $text
		430	Converts rxvt-unicodes text reprsentation into a perl string. See
		431	"$term->ROW_t" for details.
214		432
215	The "urxvt::timer" Class	433	The "urxvt::timer" Class
216	This class implements timer watchers/events. Time is represented as a	434	This class implements timer watchers/events. Time is represented as a
217	fractional number of seconds since the epoch. Example:	435	fractional number of seconds since the epoch. Example:
218		436
219	# create a digital clock display in upper right corner	437	$term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
220	$term->{timer} = urxvt::timer	438	$term->{timer} = urxvt::timer
221	->new	439	->new
222	->start (urxvt::NOW)	440	->interval (1)
223	->cb (sub {	441	->cb (sub {
224	my ($timer) = @_;
225	my $time = $timer->at;
226	$timer->start ($time + 1);
227	$self->scr_overlay (-1, 0,	442	$term->{overlay}->set (0, 0,
228	POSIX::strftime "%H:%M:%S", localtime $time);	443	sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
229	});	444	});
230		445
231	$timer = new urxvt::timer	446	$timer = new urxvt::timer
232	Create a new timer object in stopped state.	447	Create a new timer object in started state. It is scheduled to fire
		448	immediately.
233		449
234	$timer = $timer->cb (sub { my ($timer) = @_; ... })	450	$timer = $timer->cb (sub { my ($timer) = @_; ... })
235	Set the callback to be called when the timer triggers.	451	Set the callback to be called when the timer triggers.
236		452
237	$tstamp = $timer->at	453	$tstamp = $timer->at
238	Return the time this watcher will fire next.	454	Return the time this watcher will fire next.
239		455
240	$timer = $timer->set ($tstamp)	456	$timer = $timer->set ($tstamp)
241	Set the time the event is generated to $tstamp.	457	Set the time the event is generated to $tstamp.
		458
		459	$timer = $timer->interval ($interval)
		460	Normally (and when $interval is 0), the timer will automatically
		461	stop after it has fired once. If $interval is non-zero, then the
		462	timer is automatically rescheduled at the given intervals.
242		463
243	$timer = $timer->start	464	$timer = $timer->start
244	Start the timer.	465	Start the timer.
245		466
246	$timer = $timer->start ($tstamp)	467	$timer = $timer->start ($tstamp)
…		…
288	ENVIRONMENT	509	ENVIRONMENT
289	URXVT_PERL_VERBOSITY	510	URXVT_PERL_VERBOSITY
290	This variable controls the verbosity level of the perl extension. Higher	511	This variable controls the verbosity level of the perl extension. Higher
291	numbers indicate more verbose output.	512	numbers indicate more verbose output.
292		513
293	0 - only fatal messages	514	=0 - only fatal messages
294	3 - script loading and management	515	=3 - script loading and management
295	10 - all events received	516	=10 - all events received
296		517
297	AUTHOR	518	AUTHOR
298	Marc Lehmann <pcg@goof.com>	519	Marc Lehmann <pcg@goof.com>
299	http://software.schmorp.de/pkg/rxvt-unicode	520	http://software.schmorp.de/pkg/rxvt-unicode
300		521

Diff Legend

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

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents): Revision 1.2 by root, Mon Jan 2 20:35:39 2006 UTC vs. Revision 1.8 by root, Tue Jan 3 23:41:37 2006 UTC

Diff Legend

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.2 by root, Mon Jan 2 20:35:39 2006 UTC vs.
Revision 1.8 by root, Tue Jan 3 23:41:37 2006 UTC