ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/src/urxvt.pm
(Generate patch)

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.110 by root, Thu Jan 19 16:22:13 2006 UTC vs.
Revision 1.122 by root, Sat Jan 21 08:07:38 2006 UTC

34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35 35
36You can activate them like this: 36You can activate them like this:
37 37
38 @@RXVT_NAME@@ -pe <extensionname> 38 @@RXVT_NAME@@ -pe <extensionname>
39
40Or by adding them to the resource for extensions loaded by default:
41
42 URxvt.perl-ext-common: default,automove-background,selection-autotransform
39 43
40=over 4 44=over 4
41 45
42=item selection (enabled by default) 46=item selection (enabled by default)
43 47
87 91
88=item selection-popup (enabled by default) 92=item selection-popup (enabled by default)
89 93
90Binds a popup menu to Ctrl-Button3 that lets you convert the selection 94Binds a popup menu to Ctrl-Button3 that lets you convert the selection
91text into various other formats/action (such as uri unescaping, perl 95text into various other formats/action (such as uri unescaping, perl
92evalution, web-browser starting etc.), depending on content. 96evaluation, web-browser starting etc.), depending on content.
93 97
94Other extensions can extend this popup menu by pushing a code reference 98Other extensions can extend this popup menu by pushing a code reference
95onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the 99onto C<@{ $term->{selection_popup_hook} }>, that is called whenever the
96popup is displayed. 100popup is displayed.
97 101
158 162
159The first line tells the selection code to treat the unchanging part of 163The first line tells the selection code to treat the unchanging part of
160every error message as a selection pattern, and the second line transforms 164every error message as a selection pattern, and the second line transforms
161the message into vi commands to load the file. 165the message into vi commands to load the file.
162 166
167=item readline
168
169A support package that tries to make editing with readline easier. At the
170moment, it reacts to clicking with the left mouse button by trying to
171move the text cursor to this position. It does so by generating as many
172cursor-left or cursor-right keypresses as required (the this only works
173for programs that correctly support wide characters).
174
175To avoid too many false positives, this is only done when:
176
177=over 4
178
179=item - the mouse is on the same (multi-row-) line as the text cursor.
180
181=item - the primary screen is currently being displayed.
182
183=item - the text cursor is visible.
184
185=back
186
187The normal selection mechanism isn't disabled, so quick successive clicks
188might interfere with selection creation in harmless ways.
189
190=item tabbed
191
192This transforms the terminal into a tabbar with additional terminals, that
193is, it implements what is commonly refered to as "tabbed terminal". The topmost line
194displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one
195button per tab.
196
197Clicking a button will activate that tab. Pressing B<Shift-Left> and
198B<Shift-Right> will switch to the tab left or right of the current one,
199while B<Shift-Down> creates a new tab.
200
163=item mark-urls 201=item mark-urls
164 202
165Uses per-line display filtering (C<on_line_update>) to underline urls and 203Uses per-line display filtering (C<on_line_update>) to underline urls and
166make them clickable. When middle-clicked, the program specified in the 204make them clickable. When middle-clicked, the program specified in the
167resource C<urlLauncher> (default C<x-www-browser>) will be started with 205resource C<urlLauncher> (default C<x-www-browser>) will be started with
299called whenever the relevant event happens. 337called whenever the relevant event happens.
300 338
301The first argument passed to them is an extension oject as described in 339The first argument passed to them is an extension oject as described in
302the in the C<Extension Objects> section. 340the in the C<Extension Objects> section.
303 341
304B<All> of these hooks must return a boolean value. If it is true, then the 342B<All> of these hooks must return a boolean value. If any of the called
305event counts as being I<consumed>, and the invocation of other hooks is 343hooks returns true, then the event counts as being I<consumed>, and the
306skipped, and the relevant action might not be carried out by the C++ code. 344relevant action might not be carried out by the C++ code.
307 345
308I<< When in doubt, return a false value (preferably C<()>). >> 346I<< When in doubt, return a false value (preferably C<()>). >>
309 347
310=over 4 348=over 4
311 349
312=item on_init $term 350=item on_init $term
313 351
314Called after a new terminal object has been initialized, but before 352Called after a new terminal object has been initialized, but before
315windows are created or the command gets run. Most methods are unsafe to 353windows are created or the command gets run. Most methods are unsafe to
316call or deliver senseless data, as terminal size and other characteristics 354call or deliver senseless data, as terminal size and other characteristics
317have not yet been determined. You can safely query and change resources, 355have not yet been determined. You can safely query and change resources
318though. 356and options, though. For many purposes the C<on_start> hook is a better
357place.
358
359=item on_start $term
360
361Called at the very end of initialisation of a new terminal, just before
362trying to map (display) the toplevel and returning to the mainloop.
363
364=item on_destroy $term
365
366Called whenever something tries to destroy terminal, before doing anything
367yet. If this hook returns true, then destruction is skipped, but this is
368rarely a good idea.
319 369
320=item on_reset $term 370=item on_reset $term
321 371
322Called after the screen is "reset" for any reason, such as resizing or 372Called after the screen is "reset" for any reason, such as resizing or
323control sequences. Here is where you can react on changes to size-related 373control sequences. Here is where you can react on changes to size-related
324variables. 374variables.
325
326=item on_start $term
327
328Called at the very end of initialisation of a new terminal, just before
329returning to the mainloop.
330 375
331=item on_child_start $term, $pid 376=item on_child_start $term, $pid
332 377
333Called just after the child process has been C<fork>ed. 378Called just after the child process has been C<fork>ed.
334 379
454Called wheneever the window loses keyboard focus, before rxvt-unicode does 499Called wheneever the window loses keyboard focus, before rxvt-unicode does
455focus out processing. 500focus out processing.
456 501
457=item on_configure_notify $term, $event 502=item on_configure_notify $term, $event
458 503
504=item on_property_notify $term, $event
505
459=item on_key_press $term, $event, $keysym, $octets 506=item on_key_press $term, $event, $keysym, $octets
460 507
461=item on_key_release $term, $event, $keysym 508=item on_key_release $term, $event, $keysym
462 509
463=item on_button_press $term, $event 510=item on_button_press $term, $event
472 519
473Called whenever the corresponding X event is received for the terminal If 520Called whenever the corresponding X event is received for the terminal If
474the hook returns true, then the even will be ignored by rxvt-unicode. 521the hook returns true, then the even will be ignored by rxvt-unicode.
475 522
476The event is a hash with most values as named by Xlib (see the XEvent 523The event is a hash with most values as named by Xlib (see the XEvent
477manpage), with the additional members C<row> and C<col>, which are the row 524manpage), with the additional members C<row> and C<col>, which are the
478and column under the mouse cursor. 525(real, not screen-based) row and column under the mouse cursor.
479 526
480C<on_key_press> additionally receives the string rxvt-unicode would 527C<on_key_press> additionally receives the string rxvt-unicode would
481output, if any, in locale-specific encoding. 528output, if any, in locale-specific encoding.
482 529
483subwindow. 530subwindow.
531
532=item on_client_message $term, $event
533
534=item on_wm_protocols $term, $event
535
536=item on_wm_delete_window $term, $event
537
538Called when various types of ClientMessage events are received (all with
539format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).
484 540
485=back 541=back
486 542
487=cut 543=cut
488 544
494use Scalar::Util (); 550use Scalar::Util ();
495use List::Util (); 551use List::Util ();
496 552
497our $VERSION = 1; 553our $VERSION = 1;
498our $TERM; 554our $TERM;
555our @TERM_INIT;
556our @TERM_EXT;
499our @HOOKNAME; 557our @HOOKNAME;
500our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 558our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
501our %OPTION; 559our %OPTION;
502 560
503our $LIBDIR; 561our $LIBDIR;
504our $RESNAME; 562our $RESNAME;
505our $RESCLASS; 563our $RESCLASS;
506our $RXVTNAME; 564our $RXVTNAME;
507 565
566our $NOCHAR = chr 0xfffe;
567
508=head2 Variables in the C<urxvt> Package 568=head2 Variables in the C<urxvt> Package
509 569
510=over 4 570=over 4
511 571
512=item $urxvt::LIBDIR 572=item $urxvt::LIBDIR
524 584
525=item $urxvt::TERM 585=item $urxvt::TERM
526 586
527The current terminal. This variable stores the current C<urxvt::term> 587The current terminal. This variable stores the current C<urxvt::term>
528object, whenever a callback/hook is executing. 588object, whenever a callback/hook is executing.
589
590=item @urxvt::TERM_INIT
591
592All coderefs in this array will be called as methods of the next newly
593created C<urxvt::term> object (during the C<on_init> phase). The array
594gets cleared before the codereferences that were in it are being executed,
595so coderefs can push themselves onto it again if they so desire.
596
597This complements to the perl-eval commandline option, but gets executed
598first.
599
600=item @urxvt::TERM_EXT
601
602Works similar to C<@TERM_INIT>, but contains perl package/class names, which
603get registered as normal extensions after calling the hooks in C<@TERM_INIT>
604but before other extensions. Gets cleared just like C<@TERM_INIT>.
529 605
530=back 606=back
531 607
532=head2 Functions in the C<urxvt> Package 608=head2 Functions in the C<urxvt> Package
533 609
655 731
656# load a single script into its own package, once only 732# load a single script into its own package, once only
657sub extension_package($) { 733sub extension_package($) {
658 my ($path) = @_; 734 my ($path) = @_;
659 735
660 no strict 'refs';
661
662 $extension_pkg{$path} ||= do { 736 $extension_pkg{$path} ||= do {
663 $path =~ /([^\/\\]+)$/; 737 $path =~ /([^\/\\]+)$/;
664 my $pkg = $1; 738 my $pkg = $1;
665 $pkg =~ s/[^[:word:]]/_/g; 739 $pkg =~ s/[^[:word:]]/_/g;
666 $pkg = "urxvt::ext::$pkg"; 740 $pkg = "urxvt::ext::$pkg";
668 verbose 3, "loading extension '$path' into package '$pkg'"; 742 verbose 3, "loading extension '$path' into package '$pkg'";
669 743
670 open my $fh, "<:raw", $path 744 open my $fh, "<:raw", $path
671 or die "$path: $!"; 745 or die "$path: $!";
672 746
673 @{"$pkg\::ISA"} = urxvt::term::extension::;
674
675 my $source = 747 my $source =
676 "package $pkg; use strict; use utf8;\n" 748 "package $pkg; use strict; use utf8;\n"
677 . "#line 1 \"$path\"\n{\n" 749 . "#line 1 \"$path\"\n{\n"
678 . (do { local $/; <$fh> }) 750 . (do { local $/; <$fh> })
679 . "\n};\n1"; 751 . "\n};\n1";
695 if ($htype == 0) { # INIT 767 if ($htype == 0) { # INIT
696 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 768 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
697 769
698 my %ext_arg; 770 my %ext_arg;
699 771
772 {
773 my @init = @TERM_INIT;
774 @TERM_INIT = ();
775 $_->($TERM) for @init;
776 my @pkg = @TERM_EXT;
777 @TERM_EXT = ();
778 $TERM->register_package ($_) for @pkg;
779 }
780
700 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) { 781 for (grep $_, map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
701 if ($_ eq "default") { 782 if ($_ eq "default") {
702 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback); 783 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback);
703 } elsif (/^-(.*)$/) { 784 } elsif (/^-(.*)$/) {
704 delete $ext_arg{$1}; 785 delete $ext_arg{$1};
705 } elsif (/^([^<]+)<(.*)>$/) { 786 } elsif (/^([^<]+)<(.*)>$/) {
730 if $verbosity >= 10; 811 if $verbosity >= 10;
731 812
732 keys %$cb; 813 keys %$cb;
733 814
734 while (my ($pkg, $cb) = each %$cb) { 815 while (my ($pkg, $cb) = each %$cb) {
735 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) } 816 my $retval_ = eval { $cb->($TERM->{_pkg}{$pkg}, @_) };
736 and last; 817 $retval ||= $retval_;
737 818
738 if ($@) { 819 if ($@) {
739 $TERM->ungrab; # better to lose the grab than the session 820 $TERM->ungrab; # better to lose the grab than the session
740 warn $@; 821 warn $@;
741 } 822 }
899 980
900# find on_xxx subs in the package and register them 981# find on_xxx subs in the package and register them
901# as hooks 982# as hooks
902sub register_package { 983sub register_package {
903 my ($self, $pkg, $argv) = @_; 984 my ($self, $pkg, $argv) = @_;
985
986 no strict 'refs';
987
988 urxvt::verbose 6, "register package $pkg to $self";
989
990 @{"$pkg\::ISA"} = urxvt::term::extension::;
904 991
905 my $proxy = bless { 992 my $proxy = bless {
906 _pkg => $pkg, 993 _pkg => $pkg,
907 argv => $argv, 994 argv => $argv,
908 }, $pkg; 995 }, $pkg;
1198 1285
1199Normally its not a good idea to use this function, as programs might be 1286Normally its not a good idea to use this function, as programs might be
1200confused by changes in cursor position or scrolling. Its useful inside a 1287confused by changes in cursor position or scrolling. Its useful inside a
1201C<on_add_lines> hook, though. 1288C<on_add_lines> hook, though.
1202 1289
1290=item $term->scr_change_screen ($screen)
1291
1292Switch to given screen - 0 primary, 1 secondary.
1293
1203=item $term->cmd_parse ($octets) 1294=item $term->cmd_parse ($octets)
1204 1295
1205Similar to C<scr_add_lines>, but the argument must be in the 1296Similar to C<scr_add_lines>, but the argument must be in the
1206locale-specific encoding of the terminal and can contain command sequences 1297locale-specific encoding of the terminal and can contain command sequences
1207(escape codes) that will be interpreted. 1298(escape codes) that will be interpreted.
1290=item $modifiermask = $term->ModNumLockMask 1381=item $modifiermask = $term->ModNumLockMask
1291 1382
1292Return the modifier masks corresponding to the "ISO Level 3 Shift" (often 1383Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1293AltGr), the meta key (often Alt) and the num lock key, if applicable. 1384AltGr), the meta key (often Alt) and the num lock key, if applicable.
1294 1385
1386=item $screen = $term->current_screen
1387
1388Returns the currently displayed screen (0 primary, 1 secondary).
1389
1390=item $cursor_is_hidden = $term->hidden_cursor
1391
1392Returns wether the cursor is currently hidden or not.
1393
1295=item $view_start = $term->view_start ([$newvalue]) 1394=item $view_start = $term->view_start ([$newvalue])
1296 1395
1297Returns the row number of the topmost displayed line. Maximum value is 1396Returns the row number of the topmost displayed line. Maximum value is
1298C<0>, which displays the normal terminal contents. Lower values scroll 1397C<0>, which displays the normal terminal contents. Lower values scroll
1299this many lines into the scrollback buffer. 1398this many lines into the scrollback buffer.
1317If C<$new_text> is specified, it will replace characters in the current 1416If C<$new_text> is specified, it will replace characters in the current
1318line, starting at column C<$start_col> (default C<0>), which is useful 1417line, starting at column C<$start_col> (default C<0>), which is useful
1319to replace only parts of a line. The font index in the rendition will 1418to replace only parts of a line. The font index in the rendition will
1320automatically be updated. 1419automatically be updated.
1321 1420
1322C<$text> is in a special encoding: tabs and wide characters that use more 1421C<$text> is in a special encoding: tabs and wide characters that use
1323than one cell when displayed are padded with urxvt::NOCHAR characters 1422more than one cell when displayed are padded with C<$urxvt::NOCHAR>
1324(C<chr 65535>). Characters with combining characters and other characters 1423characters. Characters with combining characters and other characters that
1325that do not fit into the normal tetx encoding will be replaced with 1424do not fit into the normal tetx encoding will be replaced with characters
1326characters in the private use area. 1425in the private use area.
1327 1426
1328You have to obey this encoding when changing text. The advantage is 1427You have to obey this encoding when changing text. The advantage is
1329that C<substr> and similar functions work on screen cells and not on 1428that C<substr> and similar functions work on screen cells and not on
1330characters. 1429characters.
1331 1430
1505=item $term->ungrab 1604=item $term->ungrab
1506 1605
1507Calls XUngrab for the most recent grab. Is called automatically on 1606Calls XUngrab for the most recent grab. Is called automatically on
1508evaluation errors, as it is better to lose the grab in the error case as 1607evaluation errors, as it is better to lose the grab in the error case as
1509the session. 1608the session.
1609
1610=item $atom = $term->XInternAtom ($atom_name[, $only_if_exists])
1611
1612=item $atom_name = $term->XGetAtomName ($atom)
1613
1614=item @atoms = $term->XListProperties ($window)
1615
1616=item ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
1617
1618=item $term->XChangeWindowProperty ($window, $property, $type, $format, $octets)
1619
1620=item $term->XDeleteProperty ($window, $property)
1621
1622=item $window = $term->DefaultRootWindow
1623
1624=item $term->XReparentWindow ($window, $parent, [$x, $y])
1625
1626=item $term->XMapWindow ($window)
1627
1628=item $term->XUnmapWindow ($window)
1629
1630=item $term->XMoveResizeWindow ($window, $x, $y, $width, $height)
1631
1632=item ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
1633
1634=item $term->XChangeInput ($window, $add_events[, $del_events])
1635
1636Various X or X-related functions. The C<$term> object only serves as
1637the source of the display, otherwise those functions map more-or-less
1638directory onto the X functions of the same name.
1510 1639
1511=back 1640=back
1512 1641
1513=cut 1642=cut
1514 1643
1634 delete $self->{term}{_destroy}{$self}; 1763 delete $self->{term}{_destroy}{$self};
1635 $self->{term}->ungrab; 1764 $self->{term}->ungrab;
1636} 1765}
1637 1766
1638=back 1767=back
1768
1769=cut
1770
1771package urxvt::watcher;
1772
1773@urxvt::timer::ISA = __PACKAGE__;
1774@urxvt::iow::ISA = __PACKAGE__;
1775@urxvt::pw::ISA = __PACKAGE__;
1776@urxvt::iw::ISA = __PACKAGE__;
1639 1777
1640=head2 The C<urxvt::timer> Class 1778=head2 The C<urxvt::timer> Class
1641 1779
1642This class implements timer watchers/events. Time is represented as a 1780This class implements timer watchers/events. Time is represented as a
1643fractional number of seconds since the epoch. Example: 1781fractional number of seconds since the epoch. Example:
1741 1879
1742Stop watching for events on the given filehandle. 1880Stop watching for events on the given filehandle.
1743 1881
1744=back 1882=back
1745 1883
1884=head2 The C<urxvt::iw> Class
1885
1886This class implements idle watchers, that get called automatically when
1887the process is idle. They should return as fast as possible, after doing
1888some useful work.
1889
1890=over 4
1891
1892=item $iw = new urxvt::iw
1893
1894Create a new idle watcher object in stopped state.
1895
1896=item $iw = $iw->cb (sub { my ($iw) = @_; ... })
1897
1898Set the callback to be called when the watcher triggers.
1899
1900=item $timer = $timer->start
1901
1902Start the watcher.
1903
1904=item $timer = $timer->stop
1905
1906Stop the watcher.
1907
1908=back
1909
1910=head2 The C<urxvt::pw> Class
1911
1912This class implements process watchers. They create an event whenever a
1913process exits, after which they stop automatically.
1914
1915 my $pid = fork;
1916 ...
1917 $term->{pw} = urxvt::pw
1918 ->new
1919 ->start ($pid)
1920 ->cb (sub {
1921 my ($pw, $exit_status) = @_;
1922 ...
1923 });
1924
1925=over 4
1926
1927=item $pw = new urxvt::pw
1928
1929Create a new process watcher in stopped state.
1930
1931=item $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
1932
1933Set the callback to be called when the timer triggers.
1934
1935=item $pw = $timer->start ($pid)
1936
1937Tells the wqtcher to start watching for process C<$pid>.
1938
1939=item $pw = $pw->stop
1940
1941Stop the watcher.
1942
1943=back
1944
1746=head1 ENVIRONMENT 1945=head1 ENVIRONMENT
1747 1946
1748=head2 URXVT_PERL_VERBOSITY 1947=head2 URXVT_PERL_VERBOSITY
1749 1948
1750This variable controls the verbosity level of the perl extension. Higher 1949This variable controls the verbosity level of the perl extension. Higher

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines