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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines