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.38 by root, Fri Jan 6 03:43:12 2006 UTC vs.
Revision 1.54 by root, Sun Jan 8 01:59:29 2006 UTC

17 17
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test 18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
19 19
20=head1 DESCRIPTION 20=head1 DESCRIPTION
21 21
22Everytime a terminal object gets created, scripts specified via the 22Everytime a terminal object gets created, extension scripts specified via
23C<perl> resource are loaded and associated with it. 23the C<perl> resource are loaded and associated with it.
24 24
25Scripts are compiled in a 'use strict' and 'use utf8' environment, and 25Scripts are compiled in a 'use strict' and 'use utf8' environment, and
26thus must be encoded as UTF-8. 26thus must be encoded as UTF-8.
27 27
28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where 28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
37 37
38 @@RXVT_NAME@@ -pe <extensionname> 38 @@RXVT_NAME@@ -pe <extensionname>
39 39
40=over 4 40=over 4
41 41
42=item selection 42=item selection (enabled by default)
43 43
44Intelligent selection. This extension tries to be more intelligent when 44Intelligent selection. This extension tries to be more intelligent when
45the user extends selections (double-click). Right now, it tries to select 45the user extends selections (double-click). Right now, it tries to select
46urls and complete shell-quoted arguments, which is very convenient, too, 46urls and complete shell-quoted arguments, which is very convenient, too,
47if your F<ls> supports C<--quoting-style=shell>. 47if your F<ls> supports C<--quoting-style=shell>.
56 56
57 URxvt.keysym.C-M-r: perl:selection:rot13 57 URxvt.keysym.C-M-r: perl:selection:rot13
58 58
59=back 59=back
60 60
61=item option-popup (enabled by default)
62
63Binds a popup menu to Ctrl-Button3 that lets you toggle (some) options at
64runtime.
65
61=item digital-clock 66=item digital-clock
62 67
63Displays a digital clock using the built-in overlay. 68Displays a digital clock using the built-in overlay.
64 69
65=item mark-urls 70=item mark-urls
66 71
67Uses per-line filtering (C<on_line_update>) to underline urls. 72Uses per-line display filtering (C<on_line_update>) to underline urls.
73
74=item block-graphics-to-ascii
75
76A not very useful example of filtering all text output to the terminal,
77by replacing all line-drawing characters (U+2500 .. U+259F) by a
78similar-looking ascii character.
68 79
69=item example-refresh-hooks 80=item example-refresh-hooks
70 81
71Displays a very simple digital clock in the upper right corner of the 82Displays a very simple digital clock in the upper right corner of the
72window. Illustrates overwriting the refresh callbacks to create your own 83window. Illustrates overwriting the refresh callbacks to create your own
73overlays or changes. 84overlays or changes.
74
75=item example-filter-input
76
77A not very useful example of filtering all text output to the terminal, by
78underlining all urls that matches a certain regex (i.e. some urls :). It
79is not very useful because urls that are output in multiple steps (e.g.
80when typing them) do not get marked.
81 85
82=back 86=back
83 87
84=head2 General API Considerations 88=head2 General API Considerations
85 89
117 121
118=back 122=back
119 123
120=head2 Hooks 124=head2 Hooks
121 125
122The following subroutines can be declared in loaded scripts, and will be 126The following subroutines can be declared in extension files, and will be
123called whenever the relevant event happens. 127called whenever the relevant event happens.
124 128
125The first argument passed to them is an object private to each terminal 129The first argument passed to them is an object private to each terminal
126and extension package. You can call all C<urxvt::term> methods on it, but 130and extension package. You can call all C<urxvt::term> methods on it, but
127its not a real C<urxvt::term> object. Instead, the real C<urxvt::term> 131its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
128object that is shared between all packages is stored in the C<term> 132object that is shared between all packages is stored in the C<term>
129member. 133member. It is, however, blessed intot he package of the extension script,
134so for all practical purposes you can treat an extension script as a class.
130 135
131All of them must return a boolean value. If it is true, then the event 136All of them must return a boolean value. If it is true, then the event
132counts as being I<consumed>, and the invocation of other hooks is skipped, 137counts as being I<consumed>, and the invocation of other hooks is skipped,
133and the relevant action might not be carried out by the C++ code. 138and the relevant action might not be carried out by the C++ code.
134 139
178click) and is either supposed to return false (normal operation), or 183click) and is either supposed to return false (normal operation), or
179should extend the selection itelf and return true to suppress the built-in 184should extend the selection itelf and return true to suppress the built-in
180processing. 185processing.
181 186
182See the F<selection> example extension. 187See the F<selection> example extension.
183
184=item on_focus_in $term
185
186Called whenever the window gets the keyboard focus, before urxvt does
187focus in processing.
188
189=item on_focus_out $term
190
191Called wheneever the window loses keyboard focus, before urxvt does focus
192out processing.
193 188
194=item on_view_change $term, $offset 189=item on_view_change $term, $offset
195 190
196Called whenever the view offset changes, i..e the user or program 191Called whenever the view offset changes, i..e the user or program
197scrolls. Offset C<0> means display the normal terminal, positive values 192scrolls. Offset C<0> means display the normal terminal, positive values
261 256
262Called whenever the user presses a key combination that has a 257Called whenever the user presses a key combination that has a
263C<perl:string> action bound to it (see description of the B<keysym> 258C<perl:string> action bound to it (see description of the B<keysym>
264resource in the @@RXVT_NAME@@(1) manpage). 259resource in the @@RXVT_NAME@@(1) manpage).
265 260
261=item on_focus_in $term
262
263Called whenever the window gets the keyboard focus, before rxvt-unicode
264does focus in processing.
265
266=item on_focus_out $term
267
268Called wheneever the window loses keyboard focus, before rxvt-unicode does
269focus out processing.
270
266=item on_key_press $term, $event, $octets 271=item on_key_press $term, $event, $octets
267 272
268=item on_key_release $term, $event 273=item on_key_release $term, $event
269 274
270=item on_button_press $term, $event 275=item on_button_press $term, $event
271 276
272=item on_button_release $term, $event 277=item on_button_release $term, $event
273 278
274=item on_motion_notify $term, $event 279=item on_motion_notify $term, $event
275 280
281=item on_map_notify $term, $event
282
283=item on_unmap_notify $term, $event
284
276Called whenever the corresponding X event is received for the terminal 285Called whenever the corresponding X event is received for the terminal If
277(see the XEvent manpage) If the hook returns true, then the even will be 286the hook returns true, then the even will be ignored by rxvt-unicode.
278ignored by rxvt-unicode. 287
288The event is a hash with most values as named by Xlib (see the XEvent
289manpage), with the additional members C<row> and C<col>, which are the row
290and column under the mouse cursor.
279 291
280C<on_key_press> additionally receives the string rxvt-unicode would 292C<on_key_press> additionally receives the string rxvt-unicode would
281output, if any, in locale-specific encoding. 293output, if any, in locale-specific encoding.
282 294
283subwindow. 295subwindow.
288 300
289=over 4 301=over 4
290 302
291=item $urxvt::TERM 303=item $urxvt::TERM
292 304
293The current terminal. Whenever a callback/Hook is bein executed, this 305The current terminal. This variable stores the current C<urxvt::term>
294variable stores the current C<urxvt::term> object. 306object, whenever a callback/hook is executing.
295 307
296=back 308=back
297 309
298=head2 Functions in the C<urxvt> Package 310=head2 Functions in the C<urxvt> Package
299 311
324 336
325=item $time = urxvt::NOW 337=item $time = urxvt::NOW
326 338
327Returns the "current time" (as per the event loop). 339Returns the "current time" (as per the event loop).
328 340
341=item urxvt::CurrentTime
342
343=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
344Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
345Button4Mask, Button5Mask, AnyModifier
346
347Various constants for use in X events.
348
329=back 349=back
330 350
331=head2 RENDITION 351=head2 RENDITION
332 352
333Rendition bitsets contain information about colour, font, font styles and 353Rendition bitsets contain information about colour, font, font styles and
382 402
383=cut 403=cut
384 404
385package urxvt; 405package urxvt;
386 406
407use utf8;
387use strict; 408use strict;
388use Scalar::Util (); 409use Scalar::Util ();
410use List::Util ();
389 411
390our $TERM; 412our $TERM;
391our @HOOKNAME; 413our @HOOKNAME;
414our %OPTION;
392our $LIBDIR; 415our $LIBDIR;
393 416
394BEGIN { 417BEGIN {
395 urxvt->bootstrap; 418 urxvt->bootstrap;
396 419
426 $hook_count[$htype]++ 449 $hook_count[$htype]++
427 or set_should_invoke $htype, 1; 450 or set_should_invoke $htype, 1;
428 } 451 }
429} 452}
430 453
431my $script_pkg = "script0000"; 454my $extension_pkg = "extension0000";
432my %script_pkg; 455my %extension_pkg;
433 456
434# load a single script into its own package, once only 457# load a single script into its own package, once only
435sub script_package($) { 458sub extension_package($) {
436 my ($path) = @_; 459 my ($path) = @_;
437 460
438 $script_pkg{$path} ||= do { 461 $extension_pkg{$path} ||= do {
439 my $pkg = "urxvt::" . ($script_pkg++); 462 my $pkg = "urxvt::" . ($extension_pkg++);
440 463
441 verbose 3, "loading script '$path' into package '$pkg'"; 464 verbose 3, "loading extension '$path' into package '$pkg'";
442 465
443 open my $fh, "<:raw", $path 466 open my $fh, "<:raw", $path
444 or die "$path: $!"; 467 or die "$path: $!";
445 468
446 my $source = "package $pkg; use strict; use utf8;\n" 469 my $source = "package $pkg; use strict; use utf8;\n"
470 . "use base urxvt::term::proxy::;\n"
447 . "#line 1 \"$path\"\n{\n" 471 . "#line 1 \"$path\"\n{\n"
448 . (do { local $/; <$fh> }) 472 . (do { local $/; <$fh> })
449 . "\n};\n1"; 473 . "\n};\n1";
450 474
451 eval $source or die "$path: $@"; 475 eval $source or die "$path: $@";
461 local $TERM = shift; 485 local $TERM = shift;
462 my $htype = shift; 486 my $htype = shift;
463 487
464 if ($htype == 0) { # INIT 488 if ($htype == 0) { # INIT
465 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 489 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
490
491 my %want_ext;
466 492
467 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) { 493 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
494 if ($_ eq "default") {
495 $want_ext{$_}++ for qw(selection option-popup);
496 } elsif (/^-(.*)$/) {
497 delete $want_ext{$1};
498 } else {
499 $want_ext{$_}++;
500 }
501 }
502
503 for my $ext (keys %want_ext) {
468 my @files = grep -f $_, map "$_/$ext", @dirs; 504 my @files = grep -f $_, map "$_/$ext", @dirs;
469 505
470 if (@files) { 506 if (@files) {
471 register_package script_package $files[0]; 507 register_package extension_package $files[0];
472 } else { 508 } else {
473 warn "perl extension '$ext' not found in perl library search path\n"; 509 warn "perl extension '$ext' not found in perl library search path\n";
474 } 510 }
475 } 511 }
476 } 512 }
482 if $verbosity >= 10; 518 if $verbosity >= 10;
483 519
484 keys %$cb; 520 keys %$cb;
485 521
486 while (my ($pkg, $cb) = each %$cb) { 522 while (my ($pkg, $cb) = each %$cb) {
523 eval {
487 $retval = $cb->( 524 $retval = $cb->(
488 $TERM->{_pkg}{$pkg} ||= do { 525 $TERM->{_pkg}{$pkg} ||= do {
489 my $proxy = bless { }, urxvt::term::proxy::; 526 my $proxy = bless { }, $pkg;
490 Scalar::Util::weaken ($proxy->{term} = $TERM); 527 Scalar::Util::weaken ($proxy->{term} = $TERM);
491 $proxy 528 $proxy
492 }, 529 },
493 @_, 530 @_,
494 ) and last; 531 ) and last;
532 };
533 warn $@ if $@;#d#
495 } 534 }
496 } 535 }
497 536
498 if ($htype == 1) { # DESTROY 537 if ($htype == 1) { # DESTROY
499 # remove hooks if unused 538 # remove hooks if unused
527 } or die "FATAL: unable to compile method forwarder: $@"; 566 } or die "FATAL: unable to compile method forwarder: $@";
528 567
529 goto &$urxvt::term::proxy::AUTOLOAD; 568 goto &$urxvt::term::proxy::AUTOLOAD;
530} 569}
531 570
571sub urxvt::destroy_hook::DESTROY {
572 ${$_[0]}->();
573}
574
575sub urxvt::destroy_hook(&) {
576 bless \shift, urxvt::destroy_hook::
577}
578
532=head2 The C<urxvt::term> Class 579=head2 The C<urxvt::term> Class
533 580
534=over 4 581=over 4
535 582
536=item $term->destroy 583=item $term->destroy
537 584
538Destroy the terminal object (close the window, free resources etc.). 585Destroy the terminal object (close the window, free resources etc.).
586
587=item $isset = $term->option ($optval[, $set])
588
589Returns true if the option specified by C<$optval> is enabled, and
590optionally change it. All option values are stored by name in the hash
591C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
592
593Here is a a likely non-exhaustive list of option names, please see the
594source file F</src/optinc.h> to see the actual list:
595
596 borderLess console cursorBlink cursorUnderline hold iconic insecure
597 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
598 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
599 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
600 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
601 tripleclickwords utmpInhibit visualBell
539 602
540=item $value = $term->resource ($name[, $newval]) 603=item $value = $term->resource ($name[, $newval])
541 604
542Returns the current resource value associated with a given name and 605Returns the current resource value associated with a given name and
543optionally sets a new value. Setting values is most useful in the C<init> 606optionally sets a new value. Setting values is most useful in the C<init>
553 616
554Please note that resource strings will currently only be freed when the 617Please note that resource strings will currently only be freed when the
555terminal is destroyed, so changing options frequently will eat memory. 618terminal is destroyed, so changing options frequently will eat memory.
556 619
557Here is a a likely non-exhaustive list of resource names, not all of which 620Here is a a likely non-exhaustive list of resource names, not all of which
558are supported in every build, please see the source to see the actual 621are supported in every build, please see the source file F</src/rsinc.h>
559list: 622to see the actual list:
560 623
561 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 624 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
562 borderLess color cursorBlink cursorUnderline cutchars delete_key 625 borderLess color cursorBlink cursorUnderline cutchars delete_key
563 display_name embed ext_bwidth fade font geometry hold iconName 626 display_name embed ext_bwidth fade font geometry hold iconName
564 imFont imLocale inputMethod insecure int_bwidth intensityStyles 627 imFont imLocale inputMethod insecure int_bwidth intensityStyles
574=cut 637=cut
575 638
576sub urxvt::term::resource($$;$) { 639sub urxvt::term::resource($$;$) {
577 my ($self, $name) = (shift, shift); 640 my ($self, $name) = (shift, shift);
578 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 641 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
579 goto &urxvt::term::_resource; 642 &urxvt::term::_resource
580} 643}
581 644
582=item $rend = $term->rstyle ([$new_rstyle]) 645=item $rend = $term->rstyle ([$new_rstyle])
583 646
584Return and optionally change the current rendition. Text that is output by 647Return and optionally change the current rendition. Text that is output by
660 723
661If hidden, display the overlay again. 724If hidden, display the overlay again.
662 725
663=back 726=back
664 727
728=item $popup = $term->popup ($event)
729
730Creates a new C<urxvt::popup> object that implements a popup menu. The
731C<$event> I<must> be the event causing the menu to pop up (a button event,
732currently).
733
734=cut
735
736sub urxvt::term::popup {
737 my ($self, $event) = @_;
738
739 $self->grab ($event->{time}, 1)
740 or return;
741
742 my $popup = bless {
743 term => $self,
744 event => $event,
745 }, urxvt::popup::;
746
747 Scalar::Util::weaken $popup->{term};
748
749 $self->{_destroy}{$popup} = urxvt::destroy_hook { $popup->{popup}->destroy };
750 Scalar::Util::weaken $self->{_destroy}{$popup};
751
752 $popup
753}
754
665=item $cellwidth = $term->strwidth $string 755=item $cellwidth = $term->strwidth ($string)
666 756
667Returns the number of screen-cells this string would need. Correctly 757Returns the number of screen-cells this string would need. Correctly
668accounts for wide and combining characters. 758accounts for wide and combining characters.
669 759
670=item $octets = $term->locale_encode $string 760=item $octets = $term->locale_encode ($string)
671 761
672Convert the given text string into the corresponding locale encoding. 762Convert the given text string into the corresponding locale encoding.
673 763
674=item $string = $term->locale_decode $octets 764=item $string = $term->locale_decode ($octets)
675 765
676Convert the given locale-encoded octets into a perl string. 766Convert the given locale-encoded octets into a perl string.
677 767
678=item $term->scr_add_lines ($string) 768=item $term->scr_add_lines ($string)
679 769
696 786
697Write the octets given in C<$data> to the tty (i.e. as program input). To 787Write the octets given in C<$data> to the tty (i.e. as program input). To
698pass characters instead of octets, you should convert your strings first 788pass characters instead of octets, you should convert your strings first
699to the locale-specific encoding using C<< $term->locale_encode >>. 789to the locale-specific encoding using C<< $term->locale_encode >>.
700 790
791=item $windowid = $term->parent
792
793Return the window id of the toplevel window.
794
795=item $windowid = $term->vt
796
797Return the window id of the terminal window.
798
701=item $window_width = $term->width 799=item $window_width = $term->width
702 800
703=item $window_height = $term->height 801=item $window_height = $term->height
704 802
705=item $font_width = $term->fwidth 803=item $font_width = $term->fwidth
721=item $nrow_plus_saveLines = $term->total_rows 819=item $nrow_plus_saveLines = $term->total_rows
722 820
723=item $lines_in_scrollback = $term->nsaved 821=item $lines_in_scrollback = $term->nsaved
724 822
725Return various integers describing terminal characteristics. 823Return various integers describing terminal characteristics.
824
825=item $modifiermask = $term->ModLevel3Mask
826
827=item $modifiermask = $term->ModMetaMask
828
829=item $modifiermask = $term->ModNumLockMask
830
831Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
832AltGr), the meta key (often Alt) and the num lock key, if applicable.
726 833
727=item $view_start = $term->view_start ([$newvalue]) 834=item $view_start = $term->view_start ([$newvalue])
728 835
729Returns the negative row number of the topmost line. Minimum value is 836Returns the negative row number of the topmost line. Minimum value is
730C<0>, which displays the normal terminal contents. Larger values scroll 837C<0>, which displays the normal terminal contents. Larger values scroll
911 1018
912Converts rxvt-unicodes text reprsentation into a perl string. See 1019Converts rxvt-unicodes text reprsentation into a perl string. See
913C<< $term->ROW_t >> for details. 1020C<< $term->ROW_t >> for details.
914 1021
915=back 1022=back
1023
1024=head2 The C<urxvt::popup> Class
1025
1026=over 4
1027
1028=cut
1029
1030package urxvt::popup;
1031
1032sub add_item {
1033 my ($self, $item) = @_;
1034
1035 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1036 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1037 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1038
1039 $item->{render} ||= sub { $_[0]{text} };
1040
1041 push @{ $self->{item} }, $item;
1042}
1043
1044sub add_separator {
1045 my ($self, $sep) = @_;
1046
1047 $sep ||= "═";
1048
1049 $self->add_item ({
1050 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1051 text => "",
1052 render => sub { $sep x $urxvt::TERM->ncol },
1053 activate => sub { },
1054 });
1055}
1056
1057sub add_title {
1058 my ($self, $title) = @_;
1059
1060 $self->add_item ({
1061 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1062 text => $title,
1063 activate => sub { },
1064 });
1065}
1066
1067sub add_button {
1068 my ($self, $text, $cb) = @_;
1069
1070 $self->add_item ({ type => "button", text => "[ $text ]", activate => $cb});
1071}
1072
1073sub add_toggle {
1074 my ($self, $text, $cb, $value) = @_;
1075
1076 my $item; $item = {
1077 type => "button",
1078 text => " $text",
1079 value => $value,
1080 render => sub { ($item->{value} ? "* " : " ") . $text },
1081 activate => sub { $cb->($item->{value} = !$item->{value}); },
1082 };
1083
1084 $self->add_item ($item);
1085}
1086
1087sub show {
1088 my ($self) = @_;
1089
1090 local $urxvt::popup::self = $self;
1091
1092 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1093 "--transient-for" => $self->{term}->parent,
1094 "-pe" => "urxvt-popup")
1095 or die "unable to create popup window\n";
1096}
1097
1098sub DESTROY {
1099 my ($self) = @_;
1100
1101 $self->{term}->ungrab;
1102}
916 1103
917=head2 The C<urxvt::timer> Class 1104=head2 The C<urxvt::timer> Class
918 1105
919This class implements timer watchers/events. Time is represented as a 1106This class implements timer watchers/events. Time is represented as a
920fractional number of seconds since the epoch. Example: 1107fractional number of seconds since the epoch. Example:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines