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.18 by root, Tue Jan 3 02:01:27 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
44Miscellaneous selection modifications. 44Intelligent selection. This extension tries to be more intelligent when
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>.
48
49It also offers the following bindable event:
45 50
46=over 4 51=over 4
47 52
48=item rot13 53=item rot13
49 54
52 URxvt.keysym.C-M-r: perl:selection:rot13 57 URxvt.keysym.C-M-r: perl:selection:rot13
53 58
54=back 59=back
55 60
56=item digital-clock 61=item digital-clock
62
63Displays a digital clock using the built-in overlay.
64
65=item example-refresh-hooks
57 66
58Displays 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
59window. Illustrates overwriting the refresh callbacks to create your own 68window. Illustrates overwriting the refresh callbacks to create your own
60overlays or changes. 69overlays or changes.
61 70
62=item simple-overlay-clock
63
64Displays a digital clock using the built-in overlay (colourful, useless).
65
66=back 71=back
67 72
68=head2 General API Considerations 73=head2 General API Considerations
69 74
70All objects (such as terminals, time watchers etc.) are typical 75All objects (such as terminals, time watchers etc.) are typical
71reference-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
72like. All members starting with an underscore (such as C<_ptr> or 77like. All members starting with an underscore (such as C<_ptr> or
73C<_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
74modified). 79modified).
75 80
76When 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
77emptied, 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
78the 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
79terminal is destroyed. 84terminal is destroyed.
80 85
81=head2 Hooks 86=head2 Hooks
82 87
83The following subroutines can be declared in loaded scripts, and will be called 88The following subroutines can be declared in loaded scripts, and will be
84whenever 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.
85 96
86All 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
87counts 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,
88and 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.
89 100
122requested from the server. The selection text can be queried and changed 133requested from the server. The selection text can be queried and changed
123by calling C<< $term->selection >>. 134by calling C<< $term->selection >>.
124 135
125Returning a true value aborts selection grabbing. It will still be hilighted. 136Returning a true value aborts selection grabbing. It will still be hilighted.
126 137
138=item on_sel_extend $term
139
140Called whenever the user tries to extend the selection (e.g. with a double
141click) and is either supposed to return false (normal operation), or
142should extend the selection itelf and return true to suppress the built-in
143processing.
144
145See the F<selection> example extension.
146
127=item on_focus_in $term 147=item on_focus_in $term
128 148
129Called whenever the window gets the keyboard focus, before urxvt does 149Called whenever the window gets the keyboard focus, before urxvt does
130focus in processing. 150focus in processing.
131 151
151number of lines that will be in the scrollback buffer. 171number of lines that will be in the scrollback buffer.
152 172
153=item on_tty_activity $term *NYI* 173=item on_tty_activity $term *NYI*
154 174
155Called whenever the program(s) running in the urxvt window send output. 175Called whenever the program(s) running in the urxvt window send output.
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.
156 184
157=item on_refresh_begin $term 185=item on_refresh_begin $term
158 186
159Called just before the screen gets redrawn. Can be used for overlay 187Called just before the screen gets redrawn. Can be used for overlay
160or similar effects by modify terminal contents in refresh_begin, and 188or similar effects by modify terminal contents in refresh_begin, and
171C<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>
172resource in the @@RXVT_NAME@@(1) manpage). 200resource in the @@RXVT_NAME@@(1) manpage).
173 201
174=back 202=back
175 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
176=head2 Functions in the C<urxvt> Package 215=head2 Functions in the C<urxvt> Package
177 216
178=over 4 217=over 4
179 218
180=item urxvt::fatal $errormessage 219=item urxvt::fatal $errormessage
193correct place, e.g. on stderr of the connecting urxvtc client. 232correct place, e.g. on stderr of the connecting urxvtc client.
194 233
195=item $time = urxvt::NOW 234=item $time = urxvt::NOW
196 235
197Returns the "current time" (as per the event loop). 236Returns the "current time" (as per the event loop).
237
238=back
198 239
199=head2 RENDITION 240=head2 RENDITION
200 241
201Rendition bitsets contain information about colour, font, font styles and 242Rendition bitsets contain information about colour, font, font styles and
202similar information for each screen cell. 243similar information for each screen cell.
218Return the rendition mask used for overlays by default. 259Return the rendition mask used for overlays by default.
219 260
220=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline 261=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
221 262
222Return the bit that enabled bold, italic, blink, reverse-video and 263Return the bit that enabled bold, italic, blink, reverse-video and
223underline, respectively. To enable such a style, just or it onto the 264underline, respectively. To enable such a style, just logically OR it into
224bitset. 265the bitset.
225 266
226=item $foreground = urxvt::GET_BASEFG $rend 267=item $foreground = urxvt::GET_BASEFG $rend
227 268
228=item $background = urxvt::GET_BASEBG $rend 269=item $background = urxvt::GET_BASEBG $rend
229 270
234=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 275=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
235 276
236Replace the foreground/background colour in the rendition mask with the 277Replace the foreground/background colour in the rendition mask with the
237specified one. 278specified one.
238 279
280=item $value = urxvt::GET_CUSTOM ($rend)
281
282Return the "custom" value: Every rendition has 5 bits for use by
283extensions. They can be set and changed as you like and are initially
284zero.
285
286=item $rend = urxvt::SET_CUSTOM ($rend, $new_value)
287
288Change the custom value.
289
239=back 290=back
240 291
241=cut 292=cut
242 293
243package urxvt; 294package urxvt;
244 295
245use strict; 296use strict;
297use Scalar::Util ();
246 298
247our $term; 299our $TERM;
248our @HOOKNAME; 300our @HOOKNAME;
249our $LIBDIR; 301our $LIBDIR;
250 302
251BEGIN { 303BEGIN {
252 urxvt->bootstrap; 304 urxvt->bootstrap;
277 my $name = $HOOKNAME[$htype]; 329 my $name = $HOOKNAME[$htype];
278 330
279 my $ref = $pkg->can ("on_" . lc $name) 331 my $ref = $pkg->can ("on_" . lc $name)
280 or next; 332 or next;
281 333
282 $term->{_hook}[$htype]{$ref*1} = $ref; 334 $TERM->{_hook}[$htype]{$pkg} = $ref;
283 $hook_count[$htype]++ 335 $hook_count[$htype]++
284 or set_should_invoke $htype, 1; 336 or set_should_invoke $htype, 1;
285 } 337 }
286} 338}
287 339
311 } 363 }
312} 364}
313 365
314# called by the rxvt core 366# called by the rxvt core
315sub invoke { 367sub invoke {
316 local $term = shift; 368 local $TERM = shift;
317 my $htype = shift; 369 my $htype = shift;
318 370
319 if ($htype == 0) { # INIT 371 if ($htype == 0) { # INIT
320 my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl"); 372 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
321 373
322 for my $ext (split /:/, $term->resource ("perl_ext")) { 374 for my $ext (split /:/, $TERM->resource ("perl_ext")) {
323 my @files = grep -f $_, map "$_/$ext", @dirs; 375 my @files = grep -f $_, map "$_/$ext", @dirs;
324 376
325 if (@files) { 377 if (@files) {
326 register_package script_package $files[0]; 378 register_package script_package $files[0];
327 } else { 379 } else {
328 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";
329 } 381 }
330 } 382 }
331 383
332 } elsif ($htype == 1) { # DESTROY 384 } elsif ($htype == 1) { # DESTROY
333 if (my $hook = $term->{_hook}) { 385 if (my $hook = $TERM->{_hook}) {
334 for my $htype (0..$#$hook) { 386 for my $htype (0..$#$hook) {
335 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 387 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
336 or set_should_invoke $htype, 0; 388 or set_should_invoke $htype, 0;
337 } 389 }
338 } 390 }
339 } 391 }
340 392
341 my $cb = $term->{_hook}[$htype] 393 my $cb = $TERM->{_hook}[$htype]
342 or return; 394 or return;
343 395
344 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")" 396 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
345 if $verbosity >= 10; 397 if $verbosity >= 10;
346 398
399 keys %$cb;
400
347 while (my ($k, $v) = each %$cb) { 401 while (my ($pkg, $cb) = each %$cb) {
348 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 );
349 } 411 }
350 412
351 0 413 0
352} 414}
353 415
354=back 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;
429}
355 430
356=head2 The C<urxvt::term> Class 431=head2 The C<urxvt::term> Class
357 432
358=over 4 433=over 4
359 434
415 490
416=item $oldtext = $term->selection ([$newtext]) 491=item $oldtext = $term->selection ([$newtext])
417 492
418Return the current selection text and optionally replace it by C<$newtext>. 493Return the current selection text and optionally replace it by C<$newtext>.
419 494
420=item $term->scr_overlay ($x, $y, $text) 495#=item $term->overlay ($x, $y, $text)
421 496#
422Create a simple multi-line overlay box. See the next method for details. 497#Create a simple multi-line overlay box. See the next method for details.
423 498#
424=cut 499#=cut
425 500
426sub urxvt::term::scr_overlay { 501sub urxvt::term::scr_overlay {
502die;
427 my ($self, $x, $y, $text) = @_; 503 my ($self, $x, $y, $text) = @_;
428 504
429 my @lines = split /\n/, $text; 505 my @lines = split /\n/, $text;
430 506
431 my $w = 0; 507 my $w = 0;
435 511
436 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 512 $self->scr_overlay_new ($x, $y, $w, scalar @lines);
437 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 513 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
438} 514}
439 515
440=item $term->scr_overlay_new ($x, $y, $width, $height) 516=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
441 517
442Create a new (empty) overlay at the given position with the given 518Create a new (empty) overlay at the given position with the given
443width/height. A border will be put around the box. If either C<$x> or 519width/height. C<$rstyle> defines the initial rendition style
444C<$y> is negative, then this is counted from the right/bottom side, 520(default: C<OVERLAY_RSTYLE>).
445respectively.
446 521
447=item $term->scr_overlay_off 522If C<$border> is C<2> (default), then a decorative border will be put
523around the box.
448 524
449Switch the overlay off again. 525If either C<$x> or C<$y> is negative, then this is counted from the
526right/bottom side, respectively.
450 527
451=item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE) 528This method returns an urxvt::overlay object. The overlay will be visible
529as long as the perl object is referenced.
452 530
453Put a single character (specified numerically) at the given overlay 531The methods currently supported on C<urxvt::overlay> objects are:
454position.
455 532
533=over 4
534
456=item $term->scr_overlay_set ($x, $y, $text) 535=item $overlay->set ($x, $y, $text, $rend)
457 536
458Write a string at the given position into the overlay. 537Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
538text in rxvt-unicode's special encoding and an array of rendition values
539at a specific position inside the overlay.
540
541=item $overlay->hide
542
543If visible, hide the overlay, but do not destroy it.
544
545=item $overlay->show
546
547If hidden, display the overlay again.
548
549=back
459 550
460=item $cellwidth = $term->strwidth $string 551=item $cellwidth = $term->strwidth $string
461 552
462Returns the number of screen-cells this string would need. Correctly 553Returns the number of screen-cells this string would need. Correctly
463accounts for wide and combining characters. 554accounts for wide and combining characters.
504=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 595=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
505 596
506Returns 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>
507is 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
508terminal 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
509line C<< -$term->nsaved >>. 600line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line
601is requested.
510 602
511If 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
512line, 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
513to 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
514automatically be updated. 606automatically be updated.
536 628
537See the section on RENDITION, above. 629See the section on RENDITION, above.
538 630
539=item $length = $term->ROW_l ($row_number[, $new_length]) 631=item $length = $term->ROW_l ($row_number[, $new_length])
540 632
541Returns 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
542it 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
543means all characters are in use and it is continued on the next row. 635line is joined with the following one.
544 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)
545=item $text = $term->special_encode $string 740=item $text = $term->special_encode $string
546 741
547Converts a perl string into the special encoding used by rxvt-unicode, 742Converts a perl string into the special encoding used by rxvt-unicode,
548where one character corresponds to one screen cell. See 743where one character corresponds to one screen cell. See
549C<< $term->ROW_t >> for details. 744C<< $term->ROW_t >> for details.
558=head2 The C<urxvt::timer> Class 753=head2 The C<urxvt::timer> Class
559 754
560This class implements timer watchers/events. Time is represented as a 755This class implements timer watchers/events. Time is represented as a
561fractional number of seconds since the epoch. Example: 756fractional number of seconds since the epoch. Example:
562 757
563 # create a digital clock display in upper right corner 758 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
564 $term->{timer} = urxvt::timer 759 $term->{timer} = urxvt::timer
565 ->new 760 ->new
566 ->start (urxvt::NOW) 761 ->interval (1)
567 ->cb (sub { 762 ->cb (sub {
568 my ($timer) = @_;
569 my $time = $timer->at;
570 $timer->start ($time + 1);
571 $self->scr_overlay (-1, 0, 763 $term->{overlay}->set (0, 0,
572 POSIX::strftime "%H:%M:%S", localtime $time); 764 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
573 }); 765 });
574 766
575=over 4 767=over 4
576 768
577=item $timer = new urxvt::timer 769=item $timer = new urxvt::timer
578 770
579Create a new timer object in stopped state. 771Create a new timer object in started state. It is scheduled to fire
772immediately.
580 773
581=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 774=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
582 775
583Set the callback to be called when the timer triggers. 776Set the callback to be called when the timer triggers.
584 777
587Return the time this watcher will fire next. 780Return the time this watcher will fire next.
588 781
589=item $timer = $timer->set ($tstamp) 782=item $timer = $timer->set ($tstamp)
590 783
591Set the time the event is generated to $tstamp. 784Set the time the event is generated to $tstamp.
785
786=item $timer = $timer->interval ($interval)
787
788Normally (and when C<$interval> is C<0>), the timer will automatically
789stop after it has fired once. If C<$interval> is non-zero, then the timer
790is automatically rescheduled at the given intervals.
592 791
593=item $timer = $timer->start 792=item $timer = $timer->start
594 793
595Start the timer. 794Start the timer.
596 795
659This variable controls the verbosity level of the perl extension. Higher 858This variable controls the verbosity level of the perl extension. Higher
660numbers indicate more verbose output. 859numbers indicate more verbose output.
661 860
662=over 4 861=over 4
663 862
664=item 0 - only fatal messages 863=item =0 - only fatal messages
665 864
666=item 3 - script loading and management 865=item =3 - script loading and management
667 866
668=item 10 - all events received 867=item =10 - all events received
669 868
670=back 869=back
671 870
672=head1 AUTHOR 871=head1 AUTHOR
673 872

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines