[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.11 by root, Wed Jan 4 21:37:55 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	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.
25		54
26	General API Considerations	55	General API Considerations
27	All objects (such as terminals, time watchers etc.) are typical	56	All objects (such as terminals, time watchers etc.) are typical
28	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
29	like. All members starting with an underscore (such as "_ptr" or	58	like. All members starting with an underscore (such as "_ptr" or
30	"_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
31	modified).	60	modified).
32		61
33	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
34	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
35	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
…		…
37		66
38	Hooks	67	Hooks
39	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
40	called whenever the relevant event happens.	69	called whenever the relevant event happens.
41		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
42	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
43	counts as being consumed, and the invocation of other hooks is	78	counts as being consumed, and the invocation of other hooks is
44	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++
45	code.	80	code.
46		81
…		…
74	queried and changed by calling "$term->selection".	109	queried and changed by calling "$term->selection".
75		110
76	Returning a true value aborts selection grabbing. It will still be	111	Returning a true value aborts selection grabbing. It will still be
77	hilighted.	112	hilighted.
78		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.
		121
79	on_focus_in $term	122	on_focus_in $term
80	Called whenever the window gets the keyboard focus, before urxvt	123	Called whenever the window gets the keyboard focus, before urxvt
81	does focus in processing.	124	does focus in processing.
82		125
83	on_focus_out $term	126	on_focus_out $term
…		…
99	the total number of lines that will be in the scrollback buffer.	142	the total number of lines that will be in the scrollback buffer.
100		143
101	on_tty_activity $term NYI	144	on_tty_activity $term NYI
102	Called whenever the program(s) running in the urxvt window send	145	Called whenever the program(s) running in the urxvt window send
103	output.	146	output.
		147
		148	on_osc_seq $term, $string
		149	Called whenever the ESC ] 777 ; string ST command sequence (OSC =
		150	operating system command) is processed. Cursor position and other
		151	state information is up-to-date when this happens. For
		152	interoperability, the string should start with the extension name
		153	and a colon, to distinguish it from commands for other extensions,
		154	and this might be enforced in the future.
		155
		156	Be careful not ever to trust (in a security sense) the data you
		157	receive, as its source can not easily be controleld (e-mail content,
		158	messages from other users on the same system etc.).
104		159
105	on_refresh_begin $term	160	on_refresh_begin $term
106	Called just before the screen gets redrawn. Can be used for overlay	161	Called just before the screen gets redrawn. Can be used for overlay
107	or similar effects by modify terminal contents in refresh_begin, and	162	or similar effects by modify terminal contents in refresh_begin, and
108	restoring them in refresh_end. The built-in overlay and selection	163	restoring them in refresh_end. The built-in overlay and selection
…		…
114	on_keyboard_command $term, $string	169	on_keyboard_command $term, $string
115	Called whenever the user presses a key combination that has a	170	Called whenever the user presses a key combination that has a
116	"perl:string" action bound to it (see description of the keysym	171	"perl:string" action bound to it (see description of the keysym
117	resource in the rxvt(1) manpage).	172	resource in the rxvt(1) manpage).
118		173
		174	Variables in the "urxvt" Package
		175	$urxvt::TERM
		176	The current terminal. Whenever a callback/Hook is bein executed,
		177	this variable stores the current "urxvt::term" object.
		178
119	Functions in the "urxvt" Package	179	Functions in the "urxvt" Package
120	urxvt::fatal $errormessage	180	urxvt::fatal $errormessage
121	Fatally aborts execution with the given error message. Avoid at all	181	Fatally aborts execution with the given error message. Avoid at all
122	costs! The only time this is acceptable is when the terminal process	182	costs! The only time this is acceptable is when the terminal process
123	starts up.	183	starts up.
…		…
131	correct place, e.g. on stderr of the connecting urxvtc client.	191	correct place, e.g. on stderr of the connecting urxvtc client.
132		192
133	$time = urxvt::NOW	193	$time = urxvt::NOW
134	Returns the "current time" (as per the event loop).	194	Returns the "current time" (as per the event loop).
135		195
		196	RENDITION
		197	Rendition bitsets contain information about colour, font, font styles
		198	and similar information for each screen cell.
		199
		200	The following "macros" deal with changes in rendition sets. You should
		201	never just create a bitset, you should always modify an existing one, as
		202	they contain important information required for correct operation of
		203	rxvt-unicode.
		204
		205	$rend = urxvt::DEFAULT_RSTYLE
		206	Returns the default rendition, as used when the terminal is starting
		207	up or being reset. Useful as a base to start when creating
		208	renditions.
		209
		210	$rend = urxvt::OVERLAY_RSTYLE
		211	Return the rendition mask used for overlays by default.
		212
		213	$rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
		214	Return the bit that enabled bold, italic, blink, reverse-video and
		215	underline, respectively. To enable such a style, just logically OR
		216	it into the bitset.
		217
		218	$foreground = urxvt::GET_BASEFG $rend
		219	$background = urxvt::GET_BASEBG $rend
		220	Return the foreground/background colour index, respectively.
		221
		222	$rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
		223	$rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
		224	Replace the foreground/background colour in the rendition mask with
		225	the specified one.
		226
		227	$value = urxvt::GET_CUSTOM ($rend)
		228	Return the "custom" value: Every rendition has 5 bits for use by
		229	extensions. They can be set and changed as you like and are
		230	initially zero.
		231
		232	$rend = urxvt::SET_CUSTOM ($rend, $new_value)
		233	Change the custom value.
		234
136	The "urxvt::term" Class	235	The "urxvt::term" Class
137	$value = $term->resource ($name[, $newval])	236	$value = $term->resource ($name[, $newval])
138	Returns the current resource value associated with a given name and	237	Returns the current resource value associated with a given name and
139	optionally sets a new value. Setting values is most useful in the	238	optionally sets a new value. Setting values is most useful in the
140	"init" hook. Unset resources are returned and accepted as "undef".	239	"init" hook. Unset resources are returned and accepted as "undef".
…		…
158	answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont	257	answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
159	borderLess color cursorBlink cursorUnderline cutchars delete_key	258	borderLess color cursorBlink cursorUnderline cutchars delete_key
160	display_name embed ext_bwidth fade font geometry hold iconName	259	display_name embed ext_bwidth fade font geometry hold iconName
161	imFont imLocale inputMethod insecure int_bwidth intensityStyles	260	imFont imLocale inputMethod insecure int_bwidth intensityStyles
162	italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier	261	italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
163	mouseWheelScrollPage name pastableTabs path perl_eval perl_ext	262	mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
164	perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd	263	perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
165	reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating	264	reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
166	scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput	265	scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
167	scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle	266	scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
168	shade term_name title transparent transparent_all tripleclickwords	267	shade term_name title transparent transparent_all tripleclickwords
169	utmpInhibit visualBell	268	utmpInhibit visualBell
170		269
		270	$rend = $term->screen_rstyle ([$new_rstyle])
		271	Return and optionally change the current rendition. Text thta is
		272	output by the temrianl application will use this style.
		273
		274	($row, $col) = $term->screen_cur ([$row, $col])
		275	Return the current coordinates of the text cursor position and
		276	optionally set it (which is usually bad as applications don't expect
		277	that).
		278
171	($row, $col) = $term->selection_mark ([$row, $col])	279	($row, $col) = $term->selection_mark ([$row, $col])
172	($row, $col) = $term->selection_beg ([$row, $col])	280	($row, $col) = $term->selection_beg ([$row, $col])
173	($row, $col) = $term->selection_end ([$row, $col])	281	($row, $col) = $term->selection_end ([$row, $col])
174	Return the current values of the selection mark, begin or end	282	Return the current values of the selection mark, begin or end
175	positions, and optionally set them to new values.	283	positions, and optionally set them to new values.
…		…
180		288
181	$oldtext = $term->selection ([$newtext])	289	$oldtext = $term->selection ([$newtext])
182	Return the current selection text and optionally replace it by	290	Return the current selection text and optionally replace it by
183	$newtext.	291	$newtext.
184		292
185	$term->scr_overlay ($x, $y, $text)	293	#=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
186	Create a simple multi-line overlay box. See the next method for	294	overlay box. See the next method for details. # #=cut
187	details.
188		295
189	$term->scr_overlay_new ($x, $y, $width, $height)	296	sub urxvt::term::scr_overlay { die; my ($self, $x, $y, $text) = @_;
		297
		298	my @lines = split /\n/, $text;
		299
		300	my $w = 0;
		301	for (map $self->strwidth ($_), @lines) {
		302	$w = $_ if $w < $_;
		303	}
		304
		305	$self->scr_overlay_new ($x, $y, $w, scalar @lines);
		306	$self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
		307	}
		308
		309	$term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
190	Create a new (empty) overlay at the given position with the given	310	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	311	width/height. $rstyle defines the initial rendition style (default:
		312	"OVERLAY_RSTYLE").
		313
		314	If $border is 2 (default), then a decorative border will be put
		315	around the box.
		316
192	$y is negative, then this is counted from the right/bottom side,	317	If either $x or $y is negative, then this is counted from the
193	respectively.	318	right/bottom side, respectively.
194		319
195	$term->scr_overlay_off	320	This method returns an urxvt::overlay object. The overlay will be
196	Switch the overlay off again.	321	visible as long as the perl object is referenced.
197		322
198	$term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)	323	The methods currently supported on "urxvt::overlay" objects are:
199	Put a single character (specified numerically) at the given overlay
200	position.
201		324
202	$term->scr_overlay_set ($x, $y, $text)	325	$overlay->set ($x, $y, $text, $rend)
203	Write a string at the given position into the overlay.	326	Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts
		327	text in rxvt-unicode's special encoding and an array of
		328	rendition values at a specific position inside the overlay.
		329
		330	$overlay->hide
		331	If visible, hide the overlay, but do not destroy it.
		332
		333	$overlay->show
		334	If hidden, display the overlay again.
204		335
205	$cellwidth = $term->strwidth $string	336	$cellwidth = $term->strwidth $string
206	Returns the number of screen-cells this string would need. Correctly	337	Returns the number of screen-cells this string would need. Correctly
207	accounts for wide and combining characters.	338	accounts for wide and combining characters.
208		339
…		…
213	$string = $term->locale_decode $octets	344	$string = $term->locale_decode $octets
214	Convert the given locale-encoded octets into a perl string.	345	Convert the given locale-encoded octets into a perl string.
215		346
216	$term->tt_write ($octets)	347	$term->tt_write ($octets)
217	Write the octets given in $data to the tty (i.e. as program input).	348	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	349	To pass characters instead of octets, you should convert your
219	first to the locale-specific encoding using "$term->locale_encode".	350	strings first to the locale-specific encoding using
		351	"$term->locale_encode".
		352
		353	$window_width = $term->width
		354	$window_height = $term->height
		355	$font_width = $term->fwidth
		356	$font_height = $term->fheight
		357	$font_ascent = $term->fbase
		358	$terminal_rows = $term->nrow
		359	$terminal_columns = $term->ncol
		360	$has_focus = $term->focus
		361	$is_mapped = $term->mapped
		362	$max_scrollback = $term->saveLines
		363	$nrow_plus_saveLines = $term->total_rows
		364	$lines_in_scrollback = $term->nsaved
		365	Return various integers describing terminal characteristics.
		366
		367	$view_start = $term->view_start ([$newvalue])
		368	Returns the negative row number of the topmost line. Minimum value
		369	is 0, which displays the normal terminal contents. Larger values
		370	scroll this many lines into the scrollback buffer.
		371
		372	$term->want_refresh
		373	Requests a screen refresh. At the next opportunity, rxvt-unicode
		374	will compare the on-screen display with its stored representation.
		375	If they differ, it redraws the differences.
		376
		377	Used after changing terminal contents to display them.
		378
		379	$text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
		380	Returns the text of the entire row with number $row_number. Row 0 is
		381	the topmost terminal line, row "$term->$ncol-1" is the bottommost
		382	terminal line. The scrollback buffer starts at line -1 and extends
		383	to line "-$term->nsaved". Nothing will be returned if a nonexistent
		384	line is requested.
		385
		386	If $new_text is specified, it will replace characters in the current
		387	line, starting at column $start_col (default 0), which is useful to
		388	replace only parts of a line. The font index in the rendition will
		389	automatically be updated.
		390
		391	$text is in a special encoding: tabs and wide characters that use
		392	more than one cell when displayed are padded with urxvt::NOCHAR
		393	characters ("chr 65535"). Characters with combining characters and
		394	other characters that do not fit into the normal tetx encoding will
		395	be replaced with characters in the private use area.
		396
		397	You have to obey this encoding when changing text. The advantage is
		398	that "substr" and similar functions work on screen cells and not on
		399	characters.
		400
		401	The methods "$term->special_encode" and "$term->special_decode" can
		402	be used to convert normal strings into this encoding and vice versa.
		403
		404	$rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
		405	Like "$term->ROW_t", but returns an arrayref with rendition bitsets.
		406	Rendition bitsets contain information about colour, font, font
		407	styles and similar information. See also "$term->ROW_t".
		408
		409	When setting rendition, the font mask will be ignored.
		410
		411	See the section on RENDITION, above.
		412
		413	$length = $term->ROW_l ($row_number[, $new_length])
		414	Returns the number of screen cells that are in use ("the line
		415	length"). Unlike the urxvt core, this returns "$term->ncol" if the
		416	line is joined with the following one.
		417
		418	$bool = $term->is_longer ($row_number)
		419	Returns true if the row is part of a multiple-row logical "line"
		420	(i.e. joined with the following row), which means all characters are
		421	in use and it is continued on the next row (and possibly a
		422	continuation of the previous row(s)).
		423
		424	$line = $term->line ($row_number)
		425	Create and return a new "urxvt::line" object that stores information
		426	about the logical line that row $row_number is part of. It supports
		427	the following methods:
		428
		429	$text = $line->t
		430	Returns the full text of the line, similar to "ROW_t"
		431
		432	$rend = $line->r
		433	Returns the full rendition array of the line, similar to "ROW_r"
		434
		435	$length = $line->l
		436	Returns the length of the line in cells, similar to "ROW_l".
		437
		438	$rownum = $line->beg
		439	$rownum = $line->end
		440	Return the row number of the first/last row of the line,
		441	respectively.
		442
		443	$offset = $line->offset_of ($row, $col)
		444	Returns the character offset of the given row\|col pair within
		445	the logical line.
		446
		447	($row, $col) = $line->coord_of ($offset)
		448	Translates a string offset into terminal coordinates again.
		449
		450	($row, $col) = $line->coord_of ($offset) =item $text =
		451	$term->special_encode $string
		452	Converts a perl string into the special encoding used by
		453	rxvt-unicode, where one character corresponds to one screen cell.
		454	See "$term->ROW_t" for details.
		455
		456	$string = $term->special_decode $text
		457	Converts rxvt-unicodes text reprsentation into a perl string. See
		458	"$term->ROW_t" for details.
220		459
221	The "urxvt::timer" Class	460	The "urxvt::timer" Class
222	This class implements timer watchers/events. Time is represented as a	461	This class implements timer watchers/events. Time is represented as a
223	fractional number of seconds since the epoch. Example:	462	fractional number of seconds since the epoch. Example:
224		463
225	# create a digital clock display in upper right corner	464	$term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
226	$term->{timer} = urxvt::timer	465	$term->{timer} = urxvt::timer
227	->new	466	->new
228	->start (urxvt::NOW)	467	->interval (1)
229	->cb (sub {	468	->cb (sub {
230	my ($timer) = @_;
231	my $time = $timer->at;
232	$timer->start ($time + 1);
233	$self->scr_overlay (-1, 0,	469	$term->{overlay}->set (0, 0,
234	POSIX::strftime "%H:%M:%S", localtime $time);	470	sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
235	});	471	});
236		472
237	$timer = new urxvt::timer	473	$timer = new urxvt::timer
238	Create a new timer object in stopped state.	474	Create a new timer object in started state. It is scheduled to fire
		475	immediately.
239		476
240	$timer = $timer->cb (sub { my ($timer) = @_; ... })	477	$timer = $timer->cb (sub { my ($timer) = @_; ... })
241	Set the callback to be called when the timer triggers.	478	Set the callback to be called when the timer triggers.
242		479
243	$tstamp = $timer->at	480	$tstamp = $timer->at
244	Return the time this watcher will fire next.	481	Return the time this watcher will fire next.
245		482
246	$timer = $timer->set ($tstamp)	483	$timer = $timer->set ($tstamp)
247	Set the time the event is generated to $tstamp.	484	Set the time the event is generated to $tstamp.
		485
		486	$timer = $timer->interval ($interval)
		487	Normally (and when $interval is 0), the timer will automatically
		488	stop after it has fired once. If $interval is non-zero, then the
		489	timer is automatically rescheduled at the given intervals.
248		490
249	$timer = $timer->start	491	$timer = $timer->start
250	Start the timer.	492	Start the timer.
251		493
252	$timer = $timer->start ($tstamp)	494	$timer = $timer->start ($tstamp)
…		…
294	ENVIRONMENT	536	ENVIRONMENT
295	URXVT_PERL_VERBOSITY	537	URXVT_PERL_VERBOSITY
296	This variable controls the verbosity level of the perl extension. Higher	538	This variable controls the verbosity level of the perl extension. Higher
297	numbers indicate more verbose output.	539	numbers indicate more verbose output.
298		540
299	0 - only fatal messages	541	=0 - only fatal messages
300	3 - script loading and management	542	=3 - script loading and management
301	10 - all events received	543	=10 - all events received
302		544
303	AUTHOR	545	AUTHOR
304	Marc Lehmann <pcg@goof.com>	546	Marc Lehmann <pcg@goof.com>
305	http://software.schmorp.de/pkg/rxvt-unicode	547	http://software.schmorp.de/pkg/rxvt-unicode
306		548

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.11 by root, Wed Jan 4 21:37:55 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.11 by root, Wed Jan 4 21:37:55 2006 UTC