NAME	url-picker


AUTHOR	Chip Camden

DATE	September, 2010


Perl extension for rxvt-unicode (aka urxvt) to enable quick keyboard
navigation of URLs shown in the terminal window.  The design is similar
to the 'follow hints' feature of Vimperator


See the man page for urxvtperl(3) for a full discussion of Perl
extensions.  Enable this extension using one of the methods documented
there.  For instance, you could place the script url-picker in
/usr/local/lib/urxvt/perl, then add the following to .Xdefaults:

URxvt.perl-ext: default,matcher,url-picker
URxvt.keysym.C-0xff0d:    perl:url-picker

I find that url-picker works well in combination with matcher, but you
can leave out the latter if you don't care for it.  The above enables, in
addition to the default behavior, the matcher extension and url-picker.
It directs the key combination of ctrl+enter to call the on_user_command
function of url-picker.


If a portion of the terminal text has been marked for selection, then the
search for URLs will be restricted to that region.  Otherwise, the visible 
text of the termainl will be used.

If no URLs are found,  url-picker just pops up an overlay window that
warns "no URLs found on visible screen" or "no URLs found in visible selected
text".  The overlay disappears after five seconds, but the terminal is
immediately operable.

If the region contains only one URL, that URL is launched to the browser.
The browser is determined by X resources url-picker.launcher if defined,
otherwise URxvt.urlLauncher.  If neither of these are defined, the
'sensible-browser' is used.  The URL will be passed as the first argument.

If more than one URL is available in the region, url-picker places numbered
labels over the first characters of each URL on the screen.  A prompt
"Follow: " appears at the bottom of the terminal window, at which you
can type only numbers, backspace, enter, or escape (all other input is

Escape exits this mode and removes all overlay windows, without doing

Enter launches the URL associated with the number that has been typed, if
that number matches one of the URL labels.  Otherwise, nothing happens.

The labels are numbered in ascending order starting with 1 by default.  You can
cause them to be numbered in reverse order (so that the last link is always
number 1) by setting the resource "URxvt.url-picker.order" to "descending".

When typing numbers, if the number typed so far uniquely identifies a
URL, that URL is launched immediately.  Otherwise, the labels that do not
match the numbers typed so far will be hidden.

The backspace key erases the last number typed, if there is one.

When a URL is launched, all overlay windows are removed and the cursor
position is restored to where it was in the terminal window before
url-picker was invoked.  The url launched is displayed on the bottom
row of the terminal window for five seconds.


The following resources are recognized by url-picker:

URxvt.urlLauncher			Default browser
URxvt.url-picker.input.backgroundColor	Bg color for numbers typed
URxvt.url-picker.input.foregroundColor	Fg color for numbers typed
URxvt.url-picker.label.backgroundColor	Bg color for numbered labels
URxvt.url-picker.label.foregroundColor	Fg color for numbered labels
URxvt.url-picker.launcher		Browser override
URXVT.url-picker.order			"descending" numbers in reverse
URxvt.url-picker.prompt.backgroundColor	Bg color for "Follow:" prompt
URxvt.url-picker.prompt.foregroundColor	Fg color for "Follow:" prompt
URxvt.url-picker.status.backgroundColor	Bg color for status messages
URxvt.url-picker.status.foregroundColor	Fg color for status messages

Colors must be specified using urxvt color indices as described in
the urxvt(1) man page under COLORS AND GRAPHICS.