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.10 by root, Mon Jan 2 20:47:52 2006 UTC vs.
Revision 1.55 by root, Sun Jan 8 05:50:27 2006 UTC

1=encoding utf8
2
1=head1 NAME 3=head1 NAME
2 4
3rxvtperl - rxvt-unicode's embedded perl interpreter 5@@RXVT_NAME@@perl - rxvt-unicode's embedded perl interpreter
4 6
5=head1 SYNOPSIS 7=head1 SYNOPSIS
6 8
7 # create a file grab_test in $HOME: 9 # create a file grab_test in $HOME:
8 10
15 17
16 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test 18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
17 19
18=head1 DESCRIPTION 20=head1 DESCRIPTION
19 21
20Everytime a terminal object gets created, scripts specified via the 22Everytime a terminal object gets created, extension scripts specified via
21C<perl> resource are loaded and associated with it. 23the C<perl> resource are loaded and associated with it.
22 24
23Scripts are compiled in a 'use strict' and 'use utf8' environment, and 25Scripts are compiled in a 'use strict' and 'use utf8' environment, and
24thus must be encoded as UTF-8. 26thus must be encoded as UTF-8.
25 27
26Each 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
27scripts will be shared (But not enabled) for all terminals. 29scripts will be shared (but not enabled) for all terminals.
30
31=head2 Prepackaged Extensions
32
33This section describes the extensiosn delivered with this version. You can
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35
36You can activate them like this:
37
38 @@RXVT_NAME@@ -pe <extensionname>
39
40=over 4
41
42=item selection (enabled by default)
43
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:
50
51=over 4
52
53=item rot13
54
55Rot-13 the selection when activated. Used via keyboard trigger:
56
57 URxvt.keysym.C-M-r: perl:selection:rot13
58
59=back
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
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
81
82Displays a very simple digital clock in the upper right corner of the
83window. Illustrates overwriting the refresh callbacks to create your own
84overlays or changes.
85
86=back
28 87
29=head2 General API Considerations 88=head2 General API Considerations
30 89
31All objects (such as terminals, time watchers etc.) are typical 90All objects (such as terminals, time watchers etc.) are typical
32reference-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
33like. All members starting with an underscore (such as C<_ptr> or 92like. All members starting with an underscore (such as C<_ptr> or
34C<_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
35modified). 94modified).
36 95
37When 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
38emptied, 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
39the 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
40terminal is destroyed. 99terminal is destroyed.
41 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
42=head2 Hooks 124=head2 Hooks
43 125
44The following subroutines can be declared in loaded scripts, and will be called 126The following subroutines can be declared in extension files, and will be
45whenever 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.
46 135
47All 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
48counts 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,
49and 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.
50 139
53=over 4 142=over 4
54 143
55=item on_init $term 144=item on_init $term
56 145
57Called after a new terminal object has been initialized, but before 146Called after a new terminal object has been initialized, but before
58windows 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.
59 151
60=item on_reset $term 152=item on_reset $term
61 153
62Called 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
63control 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
83requested from the server. The selection text can be queried and changed 175requested from the server. The selection text can be queried and changed
84by calling C<< $term->selection >>. 176by calling C<< $term->selection >>.
85 177
86Returning a true value aborts selection grabbing. It will still be hilighted. 178Returning a true value aborts selection grabbing. It will still be hilighted.
87 179
88=item on_focus_in $term 180=item on_sel_extend $term
89 181
90Called whenever the window gets the keyboard focus, before urxvt does 182Called whenever the user tries to extend the selection (e.g. with a double
91focus in processing. 183click) and is either supposed to return false (normal operation), or
92 184should extend the selection itelf and return true to suppress the built-in
93=item on_focus_out $term
94
95Called wheneever the window loses keyboard focus, before urxvt does focus
96out processing. 185processing.
186
187See the F<selection> example extension.
97 188
98=item on_view_change $term, $offset 189=item on_view_change $term, $offset
99 190
100Called whenever the view offset changes, i..e the user or program 191Called whenever the view offset changes, i..e the user or program
101scrolls. Offset C<0> means display the normal terminal, positive values 192scrolls. Offset C<0> means display the normal terminal, positive values
112number of lines that will be in the scrollback buffer. 203number of lines that will be in the scrollback buffer.
113 204
114=item on_tty_activity $term *NYI* 205=item on_tty_activity $term *NYI*
115 206
116Called 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.
117 243
118=item on_refresh_begin $term 244=item on_refresh_begin $term
119 245
120Called just before the screen gets redrawn. Can be used for overlay 246Called just before the screen gets redrawn. Can be used for overlay
121or similar effects by modify terminal contents in refresh_begin, and 247or similar effects by modify terminal contents in refresh_begin, and
124 250
125=item on_refresh_end $term 251=item on_refresh_end $term
126 252
127Called just after the screen gets redrawn. See C<on_refresh_begin>. 253Called just after the screen gets redrawn. See C<on_refresh_begin>.
128 254
255=item on_keyboard_command $term, $string
256
257Called whenever the user presses a key combination that has a
258C<perl:string> action bound to it (see description of the B<keysym>
259resource in the @@RXVT_NAME@@(1) manpage).
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
129=back 297=back
130 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
131=head2 Functions in the C<urxvt> Package 310=head2 Functions in the C<urxvt> Package
132 311
133=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.
134 321
135=item urxvt::fatal $errormessage 322=item urxvt::fatal $errormessage
136 323
137Fatally aborts execution with the given error message. Avoid at all 324Fatally aborts execution with the given error message. Avoid at all
138costs! The only time this is acceptable is when the terminal process 325costs! The only time this is acceptable is when the terminal process
149 336
150=item $time = urxvt::NOW 337=item $time = urxvt::NOW
151 338
152Returns the "current time" (as per the event loop). 339Returns the "current time" (as per the event loop).
153 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
350
351=head2 RENDITION
352
353Rendition bitsets contain information about colour, font, font styles and
354similar information for each screen cell.
355
356The following "macros" deal with changes in rendition sets. You should
357never just create a bitset, you should always modify an existing one,
358as they contain important information required for correct operation of
359rxvt-unicode.
360
361=over 4
362
363=item $rend = urxvt::DEFAULT_RSTYLE
364
365Returns the default rendition, as used when the terminal is starting up or
366being reset. Useful as a base to start when creating renditions.
367
368=item $rend = urxvt::OVERLAY_RSTYLE
369
370Return the rendition mask used for overlays by default.
371
372=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
373
374Return the bit that enabled bold, italic, blink, reverse-video and
375underline, respectively. To enable such a style, just logically OR it into
376the bitset.
377
378=item $foreground = urxvt::GET_BASEFG $rend
379
380=item $background = urxvt::GET_BASEBG $rend
381
382Return the foreground/background colour index, respectively.
383
384=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
385
386=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
387
388Replace the foreground/background colour in the rendition mask with the
389specified one.
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
401=back
402
154=cut 403=cut
155 404
156package urxvt; 405package urxvt;
157 406
407use utf8;
158use strict; 408use strict;
409use Scalar::Util ();
410use List::Util ();
159 411
160our $term; 412our $VERSION = 1;
413our $TERM;
161our @HOOKNAME; 414our @HOOKNAME;
415our %OPTION;
162our $LIBDIR; 416our $LIBDIR;
163 417
164BEGIN { 418BEGIN {
165 urxvt->bootstrap; 419 urxvt->bootstrap;
166 420
190 my $name = $HOOKNAME[$htype]; 444 my $name = $HOOKNAME[$htype];
191 445
192 my $ref = $pkg->can ("on_" . lc $name) 446 my $ref = $pkg->can ("on_" . lc $name)
193 or next; 447 or next;
194 448
195 $term->{_hook}[$htype]{$ref*1} = $ref; 449 $TERM->{_hook}[$htype]{$pkg} = $ref;
196 $hook_count[$htype]++ 450 $hook_count[$htype]++
197 or set_should_invoke $htype, 1; 451 or set_should_invoke $htype, 1;
198 } 452 }
199} 453}
200 454
201my $script_pkg = "script0000"; 455my $extension_pkg = "extension0000";
202my %script_pkg; 456my %extension_pkg;
203 457
204# load a single script into its own package, once only 458# load a single script into its own package, once only
205sub script_package($) { 459sub extension_package($) {
206 my ($path) = @_; 460 my ($path) = @_;
207 461
208 $script_pkg{$path} ||= do { 462 $extension_pkg{$path} ||= do {
209 my $pkg = "urxvt::" . ($script_pkg++); 463 my $pkg = "urxvt::" . ($extension_pkg++);
210 464
211 verbose 3, "loading script '$path' into package '$pkg'"; 465 verbose 3, "loading extension '$path' into package '$pkg'";
212 466
213 open my $fh, "<:raw", $path 467 open my $fh, "<:raw", $path
214 or die "$path: $!"; 468 or die "$path: $!";
215 469
216 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"
217 . "#line 1 \"$path\"\n{\n" 472 . "#line 1 \"$path\"\n{\n"
218 . (do { local $/; <$fh> }) 473 . (do { local $/; <$fh> })
219 . "\n};\n1"; 474 . "\n};\n1";
220 475
221 eval $source or die "$path: $@"; 476 eval $source or die "$path: $@";
222 477
223 $pkg 478 $pkg
224 } 479 }
225} 480}
226 481
482our $retval; # return value for urxvt
483
227# called by the rxvt core 484# called by the rxvt core
228sub invoke { 485sub invoke {
229 local $term = shift; 486 local $TERM = shift;
230 my $htype = shift; 487 my $htype = shift;
231 488
232 if ($htype == 0) { # INIT 489 if ($htype == 0) { # INIT
233 my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl"); 490 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
491
492 my %want_ext;
234 493
235 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) {
236 my @files = grep -f $_, map "$_/$ext", @dirs; 505 my @files = grep -f $_, map "$_/$ext", @dirs;
237 506
238 if (@files) { 507 if (@files) {
239 register_package script_package $files[0]; 508 register_package extension_package $files[0];
240 } else { 509 } else {
241 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";
242 } 511 }
243 } 512 }
244 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
245 } elsif ($htype == 1) { # DESTROY 541 if ($htype == 1) { # DESTROY
542 # remove hooks if unused
246 if (my $hook = $term->{_hook}) { 543 if (my $hook = $TERM->{_hook}) {
247 for my $htype (0..$#$hook) { 544 for my $htype (0..$#$hook) {
248 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 545 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
249 or set_should_invoke $htype, 0; 546 or set_should_invoke $htype, 0;
250 } 547 }
251 } 548 }
549
550 # clear package objects
551 %$_ = () for values %{ $TERM->{_pkg} };
552
553 # clear package
554 %$TERM = ();
252 } 555 }
253 556
254 my $cb = $term->{_hook}[$htype] 557 $retval
255 or return; 558}
256 559
257 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")" 560# urxvt::term::proxy
258 if $verbosity >= 10;
259 561
260 while (my ($k, $v) = each %$cb) { 562sub urxvt::term::proxy::AUTOLOAD {
261 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");
262 } 644 }
263
264 0
265} 645}
266 646
267=back 647package urxvt::term;
268 648
269=head2 The C<urxvt::term> Class 649=head2 The C<urxvt::term> Class
270 650
271=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
272 672
273=item $value = $term->resource ($name[, $newval]) 673=item $value = $term->resource ($name[, $newval])
274 674
275Returns the current resource value associated with a given name and 675Returns the current resource value associated with a given name and
276optionally 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>
286 686
287Please note that resource strings will currently only be freed when the 687Please note that resource strings will currently only be freed when the
288terminal is destroyed, so changing options frequently will eat memory. 688terminal is destroyed, so changing options frequently will eat memory.
289 689
290Here 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
291are 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>
292list: 692to see the actual list:
293 693
294 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 694 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
295 borderLess color cursorBlink cursorUnderline cutchars delete_key 695 borderLess color cursorBlink cursorUnderline cutchars delete_key
296 display_name embed ext_bwidth fade font geometry hold iconName 696 display_name embed ext_bwidth fade font geometry hold iconName
297 imFont imLocale inputMethod insecure int_bwidth intensityStyles 697 imFont imLocale inputMethod insecure int_bwidth intensityStyles
298 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 698 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
299 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext 699 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
300 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 700 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
301 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 701 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
302 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 702 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
303 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 703 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
304 shade term_name title transparent transparent_all tripleclickwords 704 shade term_name title transparent transparent_all tripleclickwords
305 utmpInhibit visualBell 705 utmpInhibit visualBell
306 706
307=cut 707=cut
308 708
309sub urxvt::term::resource($$;$) { 709sub resource($$;$) {
310 my ($self, $name) = (shift, shift); 710 my ($self, $name) = (shift, shift);
311 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 711 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
312 goto &urxvt::term::_resource; 712 &urxvt::term::_resource
313} 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).
314 724
315=item ($row, $col) = $term->selection_mark ([$row, $col]) 725=item ($row, $col) = $term->selection_mark ([$row, $col])
316 726
317=item ($row, $col) = $term->selection_beg ([$row, $col]) 727=item ($row, $col) = $term->selection_beg ([$row, $col])
318 728
328 738
329=item $oldtext = $term->selection ([$newtext]) 739=item $oldtext = $term->selection ([$newtext])
330 740
331Return the current selection text and optionally replace it by C<$newtext>. 741Return the current selection text and optionally replace it by C<$newtext>.
332 742
333=item $term->scr_overlay ($x, $y, $text) 743#=item $term->overlay ($x, $y, $text)
334 744#
335Create 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).
336 803
337=cut 804=cut
338 805
339sub urxvt::term::scr_overlay { 806sub popup {
340 my ($self, $x, $y, $text) = @_; 807 my ($self, $event) = @_;
341 808
342 my @lines = split /\n/, $text; 809 $self->grab ($event->{time}, 1)
810 or return;
343 811
344 my $w = 0; 812 my $popup = bless {
345 for (map $self->strwidth ($_), @lines) { 813 term => $self,
346 $w = $_ if $w < $_; 814 event => $event,
347 } 815 }, urxvt::popup::;
348 816
349 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 817 Scalar::Util::weaken $popup->{term};
350 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
351}
352 818
353=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};
354 821
355Create a new (empty) overlay at the given position with the given 822 $popup
356width/height. A border will be put around the box. If either C<$x> or 823}
357C<$y> is negative, then this is counted from the right/bottom side,
358respectively.
359 824
360=item $term->scr_overlay_off
361
362Switch the overlay off again.
363
364=item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE)
365
366Put a single character (specified numerically) at the given overlay
367position.
368
369=item $term->scr_overlay_set ($x, $y, $text)
370
371Write a string at the given position into the overlay.
372
373=item $cellwidth = $term->strwidth $string 825=item $cellwidth = $term->strwidth ($string)
374 826
375Returns the number of screen-cells this string would need. Correctly 827Returns the number of screen-cells this string would need. Correctly
376accounts for wide and combining characters. 828accounts for wide and combining characters.
377 829
378=item $octets = $term->locale_encode $string 830=item $octets = $term->locale_encode ($string)
379 831
380Convert the given text string into the corresponding locale encoding. 832Convert the given text string into the corresponding locale encoding.
381 833
382=item $string = $term->locale_decode $octets 834=item $string = $term->locale_decode ($octets)
383 835
384Convert the given locale-encoded octets into a perl string. 836Convert the given locale-encoded octets into a perl string.
385 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.
854
386=item $term->tt_write ($octets) 855=item $term->tt_write ($octets)
387 856
388Write 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
389pass characters instead of octets, you should convetr you strings first to 858pass characters instead of octets, you should convert your strings first
390the locale-specific encoding using C<< $term->locale_encode >>. 859to the locale-specific encoding using C<< $term->locale_encode >>.
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
879=item $terminal_rows = $term->nrow
880
881=item $terminal_columns = $term->ncol
882
883=item $has_focus = $term->focus
884
885=item $is_mapped = $term->mapped
886
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.
903
904=item $view_start = $term->view_start ([$newvalue])
905
906Returns the negative row number of the topmost line. Minimum value is
907C<0>, which displays the normal terminal contents. Larger values scroll
908this many lines into the scrollback buffer.
909
910=item $term->want_refresh
911
912Requests a screen refresh. At the next opportunity, rxvt-unicode will
913compare the on-screen display with its stored representation. If they
914differ, it redraws the differences.
915
916Used after changing terminal contents to display them.
917
918=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
919
920Returns the text of the entire row with number C<$row_number>. Row C<0>
921is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost
922terminal line. The scrollback buffer starts at line C<-1> and extends to
923line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line
924is requested.
925
926If C<$new_text> is specified, it will replace characters in the current
927line, starting at column C<$start_col> (default C<0>), which is useful
928to replace only parts of a line. The font index in the rendition will
929automatically be updated.
930
931C<$text> is in a special encoding: tabs and wide characters that use more
932than one cell when displayed are padded with urxvt::NOCHAR characters
933(C<chr 65535>). Characters with combining characters and other characters
934that do not fit into the normal tetx encoding will be replaced with
935characters in the private use area.
936
937You have to obey this encoding when changing text. The advantage is
938that C<substr> and similar functions work on screen cells and not on
939characters.
940
941The methods C<< $term->special_encode >> and C<< $term->special_decode >>
942can be used to convert normal strings into this encoding and vice versa.
943
944=item $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
945
946Like C<< $term->ROW_t >>, but returns an arrayref with rendition
947bitsets. Rendition bitsets contain information about colour, font, font
948styles and similar information. See also C<< $term->ROW_t >>.
949
950When setting rendition, the font mask will be ignored.
951
952See the section on RENDITION, above.
953
954=item $length = $term->ROW_l ($row_number[, $new_length])
955
956Returns the number of screen cells that are in use ("the line
957length"). Unlike the urxvt core, this returns C<< $term->ncol >> if the
958line is joined with the following one.
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.
391 1001
392=back 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)
1081=item $text = $term->special_encode $string
1082
1083Converts a perl string into the special encoding used by rxvt-unicode,
1084where one character corresponds to one screen cell. See
1085C<< $term->ROW_t >> for details.
1086
1087=item $string = $term->special_decode $text
1088
1089Converts rxvt-unicodes text reprsentation into a perl string. See
1090C<< $term->ROW_t >> for details.
1091
1092=back
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}
393 1175
394=head2 The C<urxvt::timer> Class 1176=head2 The C<urxvt::timer> Class
395 1177
396This class implements timer watchers/events. Time is represented as a 1178This class implements timer watchers/events. Time is represented as a
397fractional number of seconds since the epoch. Example: 1179fractional number of seconds since the epoch. Example:
398 1180
399 # create a digital clock display in upper right corner 1181 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
400 $term->{timer} = urxvt::timer 1182 $term->{timer} = urxvt::timer
401 ->new 1183 ->new
402 ->start (urxvt::NOW) 1184 ->interval (1)
403 ->cb (sub { 1185 ->cb (sub {
404 my ($timer) = @_;
405 my $time = $timer->at;
406 $timer->start ($time + 1);
407 $self->scr_overlay (-1, 0, 1186 $term->{overlay}->set (0, 0,
408 POSIX::strftime "%H:%M:%S", localtime $time); 1187 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
409 }); 1188 });
410 1189
411=over 4 1190=over 4
412 1191
413=item $timer = new urxvt::timer 1192=item $timer = new urxvt::timer
414 1193
415Create a new timer object in stopped state. 1194Create a new timer object in started state. It is scheduled to fire
1195immediately.
416 1196
417=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 1197=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
418 1198
419Set the callback to be called when the timer triggers. 1199Set the callback to be called when the timer triggers.
420 1200
423Return the time this watcher will fire next. 1203Return the time this watcher will fire next.
424 1204
425=item $timer = $timer->set ($tstamp) 1205=item $timer = $timer->set ($tstamp)
426 1206
427Set 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.
428 1214
429=item $timer = $timer->start 1215=item $timer = $timer->start
430 1216
431Start the timer. 1217Start the timer.
432 1218
495This variable controls the verbosity level of the perl extension. Higher 1281This variable controls the verbosity level of the perl extension. Higher
496numbers indicate more verbose output. 1282numbers indicate more verbose output.
497 1283
498=over 4 1284=over 4
499 1285
500=item 0 - only fatal messages 1286=item =0 - only fatal messages
501 1287
502=item 3 - script loading and management 1288=item =3 - script loading and management
503 1289
504=item 10 - all events received 1290=item =10 - all events received
505 1291
506=back 1292=back
507 1293
508=head1 AUTHOR 1294=head1 AUTHOR
509 1295

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines