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.31 by root, Wed Jan 4 19:39:46 2006 UTC vs.
Revision 1.34 by root, Fri Jan 6 01:16:58 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
80 87
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.
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
85 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.
184future. 214future.
185 215
186Be careful not ever to trust (in a security sense) the data you receive, 216Be careful not ever to trust (in a security sense) the data you receive,
187as its source can not easily be controleld (e-mail content, messages from 217as its source can not easily be controleld (e-mail content, messages from
188other users on the same system etc.). 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.
189 227
190=item on_refresh_begin $term 228=item on_refresh_begin $term
191 229
192Called just before the screen gets redrawn. Can be used for overlay 230Called just before the screen gets redrawn. Can be used for overlay
193or similar effects by modify terminal contents in refresh_begin, and 231or similar effects by modify terminal contents in refresh_begin, and
487 my ($self, $name) = (shift, shift); 525 my ($self, $name) = (shift, shift);
488 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 526 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
489 goto &urxvt::term::_resource; 527 goto &urxvt::term::_resource;
490} 528}
491 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
492=item ($row, $col) = $term->selection_mark ([$row, $col]) 540=item ($row, $col) = $term->selection_mark ([$row, $col])
493 541
494=item ($row, $col) = $term->selection_beg ([$row, $col]) 542=item ($row, $col) = $term->selection_beg ([$row, $col])
495 543
496=item ($row, $col) = $term->selection_end ([$row, $col]) 544=item ($row, $col) = $term->selection_end ([$row, $col])
510#=item $term->overlay ($x, $y, $text) 558#=item $term->overlay ($x, $y, $text)
511# 559#
512#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.
513# 561#
514#=cut 562#=cut
515 563#
516sub urxvt::term::scr_overlay { 564#sub urxvt::term::scr_overlay {
517die;
518 my ($self, $x, $y, $text) = @_; 565# my ($self, $x, $y, $text) = @_;
519 566#
520 my @lines = split /\n/, $text; 567# my @lines = split /\n/, $text;
521 568#
522 my $w = 0; 569# my $w = 0;
523 for (map $self->strwidth ($_), @lines) { 570# for (map $self->strwidth ($_), @lines) {
524 $w = $_ if $w < $_; 571# $w = $_ if $w < $_;
525 } 572# }
526 573#
527 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 574# $self->scr_overlay_new ($x, $y, $w, scalar @lines);
528 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 575# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
529} 576#}
530 577
531=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 578=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
532 579
533Create a new (empty) overlay at the given position with the given 580Create a new (empty) overlay at the given position with the given
534width/height. C<$rstyle> defines the initial rendition style 581width/height. C<$rstyle> defines the initial rendition style
574 621
575=item $string = $term->locale_decode $octets 622=item $string = $term->locale_decode $octets
576 623
577Convert the given locale-encoded octets into a perl string. 624Convert the given locale-encoded octets into a perl string.
578 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
579=item $term->tt_write ($octets) 637=item $term->tt_write ($octets)
580 638
581Write 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
582pass characters instead of octets, you should convert your strings first 640pass characters instead of octets, you should convert your strings first
583to the locale-specific encoding using C<< $term->locale_encode >>. 641to the locale-specific encoding using C<< $term->locale_encode >>.
584 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
585=item $nrow = $term->nrow 653=item $terminal_rows = $term->nrow
586 654
587=item $ncol = $term->ncol 655=item $terminal_columns = $term->ncol
588 656
589Return the number of rows/columns of the terminal window (i.e. as 657=item $has_focus = $term->focus
590specified by C<-geometry>, excluding any scrollback).
591 658
592=item $nsaved = $term->nsaved 659=item $is_mapped = $term->mapped
593 660
594Returns 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.
595 668
596=item $view_start = $term->view_start ([$newvalue]) 669=item $view_start = $term->view_start ([$newvalue])
597 670
598Returns the negative row number of the topmost line. Minimum value is 671Returns the negative row number of the topmost line. Minimum value is
599C<0>, which displays the normal terminal contents. Larger values scroll 672C<0>, which displays the normal terminal contents. Larger values scroll
707 780
708 bless { 781 bless {
709 term => $self, 782 term => $self,
710 beg => $beg, 783 beg => $beg,
711 end => $end, 784 end => $end,
785 ncol => $self->ncol,
712 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end), 786 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
713 }, urxvt::line:: 787 }, urxvt::line::
714} 788}
715 789
716sub urxvt::line::t { 790sub urxvt::line::t {
717 my ($self) = @_; 791 my ($self) = @_;
718 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 &&
719 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 800 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
720 0, $self->{len} 801 0, $self->{len}
721} 802}
722 803
723sub urxvt::line::r { 804sub urxvt::line::r {
724 my ($self) = @_; 805 my ($self) = @_;
725 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) {
726 my $rend = [ 814 my $rend = [
727 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 815 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
728 ]; 816 ];
729 $#$rend = $self->{len} - 1; 817 $#$rend = $self->{len} - 1;
730 $rend 818 return $rend;
819 }
820
821 ()
731} 822}
732 823
733sub urxvt::line::beg { $_[0]{beg} } 824sub urxvt::line::beg { $_[0]{beg} }
734sub urxvt::line::end { $_[0]{end} } 825sub urxvt::line::end { $_[0]{end} }
735sub urxvt::line::l { $_[0]{len} } 826sub urxvt::line::l { $_[0]{len} }
736 827
737sub urxvt::line::offset_of { 828sub urxvt::line::offset_of {
738 my ($self, $row, $col) = @_; 829 my ($self, $row, $col) = @_;
739 830
740 ($row - $self->{beg}) * $self->{term}->ncol + $col 831 ($row - $self->{beg}) * $self->{ncol} + $col
741} 832}
742 833
743sub urxvt::line::coord_of { 834sub urxvt::line::coord_of {
744 my ($self, $offset) = @_; 835 my ($self, $offset) = @_;
745 836
746 use integer; 837 use integer;
747 838
748 ( 839 (
749 $offset / $self->{term}->ncol + $self->{beg}, 840 $offset / $self->{ncol} + $self->{beg},
750 $offset % $self->{term}->ncol 841 $offset % $self->{ncol}
751 ) 842 )
752} 843}
753 844
754=item ($row, $col) = $line->coord_of ($offset) 845=item ($row, $col) = $line->coord_of ($offset)
755=item $text = $term->special_encode $string 846=item $text = $term->special_encode $string

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines