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.29 by root, Wed Jan 4 00:12: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 (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
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 (OSC =
180operating system command) is processed. Cursor position and other state
181information is up-to-date when this happens. For interoperability, the
182string should start with the extension name and a colon, to distinguish
183it from commands for other extensions, and this might be enforced in the
184future.
185
186Be careful not ever to trust (in a security sense) the data you receive,
187as its source can not easily be controleld (e-mail content, messages from
188other users on the same system etc.).
156 189
157=item on_refresh_begin $term 190=item on_refresh_begin $term
158 191
159Called just before the screen gets redrawn. Can be used for overlay 192Called just before the screen gets redrawn. Can be used for overlay
160or similar effects by modify terminal contents in refresh_begin, and 193or similar effects by modify terminal contents in refresh_begin, and
171C<perl:string> action bound to it (see description of the B<keysym> 204C<perl:string> action bound to it (see description of the B<keysym>
172resource in the @@RXVT_NAME@@(1) manpage). 205resource in the @@RXVT_NAME@@(1) manpage).
173 206
174=back 207=back
175 208
209=head2 Variables in the C<urxvt> Package
210
211=over 4
212
213=item $urxvt::TERM
214
215The current terminal. Whenever a callback/Hook is bein executed, this
216variable stores the current C<urxvt::term> object.
217
218=back
219
176=head2 Functions in the C<urxvt> Package 220=head2 Functions in the C<urxvt> Package
177 221
178=over 4 222=over 4
179 223
180=item urxvt::fatal $errormessage 224=item urxvt::fatal $errormessage
194 238
195=item $time = urxvt::NOW 239=item $time = urxvt::NOW
196 240
197Returns the "current time" (as per the event loop). 241Returns the "current time" (as per the event loop).
198 242
243=back
244
245=head2 RENDITION
246
247Rendition bitsets contain information about colour, font, font styles and
248similar information for each screen cell.
249
250The following "macros" deal with changes in rendition sets. You should
251never just create a bitset, you should always modify an existing one,
252as they contain important information required for correct operation of
253rxvt-unicode.
254
255=over 4
256
257=item $rend = urxvt::DEFAULT_RSTYLE
258
259Returns the default rendition, as used when the terminal is starting up or
260being reset. Useful as a base to start when creating renditions.
261
262=item $rend = urxvt::OVERLAY_RSTYLE
263
264Return the rendition mask used for overlays by default.
265
266=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
267
268Return the bit that enabled bold, italic, blink, reverse-video and
269underline, respectively. To enable such a style, just logically OR it into
270the bitset.
271
272=item $foreground = urxvt::GET_BASEFG $rend
273
274=item $background = urxvt::GET_BASEBG $rend
275
276Return the foreground/background colour index, respectively.
277
278=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
279
280=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
281
282Replace the foreground/background colour in the rendition mask with the
283specified one.
284
285=item $value = urxvt::GET_CUSTOM ($rend)
286
287Return the "custom" value: Every rendition has 5 bits for use by
288extensions. They can be set and changed as you like and are initially
289zero.
290
291=item $rend = urxvt::SET_CUSTOM ($rend, $new_value)
292
293Change the custom value.
294
295=back
296
199=cut 297=cut
200 298
201package urxvt; 299package urxvt;
202 300
203use strict; 301use strict;
302use Scalar::Util ();
204 303
205our $term; 304our $TERM;
206our @HOOKNAME; 305our @HOOKNAME;
207our $LIBDIR; 306our $LIBDIR;
208 307
209BEGIN { 308BEGIN {
210 urxvt->bootstrap; 309 urxvt->bootstrap;
235 my $name = $HOOKNAME[$htype]; 334 my $name = $HOOKNAME[$htype];
236 335
237 my $ref = $pkg->can ("on_" . lc $name) 336 my $ref = $pkg->can ("on_" . lc $name)
238 or next; 337 or next;
239 338
240 $term->{_hook}[$htype]{$ref*1} = $ref; 339 $TERM->{_hook}[$htype]{$pkg} = $ref;
241 $hook_count[$htype]++ 340 $hook_count[$htype]++
242 or set_should_invoke $htype, 1; 341 or set_should_invoke $htype, 1;
243 } 342 }
244} 343}
245 344
269 } 368 }
270} 369}
271 370
272# called by the rxvt core 371# called by the rxvt core
273sub invoke { 372sub invoke {
274 local $term = shift; 373 local $TERM = shift;
275 my $htype = shift; 374 my $htype = shift;
276 375
277 if ($htype == 0) { # INIT 376 if ($htype == 0) { # INIT
278 my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl"); 377 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
279 378
280 for my $ext (split /:/, $term->resource ("perl_ext")) { 379 for my $ext (split /:/, $TERM->resource ("perl_ext")) {
281 my @files = grep -f $_, map "$_/$ext", @dirs; 380 my @files = grep -f $_, map "$_/$ext", @dirs;
282 381
283 if (@files) { 382 if (@files) {
284 register_package script_package $files[0]; 383 register_package script_package $files[0];
285 } else { 384 } else {
286 warn "perl extension '$ext' not found in perl library search path\n"; 385 warn "perl extension '$ext' not found in perl library search path\n";
287 } 386 }
288 } 387 }
289 388
290 } elsif ($htype == 1) { # DESTROY 389 } elsif ($htype == 1) { # DESTROY
291 if (my $hook = $term->{_hook}) { 390 if (my $hook = $TERM->{_hook}) {
292 for my $htype (0..$#$hook) { 391 for my $htype (0..$#$hook) {
293 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 392 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
294 or set_should_invoke $htype, 0; 393 or set_should_invoke $htype, 0;
295 } 394 }
296 } 395 }
297 } 396 }
298 397
299 my $cb = $term->{_hook}[$htype] 398 my $cb = $TERM->{_hook}[$htype]
300 or return; 399 or return;
301 400
302 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")" 401 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
303 if $verbosity >= 10; 402 if $verbosity >= 10;
304 403
404 keys %$cb;
405
305 while (my ($k, $v) = each %$cb) { 406 while (my ($pkg, $cb) = each %$cb) {
306 return 1 if $v->($term, @_); 407 return 1
408 if $cb->(
409 $TERM->{$pkg} ||= do {
410 my $proxy = bless { }, urxvt::term::proxy::;
411 Scalar::Util::weaken ($proxy->{term} = $TERM);
412 $proxy
413 },
414 @_,
415 );
307 } 416 }
308 417
309 0 418 0
310} 419}
311 420
312=back 421sub urxvt::term::proxy::AUTOLOAD {
422 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/
423 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable";
424
425 eval qq{
426 sub $urxvt::term::proxy::AUTOLOAD {
427 my \$proxy = shift;
428 \$proxy->{term}->$1 (\@_)
429 }
430 1
431 } or die "FATAL: unable to compile method forwarder: $@";
432
433 goto &$urxvt::term::proxy::AUTOLOAD;
434}
313 435
314=head2 The C<urxvt::term> Class 436=head2 The C<urxvt::term> Class
315 437
316=over 4 438=over 4
317 439
373 495
374=item $oldtext = $term->selection ([$newtext]) 496=item $oldtext = $term->selection ([$newtext])
375 497
376Return the current selection text and optionally replace it by C<$newtext>. 498Return the current selection text and optionally replace it by C<$newtext>.
377 499
378=item $term->scr_overlay ($x, $y, $text) 500#=item $term->overlay ($x, $y, $text)
379 501#
380Create a simple multi-line overlay box. See the next method for details. 502#Create a simple multi-line overlay box. See the next method for details.
381 503#
382=cut 504#=cut
383 505
384sub urxvt::term::scr_overlay { 506sub urxvt::term::scr_overlay {
507die;
385 my ($self, $x, $y, $text) = @_; 508 my ($self, $x, $y, $text) = @_;
386 509
387 my @lines = split /\n/, $text; 510 my @lines = split /\n/, $text;
388 511
389 my $w = 0; 512 my $w = 0;
393 516
394 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 517 $self->scr_overlay_new ($x, $y, $w, scalar @lines);
395 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 518 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
396} 519}
397 520
398=item $term->scr_overlay_new ($x, $y, $width, $height) 521=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
399 522
400Create a new (empty) overlay at the given position with the given 523Create 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 524width/height. C<$rstyle> defines the initial rendition style
402C<$y> is negative, then this is counted from the right/bottom side, 525(default: C<OVERLAY_RSTYLE>).
403respectively.
404 526
405=item $term->scr_overlay_off 527If C<$border> is C<2> (default), then a decorative border will be put
528around the box.
406 529
407Switch the overlay off again. 530If either C<$x> or C<$y> is negative, then this is counted from the
531right/bottom side, respectively.
408 532
409=item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE) 533This method returns an urxvt::overlay object. The overlay will be visible
534as long as the perl object is referenced.
410 535
411Put a single character (specified numerically) at the given overlay 536The methods currently supported on C<urxvt::overlay> objects are:
412position.
413 537
538=over 4
539
414=item $term->scr_overlay_set ($x, $y, $text) 540=item $overlay->set ($x, $y, $text, $rend)
415 541
416Write a string at the given position into the overlay. 542Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
543text in rxvt-unicode's special encoding and an array of rendition values
544at a specific position inside the overlay.
545
546=item $overlay->hide
547
548If visible, hide the overlay, but do not destroy it.
549
550=item $overlay->show
551
552If hidden, display the overlay again.
553
554=back
417 555
418=item $cellwidth = $term->strwidth $string 556=item $cellwidth = $term->strwidth $string
419 557
420Returns the number of screen-cells this string would need. Correctly 558Returns the number of screen-cells this string would need. Correctly
421accounts for wide and combining characters. 559accounts for wide and combining characters.
462=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 600=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
463 601
464Returns the text of the entire row with number C<$row_number>. Row C<0> 602Returns 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 603is 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 604terminal line. The scrollback buffer starts at line C<-1> and extends to
467line C<< -$term->nsaved >>. 605line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line
606is requested.
468 607
469If C<$new_text> is specified, it will replace characters in the current 608If 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 609line, 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 610to replace only parts of a line. The font index in the rendition will
472automatically be updated. 611automatically be updated.
473 612
474C<$text> is in a special encoding: tabs and wide characters that use more 613C<$text> is in a special encoding: tabs and wide characters that use more
475than one cell when displayed are padded with urxvt::NOCHAR characters 614than one cell when displayed are padded with urxvt::NOCHAR characters
476(C<chr 65535>). Characters with combining characters and other characters 615(C<chr 65535>). Characters with combining characters and other characters
490bitsets. Rendition bitsets contain information about colour, font, font 629bitsets. Rendition bitsets contain information about colour, font, font
491styles and similar information. See also C<< $term->ROW_t >>. 630styles and similar information. See also C<< $term->ROW_t >>.
492 631
493When setting rendition, the font mask will be ignored. 632When setting rendition, the font mask will be ignored.
494 633
495See the section on RENDITION, below. 634See the section on RENDITION, above.
496 635
497=item $length = $term->ROW_l ($row_number[, $new_length]) 636=item $length = $term->ROW_l ($row_number[, $new_length])
498 637
499Returns the number of screen cells that are in use ("the line length"). If 638Returns 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 639length"). 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. 640line is joined with the following one.
502 641
642=item $bool = $term->is_longer ($row_number)
643
644Returns true if the row is part of a multiple-row logical "line" (i.e.
645joined with the following row), which means all characters are in use
646and it is continued on the next row (and possibly a continuation of the
647previous row(s)).
648
649=item $line = $term->line ($row_number)
650
651Create and return a new C<urxvt::line> object that stores information
652about the logical line that row C<$row_number> is part of. It supports the
653following methods:
654
655=over 4
656
657=item $text = $line->t
658
659Returns the full text of the line, similar to C<ROW_t>
660
661=item $rend = $line->r
662
663Returns the full rendition array of the line, similar to C<ROW_r>
664
665=item $length = $line->l
666
667Returns the length of the line in cells, similar to C<ROW_l>.
668
669=item $rownum = $line->beg
670
671=item $rownum = $line->end
672
673Return the row number of the first/last row of the line, respectively.
674
675=item $offset = $line->offset_of ($row, $col)
676
677Returns the character offset of the given row|col pair within the logical
678line.
679
680=item ($row, $col) = $line->coord_of ($offset)
681
682Translates a string offset into terminal coordinates again.
683
684=back
685
686=cut
687
688sub urxvt::term::line {
689 my ($self, $row) = @_;
690
691 my $maxrow = $self->nrow - 1;
692
693 my ($beg, $end) = ($row, $row);
694
695 --$beg while $self->ROW_is_longer ($beg - 1);
696 ++$end while $self->ROW_is_longer ($end) && $end < $maxrow;
697
698 bless {
699 term => $self,
700 beg => $beg,
701 end => $end,
702 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
703 }, urxvt::line::
704}
705
706sub urxvt::line::t {
707 my ($self) = @_;
708
709 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
710 0, $self->{len}
711}
712
713sub urxvt::line::r {
714 my ($self) = @_;
715
716 my $rend = [
717 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
718 ];
719 $#$rend = $self->{len} - 1;
720 $rend
721}
722
723sub urxvt::line::beg { $_[0]{beg} }
724sub urxvt::line::end { $_[0]{end} }
725sub urxvt::line::l { $_[0]{len} }
726
727sub urxvt::line::offset_of {
728 my ($self, $row, $col) = @_;
729
730 ($row - $self->{beg}) * $self->{term}->ncol + $col
731}
732
733sub urxvt::line::coord_of {
734 my ($self, $offset) = @_;
735
736 use integer;
737
738 (
739 $offset / $self->{term}->ncol + $self->{beg},
740 $offset % $self->{term}->ncol
741 )
742}
743
744=item ($row, $col) = $line->coord_of ($offset)
503=item $text = $term->special_encode $string 745=item $text = $term->special_encode $string
504 746
505Converts a perl string into the special encoding used by rxvt-unicode, 747Converts a perl string into the special encoding used by rxvt-unicode,
506where one character corresponds to one screen cell. See 748where one character corresponds to one screen cell. See
507C<< $term->ROW_t >> for details. 749C<< $term->ROW_t >> for details.
511Converts rxvt-unicodes text reprsentation into a perl string. See 753Converts rxvt-unicodes text reprsentation into a perl string. See
512C<< $term->ROW_t >> for details. 754C<< $term->ROW_t >> for details.
513 755
514=back 756=back
515 757
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 758=head2 The C<urxvt::timer> Class
538 759
539This class implements timer watchers/events. Time is represented as a 760This class implements timer watchers/events. Time is represented as a
540fractional number of seconds since the epoch. Example: 761fractional number of seconds since the epoch. Example:
541 762
542 # create a digital clock display in upper right corner 763 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
543 $term->{timer} = urxvt::timer 764 $term->{timer} = urxvt::timer
544 ->new 765 ->new
545 ->start (urxvt::NOW) 766 ->interval (1)
546 ->cb (sub { 767 ->cb (sub {
547 my ($timer) = @_;
548 my $time = $timer->at;
549 $timer->start ($time + 1);
550 $self->scr_overlay (-1, 0, 768 $term->{overlay}->set (0, 0,
551 POSIX::strftime "%H:%M:%S", localtime $time); 769 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
552 }); 770 });
553 771
554=over 4 772=over 4
555 773
556=item $timer = new urxvt::timer 774=item $timer = new urxvt::timer
557 775
558Create a new timer object in stopped state. 776Create a new timer object in started state. It is scheduled to fire
777immediately.
559 778
560=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 779=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
561 780
562Set the callback to be called when the timer triggers. 781Set the callback to be called when the timer triggers.
563 782
566Return the time this watcher will fire next. 785Return the time this watcher will fire next.
567 786
568=item $timer = $timer->set ($tstamp) 787=item $timer = $timer->set ($tstamp)
569 788
570Set the time the event is generated to $tstamp. 789Set the time the event is generated to $tstamp.
790
791=item $timer = $timer->interval ($interval)
792
793Normally (and when C<$interval> is C<0>), the timer will automatically
794stop after it has fired once. If C<$interval> is non-zero, then the timer
795is automatically rescheduled at the given intervals.
571 796
572=item $timer = $timer->start 797=item $timer = $timer->start
573 798
574Start the timer. 799Start the timer.
575 800
638This variable controls the verbosity level of the perl extension. Higher 863This variable controls the verbosity level of the perl extension. Higher
639numbers indicate more verbose output. 864numbers indicate more verbose output.
640 865
641=over 4 866=over 4
642 867
643=item 0 - only fatal messages 868=item =0 - only fatal messages
644 869
645=item 3 - script loading and management 870=item =3 - script loading and management
646 871
647=item 10 - all events received 872=item =10 - all events received
648 873
649=back 874=back
650 875
651=head1 AUTHOR 876=head1 AUTHOR
652 877

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines