[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.6 by root, Tue Jan 3 04:20: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	Miscellaneous selection modifications.
		36
		37	rot13
		38	Rot-13 the selection when activated. Used via keyboard trigger:
		39
		40	URxvt.keysym.C-M-r: perl:selection:rot13
		41
		42	digital-clock
		43	Displays a digital clock using the built-in overlay.
		44
		45	example-refresh-hooks
		46	Displays a very simple digital clock in the upper right corner of
		47	the window. Illustrates overwriting the refresh callbacks to create
		48	your own overlays or changes.
24		49
25	General API Considerations	50	General API Considerations
26	All objects (such as terminals, time watchers etc.) are typical	51	All objects (such as terminals, time watchers etc.) are typical
27	reference-to-hash objects. The hash can be used to store anything you	52	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	53	like. All members starting with an underscore (such as "_ptr" or
108	display code is run after this hook, and takes precedence.	133	display code is run after this hook, and takes precedence.
109		134
110	on_refresh_end $term	135	on_refresh_end $term
111	Called just after the screen gets redrawn. See "on_refresh_begin".	136	Called just after the screen gets redrawn. See "on_refresh_begin".
112		137
		138	on_keyboard_command $term, $string
		139	Called whenever the user presses a key combination that has a
		140	"perl:string" action bound to it (see description of the keysym
		141	resource in the rxvt(1) manpage).
		142
113	Functions in the "urxvt" Package	143	Functions in the "urxvt" Package
114	urxvt::fatal $errormessage	144	urxvt::fatal $errormessage
115	Fatally aborts execution with the given error message. Avoid at all	145	Fatally aborts execution with the given error message. Avoid at all
116	costs! The only time this is acceptable is when the terminal process	146	costs! The only time this is acceptable is when the terminal process
117	starts up.	147	starts up.
…		…
124	Using this function has the advantage that its output ends up in the	154	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.	155	correct place, e.g. on stderr of the connecting urxvtc client.
126		156
127	$time = urxvt::NOW	157	$time = urxvt::NOW
128	Returns the "current time" (as per the event loop).	158	Returns the "current time" (as per the event loop).
		159
		160	RENDITION
		161	Rendition bitsets contain information about colour, font, font styles
		162	and similar information for each screen cell.
		163
		164	The following "macros" deal with changes in rendition sets. You should
		165	never just create a bitset, you should always modify an existing one, as
		166	they contain important information required for correct operation of
		167	rxvt-unicode.
		168
		169	$rend = urxvt::DEFAULT_RSTYLE
		170	Returns the default rendition, as used when the terminal is starting
		171	up or being reset. Useful as a base to start when creating
		172	renditions.
		173
		174	$rend = urxvt::OVERLAY_RSTYLE
		175	Return the rendition mask used for overlays by default.
		176
		177	$rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
		178	Return the bit that enabled bold, italic, blink, reverse-video and
		179	underline, respectively. To enable such a style, just logically OR
		180	it into the bitset.
		181
		182	$foreground = urxvt::GET_BASEFG $rend
		183	$background = urxvt::GET_BASEBG $rend
		184	Return the foreground/background colour index, respectively.
		185
		186	$rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
		187	$rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
		188	Replace the foreground/background colour in the rendition mask with
		189	the specified one.
		190
		191	$value = urxvt::GET_CUSTOM ($rend)
		192	Return the "custom" value: Every rendition has 5 bits for use by
		193	extensions. They can be set and changed as you like and are
		194	initially zero.
		195
		196	$rend = urxvt::SET_CUSTOM ($rend, $new_value)
		197	Change the custom value.
129		198
130	The "urxvt::term" Class	199	The "urxvt::term" Class
131	$value = $term->resource ($name[, $newval])	200	$value = $term->resource ($name[, $newval])
132	Returns the current resource value associated with a given name and	201	Returns the current resource value associated with a given name and
133	optionally sets a new value. Setting values is most useful in the	202	optionally sets a new value. Setting values is most useful in the
…		…
174		243
175	$oldtext = $term->selection ([$newtext])	244	$oldtext = $term->selection ([$newtext])
176	Return the current selection text and optionally replace it by	245	Return the current selection text and optionally replace it by
177	$newtext.	246	$newtext.
178		247
179	$term->scr_overlay ($x, $y, $text)	248	#=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
180	Create a simple multi-line overlay box. See the next method for	249	overlay box. See the next method for details. # #=cut
181	details.
182		250
183	$term->scr_overlay_new ($x, $y, $width, $height)	251	sub urxvt::term::scr_overlay { die; my ($self, $x, $y, $text) = @_;
		252
		253	my @lines = split /\n/, $text;
		254
		255	my $w = 0;
		256	for (map $self->strwidth ($_), @lines) {
		257	$w = $_ if $w < $_;
		258	}
		259
		260	$self->scr_overlay_new ($x, $y, $w, scalar @lines);
		261	$self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
		262	}
		263
		264	$term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
184	Create a new (empty) overlay at the given position with the given	265	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	266	width/height. $rstyle defines the initial rendition style (default:
		267	"OVERLAY_RSTYLE").
		268
		269	If $border is 2 (default), then a decorative border will be put
		270	around the box.
		271
186	$y is negative, then this is counted from the right/bottom side,	272	If either $x or $y is negative, then this is counted from the
187	respectively.	273	right/bottom side, respectively.
188		274
189	$term->scr_overlay_off	275	This method returns an urxvt::overlay object. The overlay will be
190	Switch the overlay off again.	276	visible as long as the perl object is referenced.
191		277
192	$term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)	278	Currently, the only method on the "urxvt::overlay" object is "set":
193	Put a single character (specified numerically) at the given overlay
194	position.
195		279
196	$term->scr_overlay_set ($x, $y, $text)	280	$overlay->set ($x, $y, $text, $rend)
197	Write a string at the given position into the overlay.	281	Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts text in
		282	rxvt-unicode's special encoding and an array of rendition values at
		283	a specific position inside the overlay.
198		284
199	$cellwidth = $term->strwidth $string	285	$cellwidth = $term->strwidth $string
200	Returns the number of screen-cells this string would need. Correctly	286	Returns the number of screen-cells this string would need. Correctly
201	accounts for wide and combining characters.	287	accounts for wide and combining characters.
202		288
…		…
207	$string = $term->locale_decode $octets	293	$string = $term->locale_decode $octets
208	Convert the given locale-encoded octets into a perl string.	294	Convert the given locale-encoded octets into a perl string.
209		295
210	$term->tt_write ($octets)	296	$term->tt_write ($octets)
211	Write the octets given in $data to the tty (i.e. as program input).	297	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	298	To pass characters instead of octets, you should convert your
213	first to the locale-specific encoding using "$term->locale_encode".	299	strings first to the locale-specific encoding using
		300	"$term->locale_encode".
		301
		302	$nrow = $term->nrow
		303	$ncol = $term->ncol
		304	Return the number of rows/columns of the terminal window (i.e. as
		305	specified by "-geometry", excluding any scrollback).
		306
		307	$nsaved = $term->nsaved
		308	Returns the number of lines in the scrollback buffer.
		309
		310	$view_start = $term->view_start ([$newvalue])
		311	Returns the negative row number of the topmost line. Minimum value
		312	is 0, which displays the normal terminal contents. Larger values
		313	scroll this many lines into the scrollback buffer.
		314
		315	$term->want_refresh
		316	Requests a screen refresh. At the next opportunity, rxvt-unicode
		317	will compare the on-screen display with its stored representation.
		318	If they differ, it redraws the differences.
		319
		320	Used after changing terminal contents to display them.
		321
		322	$text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
		323	Returns the text of the entire row with number $row_number. Row 0 is
		324	the topmost terminal line, row "$term->$ncol-1" is the bottommost
		325	terminal line. The scrollback buffer starts at line -1 and extends
		326	to line "-$term->nsaved".
		327
		328	If $new_text is specified, it will replace characters in the current
		329	line, starting at column $start_col (default 0), which is useful to
		330	replace only parts of a line. The font index in the rendition will
		331	automatically be updated.
		332
		333	$text is in a special encoding: tabs and wide characters that use
		334	more than one cell when displayed are padded with urxvt::NOCHAR
		335	characters ("chr 65535"). Characters with combining characters and
		336	other characters that do not fit into the normal tetx encoding will
		337	be replaced with characters in the private use area.
		338
		339	You have to obey this encoding when changing text. The advantage is
		340	that "substr" and similar functions work on screen cells and not on
		341	characters.
		342
		343	The methods "$term->special_encode" and "$term->special_decode" can
		344	be used to convert normal strings into this encoding and vice versa.
		345
		346	$rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
		347	Like "$term->ROW_t", but returns an arrayref with rendition bitsets.
		348	Rendition bitsets contain information about colour, font, font
		349	styles and similar information. See also "$term->ROW_t".
		350
		351	When setting rendition, the font mask will be ignored.
		352
		353	See the section on RENDITION, above.
		354
		355	$length = $term->ROW_l ($row_number[, $new_length])
		356	Returns the number of screen cells that are in use ("the line
		357	length"). If it is -1, then the line is part of a multiple-row
		358	logical "line", which means all characters are in use and it is
		359	continued on the next row.
		360
		361	$text = $term->special_encode $string
		362	Converts a perl string into the special encoding used by
		363	rxvt-unicode, where one character corresponds to one screen cell.
		364	See "$term->ROW_t" for details.
		365
		366	$string = $term->special_decode $text
		367	Converts rxvt-unicodes text reprsentation into a perl string. See
		368	"$term->ROW_t" for details.
214		369
215	The "urxvt::timer" Class	370	The "urxvt::timer" Class
216	This class implements timer watchers/events. Time is represented as a	371	This class implements timer watchers/events. Time is represented as a
217	fractional number of seconds since the epoch. Example:	372	fractional number of seconds since the epoch. Example:
218		373
219	# create a digital clock display in upper right corner	374	$term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
220	$term->{timer} = urxvt::timer	375	$term->{timer} = urxvt::timer
221	->new	376	->new
222	->start (urxvt::NOW)	377	->interval (1)
223	->cb (sub {	378	->cb (sub {
224	my ($timer) = @_;
225	my $time = $timer->at;
226	$timer->start ($time + 1);
227	$self->scr_overlay (-1, 0,	379	$term->{overlay}->set (0, 0,
228	POSIX::strftime "%H:%M:%S", localtime $time);	380	sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
229	});	381	});
230		382
231	$timer = new urxvt::timer	383	$timer = new urxvt::timer
232	Create a new timer object in stopped state.	384	Create a new timer object in started state. It is scheduled to fire
		385	immediately.
233		386
234	$timer = $timer->cb (sub { my ($timer) = @_; ... })	387	$timer = $timer->cb (sub { my ($timer) = @_; ... })
235	Set the callback to be called when the timer triggers.	388	Set the callback to be called when the timer triggers.
236		389
237	$tstamp = $timer->at	390	$tstamp = $timer->at
238	Return the time this watcher will fire next.	391	Return the time this watcher will fire next.
239		392
240	$timer = $timer->set ($tstamp)	393	$timer = $timer->set ($tstamp)
241	Set the time the event is generated to $tstamp.	394	Set the time the event is generated to $tstamp.
		395
		396	$timer = $timer->interval ($interval)
		397	Normally (and when $interval is 0), the timer will automatically
		398	stop after it has fired once. If $interval is non-zero, then the
		399	timer is automatically rescheduled at the given intervals.
242		400
243	$timer = $timer->start	401	$timer = $timer->start
244	Start the timer.	402	Start the timer.
245		403
246	$timer = $timer->start ($tstamp)	404	$timer = $timer->start ($tstamp)

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.6 by root, Tue Jan 3 04:20: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.6 by root, Tue Jan 3 04:20:37 2006 UTC