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.27 by root, Tue Jan 3 23:41:37 2006 UTC vs.
Revision 1.33 by root, Thu Jan 5 01:04:10 2006 UTC

… …
65=item example-refresh-hooks 65=item example-refresh-hooks
66 66
67Displays 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
68window. Illustrates overwriting the refresh callbacks to create your own 68window. Illustrates overwriting the refresh callbacks to create your own
69overlays or changes. 69overlays or changes.
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.
70 77
71=back 78=back
72 79
73=head2 General API Considerations 80=head2 General API Considerations
74 81
… …
81When 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
82emptied, 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
83the 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
84terminal is destroyed. 91terminal is destroyed.
85 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
86=head2 Hooks 116=head2 Hooks
87 117
88The following subroutines can be declared in loaded scripts, and will be 118The following subroutines can be declared in loaded scripts, and will be
89called whenever the relevant event happens. 119called whenever the relevant event happens.
90 120
… …
171number of lines that will be in the scrollback buffer. 201number of lines that will be in the scrollback buffer.
172 202
173=item on_tty_activity $term *NYI* 203=item on_tty_activity $term *NYI*
174 204
175Called whenever the program(s) running in the urxvt window send output. 205Called whenever the program(s) running in the urxvt window send output.
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.
176 227
177=item on_refresh_begin $term 228=item on_refresh_begin $term
178 229
179Called just before the screen gets redrawn. Can be used for overlay 230Called just before the screen gets redrawn. Can be used for overlay
180or similar effects by modify terminal contents in refresh_begin, and 231or similar effects by modify terminal contents in refresh_begin, and
… …
353 404
354 $pkg 405 $pkg
355 } 406 }
356} 407}
357 408
409our $retval; # return value for urxvt
410
358# called by the rxvt core 411# called by the rxvt core
359sub invoke { 412sub invoke {
360 local $TERM = shift; 413 local $TERM = shift;
361 my $htype = shift; 414 my $htype = shift;
362 415
363 if ($htype == 0) { # INIT 416 if ($htype == 0) { # INIT
364 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 417 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
365 418
366 for my $ext (split /:/, $TERM->resource ("perl_ext")) { 419 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) {
367 my @files = grep -f $_, map "$_/$ext", @dirs; 420 my @files = grep -f $_, map "$_/$ext", @dirs;
368 421
369 if (@files) { 422 if (@files) {
370 register_package script_package $files[0]; 423 register_package script_package $files[0];
371 } else { 424 } else {
372 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";
373 } 426 }
374 } 427 }
428 }
375 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
376 } elsif ($htype == 1) { # DESTROY 450 if ($htype == 1) { # DESTROY
451 # remove hooks if unused
377 if (my $hook = $TERM->{_hook}) { 452 if (my $hook = $TERM->{_hook}) {
378 for my $htype (0..$#$hook) { 453 for my $htype (0..$#$hook) {
379 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 454 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
380 or set_should_invoke $htype, 0; 455 or set_should_invoke $htype, 0;
381 } 456 }
382 } 457 }
458
459 # clear package objects
460 %$_ = () for values %{ $TERM->{_pkg} };
461
462 # clear package
463 %$TERM = ();
383 } 464 }
384 465
385 my $cb = $TERM->{_hook}[$htype] 466 $retval
386 or return;
387
388 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
389 if $verbosity >= 10;
390
391 keys %$cb;
392
393 while (my ($pkg, $cb) = each %$cb) {
394 return 1
395 if $cb->(
396 $TERM->{$pkg} ||= do {
397 my $proxy = bless { }, urxvt::term::proxy::;
398 Scalar::Util::weaken ($proxy->{term} = $TERM);
399 $proxy
400 },
401 @_,
402 );
403 }
404
405 0
406} 467}
407 468
408sub urxvt::term::proxy::AUTOLOAD { 469sub urxvt::term::proxy::AUTOLOAD {
409 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 470 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/
410 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 471 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable";
… …
448 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 509 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
449 borderLess color cursorBlink cursorUnderline cutchars delete_key 510 borderLess color cursorBlink cursorUnderline cutchars delete_key
450 display_name embed ext_bwidth fade font geometry hold iconName 511 display_name embed ext_bwidth fade font geometry hold iconName
451 imFont imLocale inputMethod insecure int_bwidth intensityStyles 512 imFont imLocale inputMethod insecure int_bwidth intensityStyles
452 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 513 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
453 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext 514 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
454 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 515 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
455 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 516 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
456 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 517 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
457 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 518 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
458 shade term_name title transparent transparent_all tripleclickwords 519 shade term_name title transparent transparent_all tripleclickwords
… …
464 my ($self, $name) = (shift, shift); 525 my ($self, $name) = (shift, shift);
465 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 526 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
466 goto &urxvt::term::_resource; 527 goto &urxvt::term::_resource;
467} 528}
468 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
469=item ($row, $col) = $term->selection_mark ([$row, $col]) 540=item ($row, $col) = $term->selection_mark ([$row, $col])
470 541
471=item ($row, $col) = $term->selection_beg ([$row, $col]) 542=item ($row, $col) = $term->selection_beg ([$row, $col])
472 543
473=item ($row, $col) = $term->selection_end ([$row, $col]) 544=item ($row, $col) = $term->selection_end ([$row, $col])
… …
487#=item $term->overlay ($x, $y, $text) 558#=item $term->overlay ($x, $y, $text)
488# 559#
489#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.
490# 561#
491#=cut 562#=cut
492 563#
493sub urxvt::term::scr_overlay { 564#sub urxvt::term::scr_overlay {
494die;
495 my ($self, $x, $y, $text) = @_; 565# my ($self, $x, $y, $text) = @_;
496 566#
497 my @lines = split /\n/, $text; 567# my @lines = split /\n/, $text;
498 568#
499 my $w = 0; 569# my $w = 0;
500 for (map $self->strwidth ($_), @lines) { 570# for (map $self->strwidth ($_), @lines) {
501 $w = $_ if $w < $_; 571# $w = $_ if $w < $_;
502 } 572# }
503 573#
504 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 574# $self->scr_overlay_new ($x, $y, $w, scalar @lines);
505 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 575# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
506} 576#}
507 577
508=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 578=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
509 579
510Create a new (empty) overlay at the given position with the given 580Create a new (empty) overlay at the given position with the given
511width/height. C<$rstyle> defines the initial rendition style 581width/height. C<$rstyle> defines the initial rendition style
… …
551 621
552=item $string = $term->locale_decode $octets 622=item $string = $term->locale_decode $octets
553 623
554Convert the given locale-encoded octets into a perl string. 624Convert the given locale-encoded octets into a perl string.
555 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
556=item $term->tt_write ($octets) 637=item $term->tt_write ($octets)
557 638
558Write 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
559pass characters instead of octets, you should convert your strings first 640pass characters instead of octets, you should convert your strings first
560to the locale-specific encoding using C<< $term->locale_encode >>. 641to the locale-specific encoding using C<< $term->locale_encode >>.
561 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
562=item $nrow = $term->nrow 653=item $terminal_rows = $term->nrow
563 654
564=item $ncol = $term->ncol 655=item $terminal_columns = $term->ncol
565 656
566Return the number of rows/columns of the terminal window (i.e. as 657=item $has_focus = $term->focus
567specified by C<-geometry>, excluding any scrollback).
568 658
569=item $nsaved = $term->nsaved 659=item $is_mapped = $term->mapped
570 660
571Returns 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.
572 668
573=item $view_start = $term->view_start ([$newvalue]) 669=item $view_start = $term->view_start ([$newvalue])
574 670
575Returns the negative row number of the topmost line. Minimum value is 671Returns the negative row number of the topmost line. Minimum value is
576C<0>, which displays the normal terminal contents. Larger values scroll 672C<0>, which displays the normal terminal contents. Larger values scroll

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines