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.37 by root, Fri Jan 6 03:40:19 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.
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.
68 81
69=back 82=back
70 83
71=head2 General API Considerations 84=head2 General API Considerations
72 85
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 122The following subroutines can be declared in loaded scripts, and will be
87called whenever the relevant event happens. 123called whenever the relevant event happens.
88 124
101=over 4 137=over 4
102 138
103=item on_init $term 139=item on_init $term
104 140
105Called after a new terminal object has been initialized, but before 141Called after a new terminal object has been initialized, but before
106windows 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.
107 146
108=item on_reset $term 147=item on_reset $term
109 148
110Called 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
111control 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
170 209
171=item on_tty_activity $term *NYI* 210=item on_tty_activity $term *NYI*
172 211
173Called whenever the program(s) running in the urxvt window send output. 212Called whenever the program(s) running in the urxvt window send output.
174 213
214=item on_osc_seq $term, $string
215
216Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
217operating system command) is processed. Cursor position and other state
218information is up-to-date when this happens. For interoperability, the
219string should start with the extension name and a colon, to distinguish
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.
248
175=item on_refresh_begin $term 249=item on_refresh_begin $term
176 250
177Called just before the screen gets redrawn. Can be used for overlay 251Called just before the screen gets redrawn. Can be used for overlay
178or similar effects by modify terminal contents in refresh_begin, and 252or similar effects by modify terminal contents in refresh_begin, and
179restoring them in refresh_end. The built-in overlay and selection display 253restoring them in refresh_end. The built-in overlay and selection display
187 261
188Called whenever the user presses a key combination that has a 262Called whenever the user presses a key combination that has a
189C<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>
190resource in the @@RXVT_NAME@@(1) manpage). 264resource in the @@RXVT_NAME@@(1) manpage).
191 265
266=item on_key_press $term, $event
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
279subwindow.
280
192=back 281=back
193 282
194=head2 Variables in the C<urxvt> Package 283=head2 Variables in the C<urxvt> Package
195 284
196=over 4 285=over 4
203=back 292=back
204 293
205=head2 Functions in the C<urxvt> Package 294=head2 Functions in the C<urxvt> Package
206 295
207=over 4 296=over 4
297
298=item $term = new urxvt [arg...]
299
300Creates a new terminal, very similar as if you had started it with
301C<system $binfile, arg...>. Croaks (and probably outputs an error message)
302if the new instance couldn't be created. Returns C<undef> if the new
303instance didn't initialise perl, and the terminal object otherwise. The
304C<init> and C<start> hooks will be called during the call.
208 305
209=item urxvt::fatal $errormessage 306=item urxvt::fatal $errormessage
210 307
211Fatally aborts execution with the given error message. Avoid at all 308Fatally aborts execution with the given error message. Avoid at all
212costs! The only time this is acceptable is when the terminal process 309costs! The only time this is acceptable is when the terminal process
351 448
352 $pkg 449 $pkg
353 } 450 }
354} 451}
355 452
453our $retval; # return value for urxvt
454
356# called by the rxvt core 455# called by the rxvt core
357sub invoke { 456sub invoke {
358 local $TERM = shift; 457 local $TERM = shift;
359 my $htype = shift; 458 my $htype = shift;
360 459
361 if ($htype == 0) { # INIT 460 if ($htype == 0) { # INIT
362 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 461 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
363 462
364 for my $ext (split /:/, $TERM->resource ("perl_ext")) { 463 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) {
365 my @files = grep -f $_, map "$_/$ext", @dirs; 464 my @files = grep -f $_, map "$_/$ext", @dirs;
366 465
367 if (@files) { 466 if (@files) {
368 register_package script_package $files[0]; 467 register_package script_package $files[0];
369 } else { 468 } else {
370 warn "perl extension '$ext' not found in perl library search path\n"; 469 warn "perl extension '$ext' not found in perl library search path\n";
371 } 470 }
372 } 471 }
472 }
373 473
474 $retval = undef;
475
476 if (my $cb = $TERM->{_hook}[$htype]) {
477 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
478 if $verbosity >= 10;
479
480 keys %$cb;
481
482 while (my ($pkg, $cb) = each %$cb) {
483 $retval = $cb->(
484 $TERM->{_pkg}{$pkg} ||= do {
485 my $proxy = bless { }, urxvt::term::proxy::;
486 Scalar::Util::weaken ($proxy->{term} = $TERM);
487 $proxy
488 },
489 @_,
490 ) and last;
491 }
492 }
493
374 } elsif ($htype == 1) { # DESTROY 494 if ($htype == 1) { # DESTROY
495 # remove hooks if unused
375 if (my $hook = $TERM->{_hook}) { 496 if (my $hook = $TERM->{_hook}) {
376 for my $htype (0..$#$hook) { 497 for my $htype (0..$#$hook) {
377 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 498 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
378 or set_should_invoke $htype, 0; 499 or set_should_invoke $htype, 0;
379 } 500 }
380 } 501 }
502
503 # clear package objects
504 %$_ = () for values %{ $TERM->{_pkg} };
505
506 # clear package
507 %$TERM = ();
381 } 508 }
382 509
383 my $cb = $TERM->{_hook}[$htype] 510 $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} 511}
403 512
404sub urxvt::term::proxy::AUTOLOAD { 513sub urxvt::term::proxy::AUTOLOAD {
405 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 514 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/
406 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 515 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable";
418 527
419=head2 The C<urxvt::term> Class 528=head2 The C<urxvt::term> Class
420 529
421=over 4 530=over 4
422 531
532=item $term->destroy
533
534Destroy the terminal object (close the window, free resources etc.).
535
423=item $value = $term->resource ($name[, $newval]) 536=item $value = $term->resource ($name[, $newval])
424 537
425Returns the current resource value associated with a given name and 538Returns the current resource value associated with a given name and
426optionally sets a new value. Setting values is most useful in the C<init> 539optionally sets a new value. Setting values is most useful in the C<init>
427hook. Unset resources are returned and accepted as C<undef>. 540hook. Unset resources are returned and accepted as C<undef>.
444 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 557 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
445 borderLess color cursorBlink cursorUnderline cutchars delete_key 558 borderLess color cursorBlink cursorUnderline cutchars delete_key
446 display_name embed ext_bwidth fade font geometry hold iconName 559 display_name embed ext_bwidth fade font geometry hold iconName
447 imFont imLocale inputMethod insecure int_bwidth intensityStyles 560 imFont imLocale inputMethod insecure int_bwidth intensityStyles
448 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 561 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
449 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext 562 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
450 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 563 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
451 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 564 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
452 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 565 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
453 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 566 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
454 shade term_name title transparent transparent_all tripleclickwords 567 shade term_name title transparent transparent_all tripleclickwords
460 my ($self, $name) = (shift, shift); 573 my ($self, $name) = (shift, shift);
461 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 574 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
462 goto &urxvt::term::_resource; 575 goto &urxvt::term::_resource;
463} 576}
464 577
578=item $rend = $term->rstyle ([$new_rstyle])
579
580Return and optionally change the current rendition. Text that is output by
581the terminal application will use this style.
582
583=item ($row, $col) = $term->screen_cur ([$row, $col])
584
585Return the current coordinates of the text cursor position and optionally
586set it (which is usually bad as applications don't expect that).
587
465=item ($row, $col) = $term->selection_mark ([$row, $col]) 588=item ($row, $col) = $term->selection_mark ([$row, $col])
466 589
467=item ($row, $col) = $term->selection_beg ([$row, $col]) 590=item ($row, $col) = $term->selection_beg ([$row, $col])
468 591
469=item ($row, $col) = $term->selection_end ([$row, $col]) 592=item ($row, $col) = $term->selection_end ([$row, $col])
483#=item $term->overlay ($x, $y, $text) 606#=item $term->overlay ($x, $y, $text)
484# 607#
485#Create a simple multi-line overlay box. See the next method for details. 608#Create a simple multi-line overlay box. See the next method for details.
486# 609#
487#=cut 610#=cut
488 611#
489sub urxvt::term::scr_overlay { 612#sub urxvt::term::scr_overlay {
490die;
491 my ($self, $x, $y, $text) = @_; 613# my ($self, $x, $y, $text) = @_;
492 614#
493 my @lines = split /\n/, $text; 615# my @lines = split /\n/, $text;
494 616#
495 my $w = 0; 617# my $w = 0;
496 for (map $self->strwidth ($_), @lines) { 618# for (map $self->strwidth ($_), @lines) {
497 $w = $_ if $w < $_; 619# $w = $_ if $w < $_;
498 } 620# }
499 621#
500 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 622# $self->scr_overlay_new ($x, $y, $w, scalar @lines);
501 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 623# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
502} 624#}
503 625
504=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 626=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
505 627
506Create a new (empty) overlay at the given position with the given 628Create a new (empty) overlay at the given position with the given
507width/height. C<$rstyle> defines the initial rendition style 629width/height. C<$rstyle> defines the initial rendition style
547 669
548=item $string = $term->locale_decode $octets 670=item $string = $term->locale_decode $octets
549 671
550Convert the given locale-encoded octets into a perl string. 672Convert the given locale-encoded octets into a perl string.
551 673
674=item $term->scr_add_lines ($string)
675
676Write the given text string to the screen, as if output by the application
677running inside the terminal. It may not contain command sequences (escape
678codes), but is free to use line feeds, carriage returns and tabs. The
679string is a normal text string, not in locale-dependent encoding.
680
681Normally its not a good idea to use this function, as programs might be
682confused by changes in cursor position or scrolling. Its useful inside a
683C<on_add_lines> hook, though.
684
685=item $term->cmd_parse ($octets)
686
687Similar to C<scr_add_lines>, but the argument must be in the
688locale-specific encoding of the terminal and can contain command sequences
689(escape codes) that will be interpreted.
690
552=item $term->tt_write ($octets) 691=item $term->tt_write ($octets)
553 692
554Write the octets given in C<$data> to the tty (i.e. as program input). To 693Write 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 694pass characters instead of octets, you should convert your strings first
556to the locale-specific encoding using C<< $term->locale_encode >>. 695to the locale-specific encoding using C<< $term->locale_encode >>.
557 696
697=item $window_width = $term->width
698
699=item $window_height = $term->height
700
701=item $font_width = $term->fwidth
702
703=item $font_height = $term->fheight
704
705=item $font_ascent = $term->fbase
706
558=item $nrow = $term->nrow 707=item $terminal_rows = $term->nrow
559 708
560=item $ncol = $term->ncol 709=item $terminal_columns = $term->ncol
561 710
562Return the number of rows/columns of the terminal window (i.e. as 711=item $has_focus = $term->focus
563specified by C<-geometry>, excluding any scrollback).
564 712
565=item $nsaved = $term->nsaved 713=item $is_mapped = $term->mapped
566 714
567Returns the number of lines in the scrollback buffer. 715=item $max_scrollback = $term->saveLines
716
717=item $nrow_plus_saveLines = $term->total_rows
718
719=item $lines_in_scrollback = $term->nsaved
720
721Return various integers describing terminal characteristics.
568 722
569=item $view_start = $term->view_start ([$newvalue]) 723=item $view_start = $term->view_start ([$newvalue])
570 724
571Returns the negative row number of the topmost line. Minimum value is 725Returns the negative row number of the topmost line. Minimum value is
572C<0>, which displays the normal terminal contents. Larger values scroll 726C<0>, which displays the normal terminal contents. Larger values scroll
635about the logical line that row C<$row_number> is part of. It supports the 789about the logical line that row C<$row_number> is part of. It supports the
636following methods: 790following methods:
637 791
638=over 4 792=over 4
639 793
640=item $text = $line->t 794=item $text = $line->t ([$new_text])
641 795
642Returns the full text of the line, similar to C<ROW_t> 796Returns or replaces the full text of the line, similar to C<ROW_t>
643 797
644=item $rend = $line->r 798=item $rend = $line->r ([$new_rend])
645 799
646Returns the full rendition array of the line, similar to C<ROW_r> 800Returns or replaces the full rendition array of the line, similar to C<ROW_r>
647 801
648=item $length = $line->l 802=item $length = $line->l
649 803
650Returns the length of the line in cells, similar to C<ROW_l>. 804Returns the length of the line in cells, similar to C<ROW_l>.
651 805
680 834
681 bless { 835 bless {
682 term => $self, 836 term => $self,
683 beg => $beg, 837 beg => $beg,
684 end => $end, 838 end => $end,
839 ncol => $self->ncol,
685 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end), 840 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
686 }, urxvt::line:: 841 }, urxvt::line::
687} 842}
688 843
689sub urxvt::line::t { 844sub urxvt::line::t {
690 my ($self) = @_; 845 my ($self) = @_;
691 846
847 if (@_ > 1)
848 {
849 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
850 for $self->{beg} .. $self->{end};
851 }
852
853 defined wantarray &&
692 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 854 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
693 0, $self->{len} 855 0, $self->{len}
694} 856}
695 857
696sub urxvt::line::r { 858sub urxvt::line::r {
697 my ($self) = @_; 859 my ($self) = @_;
698 860
861 if (@_ > 1)
862 {
863 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
864 for $self->{beg} .. $self->{end};
865 }
866
867 if (defined wantarray) {
699 my $rend = [ 868 my $rend = [
700 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 869 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
701 ]; 870 ];
702 $#$rend = $self->{len} - 1; 871 $#$rend = $self->{len} - 1;
703 $rend 872 return $rend;
873 }
874
875 ()
704} 876}
705 877
706sub urxvt::line::beg { $_[0]{beg} } 878sub urxvt::line::beg { $_[0]{beg} }
707sub urxvt::line::end { $_[0]{end} } 879sub urxvt::line::end { $_[0]{end} }
708sub urxvt::line::l { $_[0]{len} } 880sub urxvt::line::l { $_[0]{len} }
709 881
710sub urxvt::line::offset_of { 882sub urxvt::line::offset_of {
711 my ($self, $row, $col) = @_; 883 my ($self, $row, $col) = @_;
712 884
713 ($row - $self->{beg}) * $self->{term}->ncol + $col 885 ($row - $self->{beg}) * $self->{ncol} + $col
714} 886}
715 887
716sub urxvt::line::coord_of { 888sub urxvt::line::coord_of {
717 my ($self, $offset) = @_; 889 my ($self, $offset) = @_;
718 890
719 use integer; 891 use integer;
720 892
721 ( 893 (
722 $offset / $self->{term}->ncol + $self->{beg}, 894 $offset / $self->{ncol} + $self->{beg},
723 $offset % $self->{term}->ncol 895 $offset % $self->{ncol}
724 ) 896 )
725} 897}
726 898
727=item ($row, $col) = $line->coord_of ($offset) 899=item ($row, $col) = $line->coord_of ($offset)
728=item $text = $term->special_encode $string 900=item $text = $term->special_encode $string
846This variable controls the verbosity level of the perl extension. Higher 1018This variable controls the verbosity level of the perl extension. Higher
847numbers indicate more verbose output. 1019numbers indicate more verbose output.
848 1020
849=over 4 1021=over 4
850 1022
851=item 0 - only fatal messages 1023=item =0 - only fatal messages
852 1024
853=item 3 - script loading and management 1025=item =3 - script loading and management
854 1026
855=item 10 - all events received 1027=item =10 - all events received
856 1028
857=back 1029=back
858 1030
859=head1 AUTHOR 1031=head1 AUTHOR
860 1032

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines