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.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
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.
68 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.
77
69=back 78=back
70 79
71=head2 General API Considerations 80=head2 General API Considerations
72 81
73All objects (such as terminals, time watchers etc.) are typical 82All objects (such as terminals, time watchers etc.) are typical
74reference-to-hash objects. The hash can be used to store anything you 83reference-to-hash objects. The hash can be used to store anything you
75like. All members starting with an underscore (such as C<_ptr> or 84like. All members starting with an underscore (such as C<_ptr> or
76C<_hook>) are reserved for internal uses and must not be accessed or 85C<_hook>) are reserved for internal uses and B<MUST NOT> be accessed or
77modified). 86modified).
78 87
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 called 118The following subroutines can be declared in loaded scripts, and will be
87whenever the relevant event happens. 119called whenever the relevant event happens.
120
121The first argument passed to them is an object private to each terminal
122and extension package. You can call all C<urxvt::term> methods on it, but
123its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
124object that is shared between all packages is stored in the C<term>
125member.
88 126
89All of them must return a boolean value. If it is true, then the event 127All 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, 128counts 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. 129and the relevant action might not be carried out by the C++ code.
92 130
164 202
165=item on_tty_activity $term *NYI* 203=item on_tty_activity $term *NYI*
166 204
167Called whenever the program(s) running in the urxvt window send output. 205Called whenever the program(s) running in the urxvt window send output.
168 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.
227
169=item on_refresh_begin $term 228=item on_refresh_begin $term
170 229
171Called just before the screen gets redrawn. Can be used for overlay 230Called just before the screen gets redrawn. Can be used for overlay
172or similar effects by modify terminal contents in refresh_begin, and 231or similar effects by modify terminal contents in refresh_begin, and
173restoring them in refresh_end. The built-in overlay and selection display 232restoring them in refresh_end. The built-in overlay and selection display
183C<perl:string> action bound to it (see description of the B<keysym> 242C<perl:string> action bound to it (see description of the B<keysym>
184resource in the @@RXVT_NAME@@(1) manpage). 243resource in the @@RXVT_NAME@@(1) manpage).
185 244
186=back 245=back
187 246
247=head2 Variables in the C<urxvt> Package
248
249=over 4
250
251=item $urxvt::TERM
252
253The current terminal. Whenever a callback/Hook is bein executed, this
254variable stores the current C<urxvt::term> object.
255
256=back
257
188=head2 Functions in the C<urxvt> Package 258=head2 Functions in the C<urxvt> Package
189 259
190=over 4 260=over 4
191 261
192=item urxvt::fatal $errormessage 262=item urxvt::fatal $errormessage
265=cut 335=cut
266 336
267package urxvt; 337package urxvt;
268 338
269use strict; 339use strict;
340use Scalar::Util ();
270 341
271our $term; 342our $TERM;
272our @HOOKNAME; 343our @HOOKNAME;
273our $LIBDIR; 344our $LIBDIR;
274 345
275BEGIN { 346BEGIN {
276 urxvt->bootstrap; 347 urxvt->bootstrap;
301 my $name = $HOOKNAME[$htype]; 372 my $name = $HOOKNAME[$htype];
302 373
303 my $ref = $pkg->can ("on_" . lc $name) 374 my $ref = $pkg->can ("on_" . lc $name)
304 or next; 375 or next;
305 376
306 $term->{_hook}[$htype]{$ref*1} = $ref; 377 $TERM->{_hook}[$htype]{$pkg} = $ref;
307 $hook_count[$htype]++ 378 $hook_count[$htype]++
308 or set_should_invoke $htype, 1; 379 or set_should_invoke $htype, 1;
309 } 380 }
310} 381}
311 382
333 404
334 $pkg 405 $pkg
335 } 406 }
336} 407}
337 408
409our $retval; # return value for urxvt
410
338# called by the rxvt core 411# called by the rxvt core
339sub invoke { 412sub invoke {
340 local $term = shift; 413 local $TERM = shift;
341 my $htype = shift; 414 my $htype = shift;
342 415
343 if ($htype == 0) { # INIT 416 if ($htype == 0) { # INIT
344 my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl"); 417 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
345 418
346 for my $ext (split /:/, $term->resource ("perl_ext")) { 419 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) {
347 my @files = grep -f $_, map "$_/$ext", @dirs; 420 my @files = grep -f $_, map "$_/$ext", @dirs;
348 421
349 if (@files) { 422 if (@files) {
350 register_package script_package $files[0]; 423 register_package script_package $files[0];
351 } else { 424 } else {
352 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";
353 } 426 }
354 } 427 }
428 }
355 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
356 } elsif ($htype == 1) { # DESTROY 450 if ($htype == 1) { # DESTROY
451 # remove hooks if unused
357 if (my $hook = $term->{_hook}) { 452 if (my $hook = $TERM->{_hook}) {
358 for my $htype (0..$#$hook) { 453 for my $htype (0..$#$hook) {
359 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 454 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
360 or set_should_invoke $htype, 0; 455 or set_should_invoke $htype, 0;
361 } 456 }
362 } 457 }
458
459 # clear package objects
460 %$_ = () for values %{ $TERM->{_pkg} };
461
462 # clear package
463 %$TERM = ();
363 } 464 }
364 465
365 my $cb = $term->{_hook}[$htype] 466 $retval
366 or return; 467}
367 468
368 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")" 469sub urxvt::term::proxy::AUTOLOAD {
369 if $verbosity >= 10; 470 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/
471 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable";
370 472
371 while (my ($k, $v) = each %$cb) { 473 eval qq{
372 return 1 if $v->($term, @_); 474 sub $urxvt::term::proxy::AUTOLOAD {
373 } 475 my \$proxy = shift;
476 \$proxy->{term}->$1 (\@_)
477 }
478 1
479 } or die "FATAL: unable to compile method forwarder: $@";
374 480
375 0 481 goto &$urxvt::term::proxy::AUTOLOAD;
376} 482}
377 483
378=head2 The C<urxvt::term> Class 484=head2 The C<urxvt::term> Class
379 485
380=over 4 486=over 4
403 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 509 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
404 borderLess color cursorBlink cursorUnderline cutchars delete_key 510 borderLess color cursorBlink cursorUnderline cutchars delete_key
405 display_name embed ext_bwidth fade font geometry hold iconName 511 display_name embed ext_bwidth fade font geometry hold iconName
406 imFont imLocale inputMethod insecure int_bwidth intensityStyles 512 imFont imLocale inputMethod insecure int_bwidth intensityStyles
407 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 513 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
408 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext 514 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
409 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 515 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
410 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 516 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
411 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 517 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
412 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 518 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
413 shade term_name title transparent transparent_all tripleclickwords 519 shade term_name title transparent transparent_all tripleclickwords
419 my ($self, $name) = (shift, shift); 525 my ($self, $name) = (shift, shift);
420 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 526 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
421 goto &urxvt::term::_resource; 527 goto &urxvt::term::_resource;
422} 528}
423 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
424=item ($row, $col) = $term->selection_mark ([$row, $col]) 540=item ($row, $col) = $term->selection_mark ([$row, $col])
425 541
426=item ($row, $col) = $term->selection_beg ([$row, $col]) 542=item ($row, $col) = $term->selection_beg ([$row, $col])
427 543
428=item ($row, $col) = $term->selection_end ([$row, $col]) 544=item ($row, $col) = $term->selection_end ([$row, $col])
442#=item $term->overlay ($x, $y, $text) 558#=item $term->overlay ($x, $y, $text)
443# 559#
444#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.
445# 561#
446#=cut 562#=cut
447 563#
448sub urxvt::term::scr_overlay { 564#sub urxvt::term::scr_overlay {
449die;
450 my ($self, $x, $y, $text) = @_; 565# my ($self, $x, $y, $text) = @_;
451 566#
452 my @lines = split /\n/, $text; 567# my @lines = split /\n/, $text;
453 568#
454 my $w = 0; 569# my $w = 0;
455 for (map $self->strwidth ($_), @lines) { 570# for (map $self->strwidth ($_), @lines) {
456 $w = $_ if $w < $_; 571# $w = $_ if $w < $_;
457 } 572# }
458 573#
459 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 574# $self->scr_overlay_new ($x, $y, $w, scalar @lines);
460 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 575# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
461} 576#}
462 577
463=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 578=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
464 579
465Create a new (empty) overlay at the given position with the given 580Create a new (empty) overlay at the given position with the given
466width/height. C<$rstyle> defines the initial rendition style 581width/height. C<$rstyle> defines the initial rendition style
506 621
507=item $string = $term->locale_decode $octets 622=item $string = $term->locale_decode $octets
508 623
509Convert the given locale-encoded octets into a perl string. 624Convert the given locale-encoded octets into a perl string.
510 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
511=item $term->tt_write ($octets) 637=item $term->tt_write ($octets)
512 638
513Write 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
514pass characters instead of octets, you should convert your strings first 640pass characters instead of octets, you should convert your strings first
515to the locale-specific encoding using C<< $term->locale_encode >>. 641to the locale-specific encoding using C<< $term->locale_encode >>.
516 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
517=item $nrow = $term->nrow 653=item $terminal_rows = $term->nrow
518 654
519=item $ncol = $term->ncol 655=item $terminal_columns = $term->ncol
520 656
521Return the number of rows/columns of the terminal window (i.e. as 657=item $has_focus = $term->focus
522specified by C<-geometry>, excluding any scrollback).
523 658
524=item $nsaved = $term->nsaved 659=item $is_mapped = $term->mapped
525 660
526Returns 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.
527 668
528=item $view_start = $term->view_start ([$newvalue]) 669=item $view_start = $term->view_start ([$newvalue])
529 670
530Returns the negative row number of the topmost line. Minimum value is 671Returns the negative row number of the topmost line. Minimum value is
531C<0>, which displays the normal terminal contents. Larger values scroll 672C<0>, which displays the normal terminal contents. Larger values scroll
542=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 683=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
543 684
544Returns the text of the entire row with number C<$row_number>. Row C<0> 685Returns 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 686is 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 687terminal line. The scrollback buffer starts at line C<-1> and extends to
547line C<< -$term->nsaved >>. 688line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line
689is requested.
548 690
549If C<$new_text> is specified, it will replace characters in the current 691If 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 692line, 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 693to replace only parts of a line. The font index in the rendition will
552automatically be updated. 694automatically be updated.
574 716
575See the section on RENDITION, above. 717See the section on RENDITION, above.
576 718
577=item $length = $term->ROW_l ($row_number[, $new_length]) 719=item $length = $term->ROW_l ($row_number[, $new_length])
578 720
579Returns the number of screen cells that are in use ("the line length"). If 721Returns 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 722length"). 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. 723line is joined with the following one.
582 724
725=item $bool = $term->is_longer ($row_number)
726
727Returns true if the row is part of a multiple-row logical "line" (i.e.
728joined with the following row), which means all characters are in use
729and it is continued on the next row (and possibly a continuation of the
730previous row(s)).
731
732=item $line = $term->line ($row_number)
733
734Create and return a new C<urxvt::line> object that stores information
735about the logical line that row C<$row_number> is part of. It supports the
736following methods:
737
738=over 4
739
740=item $text = $line->t
741
742Returns the full text of the line, similar to C<ROW_t>
743
744=item $rend = $line->r
745
746Returns the full rendition array of the line, similar to C<ROW_r>
747
748=item $length = $line->l
749
750Returns the length of the line in cells, similar to C<ROW_l>.
751
752=item $rownum = $line->beg
753
754=item $rownum = $line->end
755
756Return the row number of the first/last row of the line, respectively.
757
758=item $offset = $line->offset_of ($row, $col)
759
760Returns the character offset of the given row|col pair within the logical
761line.
762
763=item ($row, $col) = $line->coord_of ($offset)
764
765Translates a string offset into terminal coordinates again.
766
767=back
768
769=cut
770
771sub urxvt::term::line {
772 my ($self, $row) = @_;
773
774 my $maxrow = $self->nrow - 1;
775
776 my ($beg, $end) = ($row, $row);
777
778 --$beg while $self->ROW_is_longer ($beg - 1);
779 ++$end while $self->ROW_is_longer ($end) && $end < $maxrow;
780
781 bless {
782 term => $self,
783 beg => $beg,
784 end => $end,
785 ncol => $self->ncol,
786 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
787 }, urxvt::line::
788}
789
790sub urxvt::line::t {
791 my ($self) = @_;
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 &&
800 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
801 0, $self->{len}
802}
803
804sub urxvt::line::r {
805 my ($self) = @_;
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) {
814 my $rend = [
815 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
816 ];
817 $#$rend = $self->{len} - 1;
818 return $rend;
819 }
820
821 ()
822}
823
824sub urxvt::line::beg { $_[0]{beg} }
825sub urxvt::line::end { $_[0]{end} }
826sub urxvt::line::l { $_[0]{len} }
827
828sub urxvt::line::offset_of {
829 my ($self, $row, $col) = @_;
830
831 ($row - $self->{beg}) * $self->{ncol} + $col
832}
833
834sub urxvt::line::coord_of {
835 my ($self, $offset) = @_;
836
837 use integer;
838
839 (
840 $offset / $self->{ncol} + $self->{beg},
841 $offset % $self->{ncol}
842 )
843}
844
845=item ($row, $col) = $line->coord_of ($offset)
583=item $text = $term->special_encode $string 846=item $text = $term->special_encode $string
584 847
585Converts a perl string into the special encoding used by rxvt-unicode, 848Converts a perl string into the special encoding used by rxvt-unicode,
586where one character corresponds to one screen cell. See 849where one character corresponds to one screen cell. See
587C<< $term->ROW_t >> for details. 850C<< $term->ROW_t >> for details.
701This variable controls the verbosity level of the perl extension. Higher 964This variable controls the verbosity level of the perl extension. Higher
702numbers indicate more verbose output. 965numbers indicate more verbose output.
703 966
704=over 4 967=over 4
705 968
706=item 0 - only fatal messages 969=item =0 - only fatal messages
707 970
708=item 3 - script loading and management 971=item =3 - script loading and management
709 972
710=item 10 - all events received 973=item =10 - all events received
711 974
712=back 975=back
713 976
714=head1 AUTHOR 977=head1 AUTHOR
715 978

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines