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.72 by root, Mon Jan 9 23:30:01 2006 UTC vs.
Revision 1.81 by root, Thu Jan 12 00:12:40 2006 UTC

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
29scripts will be shared (but not enabled) for all terminals. 29scripts will be shared (but not enabled) for all terminals.
30 30
31=head2 Prepackaged Extensions 31=head1 PREPACKAGED EXTENSIONS
32 32
33This section describes the extensiosn delivered with this version. You can 33This section describes the extensions delivered with this release. You can
34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 34find them in F<@@RXVT_LIBDIR@@/urxvt/perl/>.
35 35
36You can activate them like this: 36You can activate them like this:
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 (enabled by default) 42=item selection (enabled by default)
43 43
44Intelligent selection. This extension tries to be more intelligent when 44(More) intelligent selection. This extension tries to be more intelligent
45the user extends selections (double-click). Right now, it tries to select 45when the user extends selections (double-click). Right now, it tries to
46urls and complete shell-quoted arguments, which is very convenient, too, 46select urls and complete shell-quoted arguments, which is very convenient,
47if your F<ls> supports C<--quoting-style=shell>. 47too, if your F<ls> supports C<--quoting-style=shell>.
48 48
49It also offers the following bindable event: 49It also offers the following bindable keyboard command:
50 50
51=over 4 51=over 4
52 52
53=item rot13 53=item rot13
54 54
64runtime. 64runtime.
65 65
66=item selection-popup (enabled by default) 66=item selection-popup (enabled by default)
67 67
68Binds a popup menu to Ctrl-Button3 that lets you convert the selection 68Binds a popup menu to Ctrl-Button3 that lets you convert the selection
69text into various other formats/action. 69text into various other formats/action (such as uri unescaping, perl
70evalution, web-browser starting etc.), depending on content.
70 71
71=item searchable-scrollback (enabled by default) 72=item searchable-scrollback<hotkey> (enabled by default)
72 73
73Adds regex search functionality to the scrollback buffer, triggered by a 74Adds regex search functionality to the scrollback buffer, triggered
74hotkey (default: C<M-s>). When in search mode, terminal input/output is 75by a hotkey (default: C<M-s>). When in search mode, normal terminal
76input/output is suspended.
77
75suspended, C</> starts an incremental regex search, C<n> searches further, 78C</> starts an incremental regex search, C<n> searches further, C<p> or
76C<p> jumps to the previous match. C<enter> leaves search mode at the 79C<N> jump to the previous match, C<G> jumps to the bottom and clears the
77current position and C<escape> returns to the original position. 80history, C<enter> leaves search mode at the current position and C<escape>
81returns to the original position.
78 82
79=item digital-clock 83=item digital-clock
80 84
81Displays a digital clock using the built-in overlay. 85Displays a digital clock using the built-in overlay.
82 86
83=item mark-urls 87=item mark-urls
84 88
85Uses per-line display filtering (C<on_line_update>) to underline urls. 89Uses per-line display filtering (C<on_line_update>) to underline urls and
90make them clickable. When clicked, the program specified in the resource
91C<urlLauncher> (default C<x-www-browser>) will be started.
86 92
87=item block-graphics-to-ascii 93=item block-graphics-to-ascii
88 94
89A not very useful example of filtering all text output to the terminal, 95A not very useful example of filtering all text output to the terminal,
90by replacing all line-drawing characters (U+2500 .. U+259F) by a 96by replacing all line-drawing characters (U+2500 .. U+259F) by a
95Displays a very simple digital clock in the upper right corner of the 101Displays a very simple digital clock in the upper right corner of the
96window. Illustrates overwriting the refresh callbacks to create your own 102window. Illustrates overwriting the refresh callbacks to create your own
97overlays or changes. 103overlays or changes.
98 104
99=back 105=back
106
107=head1 API DOCUMENTATION
100 108
101=head2 General API Considerations 109=head2 General API Considerations
102 110
103All objects (such as terminals, time watchers etc.) are typical 111All objects (such as terminals, time watchers etc.) are typical
104reference-to-hash objects. The hash can be used to store anything you 112reference-to-hash objects. The hash can be used to store anything you
117=over 4 125=over 4
118 126
119=item $text 127=item $text
120 128
121Rxvt-unicodes special way of encoding text, where one "unicode" character 129Rxvt-unicodes special way of encoding text, where one "unicode" character
122always represents one screen cell. See L<row_t> for a discussion of this format. 130always represents one screen cell. See L<ROW_t> for a discussion of this format.
123 131
124=item $string 132=item $string
125 133
126A perl text string, with an emphasis on I<text>. It can store all unicode 134A perl text string, with an emphasis on I<text>. It can store all unicode
127characters and is to be distinguished with text encoded in a specific 135characters and is to be distinguished with text encoded in a specific
337 345
338subwindow. 346subwindow.
339 347
340=back 348=back
341 349
342=head2 Variables in the C<urxvt> Package
343
344=over 4
345
346=item $urxvt::TERM
347
348The current terminal. This variable stores the current C<urxvt::term>
349object, whenever a callback/hook is executing.
350
351=back
352
353=head2 Functions in the C<urxvt> Package
354
355=over 4
356
357=item $term = new urxvt [arg...]
358
359Creates a new terminal, very similar as if you had started it with
360C<system $binfile, arg...>. Croaks (and probably outputs an error message)
361if the new instance couldn't be created. Returns C<undef> if the new
362instance didn't initialise perl, and the terminal object otherwise. The
363C<init> and C<start> hooks will be called during the call.
364
365=item urxvt::fatal $errormessage
366
367Fatally aborts execution with the given error message. Avoid at all
368costs! The only time this is acceptable is when the terminal process
369starts up.
370
371=item urxvt::warn $string
372
373Calls C<rxvt_warn> with the given string which should not include a
374newline. The module also overwrites the C<warn> builtin with a function
375that calls this function.
376
377Using this function has the advantage that its output ends up in the
378correct place, e.g. on stderr of the connecting urxvtc client.
379
380=item $is_safe = urxvt::safe
381
382Returns true when it is safe to do potentially unsafe things, such as
383evaluating perl code specified by the user. This is true when urxvt was
384started setuid or setgid.
385
386=item $time = urxvt::NOW
387
388Returns the "current time" (as per the event loop).
389
390=item urxvt::CurrentTime
391
392=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
393Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
394Button4Mask, Button5Mask, AnyModifier
395
396Various constants for use in X calls and event processing.
397
398=back
399
400=head2 RENDITION
401
402Rendition bitsets contain information about colour, font, font styles and
403similar information for each screen cell.
404
405The following "macros" deal with changes in rendition sets. You should
406never just create a bitset, you should always modify an existing one,
407as they contain important information required for correct operation of
408rxvt-unicode.
409
410=over 4
411
412=item $rend = urxvt::DEFAULT_RSTYLE
413
414Returns the default rendition, as used when the terminal is starting up or
415being reset. Useful as a base to start when creating renditions.
416
417=item $rend = urxvt::OVERLAY_RSTYLE
418
419Return the rendition mask used for overlays by default.
420
421=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
422
423Return the bit that enabled bold, italic, blink, reverse-video and
424underline, respectively. To enable such a style, just logically OR it into
425the bitset.
426
427=item $foreground = urxvt::GET_BASEFG $rend
428
429=item $background = urxvt::GET_BASEBG $rend
430
431Return the foreground/background colour index, respectively.
432
433=item $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
434
435=item $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
436
437Replace the foreground/background colour in the rendition mask with the
438specified one.
439
440=item $value = urxvt::GET_CUSTOM ($rend)
441
442Return the "custom" value: Every rendition has 5 bits for use by
443extensions. They can be set and changed as you like and are initially
444zero.
445
446=item $rend = urxvt::SET_CUSTOM ($rend, $new_value)
447
448Change the custom value.
449
450=back
451
452=cut 350=cut
453 351
454package urxvt; 352package urxvt;
455 353
456use utf8; 354use utf8;
462our $VERSION = 1; 360our $VERSION = 1;
463our $TERM; 361our $TERM;
464our @HOOKNAME; 362our @HOOKNAME;
465our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME; 363our %HOOKTYPE = map +($HOOKNAME[$_] => $_), 0..$#HOOKNAME;
466our %OPTION; 364our %OPTION;
365
467our $LIBDIR; 366our $LIBDIR;
367our $RESNAME;
368our $RESCLASS;
369our $RXVTNAME;
370
371=head2 Variables in the C<urxvt> Package
372
373=over 4
374
375=item $urxvt::LIBDIR
376
377The rxvt-unicode library directory, where, among other things, the perl
378modules and scripts are stored.
379
380=item $urxvt::RESCLASS, $urxvt::RESCLASS
381
382The resource class and name rxvt-unicode uses to look up X resources.
383
384=item $urxvt::RXVTNAME
385
386The basename of the installed binaries, usually C<urxvt>.
387
388=item $urxvt::TERM
389
390The current terminal. This variable stores the current C<urxvt::term>
391object, whenever a callback/hook is executing.
392
393=back
394
395=head2 Functions in the C<urxvt> Package
396
397=over 4
398
399=item urxvt::fatal $errormessage
400
401Fatally aborts execution with the given error message. Avoid at all
402costs! The only time this is acceptable is when the terminal process
403starts up.
404
405=item urxvt::warn $string
406
407Calls C<rxvt_warn> with the given string which should not include a
408newline. The module also overwrites the C<warn> builtin with a function
409that calls this function.
410
411Using this function has the advantage that its output ends up in the
412correct place, e.g. on stderr of the connecting urxvtc client.
413
414Messages have a size limit of 1023 bytes currently.
415
416=item $is_safe = urxvt::safe
417
418Returns true when it is safe to do potentially unsafe things, such as
419evaluating perl code specified by the user. This is true when urxvt was
420started setuid or setgid.
421
422=item $time = urxvt::NOW
423
424Returns the "current time" (as per the event loop).
425
426=item urxvt::CurrentTime
427
428=item urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask,
429Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask,
430Button4Mask, Button5Mask, AnyModifier
431
432Various constants for use in X calls and event processing.
433
434=back
435
436=head2 RENDITION
437
438Rendition bitsets contain information about colour, font, font styles and
439similar information for each screen cell.
440
441The following "macros" deal with changes in rendition sets. You should
442never just create a bitset, you should always modify an existing one,
443as they contain important information required for correct operation of
444rxvt-unicode.
445
446=over 4
447
448=item $rend = urxvt::DEFAULT_RSTYLE
449
450Returns the default rendition, as used when the terminal is starting up or
451being reset. Useful as a base to start when creating renditions.
452
453=item $rend = urxvt::OVERLAY_RSTYLE
454
455Return the rendition mask used for overlays by default.
456
457=item $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
458
459Return the bit that enabled bold, italic, blink, reverse-video and
460underline, respectively. To enable such a style, just logically OR it into
461the bitset.
462
463=item $foreground = urxvt::GET_BASEFG $rend
464
465=item $background = urxvt::GET_BASEBG $rend
466
467Return the foreground/background colour index, respectively.
468
469=item $rend = urxvt::SET_FGCOLOR $rend, $new_colour
470
471=item $rend = urxvt::SET_BGCOLOR $rend, $new_colour
472
473Replace the foreground/background colour in the rendition mask with the
474specified one.
475
476=item $value = urxvt::GET_CUSTOM $rend
477
478Return the "custom" value: Every rendition has 5 bits for use by
479extensions. They can be set and changed as you like and are initially
480zero.
481
482=item $rend = urxvt::SET_CUSTOM $rend, $new_value
483
484Change the custom value.
485
486=back
487
488=cut
468 489
469BEGIN { 490BEGIN {
470 urxvt->bootstrap; 491 urxvt->bootstrap;
471 492
472 # overwrite perl's warn 493 # overwrite perl's warn
668 689
669=head2 The C<urxvt::anyevent> Class 690=head2 The C<urxvt::anyevent> Class
670 691
671The sole purpose of this class is to deliver an interface to the 692The sole purpose of this class is to deliver an interface to the
672C<AnyEvent> module - any module using it will work inside urxvt without 693C<AnyEvent> module - any module using it will work inside urxvt without
673further work. The only exception is that you cannot wait on condition 694further programming. The only exception is that you cannot wait on
674variables, but non-blocking condvar use is ok. What this means is that you 695condition variables, but non-blocking condvar use is ok. What this means
675cannot use blocking APIs, but the non-blocking variant should work. 696is that you cannot use blocking APIs, but the non-blocking variant should
697work.
676 698
677=cut 699=cut
678 700
679our $VERSION = 1; 701our $VERSION = 1;
680 702
757 $proxy->enable ($name => $ref); 779 $proxy->enable ($name => $ref);
758 } 780 }
759 } 781 }
760} 782}
761 783
784=item $term = new urxvt::term $envhashref, $rxvtname, [arg...]
785
786Creates a new terminal, very similar as if you had started it with system
787C<$rxvtname, arg...>. C<$envhashref> must be a reference to a C<%ENV>-like
788hash which defines the environment of the new terminal.
789
790Croaks (and probably outputs an error message) if the new instance
791couldn't be created. Returns C<undef> if the new instance didn't
792initialise perl, and the terminal object otherwise. The C<init> and
793C<start> hooks will be called during this call.
794
795=cut
796
797sub new {
798 my ($class, $env, @args) = @_;
799
800 _new ([ map "$_=$env->{$_}", keys %$env ], @args);
801}
802
762=item $term->destroy 803=item $term->destroy
763 804
764Destroy the terminal object (close the window, free resources etc.). 805Destroy the terminal object (close the window, free resources
806etc.). Please note that @@RXVT_NAME@@ will not exit as long as any event
807watchers (timers, io watchers) are still active.
765 808
766=item $isset = $term->option ($optval[, $set]) 809=item $isset = $term->option ($optval[, $set])
767 810
768Returns true if the option specified by C<$optval> is enabled, and 811Returns true if the option specified by C<$optval> is enabled, and
769optionally change it. All option values are stored by name in the hash 812optionally change it. All option values are stored by name in the hash
819 my ($self, $name) = (shift, shift); 862 my ($self, $name) = (shift, shift);
820 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0); 863 unshift @_, $self, $name, ($name =~ s/\s*\+\s*(\d+)$// ? $1 : 0);
821 &urxvt::term::_resource 864 &urxvt::term::_resource
822} 865}
823 866
867=item $value = $term->x_resource ($pattern)
868
869Returns the X-Resource for the given pattern, excluding the program or
870class name, i.e. C<< $term->x_resource ("boldFont") >> should return the
871same value as used by this instance of rxvt-unicode. Returns C<undef> if no
872resource with that pattern exists.
873
874This method should only be called during the C<on_start> hook, as there is
875only one resource database per display, and later invocations might return
876the wrong resources.
877
824=item $success = $term->parse_keysym ($keysym_spec, $command_string) 878=item $success = $term->parse_keysym ($keysym_spec, $command_string)
825 879
826Adds a keymap translation exactly as specified via a resource. See the 880Adds a keymap translation exactly as specified via a resource. See the
827C<keysym> resource in the @@RXVT_NAME@@(1) manpage. 881C<keysym> resource in the @@RXVT_NAME@@(1) manpage.
828 882
1027 1081
1028=item $lines_in_scrollback = $term->nsaved 1082=item $lines_in_scrollback = $term->nsaved
1029 1083
1030Return various integers describing terminal characteristics. 1084Return various integers describing terminal characteristics.
1031 1085
1086=item $x_display = $term->display_id
1087
1088Return the DISPLAY used by rxvt-unicode.
1089
1032=item $lc_ctype = $term->locale 1090=item $lc_ctype = $term->locale
1033 1091
1034Returns the LC_CTYPE category string used by this rxvt-unicode. 1092Returns the LC_CTYPE category string used by this rxvt-unicode.
1035 1093
1036=item $x_display = $term->display_id 1094=item $env = $term->env
1037 1095
1038Return the DISPLAY used by rxvt-unicode. 1096Returns a copy of the environment in effect for the terminal as a hashref
1097similar to C<\%ENV>.
1098
1099=cut
1100
1101sub env {
1102 if (my $env = $_[0]->_env) {
1103 +{ map /^([^=]+)(?:=(.*))?$/s && ($1 => $2), @$env }
1104 } else {
1105 +{ %ENV }
1106 }
1107}
1039 1108
1040=item $modifiermask = $term->ModLevel3Mask 1109=item $modifiermask = $term->ModLevel3Mask
1041 1110
1042=item $modifiermask = $term->ModMetaMask 1111=item $modifiermask = $term->ModMetaMask
1043 1112
1283 $item->{render} ||= sub { $_[0]{text} }; 1352 $item->{render} ||= sub { $_[0]{text} };
1284 1353
1285 push @{ $self->{item} }, $item; 1354 push @{ $self->{item} }, $item;
1286} 1355}
1287 1356
1357=item $popup->add_title ($title)
1358
1359Adds a non-clickable title to the popup.
1360
1361=cut
1362
1363sub add_title {
1364 my ($self, $title) = @_;
1365
1366 $self->add_item ({
1367 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" },
1368 text => $title,
1369 activate => sub { },
1370 });
1371}
1372
1373=item $popup->add_separator ([$sepchr])
1374
1375Creates a separator, optionally using the character given as C<$sepchr>.
1376
1377=cut
1378
1288sub add_separator { 1379sub add_separator {
1289 my ($self, $sep) = @_; 1380 my ($self, $sep) = @_;
1290 1381
1291 $sep ||= "="; 1382 $sep ||= "=";
1292 1383
1296 render => sub { $sep x $self->{term}->ncol }, 1387 render => sub { $sep x $self->{term}->ncol },
1297 activate => sub { }, 1388 activate => sub { },
1298 }); 1389 });
1299} 1390}
1300 1391
1301sub add_title { 1392=item $popup->add_button ($text, $cb)
1302 my ($self, $title) = @_;
1303 1393
1304 $self->add_item ({ 1394Adds a clickable button to the popup. C<$cb> is called whenever it is
1305 rend => { normal => "\x1b[38;5;11;44m", hover => "\x1b[38;5;11;44m", active => "\x1b[38;5;11;44m" }, 1395selected.
1306 text => $title, 1396
1307 activate => sub { }, 1397=cut
1308 });
1309}
1310 1398
1311sub add_button { 1399sub add_button {
1312 my ($self, $text, $cb) = @_; 1400 my ($self, $text, $cb) = @_;
1313 1401
1314 $self->add_item ({ type => "button", text => $text, activate => $cb}); 1402 $self->add_item ({ type => "button", text => $text, activate => $cb});
1315} 1403}
1404
1405=item $popup->add_toggle ($text, $cb, $initial_value)
1406
1407Adds a toggle/checkbox item to the popup. Teh callback gets called
1408whenever it gets toggled, with a boolean indicating its value as its first
1409argument.
1410
1411=cut
1316 1412
1317sub add_toggle { 1413sub add_toggle {
1318 my ($self, $text, $cb, $value) = @_; 1414 my ($self, $text, $cb, $value) = @_;
1319 1415
1320 my $item; $item = { 1416 my $item; $item = {
1321 type => "button", 1417 type => "button",
1322 text => " $text", 1418 text => " $text",
1323 value => $value, 1419 value => $value,
1324 render => sub { ($_[0]{value} ? "* " : " ") . $text }, 1420 render => sub { ($_[0]{value} ? "* " : " ") . $text },
1325 activate => sub { $cb->($_[0]{value} = !$_[0]{value}); }, 1421 activate => sub { $cb->($_[1]{value} = !$_[1]{value}); },
1326 }; 1422 };
1327 1423
1328 $self->add_item ($item); 1424 $self->add_item ($item);
1329} 1425}
1426
1427=item $popup->show
1428
1429Displays the popup (which is initially hidden).
1430
1431=cut
1330 1432
1331sub show { 1433sub show {
1332 my ($self) = @_; 1434 my ($self) = @_;
1333 1435
1334 local $urxvt::popup::self = $self; 1436 local $urxvt::popup::self = $self;
1335 1437
1438 my $env = $self->{term}->env;
1439 # we can't hope to reproduce the locale algorithm, so nuke LC_ALL and set LC_CTYPE.
1440 delete $env->{LC_ALL};
1336 local $ENV{LC_ALL} = $self->{term}->locale; 1441 $env->{LC_CTYPE} = $self->{term}->locale;
1337 1442
1443 urxvt::term->new ($env, $self->{term}->resource ("name"),
1338 urxvt->new ("--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0, 1444 "--perl-lib" => "", "--perl-ext-common" => "", "-pty-fd" => -1, "-sl" => 0, "-b" => 0,
1339 "--transient-for" => $self->{term}->parent, 1445 "--transient-for" => $self->{term}->parent,
1340 "-display" => $self->{term}->display_id, 1446 "-display" => $self->{term}->display_id,
1341 "-pe" => "urxvt-popup") 1447 "-pe" => "urxvt-popup")
1342 or die "unable to create popup window\n"; 1448 or die "unable to create popup window\n";
1343} 1449}
1344 1450
1345sub DESTROY { 1451sub DESTROY {
1346 my ($self) = @_; 1452 my ($self) = @_;
1347 1453
1348 delete $self->{term}{_destroy}{$self}; 1454 delete $self->{term}{_destroy}{$self};
1349 $self->{term}->ungrab; 1455 $self->{term}->ungrab;
1350} 1456}
1457
1458=back
1351 1459
1352=head2 The C<urxvt::timer> Class 1460=head2 The C<urxvt::timer> Class
1353 1461
1354This class implements timer watchers/events. Time is represented as a 1462This class implements timer watchers/events. Time is represented as a
1355fractional number of seconds since the epoch. Example: 1463fractional number of seconds since the epoch. Example:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines