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.88 by root, Thu Jan 12 12:05:28 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=head1 PREPACKAGED EXTENSIONS
32
33This section describes the extensions delivered with this release. 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
44(More) intelligent selection. This extension tries to be more intelligent
45when the user extends selections (double-click and further clicks). Right
46now, it tries to select words, urls and complete shell-quoted
47arguments, which is very convenient, too, if your F<ls> supports
48C<--quoting-style=shell>.
49
50A double-click usually selects the word under the cursor, further clicks
51will enlarge the selection.
52
53The selection works by trying to match a number of regexes and displaying
54them in increasing order of length. You can add your own regexes by
55specifying resources of the form:
56
57 URxvt.selection.pattern-0: perl-regex
58 URxvt.selection.pattern-1: perl-regex
59 ...
60
61The index number (0, 1...) must not have any holes, and each regex must
62contain at least one pair of capturing parentheses, which will be used for
63the match. For example, the followign adds a regex that matches everything
64between two vertical bars:
65
66 URxvt.selection.pattern-0: \\|([^|]+)\\|
67
68You can look at the source of the selection extension to see more
69interesting uses, such as parsing a line from beginning to end.
70
71This extension also offers the following bindable keyboard command:
72
73=over 4
74
75=item rot13
76
77Rot-13 the selection when activated. Used via keyboard trigger:
78
79 URxvt.keysym.C-M-r: perl:selection:rot13
80
81=back
82
83=item option-popup (enabled by default)
84
85Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
86runtime.
87
88=item selection-popup (enabled by default)
89
90Binds a popup menu to Ctrl-Button3 that lets you convert the selection
91text into various other formats/action (such as uri unescaping, perl
92evalution, web-browser starting etc.), depending on content.
93
94=item searchable-scrollback<hotkey> (enabled by default)
95
96Adds regex search functionality to the scrollback buffer, triggered
97by a hotkey (default: C<M-s>). While in search mode, normal terminal
98input/output is suspended and a regex is displayed at the bottom of the
99screen.
100
101Inputting characters appends them to the regex and continues incremental
102search. C<BackSpace> removes a character from the regex, C<Up> and C<Down>
103search upwards/downwards in the scrollback buffer, C<End> jumps to the
104bottom. C<Escape> leaves search mode and returns to the point where search
105was started, while C<Enter> or C<Return> stay at the current position and
106additionally stores the first match in the current line into the primary
107selection.
108
109=item selection-autotransform
110
111This selection allows you to do automatic transforms on a selection
112whenever a selection is made.
113
114It works by specifying perl snippets (most useful is a single C<s///>
115operator) that modify C<$_> as resources:
116
117 URxvt.selection-autotransform.0: transform
118 URxvt.selection-autotransform.1: transform
119 ...
120
121For example, the following will transform selections of the form
122C<word:number> into C<vi +$number $word>:
123
124 URxvt.selection-autotransform.0: s/^(S+):(d+):?$/vi +$2 $1\\x0d/
125
126And this example matches the same,but replaces it with vi-commands you can
127paste directory into your (vi :) editor:
128
129 URxvt.selection-autotransform.0: s/^(S+):(d+):?$/\\x1b:e $1\\x0d:$2\\x0d/
130
131=item mark-urls
132
133Uses per-line display filtering (C<on_line_update>) to underline urls and
134make them clickable. When middle-clicked, the program specified in the
135resource C<urlLauncher> (default C<x-www-browser>) will be started with
136the URL as first argument.
137
138=item block-graphics-to-ascii
139
140A not very useful example of filtering all text output to the terminal,
141by replacing all line-drawing characters (U+2500 .. U+259F) by a
142similar-looking ascii character.
143
144=item digital-clock
145
146Displays a digital clock using the built-in overlay.
147
148=item example-refresh-hooks
149
150Displays a very simple digital clock in the upper right corner of the
151window. Illustrates overwriting the refresh callbacks to create your own
152overlays or changes.
153
154=back
155
156=head1 API DOCUMENTATION
28 157
29=head2 General API Considerations 158=head2 General API Considerations
30 159
31All objects (such as terminals, time watchers etc.) are typical 160All objects (such as terminals, time watchers etc.) are typical
32reference-to-hash objects. The hash can be used to store anything you 161reference-to-hash objects. The hash can be used to store anything you
33like. All members starting with an underscore (such as C<_ptr> or 162like. All members starting with an underscore (such as C<_ptr> or
34C<_hook>) are reserved for internal uses and must not be accessed or 163C<_hook>) are reserved for internal uses and B<MUST NOT> be accessed or
35modified). 164modified).
36 165
37When objects are destroyed on the C++ side, the perl object hashes are 166When 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 167emptied, 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 168the like inside the terminal object so they get destroyed as soon as the
40terminal is destroyed. 169terminal is destroyed.
41 170
171Argument names also often indicate the type of a parameter. Here are some
172hints on what they mean:
173
174=over 4
175
176=item $text
177
178Rxvt-unicodes special way of encoding text, where one "unicode" character
179always represents one screen cell. See L<ROW_t> for a discussion of this format.
180
181=item $string
182
183A perl text string, with an emphasis on I<text>. It can store all unicode
184characters and is to be distinguished with text encoded in a specific
185encoding (often locale-specific) and binary data.
186
187=item $octets
188
189Either binary data or - more common - a text string encoded in a
190locale-specific way.
191
192=back
193
194=head2 Extension Objects
195
196Very perl extension is a perl class. A separate perl object is created
197for each terminal and each extension and passed as the first parameter to
198hooks. So extensions can use their C<$self> object without having to think
199about other extensions, with the exception of methods and members that
200begin with an underscore character C<_>: these are reserved for internal
201use.
202
203Although it isn't a C<urxvt::term> object, you can call all methods of the
204C<urxvt::term> class on this object.
205
206It has the following methods and data members:
207
208=over 4
209
210=item $urxvt_term = $self->{term}
211
212Returns the C<urxvt::term> object associated with this instance of the
213extension. This member I<must not> be changed in any way.
214
215=item $self->enable ($hook_name => $cb, [$hook_name => $cb..])
216
217Dynamically enable the given hooks (named without the C<on_> prefix) for
218this extension, replacing any previous hook. This is useful when you want
219to overwrite time-critical hooks only temporarily.
220
221=item $self->disable ($hook_name[, $hook_name..])
222
223Dynamically disable the given hooks.
224
225=back
226
42=head2 Hooks 227=head2 Hooks
43 228
44The following subroutines can be declared in loaded scripts, and will be called 229The following subroutines can be declared in extension files, and will be
45whenever the relevant event happens. 230called whenever the relevant event happens.
46 231
232The first argument passed to them is an extension oject as described in
233the in the C<Extension Objects> section.
234
47All of them must return a boolean value. If it is true, then the event 235B<All> of these hooks must return a boolean value. If it is true, then the
48counts as being I<consumed>, and the invocation of other hooks is skipped, 236event counts as being I<consumed>, and the invocation of other hooks is
49and the relevant action might not be carried out by the C++ code. 237skipped, and the relevant action might not be carried out by the C++ code.
50 238
51When in doubt, return a false value (preferably C<()>). 239I<< When in doubt, return a false value (preferably C<()>). >>
52 240
53=over 4 241=over 4
54 242
55=item on_init $term 243=item on_init $term
56 244
57Called after a new terminal object has been initialized, but before 245Called after a new terminal object has been initialized, but before
58windows are created or the command gets run. 246windows are created or the command gets run. Most methods are unsafe to
247call or deliver senseless data, as terminal size and other characteristics
248have not yet been determined. You can safely query and change resources,
249though.
59 250
60=item on_reset $term 251=item on_reset $term
61 252
62Called after the screen is "reset" for any reason, such as resizing or 253Called 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 254control sequences. Here is where you can react on changes to size-related
83requested from the server. The selection text can be queried and changed 274requested from the server. The selection text can be queried and changed
84by calling C<< $term->selection >>. 275by calling C<< $term->selection >>.
85 276
86Returning a true value aborts selection grabbing. It will still be hilighted. 277Returning a true value aborts selection grabbing. It will still be hilighted.
87 278
88=item on_focus_in $term 279=item on_sel_extend $term
89 280
90Called whenever the window gets the keyboard focus, before urxvt does 281Called whenever the user tries to extend the selection (e.g. with a double
91focus in processing. 282click) and is either supposed to return false (normal operation), or
283should extend the selection itelf and return true to suppress the built-in
284processing. This can happen multiple times, as long as the callback
285returns true, it will be called on every further click by the user and is
286supposed to enlarge the selection more and more, if possible.
92 287
93=item on_focus_out $term 288See the F<selection> example extension.
94
95Called wheneever the window loses keyboard focus, before urxvt does focus
96out processing.
97 289
98=item on_view_change $term, $offset 290=item on_view_change $term, $offset
99 291
100Called whenever the view offset changes, i..e the user or program 292Called whenever the view offset changes, i..e the user or program
101scrolls. Offset C<0> means display the normal terminal, positive values 293scrolls. Offset C<0> means display the normal terminal, positive values
109 301
110It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, 302It is called before lines are scrolled out (so rows 0 .. min ($lines - 1,
111$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total 303$nrow - 1) represent the lines to be scrolled out). C<$saved> is the total
112number of lines that will be in the scrollback buffer. 304number of lines that will be in the scrollback buffer.
113 305
114=item on_tty_activity $term *NYI* 306=item on_osc_seq $term, $string
115 307
116Called whenever the program(s) running in the urxvt window send output. 308Called whenever the B<ESC ] 777 ; string ST> command sequence (OSC =
309operating system command) is processed. Cursor position and other state
310information is up-to-date when this happens. For interoperability, the
311string should start with the extension name and a colon, to distinguish
312it from commands for other extensions, and this might be enforced in the
313future.
314
315Be careful not ever to trust (in a security sense) the data you receive,
316as its source can not easily be controleld (e-mail content, messages from
317other users on the same system etc.).
318
319=item on_add_lines $term, $string
320
321Called whenever text is about to be output, with the text as argument. You
322can filter/change and output the text yourself by returning a true value
323and calling C<< $term->scr_add_lines >> yourself. Please note that this
324might be very slow, however, as your hook is called for B<all> text being
325output.
326
327=item on_tt_write $term, $octets
328
329Called whenever some data is written to the tty/pty and can be used to
330suppress or filter tty input.
331
332=item on_line_update $term, $row
333
334Called whenever a line was updated or changed. Can be used to filter
335screen output (e.g. underline urls or other useless stuff). Only lines
336that are being shown will be filtered, and, due to performance reasons,
337not always immediately.
338
339The row number is always the topmost row of the line if the line spans
340multiple rows.
341
342Please note that, if you change the line, then the hook might get called
343later with the already-modified line (e.g. if unrelated parts change), so
344you cannot just toggle rendition bits, but only set them.
117 345
118=item on_refresh_begin $term 346=item on_refresh_begin $term
119 347
120Called just before the screen gets redrawn. Can be used for overlay 348Called just before the screen gets redrawn. Can be used for overlay
121or similar effects by modify terminal contents in refresh_begin, and 349or similar effects by modify terminal contents in refresh_begin, and
124 352
125=item on_refresh_end $term 353=item on_refresh_end $term
126 354
127Called just after the screen gets redrawn. See C<on_refresh_begin>. 355Called just after the screen gets redrawn. See C<on_refresh_begin>.
128 356
357=item on_keyboard_command $term, $string
358
359Called whenever the user presses a key combination that has a
360C<perl:string> action bound to it (see description of the B<keysym>
361resource in the @@RXVT_NAME@@(1) manpage).
362
363=item on_focus_in $term
364
365Called whenever the window gets the keyboard focus, before rxvt-unicode
366does focus in processing.
367
368=item on_focus_out $term
369
370Called wheneever the window loses keyboard focus, before rxvt-unicode does
371focus out processing.
372
373=item on_key_press $term, $event, $keysym, $octets
374
375=item on_key_release $term, $event, $keysym
376
377=item on_button_press $term, $event
378
379=item on_button_release $term, $event
380
381=item on_motion_notify $term, $event
382
383=item on_map_notify $term, $event
384
385=item on_unmap_notify $term, $event
386
387Called whenever the corresponding X event is received for the terminal If
388the hook returns true, then the even will be ignored by rxvt-unicode.
389
390The event is a hash with most values as named by Xlib (see the XEvent
391manpage), with the additional members C<row> and C<col>, which are the row
392and column under the mouse cursor.
393
394C<on_key_press> additionally receives the string rxvt-unicode would
395output, if any, in locale-specific encoding.
396
397subwindow.
398
399=back
400
401=cut
402
403package urxvt;
404
405use utf8;
406use strict;
407use Carp ();
408use Scalar::Util ();
409use List::Util ();
410
411our $VERSION = 1;
412our $TERM;
413our @HOOKNAME;
414our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
415our %OPTION;
416
417our $LIBDIR;
418our $RESNAME;
419our $RESCLASS;
420our $RXVTNAME;
421
422=head2 Variables in the C<urxvt> Package
423
424=over 4
425
426=item $urxvt::LIBDIR
427
428The rxvt-unicode library directory, where, among other things, the perl
429modules and scripts are stored.
430
431=item $urxvt::RESCLASS, $urxvt::RESCLASS
432
433The resource class and name rxvt-unicode uses to look up X resources.
434
435=item $urxvt::RXVTNAME
436
437The basename of the installed binaries, usually C<urxvt>.
438
439=item $urxvt::TERM
440
441The current terminal. This variable stores the current C<urxvt::term>
442object, whenever a callback/hook is executing.
443
129=back 444=back
130 445
131=head2 Functions in the C<urxvt> Package 446=head2 Functions in the C<urxvt> Package
132 447
133=over 4 448=over 4
145that calls this function. 460that calls this function.
146 461
147Using this function has the advantage that its output ends up in the 462Using this function has the advantage that its output ends up in the
148correct place, e.g. on stderr of the connecting urxvtc client. 463correct place, e.g. on stderr of the connecting urxvtc client.
149 464
465Messages have a size limit of 1023 bytes currently.
466
467=item $is_safe = urxvt::safe
468
469Returns true when it is safe to do potentially unsafe things, such as
470evaluating perl code specified by the user. This is true when urxvt was
471started setuid or setgid.
472
150=item $time = urxvt::NOW 473=item $time = urxvt::NOW
151 474
152Returns the "current time" (as per the event loop). 475Returns the "current time" (as per the event loop).
153 476
154=cut 477=item urxvt::CurrentTime
155 478
156package urxvt; 479=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
480Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
481Button4Mask, Button5Mask, AnyModifier
157 482
158use strict; 483Various constants for use in X calls and event processing.
159 484
160our $term; 485=back
161our @HOOKNAME; 486
162our $LIBDIR; 487=head2 RENDITION
488
489Rendition bitsets contain information about colour, font, font styles and
490similar information for each screen cell.
491
492The following "macros" deal with changes in rendition sets. You should
493never just create a bitset, you should always modify an existing one,
494as they contain important information required for correct operation of
495rxvt-unicode.
496
497=over 4
498
499=item $rend = urxvt::DEFAULT_RSTYLE
500
501Returns the default rendition, as used when the terminal is starting up or
502being reset. Useful as a base to start when creating renditions.
503
504=item $rend = urxvt::OVERLAY_RSTYLE
505
506Return the rendition mask used for overlays by default.
507
508=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
509
510Return the bit that enabled bold, italic, blink, reverse-video and
511underline, respectively. To enable such a style, just logically OR it into
512the bitset.
513
514=item $foreground = urxvt::GET_BASEFG $rend
515
516=item $background = urxvt::GET_BASEBG $rend
517
518Return the foreground/background colour index, respectively.
519
520=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
521
522=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
523
524Replace the foreground/background colour in the rendition mask with the
525specified one.
526
527=item $value = urxvt::GET_CUSTOM $rend
528
529Return the "custom" value: Every rendition has 5 bits for use by
530extensions. They can be set and changed as you like and are initially
531zero.
532
533=item $rend = urxvt::SET_CUSTOM $rend, $new_value
534
535Change the custom value.
536
537=back
538
539=cut
163 540
164BEGIN { 541BEGIN {
165 urxvt->bootstrap; 542 urxvt->bootstrap;
166 543
167 # overwrite perl's warn 544 # overwrite perl's warn
169 my $msg = join "", @_; 546 my $msg = join "", @_;
170 $msg .= "\n" 547 $msg .= "\n"
171 unless $msg =~ /\n$/; 548 unless $msg =~ /\n$/;
172 urxvt::warn ($msg); 549 urxvt::warn ($msg);
173 }; 550 };
551
552 # %ENV is the original startup environment
553 delete $ENV{IFS};
554 delete $ENV{CDPATH};
555 delete $ENV{BASH_ENV};
556 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
174} 557}
175 558
176my @hook_count; 559my @hook_count;
177my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 560my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
178 561
179sub verbose { 562sub verbose {
180 my ($level, $msg) = @_; 563 my ($level, $msg) = @_;
181 warn "$msg\n" if $level <= $verbosity; 564 warn "$msg\n" if $level <= $verbosity;
182} 565}
183 566
184# find on_xxx subs in the package and register them 567my $extension_pkg = "extension0000";
185# as hooks 568my %extension_pkg;
186sub register_package($) {
187 my ($pkg) = @_;
188
189 for my $htype (0.. $#HOOKNAME) {
190 my $name = $HOOKNAME[$htype];
191
192 my $ref = $pkg->can ("on_" . lc $name)
193 or next;
194
195 $term->{_hook}[$htype]{$ref*1} = $ref;
196 $hook_count[$htype]++
197 or set_should_invoke $htype, 1;
198 }
199}
200
201my $script_pkg = "script0000";
202my %script_pkg;
203 569
204# load a single script into its own package, once only 570# load a single script into its own package, once only
205sub script_package($) { 571sub extension_package($) {
206 my ($path) = @_; 572 my ($path) = @_;
207 573
208 $script_pkg{$path} ||= do { 574 $extension_pkg{$path} ||= do {
209 my $pkg = "urxvt::" . ($script_pkg++); 575 my $pkg = "urxvt::" . ($extension_pkg++);
210 576
211 verbose 3, "loading script '$path' into package '$pkg'"; 577 verbose 3, "loading extension '$path' into package '$pkg'";
212 578
213 open my $fh, "<:raw", $path 579 open my $fh, "<:raw", $path
214 or die "$path: $!"; 580 or die "$path: $!";
215 581
582 my $source = untaint
216 my $source = "package $pkg; use strict; use utf8;\n" 583 "package $pkg; use strict; use utf8;\n"
584 . "use base urxvt::term::extension::;\n"
217 . "#line 1 \"$path\"\n{\n" 585 . "#line 1 \"$path\"\n{\n"
218 . (do { local $/; <$fh> }) 586 . (do { local $/; <$fh> })
219 . "\n};\n1"; 587 . "\n};\n1";
220 588
589 eval $source
221 eval $source or die "$path: $@"; 590 or die "$path: $@";
222 591
223 $pkg 592 $pkg
224 } 593 }
225} 594}
226 595
596our $retval; # return value for urxvt
597
227# called by the rxvt core 598# called by the rxvt core
228sub invoke { 599sub invoke {
229 local $term = shift; 600 local $TERM = shift;
230 my $htype = shift; 601 my $htype = shift;
231 602
232 if ($htype == 0) { # INIT 603 if ($htype == 0) { # INIT
233 my @dirs = ((split /:/, $term->resource ("perl_lib")), "$LIBDIR/perl"); 604 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
605
606 my %ext_arg;
234 607
235 for my $ext (split /:/, $term->resource ("perl_ext")) { 608 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
609 if ($_ eq "default") {
610 $ext_arg{$_} ||= [] for qw(selection option-popup selection-popup searchable-scrollback);
611 } elsif (/^-(.*)$/) {
612 delete $ext_arg{$1};
613 } elsif (/^([^<]+)<(.*)>$/) {
614 push @{ $ext_arg{$1} }, $2;
615 } else {
616 $ext_arg{$_} ||= [];
617 }
618 }
619
620 while (my ($ext, $argv) = each %ext_arg) {
236 my @files = grep -f $_, map "$_/$ext", @dirs; 621 my @files = grep -f $_, map "$_/$ext", @dirs;
237 622
238 if (@files) { 623 if (@files) {
239 register_package script_package $files[0]; 624 $TERM->register_package (extension_package $files[0], $argv);
240 } else { 625 } else {
241 warn "perl extension '$ext' not found in perl library search path\n"; 626 warn "perl extension '$ext' not found in perl library search path\n";
242 } 627 }
243 } 628 }
244 629
630 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
631 warn $@ if $@;
632 }
633
634 $retval = undef;
635
636 if (my $cb = $TERM->{_hook}[$htype]) {
637 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $TERM, @_) . ")"
638 if $verbosity >= 10;
639
640 keys %$cb;
641
642 while (my ($pkg, $cb) = each %$cb) {
643 $retval = eval { $cb->($TERM->{_pkg}{$pkg}, @_) }
644 and last;
645
646 if ($@) {
647 $TERM->ungrab; # better to lose the grab than the session
648 warn $@;
649 }
650 }
651
652 verbose 11, "$HOOKNAME[$htype] returning <$retval>"
653 if $verbosity >= 11;
654 }
655
245 } elsif ($htype == 1) { # DESTROY 656 if ($htype == 1) { # DESTROY
246 if (my $hook = $term->{_hook}) { 657 if (my $hook = delete $TERM->{_hook}) {
247 for my $htype (0..$#$hook) { 658 for my $htype (0..$#$hook) {
248 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} } 659 $hook_count[$htype] -= scalar keys %{ $hook->[$htype] || {} }
249 or set_should_invoke $htype, 0; 660 or set_should_invoke $htype, 0;
250 } 661 }
251 } 662 }
663
664 # clear package objects
665 %$_ = () for values %{ $TERM->{_pkg} };
666
667 # clear package
668 %$TERM = ();
252 } 669 }
253 670
254 my $cb = $term->{_hook}[$htype] 671 $retval
255 or return; 672}
256 673
257 verbose 10, "$HOOKNAME[$htype] (" . (join ", ", $term, @_) . ")" 674sub exec_async(@) {
258 if $verbosity >= 10; 675 my $pid = fork;
259 676
677 return
678 if !defined $pid or $pid;
679
680 %ENV = %{ $TERM->env };
681
682 exec @_;
683 _exit 255;
684}
685
686# urxvt::term::extension
687
688package urxvt::term::extension;
689
690sub enable {
691 my ($self, %hook) = @_;
692 my $pkg = $self->{_pkg};
693
260 while (my ($k, $v) = each %$cb) { 694 while (my ($name, $cb) = each %hook) {
261 return 1 if $v->($term, @_); 695 my $htype = $HOOKTYPE{uc $name};
696 defined $htype
697 or Carp::croak "unsupported hook type '$name'";
698
699 unless (exists $self->{term}{_hook}[$htype]{$pkg}) {
700 $hook_count[$htype]++
701 or urxvt::set_should_invoke $htype, 1;
702 }
703
704 $self->{term}{_hook}[$htype]{$pkg} = $cb;
262 } 705 }
706}
263 707
708sub disable {
709 my ($self, @hook) = @_;
710 my $pkg = $self->{_pkg};
711
712 for my $name (@hook) {
713 my $htype = $HOOKTYPE{uc $name};
714 defined $htype
715 or Carp::croak "unsupported hook type '$name'";
716
717 if (delete $self->{term}{_hook}[$htype]{$pkg}) {
718 --$hook_count[$htype]
719 or urxvt::set_should_invoke $htype, 0;
720 }
264 0 721 }
265} 722}
266 723
267=back 724our $AUTOLOAD;
725
726sub AUTOLOAD {
727 $AUTOLOAD =~ /:([^:]+)$/
728 or die "FATAL: \$AUTOLOAD '$AUTOLOAD' unparsable";
729
730 eval qq{
731 sub $AUTOLOAD {
732 my \$proxy = shift;
733 \$proxy->{term}->$1 (\@_)
734 }
735 1
736 } or die "FATAL: unable to compile method forwarder: $@";
737
738 goto &$AUTOLOAD;
739}
740
741sub DESTROY {
742 # nop
743}
744
745# urxvt::destroy_hook
746
747sub urxvt::destroy_hook::DESTROY {
748 ${$_[0]}->();
749}
750
751sub urxvt::destroy_hook(&) {
752 bless \shift, urxvt::destroy_hook::
753}
754
755package urxvt::anyevent;
756
757=head2 The C<urxvt::anyevent> Class
758
759The sole purpose of this class is to deliver an interface to the
760C<AnyEvent> module - any module using it will work inside urxvt without
761further programming. The only exception is that you cannot wait on
762condition variables, but non-blocking condvar use is ok. What this means
763is that you cannot use blocking APIs, but the non-blocking variant should
764work.
765
766=cut
767
768our $VERSION = 1;
769
770$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
771push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
772
773sub timer {
774 my ($class, %arg) = @_;
775
776 my $cb = $arg{cb};
777
778 urxvt::timer
779 ->new
780 ->start (urxvt::NOW + $arg{after})
781 ->cb (sub {
782 $_[0]->stop; # need to cancel manually
783 $cb->();
784 })
785}
786
787sub io {
788 my ($class, %arg) = @_;
789
790 my $cb = $arg{cb};
791
792 bless [$arg{fh}, urxvt::iow
793 ->new
794 ->fd (fileno $arg{fh})
795 ->events (($arg{poll} =~ /r/ ? 1 : 0)
796 | ($arg{poll} =~ /w/ ? 2 : 0))
797 ->start
798 ->cb (sub {
799 $cb->(($_[1] & 1 ? 'r' : '')
800 . ($_[1] & 2 ? 'w' : ''));
801 })],
802 urxvt::anyevent::
803}
804
805sub DESTROY {
806 $_[0][1]->stop;
807}
808
809sub condvar {
810 bless \my $flag, urxvt::anyevent::condvar::
811}
812
813sub urxvt::anyevent::condvar::broadcast {
814 ${$_[0]}++;
815}
816
817sub urxvt::anyevent::condvar::wait {
818 unless (${$_[0]}) {
819 Carp::croak "AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API";
820 }
821}
822
823package urxvt::term;
268 824
269=head2 The C<urxvt::term> Class 825=head2 The C<urxvt::term> Class
270 826
271=over 4 827=over 4
828
829=cut
830
831# find on_xxx subs in the package and register them
832# as hooks
833sub register_package {
834 my ($self, $pkg, $argv) = @_;
835
836 my $proxy = bless {
837 _pkg => $pkg,
838 argv => $argv,
839 }, $pkg;
840 Scalar::Util::weaken ($proxy->{term} = $self);
841
842 $self->{_pkg}{$pkg} = $proxy;
843
844 for my $name (@HOOKNAME) {
845 if (my $ref = $pkg->can ("on_" . lc $name)) {
846 $proxy->enable ($name => $ref);
847 }
848 }
849}
850
851=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
852
853Creates a new terminal, very similar as if you had started it with system
854C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
855hash which defines the environment of the new terminal.
856
857Croaks (and probably outputs an error message) if the new instance
858couldn't be created. Returns C<undef> if the new instance didn't
859initialise perl, and the terminal object otherwise. The C<init> and
860C<start> hooks will be called during this call.
861
862=cut
863
864sub new {
865 my ($class, $env, @args) = @_;
866
867 _new ([ map "$_=$env->{$_}", keys %$env ], @args);
868}
869
870=item $term->destroy
871
872Destroy the terminal object (close the window, free resources
873etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
874watchers (timers, io watchers) are still active.
875
876=item $isset = $term->option ($optval[, $set])
877
878Returns true if the option specified by C<$optval> is enabled, and
879optionally change it. All option values are stored by name in the hash
880C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
881
882Here is a a likely non-exhaustive list of option names, please see the
883source file F</src/optinc.h> to see the actual list:
884
885 borderLess console cursorBlink cursorUnderline hold iconic insecure
886 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
887 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
888 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
889 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
890 tripleclickwords utmpInhibit visualBell
272 891
273=item $value = $term->resource ($name[, $newval]) 892=item $value = $term->resource ($name[, $newval])
274 893
275Returns the current resource value associated with a given name and 894Returns the current resource value associated with a given name and
276optionally sets a new value. Setting values is most useful in the C<init> 895optionally sets a new value. Setting values is most useful in the C<init>
286 905
287Please note that resource strings will currently only be freed when the 906Please note that resource strings will currently only be freed when the
288terminal is destroyed, so changing options frequently will eat memory. 907terminal is destroyed, so changing options frequently will eat memory.
289 908
290Here is a a likely non-exhaustive list of resource names, not all of which 909Here 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 910are supported in every build, please see the source file F</src/rsinc.h>
292list: 911to see the actual list:
293 912
294 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 913 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
295 borderLess color cursorBlink cursorUnderline cutchars delete_key 914 borderLess color cursorBlink cursorUnderline cutchars delete_key
296 display_name embed ext_bwidth fade font geometry hold iconName 915 display_name embed ext_bwidth fade font geometry hold iconName
297 imFont imLocale inputMethod insecure int_bwidth intensityStyles 916 imFont imLocale inputMethod insecure int_bwidth intensityStyles
298 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier 917 italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
299 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext 918 mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
300 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd 919 perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
301 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating 920 reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
302 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput 921 scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
303 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle 922 scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle
304 shade term_name title transparent transparent_all tripleclickwords 923 shade term_name title transparent transparent_all tripleclickwords
305 utmpInhibit visualBell 924 utmpInhibit visualBell
306 925
307=cut 926=cut
308 927
309sub urxvt::term::resource($$;$) { 928sub resource($$;$) {
310 my ($self, $name) = (shift, shift); 929 my ($self, $name) = (shift, shift);
311 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 930 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
312 goto &urxvt::term::_resource; 931 &urxvt::term::_resource
313} 932}
933
934=item $value = $term->x_resource ($pattern)
935
936Returns the X-Resource for the given pattern, excluding the program or
937class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
938same value as used by this instance of rxvt-unicode. Returns C<undef> if no
939resource with that pattern exists.
940
941This method should only be called during the C<on_start> hook, as there is
942only one resource database per display, and later invocations might return
943the wrong resources.
944
945=item $success = $term->parse_keysym ($keysym_spec, $command_string)
946
947Adds a keymap translation exactly as specified via a resource. See the
948C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
949
950=item $rend = $term->rstyle ([$new_rstyle])
951
952Return and optionally change the current rendition. Text that is output by
953the terminal application will use this style.
954
955=item ($row, $col) = $term->screen_cur ([$row, $col])
956
957Return the current coordinates of the text cursor position and optionally
958set it (which is usually bad as applications don't expect that).
314 959
315=item ($row, $col) = $term->selection_mark ([$row, $col]) 960=item ($row, $col) = $term->selection_mark ([$row, $col])
316 961
317=item ($row, $col) = $term->selection_beg ([$row, $col]) 962=item ($row, $col) = $term->selection_beg ([$row, $col])
318 963
319=item ($row, $col) = $term->selection_end ([$row, $col]) 964=item ($row, $col) = $term->selection_end ([$row, $col])
320 965
321Return the current values of the selection mark, begin or end positions, 966Return the current values of the selection mark, begin or end positions,
322and optionally set them to new values. 967and optionally set them to new values.
323 968
969=item $term->selection_make ($eventtime[, $rectangular])
970
971Tries to make a selection as set by C<selection_beg> and
972C<selection_end>. If C<$rectangular> is true (default: false), a
973rectangular selection will be made. This is the prefered function to make
974a selection.
975
324=item $success = $term->selection_grab ($eventtime) 976=item $success = $term->selection_grab ($eventtime)
325 977
326Try to request the primary selection from the server (for example, as set 978Try to request the primary selection text from the server (for example, as
327by the next method). 979set by the next method). No visual feedback will be given. This function
980is mostly useful from within C<on_sel_grab> hooks.
328 981
329=item $oldtext = $term->selection ([$newtext]) 982=item $oldtext = $term->selection ([$newtext])
330 983
331Return the current selection text and optionally replace it by C<$newtext>. 984Return the current selection text and optionally replace it by C<$newtext>.
332 985
333=item $term->scr_overlay ($x, $y, $text) 986=item $term->overlay_simple ($x, $y, $text)
334 987
335Create a simple multi-line overlay box. See the next method for details. 988Create a simple multi-line overlay box. See the next method for details.
336 989
337=cut 990=cut
338 991
339sub urxvt::term::scr_overlay { 992sub overlay_simple {
340 my ($self, $x, $y, $text) = @_; 993 my ($self, $x, $y, $text) = @_;
341 994
342 my @lines = split /\n/, $text; 995 my @lines = split /\n/, $text;
343 996
344 my $w = 0; 997 my $w = List::Util::max map $self->strwidth ($_), @lines;
345 for (map $self->strwidth ($_), @lines) {
346 $w = $_ if $w < $_;
347 }
348 998
349 $self->scr_overlay_new ($x, $y, $w, scalar @lines); 999 my $overlay = $self->overlay ($x, $y, $w, scalar @lines);
350 $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines; 1000 $overlay->set (0, $_, $lines[$_]) for 0.. $#lines;
351}
352 1001
1002 $overlay
1003}
1004
353=item $term->scr_overlay_new ($x, $y, $width, $height) 1005=item $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
354 1006
355Create a new (empty) overlay at the given position with the given 1007Create a new (empty) overlay at the given position with the given
356width/height. A border will be put around the box. If either C<$x> or 1008width/height. C<$rstyle> defines the initial rendition style
357C<$y> is negative, then this is counted from the right/bottom side, 1009(default: C<OVERLAY_RSTYLE>).
358respectively.
359 1010
360=item $term->scr_overlay_off 1011If C<$border> is C<2> (default), then a decorative border will be put
1012around the box.
361 1013
362Switch the overlay off again. 1014If either C<$x> or C<$y> is negative, then this is counted from the
1015right/bottom side, respectively.
363 1016
364=item $term->scr_overlay_set_char ($x, $y, $char, $rend = OVERLAY_RSTYLE) 1017This method returns an urxvt::overlay object. The overlay will be visible
1018as long as the perl object is referenced.
365 1019
366Put a single character (specified numerically) at the given overlay 1020The methods currently supported on C<urxvt::overlay> objects are:
367position.
368 1021
1022=over 4
1023
369=item $term->scr_overlay_set ($x, $y, $text) 1024=item $overlay->set ($x, $y, $text, $rend)
370 1025
371Write a string at the given position into the overlay. 1026Similar to C<< $term->ROW_t >> and C<< $term->ROW_r >> in that it puts
1027text in rxvt-unicode's special encoding and an array of rendition values
1028at a specific position inside the overlay.
372 1029
1030=item $overlay->hide
1031
1032If visible, hide the overlay, but do not destroy it.
1033
1034=item $overlay->show
1035
1036If hidden, display the overlay again.
1037
1038=back
1039
1040=item $popup = $term->popup ($event)
1041
1042Creates a new C<urxvt::popup> object that implements a popup menu. The
1043C<$event> I<must> be the event causing the menu to pop up (a button event,
1044currently).
1045
1046=cut
1047
1048sub popup {
1049 my ($self, $event) = @_;
1050
1051 $self->grab ($event->{time}, 1)
1052 or return;
1053
1054 my $popup = bless {
1055 term => $self,
1056 event => $event,
1057 }, urxvt::popup::;
1058
1059 Scalar::Util::weaken $popup->{term};
1060
1061 $self->{_destroy}{$popup} = urxvt::destroy_hook { $popup->{popup}->destroy };
1062 Scalar::Util::weaken $self->{_destroy}{$popup};
1063
1064 $popup
1065}
1066
373=item $cellwidth = $term->strwidth $string 1067=item $cellwidth = $term->strwidth ($string)
374 1068
375Returns the number of screen-cells this string would need. Correctly 1069Returns the number of screen-cells this string would need. Correctly
376accounts for wide and combining characters. 1070accounts for wide and combining characters.
377 1071
378=item $octets = $term->locale_encode $string 1072=item $octets = $term->locale_encode ($string)
379 1073
380Convert the given text string into the corresponding locale encoding. 1074Convert the given text string into the corresponding locale encoding.
381 1075
382=item $string = $term->locale_decode $octets 1076=item $string = $term->locale_decode ($octets)
383 1077
384Convert the given locale-encoded octets into a perl string. 1078Convert the given locale-encoded octets into a perl string.
385 1079
1080=item $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
1081
1082XORs the rendition values in the given span with the provided value
1083(default: C<RS_RVid>), which I<MUST NOT> contain font styles. Useful in
1084refresh hooks to provide effects similar to the selection.
1085
1086=item $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
1087
1088Similar to C<scr_xor_span>, but xors a rectangle instead. Trailing
1089whitespace will additionally be xored with the C<$rstyle2>, which defaults
1090to C<RS_RVid | RS_Uline>, which removes reverse video again and underlines
1091it instead. Both styles I<MUST NOT> contain font styles.
1092
1093=item $term->scr_bell
1094
1095Ring the bell!
1096
1097=item $term->scr_add_lines ($string)
1098
1099Write the given text string to the screen, as if output by the application
1100running inside the terminal. It may not contain command sequences (escape
1101codes), but is free to use line feeds, carriage returns and tabs. The
1102string is a normal text string, not in locale-dependent encoding.
1103
1104Normally its not a good idea to use this function, as programs might be
1105confused by changes in cursor position or scrolling. Its useful inside a
1106C<on_add_lines> hook, though.
1107
1108=item $term->cmd_parse ($octets)
1109
1110Similar to C<scr_add_lines>, but the argument must be in the
1111locale-specific encoding of the terminal and can contain command sequences
1112(escape codes) that will be interpreted.
1113
386=item $term->tt_write ($octets) 1114=item $term->tt_write ($octets)
387 1115
388Write the octets given in C<$data> to the tty (i.e. as program input). To 1116Write 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 1117pass characters instead of octets, you should convert your strings first
390the locale-specific encoding using C<< $term->locale_encode >>. 1118to the locale-specific encoding using C<< $term->locale_encode >>.
1119
1120=item $old_events = $term->pty_ev_events ([$new_events])
1121
1122Replaces the event mask of the pty watcher by the given event mask. Can
1123be used to suppress input and output handling to the pty/tty. See the
1124description of C<< urxvt::timer->events >>. Make sure to always restore
1125the previous value.
1126
1127=item $windowid = $term->parent
1128
1129Return the window id of the toplevel window.
1130
1131=item $windowid = $term->vt
1132
1133Return the window id of the terminal window.
1134
1135=item $window_width = $term->width
1136
1137=item $window_height = $term->height
1138
1139=item $font_width = $term->fwidth
1140
1141=item $font_height = $term->fheight
1142
1143=item $font_ascent = $term->fbase
1144
1145=item $terminal_rows = $term->nrow
1146
1147=item $terminal_columns = $term->ncol
1148
1149=item $has_focus = $term->focus
1150
1151=item $is_mapped = $term->mapped
1152
1153=item $max_scrollback = $term->saveLines
1154
1155=item $nrow_plus_saveLines = $term->total_rows
1156
1157=item $lines_in_scrollback = $term->nsaved
1158
1159Return various integers describing terminal characteristics.
1160
1161=item $x_display = $term->display_id
1162
1163Return the DISPLAY used by rxvt-unicode.
1164
1165=item $lc_ctype = $term->locale
1166
1167Returns the LC_CTYPE category string used by this rxvt-unicode.
1168
1169=item $env = $term->env
1170
1171Returns a copy of the environment in effect for the terminal as a hashref
1172similar to C<\%ENV>.
1173
1174=cut
1175
1176sub env {
1177 if (my $env = $_[0]->_env) {
1178 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env }
1179 } else {
1180 +{ %ENV }
1181 }
1182}
1183
1184=item $modifiermask = $term->ModLevel3Mask
1185
1186=item $modifiermask = $term->ModMetaMask
1187
1188=item $modifiermask = $term->ModNumLockMask
1189
1190Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
1191AltGr), the meta key (often Alt) and the num lock key, if applicable.
1192
1193=item $view_start = $term->view_start ([$newvalue])
1194
1195Returns the negative row number of the topmost line. Minimum value is
1196C<0>, which displays the normal terminal contents. Larger values scroll
1197this many lines into the scrollback buffer.
1198
1199=item $term->want_refresh
1200
1201Requests a screen refresh. At the next opportunity, rxvt-unicode will
1202compare the on-screen display with its stored representation. If they
1203differ, it redraws the differences.
1204
1205Used after changing terminal contents to display them.
1206
1207=item $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
1208
1209Returns the text of the entire row with number C<$row_number>. Row C<0>
1210is the topmost terminal line, row C<< $term->$ncol-1 >> is the bottommost
1211terminal line. The scrollback buffer starts at line C<-1> and extends to
1212line C<< -$term->nsaved >>. Nothing will be returned if a nonexistent line
1213is requested.
1214
1215If C<$new_text> is specified, it will replace characters in the current
1216line, starting at column C<$start_col> (default C<0>), which is useful
1217to replace only parts of a line. The font index in the rendition will
1218automatically be updated.
1219
1220C<$text> is in a special encoding: tabs and wide characters that use more
1221than one cell when displayed are padded with urxvt::NOCHAR characters
1222(C<chr 65535>). Characters with combining characters and other characters
1223that do not fit into the normal tetx encoding will be replaced with
1224characters in the private use area.
1225
1226You have to obey this encoding when changing text. The advantage is
1227that C<substr> and similar functions work on screen cells and not on
1228characters.
1229
1230The methods C<< $term->special_encode >> and C<< $term->special_decode >>
1231can be used to convert normal strings into this encoding and vice versa.
1232
1233=item $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
1234
1235Like C<< $term->ROW_t >>, but returns an arrayref with rendition
1236bitsets. Rendition bitsets contain information about colour, font, font
1237styles and similar information. See also C<< $term->ROW_t >>.
1238
1239When setting rendition, the font mask will be ignored.
1240
1241See the section on RENDITION, above.
1242
1243=item $length = $term->ROW_l ($row_number[, $new_length])
1244
1245Returns the number of screen cells that are in use ("the line
1246length"). Unlike the urxvt core, this returns C<< $term->ncol >> if the
1247line is joined with the following one.
1248
1249=item $bool = $term->is_longer ($row_number)
1250
1251Returns true if the row is part of a multiple-row logical "line" (i.e.
1252joined with the following row), which means all characters are in use
1253and it is continued on the next row (and possibly a continuation of the
1254previous row(s)).
1255
1256=item $line = $term->line ($row_number)
1257
1258Create and return a new C<urxvt::line> object that stores information
1259about the logical line that row C<$row_number> is part of. It supports the
1260following methods:
1261
1262=over 4
1263
1264=item $text = $line->t ([$new_text])
1265
1266Returns or replaces the full text of the line, similar to C<ROW_t>
1267
1268=item $rend = $line->r ([$new_rend])
1269
1270Returns or replaces the full rendition array of the line, similar to C<ROW_r>
1271
1272=item $length = $line->l
1273
1274Returns the length of the line in cells, similar to C<ROW_l>.
1275
1276=item $rownum = $line->beg
1277
1278=item $rownum = $line->end
1279
1280Return the row number of the first/last row of the line, respectively.
1281
1282=item $offset = $line->offset_of ($row, $col)
1283
1284Returns the character offset of the given row|col pair within the logical
1285line. Works for rows outside the line, too, and returns corresponding
1286offsets outside the string.
1287
1288=item ($row, $col) = $line->coord_of ($offset)
1289
1290Translates a string offset into terminal coordinates again.
1291
1292=back
1293
1294=cut
1295
1296sub line {
1297 my ($self, $row) = @_;
1298
1299 my $maxrow = $self->nrow - 1;
1300
1301 my ($beg, $end) = ($row, $row);
1302
1303 --$beg while $self->ROW_is_longer ($beg - 1);
1304 ++$end while $self->ROW_is_longer ($end) && $end < $maxrow;
1305
1306 bless {
1307 term => $self,
1308 beg => $beg,
1309 end => $end,
1310 ncol => $self->ncol,
1311 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
1312 }, urxvt::line::
1313}
1314
1315sub urxvt::line::t {
1316 my ($self) = @_;
1317
1318 if (@_ > 1)
1319 {
1320 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1321 for $self->{beg} .. $self->{end};
1322 }
1323
1324 defined wantarray &&
1325 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
1326 0, $self->{len}
1327}
1328
1329sub urxvt::line::r {
1330 my ($self) = @_;
1331
1332 if (@_ > 1)
1333 {
1334 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1335 for $self->{beg} .. $self->{end};
1336 }
1337
1338 if (defined wantarray) {
1339 my $rend = [
1340 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
1341 ];
1342 $#$rend = $self->{len} - 1;
1343 return $rend;
1344 }
1345
1346 ()
1347}
1348
1349sub urxvt::line::beg { $_[0]{beg} }
1350sub urxvt::line::end { $_[0]{end} }
1351sub urxvt::line::l { $_[0]{len} }
1352
1353sub urxvt::line::offset_of {
1354 my ($self, $row, $col) = @_;
1355
1356 ($row - $self->{beg}) * $self->{ncol} + $col
1357}
1358
1359sub urxvt::line::coord_of {
1360 my ($self, $offset) = @_;
1361
1362 use integer;
1363
1364 (
1365 $offset / $self->{ncol} + $self->{beg},
1366 $offset % $self->{ncol}
1367 )
1368}
1369
1370=item $text = $term->special_encode $string
1371
1372Converts a perl string into the special encoding used by rxvt-unicode,
1373where one character corresponds to one screen cell. See
1374C<< $term->ROW_t >> for details.
1375
1376=item $string = $term->special_decode $text
1377
1378Converts rxvt-unicodes text reprsentation into a perl string. See
1379C<< $term->ROW_t >> for details.
1380
1381=item $success = $term->grab_button ($button, $modifiermask)
1382
1383Registers a synchronous button grab. See the XGrabButton manpage.
1384
1385=item $success = $term->grab ($eventtime[, $sync])
1386
1387Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or
1388synchronous (C<$sync> is true). Also remembers the grab timestampe.
1389
1390=item $term->allow_events_async
1391
1392Calls XAllowEvents with AsyncBoth for the most recent grab.
1393
1394=item $term->allow_events_sync
1395
1396Calls XAllowEvents with SyncBoth for the most recent grab.
1397
1398=item $term->allow_events_replay
1399
1400Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most
1401recent grab.
1402
1403=item $term->ungrab
1404
1405Calls XUngrab for the most recent grab. Is called automatically on
1406evaluation errors, as it is better to lose the grab in the error case as
1407the session.
1408
1409=back
1410
1411=cut
1412
1413package urxvt::popup;
1414
1415=head2 The C<urxvt::popup> Class
1416
1417=over 4
1418
1419=cut
1420
1421sub add_item {
1422 my ($self, $item) = @_;
1423
1424 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1425 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1426 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1427
1428 $item->{render} ||= sub { $_[0]{text} };
1429
1430 push @{ $self->{item} }, $item;
1431}
1432
1433=item $popup->add_title ($title)
1434
1435Adds a non-clickable title to the popup.
1436
1437=cut
1438
1439sub add_title {
1440 my ($self, $title) = @_;
1441
1442 $self->add_item ({
1443 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1444 text => $title,
1445 activate => sub { },
1446 });
1447}
1448
1449=item $popup->add_separator ([$sepchr])
1450
1451Creates a separator, optionally using the character given as C<$sepchr>.
1452
1453=cut
1454
1455sub add_separator {
1456 my ($self, $sep) = @_;
1457
1458 $sep ||= "=";
1459
1460 $self->add_item ({
1461 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1462 text => "",
1463 render => sub { $sep x $self->{term}->ncol },
1464 activate => sub { },
1465 });
1466}
1467
1468=item $popup->add_button ($text, $cb)
1469
1470Adds a clickable button to the popup. C<$cb> is called whenever it is
1471selected.
1472
1473=cut
1474
1475sub add_button {
1476 my ($self, $text, $cb) = @_;
1477
1478 $self->add_item ({ type => "button", text => $text, activate => $cb});
1479}
1480
1481=item $popup->add_toggle ($text, $cb, $initial_value)
1482
1483Adds a toggle/checkbox item to the popup. Teh callback gets called
1484whenever it gets toggled, with a boolean indicating its value as its first
1485argument.
1486
1487=cut
1488
1489sub add_toggle {
1490 my ($self, $text, $cb, $value) = @_;
1491
1492 my $item; $item = {
1493 type => "button",
1494 text => " $text",
1495 value => $value,
1496 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1497 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1498 };
1499
1500 $self->add_item ($item);
1501}
1502
1503=item $popup->show
1504
1505Displays the popup (which is initially hidden).
1506
1507=cut
1508
1509sub show {
1510 my ($self) = @_;
1511
1512 local $urxvt::popup::self = $self;
1513
1514 my $env = $self->{term}->env;
1515 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1516 delete $env->{LC_ALL};
1517 $env->{LC_CTYPE} = $self->{term}->locale;
1518
1519 urxvt::term->new ($env, $self->{term}->resource ("name"),
1520 "--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1521 "--transient-for" => $self->{term}->parent,
1522 "-display" => $self->{term}->display_id,
1523 "-pe" => "urxvt-popup")
1524 or die "unable to create popup window\n";
1525}
1526
1527sub DESTROY {
1528 my ($self) = @_;
1529
1530 delete $self->{term}{_destroy}{$self};
1531 $self->{term}->ungrab;
1532}
391 1533
392=back 1534=back
393 1535
394=head2 The C<urxvt::timer> Class 1536=head2 The C<urxvt::timer> Class
395 1537
396This class implements timer watchers/events. Time is represented as a 1538This class implements timer watchers/events. Time is represented as a
397fractional number of seconds since the epoch. Example: 1539fractional number of seconds since the epoch. Example:
398 1540
399 # create a digital clock display in upper right corner 1541 $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
400 $term->{timer} = urxvt::timer 1542 $term->{timer} = urxvt::timer
401 ->new 1543 ->new
402 ->start (urxvt::NOW) 1544 ->interval (1)
403 ->cb (sub { 1545 ->cb (sub {
404 my ($timer) = @_;
405 my $time = $timer->at;
406 $timer->start ($time + 1);
407 $self->scr_overlay (-1, 0, 1546 $term->{overlay}->set (0, 0,
408 POSIX::strftime "%H:%M:%S", localtime $time); 1547 sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
409 }); 1548 });
410 1549
411=over 4 1550=over 4
412 1551
413=item $timer = new urxvt::timer 1552=item $timer = new urxvt::timer
414 1553
415Create a new timer object in stopped state. 1554Create a new timer object in started state. It is scheduled to fire
1555immediately.
416 1556
417=item $timer = $timer->cb (sub { my ($timer) = @_; ... }) 1557=item $timer = $timer->cb (sub { my ($timer) = @_; ... })
418 1558
419Set the callback to be called when the timer triggers. 1559Set the callback to be called when the timer triggers.
420 1560
423Return the time this watcher will fire next. 1563Return the time this watcher will fire next.
424 1564
425=item $timer = $timer->set ($tstamp) 1565=item $timer = $timer->set ($tstamp)
426 1566
427Set the time the event is generated to $tstamp. 1567Set the time the event is generated to $tstamp.
1568
1569=item $timer = $timer->interval ($interval)
1570
1571Normally (and when C<$interval> is C<0>), the timer will automatically
1572stop after it has fired once. If C<$interval> is non-zero, then the timer
1573is automatically rescheduled at the given intervals.
428 1574
429=item $timer = $timer->start 1575=item $timer = $timer->start
430 1576
431Start the timer. 1577Start the timer.
432 1578
446 1592
447 $term->{socket} = ... 1593 $term->{socket} = ...
448 $term->{iow} = urxvt::iow 1594 $term->{iow} = urxvt::iow
449 ->new 1595 ->new
450 ->fd (fileno $term->{socket}) 1596 ->fd (fileno $term->{socket})
451 ->events (1) # wait for read data 1597 ->events (urxvt::EVENT_READ)
452 ->start 1598 ->start
453 ->cb (sub { 1599 ->cb (sub {
454 my ($iow, $revents) = @_; 1600 my ($iow, $revents) = @_;
455 # $revents must be 1 here, no need to check 1601 # $revents must be 1 here, no need to check
456 sysread $term->{socket}, my $buf, 8192 1602 sysread $term->{socket}, my $buf, 8192
473 1619
474Set the filedescriptor (not handle) to watch. 1620Set the filedescriptor (not handle) to watch.
475 1621
476=item $iow = $iow->events ($eventmask) 1622=item $iow = $iow->events ($eventmask)
477 1623
478Set the event mask to watch. Bit #0 (value C<1>) enables watching for read 1624Set the event mask to watch. The only allowed values are
479data, Bit #1 (value C<2>) enables watching for write data. 1625C<urxvt::EVENT_READ> and C<urxvt::EVENT_WRITE>, which might be ORed
1626together, or C<urxvt::EVENT_NONE>.
480 1627
481=item $iow = $iow->start 1628=item $iow = $iow->start
482 1629
483Start watching for requested events on the given handle. 1630Start watching for requested events on the given handle.
484 1631
495This variable controls the verbosity level of the perl extension. Higher 1642This variable controls the verbosity level of the perl extension. Higher
496numbers indicate more verbose output. 1643numbers indicate more verbose output.
497 1644
498=over 4 1645=over 4
499 1646
500=item 0 - only fatal messages 1647=item == 0 - fatal messages
501 1648
502=item 3 - script loading and management 1649=item >= 3 - script loading and management
503 1650
504=item 10 - all events received 1651=item >=10 - all called hooks
1652
1653=item >=11 - hook reutrn values
505 1654
506=back 1655=back
507 1656
508=head1 AUTHOR 1657=head1 AUTHOR
509 1658

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines