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

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents):
Revision 1.1 by root, Mon Jan 2 19:36:07 2006 UTC vs.
Revision 1.11 by root, Wed Jan 4 21:37:55 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	On startup, rxvt will scan /opt/rxvt/lib/urxvt/perl-ext/ for files and	17	Everytime a terminal object gets created, scripts specified via the
20	will load them. Everytime a terminal object gets created, the directory	18	"perl" resource are loaded and associated with it.
21	specified by the "perl-lib" resource will be additionally scanned.	19
		20	Scripts are compiled in a 'use strict' and 'use utf8' environment, and
		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 for all terminals.	24	will be shared (but not enabled) for all terminals.
25		25
26	Hooks in scripts specified by "perl-lib" will only be called for the	26	Prepackaged Extensions
27	terminals created with that specific option value.	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.
28		54
29	General API Considerations	55	General API Considerations
30	All objects (such as terminals, time watchers etc.) are typical	56	All objects (such as terminals, time watchers etc.) are typical
31	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
32	like. All members starting with an underscore (such as "_ptr" or	58	like. All members starting with an underscore (such as "_ptr" or
33	"_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
34	modified).	60	modified).
35		61
36	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
37	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
38	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
40		66
41	Hooks	67	Hooks
42	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
43	called whenever the relevant event happens.	69	called whenever the relevant event happens.
44		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
45	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
46	counts as being consumed, and the invocation of other hooks is	78	counts as being consumed, and the invocation of other hooks is
47	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++
48	code.	80	code.
49		81
…		…
77	queried and changed by calling "$term->selection".	109	queried and changed by calling "$term->selection".
78		110
79	Returning a true value aborts selection grabbing. It will still be	111	Returning a true value aborts selection grabbing. It will still be
80	hilighted.	112	hilighted.
81		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
82	on_focus_in $term	122	on_focus_in $term
83	Called whenever the window gets the keyboard focus, before urxvt	123	Called whenever the window gets the keyboard focus, before urxvt
84	does focus in processing.	124	does focus in processing.
85		125
86	on_focus_out $term	126	on_focus_out $term
…		…
102	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.
103		143
104	on_tty_activity $term NYI	144	on_tty_activity $term NYI
105	Called whenever the program(s) running in the urxvt window send	145	Called whenever the program(s) running in the urxvt window send
106	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.).
107		159
108	on_refresh_begin $term	160	on_refresh_begin $term
109	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
110	or similar effects by modify terminal contents in refresh_begin, and	162	or similar effects by modify terminal contents in refresh_begin, and
111	restoring them in refresh_end. The built-in overlay and selection	163	restoring them in refresh_end. The built-in overlay and selection
112	display code is run after this hook, and takes precedence.	164	display code is run after this hook, and takes precedence.
113		165
114	on_refresh_end $term	166	on_refresh_end $term
115	Called just after the screen gets redrawn. See "on_refresh_begin".	167	Called just after the screen gets redrawn. See "on_refresh_begin".
116		168
		169	on_keyboard_command $term, $string
		170	Called whenever the user presses a key combination that has a
		171	"perl:string" action bound to it (see description of the keysym
		172	resource in the rxvt(1) manpage).
		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
117	Functions in the "urxvt" Package	179	Functions in the "urxvt" Package
118	urxvt::fatal $errormessage	180	urxvt::fatal $errormessage
119	Fatally aborts execution with the given error message. Avoid at all	181	Fatally aborts execution with the given error message. Avoid at all
120	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
121	starts up.	183	starts up.
…		…
129	correct place, e.g. on stderr of the connecting urxvtc client.	191	correct place, e.g. on stderr of the connecting urxvtc client.
130		192
131	$time = urxvt::NOW	193	$time = urxvt::NOW
132	Returns the "current time" (as per the event loop).	194	Returns the "current time" (as per the event loop).
133		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
134	The "urxvt::term" Class	235	The "urxvt::term" Class
135	$value = $term->resource ($name[, $newval])	236	$value = $term->resource ($name[, $newval])
136	Returns the current resource value associated with a given name and	237	Returns the current resource value associated with a given name and
137	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
138	"init" hook. Unset resources are returned and accepted as "undef".	239	"init" hook. Unset resources are returned and accepted as "undef".
…		…
155		256
156	answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont	257	answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
157	borderLess color cursorBlink cursorUnderline cutchars delete_key	258	borderLess color cursorBlink cursorUnderline cutchars delete_key
158	display_name embed ext_bwidth fade font geometry hold iconName	259	display_name embed ext_bwidth fade font geometry hold iconName
159	imFont imLocale inputMethod insecure int_bwidth intensityStyles	260	imFont imLocale inputMethod insecure int_bwidth intensityStyles
160	italicFont jumpScroll lineSpace loginShell mapAlert menu meta8	261	italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
161	modifier mouseWheelScrollPage name pastableTabs path perl perl_eval	262	mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
162	perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd	263	perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
163	reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating	264	reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
164	scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput	265	scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
165	scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle	266	scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
166	shade term_name title transparent transparent_all tripleclickwords	267	shade term_name title transparent transparent_all tripleclickwords
167	utmpInhibit visualBell	268	utmpInhibit visualBell
168		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
169	($row, $col) = $term->selection_mark ([$row, $col])	279	($row, $col) = $term->selection_mark ([$row, $col])
170	($row, $col) = $term->selection_beg ([$row, $col])	280	($row, $col) = $term->selection_beg ([$row, $col])
171	($row, $col) = $term->selection_end ([$row, $col])	281	($row, $col) = $term->selection_end ([$row, $col])
172	Return the current values of the selection mark, begin or end	282	Return the current values of the selection mark, begin or end
173	positions, and optionally set them to new values.	283	positions, and optionally set them to new values.
…		…
178		288
179	$oldtext = $term->selection ([$newtext])	289	$oldtext = $term->selection ([$newtext])
180	Return the current selection text and optionally replace it by	290	Return the current selection text and optionally replace it by
181	$newtext.	291	$newtext.
182		292
183	$term->scr_overlay ($x, $y, $text)	293	#=item $term->overlay ($x, $y, $text) # #Create a simple multi-line
184	Create a simple multi-line overlay box. See the next method for	294	overlay box. See the next method for details. # #=cut
185	details.
186		295
187	$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]])
188	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
189	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
190	$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
191	respectively.	318	right/bottom side, respectively.
192		319
193	$term->scr_overlay_off	320	This method returns an urxvt::overlay object. The overlay will be
194	Switch the overlay off again.	321	visible as long as the perl object is referenced.
195		322
196	$term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)	323	The methods currently supported on "urxvt::overlay" objects are:
197	Put a single character (specified numerically) at the given overlay
198	position.
199		324
200	$term->scr_overlay_set ($x, $y, $text)	325	$overlay->set ($x, $y, $text, $rend)
201	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.
202		335
203	$cellwidth = $term->strwidth $string	336	$cellwidth = $term->strwidth $string
204	Returns the number of screen-cells this string would need. Correctly	337	Returns the number of screen-cells this string would need. Correctly
205	accounts for wide and combining characters.	338	accounts for wide and combining characters.
206		339
…		…
211	$string = $term->locale_decode $octets	344	$string = $term->locale_decode $octets
212	Convert the given locale-encoded octets into a perl string.	345	Convert the given locale-encoded octets into a perl string.
213		346
214	$term->tt_write ($octets)	347	$term->tt_write ($octets)
215	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).
216	To pass characters instead of octets, you should convetr you strings	349	To pass characters instead of octets, you should convert your
217	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.
218		459
219	The "urxvt::timer" Class	460	The "urxvt::timer" Class
220	This class implements timer watchers/events. Time is represented as a	461	This class implements timer watchers/events. Time is represented as a
221	fractional number of seconds since the epoch. Example:	462	fractional number of seconds since the epoch. Example:
222		463
223	# create a digital clock display in upper right corner	464	$term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
224	$term->{timer} = urxvt::timer	465	$term->{timer} = urxvt::timer
225	->new	466	->new
226	->start (urxvt::NOW)	467	->interval (1)
227	->cb (sub {	468	->cb (sub {
228	my ($timer) = @_;
229	my $time = $timer->at;
230	$timer->start ($time + 1);
231	$self->scr_overlay (-1, 0,	469	$term->{overlay}->set (0, 0,
232	POSIX::strftime "%H:%M:%S", localtime $time);	470	sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
233	});	471	});
234		472
235	$timer = new urxvt::timer	473	$timer = new urxvt::timer
236	Create a new timer object in stopped state.	474	Create a new timer object in started state. It is scheduled to fire
		475	immediately.
237		476
238	$timer = $timer->cb (sub { my ($timer) = @_; ... })	477	$timer = $timer->cb (sub { my ($timer) = @_; ... })
239	Set the callback to be called when the timer triggers.	478	Set the callback to be called when the timer triggers.
240		479
241	$tstamp = $timer->at	480	$tstamp = $timer->at
242	Return the time this watcher will fire next.	481	Return the time this watcher will fire next.
243		482
244	$timer = $timer->set ($tstamp)	483	$timer = $timer->set ($tstamp)
245	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.
246		490
247	$timer = $timer->start	491	$timer = $timer->start
248	Start the timer.	492	Start the timer.
249		493
250	$timer = $timer->start ($tstamp)	494	$timer = $timer->start ($tstamp)
…		…
292	ENVIRONMENT	536	ENVIRONMENT
293	URXVT_PERL_VERBOSITY	537	URXVT_PERL_VERBOSITY
294	This variable controls the verbosity level of the perl extension. Higher	538	This variable controls the verbosity level of the perl extension. Higher
295	numbers indicate more verbose output.	539	numbers indicate more verbose output.
296		540
297	0 - only fatal messages	541	=0 - only fatal messages
298	3 - script loading and management	542	=3 - script loading and management
299	10 - all events received	543	=10 - all events received
300		544
301	AUTHOR	545	AUTHOR
302	Marc Lehmann <pcg@goof.com>	546	Marc Lehmann <pcg@goof.com>
303	http://software.schmorp.de/pkg/rxvt-unicode	547	http://software.schmorp.de/pkg/rxvt-unicode
304		548

Diff Legend

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

Comparing rxvt-unicode/doc/rxvtperl.3.txt (file contents): Revision 1.1 by root, Mon Jan 2 19:36:07 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.1 by root, Mon Jan 2 19:36:07 2006 UTC vs.
Revision 1.11 by root, Wed Jan 4 21:37:55 2006 UTC