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

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.3 by root, Mon Jan 2 21:41:51 2006 UTC vs.
Revision 1.6 by root, Tue Jan 3 04:20:37 2006 UTC

…		…
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
23	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
24	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.
25		49
26	General API Considerations	50	General API Considerations
27	All objects (such as terminals, time watchers etc.) are typical	51	All objects (such as terminals, time watchers etc.) are typical
28	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
29	like. All members starting with an underscore (such as "_ptr" or	53	like. All members starting with an underscore (such as "_ptr" or
…		…
130	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
131	correct place, e.g. on stderr of the connecting urxvtc client.	155	correct place, e.g. on stderr of the connecting urxvtc client.
132		156
133	$time = urxvt::NOW	157	$time = urxvt::NOW
134	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.
135		198
136	The "urxvt::term" Class	199	The "urxvt::term" Class
137	$value = $term->resource ($name[, $newval])	200	$value = $term->resource ($name[, $newval])
138	Returns the current resource value associated with a given name and	201	Returns the current resource value associated with a given name and
139	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
…		…
180		243
181	$oldtext = $term->selection ([$newtext])	244	$oldtext = $term->selection ([$newtext])
182	Return the current selection text and optionally replace it by	245	Return the current selection text and optionally replace it by
183	$newtext.	246	$newtext.
184		247
185	$term->scr_overlay ($x, $y, $text)	248	#=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
186	Create a simple multi-line overlay box. See the next method for	249	overlay box. See the next method for details. # #=cut
187	details.
188		250
189	$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]])
190	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
191	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
192	$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
193	respectively.	273	right/bottom side, respectively.
194		274
195	$term->scr_overlay_off	275	This method returns an urxvt::overlay object. The overlay will be
196	Switch the overlay off again.	276	visible as long as the perl object is referenced.
197		277
198	$term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)	278	Currently, the only method on the "urxvt::overlay" object is "set":
199	Put a single character (specified numerically) at the given overlay
200	position.
201		279
202	$term->scr_overlay_set ($x, $y, $text)	280	$overlay->set ($x, $y, $text, $rend)
203	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.
204		284
205	$cellwidth = $term->strwidth $string	285	$cellwidth = $term->strwidth $string
206	Returns the number of screen-cells this string would need. Correctly	286	Returns the number of screen-cells this string would need. Correctly
207	accounts for wide and combining characters.	287	accounts for wide and combining characters.
208		288
…		…
213	$string = $term->locale_decode $octets	293	$string = $term->locale_decode $octets
214	Convert the given locale-encoded octets into a perl string.	294	Convert the given locale-encoded octets into a perl string.
215		295
216	$term->tt_write ($octets)	296	$term->tt_write ($octets)
217	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).
218	To pass characters instead of octets, you should convetr you strings	298	To pass characters instead of octets, you should convert your
219	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.
220		369
221	The "urxvt::timer" Class	370	The "urxvt::timer" Class
222	This class implements timer watchers/events. Time is represented as a	371	This class implements timer watchers/events. Time is represented as a
223	fractional number of seconds since the epoch. Example:	372	fractional number of seconds since the epoch. Example:
224		373
225	# create a digital clock display in upper right corner	374	$term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
226	$term->{timer} = urxvt::timer	375	$term->{timer} = urxvt::timer
227	->new	376	->new
228	->start (urxvt::NOW)	377	->interval (1)
229	->cb (sub {	378	->cb (sub {
230	my ($timer) = @_;
231	my $time = $timer->at;
232	$timer->start ($time + 1);
233	$self->scr_overlay (-1, 0,	379	$term->{overlay}->set (0, 0,
234	POSIX::strftime "%H:%M:%S", localtime $time);	380	sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
235	});	381	});
236		382
237	$timer = new urxvt::timer	383	$timer = new urxvt::timer
238	Create a new timer object in stopped state.	384	Create a new timer object in started state. It is scheduled to fire
		385	immediately.
239		386
240	$timer = $timer->cb (sub { my ($timer) = @_; ... })	387	$timer = $timer->cb (sub { my ($timer) = @_; ... })
241	Set the callback to be called when the timer triggers.	388	Set the callback to be called when the timer triggers.
242		389
243	$tstamp = $timer->at	390	$tstamp = $timer->at
244	Return the time this watcher will fire next.	391	Return the time this watcher will fire next.
245		392
246	$timer = $timer->set ($tstamp)	393	$timer = $timer->set ($tstamp)
247	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.
248		400
249	$timer = $timer->start	401	$timer = $timer->start
250	Start the timer.	402	Start the timer.
251		403
252	$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.3 by root, Mon Jan 2 21:41:51 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.3 by root, Mon Jan 2 21:41:51 2006 UTC vs.
Revision 1.6 by root, Tue Jan 3 04:20:37 2006 UTC