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.24 by root, Tue Jan 3 20:47:36 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
305 while (my ($k, $v) = each %$cb) { 389 while (my ($pkg, $cb) = each %$cb) {
306 return 1 if $v->($term, @_); 390 return 1
391 if $cb->(
392 $TERM->{$pkg} ||= do {
393 my $proxy = bless { }, urxvt::term::proxy::;
394 Scalar::Util::weaken ($proxy->{term} = $TERM);
395 $proxy
396 },
397 @_,
398 );
307 } 399 }
308 400
309 0 401 0
310} 402}
311 403
312=back 404sub urxvt::term::proxy::AUTOLOAD {
405 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/
406 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable";
407
408 eval qq{
409 sub $urxvt::term::proxy::AUTOLOAD {
410 my \$proxy = shift;
411 \$proxy->{term}->$1 (\@_)
412 }
413 1
414 } or die "FATAL: unable to compile method forwarder: $@";
415
416 goto &$urxvt::term::proxy::AUTOLOAD;
417}
313 418
314=head2 The C<urxvt::term> Class 419=head2 The C<urxvt::term> Class
315 420
316=over 4 421=over 4
317 422
373 478
374=item $oldtext = $term->selection ([$newtext]) 479=item $oldtext = $term->selection ([$newtext])
375 480
376Return the current selection text and optionally replace it by C<$newtext>. 481Return the current selection text and optionally replace it by C<$newtext>.
377 482
378=item $term->scr_overlay ($x, $y, $text) 483#=item $term->overlay ($x, $y, $text)
379 484#
380Create a simple multi-line overlay box. See the next method for details. 485#Create a simple multi-line overlay box. See the next method for details.
381 486#
382=cut 487#=cut
383 488
384sub urxvt::term::scr_overlay { 489sub urxvt::term::scr_overlay {
490die;
385 my ($self, $x, $y, $text) = @_; 491 my ($self, $x, $y, $text) = @_;
386 492
387 my @lines = split /\n/, $text; 493 my @lines = split /\n/, $text;
388 494
389 my $w = 0; 495 my $w = 0;
393 499
394 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 500 $self->scr_overlay_new ($x, $y, $w, scalar @lines);
395 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 501 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
396} 502}
397 503
398=item $term->scr_overlay_new ($x, $y, $width, $height) 504=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
399 505
400Create a new (empty) overlay at the given position with the given 506Create 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 507width/height. C<$rstyle> defines the initial rendition style
402C<$y> is negative, then this is counted from the right/bottom side, 508(default: C<OVERLAY_RSTYLE>).
403respectively.
404 509
405=item $term->scr_overlay_off 510If C<$border> is C<2> (default), then a decorative border will be put
511around the box.
406 512
407Switch the overlay off again. 513If either C<$x> or C<$y> is negative, then this is counted from the
514right/bottom side, respectively.
408 515
409=item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE) 516This method returns an urxvt::overlay object. The overlay will be visible
517as long as the perl object is referenced.
410 518
411Put a single character (specified numerically) at the given overlay 519The methods currently supported on C<urxvt::overlay> objects are:
412position.
413 520
521=over 4
522
414=item $term->scr_overlay_set ($x, $y, $text) 523=item $overlay->set ($x, $y, $text, $rend)
415 524
416Write a string at the given position into the overlay. 525Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
526text in rxvt-unicode's special encoding and an array of rendition values
527at a specific position inside the overlay.
528
529=item $overlay->hide
530
531If visible, hide the overlay, but do not destroy it.
532
533=item $overlay->show
534
535If hidden, display the overlay again.
536
537=back
417 538
418=item $cellwidth = $term->strwidth $string 539=item $cellwidth = $term->strwidth $string
419 540
420Returns the number of screen-cells this string would need. Correctly 541Returns the number of screen-cells this string would need. Correctly
421accounts for wide and combining characters. 542accounts for wide and combining characters.
462=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 583=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
463 584
464Returns the text of the entire row with number C<$row_number>. Row C<0> 585Returns 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 586is 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 587terminal line. The scrollback buffer starts at line C<-1> and extends to
467line C<< -$term->nsaved >>. 588line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line
589is requested.
468 590
469If C<$new_text> is specified, it will replace characters in the current 591If 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 592line, 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 593to replace only parts of a line. The font index in the rendition will
472automatically be updated. 594automatically be updated.
473 595
474C<$text> is in a special encoding: tabs and wide characters that use more 596C<$text> is in a special encoding: tabs and wide characters that use more
475than one cell when displayed are padded with urxvt::NOCHAR characters 597than one cell when displayed are padded with urxvt::NOCHAR characters
476(C<chr 65535>). Characters with combining characters and other characters 598(C<chr 65535>). Characters with combining characters and other characters
490bitsets. Rendition bitsets contain information about colour, font, font 612bitsets. Rendition bitsets contain information about colour, font, font
491styles and similar information. See also C<< $term->ROW_t >>. 613styles and similar information. See also C<< $term->ROW_t >>.
492 614
493When setting rendition, the font mask will be ignored. 615When setting rendition, the font mask will be ignored.
494 616
495See the section on RENDITION, below. 617See the section on RENDITION, above.
496 618
497=item $length = $term->ROW_l ($row_number[, $new_length]) 619=item $length = $term->ROW_l ($row_number[, $new_length])
498 620
499Returns the number of screen cells that are in use ("the line length"). If 621Returns 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 622length"). 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. 623line is joined with the following one.
502 624
625=item $bool = $term->is_longer ($row_number)
626
627Returns true if the row is part of a multiple-row logical "line" (i.e.
628joined with the following row), which means all characters are in use
629and it is continued on the next row (and possibly a continuation of the
630previous row(s)).
631
632=item $line = $term->line ($row_number)
633
634Create and return a new C<urxvt::line> object that stores information
635about the logical line that row C<$row_number> is part of. It supports the
636following methods:
637
638=over 4
639
640=item $text = $line->t
641
642Returns the full text of the line, similar to C<ROW_t>
643
644=item $rend = $line->r
645
646Returns the full rendition array of the line, similar to C<ROW_r>
647
648=item $length = $line->l
649
650Returns the length of the line in cells, similar to C<ROW_l>.
651
652=item $rownum = $line->beg
653
654=item $rownum = $line->end
655
656Return the row number of the first/last row of the line, respectively.
657
658=item $offset = $line->offset_of ($row, $col)
659
660Returns the character offset of the given row|col pair within the logical
661line.
662
663=item ($row, $col) = $line->coord_of ($offset)
664
665Translates a string offset into terminal coordinates again.
666
667=back
668
669=cut
670
671sub urxvt::term::line {
672 my ($self, $row) = @_;
673
674 my $maxrow = $self->nrow - 1;
675
676 my ($beg, $end) = ($row, $row);
677
678 --$beg while $self->ROW_is_longer ($beg - 1);
679 ++$end while $self->ROW_is_longer ($end) && $end < $maxrow;
680
681 bless {
682 term => $self,
683 beg => $beg,
684 end => $end,
685 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
686 }, urxvt::line::
687}
688
689sub urxvt::line::t {
690 my ($self) = @_;
691
692 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
693 0, $self->{len}
694}
695
696sub urxvt::line::r {
697 my ($self) = @_;
698
699 my $rend = [
700 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
701 ];
702 $#$rend = $self->{len} - 1;
703 $rend
704}
705
706sub urxvt::line::beg { $_[0]{beg} }
707sub urxvt::line::end { $_[0]{end} }
708sub urxvt::line::l { $_[0]{len} }
709
710sub urxvt::line::offset_of {
711 my ($self, $row, $col) = @_;
712
713 ($row - $self->{beg}) * $self->{term}->ncol + $col
714}
715
716sub urxvt::line::coord_of {
717 my ($self, $offset) = @_;
718
719 use integer;
720
721 (
722 $offset / $self->{term}->ncol + $self->{beg},
723 $offset % $self->{term}->ncol
724 )
725}
726
727=item ($row, $col) = $line->coord_of ($offset)
503=item $text = $term->special_encode $string 728=item $text = $term->special_encode $string
504 729
505Converts a perl string into the special encoding used by rxvt-unicode, 730Converts a perl string into the special encoding used by rxvt-unicode,
506where one character corresponds to one screen cell. See 731where one character corresponds to one screen cell. See
507C<< $term->ROW_t >> for details. 732C<< $term->ROW_t >> for details.
511Converts rxvt-unicodes text reprsentation into a perl string. See 736Converts rxvt-unicodes text reprsentation into a perl string. See
512C<< $term->ROW_t >> for details. 737C<< $term->ROW_t >> for details.
513 738
514=back 739=back
515 740
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 741=head2 The C<urxvt::timer> Class
538 742
539This class implements timer watchers/events. Time is represented as a 743This class implements timer watchers/events. Time is represented as a
540fractional number of seconds since the epoch. Example: 744fractional number of seconds since the epoch. Example:
541 745
542 # create a digital clock display in upper right corner 746 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
543 $term->{timer} = urxvt::timer 747 $term->{timer} = urxvt::timer
544 ->new 748 ->new
545 ->start (urxvt::NOW) 749 ->interval (1)
546 ->cb (sub { 750 ->cb (sub {
547 my ($timer) = @_;
548 my $time = $timer->at;
549 $timer->start ($time + 1);
550 $self->scr_overlay (-1, 0, 751 $term->{overlay}->set (0, 0,
551 POSIX::strftime "%H:%M:%S", localtime $time); 752 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
552 }); 753 });
553 754
554=over 4 755=over 4
555 756
556=item $timer = new urxvt::timer 757=item $timer = new urxvt::timer
557 758
558Create a new timer object in stopped state. 759Create a new timer object in started state. It is scheduled to fire
760immediately.
559 761
560=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 762=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
561 763
562Set the callback to be called when the timer triggers. 764Set the callback to be called when the timer triggers.
563 765
566Return the time this watcher will fire next. 768Return the time this watcher will fire next.
567 769
568=item $timer = $timer->set ($tstamp) 770=item $timer = $timer->set ($tstamp)
569 771
570Set the time the event is generated to $tstamp. 772Set the time the event is generated to $tstamp.
773
774=item $timer = $timer->interval ($interval)
775
776Normally (and when C<$interval> is C<0>), the timer will automatically
777stop after it has fired once. If C<$interval> is non-zero, then the timer
778is automatically rescheduled at the given intervals.
571 779
572=item $timer = $timer->start 780=item $timer = $timer->start
573 781
574Start the timer. 782Start the timer.
575 783

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines