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.36 by root, Fri Jan 6 02:58:02 2006 UTC vs.
Revision 1.70 by root, Mon Jan 9 23:00:07 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-Button2 that lets you toggle (some) options at
64runtime.
65
66=item selection-popup (enabled by default)
67
68Binds a popup menu to Ctrl-Button3 that lets you convert the selection
69text into various other formats/action.
70
71=item searchable-scrollback (enabled by default)
72
73Adds regex search functionality to the scrollback buffer, triggered by a
74hotkey (default: C<M-s>). When in search mode, terminal input/output is
75suspended, C</> starts an incremental regex search, C<n> searches further,
76C<p> jumps to the previous match. C<enter> leaves search mode at the
77current position and C<escape> returns to the original position.
78
61=item digital-clock 79=item digital-clock
62 80
63Displays a digital clock using the built-in overlay. 81Displays a digital clock using the built-in overlay.
64 82
65=item mark-urls 83=item mark-urls
66 84
67Uses per-line filtering (C<on_line_update>) to underline urls. 85Uses per-line display filtering (C<on_line_update>) to underline urls.
86
87=item block-graphics-to-ascii
88
89A not very useful example of filtering all text output to the terminal,
90by replacing all line-drawing characters (U+2500 .. U+259F) by a
91similar-looking ascii character.
68 92
69=item example-refresh-hooks 93=item example-refresh-hooks
70 94
71Displays a very simple digital clock in the upper right corner of the 95Displays a very simple digital clock in the upper right corner of the
72window. Illustrates overwriting the refresh callbacks to create your own 96window. Illustrates overwriting the refresh callbacks to create your own
73overlays or changes. 97overlays 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 98
82=back 99=back
83 100
84=head2 General API Considerations 101=head2 General API Considerations
85 102
115Either binary data or - more common - a text string encoded in a 132Either binary data or - more common - a text string encoded in a
116locale-specific way. 133locale-specific way.
117 134
118=back 135=back
119 136
137=head2 Extension Objects
138
139Very perl extension is a perl class. A separate perl object is created
140for each terminal and each extension and passed as the first parameter to
141hooks. So extensions can use their C<$self> object without having to think
142about other extensions, with the exception of methods and members that
143begin with an underscore character C<_>: these are reserved for internal
144use.
145
146Although it isn't a C<urxvt::term> object, you can call all methods of the
147C<urxvt::term> class on this object.
148
149It has the following methods and data members:
150
151=over 4
152
153=item $urxvt_term = $self->{term}
154
155Returns the C<urxvt::term> object associated with this instance of the
156extension. This member I<must not> be changed in any way.
157
158=item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
159
160Dynamically enable the given hooks (named without the C<on_> prefix) for
161this extension, replacing any previous hook. This is useful when you want
162to overwrite time-critical hooks only temporarily.
163
164=item $self->disable ($hook_name[, $hook_name..])
165
166Dynamically disable the given hooks.
167
168=back
169
120=head2 Hooks 170=head2 Hooks
121 171
122The following subroutines can be declared in loaded scripts, and will be 172The following subroutines can be declared in extension files, and will be
123called whenever the relevant event happens. 173called whenever the relevant event happens.
124 174
125The first argument passed to them is an object private to each terminal 175The first argument passed to them is an extension oject as described in
126and extension package. You can call all C<urxvt::term> methods on it, but 176the in the C<Extension Objects> section.
127its 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>
129member.
130 177
131All of them must return a boolean value. If it is true, then the event 178B<All> of these hooks must return a boolean value. If it is true, then the
132counts as being I<consumed>, and the invocation of other hooks is skipped, 179event counts as being I<consumed>, and the invocation of other hooks is
133and the relevant action might not be carried out by the C++ code. 180skipped, and the relevant action might not be carried out by the C++ code.
134 181
135When in doubt, return a false value (preferably C<()>). 182I<< When in doubt, return a false value (preferably C<()>). >>
136 183
137=over 4 184=over 4
138 185
139=item on_init $term 186=item on_init $term
140 187
179should extend the selection itelf and return true to suppress the built-in 226should extend the selection itelf and return true to suppress the built-in
180processing. 227processing.
181 228
182See the F<selection> example extension. 229See the F<selection> example extension.
183 230
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
194=item on_view_change $term, $offset 231=item on_view_change $term, $offset
195 232
196Called whenever the view offset changes, i..e the user or program 233Called whenever the view offset changes, i..e the user or program
197scrolls. Offset C<0> means display the normal terminal, positive values 234scrolls. Offset C<0> means display the normal terminal, positive values
198show this many lines of scrollback. 235show this many lines of scrollback.
204than the scroll back buffer or the terminal. 241than the scroll back buffer or the terminal.
205 242
206It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 243It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
207$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 244$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
208number of lines that will be in the scrollback buffer. 245number of lines that will be in the scrollback buffer.
209
210=item on_tty_activity $term *NYI*
211
212Called whenever the program(s) running in the urxvt window send output.
213 246
214=item on_osc_seq $term, $string 247=item on_osc_seq $term, $string
215 248
216Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC = 249Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
217operating system command) is processed. Cursor position and other state 250operating system command) is processed. Cursor position and other state
261 294
262Called whenever the user presses a key combination that has a 295Called whenever the user presses a key combination that has a
263C<perl:string> action bound to it (see description of the B<keysym> 296C<perl:string> action bound to it (see description of the B<keysym>
264resource in the @@RXVT_NAME@@(1) manpage). 297resource in the @@RXVT_NAME@@(1) manpage).
265 298
299=item on_focus_in $term
300
301Called whenever the window gets the keyboard focus, before rxvt-unicode
302does focus in processing.
303
304=item on_focus_out $term
305
306Called wheneever the window loses keyboard focus, before rxvt-unicode does
307focus out processing.
308
309=item on_key_press $term, $event, $keysym, $octets
310
311=item on_key_release $term, $event, $keysym
312
313=item on_button_press $term, $event
314
315=item on_button_release $term, $event
316
317=item on_motion_notify $term, $event
318
319=item on_map_notify $term, $event
320
321=item on_unmap_notify $term, $event
322
323Called whenever the corresponding X event is received for the terminal If
324the hook returns true, then the even will be ignored by rxvt-unicode.
325
326The event is a hash with most values as named by Xlib (see the XEvent
327manpage), with the additional members C<row> and C<col>, which are the row
328and column under the mouse cursor.
329
330C<on_key_press> additionally receives the string rxvt-unicode would
331output, if any, in locale-specific encoding.
332
333subwindow.
334
266=back 335=back
267 336
268=head2 Variables in the C<urxvt> Package 337=head2 Variables in the C<urxvt> Package
269 338
270=over 4 339=over 4
271 340
272=item $urxvt::TERM 341=item $urxvt::TERM
273 342
274The current terminal. Whenever a callback/Hook is bein executed, this 343The current terminal. This variable stores the current C<urxvt::term>
275variable stores the current C<urxvt::term> object. 344object, whenever a callback/hook is executing.
276 345
277=back 346=back
278 347
279=head2 Functions in the C<urxvt> Package 348=head2 Functions in the C<urxvt> Package
280 349
301that calls this function. 370that calls this function.
302 371
303Using this function has the advantage that its output ends up in the 372Using this function has the advantage that its output ends up in the
304correct place, e.g. on stderr of the connecting urxvtc client. 373correct place, e.g. on stderr of the connecting urxvtc client.
305 374
375=item $is_safe = urxvt::safe
376
377Returns true when it is safe to do potentially unsafe things, such as
378evaluating perl code specified by the user. This is true when urxvt was
379started setuid or setgid.
380
306=item $time = urxvt::NOW 381=item $time = urxvt::NOW
307 382
308Returns the "current time" (as per the event loop). 383Returns the "current time" (as per the event loop).
384
385=item urxvt::CurrentTime
386
387=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
388Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
389Button4Mask, Button5Mask, AnyModifier
390
391Various constants for use in X calls and event processing.
309 392
310=back 393=back
311 394
312=head2 RENDITION 395=head2 RENDITION
313 396
363 446
364=cut 447=cut
365 448
366package urxvt; 449package urxvt;
367 450
451use utf8;
368use strict; 452use strict;
453use Carp ();
369use Scalar::Util (); 454use Scalar::Util ();
455use List::Util ();
370 456
457our $VERSION = 1;
371our $TERM; 458our $TERM;
372our @HOOKNAME; 459our @HOOKNAME;
460our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
461our %OPTION;
373our $LIBDIR; 462our $LIBDIR;
374 463
375BEGIN { 464BEGIN {
376 urxvt->bootstrap; 465 urxvt->bootstrap;
377 466
380 my $msg = join "", @_; 469 my $msg = join "", @_;
381 $msg .= "\n" 470 $msg .= "\n"
382 unless $msg =~ /\n$/; 471 unless $msg =~ /\n$/;
383 urxvt::warn ($msg); 472 urxvt::warn ($msg);
384 }; 473 };
474
475 delete $ENV{IFS};
476 delete $ENV{CDPATH};
477 delete $ENV{BASH_ENV};
478 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
385} 479}
386 480
387my @hook_count; 481my @hook_count;
388my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 482my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
389 483
390sub verbose { 484sub verbose {
391 my ($level, $msg) = @_; 485 my ($level, $msg) = @_;
392 warn "$msg\n" if $level <= $verbosity; 486 warn "$msg\n" if $level <= $verbosity;
393} 487}
394 488
395# find on_xxx subs in the package and register them 489my $extension_pkg = "extension0000";
396# as hooks 490my %extension_pkg;
397sub register_package($) {
398 my ($pkg) = @_;
399
400 for my $htype (0.. $#HOOKNAME) {
401 my $name = $HOOKNAME[$htype];
402
403 my $ref = $pkg->can ("on_" . lc $name)
404 or next;
405
406 $TERM->{_hook}[$htype]{$pkg} = $ref;
407 $hook_count[$htype]++
408 or set_should_invoke $htype, 1;
409 }
410}
411
412my $script_pkg = "script0000";
413my %script_pkg;
414 491
415# load a single script into its own package, once only 492# load a single script into its own package, once only
416sub script_package($) { 493sub extension_package($) {
417 my ($path) = @_; 494 my ($path) = @_;
418 495
419 $script_pkg{$path} ||= do { 496 $extension_pkg{$path} ||= do {
420 my $pkg = "urxvt::" . ($script_pkg++); 497 my $pkg = "urxvt::" . ($extension_pkg++);
421 498
422 verbose 3, "loading script '$path' into package '$pkg'"; 499 verbose 3, "loading extension '$path' into package '$pkg'";
423 500
424 open my $fh, "<:raw", $path 501 open my $fh, "<:raw", $path
425 or die "$path: $!"; 502 or die "$path: $!";
426 503
504 my $source = untaint
427 my $source = "package $pkg; use strict; use utf8;\n" 505 "package $pkg; use strict; use utf8;\n"
506 . "use base urxvt::term::proxy::;\n"
428 . "#line 1 \"$path\"\n{\n" 507 . "#line 1 \"$path\"\n{\n"
429 . (do { local $/; <$fh> }) 508 . (do { local $/; <$fh> })
430 . "\n};\n1"; 509 . "\n};\n1";
431 510
511 eval $source
432 eval $source or die "$path: $@"; 512 or die "$path: $@";
433 513
434 $pkg 514 $pkg
435 } 515 }
436} 516}
437 517
442 local $TERM = shift; 522 local $TERM = shift;
443 my $htype = shift; 523 my $htype = shift;
444 524
445 if ($htype == 0) { # INIT 525 if ($htype == 0) { # INIT
446 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 526 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
527
528 my %ext_arg;
447 529
448 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) { 530 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
531 if ($_ eq "default") {
532 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback);
533 } elsif (/^-(.*)$/) {
534 delete $ext_arg{$1};
535 } elsif (/^([^<]+)<(.*)>$/) {
536 push @{ $ext_arg{$1} }, $2;
537 } else {
538 $ext_arg{$_} ||= [];
539 }
540 }
541
542 while (my ($ext, $argv) = each %ext_arg) {
449 my @files = grep -f $_, map "$_/$ext", @dirs; 543 my @files = grep -f $_, map "$_/$ext", @dirs;
450 544
451 if (@files) { 545 if (@files) {
452 register_package script_package $files[0]; 546 $TERM->register_package (extension_package $files[0], $argv);
453 } else { 547 } else {
454 warn "perl extension '$ext' not found in perl library search path\n"; 548 warn "perl extension '$ext' not found in perl library search path\n";
455 } 549 }
456 } 550 }
551
552 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
553 warn $@ if $@;
457 } 554 }
458 555
459 $retval = undef; 556 $retval = undef;
460 557
461 if (my $cb = $TERM->{_hook}[$htype]) { 558 if (my $cb = $TERM->{_hook}[$htype]) {
463 if $verbosity >= 10; 560 if $verbosity >= 10;
464 561
465 keys %$cb; 562 keys %$cb;
466 563
467 while (my ($pkg, $cb) = each %$cb) { 564 while (my ($pkg, $cb) = each %$cb) {
468 $retval = $cb->( 565 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }
469 $TERM->{_pkg}{$pkg} ||= do {
470 my $proxy = bless { }, urxvt::term::proxy::;
471 Scalar::Util::weaken ($proxy->{term} = $TERM);
472 $proxy
473 },
474 @_,
475 ) and last; 566 and last;
567
568 if ($@) {
569 $TERM->ungrab; # better to lose the grab than the session
570 warn $@;
571 }
476 } 572 }
477 } 573 }
478 574
479 if ($htype == 1) { # DESTROY 575 if ($htype == 1) { # DESTROY
480 # remove hooks if unused
481 if (my $hook = $TERM->{_hook}) { 576 if (my $hook = delete $TERM->{_hook}) {
482 for my $htype (0..$#$hook) { 577 for my $htype (0..$#$hook) {
483 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 578 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
484 or set_should_invoke $htype, 0; 579 or set_should_invoke $htype, 0;
485 } 580 }
486 } 581 }
493 } 588 }
494 589
495 $retval 590 $retval
496} 591}
497 592
498sub urxvt::term::proxy::AUTOLOAD { 593# urxvt::term::proxy
499 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 594
595package urxvt::term::proxy;
596
597sub enable {
598 my ($self, %hook) = @_;
599 my $pkg = $self->{_pkg};
600
601 while (my ($name, $cb) = each %hook) {
602 my $htype = $HOOKTYPE{uc $name};
603 defined $htype
604 or Carp::croak "unsupported hook type '$name'";
605
606 unless (exists $self->{term}{_hook}[$htype]{$pkg}) {
607 $hook_count[$htype]++
608 or urxvt::set_should_invoke $htype, 1;
609 }
610
611 $self->{term}{_hook}[$htype]{$pkg} = $cb;
612 }
613}
614
615sub disable {
616 my ($self, @hook) = @_;
617 my $pkg = $self->{_pkg};
618
619 for my $name (@hook) {
620 my $htype = $HOOKTYPE{uc $name};
621 defined $htype
622 or Carp::croak "unsupported hook type '$name'";
623
624 if (delete $self->{term}{_hook}[$htype]{$pkg}) {
625 --$hook_count[$htype]
626 or urxvt::set_should_invoke $htype, 0;
627 }
628 }
629}
630
631our $AUTOLOAD;
632
633sub AUTOLOAD {
634 $AUTOLOAD =~ /:([^:]+)$/
500 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 635 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
501 636
502 eval qq{ 637 eval qq{
503 sub $urxvt::term::proxy::AUTOLOAD { 638 sub $AUTOLOAD {
504 my \$proxy = shift; 639 my \$proxy = shift;
505 \$proxy->{term}->$1 (\@_) 640 \$proxy->{term}->$1 (\@_)
506 } 641 }
507 1 642 1
508 } or die "FATAL: unable to compile method forwarder: $@"; 643 } or die "FATAL: unable to compile method forwarder: $@";
509 644
510 goto &$urxvt::term::proxy::AUTOLOAD; 645 goto &$AUTOLOAD;
511} 646}
647
648sub DESTROY {
649 # nop
650}
651
652# urxvt::destroy_hook
653
654sub urxvt::destroy_hook::DESTROY {
655 ${$_[0]}->();
656}
657
658sub urxvt::destroy_hook(&) {
659 bless \shift, urxvt::destroy_hook::
660}
661
662package urxvt::anyevent;
663
664=head2 The C<urxvt::anyevent> Class
665
666The sole purpose of this class is to deliver an interface to the
667C<AnyEvent> module - any module using it will work inside urxvt without
668further work. The only exception is that you cannot wait on condition
669variables, but non-blocking condvar use is ok. What this means is that you
670cannot use blocking APIs, but the non-blocking variant should work.
671
672=cut
673
674our $VERSION = 1;
675
676$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
677push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
678
679sub timer {
680 my ($class, %arg) = @_;
681
682 my $cb = $arg{cb};
683
684 urxvt::timer
685 ->new
686 ->start (urxvt::NOW + $arg{after})
687 ->cb (sub {
688 $_[0]->stop; # need to cancel manually
689 $cb->();
690 })
691}
692
693sub io {
694 my ($class, %arg) = @_;
695
696 my $cb = $arg{cb};
697
698 bless [$arg{fh}, urxvt::iow
699 ->new
700 ->fd (fileno $arg{fh})
701 ->events (($arg{poll} =~ /r/ ? 1 : 0)
702 | ($arg{poll} =~ /w/ ? 2 : 0))
703 ->start
704 ->cb (sub {
705 $cb->(($_[1] & 1 ? 'r' : '')
706 . ($_[1] & 2 ? 'w' : ''));
707 })],
708 urxvt::anyevent::
709}
710
711sub DESTROY {
712 $_[0][1]->stop;
713}
714
715sub condvar {
716 bless \my $flag, urxvt::anyevent::condvar::
717}
718
719sub urxvt::anyevent::condvar::broadcast {
720 ${$_[0]}++;
721}
722
723sub urxvt::anyevent::condvar::wait {
724 unless (${$_[0]}) {
725 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
726 }
727}
728
729package urxvt::term;
512 730
513=head2 The C<urxvt::term> Class 731=head2 The C<urxvt::term> Class
514 732
515=over 4 733=over 4
516 734
735=cut
736
737# find on_xxx subs in the package and register them
738# as hooks
739sub register_package {
740 my ($self, $pkg, $argv) = @_;
741
742 my $proxy = bless {
743 _pkg => $pkg,
744 argv => $argv,
745 }, $pkg;
746 Scalar::Util::weaken ($proxy->{term} = $self);
747
748 $self->{_pkg}{$pkg} = $proxy;
749
750 for my $name (@HOOKNAME) {
751 if (my $ref = $pkg->can ("on_" . lc $name)) {
752 $proxy->enable ($name => $ref);
753 }
754 }
755}
756
517=item $term->destroy 757=item $term->destroy
518 758
519Destroy the terminal object (close the window, free resources etc.). 759Destroy the terminal object (close the window, free resources etc.).
760
761=item $isset = $term->option ($optval[, $set])
762
763Returns true if the option specified by C<$optval> is enabled, and
764optionally change it. All option values are stored by name in the hash
765C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
766
767Here is a a likely non-exhaustive list of option names, please see the
768source file F</src/optinc.h> to see the actual list:
769
770 borderLess console cursorBlink cursorUnderline hold iconic insecure
771 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
772 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
773 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
774 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
775 tripleclickwords utmpInhibit visualBell
520 776
521=item $value = $term->resource ($name[, $newval]) 777=item $value = $term->resource ($name[, $newval])
522 778
523Returns the current resource value associated with a given name and 779Returns the current resource value associated with a given name and
524optionally sets a new value. Setting values is most useful in the C<init> 780optionally sets a new value. Setting values is most useful in the C<init>
534 790
535Please note that resource strings will currently only be freed when the 791Please note that resource strings will currently only be freed when the
536terminal is destroyed, so changing options frequently will eat memory. 792terminal is destroyed, so changing options frequently will eat memory.
537 793
538Here is a a likely non-exhaustive list of resource names, not all of which 794Here is a a likely non-exhaustive list of resource names, not all of which
539are supported in every build, please see the source to see the actual 795are supported in every build, please see the source file F</src/rsinc.h>
540list: 796to see the actual list:
541 797
542 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 798 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
543 borderLess color cursorBlink cursorUnderline cutchars delete_key 799 borderLess color cursorBlink cursorUnderline cutchars delete_key
544 display_name embed ext_bwidth fade font geometry hold iconName 800 display_name embed ext_bwidth fade font geometry hold iconName
545 imFont imLocale inputMethod insecure int_bwidth intensityStyles 801 imFont imLocale inputMethod insecure int_bwidth intensityStyles
552 shade term_name title transparent transparent_all tripleclickwords 808 shade term_name title transparent transparent_all tripleclickwords
553 utmpInhibit visualBell 809 utmpInhibit visualBell
554 810
555=cut 811=cut
556 812
557sub urxvt::term::resource($$;$) { 813sub resource($$;$) {
558 my ($self, $name) = (shift, shift); 814 my ($self, $name) = (shift, shift);
559 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 815 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
560 goto &urxvt::term::_resource; 816 &urxvt::term::_resource
561} 817}
818
819=item $success = $term->parse_keysym ($keysym_spec, $command_string)
820
821Adds a keymap translation exactly as specified via a resource. See the
822C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
562 823
563=item $rend = $term->rstyle ([$new_rstyle]) 824=item $rend = $term->rstyle ([$new_rstyle])
564 825
565Return and optionally change the current rendition. Text that is output by 826Return and optionally change the current rendition. Text that is output by
566the terminal application will use this style. 827the terminal application will use this style.
586 847
587=item $oldtext = $term->selection ([$newtext]) 848=item $oldtext = $term->selection ([$newtext])
588 849
589Return the current selection text and optionally replace it by C<$newtext>. 850Return the current selection text and optionally replace it by C<$newtext>.
590 851
591#=item $term->overlay ($x, $y, $text) 852=item $term->overlay_simple ($x, $y, $text)
592# 853
593#Create a simple multi-line overlay box. See the next method for details. 854Create a simple multi-line overlay box. See the next method for details.
594# 855
595#=cut 856=cut
596# 857
597#sub urxvt::term::scr_overlay { 858sub overlay_simple {
598# my ($self, $x, $y, $text) = @_; 859 my ($self, $x, $y, $text) = @_;
599# 860
600# my @lines = split /\n/, $text; 861 my @lines = split /\n/, $text;
601# 862
602# my $w = 0; 863 my $w = List::Util::max map $self->strwidth ($_), @lines;
603# for (map $self->strwidth ($_), @lines) { 864
604# $w = $_ if $w < $_;
605# }
606#
607# $self->scr_overlay_new ($x, $y, $w, scalar @lines); 865 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
608# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 866 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
609#} 867
868 $overlay
869}
610 870
611=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 871=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
612 872
613Create a new (empty) overlay at the given position with the given 873Create a new (empty) overlay at the given position with the given
614width/height. C<$rstyle> defines the initial rendition style 874width/height. C<$rstyle> defines the initial rendition style
641 901
642If hidden, display the overlay again. 902If hidden, display the overlay again.
643 903
644=back 904=back
645 905
906=item $popup = $term->popup ($event)
907
908Creates a new C<urxvt::popup> object that implements a popup menu. The
909C<$event> I<must> be the event causing the menu to pop up (a button event,
910currently).
911
912=cut
913
914sub popup {
915 my ($self, $event) = @_;
916
917 $self->grab ($event->{time}, 1)
918 or return;
919
920 my $popup = bless {
921 term => $self,
922 event => $event,
923 }, urxvt::popup::;
924
925 Scalar::Util::weaken $popup->{term};
926
927 $self->{_destroy}{$popup} = urxvt::destroy_hook { $popup->{popup}->destroy };
928 Scalar::Util::weaken $self->{_destroy}{$popup};
929
930 $popup
931}
932
646=item $cellwidth = $term->strwidth $string 933=item $cellwidth = $term->strwidth ($string)
647 934
648Returns the number of screen-cells this string would need. Correctly 935Returns the number of screen-cells this string would need. Correctly
649accounts for wide and combining characters. 936accounts for wide and combining characters.
650 937
651=item $octets = $term->locale_encode $string 938=item $octets = $term->locale_encode ($string)
652 939
653Convert the given text string into the corresponding locale encoding. 940Convert the given text string into the corresponding locale encoding.
654 941
655=item $string = $term->locale_decode $octets 942=item $string = $term->locale_decode ($octets)
656 943
657Convert the given locale-encoded octets into a perl string. 944Convert the given locale-encoded octets into a perl string.
945
946=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
947
948XORs the rendition values in the given span with the provided value
949(default: C<RS_RVid>). Useful in refresh hooks to provide effects similar
950to the selection.
951
952=item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
953
954Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
955whitespace will additionally be xored with the C<$rstyle2>, which defaults
956to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
957it instead.
958
959=item $term->scr_bell
960
961Ring the bell!
658 962
659=item $term->scr_add_lines ($string) 963=item $term->scr_add_lines ($string)
660 964
661Write the given text string to the screen, as if output by the application 965Write the given text string to the screen, as if output by the application
662running inside the terminal. It may not contain command sequences (escape 966running inside the terminal. It may not contain command sequences (escape
677 981
678Write the octets given in C<$data> to the tty (i.e. as program input). To 982Write the octets given in C<$data> to the tty (i.e. as program input). To
679pass characters instead of octets, you should convert your strings first 983pass characters instead of octets, you should convert your strings first
680to the locale-specific encoding using C<< $term->locale_encode >>. 984to the locale-specific encoding using C<< $term->locale_encode >>.
681 985
986=item $old_events = $term->pty_ev_events ([$new_events])
987
988Replaces the event mask of the pty watcher by the given event mask. Can
989be used to suppress input and output handling to the pty/tty. See the
990description of C<< urxvt::timer->events >>. Make sure to always restore
991the previous value.
992
993=item $windowid = $term->parent
994
995Return the window id of the toplevel window.
996
997=item $windowid = $term->vt
998
999Return the window id of the terminal window.
1000
682=item $window_width = $term->width 1001=item $window_width = $term->width
683 1002
684=item $window_height = $term->height 1003=item $window_height = $term->height
685 1004
686=item $font_width = $term->fwidth 1005=item $font_width = $term->fwidth
702=item $nrow_plus_saveLines = $term->total_rows 1021=item $nrow_plus_saveLines = $term->total_rows
703 1022
704=item $lines_in_scrollback = $term->nsaved 1023=item $lines_in_scrollback = $term->nsaved
705 1024
706Return various integers describing terminal characteristics. 1025Return various integers describing terminal characteristics.
1026
1027=item $lc_ctype = $term->locale
1028
1029Returns the LC_CTYPE category string used by this rxvt-unicode.
1030
1031=item $x_display = $term->display_id
1032
1033Return the DISPLAY used by rxvt-unicode.
1034
1035=item $modifiermask = $term->ModLevel3Mask
1036
1037=item $modifiermask = $term->ModMetaMask
1038
1039=item $modifiermask = $term->ModNumLockMask
1040
1041Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1042AltGr), the meta key (often Alt) and the num lock key, if applicable.
707 1043
708=item $view_start = $term->view_start ([$newvalue]) 1044=item $view_start = $term->view_start ([$newvalue])
709 1045
710Returns the negative row number of the topmost line. Minimum value is 1046Returns the negative row number of the topmost line. Minimum value is
711C<0>, which displays the normal terminal contents. Larger values scroll 1047C<0>, which displays the normal terminal contents. Larger values scroll
805 1141
806=back 1142=back
807 1143
808=cut 1144=cut
809 1145
810sub urxvt::term::line { 1146sub line {
811 my ($self, $row) = @_; 1147 my ($self, $row) = @_;
812 1148
813 my $maxrow = $self->nrow - 1; 1149 my $maxrow = $self->nrow - 1;
814 1150
815 my ($beg, $end) = ($row, $row); 1151 my ($beg, $end) = ($row, $row);
879 $offset / $self->{ncol} + $self->{beg}, 1215 $offset / $self->{ncol} + $self->{beg},
880 $offset % $self->{ncol} 1216 $offset % $self->{ncol}
881 ) 1217 )
882} 1218}
883 1219
884=item ($row, $col) = $line->coord_of ($offset)
885=item $text = $term->special_encode $string 1220=item $text = $term->special_encode $string
886 1221
887Converts a perl string into the special encoding used by rxvt-unicode, 1222Converts a perl string into the special encoding used by rxvt-unicode,
888where one character corresponds to one screen cell. See 1223where one character corresponds to one screen cell. See
889C<< $term->ROW_t >> for details. 1224C<< $term->ROW_t >> for details.
891=item $string = $term->special_decode $text 1226=item $string = $term->special_decode $text
892 1227
893Converts rxvt-unicodes text reprsentation into a perl string. See 1228Converts rxvt-unicodes text reprsentation into a perl string. See
894C<< $term->ROW_t >> for details. 1229C<< $term->ROW_t >> for details.
895 1230
1231=item $success = $term->grab_button ($button, $modifiermask)
1232
1233Registers a synchronous button grab. See the XGrabButton manpage.
1234
1235=item $success = $term->grab ($eventtime[, $sync])
1236
1237Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1238synchronous (C<$sync> is true). Also remembers the grab timestampe.
1239
1240=item $term->allow_events_async
1241
1242Calls XAllowEvents with AsyncBoth for the most recent grab.
1243
1244=item $term->allow_events_sync
1245
1246Calls XAllowEvents with SyncBoth for the most recent grab.
1247
1248=item $term->allow_events_replay
1249
1250Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1251recent grab.
1252
1253=item $term->ungrab
1254
1255Calls XUngrab for the most recent grab. Is called automatically on
1256evaluation errors, as it is better to lose the grab in the error case as
1257the session.
1258
896=back 1259=back
1260
1261=cut
1262
1263package urxvt::popup;
1264
1265=head2 The C<urxvt::popup> Class
1266
1267=over 4
1268
1269=cut
1270
1271sub add_item {
1272 my ($self, $item) = @_;
1273
1274 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1275 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1276 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1277
1278 $item->{render} ||= sub { $_[0]{text} };
1279
1280 push @{ $self->{item} }, $item;
1281}
1282
1283sub add_separator {
1284 my ($self, $sep) = @_;
1285
1286 $sep ||= "=";
1287
1288 $self->add_item ({
1289 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1290 text => "",
1291 render => sub { $sep x $self->{term}->ncol },
1292 activate => sub { },
1293 });
1294}
1295
1296sub add_title {
1297 my ($self, $title) = @_;
1298
1299 $self->add_item ({
1300 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1301 text => $title,
1302 activate => sub { },
1303 });
1304}
1305
1306sub add_button {
1307 my ($self, $text, $cb) = @_;
1308
1309 $self->add_item ({ type => "button", text => $text, activate => $cb});
1310}
1311
1312sub add_toggle {
1313 my ($self, $text, $cb, $value) = @_;
1314
1315 my $item; $item = {
1316 type => "button",
1317 text => " $text",
1318 value => $value,
1319 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1320 activate => sub { $cb->($_[0]{value} = !$_[0]{value}); },
1321 };
1322
1323 $self->add_item ($item);
1324}
1325
1326sub show {
1327 my ($self) = @_;
1328
1329 local $urxvt::popup::self = $self;
1330
1331 local $ENV{LC_ALL} = $self->{term}->locale;
1332
1333 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1334 "--transient-for" => $self->{term}->parent,
1335 "-display" => $self->{term}->display_id,
1336 "-pe" => "urxvt-popup")
1337 or die "unable to create popup window\n";
1338}
1339
1340sub DESTROY {
1341 my ($self) = @_;
1342
1343 delete $self->{term}{_destroy}{$self};
1344 $self->{term}->ungrab;
1345}
897 1346
898=head2 The C<urxvt::timer> Class 1347=head2 The C<urxvt::timer> Class
899 1348
900This class implements timer watchers/events. Time is represented as a 1349This class implements timer watchers/events. Time is represented as a
901fractional number of seconds since the epoch. Example: 1350fractional number of seconds since the epoch. Example:
954 1403
955 $term->{socket} = ... 1404 $term->{socket} = ...
956 $term->{iow} = urxvt::iow 1405 $term->{iow} = urxvt::iow
957 ->new 1406 ->new
958 ->fd (fileno $term->{socket}) 1407 ->fd (fileno $term->{socket})
959 ->events (1) # wait for read data 1408 ->events (urxvt::EVENT_READ)
960 ->start 1409 ->start
961 ->cb (sub { 1410 ->cb (sub {
962 my ($iow, $revents) = @_; 1411 my ($iow, $revents) = @_;
963 # $revents must be 1 here, no need to check 1412 # $revents must be 1 here, no need to check
964 sysread $term->{socket}, my $buf, 8192 1413 sysread $term->{socket}, my $buf, 8192
981 1430
982Set the filedescriptor (not handle) to watch. 1431Set the filedescriptor (not handle) to watch.
983 1432
984=item $iow = $iow->events ($eventmask) 1433=item $iow = $iow->events ($eventmask)
985 1434
986Set the event mask to watch. Bit #0 (value C<1>) enables watching for read 1435Set the event mask to watch. The only allowed values are
987data, Bit #1 (value C<2>) enables watching for write data. 1436C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1437together, or C<urxvt::EVENT_NONE>.
988 1438
989=item $iow = $iow->start 1439=item $iow = $iow->start
990 1440
991Start watching for requested events on the given handle. 1441Start watching for requested events on the given handle.
992 1442
1003This variable controls the verbosity level of the perl extension. Higher 1453This variable controls the verbosity level of the perl extension. Higher
1004numbers indicate more verbose output. 1454numbers indicate more verbose output.
1005 1455
1006=over 4 1456=over 4
1007 1457
1008=item =0 - only fatal messages 1458=item == 0 - fatal messages
1009 1459
1010=item =3 - script loading and management 1460=item >= 3 - script loading and management
1011 1461
1012=item =10 - all events received 1462=item >=10 - all events received
1013 1463
1014=back 1464=back
1015 1465
1016=head1 AUTHOR 1466=head1 AUTHOR
1017 1467

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines