--- rxvt-unicode/doc/rxvtperl.3.html 2006/01/02 17:21:59 1.2 +++ rxvt-unicode/doc/rxvtperl.3.html 2006/01/03 01:39:56 1.6 @@ -15,11 +15,14 @@
  • NAME
  • SYNOPSIS
  • DESCRIPTION
    • +
  • PACKAGED EXTENSIONS
    • @@ -43,22 +46,79 @@

    SYNOPSIS

    -

    * Put your scripts into /opt/rxvt/lib/urxvt/perl-ext/, they will be loaded automatically.

    -

    * Each script will only be loaded once, even in urxvtd, and will be valid -globally.

    -

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

    +
    +   # create a file grab_test in $HOME:
        sub on_sel_grab {
       warn "you selected ", $_[0]->selection;
       ()
    }
    -   1
    + # start a rxvt using it: +
    +   rxvt --perl-lib $HOME -pe grab_test

    DESCRIPTION

    +

    Everytime a terminal object gets created, 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.

    +

    +

    +
    +

    PACKAGED EXTENSIONS

    +

    This section describes the extensiosn delivered with this version. You can +find them in /opt/rxvt/lib/urxvt/perl/.

    +

    You can activate them like this:

    +
    +  rxvt -pe <extensionname>
    +
    +
    selection
    +
    +
    +Miscellaneous selection modifications. +
    +
    +
    rot13
    +
    +
    +Rot-13 the selection when activated. Used via keyboard trigger: +
    +
    +
    +   URxvt.keysym.C-M-r: perl:selection:rot13
    +
    +

    +
    digital-clock
    +
    +
    +Displays a very simple digital clock in the upper right corner of the +window. Illustrates overwriting the refresh callbacks to create your own +overlays or changes. +
    +

    +
    simple-overlay-clock
    +
    +
    +Displays a digital clock using the built-in overlay (colorful, useless). +
    +

    +

    +

    +

    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 +like. All members starting with an underscore (such as _ptr or +_hook) are reserved for internal uses and must not be accessed or +modified).

    +

    When objects are destroyed on the C++ side, the perl object hashes are +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.

    Hooks

    @@ -169,6 +229,14 @@
    Called just after the screen gets redrawn. See on_refresh_begin.
    +

    +
    on_keyboard_command $term, $string
    +
    +
    +Called whenever the user presses a key combination that has a +perl:string action bound to it (see description of the keysym +resource in the rxvt(1) manpage). +

    @@ -185,7 +253,7 @@
    urxvt::warn $string
    -Calls rxvt_warn witht eh given string which should not include a +Calls rxvt_warn with the given string which should not include a newline. The module also overwrites the warn builtin with a function that calls this function.
    @@ -194,13 +262,6 @@ correct place, e.g. on stderr of the connecting urxvtc client.

    -
    $cellwidth = urxvt::wcswidth $string
    -
    -
    -Returns the number of screen-cells this string would need. Correctly -accounts for wide and combining characters. -
    -

    $time = urxvt::NOW
    @@ -243,14 +304,14 @@ borderLess color cursorBlink cursorUnderline cutchars delete_key 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 pointerBlank - pointerBlankDelay preeditType print_pipe pty_fd reverseVideo saveLines - scrollBar scrollBar_align scrollBar_floating scrollBar_right - scrollBar_thickness scrollTtyKeypress scrollTtyOutput scrollWithBuffer - scrollstyle secondaryScreen secondaryScroll selectstyle shade term_name - title transparent transparent_all tripleclickwords utmpInhibit - visualBell + italicFont jumpScroll lineSpace loginShell mapAlert menu meta8 modifier + mouseWheelScrollPage name pastableTabs path perl_eval perl_ext + perl_lib pointerBlank pointerBlankDelay preeditType print_pipe pty_fd + reverseVideo saveLines scrollBar scrollBar_align scrollBar_floating + scrollBar_right scrollBar_thickness scrollTtyKeypress scrollTtyOutput + scrollWithBuffer scrollstyle secondaryScreen secondaryScroll selectstyle + shade term_name title transparent transparent_all tripleclickwords + utmpInhibit visualBell

    ($row, $col) = $term->selection_mark ([$row, $col])
    @@ -271,7 +332,7 @@ by the next method).

    -
    $oldtext = $term->selection ([$newtext])
    +
    $oldtext = $term->selection ([$newtext])
    Return the current selection text and optionally replace it by $newtext. @@ -310,6 +371,152 @@
    Write a string at the given position into the overlay.
    +

    +
    $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
    +
    +
    +Convert the given text string into the corresponding locale encoding. +
    +

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

    +
    $term->tt_write ($octets)
    +
    +
    +Write the octets given in $data to the tty (i.e. as program input). To +pass characters instead of octets, you should convert your strings first +to the locale-specific encoding using $term->locale_encode. +
    +

    +
    $nrow = $term->nrow
    +
    +
    $ncol = $term->ncol
    +
    +
    +Return the number of rows/columns of the terminal window (i.e. as +specified by -geometry, excluding any scrollback). +
    +

    +
    $nsaved = $term->nsaved
    +
    +
    +Returns the number of lines in the scrollback buffer. +
    +

    +
    $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 +this many lines into the scrollback buffer. +
    +

    +
    $term->want_refresh
    +
    +
    +Requests a screen refresh. At the next opportunity, rxvt-unicode will +compare the on-screen display with its stored representation. If they +differ, it redraws the differences. +
    +
    +

    Used after changing terminal contents to display them.

    +
    +

    +
    $text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
    +
    +
    +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. +
    +
    +

    If $new_text is specified, it will replace characters in the current +line, starting at column $start_col (default 0), which is useful +to replace only parts of a line. The font iindex in the rendition will +automatically be updated.

    +
    +
    +

    $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 +characters in the private use area.

    +
    +
    +

    You have to obey this encoding when changing text. The advantage is +that substr and similar functions work on screen cells and not on +characters.

    +
    +
    +

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

    +
    +

    +
    $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
    +
    +
    +Like $term->ROW_t, but returns an arrayref with rendition +bitsets. Rendition bitsets contain information about colour, font, font +styles and similar information. See also $term->ROW_t. +
    +
    +

    When setting rendition, the font mask will be ignored.

    +
    +
    +

    See the section on RENDITION, below.

    +
    +

    +
    $length = $term->ROW_l ($row_number[, $new_length])
    +
    +
    +Returns the number of screen cells that are in use (``the line length''). If +it is -1, then the line is part of a multiple-row logical ``line'', which +means all characters are in use and it is continued on the next row. +
    +

    +
    $text = $term->special_encode $string
    +
    +
    +Converts a perl string into the special encoding used by rxvt-unicode, +where one character corresponds to one screen cell. See +$term->ROW_t for details. +
    +

    +
    $string = $term->special_decode $text
    +
    +
    +Converts rxvt-unicodes text reprsentation into a perl string. See +$term->ROW_t for details. +
    +

    +

    +

    +

    RENDITION

    +

    Rendition bitsets contain information about colour, font, font styles and +similar information for each screen cell.

    +

    The following ``macros'' deal with changes in rendition sets. You should +never just create a bitset, you should always modify an existing one, +as they contain important information required for correct operation of +rxvt-unicode.

    +
    +
    $rend = urxvt::DEFAULT_RSTYLE
    +
    +
    +Returns the default rendition, as used when the terminal is starting up or +being reset. Useful as a base +