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.33 by root, Thu Jan 5 01:04:10 2006 UTC vs.
Revision 1.60 by root, Mon Jan 9 01:21:43 2006 UTC

17 17
18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test 18 @@RXVT_NAME@@ --perl-lib $HOME -pe grab_test
19 19
20=head1 DESCRIPTION 20=head1 DESCRIPTION
21 21
22Everytime a terminal object gets created, scripts specified via the 22Everytime a terminal object gets created, extension scripts specified via
23C<perl> resource are loaded and associated with it. 23the C<perl> resource are loaded and associated with it.
24 24
25Scripts are compiled in a 'use strict' and 'use utf8' environment, and 25Scripts are compiled in a 'use strict' and 'use utf8' environment, and
26thus must be encoded as UTF-8. 26thus must be encoded as UTF-8.
27 27
28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where 28Each script will only ever be loaded once, even in @@RXVT_NAME@@d, where
37 37
38 @@RXVT_NAME@@ -pe <extensionname> 38 @@RXVT_NAME@@ -pe <extensionname>
39 39
40=over 4 40=over 4
41 41
42=item selection 42=item selection (enabled by default)
43 43
44Intelligent selection. This extension tries to be more intelligent when 44Intelligent selection. This extension tries to be more intelligent when
45the user extends selections (double-click). Right now, it tries to select 45the user extends selections (double-click). Right now, it tries to select
46urls and complete shell-quoted arguments, which is very convenient, too, 46urls and complete shell-quoted arguments, which is very convenient, too,
47if your F<ls> supports C<--quoting-style=shell>. 47if your F<ls> supports C<--quoting-style=shell>.
56 56
57 URxvt.keysym.C-M-r: perl:selection:rot13 57 URxvt.keysym.C-M-r: perl:selection:rot13
58 58
59=back 59=back
60 60
61=item option-popup (enabled by default)
62
63Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at
64runtime.
65
66=item selection-popup (enabled by default)
67
68Binds a popup menu to Ctrl-Button3 that lets you convert the selection
69text into various other formats/action.
70
61=item digital-clock 71=item digital-clock
62 72
63Displays a digital clock using the built-in overlay. 73Displays a digital clock using the built-in overlay.
74
75=item mark-urls
76
77Uses per-line display filtering (C<on_line_update>) to underline urls.
78
79=item block-graphics-to-ascii
80
81A not very useful example of filtering all text output to the terminal,
82by replacing all line-drawing characters (U+2500 .. U+259F) by a
83similar-looking ascii character.
64 84
65=item example-refresh-hooks 85=item example-refresh-hooks
66 86
67Displays a very simple digital clock in the upper right corner of the 87Displays a very simple digital clock in the upper right corner of the
68window. Illustrates overwriting the refresh callbacks to create your own 88window. Illustrates overwriting the refresh callbacks to create your own
69overlays or changes. 89overlays or changes.
70
71=item mark-urls
72
73A not very useful example of filtering all text output to the terminal, by
74underlining all urls that matches a certain regex (i.e. some urls :). It
75is not very useful because urls that are output in multiple steps (e.g.
76when typing them) do not get marked.
77 90
78=back 91=back
79 92
80=head2 General API Considerations 93=head2 General API Considerations
81 94
113 126
114=back 127=back
115 128
116=head2 Hooks 129=head2 Hooks
117 130
118The following subroutines can be declared in loaded scripts, and will be 131The following subroutines can be declared in extension files, and will be
119called whenever the relevant event happens. 132called whenever the relevant event happens.
120 133
121The first argument passed to them is an object private to each terminal 134The first argument passed to them is an object private to each terminal
122and extension package. You can call all C<urxvt::term> methods on it, but 135and extension package. You can call all C<urxvt::term> methods on it, but
123its not a real C<urxvt::term> object. Instead, the real C<urxvt::term> 136its not a real C<urxvt::term> object. Instead, the real C<urxvt::term>
124object that is shared between all packages is stored in the C<term> 137object that is shared between all packages is stored in the C<term>
125member. 138member. It is, however, blessed intot he package of the extension script,
139so for all practical purposes you can treat an extension script as a class.
126 140
127All of them must return a boolean value. If it is true, then the event 141All of them must return a boolean value. If it is true, then the event
128counts as being I<consumed>, and the invocation of other hooks is skipped, 142counts as being I<consumed>, and the invocation of other hooks is skipped,
129and the relevant action might not be carried out by the C++ code. 143and the relevant action might not be carried out by the C++ code.
130 144
133=over 4 147=over 4
134 148
135=item on_init $term 149=item on_init $term
136 150
137Called after a new terminal object has been initialized, but before 151Called after a new terminal object has been initialized, but before
138windows are created or the command gets run. 152windows are created or the command gets run. Most methods are unsafe to
153call or deliver senseless data, as terminal size and other characteristics
154have not yet been determined. You can safely query and change resources,
155though.
139 156
140=item on_reset $term 157=item on_reset $term
141 158
142Called after the screen is "reset" for any reason, such as resizing or 159Called after the screen is "reset" for any reason, such as resizing or
143control sequences. Here is where you can react on changes to size-related 160control sequences. Here is where you can react on changes to size-related
171click) and is either supposed to return false (normal operation), or 188click) and is either supposed to return false (normal operation), or
172should extend the selection itelf and return true to suppress the built-in 189should extend the selection itelf and return true to suppress the built-in
173processing. 190processing.
174 191
175See the F<selection> example extension. 192See the F<selection> example extension.
176
177=item on_focus_in $term
178
179Called whenever the window gets the keyboard focus, before urxvt does
180focus in processing.
181
182=item on_focus_out $term
183
184Called wheneever the window loses keyboard focus, before urxvt does focus
185out processing.
186 193
187=item on_view_change $term, $offset 194=item on_view_change $term, $offset
188 195
189Called whenever the view offset changes, i..e the user or program 196Called whenever the view offset changes, i..e the user or program
190scrolls. Offset C<0> means display the normal terminal, positive values 197scrolls. Offset C<0> means display the normal terminal, positive values
223can filter/change and output the text yourself by returning a true value 230can filter/change and output the text yourself by returning a true value
224and calling C<< $term->scr_add_lines >> yourself. Please note that this 231and calling C<< $term->scr_add_lines >> yourself. Please note that this
225might be very slow, however, as your hook is called for B<all> text being 232might be very slow, however, as your hook is called for B<all> text being
226output. 233output.
227 234
235=item on_line_update $term, $row
236
237Called whenever a line was updated or changed. Can be used to filter
238screen output (e.g. underline urls or other useless stuff). Only lines
239that are being shown will be filtered, and, due to performance reasons,
240not always immediately.
241
242The row number is always the topmost row of the line if the line spans
243multiple rows.
244
245Please note that, if you change the line, then the hook might get called
246later with the already-modified line (e.g. if unrelated parts change), so
247you cannot just toggle rendition bits, but only set them.
248
228=item on_refresh_begin $term 249=item on_refresh_begin $term
229 250
230Called just before the screen gets redrawn. Can be used for overlay 251Called just before the screen gets redrawn. Can be used for overlay
231or similar effects by modify terminal contents in refresh_begin, and 252or similar effects by modify terminal contents in refresh_begin, and
232restoring them in refresh_end. The built-in overlay and selection display 253restoring them in refresh_end. The built-in overlay and selection display
240 261
241Called whenever the user presses a key combination that has a 262Called whenever the user presses a key combination that has a
242C<perl:string> action bound to it (see description of the B<keysym> 263C<perl:string> action bound to it (see description of the B<keysym>
243resource in the @@RXVT_NAME@@(1) manpage). 264resource in the @@RXVT_NAME@@(1) manpage).
244 265
266=item on_focus_in $term
267
268Called whenever the window gets the keyboard focus, before rxvt-unicode
269does focus in processing.
270
271=item on_focus_out $term
272
273Called wheneever the window loses keyboard focus, before rxvt-unicode does
274focus out processing.
275
276=item on_key_press $term, $event, $octets
277
278=item on_key_release $term, $event
279
280=item on_button_press $term, $event
281
282=item on_button_release $term, $event
283
284=item on_motion_notify $term, $event
285
286=item on_map_notify $term, $event
287
288=item on_unmap_notify $term, $event
289
290Called whenever the corresponding X event is received for the terminal If
291the hook returns true, then the even will be ignored by rxvt-unicode.
292
293The event is a hash with most values as named by Xlib (see the XEvent
294manpage), with the additional members C<row> and C<col>, which are the row
295and column under the mouse cursor.
296
297C<on_key_press> additionally receives the string rxvt-unicode would
298output, if any, in locale-specific encoding.
299
300subwindow.
301
245=back 302=back
246 303
247=head2 Variables in the C<urxvt> Package 304=head2 Variables in the C<urxvt> Package
248 305
249=over 4 306=over 4
250 307
251=item $urxvt::TERM 308=item $urxvt::TERM
252 309
253The current terminal. Whenever a callback/Hook is bein executed, this 310The current terminal. This variable stores the current C<urxvt::term>
254variable stores the current C<urxvt::term> object. 311object, whenever a callback/hook is executing.
255 312
256=back 313=back
257 314
258=head2 Functions in the C<urxvt> Package 315=head2 Functions in the C<urxvt> Package
259 316
260=over 4 317=over 4
318
319=item $term = new urxvt [arg...]
320
321Creates a new terminal, very similar as if you had started it with
322C<system $binfile, arg...>. Croaks (and probably outputs an error message)
323if the new instance couldn't be created. Returns C<undef> if the new
324instance didn't initialise perl, and the terminal object otherwise. The
325C<init> and C<start> hooks will be called during the call.
261 326
262=item urxvt::fatal $errormessage 327=item urxvt::fatal $errormessage
263 328
264Fatally aborts execution with the given error message. Avoid at all 329Fatally aborts execution with the given error message. Avoid at all
265costs! The only time this is acceptable is when the terminal process 330costs! The only time this is acceptable is when the terminal process
275correct place, e.g. on stderr of the connecting urxvtc client. 340correct place, e.g. on stderr of the connecting urxvtc client.
276 341
277=item $time = urxvt::NOW 342=item $time = urxvt::NOW
278 343
279Returns the "current time" (as per the event loop). 344Returns the "current time" (as per the event loop).
345
346=item urxvt::CurrentTime
347
348=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
349Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
350Button4Mask, Button5Mask, AnyModifier
351
352Various constants for use in X calls and event processing.
280 353
281=back 354=back
282 355
283=head2 RENDITION 356=head2 RENDITION
284 357
334 407
335=cut 408=cut
336 409
337package urxvt; 410package urxvt;
338 411
412use utf8;
339use strict; 413use strict;
340use Scalar::Util (); 414use Scalar::Util ();
415use List::Util ();
341 416
417our $VERSION = 1;
342our $TERM; 418our $TERM;
343our @HOOKNAME; 419our @HOOKNAME;
420our %OPTION;
344our $LIBDIR; 421our $LIBDIR;
345 422
346BEGIN { 423BEGIN {
347 urxvt->bootstrap; 424 urxvt->bootstrap;
348 425
351 my $msg = join "", @_; 428 my $msg = join "", @_;
352 $msg .= "\n" 429 $msg .= "\n"
353 unless $msg =~ /\n$/; 430 unless $msg =~ /\n$/;
354 urxvt::warn ($msg); 431 urxvt::warn ($msg);
355 }; 432 };
433
434 delete $ENV{IFS};
435 delete $ENV{CDPATH};
436 delete $ENV{BASH_ENV};
437 $ENV{PATH} = "/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin:/opt/sbin";
356} 438}
357 439
358my @hook_count; 440my @hook_count;
359my $verbosity = $ENV{URXVT_PERL_VERBOSITY}; 441my $verbosity = $ENV{URXVT_PERL_VERBOSITY};
360 442
378 $hook_count[$htype]++ 460 $hook_count[$htype]++
379 or set_should_invoke $htype, 1; 461 or set_should_invoke $htype, 1;
380 } 462 }
381} 463}
382 464
383my $script_pkg = "script0000"; 465my $extension_pkg = "extension0000";
384my %script_pkg; 466my %extension_pkg;
385 467
386# load a single script into its own package, once only 468# load a single script into its own package, once only
387sub script_package($) { 469sub extension_package($) {
388 my ($path) = @_; 470 my ($path) = @_;
389 471
390 $script_pkg{$path} ||= do { 472 $extension_pkg{$path} ||= do {
391 my $pkg = "urxvt::" . ($script_pkg++); 473 my $pkg = "urxvt::" . ($extension_pkg++);
392 474
393 verbose 3, "loading script '$path' into package '$pkg'"; 475 verbose 3, "loading extension '$path' into package '$pkg'";
394 476
395 open my $fh, "<:raw", $path 477 open my $fh, "<:raw", $path
396 or die "$path: $!"; 478 or die "$path: $!";
397 479
398 my $source = "package $pkg; use strict; use utf8;\n" 480 my $source = untaint "package $pkg; use strict; use utf8;\n"
481 . "use base urxvt::term::proxy::;\n"
399 . "#line 1 \"$path\"\n{\n" 482 . "#line 1 \"$path\"\n{\n"
400 . (do { local $/; <$fh> }) 483 . (do { local $/; <$fh> })
401 . "\n};\n1"; 484 . "\n};\n1";
402 485
403 eval $source or die "$path: $@"; 486 eval $source or die "$path: $@";
413 local $TERM = shift; 496 local $TERM = shift;
414 my $htype = shift; 497 my $htype = shift;
415 498
416 if ($htype == 0) { # INIT 499 if ($htype == 0) { # INIT
417 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl"); 500 my @dirs = ((split /:/, $TERM->resource ("perl_lib")), "$LIBDIR/perl");
501
502 my %want_ext;
418 503
419 for my $ext (map { split /:/, $TERM->resource ("perl_ext_$_") } 1, 2) { 504 for (map { split /,/, $TERM->resource ("perl_ext_$_") } 1, 2) {
505 if ($_ eq "default") {
506 $want_ext{$_}++ for qw(selection option-popup selection-popup);
507 } elsif (/^-(.*)$/) {
508 delete $want_ext{$1};
509 } else {
510 $want_ext{$_}++;
511 }
512 }
513
514 for my $ext (keys %want_ext) {
420 my @files = grep -f $_, map "$_/$ext", @dirs; 515 my @files = grep -f $_, map "$_/$ext", @dirs;
421 516
422 if (@files) { 517 if (@files) {
423 register_package script_package $files[0]; 518 register_package extension_package $files[0];
424 } else { 519 } else {
425 warn "perl extension '$ext' not found in perl library search path\n"; 520 warn "perl extension '$ext' not found in perl library search path\n";
426 } 521 }
427 } 522 }
523
524 eval "#line 1 \"--perl-eval resource/argument\"\n" . $TERM->resource ("perl_eval");
525 warn $@ if $@;
428 } 526 }
429 527
430 $retval = undef; 528 $retval = undef;
431 529
432 if (my $cb = $TERM->{_hook}[$htype]) { 530 if (my $cb = $TERM->{_hook}[$htype]) {
434 if $verbosity >= 10; 532 if $verbosity >= 10;
435 533
436 keys %$cb; 534 keys %$cb;
437 535
438 while (my ($pkg, $cb) = each %$cb) { 536 while (my ($pkg, $cb) = each %$cb) {
537 eval {
439 $retval = $cb->( 538 $retval = $cb->(
440 $TERM->{_pkg}{$pkg} ||= do { 539 $TERM->{_pkg}{$pkg} ||= do {
441 my $proxy = bless { }, urxvt::term::proxy::; 540 my $proxy = bless { }, $pkg;
442 Scalar::Util::weaken ($proxy->{term} = $TERM); 541 Scalar::Util::weaken ($proxy->{term} = $TERM);
443 $proxy 542 $proxy
444 }, 543 },
445 @_, 544 @_,
446 ) and last; 545 ) and last;
546 };
547 if ($@) {
548 $TERM->ungrab; # better to lose the grab than the session
549 warn $@;
550 }
447 } 551 }
448 } 552 }
449 553
450 if ($htype == 1) { # DESTROY 554 if ($htype == 1) { # DESTROY
451 # remove hooks if unused 555 # remove hooks if unused
464 } 568 }
465 569
466 $retval 570 $retval
467} 571}
468 572
573# urxvt::term::proxy
574
469sub urxvt::term::proxy::AUTOLOAD { 575sub urxvt::term::proxy::AUTOLOAD {
470 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/ 576 $urxvt::term::proxy::AUTOLOAD =~ /:([^:]+)$/
471 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable"; 577 or die "FATAL: \$AUTOLOAD '$urxvt::term::proxy::AUTOLOAD' unparsable";
472 578
473 eval qq{ 579 eval qq{
479 } or die "FATAL: unable to compile method forwarder: $@"; 585 } or die "FATAL: unable to compile method forwarder: $@";
480 586
481 goto &$urxvt::term::proxy::AUTOLOAD; 587 goto &$urxvt::term::proxy::AUTOLOAD;
482} 588}
483 589
590sub urxvt::term::proxy::DESTROY {
591 # nop
592}
593
594# urxvt::destroy_hook
595
596sub urxvt::destroy_hook::DESTROY {
597 ${$_[0]}->();
598}
599
600sub urxvt::destroy_hook(&) {
601 bless \shift, urxvt::destroy_hook::
602}
603
604package urxvt::anyevent;
605
606=head2 The C<urxvt::anyevent> Class
607
608The sole purpose of this class is to deliver an interface to the
609C<AnyEvent> module - any module using it will work inside urxvt without
610further work. The only exception is that you cannot wait on condition
611variables, but non-blocking condvar use is ok. What this means is that you
612cannot use blocking APIs, but the non-blocking variant should work.
613
614=cut
615
616our $VERSION = 1;
617
618$INC{"urxvt/anyevent.pm"} = 1; # mark us as there
619push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
620
621sub timer {
622 my ($class, %arg) = @_;
623
624 my $cb = $arg{cb};
625
626 urxvt::timer
627 ->new
628 ->start (urxvt::NOW + $arg{after})
629 ->cb (sub {
630 $_[0]->stop; # need to cancel manually
631 $cb->();
632 })
633}
634
635sub io {
636 my ($class, %arg) = @_;
637
638 my $cb = $arg{cb};
639
640 bless [$arg{fh}, urxvt::iow
641 ->new
642 ->fd (fileno $arg{fh})
643 ->events (($arg{poll} =~ /r/ ? 1 : 0)
644 | ($arg{poll} =~ /w/ ? 2 : 0))
645 ->start
646 ->cb (sub {
647 $cb->(($_[1] & 1 ? 'r' : '')
648 . ($_[1] & 2 ? 'w' : ''));
649 })],
650 urxvt::anyevent::
651}
652
653sub DESTROY {
654 $_[0][1]->stop;
655}
656
657sub condvar {
658 bless \my $flag, urxvt::anyevent::condvar::
659}
660
661sub urxvt::anyevent::condvar::broadcast {
662 ${$_[0]}++;
663}
664
665sub urxvt::anyevent::condvar::wait {
666 unless (${$_[0]}) {
667 require Carp;
668 Carp::croak ("AnyEvent->condvar blocking wait unsupported in urxvt, use a non-blocking API");
669 }
670}
671
672package urxvt::term;
673
484=head2 The C<urxvt::term> Class 674=head2 The C<urxvt::term> Class
485 675
486=over 4 676=over 4
677
678=item $term->destroy
679
680Destroy the terminal object (close the window, free resources etc.).
681
682=item $isset = $term->option ($optval[, $set])
683
684Returns true if the option specified by C<$optval> is enabled, and
685optionally change it. All option values are stored by name in the hash
686C<%urxvt::OPTION>. Options not enabled in this binary are not in the hash.
687
688Here is a a likely non-exhaustive list of option names, please see the
689source file F</src/optinc.h> to see the actual list:
690
691 borderLess console cursorBlink cursorUnderline hold iconic insecure
692 intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
693 pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
694 scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
695 secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
696 tripleclickwords utmpInhibit visualBell
487 697
488=item $value = $term->resource ($name[, $newval]) 698=item $value = $term->resource ($name[, $newval])
489 699
490Returns the current resource value associated with a given name and 700Returns the current resource value associated with a given name and
491optionally sets a new value. Setting values is most useful in the C<init> 701optionally sets a new value. Setting values is most useful in the C<init>
501 711
502Please note that resource strings will currently only be freed when the 712Please note that resource strings will currently only be freed when the
503terminal is destroyed, so changing options frequently will eat memory. 713terminal is destroyed, so changing options frequently will eat memory.
504 714
505Here is a a likely non-exhaustive list of resource names, not all of which 715Here is a a likely non-exhaustive list of resource names, not all of which
506are supported in every build, please see the source to see the actual 716are supported in every build, please see the source file F</src/rsinc.h>
507list: 717to see the actual list:
508 718
509 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont 719 answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
510 borderLess color cursorBlink cursorUnderline cutchars delete_key 720 borderLess color cursorBlink cursorUnderline cutchars delete_key
511 display_name embed ext_bwidth fade font geometry hold iconName 721 display_name embed ext_bwidth fade font geometry hold iconName
512 imFont imLocale inputMethod insecure int_bwidth intensityStyles 722 imFont imLocale inputMethod insecure int_bwidth intensityStyles
519 shade term_name title transparent transparent_all tripleclickwords 729 shade term_name title transparent transparent_all tripleclickwords
520 utmpInhibit visualBell 730 utmpInhibit visualBell
521 731
522=cut 732=cut
523 733
524sub urxvt::term::resource($$;$) { 734sub resource($$;$) {
525 my ($self, $name) = (shift, shift); 735 my ($self, $name) = (shift, shift);
526 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 736 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
527 goto &urxvt::term::_resource; 737 &urxvt::term::_resource
528} 738}
529 739
530=item $rend = $term->rstyle ([$new_rstyle]) 740=item $rend = $term->rstyle ([$new_rstyle])
531 741
532Return and optionally change the current rendition. Text that is output by 742Return and optionally change the current rendition. Text that is output by
608 818
609If hidden, display the overlay again. 819If hidden, display the overlay again.
610 820
611=back 821=back
612 822
823=item $popup = $term->popup ($event)
824
825Creates a new C<urxvt::popup> object that implements a popup menu. The
826C<$event> I<must> be the event causing the menu to pop up (a button event,
827currently).
828
829=cut
830
831sub popup {
832 my ($self, $event) = @_;
833
834 $self->grab ($event->{time}, 1)
835 or return;
836
837 my $popup = bless {
838 term => $self,
839 event => $event,
840 }, urxvt::popup::;
841
842 Scalar::Util::weaken $popup->{term};
843
844 $self->{_destroy}{$popup} = urxvt::destroy_hook { $popup->{popup}->destroy };
845 Scalar::Util::weaken $self->{_destroy}{$popup};
846
847 $popup
848}
849
613=item $cellwidth = $term->strwidth $string 850=item $cellwidth = $term->strwidth ($string)
614 851
615Returns the number of screen-cells this string would need. Correctly 852Returns the number of screen-cells this string would need. Correctly
616accounts for wide and combining characters. 853accounts for wide and combining characters.
617 854
618=item $octets = $term->locale_encode $string 855=item $octets = $term->locale_encode ($string)
619 856
620Convert the given text string into the corresponding locale encoding. 857Convert the given text string into the corresponding locale encoding.
621 858
622=item $string = $term->locale_decode $octets 859=item $string = $term->locale_decode ($octets)
623 860
624Convert the given locale-encoded octets into a perl string. 861Convert the given locale-encoded octets into a perl string.
625 862
626=item $term->scr_add_lines ($string) 863=item $term->scr_add_lines ($string)
627 864
632 869
633Normally its not a good idea to use this function, as programs might be 870Normally its not a good idea to use this function, as programs might be
634confused by changes in cursor position or scrolling. Its useful inside a 871confused by changes in cursor position or scrolling. Its useful inside a
635C<on_add_lines> hook, though. 872C<on_add_lines> hook, though.
636 873
874=item $term->cmd_parse ($octets)
875
876Similar to C<scr_add_lines>, but the argument must be in the
877locale-specific encoding of the terminal and can contain command sequences
878(escape codes) that will be interpreted.
879
637=item $term->tt_write ($octets) 880=item $term->tt_write ($octets)
638 881
639Write the octets given in C<$data> to the tty (i.e. as program input). To 882Write the octets given in C<$data> to the tty (i.e. as program input). To
640pass characters instead of octets, you should convert your strings first 883pass characters instead of octets, you should convert your strings first
641to the locale-specific encoding using C<< $term->locale_encode >>. 884to the locale-specific encoding using C<< $term->locale_encode >>.
642 885
886=item $windowid = $term->parent
887
888Return the window id of the toplevel window.
889
890=item $windowid = $term->vt
891
892Return the window id of the terminal window.
893
643=item $window_width = $term->width 894=item $window_width = $term->width
644 895
645=item $window_height = $term->height 896=item $window_height = $term->height
646 897
647=item $font_width = $term->fwidth 898=item $font_width = $term->fwidth
663=item $nrow_plus_saveLines = $term->total_rows 914=item $nrow_plus_saveLines = $term->total_rows
664 915
665=item $lines_in_scrollback = $term->nsaved 916=item $lines_in_scrollback = $term->nsaved
666 917
667Return various integers describing terminal characteristics. 918Return various integers describing terminal characteristics.
919
920=item $modifiermask = $term->ModLevel3Mask
921
922=item $modifiermask = $term->ModMetaMask
923
924=item $modifiermask = $term->ModNumLockMask
925
926Return the modifier masks corresponding to the "ISO Level 3 Shift" (often
927AltGr), the meta key (often Alt) and the num lock key, if applicable.
668 928
669=item $view_start = $term->view_start ([$newvalue]) 929=item $view_start = $term->view_start ([$newvalue])
670 930
671Returns the negative row number of the topmost line. Minimum value is 931Returns the negative row number of the topmost line. Minimum value is
672C<0>, which displays the normal terminal contents. Larger values scroll 932C<0>, which displays the normal terminal contents. Larger values scroll
735about the logical line that row C<$row_number> is part of. It supports the 995about the logical line that row C<$row_number> is part of. It supports the
736following methods: 996following methods:
737 997
738=over 4 998=over 4
739 999
740=item $text = $line->t 1000=item $text = $line->t ([$new_text])
741 1001
742Returns the full text of the line, similar to C<ROW_t> 1002Returns or replaces the full text of the line, similar to C<ROW_t>
743 1003
744=item $rend = $line->r 1004=item $rend = $line->r ([$new_rend])
745 1005
746Returns the full rendition array of the line, similar to C<ROW_r> 1006Returns or replaces the full rendition array of the line, similar to C<ROW_r>
747 1007
748=item $length = $line->l 1008=item $length = $line->l
749 1009
750Returns the length of the line in cells, similar to C<ROW_l>. 1010Returns the length of the line in cells, similar to C<ROW_l>.
751 1011
766 1026
767=back 1027=back
768 1028
769=cut 1029=cut
770 1030
771sub urxvt::term::line { 1031sub line {
772 my ($self, $row) = @_; 1032 my ($self, $row) = @_;
773 1033
774 my $maxrow = $self->nrow - 1; 1034 my $maxrow = $self->nrow - 1;
775 1035
776 my ($beg, $end) = ($row, $row); 1036 my ($beg, $end) = ($row, $row);
780 1040
781 bless { 1041 bless {
782 term => $self, 1042 term => $self,
783 beg => $beg, 1043 beg => $beg,
784 end => $end, 1044 end => $end,
1045 ncol => $self->ncol,
785 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end), 1046 len => ($end - $beg) * $self->ncol + $self->ROW_l ($end),
786 }, urxvt::line:: 1047 }, urxvt::line::
787} 1048}
788 1049
789sub urxvt::line::t { 1050sub urxvt::line::t {
790 my ($self) = @_; 1051 my ($self) = @_;
791 1052
1053 if (@_ > 1)
1054 {
1055 $self->{term}->ROW_t ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1056 for $self->{beg} .. $self->{end};
1057 }
1058
1059 defined wantarray &&
792 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}), 1060 substr +(join "", map $self->{term}->ROW_t ($_), $self->{beg} .. $self->{end}),
793 0, $self->{len} 1061 0, $self->{len}
794} 1062}
795 1063
796sub urxvt::line::r { 1064sub urxvt::line::r {
797 my ($self) = @_; 1065 my ($self) = @_;
798 1066
1067 if (@_ > 1)
1068 {
1069 $self->{term}->ROW_r ($_, $_[1], 0, ($_ - $self->{beg}) * $self->{ncol}, $self->{ncol})
1070 for $self->{beg} .. $self->{end};
1071 }
1072
1073 if (defined wantarray) {
799 my $rend = [ 1074 my $rend = [
800 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end} 1075 map @{ $self->{term}->ROW_r ($_) }, $self->{beg} .. $self->{end}
801 ]; 1076 ];
802 $#$rend = $self->{len} - 1; 1077 $#$rend = $self->{len} - 1;
803 $rend 1078 return $rend;
1079 }
1080
1081 ()
804} 1082}
805 1083
806sub urxvt::line::beg { $_[0]{beg} } 1084sub urxvt::line::beg { $_[0]{beg} }
807sub urxvt::line::end { $_[0]{end} } 1085sub urxvt::line::end { $_[0]{end} }
808sub urxvt::line::l { $_[0]{len} } 1086sub urxvt::line::l { $_[0]{len} }
809 1087
810sub urxvt::line::offset_of { 1088sub urxvt::line::offset_of {
811 my ($self, $row, $col) = @_; 1089 my ($self, $row, $col) = @_;
812 1090
813 ($row - $self->{beg}) * $self->{term}->ncol + $col 1091 ($row - $self->{beg}) * $self->{ncol} + $col
814} 1092}
815 1093
816sub urxvt::line::coord_of { 1094sub urxvt::line::coord_of {
817 my ($self, $offset) = @_; 1095 my ($self, $offset) = @_;
818 1096
819 use integer; 1097 use integer;
820 1098
821 ( 1099 (
822 $offset / $self->{term}->ncol + $self->{beg}, 1100 $offset / $self->{ncol} + $self->{beg},
823 $offset % $self->{term}->ncol 1101 $offset % $self->{ncol}
824 ) 1102 )
825} 1103}
826 1104
827=item ($row, $col) = $line->coord_of ($offset) 1105=item ($row, $col) = $line->coord_of ($offset)
828=item $text = $term->special_encode $string 1106=item $text = $term->special_encode $string
835 1113
836Converts rxvt-unicodes text reprsentation into a perl string. See 1114Converts rxvt-unicodes text reprsentation into a perl string. See
837C<< $term->ROW_t >> for details. 1115C<< $term->ROW_t >> for details.
838 1116
839=back 1117=back
1118
1119=cut
1120
1121package urxvt::popup;
1122
1123=head2 The C<urxvt::popup> Class
1124
1125=over 4
1126
1127=cut
1128
1129sub add_item {
1130 my ($self, $item) = @_;
1131
1132 $item->{rend}{normal} = "\x1b[0;30;47m" unless exists $item->{rend}{normal};
1133 $item->{rend}{hover} = "\x1b[0;30;46m" unless exists $item->{rend}{hover};
1134 $item->{rend}{active} = "\x1b[m" unless exists $item->{rend}{active};
1135
1136 $item->{render} ||= sub { $_[0]{text} };
1137
1138 push @{ $self->{item} }, $item;
1139}
1140
1141sub add_separator {
1142 my ($self, $sep) = @_;
1143
1144 $sep ||= "═";
1145
1146 $self->add_item ({
1147 rend => { normal => "\x1b[0;30;47m", hover => "\x1b[0;30;47m", active => "\x1b[0;30;47m" },
1148 text => "",
1149 render => sub { $sep x $urxvt::TERM->ncol },
1150 activate => sub { },
1151 });
1152}
1153
1154sub add_title {
1155 my ($self, $title) = @_;
1156
1157 $self->add_item ({
1158 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1159 text => $title,
1160 activate => sub { },
1161 });
1162}
1163
1164sub add_button {
1165 my ($self, $text, $cb) = @_;
1166
1167 $self->add_item ({ type => "button", text => "[ $text ]", activate => $cb});
1168}
1169
1170sub add_toggle {
1171 my ($self, $text, $cb, $value) = @_;
1172
1173 my $item; $item = {
1174 type => "button",
1175 text => " $text",
1176 value => $value,
1177 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1178 activate => sub { $cb->($_[0]{value} = !$_[0]{value}); },
1179 };
1180
1181 $self->add_item ($item);
1182}
1183
1184sub show {
1185 my ($self) = @_;
1186
1187 local $urxvt::popup::self = $self;
1188
1189 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1190 "--transient-for" => $self->{term}->parent,
1191 "-pe" => "urxvt-popup")
1192 or die "unable to create popup window\n";
1193}
1194
1195sub DESTROY {
1196 my ($self) = @_;
1197
1198 delete $self->{term}{_destroy}{$self};
1199 $self->{term}->ungrab;
1200}
840 1201
841=head2 The C<urxvt::timer> Class 1202=head2 The C<urxvt::timer> Class
842 1203
843This class implements timer watchers/events. Time is represented as a 1204This class implements timer watchers/events. Time is represented as a
844fractional number of seconds since the epoch. Example: 1205fractional number of seconds since the epoch. Example:
946This variable controls the verbosity level of the perl extension. Higher 1307This variable controls the verbosity level of the perl extension. Higher
947numbers indicate more verbose output. 1308numbers indicate more verbose output.
948 1309
949=over 4 1310=over 4
950 1311
951=item =0 - only fatal messages 1312=item == 0 - fatal messages
952 1313
953=item =3 - script loading and management 1314=item >= 3 - script loading and management
954 1315
955=item =10 - all events received 1316=item >=10 - all events received
956 1317
957=back 1318=back
958 1319
959=head1 AUTHOR 1320=head1 AUTHOR
960 1321

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines