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.43 by root, Sat Jan 7 04:19:43 2006 UTC

… …
59=back 59=back
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
65=item mark-urls
66
67Uses per-line display filtering (C<on_line_update>) to underline urls.
68
69=item block-graphics-to-ascii
70
71A not very useful example of filtering all text output to the terminal,
72by replacing all line-drawing characters (U+2500 .. U+259F) by a
73similar-looking ascii character.
64 74
65=item example-refresh-hooks 75=item example-refresh-hooks
66 76
67Displays a very simple digital clock in the upper right corner of the 77Displays a very simple digital clock in the upper right corner of the
68window. Illustrates overwriting the refresh callbacks to create your own 78window. Illustrates overwriting the refresh callbacks to create your own
… …
81When objects are destroyed on the C++ side, the perl object hashes are 91When 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 92emptied, 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 93the like inside the terminal object so they get destroyed as soon as the
84terminal is destroyed. 94terminal is destroyed.
85 95
96Argument names also often indicate the type of a parameter. Here are some
97hints on what they mean:
98
99=over 4
100
101=item $text
102
103Rxvt-unicodes special way of encoding text, where one "unicode" character
104always represents one screen cell. See L<row_t> for a discussion of this format.
105
106=item $string
107
108A perl text string, with an emphasis on I<text>. It can store all unicode
109characters and is to be distinguished with text encoded in a specific
110encoding (often locale-specific) and binary data.
111
112=item $octets
113
114Either binary data or - more common - a text string encoded in a
115locale-specific way.
116
117=back
118
86=head2 Hooks 119=head2 Hooks
87 120
88The following subroutines can be declared in loaded scripts, and will be 121The following subroutines can be declared in extension files, and will be
89called whenever the relevant event happens. 122called whenever the relevant event happens.
90 123
91The first argument passed to them is an object private to each terminal 124The first argument passed to them is an object private to each terminal
92and extension package. You can call all C<urxvt::term> methods on it, but 125and extension package. You can call all C<urxvt::term> methods on it, but
93its not a real C<urxvt::term> object. Instead, the real C<urxvt::term> 126its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
… …
103=over 4 136=over 4
104 137
105=item on_init $term 138=item on_init $term
106 139
107Called after a new terminal object has been initialized, but before 140Called after a new terminal object has been initialized, but before
108windows are created or the command gets run. 141windows are created or the command gets run. Most methods are unsafe to
142call or deliver senseless data, as terminal size and other characteristics
143have not yet been determined. You can safely query and change resources,
144though.
109 145
110=item on_reset $term 146=item on_reset $term
111 147
112Called after the screen is "reset" for any reason, such as resizing or 148Called 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 149control sequences. Here is where you can react on changes to size-related
… …
185 221
186Be careful not ever to trust (in a security sense) the data you receive, 222Be 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 223as its source can not easily be controleld (e-mail content, messages from
188other users on the same system etc.). 224other users on the same system etc.).
189 225
226=item on_add_lines $term, $string
227
228Called whenever text is about to be output, with the text as argument. You
229can filter/change and output the text yourself by returning a true value
230and calling C<< $term->scr_add_lines >> yourself. Please note that this
231might be very slow, however, as your hook is called for B<all> text being
232output.
233
234=item on_line_update $term, $row
235
236Called whenever a line was updated or changed. Can be used to filter
237screen output (e.g. underline urls or other useless stuff). Only lines
238that are being shown will be filtered, and, due to performance reasons,
239not always immediately.
240
241The row number is always the topmost row of the line if the line spans
242multiple rows.
243
244Please note that, if you change the line, then the hook might get called
245later with the already-modified line (e.g. if unrelated parts change), so
246you cannot just toggle rendition bits, but only set them.
247
190=item on_refresh_begin $term 248=item on_refresh_begin $term
191 249
192Called just before the screen gets redrawn. Can be used for overlay 250Called just before the screen gets redrawn. Can be used for overlay
193or similar effects by modify terminal contents in refresh_begin, and 251or similar effects by modify terminal contents in refresh_begin, and
194restoring them in refresh_end. The built-in overlay and selection display 252restoring them in refresh_end. The built-in overlay and selection display
… …
202 260
203Called whenever the user presses a key combination that has a 261Called whenever the user presses a key combination that has a
204C<perl:string> action bound to it (see description of the B<keysym> 262C<perl:string> action bound to it (see description of the B<keysym>
205resource in the @@RXVT_NAME@@(1) manpage). 263resource in the @@RXVT_NAME@@(1) manpage).
206 264
265=item on_key_press $term, $event, $octets
266
267=item on_key_release $term, $event
268
269=item on_button_press $term, $event
270
271=item on_button_release $term, $event
272
273=item on_motion_notify $term, $event
274
275Called whenever the corresponding X event is received for the terminal If
276the hook returns true, then the even will be ignored by rxvt-unicode.
277
278The event is a hash with most values as named by Xlib (see the XEvent
279manpage), with the additional members C<row> and C<col>, which are the row
280and column under the mouse cursor.
281
282C<on_key_press> additionally receives the string rxvt-unicode would
283output, if any, in locale-specific encoding.
284
285subwindow.
286
207=back 287=back
208 288
209=head2 Variables in the C<urxvt> Package 289=head2 Variables in the C<urxvt> Package
210 290
211=over 4 291=over 4
212 292
213=item $urxvt::TERM 293=item $urxvt::TERM
214 294
215The current terminal. Whenever a callback/Hook is bein executed, this 295The current terminal. This variable stores the current C<urxvt::term>
216variable stores the current C<urxvt::term> object. 296object, whenever a callback/hook is executing.
217 297
218=back 298=back
219 299
220=head2 Functions in the C<urxvt> Package 300=head2 Functions in the C<urxvt> Package
221 301
222=over 4 302=over 4
303
304=item $term = new urxvt [arg...]
305
306Creates a new terminal, very similar as if you had started it with
307C<system $binfile, arg...>. Croaks (and probably outputs an error message)
308if the new instance couldn't be created. Returns C<undef> if the new
309instance didn't initialise perl, and the terminal object otherwise. The
310C<init> and C<start> hooks will be called during the call.
223 311
224=item urxvt::fatal $errormessage 312=item urxvt::fatal $errormessage
225 313
226Fatally aborts execution with the given error message. Avoid at all 314Fatally aborts execution with the given error message. Avoid at all
227costs! The only time this is acceptable is when the terminal process 315costs! The only time this is acceptable is when the terminal process
… …
376 my $htype = shift; 464 my $htype = shift;
377 465
378 if ($htype == 0) { # INIT 466 if ($htype == 0) { # INIT
379 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 467 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
380 468
381 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) { 469 for my $ext (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
382 my @files = grep -f $_, map "$_/$ext", @dirs; 470 my @files = grep -f $_, map "$_/$ext", @dirs;
383 471
384 if (@files) { 472 if (@files) {
385 register_package script_package $files[0]; 473 register_package script_package $files[0];
386 } else { 474 } else {
… …
444} 532}
445 533
446=head2 The C<urxvt::term> Class 534=head2 The C<urxvt::term> Class
447 535
448=over 4 536=over 4
537
538=item $term->destroy
539
540Destroy the terminal object (close the window, free resources etc.).
449 541
450=item $value = $term->resource ($name[, $newval]) 542=item $value = $term->resource ($name[, $newval])
451 543
452Returns the current resource value associated with a given name and 544Returns the current resource value associated with a given name and
453optionally sets a new value. Setting values is most useful in the C<init> 545optionally sets a new value. Setting values is most useful in the C<init>
… …
487 my ($self, $name) = (shift, shift); 579 my ($self, $name) = (shift, shift);
488 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 580 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
489 goto &urxvt::term::_resource; 581 goto &urxvt::term::_resource;
490} 582}
491 583
492=item $rend = $term->screen_rstyle ([$new_rstyle]) 584=item $rend = $term->rstyle ([$new_rstyle])
493 585
494Return and optionally change the current rendition. Text thta is output by 586Return and optionally change the current rendition. Text that is output by
495the temrianl application will use this style. 587the terminal application will use this style.
496 588
497=item ($row, $col) = $term->screen_cur ([$row, $col]) 589=item ($row, $col) = $term->screen_cur ([$row, $col])
498 590
499Return the current coordinates of the text cursor position and optionally 591Return the current coordinates of the text cursor position and optionally
500set it (which is usually bad as applications don't expect that). 592set it (which is usually bad as applications don't expect that).
… …
520#=item $term->overlay ($x, $y, $text) 612#=item $term->overlay ($x, $y, $text)
521# 613#
522#Create a simple multi-line overlay box. See the next method for details. 614#Create a simple multi-line overlay box. See the next method for details.
523# 615#
524#=cut 616#=cut
525 617#
526sub urxvt::term::scr_overlay { 618#sub urxvt::term::scr_overlay {
527die;
528 my ($self, $x, $y, $text) = @_; 619# my ($self, $x, $y, $text) = @_;
529 620#
530 my @lines = split /\n/, $text; 621# my @lines = split /\n/, $text;
531 622#
532 my $w = 0; 623# my $w = 0;
533 for (map $self->strwidth ($_), @lines) { 624# for (map $self->strwidth ($_), @lines) {
534 $w = $_ if $w < $_; 625# $w = $_ if $w < $_;
535 } 626# }
536 627#
537 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 628# $self->scr_overlay_new ($x, $y, $w, scalar @lines);
538 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 629# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
539} 630#}
540 631
541=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) 632=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
542 633
543Create a new (empty) overlay at the given position with the given 634Create a new (empty) overlay at the given position with the given
544width/height. C<$rstyle> defines the initial rendition style 635width/height. C<$rstyle> defines the initial rendition style
… …
571 662
572If hidden, display the overlay again. 663If hidden, display the overlay again.
573 664
574=back 665=back
575 666
576=item $cellwidth = $term->strwidth $string 667=item $cellwidth = $term->strwidth ($string)
577 668
578Returns the number of screen-cells this string would need. Correctly 669Returns the number of screen-cells this string would need. Correctly
579accounts for wide and combining characters. 670accounts for wide and combining characters.
580 671
581=item $octets = $term->locale_encode $string 672=item $octets = $term->locale_encode ($string)
582 673
583Convert the given text string into the corresponding locale encoding. 674Convert the given text string into the corresponding locale encoding.
584 675
585=item $string = $term->locale_decode $octets 676=item $string = $term->locale_decode ($octets)
586 677
587Convert the given locale-encoded octets into a perl string. 678Convert the given locale-encoded octets into a perl string.
679
680=item $term->scr_add_lines ($string)
681
682Write the given text string to the screen, as if output by the application
683running inside the terminal. It may not contain command sequences (escape
684codes), but is free to use line feeds, carriage returns and tabs. The
685string is a normal text string, not in locale-dependent encoding.
686
687Normally its not a good idea to use this function, as programs might be
688confused by changes in cursor position or scrolling. Its useful inside a
689C<on_add_lines> hook, though.
690
691=item $term->cmd_parse ($octets)
692
693Similar to C<scr_add_lines>, but the argument must be in the
694locale-specific encoding of the terminal and can contain command sequences
695(escape codes) that will be interpreted.
588 696
589=item $term->tt_write ($octets) 697=item $term->tt_write ($octets)
590 698
591Write the octets given in C<$data> to the tty (i.e. as program input). To 699Write 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 700pass characters instead of octets, you should convert your strings first
593to the locale-specific encoding using C<< $term->locale_encode >>. 701to the locale-specific encoding using C<< $term->locale_encode >>.
702
703=item $windowid = $term->parent
704
705Return the window id of the toplevel window.
706
707=item $windowid = $term->vt
708
709Return the window id of the terminal window.
594 710
595=item $window_width = $term->width 711=item $window_width = $term->width
596 712
597=item $window_height = $term->height 713=item $window_height = $term->height
598 714
… …
687about the logical line that row C<$row_number> is part of. It supports the 803about the logical line that row C<$row_number> is part of. It supports the
688following methods: 804following methods:
689 805
690=over 4 806=over 4
691 807
692=item $text = $line->t 808=item $text = $line->t ([$new_text])
693 809
694Returns the full text of the line, similar to C<ROW_t> 810Returns or replaces the full text of the line, similar to C<ROW_t>
695 811
696=item $rend = $line->r 812=item $rend = $line->r ([$new_rend])
697 813
698Returns the full rendition array of the line, similar to C<ROW_r> 814Returns or replaces the full rendition array of the line, similar to C<ROW_r>
699 815
700=item $length = $line->l 816=item $length = $line->l
701 817
702Returns the length of the line in cells, similar to C<ROW_l>. 818Returns the length of the line in cells, similar to C<ROW_l>.
703 819
… …
732 848
733 bless { 849 bless {
734 term => $self, 850 term => $self,
735 beg => $beg, 851 beg => $beg,
736 end => $end, 852 end => $end,
853 ncol => $self->ncol,
737 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end), 854 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
738 }, urxvt::line:: 855 }, urxvt::line::
739} 856}
740 857
741sub urxvt::line::t { 858sub urxvt::line::t {
742 my ($self) = @_; 859 my ($self) = @_;
743 860
861 if (@_ > 1)
862 {
863 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
864 for $self->{beg} .. $self->{end};
865 }
866
867 defined wantarray &&
744 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 868 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
745 0, $self->{len} 869 0, $self->{len}
746} 870}
747 871
748sub urxvt::line::r { 872sub urxvt::line::r {
749 my ($self) = @_; 873 my ($self) = @_;
750 874
875 if (@_ > 1)
876 {
877 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
878 for $self->{beg} .. $self->{end};
879 }
880
881 if (defined wantarray) {
751 my $rend = [ 882 my $rend = [
752 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 883 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
753 ]; 884 ];
754 $#$rend = $self->{len} - 1; 885 $#$rend = $self->{len} - 1;
755 $rend 886 return $rend;
887 }
888
889 ()
756} 890}
757 891
758sub urxvt::line::beg { $_[0]{beg} } 892sub urxvt::line::beg { $_[0]{beg} }
759sub urxvt::line::end { $_[0]{end} } 893sub urxvt::line::end { $_[0]{end} }
760sub urxvt::line::l { $_[0]{len} } 894sub urxvt::line::l { $_[0]{len} }
761 895
762sub urxvt::line::offset_of { 896sub urxvt::line::offset_of {
763 my ($self, $row, $col) = @_; 897 my ($self, $row, $col) = @_;
764 898
765 ($row - $self->{beg}) * $self->{term}->ncol + $col 899 ($row - $self->{beg}) * $self->{ncol} + $col
766} 900}
767 901
768sub urxvt::line::coord_of { 902sub urxvt::line::coord_of {
769 my ($self, $offset) = @_; 903 my ($self, $offset) = @_;
770 904
771 use integer; 905 use integer;
772 906
773 ( 907 (
774 $offset / $self->{term}->ncol + $self->{beg}, 908 $offset / $self->{ncol} + $self->{beg},
775 $offset % $self->{term}->ncol 909 $offset % $self->{ncol}
776 ) 910 )
777} 911}
778 912
779=item ($row, $col) = $line->coord_of ($offset) 913=item ($row, $col) = $line->coord_of ($offset)
780=item $text = $term->special_encode $string 914=item $text = $term->special_encode $string

Diff Legend

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