[ViewVC] Diff of: cvs/rxvt-unicode/src/urxvt.pm

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.7 by root, Mon Jan 2 19:05:05 2006 UTC vs.
Revision 1.22 by root, Tue Jan 3 19:10:54 2006 UTC

…		…
		1	=encoding utf8
		2
1	=head1 NAME	3	=head1 NAME
2		4
3	rxvtperl - rxvt-unicode's embedded perl interpreter	5	@@RXVT_NAME@@perl - rxvt-unicode's embedded perl interpreter
4		6
5	=head1 SYNOPSIS	7	=head1 SYNOPSIS
6		8
7	* Put your scripts into F<@@RXVT_LIBDIR@@/urxvt/perl-ext/>, they will be loaded automatically.	9	# create a file grab_test in $HOME:
8
9	* Scripts are evaluated in a 'use strict' and 'use utf8' environment, and
10	thus must be encoded as UTF-8.
11		10
12	sub on_sel_grab {	11	sub on_sel_grab {
13	warn "you selected ", $_[0]->selection;	12	warn "you selected ", $_[0]->selection;
14	()	13	()
15	}	14	}
16		15
17	1	16	# start a @@RXVT_NAME@@ using it:
		17
		18	@@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
18		19
19	=head1 DESCRIPTION	20	=head1 DESCRIPTION
20		21
21	On startup, @@RXVT_NAME@@ will scan F<@@RXVT_LIBDIR@@/urxvt/perl-ext/>	22	Everytime a terminal object gets created, scripts specified via the
22	for files and will load them. Everytime a terminal object gets created,	23	C<perl> resource are loaded and associated with it.
23	the directory specified by the C<perl-lib> resource will be additionally	24
24	scanned.	25	Scripts are compiled in a 'use strict' and 'use utf8' environment, and
		26	thus must be encoded as UTF-8.
25		27
26	Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where	28	Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
27	scripts will be shared for all terminals.	29	scripts will be shared (but not enabled) for all terminals.
28		30
29	Hooks in scripts specified by C<perl-lib> will only be called for the	31	=head2 Prepackaged Extensions
30	terminals created with that specific option value.	32
		33	This section describes the extensiosn delivered with this version. You can
		34	find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
		35
		36	You can activate them like this:
		37
		38	@@RXVT_NAME@@ -pe <extensionname>
		39
		40	=over 4
		41
		42	=item selection
		43
		44	Intelligent selection. This etxension tries to be more intelligent when the user
		45	extends selections (double-click).
		46
		47	It also offers the following bindable event:
		48
		49	=over 4
		50
		51	=item rot13
		52
		53	Rot-13 the selection when activated. Used via keyboard trigger:
		54
		55	URxvt.keysym.C-M-r: perl:selection:rot13
		56
		57	=back
		58
		59	=item digital-clock
		60
		61	Displays a digital clock using the built-in overlay.
		62
		63	=item example-refresh-hooks
		64
		65	Displays a very simple digital clock in the upper right corner of the
		66	window. Illustrates overwriting the refresh callbacks to create your own
		67	overlays or changes.
		68
		69	=back
31		70
32	=head2 General API Considerations	71	=head2 General API Considerations
33		72
34	All objects (such as terminals, time watchers etc.) are typical	73	All objects (such as terminals, time watchers etc.) are typical
35	reference-to-hash objects. The hash can be used to store anything you	74	reference-to-hash objects. The hash can be used to store anything you
86	requested from the server. The selection text can be queried and changed	125	requested from the server. The selection text can be queried and changed
87	by calling C<< $term->selection >>.	126	by calling C<< $term->selection >>.
88		127
89	Returning a true value aborts selection grabbing. It will still be hilighted.	128	Returning a true value aborts selection grabbing. It will still be hilighted.
90		129
		130	=item on_sel_extend $term
		131
		132	Called whenever the user tries to extend the selection (e.g. with a double
		133	click) and is either supposed to return false (normal operation), or
		134	should extend the selection itelf and return true to suppress the built-in
		135	processing.
		136
		137	See the F<selection> example extension.
		138
91	=item on_focus_in $term	139	=item on_focus_in $term
92		140
93	Called whenever the window gets the keyboard focus, before urxvt does	141	Called whenever the window gets the keyboard focus, before urxvt does
94	focus in processing.	142	focus in processing.
95		143
…		…
127		175
128	=item on_refresh_end $term	176	=item on_refresh_end $term
129		177
130	Called just after the screen gets redrawn. See C<on_refresh_begin>.	178	Called just after the screen gets redrawn. See C<on_refresh_begin>.
131		179
		180	=item on_keyboard_command $term, $string
		181
		182	Called whenever the user presses a key combination that has a
		183	C<perl:string> action bound to it (see description of the B<keysym>
		184	resource in the @@RXVT_NAME@@(1) manpage).
		185
132	=back	186	=back
133		187
134	=head2 Functions in the C<urxvt> Package	188	=head2 Functions in the C<urxvt> Package
135		189
136	=over 4	190	=over 4
…		…
151	correct place, e.g. on stderr of the connecting urxvtc client.	205	correct place, e.g. on stderr of the connecting urxvtc client.
152		206
153	=item $time = urxvt::NOW	207	=item $time = urxvt::NOW
154		208
155	Returns the "current time" (as per the event loop).	209	Returns the "current time" (as per the event loop).
		210
		211	=back
		212
		213	=head2 RENDITION
		214
		215	Rendition bitsets contain information about colour, font, font styles and
		216	similar information for each screen cell.
		217
		218	The following "macros" deal with changes in rendition sets. You should
		219	never just create a bitset, you should always modify an existing one,
		220	as they contain important information required for correct operation of
		221	rxvt-unicode.
		222
		223	=over 4
		224
		225	=item $rend = urxvt::DEFAULT_RSTYLE
		226
		227	Returns the default rendition, as used when the terminal is starting up or
		228	being reset. Useful as a base to start when creating renditions.
		229
		230	=item $rend = urxvt::OVERLAY_RSTYLE
		231
		232	Return the rendition mask used for overlays by default.
		233
		234	=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
		235
		236	Return the bit that enabled bold, italic, blink, reverse-video and
		237	underline, respectively. To enable such a style, just logically OR it into
		238	the bitset.
		239
		240	=item $foreground = urxvt::GET_BASEFG $rend
		241
		242	=item $background = urxvt::GET_BASEBG $rend
		243
		244	Return the foreground/background colour index, respectively.
		245
		246	=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
		247
		248	=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
		249
		250	Replace the foreground/background colour in the rendition mask with the
		251	specified one.
		252
		253	=item $value = urxvt::GET_CUSTOM ($rend)
		254
		255	Return the "custom" value: Every rendition has 5 bits for use by
		256	extensions. They can be set and changed as you like and are initially
		257	zero.
		258
		259	=item $rend = urxvt::SET_CUSTOM ($rend, $new_value)
		260
		261	Change the custom value.
		262
		263	=back
156		264
157	=cut	265	=cut
158		266
159	package urxvt;	267	package urxvt;
160		268
…		…
174	unless $msg =~ /\n$/;	282	unless $msg =~ /\n$/;
175	urxvt::warn ($msg);	283	urxvt::warn ($msg);
176	};	284	};
177	}	285	}
178		286
		287	my @hook_count;
179	my $verbosity = $ENV{URXVT_PERL_VERBOSITY};	288	my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
180		289
181	sub verbose {	290	sub verbose {
182	my ($level, $msg) = @_;	291	my ($level, $msg) = @_;
183	warn "$msg\n" if $level < $verbosity;	292	warn "$msg\n" if $level <= $verbosity;
184	}
185
186	my %hook_global;
187	my @hook_count;
188
189	# called by the rxvt core
190	sub invoke {
191	local $term = shift;
192	my $htype = shift;
193
194	verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")"
195	if $verbosity >= 10;
196
197	for my $cb ($hook_global{_hook}[$htype], $term->{_hook}[$htype]) {
198	$cb or next;
199
200	while (my ($k, $v) = each %$cb) {
201	return 1 if $v->($term, @_);
202	}
203	}
204
205	0
206	}	293	}
207		294
208	# find on_xxx subs in the package and register them	295	# find on_xxx subs in the package and register them
209	# as hooks	296	# as hooks
210	sub register_package($) {	297	sub register_package($) {
…		…
228	# load a single script into its own package, once only	315	# load a single script into its own package, once only
229	sub script_package($) {	316	sub script_package($) {
230	my ($path) = @_;	317	my ($path) = @_;
231		318
232	$script_pkg{$path} \|\|= do {	319	$script_pkg{$path} \|\|= do {
233	my $pkg = $script_pkg++;	320	my $pkg = "urxvt::" . ($script_pkg++);
		321
234	verbose 3, "loading script '$path' into package '$pkg'";	322	verbose 3, "loading script '$path' into package '$pkg'";
235		323
236	open my $fh, "<:raw", $path	324	open my $fh, "<:raw", $path
237	or die "$path: $!";	325	or die "$path: $!";
238		326
239	eval "package $pkg; use strict; use utf8;\n"	327	my $source = "package $pkg; use strict; use utf8;\n"
240	. "#line 1 \"$path\"\n"	328	. "#line 1 \"$path\"\n{\n"
241	. do { local $/; <$fh> }	329	. (do { local $/; <$fh> })
		330	. "\n};\n1";
		331
242	or die "$path: $@";	332	eval $source or die "$path: $@";
243		333
244	$pkg	334	$pkg
245	}	335	}
246	}	336	}
247		337
248	sub load_scripts($) {	338	# called by the rxvt core
249	my ($dir) = @_;	339	sub invoke {
		340	local $term = shift;
		341	my $htype = shift;
250		342
251	verbose 3, "loading scripts from '$dir'";	343	if ($htype == 0) { # INIT
		344	my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl");
252		345
		346	for my $ext (split /:/, $term->resource ("perl_ext")) {
		347	my @files = grep -f $_, map "$_/$ext", @dirs;
		348
		349	if (@files) {
253	register_package script_package $_	350	register_package script_package $files[0];
254	for grep -f $_,	351	} else {
255	<$dir/*>;	352	warn "perl extension '$ext' not found in perl library search path\n";
		353	}
		354	}
		355
		356	} elsif ($htype == 1) { # DESTROY
		357	if (my $hook = $term->{_hook}) {
		358	for my $htype (0..$#$hook) {
		359	$hook_count[$htype] -= scalar keys %{ $hook->[$htype] \|\| {} }
		360	or set_should_invoke $htype, 0;
		361	}
		362	}
		363	}
		364
		365	my $cb = $term->{_hook}[$htype]
		366	or return;
		367
		368	verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")"
		369	if $verbosity >= 10;
		370
		371	while (my ($k, $v) = each %$cb) {
		372	return 1 if $v->($term, @_);
		373	}
		374
		375	0
256	}	376	}
257
258	sub on_init {
259	my ($term) = @_;
260
261	my $libdir = $term->resource ("perl_lib");
262
263	load_scripts $libdir
264	if defined $libdir;
265	}
266
267	sub on_destroy {
268	my ($term) = @_;
269
270	my $hook = $term->{_hook}
271	or return;
272
273	for my $htype (0..$#$hook) {
274	$hook_count[$htype] -= scalar keys %{ $hook->[$htype] \|\| {} }
275	or set_should_invoke $htype, 0;
276	}
277	}
278
279	{
280	local $term = \%hook_global;
281
282	register_package __PACKAGE__;
283	load_scripts "$LIBDIR/perl-ext";
284	}
285
286	=back
287		377
288	=head2 The C<urxvt::term> Class	378	=head2 The C<urxvt::term> Class
289		379
290	=over 4	380	=over 4
291		381
…		…
312		402
313	answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont	403	answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
314	borderLess color cursorBlink cursorUnderline cutchars delete_key	404	borderLess color cursorBlink cursorUnderline cutchars delete_key
315	display_name embed ext_bwidth fade font geometry hold iconName	405	display_name embed ext_bwidth fade font geometry hold iconName
316	imFont imLocale inputMethod insecure int_bwidth intensityStyles	406	imFont imLocale inputMethod insecure int_bwidth intensityStyles
317	italicFont jumpScroll lineSpace loginShell mapAlert menu meta8	407	italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
318	modifier mouseWheelScrollPage name pastableTabs path perl perl_eval	408	mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
319	perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd	409	perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
320	reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating	410	reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
321	scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput	411	scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
322	scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle	412	scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
323	shade term_name title transparent transparent_all tripleclickwords	413	shade term_name title transparent transparent_all tripleclickwords
…		…
347		437
348	=item $oldtext = $term->selection ([$newtext])	438	=item $oldtext = $term->selection ([$newtext])
349		439
350	Return the current selection text and optionally replace it by C<$newtext>.	440	Return the current selection text and optionally replace it by C<$newtext>.
351		441
352	=item $term->scr_overlay ($x, $y, $text)	442	#=item $term->overlay ($x, $y, $text)
353		443	#
354	Create a simple multi-line overlay box. See the next method for details.	444	#Create a simple multi-line overlay box. See the next method for details.
355		445	#
356	=cut	446	#=cut
357		447
358	sub urxvt::term::scr_overlay {	448	sub urxvt::term::scr_overlay {
		449	die;
359	my ($self, $x, $y, $text) = @_;	450	my ($self, $x, $y, $text) = @_;
360		451
361	my @lines = split /\n/, $text;	452	my @lines = split /\n/, $text;
362		453
363	my $w = 0;	454	my $w = 0;
…		…
367		458
368	$self->scr_overlay_new ($x, $y, $w, scalar @lines);	459	$self->scr_overlay_new ($x, $y, $w, scalar @lines);
369	$self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;	460	$self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
370	}	461	}
371		462
372	=item $term->scr_overlay_new ($x, $y, $width, $height)	463	=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
373		464
374	Create a new (empty) overlay at the given position with the given	465	Create a new (empty) overlay at the given position with the given
375	width/height. A border will be put around the box. If either C<$x> or	466	width/height. C<$rstyle> defines the initial rendition style
376	C<$y> is negative, then this is counted from the right/bottom side,	467	(default: C<OVERLAY_RSTYLE>).
377	respectively.
378		468
379	=item $term->scr_overlay_off	469	If C<$border> is C<2> (default), then a decorative border will be put
		470	around the box.
380		471
381	Switch the overlay off again.	472	If either C<$x> or C<$y> is negative, then this is counted from the
		473	right/bottom side, respectively.
382		474
383	=item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)	475	This method returns an urxvt::overlay object. The overlay will be visible
		476	as long as the perl object is referenced.
384		477
385	Put a single character (specified numerically) at the given overlay	478	The methods currently supported on C<urxvt::overlay> objects are:
386	position.
387		479
		480	=over 4
		481
388	=item $term->scr_overlay_set ($x, $y, $text)	482	=item $overlay->set ($x, $y, $text, $rend)
389		483
390	Write a string at the given position into the overlay.	484	Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
		485	text in rxvt-unicode's special encoding and an array of rendition values
		486	at a specific position inside the overlay.
		487
		488	=item $overlay->hide
		489
		490	If visible, hide the overlay, but do not destroy it.
		491
		492	=item $overlay->show
		493
		494	If hidden, display the overlay again.
		495
		496	=back
391		497
392	=item $cellwidth = $term->strwidth $string	498	=item $cellwidth = $term->strwidth $string
393		499
394	Returns the number of screen-cells this string would need. Correctly	500	Returns the number of screen-cells this string would need. Correctly
395	accounts for wide and combining characters.	501	accounts for wide and combining characters.
…		…
403	Convert the given locale-encoded octets into a perl string.	509	Convert the given locale-encoded octets into a perl string.
404		510
405	=item $term->tt_write ($octets)	511	=item $term->tt_write ($octets)
406		512
407	Write the octets given in C<$data> to the tty (i.e. as program input). To	513	Write the octets given in C<$data> to the tty (i.e. as program input). To
408	pass characters instead of octets, you should convetr you strings first to	514	pass characters instead of octets, you should convert your strings first
409	the locale-specific encoding using C<< $term->locale_encode >>.	515	to the locale-specific encoding using C<< $term->locale_encode >>.
		516
		517	=item $nrow = $term->nrow
		518
		519	=item $ncol = $term->ncol
		520
		521	Return the number of rows/columns of the terminal window (i.e. as
		522	specified by C<-geometry>, excluding any scrollback).
		523
		524	=item $nsaved = $term->nsaved
		525
		526	Returns the number of lines in the scrollback buffer.
		527
		528	=item $view_start = $term->view_start ([$newvalue])
		529
		530	Returns the negative row number of the topmost line. Minimum value is
		531	C<0>, which displays the normal terminal contents. Larger values scroll
		532	this many lines into the scrollback buffer.
		533
		534	=item $term->want_refresh
		535
		536	Requests a screen refresh. At the next opportunity, rxvt-unicode will
		537	compare the on-screen display with its stored representation. If they
		538	differ, it redraws the differences.
		539
		540	Used after changing terminal contents to display them.
		541
		542	=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
		543
		544	Returns the text of the entire row with number C<$row_number>. Row C<0>
		545	is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost
		546	terminal line. The scrollback buffer starts at line C<-1> and extends to
		547	line C<< -$term->nsaved >>.
		548
		549	If C<$new_text> is specified, it will replace characters in the current
		550	line, starting at column C<$start_col> (default C<0>), which is useful
		551	to replace only parts of a line. The font index in the rendition will
		552	automatically be updated.
		553
		554	C<$text> is in a special encoding: tabs and wide characters that use more
		555	than one cell when displayed are padded with urxvt::NOCHAR characters
		556	(C<chr 65535>). Characters with combining characters and other characters
		557	that do not fit into the normal tetx encoding will be replaced with
		558	characters in the private use area.
		559
		560	You have to obey this encoding when changing text. The advantage is
		561	that C<substr> and similar functions work on screen cells and not on
		562	characters.
		563
		564	The methods C<< $term->special_encode >> and C<< $term->special_decode >>
		565	can be used to convert normal strings into this encoding and vice versa.
		566
		567	=item $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
		568
		569	Like C<< $term->ROW_t >>, but returns an arrayref with rendition
		570	bitsets. Rendition bitsets contain information about colour, font, font
		571	styles and similar information. See also C<< $term->ROW_t >>.
		572
		573	When setting rendition, the font mask will be ignored.
		574
		575	See the section on RENDITION, above.
		576
		577	=item $length = $term->ROW_l ($row_number[, $new_length])
		578
		579	Returns the number of screen cells that are in use ("the line length"). If
		580	it is C<-1>, then the line is part of a multiple-row logical "line", which
		581	means all characters are in use and it is continued on the next row.
		582
		583	=item $text = $term->special_encode $string
		584
		585	Converts a perl string into the special encoding used by rxvt-unicode,
		586	where one character corresponds to one screen cell. See
		587	C<< $term->ROW_t >> for details.
		588
		589	=item $string = $term->special_decode $text
		590
		591	Converts rxvt-unicodes text reprsentation into a perl string. See
		592	C<< $term->ROW_t >> for details.
410		593
411	=back	594	=back
412		595
413	=head2 The C<urxvt::timer> Class	596	=head2 The C<urxvt::timer> Class
414		597
415	This class implements timer watchers/events. Time is represented as a	598	This class implements timer watchers/events. Time is represented as a
416	fractional number of seconds since the epoch. Example:	599	fractional number of seconds since the epoch. Example:
417		600
418	# create a digital clock display in upper right corner	601	$term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
419	$term->{timer} = urxvt::timer	602	$term->{timer} = urxvt::timer
420	->new	603	->new
421	->start (urxvt::NOW)	604	->interval (1)
422	->cb (sub {	605	->cb (sub {
423	my ($timer) = @_;
424	my $time = $timer->at;
425	$timer->start ($time + 1);
426	$self->scr_overlay (-1, 0,	606	$term->{overlay}->set (0, 0,
427	POSIX::strftime "%H:%M:%S", localtime $time);	607	sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
428	});	608	});
429		609
430	=over 4	610	=over 4
431		611
432	=item $timer = new urxvt::timer	612	=item $timer = new urxvt::timer
433		613
434	Create a new timer object in stopped state.	614	Create a new timer object in started state. It is scheduled to fire
		615	immediately.
435		616
436	=item $timer = $timer->cb (sub { my ($timer) = @_; ... })	617	=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
437		618
438	Set the callback to be called when the timer triggers.	619	Set the callback to be called when the timer triggers.
439		620
…		…
442	Return the time this watcher will fire next.	623	Return the time this watcher will fire next.
443		624
444	=item $timer = $timer->set ($tstamp)	625	=item $timer = $timer->set ($tstamp)
445		626
446	Set the time the event is generated to $tstamp.	627	Set the time the event is generated to $tstamp.
		628
		629	=item $timer = $timer->interval ($interval)
		630
		631	Normally (and when C<$interval> is C<0>), the timer will automatically
		632	stop after it has fired once. If C<$interval> is non-zero, then the timer
		633	is automatically rescheduled at the given intervals.
447		634
448	=item $timer = $timer->start	635	=item $timer = $timer->start
449		636
450	Start the timer.	637	Start the timer.
451		638

Diff Legend

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

Comparing rxvt-unicode/src/urxvt.pm (file contents): Revision 1.7 by root, Mon Jan 2 19:05:05 2006 UTC vs. Revision 1.22 by root, Tue Jan 3 19:10:54 2006 UTC

Diff Legend

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.7 by root, Mon Jan 2 19:05:05 2006 UTC vs.
Revision 1.22 by root, Tue Jan 3 19:10:54 2006 UTC