--- rxvt-unicode/doc/rxvtperl.3.html 2006/01/03 21:15:22 1.9 +++ rxvt-unicode/doc/rxvtperl.3.html 2006/01/18 09:40:53 1.32 @@ -15,15 +15,19 @@
  • NAME
  • SYNOPSIS
  • DESCRIPTION
    • +
  • PREPACKAGED EXTENSIONS
    • +
  • API DOCUMENTATION
    • @@ -63,29 +67,62 @@

    DESCRIPTION

    -

    Everytime a terminal object gets created, scripts specified via the -perl resource are loaded and associated with it.

    +

    Everytime a terminal object gets created, extension scripts specified via +the perl resource are loaded and associated with it.

    Scripts are compiled in a 'use strict' and 'use utf8' environment, and thus must be encoded as UTF-8.

    Each script will only ever be loaded once, even in rxvtd, where scripts will be shared (but not enabled) for all terminals.

    -

    Prepackaged Extensions

    -

    This section describes the extensiosn delivered with this version. You can +

    +

    PREPACKAGED EXTENSIONS

    +

    This section describes the extensions delivered with this release. You can find them in /opt/rxvt/lib/urxvt/perl/.

    You can activate them like this:

       rxvt -pe <extensionname>
    -
    selection
    +
    selection (enabled by default)
    -Intelligent selection. This etxension tries to be more intelligent when the user -extends selections (double-click). +(More) intelligent selection. This extension tries to be more intelligent +when the user extends selections (double-click and further clicks). Right +now, it tries to select words, urls and complete shell-quoted +arguments, which is very convenient, too, if your ls supports +--quoting-style=shell. +
    +
    +

    A double-click usually selects the word under the cursor, further clicks +will enlarge the selection.

    +
    +
    +

    The selection works by trying to match a number of regexes and displaying +them in increasing order of length. You can add your own regexes by +specifying resources of the form:

    +
    +
    +
    +   URxvt.selection.pattern-0: perl-regex
+   URxvt.selection.pattern-1: perl-regex
+   ...
    +
    +
    +

    The index number (0, 1...) must not have any holes, and each regex must +contain at least one pair of capturing parentheses, which will be used for +the match. For example, the followign adds a regex that matches everything +between two vertical bars:

    +
    +
    +
    +   URxvt.selection.pattern-0: \\|([^|]+)\\|
    +
    +
    +

    You can look at the source of the selection extension to see more +interesting uses, such as parsing a line from beginning to end.

    -

    It also offers the following bindable event:

    +

    This extension also offers following bindable keyboard commands:

    rot13
    @@ -98,6 +135,107 @@ URxvt.keysym.C-M-r: perl:selection:rot13

    +
    option-popup (enabled by default)
    +
    +
    +Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at +runtime. +
    +

    +
    selection-popup (enabled by default)
    +
    +
    +Binds a popup menu to Ctrl-Button3 that lets you convert the selection +text into various other formats/action (such as uri unescaping, perl +evalution, web-browser starting etc.), depending on content. +
    +

    +
    searchable-scrollback<hotkey> (enabled by default)
    +
    +
    +Adds regex search functionality to the scrollback buffer, triggered +by a hotkey (default: M-s). While in search mode, normal terminal +input/output is suspended and a regex is displayed at the bottom of the +screen. +
    +
    +

    Inputting characters appends them to the regex and continues incremental +search. BackSpace removes a character from the regex, Up and Down +search upwards/downwards in the scrollback buffer, End jumps to the +bottom. Escape leaves search mode and returns to the point where search +was started, while Enter or Return stay at the current position and +additionally stores the first match in the current line into the primary +selection.

    +
    +

    +
    selection-autotransform
    +
    +
    +This selection allows you to do automatic transforms on a selection +whenever a selection is made. +
    +
    +

    It works by specifying perl snippets (most useful is a single s/// +operator) that modify $_ as resources:

    +
    +
    +
    +   URxvt.selection-autotransform.0: transform
+   URxvt.selection-autotransform.1: transform
+   ...
    +
    +
    +

    For example, the following will transform selections of the form +filename:number, often seen in compiler messages, into vi +$filename +$word:

    +
    +
    +
    +   URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
    +
    +
    +

    And this example matches the same,but replaces it with vi-commands you can +paste directly into your (vi :) editor:

    +
    +
    +
    +   URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/\\x1b:e \\Q$1\\E\\x0d:$2\\x0d/
    +
    +
    +

    Of course, this can be modified to suit your needs and your editor :)

    +
    +
    +

    To expand the example above to typical perl error messages (``XXX at +FILENAME line YYY.''), you need a slightly more elaborate solution:

    +
    +
    +
    +   URxvt.selection.pattern-0: ( at .*? line \\d+\\.)
+   URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)\\.$/\x1b:e \\Q$1\E\\x0d:$2\\x0d/
    +
    +
    +

    The first line tells the selection code to treat the unchanging part of +every error message as a selection pattern, and the second line transforms +the message into vi commands to load the file.

    +
    +

    +
    mark-urls
    +
    +
    +Uses per-line display filtering (on_line_update) to underline urls and +make them clickable. When middle-clicked, the program specified in the +resource urlLauncher (default x-www-browser) will be started with +the URL as first argument. +
    +

    +
    block-graphics-to-ascii
    +
    +
    +A not very useful example of filtering all text output to the terminal, +by replacing all line-drawing characters (U+2500 .. U+259F) by a +similar-looking ascii character. +
    +

    digital-clock
    @@ -111,9 +249,55 @@ window. Illustrates overwriting the refresh callbacks to create your own overlays or changes.
    +

    +
    selection-pastebin
    +
    +
    +This is a little rarely useful extension that Uploads the selection as +textfile to a remote site (or does other things). (The implementation is +not currently secure for use in a multiuser environment as it writes to +/tmp directly.). +
    +
    +

    It listens to the selection-pastebin:remote-pastebin keyboard command, +i.e.

    +
    +
    +
    +   URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
    +
    +
    +

    Pressing this combination runs a command with % replaced by the name of +the textfile. This command can be set via a resource:

    +
    +
    +
    +   URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
    +
    +
    +

    And the default is likely not useful to anybody but the few people around +here :)

    +
    +
    +

    The name of the textfile is the hex encoded md5 sum of the selection, so +the same content should lead to the same filename.

    +
    +
    +

    After a successful upload the selection will be replaced by the text given +in the selection-pastebin-url resource (again, the % is the placeholder +for the filename):

    +
    +
    +
    +   URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
    +

    +
    +

    API DOCUMENTATION

    +

    +

    General API Considerations

    All objects (such as terminals, time watchers etc.) are typical reference-to-hash objects. The hash can be used to store anything you @@ -124,26 +308,85 @@ emptied, so its best to store related objects such as time watchers and the like inside the terminal object so they get destroyed as soon as the terminal is destroyed.

    +

    Argument names also often indicate the type of a parameter. Here are some +hints on what they mean:

    +
    +
    $text
    +
    +
    +Rxvt-unicodes special way of encoding text, where one ``unicode'' character +always represents one screen cell. See ROW_t for a discussion of this format. +
    +

    +
    $string
    +
    +
    +A perl text string, with an emphasis on text. It can store all unicode +characters and is to be distinguished with text encoded in a specific +encoding (often locale-specific) and binary data. +
    +

    +
    $octets
    +
    +
    +Either binary data or - more common - a text string encoded in a +locale-specific way. +
    +

    +

    +

    +

    Extension Objects

    +

    Very perl extension is a perl class. A separate perl object is created +for each terminal and each extension and passed as the first parameter to +hooks. So extensions can use their $self object without having to think +about other extensions, with the exception of methods and members that +begin with an underscore character _: these are reserved for internal +use.

    +

    Although it isn't a urxvt::term object, you can call all methods of the +urxvt::term class on this object.

    +

    It has the following methods and data members:

    +
    +
    $urxvt_term = $self->{term}
    +
    +
    +Returns the urxvt::term object associated with this instance of the +extension. This member must not be changed in any way. +
    +

    +
    $self->enable ($hook_name => $cb, [$hook_name => $cb..])
    +
    +
    +Dynamically enable the given hooks (named without the on_ prefix) for +this extension, replacing any previous hook. This is useful when you want +to overwrite time-critical hooks only temporarily. +
    +

    +
    $self->disable ($hook_name[, $hook_name..])
    +
    +
    +Dynamically disable the given hooks. +
    +

    Hooks

    -

    The following subroutines can be declared in loaded scripts, and will be +

    The following subroutines can be declared in extension files, and will be called whenever the relevant event happens.

    -

    The first argument passed to them is an object private to each terminal -and extension package. You can call all urxvt::term methods on it, but -its not a real urxvt::term object. Instead, the real urxvt::term -object that is shared between all packages is stored in the term -member.

    -

    All of them must return a boolean value. If it is true, then the event -counts as being consumed, and the invocation of other hooks is skipped, -and the relevant action might not be carried out by the C++ code.

    -

    When in doubt, return a false value (preferably ()).

    +

    The first argument passed to them is an extension oject as described in +the in the Extension Objects section.

    +

    All of these hooks must return a boolean value. If it is true, then the +event counts as being consumed, and the invocation of other hooks is +skipped, and the relevant action might not be carried out by the C++ code.

    +

    When in doubt, return a false value (preferably ()). >

    on_init $term
    Called after a new terminal object has been initialized, but before -windows are created or the command gets run. +windows are created or the command gets run. Most methods are unsafe to +call or deliver senseless data, as terminal size and other characteristics +have not yet been determined. You can safely query and change resources, +though.

    on_reset $term
    @@ -190,26 +433,14 @@ Called whenever the user tries to extend the selection (e.g. with a double click) and is either supposed to return false (normal operation), or should extend the selection itelf and return true to suppress the built-in -processing. +processing. This can happen multiple times, as long as the callback +returns true, it will be called on every further click by the user and is +supposed to enlarge the selection more and more, if possible.

    See the selection example extension.

    -
    on_focus_in $term
    -
    -
    -Called whenever the window gets the keyboard focus, before urxvt does -focus in processing. -
    -

    -
    on_focus_out $term
    -
    -
    -Called wheneever the window loses keyboard focus, before urxvt does focus -out processing. -
    -

    on_view_change $term, $offset
    @@ -231,10 +462,55 @@ number of lines that will be in the scrollback buffer.

    -
    on_tty_activity $term *NYI*
    +
    on_osc_seq $term, $string
    -Called whenever the program(s) running in the urxvt window send output. +Called whenever the ESC ] 777 ; string ST command sequence (OSC = +operating system command) is processed. Cursor position and other state +information is up-to-date when this happens. For interoperability, the +string should start with the extension name and a colon, to distinguish +it from commands for other extensions, and this might be enforced in the +future. +
    +
    +

    Be careful not ever to trust (in a security sense) the data you receive, +as its source can not easily be controleld (e-mail content, messages from +other users on the same system etc.).

    +
    +

    +
    on_add_lines $term, $string
    +
    +
    +Called whenever text is about to be output, with the text as argument. You +can filter/change and output the text yourself by returning a true value +and calling $term->scr_add_lines yourself. Please note that this +might be very slow, however, as your hook is called for all text being +output. +
    +

    +
    on_tt_write $term, $octets
    +
    +
    +Called whenever some data is written to the tty/pty and can be used to +suppress or filter tty input. +
    +

    +
    on_line_update $term, $row
    +
    +
    +Called whenever a line was updated or changed. Can be used to filter +screen output (e.g. underline urls or other useless stuff). Only lines +that are being shown will be filtered, and, due to performance reasons, +not always immediately. +
    +
    +

    The row number is always the topmost row of the line if the line spans +multiple rows.

    +
    +
    +

    Please note that, if you change the line, then the hook might get called +later with the already-modified line (e.g. if unrelated parts change), so +you cannot just toggle rendition bits, but only set them.

    on_refresh_begin $term
    @@ -259,16 +535,88 @@ perl:string action bound to it (see description of the keysym resource in the rxvt(1) manpage). +

    +
    on_x_event $term, $event
    +
    +
    +Called on every X event received on the vt window (and possibly other +windows). Should only be used as a last resort. Most event structure +members are not passed. +
    +

    +
    on_focus_in $term
    +
    +
    +Called whenever the window gets the keyboard focus, before rxvt-unicode +does focus in processing. +
    +

    +
    on_focus_out $term
    +
    +
    +Called wheneever the window loses keyboard focus, before rxvt-unicode does +focus out processing. +
    +

    +
    on_key_press $term, $event, $keysym, $octets
    +
    +
    on_key_release $term, $event, $keysym
    +
    +
    on_button_press $term, $event
    +
    +
    on_button_release $term, $event
    +
    +
    on_motion_notify $term, $event
    +
    +
    on_map_notify $term, $event
    +
    +
    on_unmap_notify $term, $event
    +
    +
    +Called whenever the corresponding X event is received for the terminal If +the hook returns true, then the even will be ignored by rxvt-unicode. +
    +
    +

    The event is a hash with most values as named by Xlib (see the XEvent +manpage), with the additional members row and col, which are the row +and column under the mouse cursor.

    +
    +
    +

    on_key_press additionally receives the string rxvt-unicode would +output, if any, in locale-specific encoding.

    +
    +
    +

    subwindow.

    +

    Variables in the urxvt Package

    +
    $urxvt::LIBDIR
    +
    +
    +The rxvt-unicode library directory, where, among other things, the perl +modules and scripts are stored. +
    +

    +
    $urxvt::RESCLASS, $urxvt::RESCLASS
    +
    +
    +The resource class and name rxvt-unicode uses to look up X resources. +
    +

    +
    $urxvt::RXVTNAME
    +
    +
    +The basename of the installed binaries, usually urxvt. +
    +

    $urxvt::TERM
    -The current terminal. Whenever a callback/Hook is bein executed, this -variable stores the current urxvt::term object. +The current terminal. This variable stores the current urxvt::term +object, whenever a callback/hook is executing.

    @@ -294,12 +642,41 @@

    Using this function has the advantage that its output ends up in the correct place, e.g. on stderr of the connecting urxvtc client.

    +
    +

    Messages have a size limit of 1023 bytes currently.

    +

    $time = urxvt::NOW
    Returns the ``current time'' (as per the event loop).
    +

    +
    urxvt::CurrentTime
    +
    +
    urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, +Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, +Button4Mask, Button5Mask, AnyModifier
    +
    +
    urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, +ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, +PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask, +Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask, +KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask, +ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask, +FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask
    +
    +
    urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify, +EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose, +GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify, +UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify, +ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify, +CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest, +SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
    +
    +
    +Various constants for use in X calls and event processing. +

    @@ -340,16 +717,16 @@ Return the foreground/background colour index, respectively.

    -
    $rend = urxvt::SET_FGCOLOR ($rend, $new_colour)
    +
    $rend = urxvt::SET_FGCOLOR $rend, $new_colour
    -
    $rend = urxvt::SET_BGCOLOR ($rend, $new_colour)
    +
    $rend = urxvt::SET_BGCOLOR $rend, $new_colour
    Replace the foreground/background colour in the rendition mask with the specified one.

    -
    $value = urxvt::GET_CUSTOM ($rend)
    +
    $value = urxvt::GET_CUSTOM $rend
    Return the ``custom'' value: Every rendition has 5 bits for use by @@ -357,7 +734,7 @@ zero.

    -
    $rend = urxvt::SET_CUSTOM ($rend, $new_value)
    +
    $rend = urxvt::SET_CUSTOM $rend, $new_value
    Change the custom value. @@ -365,8 +742,60 @@

    +

    The urxvt::anyevent Class

    +

    The sole purpose of this class is to deliver an interface to the +AnyEvent module - any module using it will work inside urxvt without +further programming. The only exception is that you cannot wait on +condition variables, but non-blocking condvar use is ok. What this means +is that you cannot use blocking APIs, but the non-blocking variant should +work.

    +

    +

    The urxvt::term Class

    +
    $term = new urxvt::term $envhashref, $rxvtname, [arg...]
    +
    +
    +Creates a new terminal, very similar as if you had started it with system +$rxvtname, arg.... $envhashref must be a reference to a %ENV-like +hash which defines the environment of the new terminal. +
    +
    +

    Croaks (and probably outputs an error message) if the new instance +couldn't be created. Returns undef if the new instance didn't +initialise perl, and the terminal object otherwise. The init and +start hooks will be called during this call.

    +
    +

    +
    $term->destroy
    +
    +
    +Destroy the terminal object (close the window, free resources +etc.). Please note that rxvt will not exit as long as any event +watchers (timers, io watchers) are still active. +
    +

    +
    $isset = $term->option ($optval[, $set])
    +
    +
    +Returns true if the option specified by $optval is enabled, and +optionally change it. All option values are stored by name in the hash +%urxvt::OPTION. Options not enabled in this binary are not in the hash. +
    +
    +

    Here is a a likely non-exhaustive list of option names, please see the +source file /src/optinc.h to see the actual list:

    +
    +
    +
    + borderLess console cursorBlink cursorUnderline hold iconic insecure
+ intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
+ pastableTabs pointerBlank reverseVideo scrollBar scrollBar_floating
+ scrollBar_right scrollTtyKeypress scrollTtyOutput scrollWithBuffer
+ secondaryScreen secondaryScroll skipBuiltinGlyphs transparent
+ tripleclickwords utmpInhibit visualBell
    +
    +

    $value = $term->resource ($name[, $newval])
    @@ -390,8 +819,8 @@

    Here is a a likely non-exhaustive list of resource names, not all of which -are supported in every build, please see the source to see the actual -list:

    +are supported in every build, please see the source file /src/rsinc.h +to see the actual list:

    @@ -400,7 +829,7 @@
   display_name embed ext_bwidth fade font geometry hold iconName
   imFont imLocale inputMethod insecure int_bwidth intensityStyles
   italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier
-  mouseWheelScrollPage name pastableTabs path perl_eval perl_ext
+  mouseWheelScrollPage name pastableTabs path perl_eval perl_ext_1 perl_ext_2
   perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd
   reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating
   scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput
@@ -409,6 +838,41 @@
   utmpInhibit visualBell

    +
    $value = $term->x_resource ($pattern)
    +
    +
    +Returns the X-Resource for the given pattern, excluding the program or +class name, i.e. $term->x_resource ("boldFont") should return the +same value as used by this instance of rxvt-unicode. Returns undef if no +resource with that pattern exists. +
    +
    +

    This method should only be called during the on_start hook, as there is +only one resource database per display, and later invocations might return +the wrong resources.

    +
    +

    +
    $success = $term->parse_keysym ($keysym_spec, $command_string)
    +
    +
    +Adds a keymap translation exactly as specified via a resource. See the +keysym resource in the rxvt(1) manpage. +
    +

    +
    $rend = $term->rstyle ([$new_rstyle])
    +
    +
    +Return and optionally change the current rendition. Text that is output by +the terminal application will use this style. +
    +

    +
    ($row, $col) = $term->screen_cur ([$row, $col])
    +
    +
    +Return the current coordinates of the text cursor position and optionally +set it (which is usually bad as applications don't expect that). +
    +

    ($row, $col) = $term->selection_mark ([$row, $col])
    ($row, $col) = $term->selection_beg ([$row, $col])
    @@ -420,11 +884,21 @@ and optionally set them to new values.

    +
    $term->selection_make ($eventtime[, $rectangular])
    +
    +
    +Tries to make a selection as set by selection_beg and +selection_end. If $rectangular is true (default: false), a +rectangular selection will be made. This is the prefered function to make +a selection. +
    +

    $success = $term->selection_grab ($eventtime)
    -Try to request the primary selection from the server (for example, as set -by the next method). +Try to request the primary selection text from the server (for example, as +set by the next method). No visual feedback will be given. This function +is mostly useful from within on_sel_grab hooks.

    $oldtext = $term->selection ([$newtext])
    @@ -432,34 +906,11 @@
    Return the current selection text and optionally replace it by $newtext.
    +

    +
    $term->overlay_simple ($x, $y, $text)
    +
    -

    #=item $term->overlay ($x, $y, $text) -# -#Create a simple multi-line overlay box. See the next method for details. -# -#=cut

    -
    -
    -

    sub urxvt::term::scr_overlay { -die; - my ($self, $x, $y, $text) = @_;

    -
    -
    -
    -   my @lines = split /\n/, $text;
    -
    -
    -
    -   my $w = 0;
-   for (map $self->strwidth ($_), @lines) {
-      $w = $_ if $w < $_;
-   }
    -
    -
    -
    -   $self->scr_overlay_new ($x, $y, $w, scalar @lines);
-   $self->scr_overlay_set (0, $_, $lines[$_]) for 0.. $#lines;
-}
    +Create a simple multi-line overlay box. See the next method for details.

    $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
    @@ -505,25 +956,78 @@ If hidden, display the overlay again.

    -
    $cellwidth = $term->strwidth $string
    +
    $popup = $term->popup ($event)
    +
    +
    +Creates a new urxvt::popup object that implements a popup menu. The +$event must be the event causing the menu to pop up (a button event, +currently). +
    +

    +
    $cellwidth = $term->strwidth ($string)
    Returns the number of screen-cells this string would need. Correctly accounts for wide and combining characters.

    -
    $octets = $term->locale_encode $string
    +
    $octets = $term->locale_encode ($string)
    Convert the given text string into the corresponding locale encoding.

    -
    $string = $term->locale_decode $octets
    +
    $string = $term->locale_decode ($octets)
    Convert the given locale-encoded octets into a perl string.

    +
    $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
    +
    +
    +XORs the rendition values in the given span with the provided value +(default: RS_RVid), which MUST NOT contain font styles. Useful in +refresh hooks to provide effects similar to the selection. +
    +

    +
    $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
    +
    +
    +Similar to scr_xor_span, but xors a rectangle instead. Trailing +whitespace will additionally be xored with the $rstyle2, which defaults +to RS_RVid | RS_Uline, which removes reverse video again and underlines +it instead. Both styles MUST NOT contain font styles. +
    +

    +
    $term->scr_bell
    +
    +
    +Ring the bell! +
    +

    +
    $term->scr_add_lines ($string)
    +
    +
    +Write the given text string to the screen, as if output by the application +running inside the terminal. It may not contain command sequences (escape +codes), but is free to use line feeds, carriage returns and tabs. The +string is a normal text string, not in locale-dependent encoding. +
    +
    +

    Normally its not a good idea to use this function, as programs might be +confused by changes in cursor position or scrolling. Its useful inside a +on_add_lines hook, though.

    +
    +

    +
    $term->cmd_parse ($octets)
    +
    +
    +Similar to scr_add_lines, but the argument must be in the +locale-specific encoding of the terminal and can contain command sequences +(escape codes) that will be interpreted. +
    +

    $term->tt_write ($octets)
    @@ -532,26 +1036,101 @@ to the locale-specific encoding using $term->locale_encode.

    -
    $nrow = $term->nrow
    +
    $old_events = $term->pty_ev_events ([$new_events])
    -
    $ncol = $term->ncol
    +
    +Replaces the event mask of the pty watcher by the given event mask. Can +be used to suppress input and output handling to the pty/tty. See the +description of urxvt::timer->events. Make sure to always restore +the previous value. +
    +

    +
    $windowid = $term->parent
    +
    +
    +Return the window id of the toplevel window. +
    +

    +
    $windowid = $term->vt
    +
    +
    +Return the window id of the terminal window. +
    +

    +
    $term->vt_emask_add ($x_event_mask)
    -Return the number of rows/columns of the terminal window (i.e. as -specified by -geometry, excluding any scrollback). +Adds the specified events to the vt event mask. Useful e.g. when you want +to receive pointer events all the times: +
    +
    +
    +   $term->vt_emask_add (urxvt::PointerMotionMask);

    -
    $nsaved = $term->nsaved
    +
    $window_width = $term->width
    +
    +
    $window_height = $term->height
    +
    +
    $font_width = $term->fwidth
    +
    +
    $font_height = $term->fheight
    +
    +
    $font_ascent = $term->fbase
    +
    +
    $terminal_rows = $term->nrow
    +
    +
    $terminal_columns = $term->ncol
    +
    +
    $has_focus = $term->focus
    +
    +
    $is_mapped = $term->mapped
    +
    +
    $max_scrollback = $term->saveLines
    +
    +
    $nrow_plus_saveLines = $term->total_rows
    +
    +
    $topmost_scrollback_row = $term->top_row
    -Returns the number of lines in the scrollback buffer. +Return various integers describing terminal characteristics. +
    +

    +
    $x_display = $term->display_id
    +
    +
    +Return the DISPLAY used by rxvt-unicode. +
    +

    +
    $lc_ctype = $term->locale
    +
    +
    +Returns the LC_CTYPE category string used by this rxvt-unicode. +
    +

    +
    $env = $term->env
    +
    +
    +Returns a copy of the environment in effect for the terminal as a hashref +similar to \%ENV. +
    +

    +
    $modifiermask = $term->ModLevel3Mask
    +
    +
    $modifiermask = $term->ModMetaMask
    +
    +
    $modifiermask = $term->ModNumLockMask
    +
    +
    +Return the modifier masks corresponding to the ``ISO Level 3 Shift'' (often +AltGr), the meta key (often Alt) and the num lock key, if applicable.

    $view_start = $term->view_start ([$newvalue])
    -Returns the negative row number of the topmost line. Minimum value is -0, which displays the normal terminal contents. Larger values scroll +Returns the row number of the topmost displayed line. Maximum value is +0, which displays the normal terminal contents. Lower values scroll this many lines into the scrollback buffer.

    @@ -572,7 +1151,7 @@ Returns the text of the entire row with number $row_number. Row 0 is the topmost terminal line, row $term->$ncol-1 is the bottommost terminal line. The scrollback buffer starts at line -1 and extends to -line -$term->nsaved. Nothing will be returned if a nonexistent line +line -$term->nsaved. Nothing will be returned if a nonexistent line is requested.
    @@ -582,7 +1161,7 @@ automatically be updated.

    -

    $text is in a special encoding: tabs and wide characters that use more +

    $text is in a special encoding: tabs and wide characters that use more than one cell when displayed are padded with urxvt::NOCHAR characters (chr 65535). Characters with combining characters and other characters that do not fit into the normal tetx encoding will be replaced with @@ -594,7 +1173,7 @@ characters.

    -

    The methods $term->special_encode and $term->special_decode +

    The methods $term->special_encode and $term->special_decode can be used to convert normal strings into this encoding and vice versa.

    @@ -637,16 +1216,16 @@ following methods:
    -
    $text = $line->t
    +
    $text = $line->t ([$new_text])
    -Returns the full text of the line, similar to ROW_t +Returns or replaces the full text of the line, similar to ROW_t

    -
    $rend = $line->r
    +
    $rend = $line->r ([$new_rend])
    -Returns the full rendition array of the line, similar to ROW_r +Returns or replaces the full rendition array of the line, similar to ROW_r

    $length = $line->l
    @@ -667,7 +1246,8 @@
    Returns the character offset of the given row|col pair within the logical -line. +line. Works for rows outside the line, too, and returns corresponding +offsets outside the string.

    ($row, $col) = $line->coord_of ($offset)
    @@ -676,8 +1256,7 @@ Translates a string offset into terminal coordinates again.

    -
    ($row, $col) = $line->coord_of ($offset) -=item $text = $term->special_encode $string
    +
    $text = $term->special_encode $string
    Converts a perl string into the special encoding used by rxvt-unicode, @@ -691,6 +1270,83 @@ Converts rxvt-unicodes text reprsentation into a perl string. See $term->ROW_t for details.
    +

    +
    $success = $term->grab_button ($button, $modifiermask)
    +
    +
    +Registers a synchronous button grab. See the XGrabButton manpage. +
    +

    +
    $success = $term->grab ($eventtime[, $sync])
    +
    +
    +Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or +synchronous ($sync is true). Also remembers the grab timestampe. +
    +

    +
    $term->allow_events_async
    +
    +
    +Calls XAllowEvents with AsyncBoth for the most recent grab. +
    +

    +
    $term->allow_events_sync
    +
    +
    +Calls XAllowEvents with SyncBoth for the most recent grab. +
    +

    +
    $term->allow_events_replay
    +
    +
    +Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most +recent grab. +
    +

    +
    $term->ungrab
    +
    +
    +Calls XUngrab for the most recent grab. Is called automatically on +evaluation errors, as it is better to lose the grab in the error case as +the session. +
    +

    +

    +

    +

    The urxvt::popup Class

    +
    +
    $popup->add_title ($title)
    +
    +
    +Adds a non-clickable title to the popup. +
    +

    +
    $popup->add_separator ([$sepchr])
    +
    +
    +Creates a separator, optionally using the character given as $sepchr. +
    +

    +
    $popup->add_button ($text, $cb)
    +
    +
    +Adds a clickable button to the popup. $cb is called whenever it is +selected. +
    +

    +
    $popup->add_toggle ($text, $cb, $initial_value)
    +
    +
    +Adds a toggle/checkbox item to the popup. Teh callback gets called +whenever it gets toggled, with a boolean indicating its value as its first +argument. +
    +

    +
    $popup->show
    +
    +
    +Displays the popup (which is initially hidden). +

    @@ -767,7 +1423,7 @@ $term->{iow} = urxvt::iow ->new ->fd (fileno $term->{socket}) - ->events (1) # wait for read data + ->events (urxvt::EVENT_READ) ->start ->cb (sub { my ($iow, $revents) = @_; @@ -798,8 +1454,9 @@
    $iow = $iow->events ($eventmask)
    -Set the event mask to watch. Bit #0 (value 1) enables watching for read -data, Bit #1 (value 2) enables watching for write data. +Set the event mask to watch. The only allowed values are +urxvt::EVENT_READ and urxvt::EVENT_WRITE, which might be ORed +together, or urxvt::EVENT_NONE.

    $iow = $iow->start
    @@ -823,14 +1480,16 @@

    URXVT_PERL_VERBOSITY

    This variable controls the verbosity level of the perl extension. Higher numbers indicate more verbose output.

    -
      -
    1. - only fatal messages
      -
      2. -
    2. - script loading and management
      -
      3. -
    3. - all events received
      -
      4. -
    +
    +
    == 0 - fatal messages
    +
    +
    >= 3 - script loading and management
    +
    +
    >=10 - all called hooks
    +
    +
    >=11 - hook reutrn values
    +
    +