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.17 by root, Tue Jan 3 01:45:03 2006 UTC vs.
Revision 1.26 by root, Tue Jan 3 21:22:22 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 (colorful, 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
121Called whenever a selection has been copied, but before the selection is 132Called whenever a selection has been copied, but before the selection is
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.
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.
126 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.
171C<perl:string> action bound to it (see description of the B<keysym> 191C<perl:string> action bound to it (see description of the B<keysym>
172resource in the @@RXVT_NAME@@(1) manpage). 192resource in the @@RXVT_NAME@@(1) manpage).
173 193
174=back 194=back
175 195
196=head2 Variables in the C<urxvt> Package
197
198=over 4
199
200=item $urxvt::TERM
201
202The current terminal. Whenever a callback/Hook is bein executed, this
203variable stores the current C<urxvt::term> object.
204
205=back
206
176=head2 Functions in the C<urxvt> Package 207=head2 Functions in the C<urxvt> Package
177 208
178=over 4 209=over 4
179 210
180=item urxvt::fatal $errormessage 211=item urxvt::fatal $errormessage
194 225
195=item $time = urxvt::NOW 226=item $time = urxvt::NOW
196 227
197Returns the "current time" (as per the event loop). 228Returns the "current time" (as per the event loop).
198 229
230=back
231
232=head2 RENDITION
233
234Rendition bitsets contain information about colour, font, font styles and
235similar information for each screen cell.
236
237The following "macros" deal with changes in rendition sets. You should
238never just create a bitset, you should always modify an existing one,
239as they contain important information required for correct operation of
240rxvt-unicode.
241
242=over 4
243
244=item $rend = urxvt::DEFAULT_RSTYLE
245
246Returns the default rendition, as used when the terminal is starting up or
247being reset. Useful as a base to start when creating renditions.
248
249=item $rend = urxvt::OVERLAY_RSTYLE
250
251Return the rendition mask used for overlays by default.
252
253=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
254
255Return the bit that enabled bold, italic, blink, reverse-video and
256underline, respectively. To enable such a style, just logically OR it into
257the bitset.
258
259=item $foreground = urxvt::GET_BASEFG $rend
260
261=item $background = urxvt::GET_BASEBG $rend
262
263Return the foreground/background colour index, respectively.
264
265=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
266
267=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
268
269Replace the foreground/background colour in the rendition mask with the
270specified one.
271
272=item $value = urxvt::GET_CUSTOM ($rend)
273
274Return the "custom" value: Every rendition has 5 bits for use by
275extensions. They can be set and changed as you like and are initially
276zero.
277
278=item $rend = urxvt::SET_CUSTOM ($rend, $new_value)
279
280Change the custom value.
281
282=back
283
199=cut 284=cut
200 285
201package urxvt; 286package urxvt;
202 287
203use strict; 288use strict;
289use Scalar::Util ();
204 290
205our $term; 291our $TERM;
206our @HOOKNAME; 292our @HOOKNAME;
207our $LIBDIR; 293our $LIBDIR;
208 294
209BEGIN { 295BEGIN {
210 urxvt->bootstrap; 296 urxvt->bootstrap;
235 my $name = $HOOKNAME[$htype]; 321 my $name = $HOOKNAME[$htype];
236 322
237 my $ref = $pkg->can ("on_" . lc $name) 323 my $ref = $pkg->can ("on_" . lc $name)
238 or next; 324 or next;
239 325
240 $term->{_hook}[$htype]{$ref*1} = $ref; 326 $TERM->{_hook}[$htype]{$pkg} = $ref;
241 $hook_count[$htype]++ 327 $hook_count[$htype]++
242 or set_should_invoke $htype, 1; 328 or set_should_invoke $htype, 1;
243 } 329 }
244} 330}
245 331
269 } 355 }
270} 356}
271 357
272# called by the rxvt core 358# called by the rxvt core
273sub invoke { 359sub invoke {
274 local $term = shift; 360 local $TERM = shift;
275 my $htype = shift; 361 my $htype = shift;
276 362
277 if ($htype == 0) { # INIT 363 if ($htype == 0) { # INIT
278 my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl"); 364 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
279 365
280 for my $ext (split /:/, $term->resource ("perl_ext")) { 366 for my $ext (split /:/, $TERM->resource ("perl_ext")) {
281 my @files = grep -f $_, map "$_/$ext", @dirs; 367 my @files = grep -f $_, map "$_/$ext", @dirs;
282 368
283 if (@files) { 369 if (@files) {
284 register_package script_package $files[0]; 370 register_package script_package $files[0];
285 } else { 371 } else {
286 warn "perl extension '$ext' not found in perl library search path\n"; 372 warn "perl extension '$ext' not found in perl library search path\n";
287 } 373 }
288 } 374 }
289 375
290 } elsif ($htype == 1) { # DESTROY 376 } elsif ($htype == 1) { # DESTROY
291 if (my $hook = $term->{_hook}) { 377 if (my $hook = $TERM->{_hook}) {
292 for my $htype (0..$#$hook) { 378 for my $htype (0..$#$hook) {
293 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 379 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
294 or set_should_invoke $htype, 0; 380 or set_should_invoke $htype, 0;
295 } 381 }
296 } 382 }
297 } 383 }
298 384
299 my $cb = $term->{_hook}[$htype] 385 my $cb = $TERM->{_hook}[$htype]
300 or return; 386 or return;
301 387
302 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")" 388 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
303 if $verbosity >= 10; 389 if $verbosity >= 10;
304 390
391 keys %$cb;
392
305 while (my ($k, $v) = each %$cb) { 393 while (my ($pkg, $cb) = each %$cb) {
306 return 1 if $v->($term, @_); 394 return 1
395 if $cb->(
396 $TERM->{$pkg} ||= do {
397 my $proxy = bless { }, urxvt::term::proxy::;
398 Scalar::Util::weaken ($proxy->{term} = $TERM);
399 $proxy
400 },
401 @_,
402 );
307 } 403 }
308 404
309 0 405 0
310} 406}
311 407
312=back 408sub urxvt::term::proxy::AUTOLOAD {
409 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/
410 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable";
411
412 eval qq{
413 sub $urxvt::term::proxy::AUTOLOAD {
414 my \$proxy = shift;
415 \$proxy->{term}->$1 (\@_)
416 }
417 1
418 } or die "FATAL: unable to compile method forwarder: $@";
419
420 goto &$urxvt::term::proxy::AUTOLOAD;
421}
313 422
314=head2 The C<urxvt::term> Class 423=head2 The C<urxvt::term> Class
315 424
316=over 4 425=over 4
317 426
373 482
374=item $oldtext = $term->selection ([$newtext]) 483=item $oldtext = $term->selection ([$newtext])
375 484
376Return the current selection text and optionally replace it by C<$newtext>. 485Return the current selection text and optionally replace it by C<$newtext>.
377 486
378=item $term->scr_overlay ($x, $y, $text) 487#=item $term->overlay ($x, $y, $text)
379 488#
380Create a simple multi-line overlay box. See the next method for details. 489#Create a simple multi-line overlay box. See the next method for details.
381 490#
382=cut 491#=cut
383 492
384sub urxvt::term::scr_overlay { 493sub urxvt::term::scr_overlay {
494die;
385 my ($self, $x, $y, $text) = @_; 495 my ($self, $x, $y, $text) = @_;
386 496
387 my @lines = split /\n/, $text; 497 my @lines = split /\n/, $text;
388 498
389 my $w = 0; 499 my $w = 0;
393 503
394 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 504 $self->scr_overlay_new ($x, $y, $w, scalar @lines);
395 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 505 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
396} 506}
397 507
398=item $term->scr_overlay_new ($x, $y, $width, $height) 508=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
399 509
400Create a new (empty) overlay at the given position with the given 510Create a new (empty) overlay at the given position with the given
401width/height. A border will be put around the box. If either C<$x> or 511width/height. C<$rstyle> defines the initial rendition style
402C<$y> is negative, then this is counted from the right/bottom side, 512(default: C<OVERLAY_RSTYLE>).
403respectively.
404 513
405=item $term->scr_overlay_off 514If C<$border> is C<2> (default), then a decorative border will be put
515around the box.
406 516
407Switch the overlay off again. 517If either C<$x> or C<$y> is negative, then this is counted from the
518right/bottom side, respectively.
408 519
409=item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE) 520This method returns an urxvt::overlay object. The overlay will be visible
521as long as the perl object is referenced.
410 522
411Put a single character (specified numerically) at the given overlay 523The methods currently supported on C<urxvt::overlay> objects are:
412position.
413 524
525=over 4
526
414=item $term->scr_overlay_set ($x, $y, $text) 527=item $overlay->set ($x, $y, $text, $rend)
415 528
416Write a string at the given position into the overlay. 529Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
530text in rxvt-unicode's special encoding and an array of rendition values
531at a specific position inside the overlay.
532
533=item $overlay->hide
534
535If visible, hide the overlay, but do not destroy it.
536
537=item $overlay->show
538
539If hidden, display the overlay again.
540
541=back
417 542
418=item $cellwidth = $term->strwidth $string 543=item $cellwidth = $term->strwidth $string
419 544
420Returns the number of screen-cells this string would need. Correctly 545Returns the number of screen-cells this string would need. Correctly
421accounts for wide and combining characters. 546accounts for wide and combining characters.
462=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 587=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
463 588
464Returns the text of the entire row with number C<$row_number>. Row C<0> 589Returns the text of the entire row with number C<$row_number>. Row C<0>
465is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost 590is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost
466terminal line. The scrollback buffer starts at line C<-1> and extends to 591terminal line. The scrollback buffer starts at line C<-1> and extends to
467line C<< -$term->nsaved >>. 592line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line
593is requested.
468 594
469If C<$new_text> is specified, it will replace characters in the current 595If C<$new_text> is specified, it will replace characters in the current
470line, starting at column C<$start_col> (default C<0>), which is useful 596line, starting at column C<$start_col> (default C<0>), which is useful
471to replace only parts of a line. The font iindex in the rendition will 597to replace only parts of a line. The font index in the rendition will
472automatically be updated. 598automatically be updated.
473 599
474C<$text> is in a special encoding: tabs and wide characters that use more 600C<$text> is in a special encoding: tabs and wide characters that use more
475than one cell when displayed are padded with urxvt::NOCHAR characters 601than one cell when displayed are padded with urxvt::NOCHAR characters
476(C<chr 65535>). Characters with combining characters and other characters 602(C<chr 65535>). Characters with combining characters and other characters
490bitsets. Rendition bitsets contain information about colour, font, font 616bitsets. Rendition bitsets contain information about colour, font, font
491styles and similar information. See also C<< $term->ROW_t >>. 617styles and similar information. See also C<< $term->ROW_t >>.
492 618
493When setting rendition, the font mask will be ignored. 619When setting rendition, the font mask will be ignored.
494 620
495See the section on RENDITION, below. 621See the section on RENDITION, above.
496 622
497=item $length = $term->ROW_l ($row_number[, $new_length]) 623=item $length = $term->ROW_l ($row_number[, $new_length])
498 624
499Returns the number of screen cells that are in use ("the line length"). If 625Returns the number of screen cells that are in use ("the line
500it is C<-1>, then the line is part of a multiple-row logical "line", which 626length"). Unlike the urxvt core, this returns C<< $term->ncol >> if the
501means all characters are in use and it is continued on the next row. 627line is joined with the following one.
502 628
629=item $bool = $term->is_longer ($row_number)
630
631Returns true if the row is part of a multiple-row logical "line" (i.e.
632joined with the following row), which means all characters are in use
633and it is continued on the next row (and possibly a continuation of the
634previous row(s)).
635
636=item $line = $term->line ($row_number)
637
638Create and return a new C<urxvt::line> object that stores information
639about the logical line that row C<$row_number> is part of. It supports the
640following methods:
641
642=over 4
643
644=item $text = $line->t
645
646Returns the full text of the line, similar to C<ROW_t>
647
648=item $rend = $line->r
649
650Returns the full rendition array of the line, similar to C<ROW_r>
651
652=item $length = $line->l
653
654Returns the length of the line in cells, similar to C<ROW_l>.
655
656=item $rownum = $line->beg
657
658=item $rownum = $line->end
659
660Return the row number of the first/last row of the line, respectively.
661
662=item $offset = $line->offset_of ($row, $col)
663
664Returns the character offset of the given row|col pair within the logical
665line.
666
667=item ($row, $col) = $line->coord_of ($offset)
668
669Translates a string offset into terminal coordinates again.
670
671=back
672
673=cut
674
675sub urxvt::term::line {
676 my ($self, $row) = @_;
677
678 my $maxrow = $self->nrow - 1;
679
680 my ($beg, $end) = ($row, $row);
681
682 --$beg while $self->ROW_is_longer ($beg - 1);
683 ++$end while $self->ROW_is_longer ($end) && $end < $maxrow;
684
685 bless {
686 term => $self,
687 beg => $beg,
688 end => $end,
689 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
690 }, urxvt::line::
691}
692
693sub urxvt::line::t {
694 my ($self) = @_;
695
696 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
697 0, $self->{len}
698}
699
700sub urxvt::line::r {
701 my ($self) = @_;
702
703 my $rend = [
704 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
705 ];
706 $#$rend = $self->{len} - 1;
707 $rend
708}
709
710sub urxvt::line::beg { $_[0]{beg} }
711sub urxvt::line::end { $_[0]{end} }
712sub urxvt::line::l { $_[0]{len} }
713
714sub urxvt::line::offset_of {
715 my ($self, $row, $col) = @_;
716
717 ($row - $self->{beg}) * $self->{term}->ncol + $col
718}
719
720sub urxvt::line::coord_of {
721 my ($self, $offset) = @_;
722
723 use integer;
724
725 (
726 $offset / $self->{term}->ncol + $self->{beg},
727 $offset % $self->{term}->ncol
728 )
729}
730
731=item ($row, $col) = $line->coord_of ($offset)
503=item $text = $term->special_encode $string 732=item $text = $term->special_encode $string
504 733
505Converts a perl string into the special encoding used by rxvt-unicode, 734Converts a perl string into the special encoding used by rxvt-unicode,
506where one character corresponds to one screen cell. See 735where one character corresponds to one screen cell. See
507C<< $term->ROW_t >> for details. 736C<< $term->ROW_t >> for details.
511Converts rxvt-unicodes text reprsentation into a perl string. See 740Converts rxvt-unicodes text reprsentation into a perl string. See
512C<< $term->ROW_t >> for details. 741C<< $term->ROW_t >> for details.
513 742
514=back 743=back
515 744
516=head2 RENDITION
517
518Rendition bitsets contain information about colour, font, font styles and
519similar information for each screen cell.
520
521The following "macros" deal with changes in rendition sets. You should
522never just create a bitset, you should always modify an existing one,
523as they contain important information required for correct operation of
524rxvt-unicode.
525
526=over 4
527
528=item $rend = urxvt::DEFAULT_RSTYLE
529
530Returns the default rendition, as used when the terminal is starting up or
531being reset. Useful as a base
532
533=back
534
535=cut
536
537=head2 The C<urxvt::timer> Class 745=head2 The C<urxvt::timer> Class
538 746
539This class implements timer watchers/events. Time is represented as a 747This class implements timer watchers/events. Time is represented as a
540fractional number of seconds since the epoch. Example: 748fractional number of seconds since the epoch. Example:
541 749
542 # create a digital clock display in upper right corner 750 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
543 $term->{timer} = urxvt::timer 751 $term->{timer} = urxvt::timer
544 ->new 752 ->new
545 ->start (urxvt::NOW) 753 ->interval (1)
546 ->cb (sub { 754 ->cb (sub {
547 my ($timer) = @_;
548 my $time = $timer->at;
549 $timer->start ($time + 1);
550 $self->scr_overlay (-1, 0, 755 $term->{overlay}->set (0, 0,
551 POSIX::strftime "%H:%M:%S", localtime $time); 756 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
552 }); 757 });
553 758
554=over 4 759=over 4
555 760
556=item $timer = new urxvt::timer 761=item $timer = new urxvt::timer
557 762
558Create a new timer object in stopped state. 763Create a new timer object in started state. It is scheduled to fire
764immediately.
559 765
560=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 766=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
561 767
562Set the callback to be called when the timer triggers. 768Set the callback to be called when the timer triggers.
563 769
566Return the time this watcher will fire next. 772Return the time this watcher will fire next.
567 773
568=item $timer = $timer->set ($tstamp) 774=item $timer = $timer->set ($tstamp)
569 775
570Set the time the event is generated to $tstamp. 776Set the time the event is generated to $tstamp.
777
778=item $timer = $timer->interval ($interval)
779
780Normally (and when C<$interval> is C<0>), the timer will automatically
781stop after it has fired once. If C<$interval> is non-zero, then the timer
782is automatically rescheduled at the given intervals.
571 783
572=item $timer = $timer->start 784=item $timer = $timer->start
573 785
574Start the timer. 786Start the timer.
575 787

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines