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

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.121 by root, Fri Jan 20 22:49:34 2006 UTC vs.
Revision 1.131 by root, Sun Jan 29 20:51:28 2006 UTC

…		…
66	contain at least one pair of capturing parentheses, which will be used for	66	contain at least one pair of capturing parentheses, which will be used for
67	the match. For example, the followign adds a regex that matches everything	67	the match. For example, the followign adds a regex that matches everything
68	between two vertical bars:	68	between two vertical bars:
69		69
70	URxvt.selection.pattern-0: \\\|([^\|]+)\\\|	70	URxvt.selection.pattern-0: \\\|([^\|]+)\\\|
		71
		72	Another example: Programs I use often output "absolute path: " at the
		73	beginning of a line when they process multiple files. The following
		74	pattern matches the filename (note, there is a single space at the very
		75	end):
		76
		77	URxvt.selection.pattern-0: ^(/[^:]+):\
71		78
72	You can look at the source of the selection extension to see more	79	You can look at the source of the selection extension to see more
73	interesting uses, such as parsing a line from beginning to end.	80	interesting uses, such as parsing a line from beginning to end.
74		81
75	This extension also offers following bindable keyboard commands:	82	This extension also offers following bindable keyboard commands:
…		…
127	bottom. C<Escape> leaves search mode and returns to the point where search	134	bottom. C<Escape> leaves search mode and returns to the point where search
128	was started, while C<Enter> or C<Return> stay at the current position and	135	was started, while C<Enter> or C<Return> stay at the current position and
129	additionally stores the first match in the current line into the primary	136	additionally stores the first match in the current line into the primary
130	selection.	137	selection.
131		138
132	=item selection-autotransform	139	=item readline (enabled by default)
133
134	This selection allows you to do automatic transforms on a selection
135	whenever a selection is made.
136
137	It works by specifying perl snippets (most useful is a single C<s///>
138	operator) that modify C<$_> as resources:
139
140	URxvt.selection-autotransform.0: transform
141	URxvt.selection-autotransform.1: transform
142	...
143
144	For example, the following will transform selections of the form
145	C<filename:number>, often seen in compiler messages, into C<vi +$filename
146	$word>:
147
148	URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
149
150	And this example matches the same,but replaces it with vi-commands you can
151	paste directly into your (vi :) editor:
152
153	URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
154
155	Of course, this can be modified to suit your needs and your editor :)
156
157	To expand the example above to typical perl error messages ("XXX at
158	FILENAME line YYY."), you need a slightly more elaborate solution:
159
160	URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
161	URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
162
163	The first line tells the selection code to treat the unchanging part of
164	every error message as a selection pattern, and the second line transforms
165	the message into vi commands to load the file.
166
167	=item readline
168		140
169	A support package that tries to make editing with readline easier. At the	141	A support package that tries to make editing with readline easier. At the
170	moment, it reacts to clicking with the left mouse button by trying to	142	moment, it reacts to clicking with the left mouse button by trying to
171	move the text cursor to this position. It does so by generating as many	143	move the text cursor to this position. It does so by generating as many
172	cursor-left or cursor-right keypresses as required (the this only works	144	cursor-left or cursor-right keypresses as required (the this only works
173	for programs that correctly support wide characters).	145	for programs that correctly support wide characters).
174		146
175	It only works when clicking into the same line (possibly extended over	147	To avoid too many false positives, this is only done when:
176	multiple rows) as the text cursor and on the primary screen, to reduce the	148
177	risk of misinterpreting. The normal selection isn't disabled, so quick	149	=over 4
		150
		151	=item - the tty is in ICANON state.
		152
		153	=item - the text cursor is visible.
		154
		155	=item - the primary screen is currently being displayed.
		156
		157	=item - the mouse is on the same (multi-row-) line as the text cursor.
		158
		159	=back
		160
		161	The normal selection mechanism isn't disabled, so quick successive clicks
178	successive clicks might interfere with selection creation in harmless	162	might interfere with selection creation in harmless ways.
179	ways.	163
		164	=item selection-autotransform
		165
		166	This selection allows you to do automatic transforms on a selection
		167	whenever a selection is made.
		168
		169	It works by specifying perl snippets (most useful is a single C<s///>
		170	operator) that modify C<$_> as resources:
		171
		172	URxvt.selection-autotransform.0: transform
		173	URxvt.selection-autotransform.1: transform
		174	...
		175
		176	For example, the following will transform selections of the form
		177	C<filename:number>, often seen in compiler messages, into C<vi +$filename
		178	$word>:
		179
		180	URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
		181
		182	And this example matches the same,but replaces it with vi-commands you can
		183	paste directly into your (vi :) editor:
		184
		185	URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
		186
		187	Of course, this can be modified to suit your needs and your editor :)
		188
		189	To expand the example above to typical perl error messages ("XXX at
		190	FILENAME line YYY."), you need a slightly more elaborate solution:
		191
		192	URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
		193	URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
		194
		195	The first line tells the selection code to treat the unchanging part of
		196	every error message as a selection pattern, and the second line transforms
		197	the message into vi commands to load the file.
180		198
181	=item tabbed	199	=item tabbed
182		200
183	This transforms the terminal into a tabbar with additional terminals, that	201	This transforms the terminal into a tabbar with additional terminals, that
184	is, it implements what is commonly refered to as "tabbed terminal". The topmost line	202	is, it implements what is commonly refered to as "tabbed terminal". The topmost line
…		…
194	Uses per-line display filtering (C<on_line_update>) to underline urls and	212	Uses per-line display filtering (C<on_line_update>) to underline urls and
195	make them clickable. When middle-clicked, the program specified in the	213	make them clickable. When middle-clicked, the program specified in the
196	resource C<urlLauncher> (default C<x-www-browser>) will be started with	214	resource C<urlLauncher> (default C<x-www-browser>) will be started with
197	the URL as first argument.	215	the URL as first argument.
198		216
		217	=item xim-onthespot
		218
		219	This (experimental) perl extension implements OnTheSpot editing. It does
		220	not work perfectly, and some input methods don't seem to work well with
		221	OnTheSpot editing in general, but it seems to work at leats for SCIM and
		222	kinput2.
		223
		224	You enable it by specifying this extension and a preedit style of
		225	C<OnTheSpot>, i.e.:
		226
		227	@@RXVT_NAME@@ -pt OnTheSpot -pe xim-onthespot
		228
199	=item automove-background	229	=item automove-background
200		230
201	This is basically a one-line extension that dynamically changes the background pixmap offset	231	This is basically a one-line extension that dynamically changes the background pixmap offset
202	to the window position, in effect creating the same effect as pseudo transparency with	232	to the window position, in effect creating the same effect as pseudo transparency with
203	a custom pixmap. No scaling is supported in this mode. Exmaple:	233	a custom pixmap. No scaling is supported in this mode. Exmaple:
…		…
212		242
213	=item digital-clock	243	=item digital-clock
214		244
215	Displays a digital clock using the built-in overlay.	245	Displays a digital clock using the built-in overlay.
216		246
217	=item example-refresh-hooks	247	=item remote-clipboard
218		248
219	Displays a very simple digital clock in the upper right corner of the	249	Somewhat of a misnomer, this extension adds two menu entries to the
220	window. Illustrates overwriting the refresh callbacks to create your own	250	selection popup that allows one ti run external commands to store the
221	overlays or changes.	251	selection somewhere and fetch it again.
		252
		253	We use it to implement a "distributed selection mechanism", which just
		254	means that one command uploads the file to a remote server, and another
		255	reads it.
		256
		257	The commands can be set using the C<URxvt.remote-selection.store> and
		258	C<URxvt.remote-selection.fetch> resources. The first should read the
		259	selection to store from STDIN (always in UTF-8), the second should provide
		260	the selection data on STDOUT (also in UTF-8).
		261
		262	The defaults (which are likely useless to you) use rsh and cat:
		263
		264	URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
		265	URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
222		266
223	=item selection-pastebin	267	=item selection-pastebin
224		268
225	This is a little rarely useful extension that Uploads the selection as	269	This is a little rarely useful extension that Uploads the selection as
226	textfile to a remote site (or does other things). (The implementation is	270	textfile to a remote site (or does other things). (The implementation is
…		…
246	After a successful upload the selection will be replaced by the text given	290	After a successful upload the selection will be replaced by the text given
247	in the C<selection-pastebin-url> resource (again, the % is the placeholder	291	in the C<selection-pastebin-url> resource (again, the % is the placeholder
248	for the filename):	292	for the filename):
249		293
250	URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%	294	URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
		295
		296	=item example-refresh-hooks
		297
		298	Displays a very simple digital clock in the upper right corner of the
		299	window. Illustrates overwriting the refresh callbacks to create your own
		300	overlays or changes.
251		301
252	=back	302	=back
253		303
254	=head1 API DOCUMENTATION	304	=head1 API DOCUMENTATION
255		305
…		…
352	Called at the very end of initialisation of a new terminal, just before	402	Called at the very end of initialisation of a new terminal, just before
353	trying to map (display) the toplevel and returning to the mainloop.	403	trying to map (display) the toplevel and returning to the mainloop.
354		404
355	=item on_destroy $term	405	=item on_destroy $term
356		406
357	Called whenever something tries to destroy terminal, before doing anything	407	Called whenever something tries to destroy terminal, when the terminal is
358	yet. If this hook returns true, then destruction is skipped, but this is	408	still fully functional (not for long, though).
359	rarely a good idea.
360		409
361	=item on_reset $term	410	=item on_reset $term
362		411
363	Called after the screen is "reset" for any reason, such as resizing or	412	Called after the screen is "reset" for any reason, such as resizing or
364	control sequences. Here is where you can react on changes to size-related	413	control sequences. Here is where you can react on changes to size-related
…		…
466		515
467	=item on_refresh_end $term	516	=item on_refresh_end $term
468		517
469	Called just after the screen gets redrawn. See C<on_refresh_begin>.	518	Called just after the screen gets redrawn. See C<on_refresh_begin>.
470		519
471	=item on_keyboard_command $term, $string	520	=item on_user_command $term, $string
472		521
473	Called whenever the user presses a key combination that has a	522	Called whenever the a user-configured event is being activated (e.g. via
474	C<perl:string> action bound to it (see description of the B<keysym>	523	a C<perl:string> action bound to a key, see description of the B<keysym>
475	resource in the @@RXVT_NAME@@(1) manpage).	524	resource in the @@RXVT_NAME@@(1) manpage).
		525
		526	The event is simply the action string. This interface is assumed to change
		527	slightly in the future.
476		528
477	=item on_x_event $term, $event	529	=item on_x_event $term, $event
478		530
479	Called on every X event received on the vt window (and possibly other	531	Called on every X event received on the vt window (and possibly other
480	windows). Should only be used as a last resort. Most event structure	532	windows). Should only be used as a last resort. Most event structure
…		…
552	our $LIBDIR;	604	our $LIBDIR;
553	our $RESNAME;	605	our $RESNAME;
554	our $RESCLASS;	606	our $RESCLASS;
555	our $RXVTNAME;	607	our $RXVTNAME;
556		608
557	our $NOCHAR = chr 0xfffe;	609	our $NOCHAR = chr 0xffff;
558		610
559	=head2 Variables in the C<urxvt> Package	611	=head2 Variables in the C<urxvt> Package
560		612
561	=over 4	613	=over 4
562		614
…		…
614		666
615	Using this function has the advantage that its output ends up in the	667	Using this function has the advantage that its output ends up in the
616	correct place, e.g. on stderr of the connecting urxvtc client.	668	correct place, e.g. on stderr of the connecting urxvtc client.
617		669
618	Messages have a size limit of 1023 bytes currently.	670	Messages have a size limit of 1023 bytes currently.
		671
		672	=item @terms = urxvt::termlist
		673
		674	Returns all urxvt::term objects that exist in this process, regardless of
		675	wether they are started, being destroyed etc., so be careful. Only term
		676	objects that have perl extensions attached will be returned (because there
		677	is no urxvt::term objet associated with others).
619		678
620	=item $time = urxvt::NOW	679	=item $time = urxvt::NOW
621		680
622	Returns the "current time" (as per the event loop).	681	Returns the "current time" (as per the event loop).
623		682
…		…
709	unless $msg =~ /\n$/;	768	unless $msg =~ /\n$/;
710	urxvt::warn ($msg);	769	urxvt::warn ($msg);
711	};	770	};
712	}	771	}
713		772
		773	no warnings 'utf8';
		774
714	my $verbosity = $ENV{URXVT_PERL_VERBOSITY};	775	my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
715		776
716	sub verbose {	777	sub verbose {
717	my ($level, $msg) = @_;	778	my ($level, $msg) = @_;
718	warn "$msg\n" if $level <= $verbosity;	779	warn "$msg\n" if $level <= $verbosity;
…		…
734		795
735	open my $fh, "<:raw", $path	796	open my $fh, "<:raw", $path
736	or die "$path: $!";	797	or die "$path: $!";
737		798
738	my $source =	799	my $source =
739	"package $pkg; use strict; use utf8;\n"	800	"package $pkg; use strict; use utf8; no warnings 'utf8';\n"
740	. "#line 1 \"$path\"\n{\n"	801	. "#line 1 \"$path\"\n{\n"
741	. (do { local $/; <$fh> })	802	. (do { local $/; <$fh> })
742	. "\n};\n1";	803	. "\n};\n1";
743		804
744	eval $source	805	eval $source
…		…
769	$TERM->register_package ($_) for @pkg;	830	$TERM->register_package ($_) for @pkg;
770	}	831	}
771		832
772	for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {	833	for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
773	if ($_ eq "default") {	834	if ($_ eq "default") {
774	$ext_arg{$_} \|\|= [] for qw(selection option-popup selection-popup searchable-scrollback);	835	$ext_arg{$_} \|\|= [] for qw(selection option-popup selection-popup searchable-scrollback readline);
775	} elsif (/^-(.*)$/) {	836	} elsif (/^-(.*)$/) {
776	delete $ext_arg{$1};	837	delete $ext_arg{$1};
777	} elsif (/^([^<]+)<(.*)>$/) {	838	} elsif (/^([^<]+)<(.*)>$/) {
778	push @{ $ext_arg{$1} }, $2;	839	push @{ $ext_arg{$1} }, $2;
779	} else {	840	} else {
…		…
1002	hash which defines the environment of the new terminal.	1063	hash which defines the environment of the new terminal.
1003		1064
1004	Croaks (and probably outputs an error message) if the new instance	1065	Croaks (and probably outputs an error message) if the new instance
1005	couldn't be created. Returns C<undef> if the new instance didn't	1066	couldn't be created. Returns C<undef> if the new instance didn't
1006	initialise perl, and the terminal object otherwise. The C<init> and	1067	initialise perl, and the terminal object otherwise. The C<init> and
1007	C<start> hooks will be called during this call.	1068	C<start> hooks will be called before this call returns, and are free to
		1069	refer to global data (which is race free).
1008		1070
1009	=cut	1071	=cut
1010		1072
1011	sub new {	1073	sub new {
1012	my ($class, $env, @args) = @_;	1074	my ($class, $env, @args) = @_;
1013		1075
		1076	$env or Carp::croak "environment hash missing in call to urxvt::term->new";
		1077	@args or Carp::croak "name argument missing in call to urxvt::term->new";
		1078
1014	_new ([ map "$_=$env->{$_}", keys %$env ], @args);	1079	_new ([ map "$_=$env->{$_}", keys %$env ], \@args);
1015	}	1080	}
1016		1081
1017	=item $term->destroy	1082	=item $term->destroy
1018		1083
1019	Destroy the terminal object (close the window, free resources	1084	Destroy the terminal object (close the window, free resources
…		…
1299	Replaces the event mask of the pty watcher by the given event mask. Can	1364	Replaces the event mask of the pty watcher by the given event mask. Can
1300	be used to suppress input and output handling to the pty/tty. See the	1365	be used to suppress input and output handling to the pty/tty. See the
1301	description of C<< urxvt::timer->events >>. Make sure to always restore	1366	description of C<< urxvt::timer->events >>. Make sure to always restore
1302	the previous value.	1367	the previous value.
1303		1368
		1369	=item $fd = $term->pty_fd
		1370
		1371	Returns the master file descriptor for the pty in use, or C<-1> if no pty
		1372	is used.
		1373
1304	=item $windowid = $term->parent	1374	=item $windowid = $term->parent
1305		1375
1306	Return the window id of the toplevel window.	1376	Return the window id of the toplevel window.
1307		1377
1308	=item $windowid = $term->vt	1378	=item $windowid = $term->vt
…		…
1376		1446
1377	=item $screen = $term->current_screen	1447	=item $screen = $term->current_screen
1378		1448
1379	Returns the currently displayed screen (0 primary, 1 secondary).	1449	Returns the currently displayed screen (0 primary, 1 secondary).
1380		1450
		1451	=item $cursor_is_hidden = $term->hidden_cursor
		1452
		1453	Returns wether the cursor is currently hidden or not.
		1454
1381	=item $view_start = $term->view_start ([$newvalue])	1455	=item $view_start = $term->view_start ([$newvalue])
1382		1456
1383	Returns the row number of the topmost displayed line. Maximum value is	1457	Returns the row number of the topmost displayed line. Maximum value is
1384	C<0>, which displays the normal terminal contents. Lower values scroll	1458	C<0>, which displays the normal terminal contents. Lower values scroll
1385	this many lines into the scrollback buffer.	1459	this many lines into the scrollback buffer.
…		…
1403	If C<$new_text> is specified, it will replace characters in the current	1477	If C<$new_text> is specified, it will replace characters in the current
1404	line, starting at column C<$start_col> (default C<0>), which is useful	1478	line, starting at column C<$start_col> (default C<0>), which is useful
1405	to replace only parts of a line. The font index in the rendition will	1479	to replace only parts of a line. The font index in the rendition will
1406	automatically be updated.	1480	automatically be updated.
1407		1481
1408	C<$text> is in a special encoding: tabs and wide characters that use	1482	C<$text> is in a special encoding: tabs and wide characters that use more
1409	more than one cell when displayed are padded with C<$urxvt::NOCHAR>	1483	than one cell when displayed are padded with C<$urxvt::NOCHAR> (chr 65535)
1410	characters. Characters with combining characters and other characters that	1484	characters. Characters with combining characters and other characters that
1411	do not fit into the normal tetx encoding will be replaced with characters	1485	do not fit into the normal tetx encoding will be replaced with characters
1412	in the private use area.	1486	in the private use area.
1413		1487
1414	You have to obey this encoding when changing text. The advantage is	1488	You have to obey this encoding when changing text. The advantage is
…		…
1564	=item $string = $term->special_decode $text	1638	=item $string = $term->special_decode $text
1565		1639
1566	Converts rxvt-unicodes text reprsentation into a perl string. See	1640	Converts rxvt-unicodes text reprsentation into a perl string. See
1567	C<< $term->ROW_t >> for details.	1641	C<< $term->ROW_t >> for details.
1568		1642
1569	=item $success = $term->grab_button ($button, $modifiermask)	1643	=item $success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
1570		1644
		1645	=item $term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
		1646
1571	Registers a synchronous button grab. See the XGrabButton manpage.	1647	Register/unregister a synchronous button grab. See the XGrabButton
		1648	manpage.
1572		1649
1573	=item $success = $term->grab ($eventtime[, $sync])	1650	=item $success = $term->grab ($eventtime[, $sync])
1574		1651
1575	Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or	1652	Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1576	synchronous (C<$sync> is true). Also remembers the grab timestampe.	1653	synchronous (C<$sync> is true). Also remembers the grab timestampe.

Diff Legend

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

Comparing rxvt-unicode/src/urxvt.pm (file contents): Revision 1.121 by root, Fri Jan 20 22:49:34 2006 UTC vs. Revision 1.131 by root, Sun Jan 29 20:51:28 2006 UTC

Diff Legend

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.121 by root, Fri Jan 20 22:49:34 2006 UTC vs.
Revision 1.131 by root, Sun Jan 29 20:51:28 2006 UTC