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.28 by root, Wed Jan 4 00:09:12 2006 UTC vs.
Revision 1.40 by root, Fri Jan 6 05:37:59 2006 UTC

60 60
61=item digital-clock 61=item digital-clock
62 62
63Displays a digital clock using the built-in overlay. 63Displays a digital clock using the built-in overlay.
64 64
65=item mark-urls
66
67Uses per-line filtering (C<on_line_update>) to underline urls.
68
65=item example-refresh-hooks 69=item example-refresh-hooks
66 70
67Displays 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
68window. Illustrates overwriting the refresh callbacks to create your own 72window. Illustrates overwriting the refresh callbacks to create your own
69overlays or changes. 73overlays 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.
70 81
71=back 82=back
72 83
73=head2 General API Considerations 84=head2 General API Considerations
74 85
81When 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
82emptied, 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
83the 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
84terminal is destroyed. 95terminal is destroyed.
85 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
86=head2 Hooks 120=head2 Hooks
87 121
88The following subroutines can be declared in loaded scripts, and will be 122The following subroutines can be declared in loaded scripts, and will be
89called whenever the relevant event happens. 123called whenever the relevant event happens.
90 124
103=over 4 137=over 4
104 138
105=item on_init $term 139=item on_init $term
106 140
107Called after a new terminal object has been initialized, but before 141Called after a new terminal object has been initialized, but before
108windows are created or the command gets run. 142windows are created or the command gets run. Most methods are unsafe to
143call or deliver senseless data, as terminal size and other characteristics
144have not yet been determined. You can safely query and change resources,
145though.
109 146
110=item on_reset $term 147=item on_reset $term
111 148
112Called after the screen is "reset" for any reason, such as resizing or 149Called after the screen is "reset" for any reason, such as resizing or
113control sequences. Here is where you can react on changes to size-related 150control sequences. Here is where you can react on changes to size-related
174 211
175Called whenever the program(s) running in the urxvt window send output. 212Called whenever the program(s) running in the urxvt window send output.
176 213
177=item on_osc_seq $term, $string 214=item on_osc_seq $term, $string
178 215
179Called whenever the B<ESC ] 777 ; string ST> command sequence is 216Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
180processed. Cursor position and other state information is up-to-date when 217operating system command) is processed. Cursor position and other state
181this happens. For interoperability, the string should start with the 218information is up-to-date when this happens. For interoperability, the
182extension name and a colon, to distinguish it from commands for other 219string should start with the extension name and a colon, to distinguish
183extensions, and this might be enforced in the future. 220it from commands for other extensions, and this might be enforced in the
221future.
222
223Be careful not ever to trust (in a security sense) the data you receive,
224as its source can not easily be controleld (e-mail content, messages from
225other users on the same system etc.).
226
227=item on_add_lines $term, $string
228
229Called whenever text is about to be output, with the text as argument. You
230can filter/change and output the text yourself by returning a true value
231and calling C<< $term->scr_add_lines >> yourself. Please note that this
232might be very slow, however, as your hook is called for B<all> text being
233output.
234
235=item on_line_update $term, $row
236
237Called whenever a line was updated or changed. Can be used to filter
238screen output (e.g. underline urls or other useless stuff). Only lines
239that are being shown will be filtered, and, due to performance reasons,
240not always immediately.
241
242The row number is always the topmost row of the line if the line spans
243multiple rows.
244
245Please note that, if you change the line, then the hook might get called
246later with the already-modified line (e.g. if unrelated parts change), so
247you cannot just toggle rendition bits, but only set them.
184 248
185=item on_refresh_begin $term 249=item on_refresh_begin $term
186 250
187Called just before the screen gets redrawn. Can be used for overlay 251Called just before the screen gets redrawn. Can be used for overlay
188or similar effects by modify terminal contents in refresh_begin, and 252or similar effects by modify terminal contents in refresh_begin, and
197 261
198Called whenever the user presses a key combination that has a 262Called whenever the user presses a key combination that has a
199C<perl:string> action bound to it (see description of the B<keysym> 263C<perl:string> action bound to it (see description of the B<keysym>
200resource in the @@RXVT_NAME@@(1) manpage). 264resource in the @@RXVT_NAME@@(1) manpage).
201 265
266=item on_key_press $term, $event, $octets
267
268=item on_key_release $term, $event
269
270=item on_button_press $term, $event
271
272=item on_button_release $term, $event
273
274=item on_motion_notify $term, $event
275
276Called whenever the corresponding X event is received for the terminal If
277the hook returns true, then the even will be ignored by rxvt-unicode.
278
279The event is a hash with most values as named by Xlib (see the XEvent
280manpage), with the additional members C<row> and C<col>, which are the row
281and column under the mouse cursor.
282
283C<on_key_press> additionally receives the string rxvt-unicode would
284output, if any, in locale-specific encoding.
285
286subwindow.
287
202=back 288=back
203 289
204=head2 Variables in the C<urxvt> Package 290=head2 Variables in the C<urxvt> Package
205 291
206=over 4 292=over 4
213=back 299=back
214 300
215=head2 Functions in the C<urxvt> Package 301=head2 Functions in the C<urxvt> Package
216 302
217=over 4 303=over 4
304
305=item $term = new urxvt [arg...]
306
307Creates a new terminal, very similar as if you had started it with
308C<system $binfile, arg...>. Croaks (and probably outputs an error message)
309if the new instance couldn't be created. Returns C<undef> if the new
310instance didn't initialise perl, and the terminal object otherwise. The
311C<init> and C<start> hooks will be called during the call.
218 312
219=item urxvt::fatal $errormessage 313=item urxvt::fatal $errormessage
220 314
221Fatally aborts execution with the given error message. Avoid at all 315Fatally aborts execution with the given error message. Avoid at all
222costs! The only time this is acceptable is when the terminal process 316costs! The only time this is acceptable is when the terminal process
361 455
362 $pkg 456 $pkg
363 } 457 }
364} 458}
365 459
460our $retval; # return value for urxvt
461
366# called by the rxvt core 462# called by the rxvt core
367sub invoke { 463sub invoke {
368 local $TERM = shift; 464 local $TERM = shift;
369 my $htype = shift; 465 my $htype = shift;
370 466
371 if ($htype == 0) { # INIT 467 if ($htype == 0) { # INIT
372 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 468 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
373 469
374 for my $ext (split /:/, $TERM->resource ("perl_ext")) { 470 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) {
375 my @files = grep -f $_, map "$_/$ext", @dirs; 471 my @files = grep -f $_, map "$_/$ext", @dirs;
376 472
377 if (@files) { 473 if (@files) {
378 register_package script_package $files[0]; 474 register_package script_package $files[0];
379 } else { 475 } else {
380 warn "perl extension '$ext' not found in perl library search path\n"; 476 warn "perl extension '$ext' not found in perl library search path\n";
381 } 477 }
382 } 478 }
479 }
383 480
481 $retval = undef;
482
483 if (my $cb = $TERM->{_hook}[$htype]) {
484 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
485 if $verbosity >= 10;
486
487 keys %$cb;
488
489 while (my ($pkg, $cb) = each %$cb) {
490 $retval = $cb->(
491 $TERM->{_pkg}{$pkg} ||= do {
492 my $proxy = bless { }, urxvt::term::proxy::;
493 Scalar::Util::weaken ($proxy->{term} = $TERM);
494 $proxy
495 },
496 @_,
497 ) and last;
498 }
499 }
500
384 } elsif ($htype == 1) { # DESTROY 501 if ($htype == 1) { # DESTROY
502 # remove hooks if unused
385 if (my $hook = $TERM->{_hook}) { 503 if (my $hook = $TERM->{_hook}) {
386 for my $htype (0..$#$hook) { 504 for my $htype (0..$#$hook) {
387 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 505 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
388 or set_should_invoke $htype, 0; 506 or set_should_invoke $htype, 0;
389 } 507 }
390 } 508 }
509
510 # clear package objects
511 %$_ = () for values %{ $TERM->{_pkg} };
512
513 # clear package
514 %$TERM = ();
391 } 515 }
392 516
393 my $cb = $TERM->{_hook}[$htype] 517 $retval
394 or return;
395
396 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
397 if $verbosity >= 10;
398
399 keys %$cb;
400
401 while (my ($pkg, $cb) = each %$cb) {
402 return 1
403 if $cb->(
404 $TERM->{$pkg} ||= do {
405 my $proxy = bless { }, urxvt::term::proxy::;
406 Scalar::Util::weaken ($proxy->{term} = $TERM);
407 $proxy
408 },
409 @_,
410 );
411 }
412
413 0
414} 518}
415 519
416sub urxvt::term::proxy::AUTOLOAD { 520sub urxvt::term::proxy::AUTOLOAD {
417 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 521 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/
418 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 522 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable";
430 534
431=head2 The C<urxvt::term> Class 535=head2 The C<urxvt::term> Class
432 536
433=over 4 537=over 4
434 538
539=item $term->destroy
540
541Destroy the terminal object (close the window, free resources etc.).
542
435=item $value = $term->resource ($name[, $newval]) 543=item $value = $term->resource ($name[, $newval])
436 544
437Returns the current resource value associated with a given name and 545Returns the current resource value associated with a given name and
438optionally sets a new value. Setting values is most useful in the C<init> 546optionally sets a new value. Setting values is most useful in the C<init>
439hook. Unset resources are returned and accepted as C<undef>. 547hook. Unset resources are returned and accepted as C<undef>.
456 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 564 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
457 borderLess color cursorBlink cursorUnderline cutchars delete_key 565 borderLess color cursorBlink cursorUnderline cutchars delete_key
458 display_name embed ext_bwidth fade font geometry hold iconName 566 display_name embed ext_bwidth fade font geometry hold iconName
459 imFont imLocale inputMethod insecure int_bwidth intensityStyles 567 imFont imLocale inputMethod insecure int_bwidth intensityStyles
460 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 568 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
461 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext 569 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
462 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 570 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
463 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 571 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
464 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 572 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
465 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 573 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
466 shade term_name title transparent transparent_all tripleclickwords 574 shade term_name title transparent transparent_all tripleclickwords
472 my ($self, $name) = (shift, shift); 580 my ($self, $name) = (shift, shift);
473 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 581 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
474 goto &urxvt::term::_resource; 582 goto &urxvt::term::_resource;
475} 583}
476 584
585=item $rend = $term->rstyle ([$new_rstyle])
586
587Return and optionally change the current rendition. Text that is output by
588the terminal application will use this style.
589
590=item ($row, $col) = $term->screen_cur ([$row, $col])
591
592Return the current coordinates of the text cursor position and optionally
593set it (which is usually bad as applications don't expect that).
594
477=item ($row, $col) = $term->selection_mark ([$row, $col]) 595=item ($row, $col) = $term->selection_mark ([$row, $col])
478 596
479=item ($row, $col) = $term->selection_beg ([$row, $col]) 597=item ($row, $col) = $term->selection_beg ([$row, $col])
480 598
481=item ($row, $col) = $term->selection_end ([$row, $col]) 599=item ($row, $col) = $term->selection_end ([$row, $col])
495#=item $term->overlay ($x, $y, $text) 613#=item $term->overlay ($x, $y, $text)
496# 614#
497#Create a simple multi-line overlay box. See the next method for details. 615#Create a simple multi-line overlay box. See the next method for details.
498# 616#
499#=cut 617#=cut
500 618#
501sub urxvt::term::scr_overlay { 619#sub urxvt::term::scr_overlay {
502die;
503 my ($self, $x, $y, $text) = @_; 620# my ($self, $x, $y, $text) = @_;
504 621#
505 my @lines = split /\n/, $text; 622# my @lines = split /\n/, $text;
506 623#
507 my $w = 0; 624# my $w = 0;
508 for (map $self->strwidth ($_), @lines) { 625# for (map $self->strwidth ($_), @lines) {
509 $w = $_ if $w < $_; 626# $w = $_ if $w < $_;
510 } 627# }
511 628#
512 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 629# $self->scr_overlay_new ($x, $y, $w, scalar @lines);
513 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 630# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
514} 631#}
515 632
516=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 633=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
517 634
518Create a new (empty) overlay at the given position with the given 635Create a new (empty) overlay at the given position with the given
519width/height. C<$rstyle> defines the initial rendition style 636width/height. C<$rstyle> defines the initial rendition style
546 663
547If hidden, display the overlay again. 664If hidden, display the overlay again.
548 665
549=back 666=back
550 667
551=item $cellwidth = $term->strwidth $string 668=item $cellwidth = $term->strwidth ($string)
552 669
553Returns the number of screen-cells this string would need. Correctly 670Returns the number of screen-cells this string would need. Correctly
554accounts for wide and combining characters. 671accounts for wide and combining characters.
555 672
556=item $octets = $term->locale_encode $string 673=item $octets = $term->locale_encode ($string)
557 674
558Convert the given text string into the corresponding locale encoding. 675Convert the given text string into the corresponding locale encoding.
559 676
560=item $string = $term->locale_decode $octets 677=item $string = $term->locale_decode ($octets)
561 678
562Convert the given locale-encoded octets into a perl string. 679Convert the given locale-encoded octets into a perl string.
680
681=item $term->scr_add_lines ($string)
682
683Write the given text string to the screen, as if output by the application
684running inside the terminal. It may not contain command sequences (escape
685codes), but is free to use line feeds, carriage returns and tabs. The
686string is a normal text string, not in locale-dependent encoding.
687
688Normally its not a good idea to use this function, as programs might be
689confused by changes in cursor position or scrolling. Its useful inside a
690C<on_add_lines> hook, though.
691
692=item $term->cmd_parse ($octets)
693
694Similar to C<scr_add_lines>, but the argument must be in the
695locale-specific encoding of the terminal and can contain command sequences
696(escape codes) that will be interpreted.
563 697
564=item $term->tt_write ($octets) 698=item $term->tt_write ($octets)
565 699
566Write the octets given in C<$data> to the tty (i.e. as program input). To 700Write the octets given in C<$data> to the tty (i.e. as program input). To
567pass characters instead of octets, you should convert your strings first 701pass characters instead of octets, you should convert your strings first
568to the locale-specific encoding using C<< $term->locale_encode >>. 702to the locale-specific encoding using C<< $term->locale_encode >>.
569 703
704=item $windowid = $term->parent
705
706Return the window id of the toplevel window.
707
708=item $windowid = $term->vt
709
710Return the window id of the terminal window.
711
712=item $window_width = $term->width
713
714=item $window_height = $term->height
715
716=item $font_width = $term->fwidth
717
718=item $font_height = $term->fheight
719
720=item $font_ascent = $term->fbase
721
570=item $nrow = $term->nrow 722=item $terminal_rows = $term->nrow
571 723
572=item $ncol = $term->ncol 724=item $terminal_columns = $term->ncol
573 725
574Return the number of rows/columns of the terminal window (i.e. as 726=item $has_focus = $term->focus
575specified by C<-geometry>, excluding any scrollback).
576 727
577=item $nsaved = $term->nsaved 728=item $is_mapped = $term->mapped
578 729
579Returns the number of lines in the scrollback buffer. 730=item $max_scrollback = $term->saveLines
731
732=item $nrow_plus_saveLines = $term->total_rows
733
734=item $lines_in_scrollback = $term->nsaved
735
736Return various integers describing terminal characteristics.
580 737
581=item $view_start = $term->view_start ([$newvalue]) 738=item $view_start = $term->view_start ([$newvalue])
582 739
583Returns the negative row number of the topmost line. Minimum value is 740Returns the negative row number of the topmost line. Minimum value is
584C<0>, which displays the normal terminal contents. Larger values scroll 741C<0>, which displays the normal terminal contents. Larger values scroll
647about the logical line that row C<$row_number> is part of. It supports the 804about the logical line that row C<$row_number> is part of. It supports the
648following methods: 805following methods:
649 806
650=over 4 807=over 4
651 808
652=item $text = $line->t 809=item $text = $line->t ([$new_text])
653 810
654Returns the full text of the line, similar to C<ROW_t> 811Returns or replaces the full text of the line, similar to C<ROW_t>
655 812
656=item $rend = $line->r 813=item $rend = $line->r ([$new_rend])
657 814
658Returns the full rendition array of the line, similar to C<ROW_r> 815Returns or replaces the full rendition array of the line, similar to C<ROW_r>
659 816
660=item $length = $line->l 817=item $length = $line->l
661 818
662Returns the length of the line in cells, similar to C<ROW_l>. 819Returns the length of the line in cells, similar to C<ROW_l>.
663 820
692 849
693 bless { 850 bless {
694 term => $self, 851 term => $self,
695 beg => $beg, 852 beg => $beg,
696 end => $end, 853 end => $end,
854 ncol => $self->ncol,
697 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end), 855 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
698 }, urxvt::line:: 856 }, urxvt::line::
699} 857}
700 858
701sub urxvt::line::t { 859sub urxvt::line::t {
702 my ($self) = @_; 860 my ($self) = @_;
703 861
862 if (@_ > 1)
863 {
864 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
865 for $self->{beg} .. $self->{end};
866 }
867
868 defined wantarray &&
704 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 869 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
705 0, $self->{len} 870 0, $self->{len}
706} 871}
707 872
708sub urxvt::line::r { 873sub urxvt::line::r {
709 my ($self) = @_; 874 my ($self) = @_;
710 875
876 if (@_ > 1)
877 {
878 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
879 for $self->{beg} .. $self->{end};
880 }
881
882 if (defined wantarray) {
711 my $rend = [ 883 my $rend = [
712 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 884 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
713 ]; 885 ];
714 $#$rend = $self->{len} - 1; 886 $#$rend = $self->{len} - 1;
715 $rend 887 return $rend;
888 }
889
890 ()
716} 891}
717 892
718sub urxvt::line::beg { $_[0]{beg} } 893sub urxvt::line::beg { $_[0]{beg} }
719sub urxvt::line::end { $_[0]{end} } 894sub urxvt::line::end { $_[0]{end} }
720sub urxvt::line::l { $_[0]{len} } 895sub urxvt::line::l { $_[0]{len} }
721 896
722sub urxvt::line::offset_of { 897sub urxvt::line::offset_of {
723 my ($self, $row, $col) = @_; 898 my ($self, $row, $col) = @_;
724 899
725 ($row - $self->{beg}) * $self->{term}->ncol + $col 900 ($row - $self->{beg}) * $self->{ncol} + $col
726} 901}
727 902
728sub urxvt::line::coord_of { 903sub urxvt::line::coord_of {
729 my ($self, $offset) = @_; 904 my ($self, $offset) = @_;
730 905
731 use integer; 906 use integer;
732 907
733 ( 908 (
734 $offset / $self->{term}->ncol + $self->{beg}, 909 $offset / $self->{ncol} + $self->{beg},
735 $offset % $self->{term}->ncol 910 $offset % $self->{ncol}
736 ) 911 )
737} 912}
738 913
739=item ($row, $col) = $line->coord_of ($offset) 914=item ($row, $col) = $line->coord_of ($offset)
740=item $text = $term->special_encode $string 915=item $text = $term->special_encode $string

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines