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.22 by root, Tue Jan 3 19:10:54 2006 UTC vs.
Revision 1.28 by root, Wed Jan 4 00:09:12 2006 UTC

… …
39 39
40=over 4 40=over 4
41 41
42=item selection 42=item selection
43 43
44Intelligent selection. This etxension tries to be more intelligent when the user 44Intelligent selection. This extension tries to be more intelligent when
45extends selections (double-click). 45the user extends selections (double-click). Right now, it tries to select
46urls and complete shell-quoted arguments, which is very convenient, too,
47if your F<ls> supports C<--quoting-style=shell>.
46 48
47It also offers the following bindable event: 49It also offers the following bindable event:
48 50
49=over 4 51=over 4
50 52
… …
71=head2 General API Considerations 73=head2 General API Considerations
72 74
73All objects (such as terminals, time watchers etc.) are typical 75All objects (such as terminals, time watchers etc.) are typical
74reference-to-hash objects. The hash can be used to store anything you 76reference-to-hash objects. The hash can be used to store anything you
75like. All members starting with an underscore (such as C<_ptr> or 77like. All members starting with an underscore (such as C<_ptr> or
76C<_hook>) are reserved for internal uses and must not be accessed or 78C<_hook>) are reserved for internal uses and B<MUST NOT> be accessed or
77modified). 79modified).
78 80
79When objects are destroyed on the C++ side, the perl object hashes are 81When objects are destroyed on the C++ side, the perl object hashes are
80emptied, so its best to store related objects such as time watchers and 82emptied, so its best to store related objects such as time watchers and
81the like inside the terminal object so they get destroyed as soon as the 83the like inside the terminal object so they get destroyed as soon as the
82terminal is destroyed. 84terminal is destroyed.
83 85
84=head2 Hooks 86=head2 Hooks
85 87
86The following subroutines can be declared in loaded scripts, and will be called 88The following subroutines can be declared in loaded scripts, and will be
87whenever the relevant event happens. 89called whenever the relevant event happens.
90
91The 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
93its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
94object that is shared between all packages is stored in the C<term>
95member.
88 96
89All of them must return a boolean value. If it is true, then the event 97All of them must return a boolean value. If it is true, then the event
90counts as being I<consumed>, and the invocation of other hooks is skipped, 98counts as being I<consumed>, and the invocation of other hooks is skipped,
91and the relevant action might not be carried out by the C++ code. 99and the relevant action might not be carried out by the C++ code.
92 100
… …
164 172
165=item on_tty_activity $term *NYI* 173=item on_tty_activity $term *NYI*
166 174
167Called whenever the program(s) running in the urxvt window send output. 175Called whenever the program(s) running in the urxvt window send output.
168 176
177=item on_osc_seq $term, $string
178
179Called whenever the B<ESC ] 777 ; string ST> command sequence is
180processed. Cursor position and other state information is up-to-date when
181this happens. For interoperability, the string should start with the
182extension name and a colon, to distinguish it from commands for other
183extensions, and this might be enforced in the future.
184
169=item on_refresh_begin $term 185=item on_refresh_begin $term
170 186
171Called just before the screen gets redrawn. Can be used for overlay 187Called just before the screen gets redrawn. Can be used for overlay
172or similar effects by modify terminal contents in refresh_begin, and 188or similar effects by modify terminal contents in refresh_begin, and
173restoring them in refresh_end. The built-in overlay and selection display 189restoring them in refresh_end. The built-in overlay and selection display
… …
183C<perl:string> action bound to it (see description of the B<keysym> 199C<perl:string> action bound to it (see description of the B<keysym>
184resource in the @@RXVT_NAME@@(1) manpage). 200resource in the @@RXVT_NAME@@(1) manpage).
185 201
186=back 202=back
187 203
204=head2 Variables in the C<urxvt> Package
205
206=over 4
207
208=item $urxvt::TERM
209
210The current terminal. Whenever a callback/Hook is bein executed, this
211variable stores the current C<urxvt::term> object.
212
213=back
214
188=head2 Functions in the C<urxvt> Package 215=head2 Functions in the C<urxvt> Package
189 216
190=over 4 217=over 4
191 218
192=item urxvt::fatal $errormessage 219=item urxvt::fatal $errormessage
… …
265=cut 292=cut
266 293
267package urxvt; 294package urxvt;
268 295
269use strict; 296use strict;
297use Scalar::Util ();
270 298
271our $term; 299our $TERM;
272our @HOOKNAME; 300our @HOOKNAME;
273our $LIBDIR; 301our $LIBDIR;
274 302
275BEGIN { 303BEGIN {
276 urxvt->bootstrap; 304 urxvt->bootstrap;
… …
301 my $name = $HOOKNAME[$htype]; 329 my $name = $HOOKNAME[$htype];
302 330
303 my $ref = $pkg->can ("on_" . lc $name) 331 my $ref = $pkg->can ("on_" . lc $name)
304 or next; 332 or next;
305 333
306 $term->{_hook}[$htype]{$ref*1} = $ref; 334 $TERM->{_hook}[$htype]{$pkg} = $ref;
307 $hook_count[$htype]++ 335 $hook_count[$htype]++
308 or set_should_invoke $htype, 1; 336 or set_should_invoke $htype, 1;
309 } 337 }
310} 338}
311 339
… …
335 } 363 }
336} 364}
337 365
338# called by the rxvt core 366# called by the rxvt core
339sub invoke { 367sub invoke {
340 local $term = shift; 368 local $TERM = shift;
341 my $htype = shift; 369 my $htype = shift;
342 370
343 if ($htype == 0) { # INIT 371 if ($htype == 0) { # INIT
344 my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl"); 372 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
345 373
346 for my $ext (split /:/, $term->resource ("perl_ext")) { 374 for my $ext (split /:/, $TERM->resource ("perl_ext")) {
347 my @files = grep -f $_, map "$_/$ext", @dirs; 375 my @files = grep -f $_, map "$_/$ext", @dirs;
348 376
349 if (@files) { 377 if (@files) {
350 register_package script_package $files[0]; 378 register_package script_package $files[0];
351 } else { 379 } else {
352 warn "perl extension '$ext' not found in perl library search path\n"; 380 warn "perl extension '$ext' not found in perl library search path\n";
353 } 381 }
354 } 382 }
355 383
356 } elsif ($htype == 1) { # DESTROY 384 } elsif ($htype == 1) { # DESTROY
357 if (my $hook = $term->{_hook}) { 385 if (my $hook = $TERM->{_hook}) {
358 for my $htype (0..$#$hook) { 386 for my $htype (0..$#$hook) {
359 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 387 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
360 or set_should_invoke $htype, 0; 388 or set_should_invoke $htype, 0;
361 } 389 }
362 } 390 }
363 } 391 }
364 392
365 my $cb = $term->{_hook}[$htype] 393 my $cb = $TERM->{_hook}[$htype]
366 or return; 394 or return;
367 395
368 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")" 396 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
369 if $verbosity >= 10; 397 if $verbosity >= 10;
370 398
399 keys %$cb;
400
371 while (my ($k, $v) = each %$cb) { 401 while (my ($pkg, $cb) = each %$cb) {
372 return 1 if $v->($term, @_); 402 return 1
403 if $cb->(
404 $TERM->{$pkg} ||= do {
405 my $proxy = bless { }, urxvt::term::proxy::;
406 Scalar::Util::weaken ($proxy->{term} = $TERM);
407 $proxy
408 },
409 @_,
410 );
373 } 411 }
374 412
375 0 413 0
414}
415
416sub urxvt::term::proxy::AUTOLOAD {
417 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/
418 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable";
419
420 eval qq{
421 sub $urxvt::term::proxy::AUTOLOAD {
422 my \$proxy = shift;
423 \$proxy->{term}->$1 (\@_)
424 }
425 1
426 } or die "FATAL: unable to compile method forwarder: $@";
427
428 goto &$urxvt::term::proxy::AUTOLOAD;
376} 429}
377 430
378=head2 The C<urxvt::term> Class 431=head2 The C<urxvt::term> Class
379 432
380=over 4 433=over 4
… …
542=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 595=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
543 596
544Returns the text of the entire row with number C<$row_number>. Row C<0> 597Returns the text of the entire row with number C<$row_number>. Row C<0>
545is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost 598is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost
546terminal line. The scrollback buffer starts at line C<-1> and extends to 599terminal line. The scrollback buffer starts at line C<-1> and extends to
547line C<< -$term->nsaved >>. 600line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line
601is requested.
548 602
549If C<$new_text> is specified, it will replace characters in the current 603If C<$new_text> is specified, it will replace characters in the current
550line, starting at column C<$start_col> (default C<0>), which is useful 604line, starting at column C<$start_col> (default C<0>), which is useful
551to replace only parts of a line. The font index in the rendition will 605to replace only parts of a line. The font index in the rendition will
552automatically be updated. 606automatically be updated.
… …
574 628
575See the section on RENDITION, above. 629See the section on RENDITION, above.
576 630
577=item $length = $term->ROW_l ($row_number[, $new_length]) 631=item $length = $term->ROW_l ($row_number[, $new_length])
578 632
579Returns the number of screen cells that are in use ("the line length"). If 633Returns the number of screen cells that are in use ("the line
580it is C<-1>, then the line is part of a multiple-row logical "line", which 634length"). Unlike the urxvt core, this returns C<< $term->ncol >> if the
581means all characters are in use and it is continued on the next row. 635line is joined with the following one.
582 636
637=item $bool = $term->is_longer ($row_number)
638
639Returns true if the row is part of a multiple-row logical "line" (i.e.
640joined with the following row), which means all characters are in use
641and it is continued on the next row (and possibly a continuation of the
642previous row(s)).
643
644=item $line = $term->line ($row_number)
645
646Create and return a new C<urxvt::line> object that stores information
647about the logical line that row C<$row_number> is part of. It supports the
648following methods:
649
650=over 4
651
652=item $text = $line->t
653
654Returns the full text of the line, similar to C<ROW_t>
655
656=item $rend = $line->r
657
658Returns the full rendition array of the line, similar to C<ROW_r>
659
660=item $length = $line->l
661
662Returns the length of the line in cells, similar to C<ROW_l>.
663
664=item $rownum = $line->beg
665
666=item $rownum = $line->end
667
668Return the row number of the first/last row of the line, respectively.
669
670=item $offset = $line->offset_of ($row, $col)
671
672Returns the character offset of the given row|col pair within the logical
673line.
674
675=item ($row, $col) = $line->coord_of ($offset)
676
677Translates a string offset into terminal coordinates again.
678
679=back
680
681=cut
682
683sub urxvt::term::line {
684 my ($self, $row) = @_;
685
686 my $maxrow = $self->nrow - 1;
687
688 my ($beg, $end) = ($row, $row);
689
690 --$beg while $self->ROW_is_longer ($beg - 1);
691 ++$end while $self->ROW_is_longer ($end) && $end < $maxrow;
692
693 bless {
694 term => $self,
695 beg => $beg,
696 end => $end,
697 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
698 }, urxvt::line::
699}
700
701sub urxvt::line::t {
702 my ($self) = @_;
703
704 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
705 0, $self->{len}
706}
707
708sub urxvt::line::r {
709 my ($self) = @_;
710
711 my $rend = [
712 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
713 ];
714 $#$rend = $self->{len} - 1;
715 $rend
716}
717
718sub urxvt::line::beg { $_[0]{beg} }
719sub urxvt::line::end { $_[0]{end} }
720sub urxvt::line::l { $_[0]{len} }
721
722sub urxvt::line::offset_of {
723 my ($self, $row, $col) = @_;
724
725 ($row - $self->{beg}) * $self->{term}->ncol + $col
726}
727
728sub urxvt::line::coord_of {
729 my ($self, $offset) = @_;
730
731 use integer;
732
733 (
734 $offset / $self->{term}->ncol + $self->{beg},
735 $offset % $self->{term}->ncol
736 )
737}
738
739=item ($row, $col) = $line->coord_of ($offset)
583=item $text = $term->special_encode $string 740=item $text = $term->special_encode $string
584 741
585Converts a perl string into the special encoding used by rxvt-unicode, 742Converts a perl string into the special encoding used by rxvt-unicode,
586where one character corresponds to one screen cell. See 743where one character corresponds to one screen cell. See
587C<< $term->ROW_t >> for details. 744C<< $term->ROW_t >> for details.
… …
701This variable controls the verbosity level of the perl extension. Higher 858This variable controls the verbosity level of the perl extension. Higher
702numbers indicate more verbose output. 859numbers indicate more verbose output.
703 860
704=over 4 861=over 4
705 862
706=item 0 - only fatal messages 863=item =0 - only fatal messages
707 864
708=item 3 - script loading and management 865=item =3 - script loading and management
709 866
710=item 10 - all events received 867=item =10 - all events received
711 868
712=back 869=back
713 870
714=head1 AUTHOR 871=head1 AUTHOR
715 872

Diff Legend

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