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.32 by root, Wed Jan 4 21:37:55 2006 UTC vs.
Revision 1.38 by root, Fri Jan 6 03:43:12 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
… …
202 261
203Called whenever the user presses a key combination that has a 262Called whenever the user presses a key combination that has a
204C<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>
205resource in the @@RXVT_NAME@@(1) manpage). 264resource in the @@RXVT_NAME@@(1) manpage).
206 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
277(see the XEvent manpage) If the hook returns true, then the even will be
278ignored by rxvt-unicode.
279
280C<on_key_press> additionally receives the string rxvt-unicode would
281output, if any, in locale-specific encoding.
282
283subwindow.
284
207=back 285=back
208 286
209=head2 Variables in the C<urxvt> Package 287=head2 Variables in the C<urxvt> Package
210 288
211=over 4 289=over 4
… …
218=back 296=back
219 297
220=head2 Functions in the C<urxvt> Package 298=head2 Functions in the C<urxvt> Package
221 299
222=over 4 300=over 4
301
302=item $term = new urxvt [arg...]
303
304Creates a new terminal, very similar as if you had started it with
305C<system $binfile, arg...>. Croaks (and probably outputs an error message)
306if the new instance couldn't be created. Returns C<undef> if the new
307instance didn't initialise perl, and the terminal object otherwise. The
308C<init> and C<start> hooks will be called during the call.
223 309
224=item urxvt::fatal $errormessage 310=item urxvt::fatal $errormessage
225 311
226Fatally aborts execution with the given error message. Avoid at all 312Fatally aborts execution with the given error message. Avoid at all
227costs! The only time this is acceptable is when the terminal process 313costs! The only time this is acceptable is when the terminal process
… …
444} 530}
445 531
446=head2 The C<urxvt::term> Class 532=head2 The C<urxvt::term> Class
447 533
448=over 4 534=over 4
535
536=item $term->destroy
537
538Destroy the terminal object (close the window, free resources etc.).
449 539
450=item $value = $term->resource ($name[, $newval]) 540=item $value = $term->resource ($name[, $newval])
451 541
452Returns the current resource value associated with a given name and 542Returns the current resource value associated with a given name and
453optionally sets a new value. Setting values is most useful in the C<init> 543optionally sets a new value. Setting values is most useful in the C<init>
… …
487 my ($self, $name) = (shift, shift); 577 my ($self, $name) = (shift, shift);
488 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 578 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
489 goto &urxvt::term::_resource; 579 goto &urxvt::term::_resource;
490} 580}
491 581
492=item $rend = $term->screen_rstyle ([$new_rstyle]) 582=item $rend = $term->rstyle ([$new_rstyle])
493 583
494Return and optionally change the current rendition. Text thta is output by 584Return and optionally change the current rendition. Text that is output by
495the temrianl application will use this style. 585the terminal application will use this style.
496 586
497=item ($row, $col) = $term->screen_cur ([$row, $col]) 587=item ($row, $col) = $term->screen_cur ([$row, $col])
498 588
499Return the current coordinates of the text cursor position and optionally 589Return the current coordinates of the text cursor position and optionally
500set it (which is usually bad as applications don't expect that). 590set it (which is usually bad as applications don't expect that).
… …
520#=item $term->overlay ($x, $y, $text) 610#=item $term->overlay ($x, $y, $text)
521# 611#
522#Create a simple multi-line overlay box. See the next method for details. 612#Create a simple multi-line overlay box. See the next method for details.
523# 613#
524#=cut 614#=cut
525 615#
526sub urxvt::term::scr_overlay { 616#sub urxvt::term::scr_overlay {
527die;
528 my ($self, $x, $y, $text) = @_; 617# my ($self, $x, $y, $text) = @_;
529 618#
530 my @lines = split /\n/, $text; 619# my @lines = split /\n/, $text;
531 620#
532 my $w = 0; 621# my $w = 0;
533 for (map $self->strwidth ($_), @lines) { 622# for (map $self->strwidth ($_), @lines) {
534 $w = $_ if $w < $_; 623# $w = $_ if $w < $_;
535 } 624# }
536 625#
537 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 626# $self->scr_overlay_new ($x, $y, $w, scalar @lines);
538 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 627# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
539} 628#}
540 629
541=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 630=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
542 631
543Create a new (empty) overlay at the given position with the given 632Create a new (empty) overlay at the given position with the given
544width/height. C<$rstyle> defines the initial rendition style 633width/height. C<$rstyle> defines the initial rendition style
… …
583Convert the given text string into the corresponding locale encoding. 672Convert the given text string into the corresponding locale encoding.
584 673
585=item $string = $term->locale_decode $octets 674=item $string = $term->locale_decode $octets
586 675
587Convert the given locale-encoded octets into a perl string. 676Convert the given locale-encoded octets into a perl string.
677
678=item $term->scr_add_lines ($string)
679
680Write the given text string to the screen, as if output by the application
681running inside the terminal. It may not contain command sequences (escape
682codes), but is free to use line feeds, carriage returns and tabs. The
683string is a normal text string, not in locale-dependent encoding.
684
685Normally its not a good idea to use this function, as programs might be
686confused by changes in cursor position or scrolling. Its useful inside a
687C<on_add_lines> hook, though.
688
689=item $term->cmd_parse ($octets)
690
691Similar to C<scr_add_lines>, but the argument must be in the
692locale-specific encoding of the terminal and can contain command sequences
693(escape codes) that will be interpreted.
588 694
589=item $term->tt_write ($octets) 695=item $term->tt_write ($octets)
590 696
591Write the octets given in C<$data> to the tty (i.e. as program input). To 697Write the octets given in C<$data> to the tty (i.e. as program input). To
592pass characters instead of octets, you should convert your strings first 698pass characters instead of octets, you should convert your strings first
… …
687about the logical line that row C<$row_number> is part of. It supports the 793about the logical line that row C<$row_number> is part of. It supports the
688following methods: 794following methods:
689 795
690=over 4 796=over 4
691 797
692=item $text = $line->t 798=item $text = $line->t ([$new_text])
693 799
694Returns the full text of the line, similar to C<ROW_t> 800Returns or replaces the full text of the line, similar to C<ROW_t>
695 801
696=item $rend = $line->r 802=item $rend = $line->r ([$new_rend])
697 803
698Returns the full rendition array of the line, similar to C<ROW_r> 804Returns or replaces the full rendition array of the line, similar to C<ROW_r>
699 805
700=item $length = $line->l 806=item $length = $line->l
701 807
702Returns the length of the line in cells, similar to C<ROW_l>. 808Returns the length of the line in cells, similar to C<ROW_l>.
703 809
… …
732 838
733 bless { 839 bless {
734 term => $self, 840 term => $self,
735 beg => $beg, 841 beg => $beg,
736 end => $end, 842 end => $end,
843 ncol => $self->ncol,
737 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end), 844 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
738 }, urxvt::line:: 845 }, urxvt::line::
739} 846}
740 847
741sub urxvt::line::t { 848sub urxvt::line::t {
742 my ($self) = @_; 849 my ($self) = @_;
743 850
851 if (@_ > 1)
852 {
853 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
854 for $self->{beg} .. $self->{end};
855 }
856
857 defined wantarray &&
744 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 858 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
745 0, $self->{len} 859 0, $self->{len}
746} 860}
747 861
748sub urxvt::line::r { 862sub urxvt::line::r {
749 my ($self) = @_; 863 my ($self) = @_;
750 864
865 if (@_ > 1)
866 {
867 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
868 for $self->{beg} .. $self->{end};
869 }
870
871 if (defined wantarray) {
751 my $rend = [ 872 my $rend = [
752 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 873 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
753 ]; 874 ];
754 $#$rend = $self->{len} - 1; 875 $#$rend = $self->{len} - 1;
755 $rend 876 return $rend;
877 }
878
879 ()
756} 880}
757 881
758sub urxvt::line::beg { $_[0]{beg} } 882sub urxvt::line::beg { $_[0]{beg} }
759sub urxvt::line::end { $_[0]{end} } 883sub urxvt::line::end { $_[0]{end} }
760sub urxvt::line::l { $_[0]{len} } 884sub urxvt::line::l { $_[0]{len} }
761 885
762sub urxvt::line::offset_of { 886sub urxvt::line::offset_of {
763 my ($self, $row, $col) = @_; 887 my ($self, $row, $col) = @_;
764 888
765 ($row - $self->{beg}) * $self->{term}->ncol + $col 889 ($row - $self->{beg}) * $self->{ncol} + $col
766} 890}
767 891
768sub urxvt::line::coord_of { 892sub urxvt::line::coord_of {
769 my ($self, $offset) = @_; 893 my ($self, $offset) = @_;
770 894
771 use integer; 895 use integer;
772 896
773 ( 897 (
774 $offset / $self->{term}->ncol + $self->{beg}, 898 $offset / $self->{ncol} + $self->{beg},
775 $offset % $self->{term}->ncol 899 $offset % $self->{ncol}
776 ) 900 )
777} 901}
778 902
779=item ($row, $col) = $line->coord_of ($offset) 903=item ($row, $col) = $line->coord_of ($offset)
780=item $text = $term->special_encode $string 904=item $text = $term->special_encode $string

Diff Legend

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