ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/src/urxvt.pm
(Generate patch)

Comparing rxvt-unicode/src/urxvt.pm (file contents):
Revision 1.18 by root, Tue Jan 3 02:01:27 2006 UTC vs.
Revision 1.55 by root, Sun Jan 8 05:50:27 2006 UTC

17 17
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test 18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
19 19
20=head1 DESCRIPTION 20=head1 DESCRIPTION
21 21
22Everytime a terminal object gets created, scripts specified via the 22Everytime a terminal object gets created, extension scripts specified via
23C<perl> resource are loaded and associated with it. 23the C<perl> resource are loaded and associated with it.
24 24
25Scripts are compiled in a 'use strict' and 'use utf8' environment, and 25Scripts are compiled in a 'use strict' and 'use utf8' environment, and
26thus must be encoded as UTF-8. 26thus must be encoded as UTF-8.
27 27
28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where 28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
37 37
38 @@RXVT_NAME@@ -pe <extensionname> 38 @@RXVT_NAME@@ -pe <extensionname>
39 39
40=over 4 40=over 4
41 41
42=item selection 42=item selection (enabled by default)
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
51 56
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
61=item option-popup (enabled by default)
62
63Binds a popup menu to Ctrl-Button3 that lets you toggle (some) options at
64runtime.
65
56=item digital-clock 66=item digital-clock
67
68Displays a digital clock using the built-in overlay.
69
70=item mark-urls
71
72Uses per-line display filtering (C<on_line_update>) to underline urls.
73
74=item block-graphics-to-ascii
75
76A not very useful example of filtering all text output to the terminal,
77by replacing all line-drawing characters (U+2500 .. U+259F) by a
78similar-looking ascii character.
79
80=item example-refresh-hooks
57 81
58Displays a very simple digital clock in the upper right corner of the 82Displays a very simple digital clock in the upper right corner of the
59window. Illustrates overwriting the refresh callbacks to create your own 83window. Illustrates overwriting the refresh callbacks to create your own
60overlays or changes. 84overlays or changes.
61 85
62=item simple-overlay-clock
63
64Displays a digital clock using the built-in overlay (colourful, useless).
65
66=back 86=back
67 87
68=head2 General API Considerations 88=head2 General API Considerations
69 89
70All objects (such as terminals, time watchers etc.) are typical 90All objects (such as terminals, time watchers etc.) are typical
71reference-to-hash objects. The hash can be used to store anything you 91reference-to-hash objects. The hash can be used to store anything you
72like. All members starting with an underscore (such as C<_ptr> or 92like. All members starting with an underscore (such as C<_ptr> or
73C<_hook>) are reserved for internal uses and must not be accessed or 93C<_hook>) are reserved for internal uses and B<MUST NOT> be accessed or
74modified). 94modified).
75 95
76When objects are destroyed on the C++ side, the perl object hashes are 96When 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 97emptied, 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 98the like inside the terminal object so they get destroyed as soon as the
79terminal is destroyed. 99terminal is destroyed.
80 100
101Argument names also often indicate the type of a parameter. Here are some
102hints on what they mean:
103
104=over 4
105
106=item $text
107
108Rxvt-unicodes special way of encoding text, where one "unicode" character
109always represents one screen cell. See L<row_t> for a discussion of this format.
110
111=item $string
112
113A perl text string, with an emphasis on I<text>. It can store all unicode
114characters and is to be distinguished with text encoded in a specific
115encoding (often locale-specific) and binary data.
116
117=item $octets
118
119Either binary data or - more common - a text string encoded in a
120locale-specific way.
121
122=back
123
81=head2 Hooks 124=head2 Hooks
82 125
83The following subroutines can be declared in loaded scripts, and will be called 126The following subroutines can be declared in extension files, and will be
84whenever the relevant event happens. 127called whenever the relevant event happens.
128
129The first argument passed to them is an object private to each terminal
130and extension package. You can call all C<urxvt::term> methods on it, but
131its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
132object that is shared between all packages is stored in the C<term>
133member. It is, however, blessed intot he package of the extension script,
134so for all practical purposes you can treat an extension script as a class.
85 135
86All of them must return a boolean value. If it is true, then the event 136All 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, 137counts 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. 138and the relevant action might not be carried out by the C++ code.
89 139
92=over 4 142=over 4
93 143
94=item on_init $term 144=item on_init $term
95 145
96Called after a new terminal object has been initialized, but before 146Called after a new terminal object has been initialized, but before
97windows are created or the command gets run. 147windows are created or the command gets run. Most methods are unsafe to
148call or deliver senseless data, as terminal size and other characteristics
149have not yet been determined. You can safely query and change resources,
150though.
98 151
99=item on_reset $term 152=item on_reset $term
100 153
101Called after the screen is "reset" for any reason, such as resizing or 154Called after the screen is "reset" for any reason, such as resizing or
102control sequences. Here is where you can react on changes to size-related 155control sequences. Here is where you can react on changes to size-related
122requested from the server. The selection text can be queried and changed 175requested from the server. The selection text can be queried and changed
123by calling C<< $term->selection >>. 176by calling C<< $term->selection >>.
124 177
125Returning a true value aborts selection grabbing. It will still be hilighted. 178Returning a true value aborts selection grabbing. It will still be hilighted.
126 179
127=item on_focus_in $term 180=item on_sel_extend $term
128 181
129Called whenever the window gets the keyboard focus, before urxvt does 182Called whenever the user tries to extend the selection (e.g. with a double
130focus in processing. 183click) and is either supposed to return false (normal operation), or
131 184should extend the selection itelf and return true to suppress the built-in
132=item on_focus_out $term
133
134Called wheneever the window loses keyboard focus, before urxvt does focus
135out processing. 185processing.
186
187See the F<selection> example extension.
136 188
137=item on_view_change $term, $offset 189=item on_view_change $term, $offset
138 190
139Called whenever the view offset changes, i..e the user or program 191Called whenever the view offset changes, i..e the user or program
140scrolls. Offset C<0> means display the normal terminal, positive values 192scrolls. Offset C<0> means display the normal terminal, positive values
151number of lines that will be in the scrollback buffer. 203number of lines that will be in the scrollback buffer.
152 204
153=item on_tty_activity $term *NYI* 205=item on_tty_activity $term *NYI*
154 206
155Called whenever the program(s) running in the urxvt window send output. 207Called whenever the program(s) running in the urxvt window send output.
208
209=item on_osc_seq $term, $string
210
211Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
212operating system command) is processed. Cursor position and other state
213information is up-to-date when this happens. For interoperability, the
214string should start with the extension name and a colon, to distinguish
215it from commands for other extensions, and this might be enforced in the
216future.
217
218Be careful not ever to trust (in a security sense) the data you receive,
219as its source can not easily be controleld (e-mail content, messages from
220other users on the same system etc.).
221
222=item on_add_lines $term, $string
223
224Called whenever text is about to be output, with the text as argument. You
225can filter/change and output the text yourself by returning a true value
226and calling C<< $term->scr_add_lines >> yourself. Please note that this
227might be very slow, however, as your hook is called for B<all> text being
228output.
229
230=item on_line_update $term, $row
231
232Called whenever a line was updated or changed. Can be used to filter
233screen output (e.g. underline urls or other useless stuff). Only lines
234that are being shown will be filtered, and, due to performance reasons,
235not always immediately.
236
237The row number is always the topmost row of the line if the line spans
238multiple rows.
239
240Please note that, if you change the line, then the hook might get called
241later with the already-modified line (e.g. if unrelated parts change), so
242you cannot just toggle rendition bits, but only set them.
156 243
157=item on_refresh_begin $term 244=item on_refresh_begin $term
158 245
159Called just before the screen gets redrawn. Can be used for overlay 246Called just before the screen gets redrawn. Can be used for overlay
160or similar effects by modify terminal contents in refresh_begin, and 247or similar effects by modify terminal contents in refresh_begin, and
169 256
170Called whenever the user presses a key combination that has a 257Called whenever the user presses a key combination that has a
171C<perl:string> action bound to it (see description of the B<keysym> 258C<perl:string> action bound to it (see description of the B<keysym>
172resource in the @@RXVT_NAME@@(1) manpage). 259resource in the @@RXVT_NAME@@(1) manpage).
173 260
261=item on_focus_in $term
262
263Called whenever the window gets the keyboard focus, before rxvt-unicode
264does focus in processing.
265
266=item on_focus_out $term
267
268Called wheneever the window loses keyboard focus, before rxvt-unicode does
269focus out processing.
270
271=item on_key_press $term, $event, $octets
272
273=item on_key_release $term, $event
274
275=item on_button_press $term, $event
276
277=item on_button_release $term, $event
278
279=item on_motion_notify $term, $event
280
281=item on_map_notify $term, $event
282
283=item on_unmap_notify $term, $event
284
285Called whenever the corresponding X event is received for the terminal If
286the hook returns true, then the even will be ignored by rxvt-unicode.
287
288The event is a hash with most values as named by Xlib (see the XEvent
289manpage), with the additional members C<row> and C<col>, which are the row
290and column under the mouse cursor.
291
292C<on_key_press> additionally receives the string rxvt-unicode would
293output, if any, in locale-specific encoding.
294
295subwindow.
296
174=back 297=back
175 298
299=head2 Variables in the C<urxvt> Package
300
301=over 4
302
303=item $urxvt::TERM
304
305The current terminal. This variable stores the current C<urxvt::term>
306object, whenever a callback/hook is executing.
307
308=back
309
176=head2 Functions in the C<urxvt> Package 310=head2 Functions in the C<urxvt> Package
177 311
178=over 4 312=over 4
313
314=item $term = new urxvt [arg...]
315
316Creates a new terminal, very similar as if you had started it with
317C<system $binfile, arg...>. Croaks (and probably outputs an error message)
318if the new instance couldn't be created. Returns C<undef> if the new
319instance didn't initialise perl, and the terminal object otherwise. The
320C<init> and C<start> hooks will be called during the call.
179 321
180=item urxvt::fatal $errormessage 322=item urxvt::fatal $errormessage
181 323
182Fatally aborts execution with the given error message. Avoid at all 324Fatally aborts execution with the given error message. Avoid at all
183costs! The only time this is acceptable is when the terminal process 325costs! The only time this is acceptable is when the terminal process
193correct place, e.g. on stderr of the connecting urxvtc client. 335correct place, e.g. on stderr of the connecting urxvtc client.
194 336
195=item $time = urxvt::NOW 337=item $time = urxvt::NOW
196 338
197Returns the "current time" (as per the event loop). 339Returns the "current time" (as per the event loop).
340
341=item urxvt::CurrentTime
342
343=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
344Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
345Button4Mask, Button5Mask, AnyModifier
346
347Various constants for use in X calls and event processing.
348
349=back
198 350
199=head2 RENDITION 351=head2 RENDITION
200 352
201Rendition bitsets contain information about colour, font, font styles and 353Rendition bitsets contain information about colour, font, font styles and
202similar information for each screen cell. 354similar information for each screen cell.
218Return the rendition mask used for overlays by default. 370Return the rendition mask used for overlays by default.
219 371
220=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline 372=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
221 373
222Return the bit that enabled bold, italic, blink, reverse-video and 374Return the bit that enabled bold, italic, blink, reverse-video and
223underline, respectively. To enable such a style, just or it onto the 375underline, respectively. To enable such a style, just logically OR it into
224bitset. 376the bitset.
225 377
226=item $foreground = urxvt::GET_BASEFG $rend 378=item $foreground = urxvt::GET_BASEFG $rend
227 379
228=item $background = urxvt::GET_BASEBG $rend 380=item $background = urxvt::GET_BASEBG $rend
229 381
234=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour) 386=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
235 387
236Replace the foreground/background colour in the rendition mask with the 388Replace the foreground/background colour in the rendition mask with the
237specified one. 389specified one.
238 390
391=item $value = urxvt::GET_CUSTOM ($rend)
392
393Return the "custom" value: Every rendition has 5 bits for use by
394extensions. They can be set and changed as you like and are initially
395zero.
396
397=item $rend = urxvt::SET_CUSTOM ($rend, $new_value)
398
399Change the custom value.
400
239=back 401=back
240 402
241=cut 403=cut
242 404
243package urxvt; 405package urxvt;
244 406
407use utf8;
245use strict; 408use strict;
409use Scalar::Util ();
410use List::Util ();
246 411
247our $term; 412our $VERSION = 1;
413our $TERM;
248our @HOOKNAME; 414our @HOOKNAME;
415our %OPTION;
249our $LIBDIR; 416our $LIBDIR;
250 417
251BEGIN { 418BEGIN {
252 urxvt->bootstrap; 419 urxvt->bootstrap;
253 420
277 my $name = $HOOKNAME[$htype]; 444 my $name = $HOOKNAME[$htype];
278 445
279 my $ref = $pkg->can ("on_" . lc $name) 446 my $ref = $pkg->can ("on_" . lc $name)
280 or next; 447 or next;
281 448
282 $term->{_hook}[$htype]{$ref*1} = $ref; 449 $TERM->{_hook}[$htype]{$pkg} = $ref;
283 $hook_count[$htype]++ 450 $hook_count[$htype]++
284 or set_should_invoke $htype, 1; 451 or set_should_invoke $htype, 1;
285 } 452 }
286} 453}
287 454
288my $script_pkg = "script0000"; 455my $extension_pkg = "extension0000";
289my %script_pkg; 456my %extension_pkg;
290 457
291# load a single script into its own package, once only 458# load a single script into its own package, once only
292sub script_package($) { 459sub extension_package($) {
293 my ($path) = @_; 460 my ($path) = @_;
294 461
295 $script_pkg{$path} ||= do { 462 $extension_pkg{$path} ||= do {
296 my $pkg = "urxvt::" . ($script_pkg++); 463 my $pkg = "urxvt::" . ($extension_pkg++);
297 464
298 verbose 3, "loading script '$path' into package '$pkg'"; 465 verbose 3, "loading extension '$path' into package '$pkg'";
299 466
300 open my $fh, "<:raw", $path 467 open my $fh, "<:raw", $path
301 or die "$path: $!"; 468 or die "$path: $!";
302 469
303 my $source = "package $pkg; use strict; use utf8;\n" 470 my $source = "package $pkg; use strict; use utf8;\n"
471 . "use base urxvt::term::proxy::;\n"
304 . "#line 1 \"$path\"\n{\n" 472 . "#line 1 \"$path\"\n{\n"
305 . (do { local $/; <$fh> }) 473 . (do { local $/; <$fh> })
306 . "\n};\n1"; 474 . "\n};\n1";
307 475
308 eval $source or die "$path: $@"; 476 eval $source or die "$path: $@";
309 477
310 $pkg 478 $pkg
311 } 479 }
312} 480}
313 481
482our $retval; # return value for urxvt
483
314# called by the rxvt core 484# called by the rxvt core
315sub invoke { 485sub invoke {
316 local $term = shift; 486 local $TERM = shift;
317 my $htype = shift; 487 my $htype = shift;
318 488
319 if ($htype == 0) { # INIT 489 if ($htype == 0) { # INIT
320 my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl"); 490 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
491
492 my %want_ext;
321 493
322 for my $ext (split /:/, $term->resource ("perl_ext")) { 494 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
495 if ($_ eq "default") {
496 $want_ext{$_}++ for qw(selection option-popup);
497 } elsif (/^-(.*)$/) {
498 delete $want_ext{$1};
499 } else {
500 $want_ext{$_}++;
501 }
502 }
503
504 for my $ext (keys %want_ext) {
323 my @files = grep -f $_, map "$_/$ext", @dirs; 505 my @files = grep -f $_, map "$_/$ext", @dirs;
324 506
325 if (@files) { 507 if (@files) {
326 register_package script_package $files[0]; 508 register_package extension_package $files[0];
327 } else { 509 } else {
328 warn "perl extension '$ext' not found in perl library search path\n"; 510 warn "perl extension '$ext' not found in perl library search path\n";
329 } 511 }
330 } 512 }
331 513
514 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
515 warn $@ if $@;
516 }
517
518 $retval = undef;
519
520 if (my $cb = $TERM->{_hook}[$htype]) {
521 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
522 if $verbosity >= 10;
523
524 keys %$cb;
525
526 while (my ($pkg, $cb) = each %$cb) {
527 eval {
528 $retval = $cb->(
529 $TERM->{_pkg}{$pkg} ||= do {
530 my $proxy = bless { }, $pkg;
531 Scalar::Util::weaken ($proxy->{term} = $TERM);
532 $proxy
533 },
534 @_,
535 ) and last;
536 };
537 warn $@ if $@;#d#
538 }
539 }
540
332 } elsif ($htype == 1) { # DESTROY 541 if ($htype == 1) { # DESTROY
542 # remove hooks if unused
333 if (my $hook = $term->{_hook}) { 543 if (my $hook = $TERM->{_hook}) {
334 for my $htype (0..$#$hook) { 544 for my $htype (0..$#$hook) {
335 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 545 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
336 or set_should_invoke $htype, 0; 546 or set_should_invoke $htype, 0;
337 } 547 }
338 } 548 }
549
550 # clear package objects
551 %$_ = () for values %{ $TERM->{_pkg} };
552
553 # clear package
554 %$TERM = ();
339 } 555 }
340 556
341 my $cb = $term->{_hook}[$htype] 557 $retval
342 or return; 558}
343 559
344 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")" 560# urxvt::term::proxy
345 if $verbosity >= 10;
346 561
347 while (my ($k, $v) = each %$cb) { 562sub urxvt::term::proxy::AUTOLOAD {
348 return 1 if $v->($term, @_); 563 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/
564 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable";
565
566 eval qq{
567 sub $urxvt::term::proxy::AUTOLOAD {
568 my \$proxy = shift;
569 \$proxy->{term}->$1 (\@_)
570 }
571 1
572 } or die "FATAL: unable to compile method forwarder: $@";
573
574 goto &$urxvt::term::proxy::AUTOLOAD;
575}
576
577# urxvt::destroy_hook
578
579sub urxvt::destroy_hook::DESTROY {
580 ${$_[0]}->();
581}
582
583sub urxvt::destroy_hook(&) {
584 bless \shift, urxvt::destroy_hook::
585}
586
587# urxvt::anyevent
588
589package urxvt::anyevent;
590
591our $VERSION = 1;
592
593$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
594push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
595
596sub timer {
597 my ($class, %arg) = @_;
598
599 my $cb = $arg{cb};
600
601 urxvt::timer
602 ->new
603 ->start (urxvt::NOW + $arg{after})
604 ->cb (sub {
605 $_[0]->stop; # need to cancel manually
606 $cb->();
607 })
608}
609
610sub io {
611 my ($class, %arg) = @_;
612
613 my $cb = $arg{cb};
614
615 bless [$arg{fh}, urxvt::iow
616 ->new
617 ->fd (fileno $arg{fh})
618 ->events (($arg{poll} =~ /r/ ? 1 : 0)
619 | ($arg{poll} =~ /w/ ? 2 : 0))
620 ->start
621 ->cb (sub {
622 $cb->(($_[1] & 1 ? 'r' : '')
623 . ($_[1] & 2 ? 'w' : ''));
624 })],
625 urxvt::anyevent::
626}
627
628sub DESTROY {
629 $_[0][1]->stop;
630}
631
632sub condvar {
633 bless \my $flag, urxvt::anyevent::condvar::
634}
635
636sub urxvt::anyevent::condvar::broadcast {
637 ${$_[0]}++;
638}
639
640sub urxvt::anyevent::condvar::wait {
641 unless (${$_[0]}) {
642 require Carp;
643 Carp::croak ("AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API");
349 } 644 }
350
351 0
352} 645}
353 646
354=back 647package urxvt::term;
355 648
356=head2 The C<urxvt::term> Class 649=head2 The C<urxvt::term> Class
357 650
358=over 4 651=over 4
652
653=item $term->destroy
654
655Destroy the terminal object (close the window, free resources etc.).
656
657=item $isset = $term->option ($optval[, $set])
658
659Returns true if the option specified by C<$optval> is enabled, and
660optionally change it. All option values are stored by name in the hash
661C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
662
663Here is a a likely non-exhaustive list of option names, please see the
664source file F</src/optinc.h> to see the actual list:
665
666 borderLess console cursorBlink cursorUnderline hold iconic insecure
667 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
668 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
669 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
670 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
671 tripleclickwords utmpInhibit visualBell
359 672
360=item $value = $term->resource ($name[, $newval]) 673=item $value = $term->resource ($name[, $newval])
361 674
362Returns the current resource value associated with a given name and 675Returns the current resource value associated with a given name and
363optionally sets a new value. Setting values is most useful in the C<init> 676optionally sets a new value. Setting values is most useful in the C<init>
373 686
374Please note that resource strings will currently only be freed when the 687Please note that resource strings will currently only be freed when the
375terminal is destroyed, so changing options frequently will eat memory. 688terminal is destroyed, so changing options frequently will eat memory.
376 689
377Here is a a likely non-exhaustive list of resource names, not all of which 690Here is a a likely non-exhaustive list of resource names, not all of which
378are supported in every build, please see the source to see the actual 691are supported in every build, please see the source file F</src/rsinc.h>
379list: 692to see the actual list:
380 693
381 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 694 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
382 borderLess color cursorBlink cursorUnderline cutchars delete_key 695 borderLess color cursorBlink cursorUnderline cutchars delete_key
383 display_name embed ext_bwidth fade font geometry hold iconName 696 display_name embed ext_bwidth fade font geometry hold iconName
384 imFont imLocale inputMethod insecure int_bwidth intensityStyles 697 imFont imLocale inputMethod insecure int_bwidth intensityStyles
385 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 698 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
386 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext 699 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
387 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 700 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
388 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 701 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
389 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 702 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
390 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 703 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
391 shade term_name title transparent transparent_all tripleclickwords 704 shade term_name title transparent transparent_all tripleclickwords
392 utmpInhibit visualBell 705 utmpInhibit visualBell
393 706
394=cut 707=cut
395 708
396sub urxvt::term::resource($$;$) { 709sub resource($$;$) {
397 my ($self, $name) = (shift, shift); 710 my ($self, $name) = (shift, shift);
398 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 711 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
399 goto &urxvt::term::_resource; 712 &urxvt::term::_resource
400} 713}
714
715=item $rend = $term->rstyle ([$new_rstyle])
716
717Return and optionally change the current rendition. Text that is output by
718the terminal application will use this style.
719
720=item ($row, $col) = $term->screen_cur ([$row, $col])
721
722Return the current coordinates of the text cursor position and optionally
723set it (which is usually bad as applications don't expect that).
401 724
402=item ($row, $col) = $term->selection_mark ([$row, $col]) 725=item ($row, $col) = $term->selection_mark ([$row, $col])
403 726
404=item ($row, $col) = $term->selection_beg ([$row, $col]) 727=item ($row, $col) = $term->selection_beg ([$row, $col])
405 728
415 738
416=item $oldtext = $term->selection ([$newtext]) 739=item $oldtext = $term->selection ([$newtext])
417 740
418Return the current selection text and optionally replace it by C<$newtext>. 741Return the current selection text and optionally replace it by C<$newtext>.
419 742
420=item $term->scr_overlay ($x, $y, $text) 743#=item $term->overlay ($x, $y, $text)
421 744#
422Create a simple multi-line overlay box. See the next method for details. 745#Create a simple multi-line overlay box. See the next method for details.
746#
747#=cut
748#
749#sub urxvt::term::scr_overlay {
750# my ($self, $x, $y, $text) = @_;
751#
752# my @lines = split /\n/, $text;
753#
754# my $w = 0;
755# for (map $self->strwidth ($_), @lines) {
756# $w = $_ if $w < $_;
757# }
758#
759# $self->scr_overlay_new ($x, $y, $w, scalar @lines);
760# $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
761#}
762
763=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
764
765Create a new (empty) overlay at the given position with the given
766width/height. C<$rstyle> defines the initial rendition style
767(default: C<OVERLAY_RSTYLE>).
768
769If C<$border> is C<2> (default), then a decorative border will be put
770around the box.
771
772If either C<$x> or C<$y> is negative, then this is counted from the
773right/bottom side, respectively.
774
775This method returns an urxvt::overlay object. The overlay will be visible
776as long as the perl object is referenced.
777
778The methods currently supported on C<urxvt::overlay> objects are:
779
780=over 4
781
782=item $overlay->set ($x, $y, $text, $rend)
783
784Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
785text in rxvt-unicode's special encoding and an array of rendition values
786at a specific position inside the overlay.
787
788=item $overlay->hide
789
790If visible, hide the overlay, but do not destroy it.
791
792=item $overlay->show
793
794If hidden, display the overlay again.
795
796=back
797
798=item $popup = $term->popup ($event)
799
800Creates a new C<urxvt::popup> object that implements a popup menu. The
801C<$event> I<must> be the event causing the menu to pop up (a button event,
802currently).
423 803
424=cut 804=cut
425 805
426sub urxvt::term::scr_overlay { 806sub popup {
427 my ($self, $x, $y, $text) = @_; 807 my ($self, $event) = @_;
428 808
429 my @lines = split /\n/, $text; 809 $self->grab ($event->{time}, 1)
810 or return;
430 811
431 my $w = 0; 812 my $popup = bless {
432 for (map $self->strwidth ($_), @lines) { 813 term => $self,
433 $w = $_ if $w < $_; 814 event => $event,
434 } 815 }, urxvt::popup::;
435 816
436 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 817 Scalar::Util::weaken $popup->{term};
437 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
438}
439 818
440=item $term->scr_overlay_new ($x, $y, $width, $height) 819 $self->{_destroy}{$popup} = urxvt::destroy_hook { $popup->{popup}->destroy };
820 Scalar::Util::weaken $self->{_destroy}{$popup};
441 821
442Create a new (empty) overlay at the given position with the given 822 $popup
443width/height. A border will be put around the box. If either C<$x> or 823}
444C<$y> is negative, then this is counted from the right/bottom side,
445respectively.
446 824
447=item $term->scr_overlay_off
448
449Switch the overlay off again.
450
451=item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)
452
453Put a single character (specified numerically) at the given overlay
454position.
455
456=item $term->scr_overlay_set ($x, $y, $text)
457
458Write a string at the given position into the overlay.
459
460=item $cellwidth = $term->strwidth $string 825=item $cellwidth = $term->strwidth ($string)
461 826
462Returns the number of screen-cells this string would need. Correctly 827Returns the number of screen-cells this string would need. Correctly
463accounts for wide and combining characters. 828accounts for wide and combining characters.
464 829
465=item $octets = $term->locale_encode $string 830=item $octets = $term->locale_encode ($string)
466 831
467Convert the given text string into the corresponding locale encoding. 832Convert the given text string into the corresponding locale encoding.
468 833
469=item $string = $term->locale_decode $octets 834=item $string = $term->locale_decode ($octets)
470 835
471Convert the given locale-encoded octets into a perl string. 836Convert the given locale-encoded octets into a perl string.
837
838=item $term->scr_add_lines ($string)
839
840Write the given text string to the screen, as if output by the application
841running inside the terminal. It may not contain command sequences (escape
842codes), but is free to use line feeds, carriage returns and tabs. The
843string is a normal text string, not in locale-dependent encoding.
844
845Normally its not a good idea to use this function, as programs might be
846confused by changes in cursor position or scrolling. Its useful inside a
847C<on_add_lines> hook, though.
848
849=item $term->cmd_parse ($octets)
850
851Similar to C<scr_add_lines>, but the argument must be in the
852locale-specific encoding of the terminal and can contain command sequences
853(escape codes) that will be interpreted.
472 854
473=item $term->tt_write ($octets) 855=item $term->tt_write ($octets)
474 856
475Write the octets given in C<$data> to the tty (i.e. as program input). To 857Write the octets given in C<$data> to the tty (i.e. as program input). To
476pass characters instead of octets, you should convert your strings first 858pass characters instead of octets, you should convert your strings first
477to the locale-specific encoding using C<< $term->locale_encode >>. 859to the locale-specific encoding using C<< $term->locale_encode >>.
478 860
861=item $windowid = $term->parent
862
863Return the window id of the toplevel window.
864
865=item $windowid = $term->vt
866
867Return the window id of the terminal window.
868
869=item $window_width = $term->width
870
871=item $window_height = $term->height
872
873=item $font_width = $term->fwidth
874
875=item $font_height = $term->fheight
876
877=item $font_ascent = $term->fbase
878
479=item $nrow = $term->nrow 879=item $terminal_rows = $term->nrow
480 880
481=item $ncol = $term->ncol 881=item $terminal_columns = $term->ncol
482 882
483Return the number of rows/columns of the terminal window (i.e. as 883=item $has_focus = $term->focus
484specified by C<-geometry>, excluding any scrollback).
485 884
486=item $nsaved = $term->nsaved 885=item $is_mapped = $term->mapped
487 886
488Returns the number of lines in the scrollback buffer. 887=item $max_scrollback = $term->saveLines
888
889=item $nrow_plus_saveLines = $term->total_rows
890
891=item $lines_in_scrollback = $term->nsaved
892
893Return various integers describing terminal characteristics.
894
895=item $modifiermask = $term->ModLevel3Mask
896
897=item $modifiermask = $term->ModMetaMask
898
899=item $modifiermask = $term->ModNumLockMask
900
901Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
902AltGr), the meta key (often Alt) and the num lock key, if applicable.
489 903
490=item $view_start = $term->view_start ([$newvalue]) 904=item $view_start = $term->view_start ([$newvalue])
491 905
492Returns the negative row number of the topmost line. Minimum value is 906Returns the negative row number of the topmost line. Minimum value is
493C<0>, which displays the normal terminal contents. Larger values scroll 907C<0>, which displays the normal terminal contents. Larger values scroll
504=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) 918=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
505 919
506Returns the text of the entire row with number C<$row_number>. Row C<0> 920Returns the text of the entire row with number C<$row_number>. Row C<0>
507is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost 921is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost
508terminal line. The scrollback buffer starts at line C<-1> and extends to 922terminal line. The scrollback buffer starts at line C<-1> and extends to
509line C<< -$term->nsaved >>. 923line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line
924is requested.
510 925
511If C<$new_text> is specified, it will replace characters in the current 926If C<$new_text> is specified, it will replace characters in the current
512line, starting at column C<$start_col> (default C<0>), which is useful 927line, starting at column C<$start_col> (default C<0>), which is useful
513to replace only parts of a line. The font index in the rendition will 928to replace only parts of a line. The font index in the rendition will
514automatically be updated. 929automatically be updated.
536 951
537See the section on RENDITION, above. 952See the section on RENDITION, above.
538 953
539=item $length = $term->ROW_l ($row_number[, $new_length]) 954=item $length = $term->ROW_l ($row_number[, $new_length])
540 955
541Returns the number of screen cells that are in use ("the line length"). If 956Returns the number of screen cells that are in use ("the line
542it is C<-1>, then the line is part of a multiple-row logical "line", which 957length"). Unlike the urxvt core, this returns C<< $term->ncol >> if the
543means all characters are in use and it is continued on the next row. 958line is joined with the following one.
544 959
960=item $bool = $term->is_longer ($row_number)
961
962Returns true if the row is part of a multiple-row logical "line" (i.e.
963joined with the following row), which means all characters are in use
964and it is continued on the next row (and possibly a continuation of the
965previous row(s)).
966
967=item $line = $term->line ($row_number)
968
969Create and return a new C<urxvt::line> object that stores information
970about the logical line that row C<$row_number> is part of. It supports the
971following methods:
972
973=over 4
974
975=item $text = $line->t ([$new_text])
976
977Returns or replaces the full text of the line, similar to C<ROW_t>
978
979=item $rend = $line->r ([$new_rend])
980
981Returns or replaces the full rendition array of the line, similar to C<ROW_r>
982
983=item $length = $line->l
984
985Returns the length of the line in cells, similar to C<ROW_l>.
986
987=item $rownum = $line->beg
988
989=item $rownum = $line->end
990
991Return the row number of the first/last row of the line, respectively.
992
993=item $offset = $line->offset_of ($row, $col)
994
995Returns the character offset of the given row|col pair within the logical
996line.
997
998=item ($row, $col) = $line->coord_of ($offset)
999
1000Translates a string offset into terminal coordinates again.
1001
1002=back
1003
1004=cut
1005
1006sub line {
1007 my ($self, $row) = @_;
1008
1009 my $maxrow = $self->nrow - 1;
1010
1011 my ($beg, $end) = ($row, $row);
1012
1013 --$beg while $self->ROW_is_longer ($beg - 1);
1014 ++$end while $self->ROW_is_longer ($end) && $end < $maxrow;
1015
1016 bless {
1017 term => $self,
1018 beg => $beg,
1019 end => $end,
1020 ncol => $self->ncol,
1021 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
1022 }, urxvt::line::
1023}
1024
1025sub urxvt::line::t {
1026 my ($self) = @_;
1027
1028 if (@_ > 1)
1029 {
1030 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1031 for $self->{beg} .. $self->{end};
1032 }
1033
1034 defined wantarray &&
1035 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
1036 0, $self->{len}
1037}
1038
1039sub urxvt::line::r {
1040 my ($self) = @_;
1041
1042 if (@_ > 1)
1043 {
1044 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1045 for $self->{beg} .. $self->{end};
1046 }
1047
1048 if (defined wantarray) {
1049 my $rend = [
1050 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
1051 ];
1052 $#$rend = $self->{len} - 1;
1053 return $rend;
1054 }
1055
1056 ()
1057}
1058
1059sub urxvt::line::beg { $_[0]{beg} }
1060sub urxvt::line::end { $_[0]{end} }
1061sub urxvt::line::l { $_[0]{len} }
1062
1063sub urxvt::line::offset_of {
1064 my ($self, $row, $col) = @_;
1065
1066 ($row - $self->{beg}) * $self->{ncol} + $col
1067}
1068
1069sub urxvt::line::coord_of {
1070 my ($self, $offset) = @_;
1071
1072 use integer;
1073
1074 (
1075 $offset / $self->{ncol} + $self->{beg},
1076 $offset % $self->{ncol}
1077 )
1078}
1079
1080=item ($row, $col) = $line->coord_of ($offset)
545=item $text = $term->special_encode $string 1081=item $text = $term->special_encode $string
546 1082
547Converts a perl string into the special encoding used by rxvt-unicode, 1083Converts a perl string into the special encoding used by rxvt-unicode,
548where one character corresponds to one screen cell. See 1084where one character corresponds to one screen cell. See
549C<< $term->ROW_t >> for details. 1085C<< $term->ROW_t >> for details.
553Converts rxvt-unicodes text reprsentation into a perl string. See 1089Converts rxvt-unicodes text reprsentation into a perl string. See
554C<< $term->ROW_t >> for details. 1090C<< $term->ROW_t >> for details.
555 1091
556=back 1092=back
557 1093
1094=cut
1095
1096package urxvt::popup;
1097
1098=head2 The C<urxvt::popup> Class
1099
1100=over 4
1101
1102=cut
1103
1104sub add_item {
1105 my ($self, $item) = @_;
1106
1107 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1108 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1109 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1110
1111 $item->{render} ||= sub { $_[0]{text} };
1112
1113 push @{ $self->{item} }, $item;
1114}
1115
1116sub add_separator {
1117 my ($self, $sep) = @_;
1118
1119 $sep ||= "═";
1120
1121 $self->add_item ({
1122 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1123 text => "",
1124 render => sub { $sep x $urxvt::TERM->ncol },
1125 activate => sub { },
1126 });
1127}
1128
1129sub add_title {
1130 my ($self, $title) = @_;
1131
1132 $self->add_item ({
1133 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1134 text => $title,
1135 activate => sub { },
1136 });
1137}
1138
1139sub add_button {
1140 my ($self, $text, $cb) = @_;
1141
1142 $self->add_item ({ type => "button", text => "[ $text ]", activate => $cb});
1143}
1144
1145sub add_toggle {
1146 my ($self, $text, $cb, $value) = @_;
1147
1148 my $item; $item = {
1149 type => "button",
1150 text => " $text",
1151 value => $value,
1152 render => sub { ($item->{value} ? "* " : " ") . $text },
1153 activate => sub { $cb->($item->{value} = !$item->{value}); },
1154 };
1155
1156 $self->add_item ($item);
1157}
1158
1159sub show {
1160 my ($self) = @_;
1161
1162 local $urxvt::popup::self = $self;
1163
1164 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1165 "--transient-for" => $self->{term}->parent,
1166 "-pe" => "urxvt-popup")
1167 or die "unable to create popup window\n";
1168}
1169
1170sub DESTROY {
1171 my ($self) = @_;
1172
1173 $self->{term}->ungrab;
1174}
1175
558=head2 The C<urxvt::timer> Class 1176=head2 The C<urxvt::timer> Class
559 1177
560This class implements timer watchers/events. Time is represented as a 1178This class implements timer watchers/events. Time is represented as a
561fractional number of seconds since the epoch. Example: 1179fractional number of seconds since the epoch. Example:
562 1180
563 # create a digital clock display in upper right corner 1181 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
564 $term->{timer} = urxvt::timer 1182 $term->{timer} = urxvt::timer
565 ->new 1183 ->new
566 ->start (urxvt::NOW) 1184 ->interval (1)
567 ->cb (sub { 1185 ->cb (sub {
568 my ($timer) = @_;
569 my $time = $timer->at;
570 $timer->start ($time + 1);
571 $self->scr_overlay (-1, 0, 1186 $term->{overlay}->set (0, 0,
572 POSIX::strftime "%H:%M:%S", localtime $time); 1187 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
573 }); 1188 });
574 1189
575=over 4 1190=over 4
576 1191
577=item $timer = new urxvt::timer 1192=item $timer = new urxvt::timer
578 1193
579Create a new timer object in stopped state. 1194Create a new timer object in started state. It is scheduled to fire
1195immediately.
580 1196
581=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 1197=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
582 1198
583Set the callback to be called when the timer triggers. 1199Set the callback to be called when the timer triggers.
584 1200
587Return the time this watcher will fire next. 1203Return the time this watcher will fire next.
588 1204
589=item $timer = $timer->set ($tstamp) 1205=item $timer = $timer->set ($tstamp)
590 1206
591Set the time the event is generated to $tstamp. 1207Set the time the event is generated to $tstamp.
1208
1209=item $timer = $timer->interval ($interval)
1210
1211Normally (and when C<$interval> is C<0>), the timer will automatically
1212stop after it has fired once. If C<$interval> is non-zero, then the timer
1213is automatically rescheduled at the given intervals.
592 1214
593=item $timer = $timer->start 1215=item $timer = $timer->start
594 1216
595Start the timer. 1217Start the timer.
596 1218
659This variable controls the verbosity level of the perl extension. Higher 1281This variable controls the verbosity level of the perl extension. Higher
660numbers indicate more verbose output. 1282numbers indicate more verbose output.
661 1283
662=over 4 1284=over 4
663 1285
664=item 0 - only fatal messages 1286=item =0 - only fatal messages
665 1287
666=item 3 - script loading and management 1288=item =3 - script loading and management
667 1289
668=item 10 - all events received 1290=item =10 - all events received
669 1291
670=back 1292=back
671 1293
672=head1 AUTHOR 1294=head1 AUTHOR
673 1295

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines