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.25 by root, Tue Jan 3 21:08:39 2006 UTC vs.
Revision 1.39 by root, Fri Jan 6 05:28:55 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, $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
192=back 288=back
193 289
194=head2 Variables in the C<urxvt> Package 290=head2 Variables in the C<urxvt> Package
195 291
196=over 4 292=over 4
203=back 299=back
204 300
205=head2 Functions in the C<urxvt> Package 301=head2 Functions in the C<urxvt> Package
206 302
207=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.
208 312
209=item urxvt::fatal $errormessage 313=item urxvt::fatal $errormessage
210 314
211Fatally aborts execution with the given error message. Avoid at all 315Fatally aborts execution with the given error message. Avoid at all
212costs! The only time this is acceptable is when the terminal process 316costs! The only time this is acceptable is when the terminal process
351 455
352 $pkg 456 $pkg
353 } 457 }
354} 458}
355 459
460our $retval; # return value for urxvt
461
356# called by the rxvt core 462# called by the rxvt core
357sub invoke { 463sub invoke {
358 local $TERM = shift; 464 local $TERM = shift;
359 my $htype = shift; 465 my $htype = shift;
360 466
361 if ($htype == 0) { # INIT 467 if ($htype == 0) { # INIT
362 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 468 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
363 469
364 for my $ext (split /:/, $TERM->resource ("perl_ext")) { 470 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) {
365 my @files = grep -f $_, map "$_/$ext", @dirs; 471 my @files = grep -f $_, map "$_/$ext", @dirs;
366 472
367 if (@files) { 473 if (@files) {
368 register_package script_package $files[0]; 474 register_package script_package $files[0];
369 } else { 475 } else {
370 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";
371 } 477 }
372 } 478 }
479 }
373 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
374 } elsif ($htype == 1) { # DESTROY 501 if ($htype == 1) { # DESTROY
502 # remove hooks if unused
375 if (my $hook = $TERM->{_hook}) { 503 if (my $hook = $TERM->{_hook}) {
376 for my $htype (0..$#$hook) { 504 for my $htype (0..$#$hook) {
377 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 505 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
378 or set_should_invoke $htype, 0; 506 or set_should_invoke $htype, 0;
379 } 507 }
380 } 508 }
509
510 # clear package objects
511 %$_ = () for values %{ $TERM->{_pkg} };
512
513 # clear package
514 %$TERM = ();
381 } 515 }
382 516
383 my $cb = $TERM->{_hook}[$htype] 517 $retval
384 or return;
385
386 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
387 if $verbosity >= 10;
388
389 keys %$cb;
390
391 while (my ($pkg, $cb) = each %$cb) {
392 return 1
393 if $cb->(
394 $TERM->{$pkg} ||= do {
395 my $proxy = bless { }, urxvt::term::proxy::;
396 Scalar::Util::weaken ($proxy->{term} = $TERM);
397 $proxy
398 },
399 @_,
400 );
401 }
402
403 0
404} 518}
405 519
406sub urxvt::term::proxy::AUTOLOAD { 520sub urxvt::term::proxy::AUTOLOAD {
407 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 521 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/
408 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 522 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable";
420 534
421=head2 The C<urxvt::term> Class 535=head2 The C<urxvt::term> Class
422 536
423=over 4 537=over 4
424 538
539=item $term->destroy
540
541Destroy the terminal object (close the window, free resources etc.).
542
425=item $value = $term->resource ($name[, $newval]) 543=item $value = $term->resource ($name[, $newval])
426 544
427Returns the current resource value associated with a given name and 545Returns the current resource value associated with a given name and
428optionally 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>
429hook. Unset resources are returned and accepted as C<undef>. 547hook. Unset resources are returned and accepted as C<undef>.
446 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 564 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
447 borderLess color cursorBlink cursorUnderline cutchars delete_key 565 borderLess color cursorBlink cursorUnderline cutchars delete_key
448 display_name embed ext_bwidth fade font geometry hold iconName 566 display_name embed ext_bwidth fade font geometry hold iconName
449 imFont imLocale inputMethod insecure int_bwidth intensityStyles 567 imFont imLocale inputMethod insecure int_bwidth intensityStyles
450 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 568 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
451 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext 569 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
452 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 570 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
453 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 571 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
454 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 572 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
455 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 573 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
456 shade term_name title transparent transparent_all tripleclickwords 574 shade term_name title transparent transparent_all tripleclickwords
462 my ($self, $name) = (shift, shift); 580 my ($self, $name) = (shift, shift);
463 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 581 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
464 goto &urxvt::term::_resource; 582 goto &urxvt::term::_resource;
465} 583}
466 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
467=item ($row, $col) = $term->selection_mark ([$row, $col]) 595=item ($row, $col) = $term->selection_mark ([$row, $col])
468 596
469=item ($row, $col) = $term->selection_beg ([$row, $col]) 597=item ($row, $col) = $term->selection_beg ([$row, $col])
470 598
471=item ($row, $col) = $term->selection_end ([$row, $col]) 599=item ($row, $col) = $term->selection_end ([$row, $col])
485#=item $term->overlay ($x, $y, $text) 613#=item $term->overlay ($x, $y, $text)
486# 614#
487#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.
488# 616#
489#=cut 617#=cut
490 618#
491sub urxvt::term::scr_overlay { 619#sub urxvt::term::scr_overlay {
492die;
493 my ($self, $x, $y, $text) = @_; 620# my ($self, $x, $y, $text) = @_;
494 621#
495 my @lines = split /\n/, $text; 622# my @lines = split /\n/, $text;
496 623#
497 my $w = 0; 624# my $w = 0;
498 for (map $self->strwidth ($_), @lines) { 625# for (map $self->strwidth ($_), @lines) {
499 $w = $_ if $w < $_; 626# $w = $_ if $w < $_;
500 } 627# }
501 628#
502 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 629# $self->scr_overlay_new ($x, $y, $w, scalar @lines);
503 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 630# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
504} 631#}
505 632
506=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 633=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
507 634
508Create a new (empty) overlay at the given position with the given 635Create a new (empty) overlay at the given position with the given
509width/height. C<$rstyle> defines the initial rendition style 636width/height. C<$rstyle> defines the initial rendition style
549 676
550=item $string = $term->locale_decode $octets 677=item $string = $term->locale_decode $octets
551 678
552Convert the given locale-encoded octets into a perl string. 679Convert the given locale-encoded octets into a perl string.
553 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.
697
554=item $term->tt_write ($octets) 698=item $term->tt_write ($octets)
555 699
556Write 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
557pass characters instead of octets, you should convert your strings first 701pass characters instead of octets, you should convert your strings first
558to the locale-specific encoding using C<< $term->locale_encode >>. 702to the locale-specific encoding using C<< $term->locale_encode >>.
559 703
704=item $window_width = $term->width
705
706=item $window_height = $term->height
707
708=item $font_width = $term->fwidth
709
710=item $font_height = $term->fheight
711
712=item $font_ascent = $term->fbase
713
560=item $nrow = $term->nrow 714=item $terminal_rows = $term->nrow
561 715
562=item $ncol = $term->ncol 716=item $terminal_columns = $term->ncol
563 717
564Return the number of rows/columns of the terminal window (i.e. as 718=item $has_focus = $term->focus
565specified by C<-geometry>, excluding any scrollback).
566 719
567=item $nsaved = $term->nsaved 720=item $is_mapped = $term->mapped
568 721
569Returns the number of lines in the scrollback buffer. 722=item $max_scrollback = $term->saveLines
723
724=item $nrow_plus_saveLines = $term->total_rows
725
726=item $lines_in_scrollback = $term->nsaved
727
728Return various integers describing terminal characteristics.
570 729
571=item $view_start = $term->view_start ([$newvalue]) 730=item $view_start = $term->view_start ([$newvalue])
572 731
573Returns the negative row number of the topmost line. Minimum value is 732Returns the negative row number of the topmost line. Minimum value is
574C<0>, which displays the normal terminal contents. Larger values scroll 733C<0>, which displays the normal terminal contents. Larger values scroll
637about the logical line that row C<$row_number> is part of. It supports the 796about the logical line that row C<$row_number> is part of. It supports the
638following methods: 797following methods:
639 798
640=over 4 799=over 4
641 800
642=item $text = $line->t 801=item $text = $line->t ([$new_text])
643 802
644Returns the full text of the line, similar to C<ROW_t> 803Returns or replaces the full text of the line, similar to C<ROW_t>
645 804
646=item $rend = $line->r 805=item $rend = $line->r ([$new_rend])
647 806
648Returns the full rendition array of the line, similar to C<ROW_r> 807Returns or replaces the full rendition array of the line, similar to C<ROW_r>
649 808
650=item $length = $line->l 809=item $length = $line->l
651 810
652Returns the length of the line in cells, similar to C<ROW_l>. 811Returns the length of the line in cells, similar to C<ROW_l>.
653 812
682 841
683 bless { 842 bless {
684 term => $self, 843 term => $self,
685 beg => $beg, 844 beg => $beg,
686 end => $end, 845 end => $end,
846 ncol => $self->ncol,
687 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end), 847 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
688 }, urxvt::line:: 848 }, urxvt::line::
689} 849}
690 850
691sub urxvt::line::t { 851sub urxvt::line::t {
692 my ($self) = @_; 852 my ($self) = @_;
693 853
854 if (@_ > 1)
855 {
856 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
857 for $self->{beg} .. $self->{end};
858 }
859
860 defined wantarray &&
694 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 861 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
695 0, $self->{len} 862 0, $self->{len}
696} 863}
697 864
698sub urxvt::line::r { 865sub urxvt::line::r {
699 my ($self) = @_; 866 my ($self) = @_;
700 867
868 if (@_ > 1)
869 {
870 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
871 for $self->{beg} .. $self->{end};
872 }
873
874 if (defined wantarray) {
701 my $rend = [ 875 my $rend = [
702 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 876 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
703 ]; 877 ];
704 $#$rend = $self->{len} - 1; 878 $#$rend = $self->{len} - 1;
705 $rend 879 return $rend;
880 }
881
882 ()
706} 883}
707 884
708sub urxvt::line::beg { $_[0]{beg} } 885sub urxvt::line::beg { $_[0]{beg} }
709sub urxvt::line::end { $_[0]{end} } 886sub urxvt::line::end { $_[0]{end} }
710sub urxvt::line::l { $_[0]{len} } 887sub urxvt::line::l { $_[0]{len} }
711 888
712sub urxvt::line::offset_of { 889sub urxvt::line::offset_of {
713 my ($self, $row, $col) = @_; 890 my ($self, $row, $col) = @_;
714 891
715 ($row - $self->{beg}) * $self->{term}->ncol + $col 892 ($row - $self->{beg}) * $self->{ncol} + $col
716} 893}
717 894
718sub urxvt::line::coord_of { 895sub urxvt::line::coord_of {
719 my ($self, $offset) = @_; 896 my ($self, $offset) = @_;
720 897
721 use integer; 898 use integer;
722 899
723 ( 900 (
724 $offset / $self->{term}->ncol + $self->{beg}, 901 $offset / $self->{ncol} + $self->{beg},
725 $offset % $self->{term}->ncol 902 $offset % $self->{ncol}
726 ) 903 )
727} 904}
728 905
729=item ($row, $col) = $line->coord_of ($offset) 906=item ($row, $col) = $line->coord_of ($offset)
730=item $text = $term->special_encode $string 907=item $text = $term->special_encode $string
848This variable controls the verbosity level of the perl extension. Higher 1025This variable controls the verbosity level of the perl extension. Higher
849numbers indicate more verbose output. 1026numbers indicate more verbose output.
850 1027
851=over 4 1028=over 4
852 1029
853=item 0 - only fatal messages 1030=item =0 - only fatal messages
854 1031
855=item 3 - script loading and management 1032=item =3 - script loading and management
856 1033
857=item 10 - all events received 1034=item =10 - all events received
858 1035
859=back 1036=back
860 1037
861=head1 AUTHOR 1038=head1 AUTHOR
862 1039

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines