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.36 by root, Fri Jan 6 02:58:02 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
… …
185 222
186Be careful not ever to trust (in a security sense) the data you receive, 223Be 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 224as its source can not easily be controleld (e-mail content, messages from
188other users on the same system etc.). 225other users on the same system etc.).
189 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
190=item on_refresh_begin $term 249=item on_refresh_begin $term
191 250
192Called just before the screen gets redrawn. Can be used for overlay 251Called just before the screen gets redrawn. Can be used for overlay
193or similar effects by modify terminal contents in refresh_begin, and 252or similar effects by modify terminal contents in refresh_begin, and
194restoring them in refresh_end. The built-in overlay and selection display 253restoring them in refresh_end. The built-in overlay and selection display
… …
218=back 277=back
219 278
220=head2 Functions in the C<urxvt> Package 279=head2 Functions in the C<urxvt> Package
221 280
222=over 4 281=over 4
282
283=item $term = new urxvt [arg...]
284
285Creates a new terminal, very similar as if you had started it with
286C<system $binfile, arg...>. Croaks (and probably outputs an error message)
287if the new instance couldn't be created. Returns C<undef> if the new
288instance didn't initialise perl, and the terminal object otherwise. The
289C<init> and C<start> hooks will be called during the call.
223 290
224=item urxvt::fatal $errormessage 291=item urxvt::fatal $errormessage
225 292
226Fatally aborts execution with the given error message. Avoid at all 293Fatally aborts execution with the given error message. Avoid at all
227costs! The only time this is acceptable is when the terminal process 294costs! The only time this is acceptable is when the terminal process
… …
444} 511}
445 512
446=head2 The C<urxvt::term> Class 513=head2 The C<urxvt::term> Class
447 514
448=over 4 515=over 4
516
517=item $term->destroy
518
519Destroy the terminal object (close the window, free resources etc.).
449 520
450=item $value = $term->resource ($name[, $newval]) 521=item $value = $term->resource ($name[, $newval])
451 522
452Returns the current resource value associated with a given name and 523Returns the current resource value associated with a given name and
453optionally sets a new value. Setting values is most useful in the C<init> 524optionally sets a new value. Setting values is most useful in the C<init>
… …
487 my ($self, $name) = (shift, shift); 558 my ($self, $name) = (shift, shift);
488 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 559 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
489 goto &urxvt::term::_resource; 560 goto &urxvt::term::_resource;
490} 561}
491 562
563=item $rend = $term->rstyle ([$new_rstyle])
564
565Return and optionally change the current rendition. Text that is output by
566the terminal application will use this style.
567
568=item ($row, $col) = $term->screen_cur ([$row, $col])
569
570Return the current coordinates of the text cursor position and optionally
571set it (which is usually bad as applications don't expect that).
572
492=item ($row, $col) = $term->selection_mark ([$row, $col]) 573=item ($row, $col) = $term->selection_mark ([$row, $col])
493 574
494=item ($row, $col) = $term->selection_beg ([$row, $col]) 575=item ($row, $col) = $term->selection_beg ([$row, $col])
495 576
496=item ($row, $col) = $term->selection_end ([$row, $col]) 577=item ($row, $col) = $term->selection_end ([$row, $col])
… …
510#=item $term->overlay ($x, $y, $text) 591#=item $term->overlay ($x, $y, $text)
511# 592#
512#Create a simple multi-line overlay box. See the next method for details. 593#Create a simple multi-line overlay box. See the next method for details.
513# 594#
514#=cut 595#=cut
515 596#
516sub urxvt::term::scr_overlay { 597#sub urxvt::term::scr_overlay {
517die;
518 my ($self, $x, $y, $text) = @_; 598# my ($self, $x, $y, $text) = @_;
519 599#
520 my @lines = split /\n/, $text; 600# my @lines = split /\n/, $text;
521 601#
522 my $w = 0; 602# my $w = 0;
523 for (map $self->strwidth ($_), @lines) { 603# for (map $self->strwidth ($_), @lines) {
524 $w = $_ if $w < $_; 604# $w = $_ if $w < $_;
525 } 605# }
526 606#
527 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 607# $self->scr_overlay_new ($x, $y, $w, scalar @lines);
528 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 608# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
529} 609#}
530 610
531=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 611=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
532 612
533Create a new (empty) overlay at the given position with the given 613Create a new (empty) overlay at the given position with the given
534width/height. C<$rstyle> defines the initial rendition style 614width/height. C<$rstyle> defines the initial rendition style
… …
574 654
575=item $string = $term->locale_decode $octets 655=item $string = $term->locale_decode $octets
576 656
577Convert the given locale-encoded octets into a perl string. 657Convert the given locale-encoded octets into a perl string.
578 658
659=item $term->scr_add_lines ($string)
660
661Write the given text string to the screen, as if output by the application
662running inside the terminal. It may not contain command sequences (escape
663codes), but is free to use line feeds, carriage returns and tabs. The
664string is a normal text string, not in locale-dependent encoding.
665
666Normally its not a good idea to use this function, as programs might be
667confused by changes in cursor position or scrolling. Its useful inside a
668C<on_add_lines> hook, though.
669
670=item $term->cmd_parse ($octets)
671
672Similar to C<scr_add_lines>, but the argument must be in the
673locale-specific encoding of the terminal and can contain command sequences
674(escape codes) that will be interpreted.
675
579=item $term->tt_write ($octets) 676=item $term->tt_write ($octets)
580 677
581Write the octets given in C<$data> to the tty (i.e. as program input). To 678Write 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 679pass characters instead of octets, you should convert your strings first
583to the locale-specific encoding using C<< $term->locale_encode >>. 680to the locale-specific encoding using C<< $term->locale_encode >>.
584 681
682=item $window_width = $term->width
683
684=item $window_height = $term->height
685
686=item $font_width = $term->fwidth
687
688=item $font_height = $term->fheight
689
690=item $font_ascent = $term->fbase
691
585=item $nrow = $term->nrow 692=item $terminal_rows = $term->nrow
586 693
587=item $ncol = $term->ncol 694=item $terminal_columns = $term->ncol
588 695
589Return the number of rows/columns of the terminal window (i.e. as 696=item $has_focus = $term->focus
590specified by C<-geometry>, excluding any scrollback).
591 697
592=item $nsaved = $term->nsaved 698=item $is_mapped = $term->mapped
593 699
594Returns the number of lines in the scrollback buffer. 700=item $max_scrollback = $term->saveLines
701
702=item $nrow_plus_saveLines = $term->total_rows
703
704=item $lines_in_scrollback = $term->nsaved
705
706Return various integers describing terminal characteristics.
595 707
596=item $view_start = $term->view_start ([$newvalue]) 708=item $view_start = $term->view_start ([$newvalue])
597 709
598Returns the negative row number of the topmost line. Minimum value is 710Returns the negative row number of the topmost line. Minimum value is
599C<0>, which displays the normal terminal contents. Larger values scroll 711C<0>, which displays the normal terminal contents. Larger values scroll
… …
662about the logical line that row C<$row_number> is part of. It supports the 774about the logical line that row C<$row_number> is part of. It supports the
663following methods: 775following methods:
664 776
665=over 4 777=over 4
666 778
667=item $text = $line->t 779=item $text = $line->t ([$new_text])
668 780
669Returns the full text of the line, similar to C<ROW_t> 781Returns or replaces the full text of the line, similar to C<ROW_t>
670 782
671=item $rend = $line->r 783=item $rend = $line->r ([$new_rend])
672 784
673Returns the full rendition array of the line, similar to C<ROW_r> 785Returns or replaces the full rendition array of the line, similar to C<ROW_r>
674 786
675=item $length = $line->l 787=item $length = $line->l
676 788
677Returns the length of the line in cells, similar to C<ROW_l>. 789Returns the length of the line in cells, similar to C<ROW_l>.
678 790
… …
707 819
708 bless { 820 bless {
709 term => $self, 821 term => $self,
710 beg => $beg, 822 beg => $beg,
711 end => $end, 823 end => $end,
824 ncol => $self->ncol,
712 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end), 825 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
713 }, urxvt::line:: 826 }, urxvt::line::
714} 827}
715 828
716sub urxvt::line::t { 829sub urxvt::line::t {
717 my ($self) = @_; 830 my ($self) = @_;
718 831
832 if (@_ > 1)
833 {
834 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
835 for $self->{beg} .. $self->{end};
836 }
837
838 defined wantarray &&
719 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 839 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
720 0, $self->{len} 840 0, $self->{len}
721} 841}
722 842
723sub urxvt::line::r { 843sub urxvt::line::r {
724 my ($self) = @_; 844 my ($self) = @_;
725 845
846 if (@_ > 1)
847 {
848 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
849 for $self->{beg} .. $self->{end};
850 }
851
852 if (defined wantarray) {
726 my $rend = [ 853 my $rend = [
727 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 854 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
728 ]; 855 ];
729 $#$rend = $self->{len} - 1; 856 $#$rend = $self->{len} - 1;
730 $rend 857 return $rend;
858 }
859
860 ()
731} 861}
732 862
733sub urxvt::line::beg { $_[0]{beg} } 863sub urxvt::line::beg { $_[0]{beg} }
734sub urxvt::line::end { $_[0]{end} } 864sub urxvt::line::end { $_[0]{end} }
735sub urxvt::line::l { $_[0]{len} } 865sub urxvt::line::l { $_[0]{len} }
736 866
737sub urxvt::line::offset_of { 867sub urxvt::line::offset_of {
738 my ($self, $row, $col) = @_; 868 my ($self, $row, $col) = @_;
739 869
740 ($row - $self->{beg}) * $self->{term}->ncol + $col 870 ($row - $self->{beg}) * $self->{ncol} + $col
741} 871}
742 872
743sub urxvt::line::coord_of { 873sub urxvt::line::coord_of {
744 my ($self, $offset) = @_; 874 my ($self, $offset) = @_;
745 875
746 use integer; 876 use integer;
747 877
748 ( 878 (
749 $offset / $self->{term}->ncol + $self->{beg}, 879 $offset / $self->{ncol} + $self->{beg},
750 $offset % $self->{term}->ncol 880 $offset % $self->{ncol}
751 ) 881 )
752} 882}
753 883
754=item ($row, $col) = $line->coord_of ($offset) 884=item ($row, $col) = $line->coord_of ($offset)
755=item $text = $term->special_encode $string 885=item $text = $term->special_encode $string

Diff Legend

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