-Intelligent selection. This extension tries to be more intelligent when
-the user extends selections (double-click). Right now, it tries to select
-urls and complete shell-quoted arguments, which is very convenient, too,
-if your ls supports --quoting-style=shell.
+(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:
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 the following bindable keyboard command:
+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.
+
+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.
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.
+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.
+
+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.
+
All objects (such as terminals, time watchers etc.) are typical
reference-to-hash objects. The hash can be used to store anything you
@@ -126,26 +266,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:
+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.
+
+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.
+
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.
+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.
+
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 ()). >
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
@@ -192,26 +391,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.
+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.
+
+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.
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).
+resource in the urxvt(1) manpage).
+
+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.
+
+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.
-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.
@@ -312,12 +600,49 @@
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.
+Returns true when it is safe to do potentially unsafe things, such as
+evaluating perl code specified by the user. This is true when urxvt was
+started setuid or setgid.
+
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.
+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.
+Destroy the terminal object (close the window, free resources
+etc.). Please note that urxvt will not exit as long as any event
+watchers (timers, io watchers) are still active.
+
+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:
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:
-Return and optionally change the current rendition. Text thta is output by
-the temrianl application will use this style.
+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.
+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.
+
-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.
+Creates a new urxvt::popup object that implements a popup menu. The
+$eventmust be the event causing the menu to pop up (a button event,
+currently).
+
+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.
+
+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.
+
+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.
+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.
+
+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.
+
$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
@@ -639,7 +1139,7 @@
characters.
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.
Converts a perl string into the special encoding used by rxvt-unicode,
@@ -736,6 +1236,83 @@
Converts rxvt-unicodes text reprsentation into a perl string. See
$term->ROW_t for details.
+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.
+
+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).
+
-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
@@ -869,11 +1447,13 @@
This variable controls the verbosity level of the perl extension. Higher
numbers indicate more verbose output.