| … | |
… | |
| 67 | |
67 | |
| 68 | digital-clock |
68 | digital-clock |
| 69 | Displays a digital clock using the built-in overlay. |
69 | Displays a digital clock using the built-in overlay. |
| 70 | |
70 | |
| 71 | mark-urls |
71 | mark-urls |
| 72 | Uses per-line display filtering ("on_line_update") to underline |
72 | Uses per-line display filtering ("on_line_update") to underline urls |
| 73 | urls. |
73 | and make them clickable. When clicked, the program specified in the |
|
|
74 | resource "urlLauncher" (default "x-www-browser") will be started. |
| 74 | |
75 | |
| 75 | block-graphics-to-ascii |
76 | block-graphics-to-ascii |
| 76 | A not very useful example of filtering all text output to the |
77 | A not very useful example of filtering all text output to the |
| 77 | terminal, by replacing all line-drawing characters (U+2500 .. |
78 | terminal, by replacing all line-drawing characters (U+2500 .. |
| 78 | U+259F) by a similar-looking ascii character. |
79 | U+259F) by a similar-looking ascii character. |
| … | |
… | |
| 98 | Argument names also often indicate the type of a parameter. Here are |
99 | Argument names also often indicate the type of a parameter. Here are |
| 99 | some hints on what they mean: |
100 | some hints on what they mean: |
| 100 | |
101 | |
| 101 | $text |
102 | $text |
| 102 | Rxvt-unicodes special way of encoding text, where one "unicode" |
103 | Rxvt-unicodes special way of encoding text, where one "unicode" |
| 103 | character always represents one screen cell. See row_t for a |
104 | character always represents one screen cell. See ROW_t for a |
| 104 | discussion of this format. |
105 | discussion of this format. |
| 105 | |
106 | |
| 106 | $string |
107 | $string |
| 107 | A perl text string, with an emphasis on *text*. It can store all |
108 | A perl text string, with an emphasis on *text*. It can store all |
| 108 | unicode characters and is to be distinguished with text encoded in a |
109 | unicode characters and is to be distinguished with text encoded in a |
| … | |
… | |
| 299 | |
300 | |
| 300 | $urxvt::TERM |
301 | $urxvt::TERM |
| 301 | The current terminal. This variable stores the current "urxvt::term" |
302 | The current terminal. This variable stores the current "urxvt::term" |
| 302 | object, whenever a callback/hook is executing. |
303 | object, whenever a callback/hook is executing. |
| 303 | |
304 | |
| 304 | * |
|
|
| 305 | |
|
|
| 306 | Functions in the "urxvt" Package |
305 | Functions in the "urxvt" Package |
| 307 | $term = new urxvt [arg...] |
|
|
| 308 | Creates a new terminal, very similar as if you had started it with |
|
|
| 309 | "system $binfile, arg...". Croaks (and probably outputs an error |
|
|
| 310 | message) if the new instance couldn't be created. Returns "undef" if |
|
|
| 311 | the new instance didn't initialise perl, and the terminal object |
|
|
| 312 | otherwise. The "init" and "start" hooks will be called during the |
|
|
| 313 | call. |
|
|
| 314 | |
|
|
| 315 | urxvt::fatal $errormessage |
306 | urxvt::fatal $errormessage |
| 316 | Fatally aborts execution with the given error message. Avoid at all |
307 | Fatally aborts execution with the given error message. Avoid at all |
| 317 | costs! The only time this is acceptable is when the terminal process |
308 | costs! The only time this is acceptable is when the terminal process |
| 318 | starts up. |
309 | starts up. |
| 319 | |
310 | |
| … | |
… | |
| 322 | newline. The module also overwrites the "warn" builtin with a |
313 | newline. The module also overwrites the "warn" builtin with a |
| 323 | function that calls this function. |
314 | function that calls this function. |
| 324 | |
315 | |
| 325 | Using this function has the advantage that its output ends up in the |
316 | Using this function has the advantage that its output ends up in the |
| 326 | correct place, e.g. on stderr of the connecting urxvtc client. |
317 | correct place, e.g. on stderr of the connecting urxvtc client. |
|
|
318 | |
|
|
319 | Messages have a size limit of 1023 bytes currently. |
| 327 | |
320 | |
| 328 | $is_safe = urxvt::safe |
321 | $is_safe = urxvt::safe |
| 329 | Returns true when it is safe to do potentially unsafe things, such |
322 | Returns true when it is safe to do potentially unsafe things, such |
| 330 | as evaluating perl code specified by the user. This is true when |
323 | as evaluating perl code specified by the user. This is true when |
| 331 | urxvt was started setuid or setgid. |
324 | urxvt was started setuid or setgid. |
| … | |
… | |
| 385 | condition variables, but non-blocking condvar use is ok. What this means |
378 | condition variables, but non-blocking condvar use is ok. What this means |
| 386 | is that you cannot use blocking APIs, but the non-blocking variant |
379 | is that you cannot use blocking APIs, but the non-blocking variant |
| 387 | should work. |
380 | should work. |
| 388 | |
381 | |
| 389 | The "urxvt::term" Class |
382 | The "urxvt::term" Class |
|
|
383 | $term = new urxvt::term $envhashref, $rxvtname, [arg...] |
|
|
384 | Creates a new terminal, very similar as if you had started it with |
|
|
385 | system "$rxvtname, arg...". $envhashref must be a reference to a |
|
|
386 | %ENV-like hash which defines the environment of the new terminal. |
|
|
387 | |
|
|
388 | Croaks (and probably outputs an error message) if the new instance |
|
|
389 | couldn't be created. Returns "undef" if the new instance didn't |
|
|
390 | initialise perl, and the terminal object otherwise. The "init" and |
|
|
391 | "start" hooks will be called during this call. |
|
|
392 | |
| 390 | $term->destroy |
393 | $term->destroy |
| 391 | Destroy the terminal object (close the window, free resources etc.). |
394 | Destroy the terminal object (close the window, free resources etc.). |
| 392 | Please note that rxvt will not exit as long as any event watchers |
395 | Please note that rxvt will not exit as long as any event watchers |
| 393 | (timers, io watchers) are still active. |
396 | (timers, io watchers) are still active. |
| 394 | |
397 | |
| … | |
… | |
| 439 | reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating |
442 | reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating |
| 440 | scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput |
443 | scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput |
| 441 | scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle |
444 | scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle |
| 442 | shade term_name title transparent transparent_all tripleclickwords |
445 | shade term_name title transparent transparent_all tripleclickwords |
| 443 | utmpInhibit visualBell |
446 | utmpInhibit visualBell |
|
|
447 | |
|
|
448 | $value = $term->x_resource ($pattern) |
|
|
449 | Returns the X-Resource for the given pattern, excluding the program |
|
|
450 | or class name, i.e. "$term->x_resource ("boldFont")" should return |
|
|
451 | the same value as used by this instance of rxvt-unicode. Returns |
|
|
452 | "undef" if no resource with that pattern exists. |
|
|
453 | |
|
|
454 | This method should only be called during the "on_start" hook, as |
|
|
455 | there is only one resource database per display, and later |
|
|
456 | invocations might return the wrong resources. |
| 444 | |
457 | |
| 445 | $success = $term->parse_keysym ($keysym_spec, $command_string) |
458 | $success = $term->parse_keysym ($keysym_spec, $command_string) |
| 446 | Adds a keymap translation exactly as specified via a resource. See |
459 | Adds a keymap translation exactly as specified via a resource. See |
| 447 | the "keysym" resource in the rxvt(1) manpage. |
460 | the "keysym" resource in the rxvt(1) manpage. |
| 448 | |
461 | |
| … | |
… | |
| 577 | $max_scrollback = $term->saveLines |
590 | $max_scrollback = $term->saveLines |
| 578 | $nrow_plus_saveLines = $term->total_rows |
591 | $nrow_plus_saveLines = $term->total_rows |
| 579 | $lines_in_scrollback = $term->nsaved |
592 | $lines_in_scrollback = $term->nsaved |
| 580 | Return various integers describing terminal characteristics. |
593 | Return various integers describing terminal characteristics. |
| 581 | |
594 | |
|
|
595 | $x_display = $term->display_id |
|
|
596 | Return the DISPLAY used by rxvt-unicode. |
|
|
597 | |
| 582 | $lc_ctype = $term->locale |
598 | $lc_ctype = $term->locale |
| 583 | Returns the LC_CTYPE category string used by this rxvt-unicode. |
599 | Returns the LC_CTYPE category string used by this rxvt-unicode. |
| 584 | |
600 | |
| 585 | $x_display = $term->display_id |
601 | $env = $term->env |
| 586 | Return the DISPLAY used by rxvt-unicode. |
602 | Returns a copy of the environment in effect for the terminal as a |
|
|
603 | hashref similar to "\%ENV". |
| 587 | |
604 | |
| 588 | $modifiermask = $term->ModLevel3Mask |
605 | $modifiermask = $term->ModLevel3Mask |
| 589 | $modifiermask = $term->ModMetaMask |
606 | $modifiermask = $term->ModMetaMask |
| 590 | $modifiermask = $term->ModNumLockMask |
607 | $modifiermask = $term->ModNumLockMask |
| 591 | Return the modifier masks corresponding to the "ISO Level 3 Shift" |
608 | Return the modifier masks corresponding to the "ISO Level 3 Shift" |
| … | |
… | |
| 727 | |
744 | |
| 728 | $popup->show |
745 | $popup->show |
| 729 | Displays the popup (which is initially hidden). |
746 | Displays the popup (which is initially hidden). |
| 730 | |
747 | |
| 731 | The "urxvt::timer" Class |
748 | The "urxvt::timer" Class |
| 732 | This class implements timer watchers/events. Time is represented as |
749 | This class implements timer watchers/events. Time is represented as a |
| 733 | a fractional number of seconds since the epoch. Example: |
750 | fractional number of seconds since the epoch. Example: |
| 734 | |
751 | |
| 735 | $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0); |
752 | $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0); |
| 736 | $term->{timer} = urxvt::timer |
753 | $term->{timer} = urxvt::timer |
| 737 | ->new |
754 | ->new |
| 738 | ->interval (1) |
755 | ->interval (1) |
| 739 | ->cb (sub { |
756 | ->cb (sub { |
| 740 | $term->{overlay}->set (0, 0, |
757 | $term->{overlay}->set (0, 0, |
| 741 | sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); |
758 | sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); |
| 742 | }); |
759 | }); |
| 743 | |
760 | |
| 744 | $timer = new urxvt::timer |
761 | $timer = new urxvt::timer |
| 745 | Create a new timer object in started state. It is scheduled to |
762 | Create a new timer object in started state. It is scheduled to fire |
| 746 | fire immediately. |
763 | immediately. |
| 747 | |
764 | |
| 748 | $timer = $timer->cb (sub { my ($timer) = @_; ... }) |
765 | $timer = $timer->cb (sub { my ($timer) = @_; ... }) |
| 749 | Set the callback to be called when the timer triggers. |
766 | Set the callback to be called when the timer triggers. |
| 750 | |
767 | |
| 751 | $tstamp = $timer->at |
768 | $tstamp = $timer->at |
| 752 | Return the time this watcher will fire next. |
769 | Return the time this watcher will fire next. |
| 753 | |
770 | |
| 754 | $timer = $timer->set ($tstamp) |
771 | $timer = $timer->set ($tstamp) |
| 755 | Set the time the event is generated to $tstamp. |
772 | Set the time the event is generated to $tstamp. |
| 756 | |
773 | |
| 757 | $timer = $timer->interval ($interval) |
774 | $timer = $timer->interval ($interval) |
| 758 | Normally (and when $interval is 0), the timer will automatically |
775 | Normally (and when $interval is 0), the timer will automatically |
| 759 | stop after it has fired once. If $interval is non-zero, then the |
776 | stop after it has fired once. If $interval is non-zero, then the |
| 760 | timer is automatically rescheduled at the given intervals. |
777 | timer is automatically rescheduled at the given intervals. |
| 761 | |
778 | |
| 762 | $timer = $timer->start |
779 | $timer = $timer->start |
| 763 | Start the timer. |
780 | Start the timer. |
| 764 | |
781 | |
| 765 | $timer = $timer->start ($tstamp) |
782 | $timer = $timer->start ($tstamp) |
| 766 | Set the event trigger time to $tstamp and start the timer. |
783 | Set the event trigger time to $tstamp and start the timer. |
| 767 | |
784 | |
| 768 | $timer = $timer->stop |
785 | $timer = $timer->stop |
| 769 | Stop the timer. |
786 | Stop the timer. |
| 770 | |
787 | |
| 771 | The "urxvt::iow" Class |
788 | The "urxvt::iow" Class |
| 772 | This class implements io watchers/events. Example: |
789 | This class implements io watchers/events. Example: |
| 773 | |
790 | |
| 774 | $term->{socket} = ... |
791 | $term->{socket} = ... |
| 775 | $term->{iow} = urxvt::iow |
792 | $term->{iow} = urxvt::iow |
| 776 | ->new |
793 | ->new |
| 777 | ->fd (fileno $term->{socket}) |
794 | ->fd (fileno $term->{socket}) |
| 778 | ->events (urxvt::EVENT_READ) |
795 | ->events (urxvt::EVENT_READ) |
| 779 | ->start |
796 | ->start |
| 780 | ->cb (sub { |
797 | ->cb (sub { |
| 781 | my ($iow, $revents) = @_; |
798 | my ($iow, $revents) = @_; |
| 782 | # $revents must be 1 here, no need to check |
799 | # $revents must be 1 here, no need to check |
| 783 | sysread $term->{socket}, my $buf, 8192 |
800 | sysread $term->{socket}, my $buf, 8192 |
| 784 | or end-of-file; |
801 | or end-of-file; |
| 785 | }); |
802 | }); |
| 786 | |
803 | |
| 787 | $iow = new urxvt::iow |
804 | $iow = new urxvt::iow |
| 788 | Create a new io watcher object in stopped state. |
805 | Create a new io watcher object in stopped state. |
| 789 | |
806 | |
| 790 | $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... }) |
807 | $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... }) |
| 791 | Set the callback to be called when io events are triggered. |
808 | Set the callback to be called when io events are triggered. |
| 792 | $reventmask is a bitset as described in the "events" method. |
809 | $reventmask is a bitset as described in the "events" method. |
| 793 | |
810 | |
| 794 | $iow = $iow->fd ($fd) |
811 | $iow = $iow->fd ($fd) |
| 795 | Set the filedescriptor (not handle) to watch. |
812 | Set the filedescriptor (not handle) to watch. |
| 796 | |
813 | |
| 797 | $iow = $iow->events ($eventmask) |
814 | $iow = $iow->events ($eventmask) |
| 798 | Set the event mask to watch. The only allowed values are |
815 | Set the event mask to watch. The only allowed values are |
| 799 | "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be |
816 | "urxvt::EVENT_READ" and "urxvt::EVENT_WRITE", which might be ORed |
| 800 | ORed together, or "urxvt::EVENT_NONE". |
817 | together, or "urxvt::EVENT_NONE". |
| 801 | |
818 | |
| 802 | $iow = $iow->start |
819 | $iow = $iow->start |
| 803 | Start watching for requested events on the given handle. |
820 | Start watching for requested events on the given handle. |
| 804 | |
821 | |
| 805 | $iow = $iow->stop |
822 | $iow = $iow->stop |
| 806 | Stop watching for events on the given filehandle. |
823 | Stop watching for events on the given filehandle. |
| 807 | |
824 | |
| 808 | ENVIRONMENT |
825 | ENVIRONMENT |
| 809 | URXVT_PERL_VERBOSITY |
826 | URXVT_PERL_VERBOSITY |
| 810 | This variable controls the verbosity level of the perl extension. |
827 | This variable controls the verbosity level of the perl extension. Higher |
| 811 | Higher numbers indicate more verbose output. |
828 | numbers indicate more verbose output. |
| 812 | |
829 | |
| 813 | == 0 - fatal messages |
830 | == 0 - fatal messages |
| 814 | >= 3 - script loading and management |
831 | >= 3 - script loading and management |
| 815 | >=10 - all events received |
832 | >=10 - all events received |
| 816 | |
833 | |
| 817 | AUTHOR |
834 | AUTHOR |
| 818 | Marc Lehmann <pcg@goof.com> |
835 | Marc Lehmann <pcg@goof.com> |
| 819 | http://software.schmorp.de/pkg/rxvt-unicode |
836 | http://software.schmorp.de/pkg/rxvt-unicode |
| 820 | |
837 | |
