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