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.22 by root, Tue Jan 3 19:10:54 2006 UTC vs.
Revision 1.35 by root, Fri Jan 6 01:27:27 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
57=back 59=back
58 60
59=item digital-clock 61=item digital-clock
60 62
61Displays a digital clock using the built-in overlay. 63Displays a digital clock using the built-in overlay.
64
65=item mark-urls
66
67Uses per-line filtering (C<on_line_update>) to underline urls.
62 68
63=item example-refresh-hooks 69=item example-refresh-hooks
64 70
65Displays a very simple digital clock in the upper right corner of the 71Displays a very simple digital clock in the upper right corner of the
66window. Illustrates overwriting the refresh callbacks to create your own 72window. Illustrates overwriting the refresh callbacks to create your own
67overlays or changes. 73overlays or changes.
68 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
69=back 82=back
70 83
71=head2 General API Considerations 84=head2 General API Considerations
72 85
73All objects (such as terminals, time watchers etc.) are typical 86All objects (such as terminals, time watchers etc.) are typical
74reference-to-hash objects. The hash can be used to store anything you 87reference-to-hash objects. The hash can be used to store anything you
75like. All members starting with an underscore (such as C<_ptr> or 88like. All members starting with an underscore (such as C<_ptr> or
76C<_hook>) are reserved for internal uses and must not be accessed or 89C<_hook>) are reserved for internal uses and B<MUST NOT> be accessed or
77modified). 90modified).
78 91
79When objects are destroyed on the C++ side, the perl object hashes are 92When 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 93emptied, 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 94the like inside the terminal object so they get destroyed as soon as the
82terminal is destroyed. 95terminal is destroyed.
83 96
97Argument names also often indicate the type of a parameter. Here are some
98hints on what they mean:
99
100=over 4
101
102=item $text
103
104Rxvt-unicodes special way of encoding text, where one "unicode" character
105always represents one screen cell. See L<row_t> for a discussion of this format.
106
107=item $string
108
109A perl text string, with an emphasis on I<text>. It can store all unicode
110characters and is to be distinguished with text encoded in a specific
111encoding (often locale-specific) and binary data.
112
113=item $octets
114
115Either binary data or - more common - a text string encoded in a
116locale-specific way.
117
118=back
119
84=head2 Hooks 120=head2 Hooks
85 121
86The following subroutines can be declared in loaded scripts, and will be called 122The following subroutines can be declared in loaded scripts, and will be
87whenever the relevant event happens. 123called whenever the relevant event happens.
124
125The 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
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.
88 130
89All of them must return a boolean value. If it is true, then the event 131All of them must return a boolean value. If it is true, then the event
90counts as being I<consumed>, and the invocation of other hooks is skipped, 132counts as being I<consumed>, and the invocation of other hooks is skipped,
91and the relevant action might not be carried out by the C++ code. 133and the relevant action might not be carried out by the C++ code.
92 134
164 206
165=item on_tty_activity $term *NYI* 207=item on_tty_activity $term *NYI*
166 208
167Called whenever the program(s) running in the urxvt window send output. 209Called whenever the program(s) running in the urxvt window send output.
168 210
211=item on_osc_seq $term, $string
212
213Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
214operating system command) is processed. Cursor position and other state
215information is up-to-date when this happens. For interoperability, the
216string should start with the extension name and a colon, to distinguish
217it from commands for other extensions, and this might be enforced in the
218future.
219
220Be careful not ever to trust (in a security sense) the data you receive,
221as its source can not easily be controleld (e-mail content, messages from
222other users on the same system etc.).
223
224=item on_add_lines $term, $string
225
226Called whenever text is about to be output, with the text as argument. You
227can filter/change and output the text yourself by returning a true value
228and calling C<< $term->scr_add_lines >> yourself. Please note that this
229might be very slow, however, as your hook is called for B<all> text being
230output.
231
232=item on_line_update $term, $row
233
234Called whenever a line was updated or changed. Can be used to filter
235screen output (e.g. underline urls or other useless stuff). Only lines
236that are being shown will be filtered, and, due to performance reasons,
237not always immediately.
238
239The row number is always the topmost row of the line if the line spans
240multiple rows.
241
242Please note that, if you change the line, then the hook might get called
243later with the already-modified line (e.g. if unrelated parts change), so
244you cannot just toggle rendition bits, but only set them.
245
169=item on_refresh_begin $term 246=item on_refresh_begin $term
170 247
171Called just before the screen gets redrawn. Can be used for overlay 248Called just before the screen gets redrawn. Can be used for overlay
172or similar effects by modify terminal contents in refresh_begin, and 249or similar effects by modify terminal contents in refresh_begin, and
173restoring them in refresh_end. The built-in overlay and selection display 250restoring them in refresh_end. The built-in overlay and selection display
183C<perl:string> action bound to it (see description of the B<keysym> 260C<perl:string> action bound to it (see description of the B<keysym>
184resource in the @@RXVT_NAME@@(1) manpage). 261resource in the @@RXVT_NAME@@(1) manpage).
185 262
186=back 263=back
187 264
265=head2 Variables in the C<urxvt> Package
266
267=over 4
268
269=item $urxvt::TERM
270
271The current terminal. Whenever a callback/Hook is bein executed, this
272variable stores the current C<urxvt::term> object.
273
274=back
275
188=head2 Functions in the C<urxvt> Package 276=head2 Functions in the C<urxvt> Package
189 277
190=over 4 278=over 4
191 279
192=item urxvt::fatal $errormessage 280=item urxvt::fatal $errormessage
265=cut 353=cut
266 354
267package urxvt; 355package urxvt;
268 356
269use strict; 357use strict;
358use Scalar::Util ();
270 359
271our $term; 360our $TERM;
272our @HOOKNAME; 361our @HOOKNAME;
273our $LIBDIR; 362our $LIBDIR;
274 363
275BEGIN { 364BEGIN {
276 urxvt->bootstrap; 365 urxvt->bootstrap;
301 my $name = $HOOKNAME[$htype]; 390 my $name = $HOOKNAME[$htype];
302 391
303 my $ref = $pkg->can ("on_" . lc $name) 392 my $ref = $pkg->can ("on_" . lc $name)
304 or next; 393 or next;
305 394
306 $term->{_hook}[$htype]{$ref*1} = $ref; 395 $TERM->{_hook}[$htype]{$pkg} = $ref;
307 $hook_count[$htype]++ 396 $hook_count[$htype]++
308 or set_should_invoke $htype, 1; 397 or set_should_invoke $htype, 1;
309 } 398 }
310} 399}
311 400
333 422
334 $pkg 423 $pkg
335 } 424 }
336} 425}
337 426
427our $retval; # return value for urxvt
428
338# called by the rxvt core 429# called by the rxvt core
339sub invoke { 430sub invoke {
340 local $term = shift; 431 local $TERM = shift;
341 my $htype = shift; 432 my $htype = shift;
342 433
343 if ($htype == 0) { # INIT 434 if ($htype == 0) { # INIT
344 my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl"); 435 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
345 436
346 for my $ext (split /:/, $term->resource ("perl_ext")) { 437 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) {
347 my @files = grep -f $_, map "$_/$ext", @dirs; 438 my @files = grep -f $_, map "$_/$ext", @dirs;
348 439
349 if (@files) { 440 if (@files) {
350 register_package script_package $files[0]; 441 register_package script_package $files[0];
351 } else { 442 } else {
352 warn "perl extension '$ext' not found in perl library search path\n"; 443 warn "perl extension '$ext' not found in perl library search path\n";
353 } 444 }
354 } 445 }
446 }
355 447
448 $retval = undef;
449
450 if (my $cb = $TERM->{_hook}[$htype]) {
451 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
452 if $verbosity >= 10;
453
454 keys %$cb;
455
456 while (my ($pkg, $cb) = each %$cb) {
457 $retval = $cb->(
458 $TERM->{_pkg}{$pkg} ||= do {
459 my $proxy = bless { }, urxvt::term::proxy::;
460 Scalar::Util::weaken ($proxy->{term} = $TERM);
461 $proxy
462 },
463 @_,
464 ) and last;
465 }
466 }
467
356 } elsif ($htype == 1) { # DESTROY 468 if ($htype == 1) { # DESTROY
469 # remove hooks if unused
357 if (my $hook = $term->{_hook}) { 470 if (my $hook = $TERM->{_hook}) {
358 for my $htype (0..$#$hook) { 471 for my $htype (0..$#$hook) {
359 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 472 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
360 or set_should_invoke $htype, 0; 473 or set_should_invoke $htype, 0;
361 } 474 }
362 } 475 }
476
477 # clear package objects
478 %$_ = () for values %{ $TERM->{_pkg} };
479
480 # clear package
481 %$TERM = ();
363 } 482 }
364 483
365 my $cb = $term->{_hook}[$htype] 484 $retval
366 or return; 485}
367 486
368 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")" 487sub urxvt::term::proxy::AUTOLOAD {
369 if $verbosity >= 10; 488 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/
489 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable";
370 490
371 while (my ($k, $v) = each %$cb) { 491 eval qq{
372 return 1 if $v->($term, @_); 492 sub $urxvt::term::proxy::AUTOLOAD {
373 } 493 my \$proxy = shift;
494 \$proxy->{term}->$1 (\@_)
495 }
496 1
497 } or die "FATAL: unable to compile method forwarder: $@";
374 498
375 0 499 goto &$urxvt::term::proxy::AUTOLOAD;
376} 500}
377 501
378=head2 The C<urxvt::term> Class 502=head2 The C<urxvt::term> Class
379 503
380=over 4 504=over 4
403 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 527 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
404 borderLess color cursorBlink cursorUnderline cutchars delete_key 528 borderLess color cursorBlink cursorUnderline cutchars delete_key
405 display_name embed ext_bwidth fade font geometry hold iconName 529 display_name embed ext_bwidth fade font geometry hold iconName
406 imFont imLocale inputMethod insecure int_bwidth intensityStyles 530 imFont imLocale inputMethod insecure int_bwidth intensityStyles
407 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 531 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
408 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext 532 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
409 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 533 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
410 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 534 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
411 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 535 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
412 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 536 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
413 shade term_name title transparent transparent_all tripleclickwords 537 shade term_name title transparent transparent_all tripleclickwords
419 my ($self, $name) = (shift, shift); 543 my ($self, $name) = (shift, shift);
420 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 544 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
421 goto &urxvt::term::_resource; 545 goto &urxvt::term::_resource;
422} 546}
423 547
548=item $rend = $term->rstyle ([$new_rstyle])
549
550Return and optionally change the current rendition. Text that is output by
551the terminal application will use this style.
552
553=item ($row, $col) = $term->screen_cur ([$row, $col])
554
555Return the current coordinates of the text cursor position and optionally
556set it (which is usually bad as applications don't expect that).
557
424=item ($row, $col) = $term->selection_mark ([$row, $col]) 558=item ($row, $col) = $term->selection_mark ([$row, $col])
425 559
426=item ($row, $col) = $term->selection_beg ([$row, $col]) 560=item ($row, $col) = $term->selection_beg ([$row, $col])
427 561
428=item ($row, $col) = $term->selection_end ([$row, $col]) 562=item ($row, $col) = $term->selection_end ([$row, $col])
442#=item $term->overlay ($x, $y, $text) 576#=item $term->overlay ($x, $y, $text)
443# 577#
444#Create a simple multi-line overlay box. See the next method for details. 578#Create a simple multi-line overlay box. See the next method for details.
445# 579#
446#=cut 580#=cut
447 581#
448sub urxvt::term::scr_overlay { 582#sub urxvt::term::scr_overlay {
449die;
450 my ($self, $x, $y, $text) = @_; 583# my ($self, $x, $y, $text) = @_;
451 584#
452 my @lines = split /\n/, $text; 585# my @lines = split /\n/, $text;
453 586#
454 my $w = 0; 587# my $w = 0;
455 for (map $self->strwidth ($_), @lines) { 588# for (map $self->strwidth ($_), @lines) {
456 $w = $_ if $w < $_; 589# $w = $_ if $w < $_;
457 } 590# }
458 591#
459 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 592# $self->scr_overlay_new ($x, $y, $w, scalar @lines);
460 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 593# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
461} 594#}
462 595
463=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 596=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
464 597
465Create a new (empty) overlay at the given position with the given 598Create a new (empty) overlay at the given position with the given
466width/height. C<$rstyle> defines the initial rendition style 599width/height. C<$rstyle> defines the initial rendition style
506 639
507=item $string = $term->locale_decode $octets 640=item $string = $term->locale_decode $octets
508 641
509Convert the given locale-encoded octets into a perl string. 642Convert the given locale-encoded octets into a perl string.
510 643
644=item $term->scr_add_lines ($string)
645
646Write the given text string to the screen, as if output by the application
647running inside the terminal. It may not contain command sequences (escape
648codes), but is free to use line feeds, carriage returns and tabs. The
649string is a normal text string, not in locale-dependent encoding.
650
651Normally its not a good idea to use this function, as programs might be
652confused by changes in cursor position or scrolling. Its useful inside a
653C<on_add_lines> hook, though.
654
511=item $term->tt_write ($octets) 655=item $term->tt_write ($octets)
512 656
513Write the octets given in C<$data> to the tty (i.e. as program input). To 657Write the octets given in C<$data> to the tty (i.e. as program input). To
514pass characters instead of octets, you should convert your strings first 658pass characters instead of octets, you should convert your strings first
515to the locale-specific encoding using C<< $term->locale_encode >>. 659to the locale-specific encoding using C<< $term->locale_encode >>.
516 660
661=item $window_width = $term->width
662
663=item $window_height = $term->height
664
665=item $font_width = $term->fwidth
666
667=item $font_height = $term->fheight
668
669=item $font_ascent = $term->fbase
670
517=item $nrow = $term->nrow 671=item $terminal_rows = $term->nrow
518 672
519=item $ncol = $term->ncol 673=item $terminal_columns = $term->ncol
520 674
521Return the number of rows/columns of the terminal window (i.e. as 675=item $has_focus = $term->focus
522specified by C<-geometry>, excluding any scrollback).
523 676
524=item $nsaved = $term->nsaved 677=item $is_mapped = $term->mapped
525 678
526Returns the number of lines in the scrollback buffer. 679=item $max_scrollback = $term->saveLines
680
681=item $nrow_plus_saveLines = $term->total_rows
682
683=item $lines_in_scrollback = $term->nsaved
684
685Return various integers describing terminal characteristics.
527 686
528=item $view_start = $term->view_start ([$newvalue]) 687=item $view_start = $term->view_start ([$newvalue])
529 688
530Returns the negative row number of the topmost line. Minimum value is 689Returns the negative row number of the topmost line. Minimum value is
531C<0>, which displays the normal terminal contents. Larger values scroll 690C<0>, which displays the normal terminal contents. Larger values scroll
542=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 701=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
543 702
544Returns the text of the entire row with number C<$row_number>. Row C<0> 703Returns the text of the entire row with number C<$row_number>. Row C<0>
545is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost 704is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost
546terminal line. The scrollback buffer starts at line C<-1> and extends to 705terminal line. The scrollback buffer starts at line C<-1> and extends to
547line C<< -$term->nsaved >>. 706line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line
707is requested.
548 708
549If C<$new_text> is specified, it will replace characters in the current 709If C<$new_text> is specified, it will replace characters in the current
550line, starting at column C<$start_col> (default C<0>), which is useful 710line, starting at column C<$start_col> (default C<0>), which is useful
551to replace only parts of a line. The font index in the rendition will 711to replace only parts of a line. The font index in the rendition will
552automatically be updated. 712automatically be updated.
574 734
575See the section on RENDITION, above. 735See the section on RENDITION, above.
576 736
577=item $length = $term->ROW_l ($row_number[, $new_length]) 737=item $length = $term->ROW_l ($row_number[, $new_length])
578 738
579Returns the number of screen cells that are in use ("the line length"). If 739Returns the number of screen cells that are in use ("the line
580it is C<-1>, then the line is part of a multiple-row logical "line", which 740length"). Unlike the urxvt core, this returns C<< $term->ncol >> if the
581means all characters are in use and it is continued on the next row. 741line is joined with the following one.
582 742
743=item $bool = $term->is_longer ($row_number)
744
745Returns true if the row is part of a multiple-row logical "line" (i.e.
746joined with the following row), which means all characters are in use
747and it is continued on the next row (and possibly a continuation of the
748previous row(s)).
749
750=item $line = $term->line ($row_number)
751
752Create and return a new C<urxvt::line> object that stores information
753about the logical line that row C<$row_number> is part of. It supports the
754following methods:
755
756=over 4
757
758=item $text = $line->t ([$new_text])
759
760Returns or replaces the full text of the line, similar to C<ROW_t>
761
762=item $rend = $line->r ([$new_rend])
763
764Returns or replaces the full rendition array of the line, similar to C<ROW_r>
765
766=item $length = $line->l
767
768Returns the length of the line in cells, similar to C<ROW_l>.
769
770=item $rownum = $line->beg
771
772=item $rownum = $line->end
773
774Return the row number of the first/last row of the line, respectively.
775
776=item $offset = $line->offset_of ($row, $col)
777
778Returns the character offset of the given row|col pair within the logical
779line.
780
781=item ($row, $col) = $line->coord_of ($offset)
782
783Translates a string offset into terminal coordinates again.
784
785=back
786
787=cut
788
789sub urxvt::term::line {
790 my ($self, $row) = @_;
791
792 my $maxrow = $self->nrow - 1;
793
794 my ($beg, $end) = ($row, $row);
795
796 --$beg while $self->ROW_is_longer ($beg - 1);
797 ++$end while $self->ROW_is_longer ($end) && $end < $maxrow;
798
799 bless {
800 term => $self,
801 beg => $beg,
802 end => $end,
803 ncol => $self->ncol,
804 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
805 }, urxvt::line::
806}
807
808sub urxvt::line::t {
809 my ($self) = @_;
810
811 if (@_ > 1)
812 {
813 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
814 for $self->{beg} .. $self->{end};
815 }
816
817 defined wantarray &&
818 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
819 0, $self->{len}
820}
821
822sub urxvt::line::r {
823 my ($self) = @_;
824
825 if (@_ > 1)
826 {
827 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
828 for $self->{beg} .. $self->{end};
829 }
830
831 if (defined wantarray) {
832 my $rend = [
833 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
834 ];
835 $#$rend = $self->{len} - 1;
836 return $rend;
837 }
838
839 ()
840}
841
842sub urxvt::line::beg { $_[0]{beg} }
843sub urxvt::line::end { $_[0]{end} }
844sub urxvt::line::l { $_[0]{len} }
845
846sub urxvt::line::offset_of {
847 my ($self, $row, $col) = @_;
848
849 ($row - $self->{beg}) * $self->{ncol} + $col
850}
851
852sub urxvt::line::coord_of {
853 my ($self, $offset) = @_;
854
855 use integer;
856
857 (
858 $offset / $self->{ncol} + $self->{beg},
859 $offset % $self->{ncol}
860 )
861}
862
863=item ($row, $col) = $line->coord_of ($offset)
583=item $text = $term->special_encode $string 864=item $text = $term->special_encode $string
584 865
585Converts a perl string into the special encoding used by rxvt-unicode, 866Converts a perl string into the special encoding used by rxvt-unicode,
586where one character corresponds to one screen cell. See 867where one character corresponds to one screen cell. See
587C<< $term->ROW_t >> for details. 868C<< $term->ROW_t >> for details.
701This variable controls the verbosity level of the perl extension. Higher 982This variable controls the verbosity level of the perl extension. Higher
702numbers indicate more verbose output. 983numbers indicate more verbose output.
703 984
704=over 4 985=over 4
705 986
706=item 0 - only fatal messages 987=item =0 - only fatal messages
707 988
708=item 3 - script loading and management 989=item =3 - script loading and management
709 990
710=item 10 - all events received 991=item =10 - all events received
711 992
712=back 993=back
713 994
714=head1 AUTHOR 995=head1 AUTHOR
715 996

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines