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.24 by root, Tue Jan 3 20:47:36 2006 UTC vs.
Revision 1.34 by root, Fri Jan 6 01:16:58 2006 UTC

39 39
40=over 4 40=over 4
41 41
42=item selection 42=item selection
43 43
44Intelligent selection. This etxension tries to be more intelligent when the user 44Intelligent selection. This extension tries to be more intelligent when
45extends selections (double-click). 45the user extends selections (double-click). Right now, it tries to select
46urls and complete shell-quoted arguments, which is very convenient, too,
47if your F<ls> supports C<--quoting-style=shell>.
46 48
47It also offers the following bindable event: 49It also offers the following bindable event:
48 50
49=over 4 51=over 4
50 52
63=item example-refresh-hooks 65=item example-refresh-hooks
64 66
65Displays a very simple digital clock in the upper right corner of the 67Displays a very simple digital clock in the upper right corner of the
66window. Illustrates overwriting the refresh callbacks to create your own 68window. Illustrates overwriting the refresh callbacks to create your own
67overlays or changes. 69overlays or changes.
70
71=item mark-urls
72
73A not very useful example of filtering all text output to the terminal, by
74underlining all urls that matches a certain regex (i.e. some urls :). It
75is not very useful because urls that are output in multiple steps (e.g.
76when typing them) do not get marked.
68 77
69=back 78=back
70 79
71=head2 General API Considerations 80=head2 General API Considerations
72 81
79When objects are destroyed on the C++ side, the perl object hashes are 88When objects are destroyed on the C++ side, the perl object hashes are
80emptied, so its best to store related objects such as time watchers and 89emptied, so its best to store related objects such as time watchers and
81the like inside the terminal object so they get destroyed as soon as the 90the like inside the terminal object so they get destroyed as soon as the
82terminal is destroyed. 91terminal is destroyed.
83 92
93Argument names also often indicate the type of a parameter. Here are some
94hints on what they mean:
95
96=over 4
97
98=item $text
99
100Rxvt-unicodes special way of encoding text, where one "unicode" character
101always represents one screen cell. See L<row_t> for a discussion of this format.
102
103=item $string
104
105A perl text string, with an emphasis on I<text>. It can store all unicode
106characters and is to be distinguished with text encoded in a specific
107encoding (often locale-specific) and binary data.
108
109=item $octets
110
111Either binary data or - more common - a text string encoded in a
112locale-specific way.
113
114=back
115
84=head2 Hooks 116=head2 Hooks
85 117
86The following subroutines can be declared in loaded scripts, and will be 118The following subroutines can be declared in loaded scripts, and will be
87called whenever the relevant event happens. 119called whenever the relevant event happens.
88 120
169number of lines that will be in the scrollback buffer. 201number of lines that will be in the scrollback buffer.
170 202
171=item on_tty_activity $term *NYI* 203=item on_tty_activity $term *NYI*
172 204
173Called whenever the program(s) running in the urxvt window send output. 205Called whenever the program(s) running in the urxvt window send output.
206
207=item on_osc_seq $term, $string
208
209Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
210operating system command) is processed. Cursor position and other state
211information is up-to-date when this happens. For interoperability, the
212string should start with the extension name and a colon, to distinguish
213it from commands for other extensions, and this might be enforced in the
214future.
215
216Be careful not ever to trust (in a security sense) the data you receive,
217as its source can not easily be controleld (e-mail content, messages from
218other users on the same system etc.).
219
220=item on_add_lines $term, $string
221
222Called whenever text is about to be output, with the text as argument. You
223can filter/change and output the text yourself by returning a true value
224and calling C<< $term->scr_add_lines >> yourself. Please note that this
225might be very slow, however, as your hook is called for B<all> text being
226output.
174 227
175=item on_refresh_begin $term 228=item on_refresh_begin $term
176 229
177Called just before the screen gets redrawn. Can be used for overlay 230Called just before the screen gets redrawn. Can be used for overlay
178or similar effects by modify terminal contents in refresh_begin, and 231or similar effects by modify terminal contents in refresh_begin, and
351 404
352 $pkg 405 $pkg
353 } 406 }
354} 407}
355 408
409our $retval; # return value for urxvt
410
356# called by the rxvt core 411# called by the rxvt core
357sub invoke { 412sub invoke {
358 local $TERM = shift; 413 local $TERM = shift;
359 my $htype = shift; 414 my $htype = shift;
360 415
361 if ($htype == 0) { # INIT 416 if ($htype == 0) { # INIT
362 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 417 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
363 418
364 for my $ext (split /:/, $TERM->resource ("perl_ext")) { 419 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) {
365 my @files = grep -f $_, map "$_/$ext", @dirs; 420 my @files = grep -f $_, map "$_/$ext", @dirs;
366 421
367 if (@files) { 422 if (@files) {
368 register_package script_package $files[0]; 423 register_package script_package $files[0];
369 } else { 424 } else {
370 warn "perl extension '$ext' not found in perl library search path\n"; 425 warn "perl extension '$ext' not found in perl library search path\n";
371 } 426 }
372 } 427 }
428 }
373 429
430 $retval = undef;
431
432 if (my $cb = $TERM->{_hook}[$htype]) {
433 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
434 if $verbosity >= 10;
435
436 keys %$cb;
437
438 while (my ($pkg, $cb) = each %$cb) {
439 $retval = $cb->(
440 $TERM->{_pkg}{$pkg} ||= do {
441 my $proxy = bless { }, urxvt::term::proxy::;
442 Scalar::Util::weaken ($proxy->{term} = $TERM);
443 $proxy
444 },
445 @_,
446 ) and last;
447 }
448 }
449
374 } elsif ($htype == 1) { # DESTROY 450 if ($htype == 1) { # DESTROY
451 # remove hooks if unused
375 if (my $hook = $TERM->{_hook}) { 452 if (my $hook = $TERM->{_hook}) {
376 for my $htype (0..$#$hook) { 453 for my $htype (0..$#$hook) {
377 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 454 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
378 or set_should_invoke $htype, 0; 455 or set_should_invoke $htype, 0;
379 } 456 }
380 } 457 }
458
459 # clear package objects
460 %$_ = () for values %{ $TERM->{_pkg} };
461
462 # clear package
463 %$TERM = ();
381 } 464 }
382 465
383 my $cb = $TERM->{_hook}[$htype] 466 $retval
384 or return;
385
386 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
387 if $verbosity >= 10;
388
389 while (my ($pkg, $cb) = each %$cb) {
390 return 1
391 if $cb->(
392 $TERM->{$pkg} ||= do {
393 my $proxy = bless { }, urxvt::term::proxy::;
394 Scalar::Util::weaken ($proxy->{term} = $TERM);
395 $proxy
396 },
397 @_,
398 );
399 }
400
401 0
402} 467}
403 468
404sub urxvt::term::proxy::AUTOLOAD { 469sub urxvt::term::proxy::AUTOLOAD {
405 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 470 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/
406 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 471 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable";
444 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 509 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
445 borderLess color cursorBlink cursorUnderline cutchars delete_key 510 borderLess color cursorBlink cursorUnderline cutchars delete_key
446 display_name embed ext_bwidth fade font geometry hold iconName 511 display_name embed ext_bwidth fade font geometry hold iconName
447 imFont imLocale inputMethod insecure int_bwidth intensityStyles 512 imFont imLocale inputMethod insecure int_bwidth intensityStyles
448 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 513 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
449 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext 514 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
450 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 515 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
451 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 516 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
452 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 517 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
453 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 518 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
454 shade term_name title transparent transparent_all tripleclickwords 519 shade term_name title transparent transparent_all tripleclickwords
460 my ($self, $name) = (shift, shift); 525 my ($self, $name) = (shift, shift);
461 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 526 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
462 goto &urxvt::term::_resource; 527 goto &urxvt::term::_resource;
463} 528}
464 529
530=item $rend = $term->rstyle ([$new_rstyle])
531
532Return and optionally change the current rendition. Text that is output by
533the terminal application will use this style.
534
535=item ($row, $col) = $term->screen_cur ([$row, $col])
536
537Return the current coordinates of the text cursor position and optionally
538set it (which is usually bad as applications don't expect that).
539
465=item ($row, $col) = $term->selection_mark ([$row, $col]) 540=item ($row, $col) = $term->selection_mark ([$row, $col])
466 541
467=item ($row, $col) = $term->selection_beg ([$row, $col]) 542=item ($row, $col) = $term->selection_beg ([$row, $col])
468 543
469=item ($row, $col) = $term->selection_end ([$row, $col]) 544=item ($row, $col) = $term->selection_end ([$row, $col])
483#=item $term->overlay ($x, $y, $text) 558#=item $term->overlay ($x, $y, $text)
484# 559#
485#Create a simple multi-line overlay box. See the next method for details. 560#Create a simple multi-line overlay box. See the next method for details.
486# 561#
487#=cut 562#=cut
488 563#
489sub urxvt::term::scr_overlay { 564#sub urxvt::term::scr_overlay {
490die;
491 my ($self, $x, $y, $text) = @_; 565# my ($self, $x, $y, $text) = @_;
492 566#
493 my @lines = split /\n/, $text; 567# my @lines = split /\n/, $text;
494 568#
495 my $w = 0; 569# my $w = 0;
496 for (map $self->strwidth ($_), @lines) { 570# for (map $self->strwidth ($_), @lines) {
497 $w = $_ if $w < $_; 571# $w = $_ if $w < $_;
498 } 572# }
499 573#
500 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 574# $self->scr_overlay_new ($x, $y, $w, scalar @lines);
501 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 575# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
502} 576#}
503 577
504=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 578=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
505 579
506Create a new (empty) overlay at the given position with the given 580Create a new (empty) overlay at the given position with the given
507width/height. C<$rstyle> defines the initial rendition style 581width/height. C<$rstyle> defines the initial rendition style
547 621
548=item $string = $term->locale_decode $octets 622=item $string = $term->locale_decode $octets
549 623
550Convert the given locale-encoded octets into a perl string. 624Convert the given locale-encoded octets into a perl string.
551 625
626=item $term->scr_add_lines ($string)
627
628Write the given text string to the screen, as if output by the application
629running inside the terminal. It may not contain command sequences (escape
630codes), but is free to use line feeds, carriage returns and tabs. The
631string is a normal text string, not in locale-dependent encoding.
632
633Normally its not a good idea to use this function, as programs might be
634confused by changes in cursor position or scrolling. Its useful inside a
635C<on_add_lines> hook, though.
636
552=item $term->tt_write ($octets) 637=item $term->tt_write ($octets)
553 638
554Write the octets given in C<$data> to the tty (i.e. as program input). To 639Write the octets given in C<$data> to the tty (i.e. as program input). To
555pass characters instead of octets, you should convert your strings first 640pass characters instead of octets, you should convert your strings first
556to the locale-specific encoding using C<< $term->locale_encode >>. 641to the locale-specific encoding using C<< $term->locale_encode >>.
557 642
643=item $window_width = $term->width
644
645=item $window_height = $term->height
646
647=item $font_width = $term->fwidth
648
649=item $font_height = $term->fheight
650
651=item $font_ascent = $term->fbase
652
558=item $nrow = $term->nrow 653=item $terminal_rows = $term->nrow
559 654
560=item $ncol = $term->ncol 655=item $terminal_columns = $term->ncol
561 656
562Return the number of rows/columns of the terminal window (i.e. as 657=item $has_focus = $term->focus
563specified by C<-geometry>, excluding any scrollback).
564 658
565=item $nsaved = $term->nsaved 659=item $is_mapped = $term->mapped
566 660
567Returns the number of lines in the scrollback buffer. 661=item $max_scrollback = $term->saveLines
662
663=item $nrow_plus_saveLines = $term->total_rows
664
665=item $lines_in_scrollback = $term->nsaved
666
667Return various integers describing terminal characteristics.
568 668
569=item $view_start = $term->view_start ([$newvalue]) 669=item $view_start = $term->view_start ([$newvalue])
570 670
571Returns the negative row number of the topmost line. Minimum value is 671Returns the negative row number of the topmost line. Minimum value is
572C<0>, which displays the normal terminal contents. Larger values scroll 672C<0>, which displays the normal terminal contents. Larger values scroll
680 780
681 bless { 781 bless {
682 term => $self, 782 term => $self,
683 beg => $beg, 783 beg => $beg,
684 end => $end, 784 end => $end,
785 ncol => $self->ncol,
685 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end), 786 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
686 }, urxvt::line:: 787 }, urxvt::line::
687} 788}
688 789
689sub urxvt::line::t { 790sub urxvt::line::t {
690 my ($self) = @_; 791 my ($self) = @_;
691 792
793 if (@_ > 1)
794 {
795 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
796 for $self->{beg} .. $self->{end};
797 }
798
799 defined wantarray &&
692 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 800 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
693 0, $self->{len} 801 0, $self->{len}
694} 802}
695 803
696sub urxvt::line::r { 804sub urxvt::line::r {
697 my ($self) = @_; 805 my ($self) = @_;
698 806
807 if (@_ > 1)
808 {
809 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
810 for $self->{beg} .. $self->{end};
811 }
812
813 if (defined wantarray) {
699 my $rend = [ 814 my $rend = [
700 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 815 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
701 ]; 816 ];
702 $#$rend = $self->{len} - 1; 817 $#$rend = $self->{len} - 1;
703 $rend 818 return $rend;
819 }
820
821 ()
704} 822}
705 823
706sub urxvt::line::beg { $_[0]{beg} } 824sub urxvt::line::beg { $_[0]{beg} }
707sub urxvt::line::end { $_[0]{end} } 825sub urxvt::line::end { $_[0]{end} }
708sub urxvt::line::l { $_[0]{len} } 826sub urxvt::line::l { $_[0]{len} }
709 827
710sub urxvt::line::offset_of { 828sub urxvt::line::offset_of {
711 my ($self, $row, $col) = @_; 829 my ($self, $row, $col) = @_;
712 830
713 ($row - $self->{beg}) * $self->{term}->ncol + $col 831 ($row - $self->{beg}) * $self->{ncol} + $col
714} 832}
715 833
716sub urxvt::line::coord_of { 834sub urxvt::line::coord_of {
717 my ($self, $offset) = @_; 835 my ($self, $offset) = @_;
718 836
719 use integer; 837 use integer;
720 838
721 ( 839 (
722 $offset / $self->{term}->ncol + $self->{beg}, 840 $offset / $self->{ncol} + $self->{beg},
723 $offset % $self->{term}->ncol 841 $offset % $self->{ncol}
724 ) 842 )
725} 843}
726 844
727=item ($row, $col) = $line->coord_of ($offset) 845=item ($row, $col) = $line->coord_of ($offset)
728=item $text = $term->special_encode $string 846=item $text = $term->special_encode $string
846This variable controls the verbosity level of the perl extension. Higher 964This variable controls the verbosity level of the perl extension. Higher
847numbers indicate more verbose output. 965numbers indicate more verbose output.
848 966
849=over 4 967=over 4
850 968
851=item 0 - only fatal messages 969=item =0 - only fatal messages
852 970
853=item 3 - script loading and management 971=item =3 - script loading and management
854 972
855=item 10 - all events received 973=item =10 - all events received
856 974
857=back 975=back
858 976
859=head1 AUTHOR 977=head1 AUTHOR
860 978

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines