Hyperlink support

[egmontkob]

VTE 0.49.1 (and GNOME Terminal 3.25.1) has just implemented a brand new and hopefully really cool feature: hyperlinks (that is, HTML-like anchors).

This is different from the regex-based autodetection of URLs that appear onscreen. This time the text that appears does not have to look like a URL, it can be anything, and the target URL is specified explicitly by the utility along with the displayed text, using a particular escape sequence.

In case you'd like to hook up to this new feature (I hope you do), here's what to do:

• Call vte_terminal_set_allow_hyperlink() to enable the feature, as it's disabled by default.

• Whenever you're interested in the target URL at a certain location (e.g. for Ctrl+click action, or for presenting the right-click menu), call vte_terminal_hyperlink_check_event(). This returns a newly allocated string containing the URI-encoded URL that you should eventually free.

• If you'd like to stay up to date with the URL as the mouse moves or the contents underneath change, hook up to the hyperlink-hover-uri-changed signal. It'll give you two parameters owned by VTE (that is, must not be modified or freed, and only valid for the duration of the signal handler). The first is the URI-encoded URL, the second is a bounding rectangle of the anchor text (relative to GtkWindow's topleft). [GNOME Terminal shows a tooltip with the URI-decoded and un-IDN'd URL (this decoding is done by GNOME Terminal, not by VTE). It's up to you to choose different presentations if you wish, e.g. an overlay in the bottom corner similarly to browsers, or whatever you prefer. There's even a pending demo patch for GNOME Terminal to show a preview for certain local files (most notably pictures, PDFs).]

When handling file: URLs, please double check that you verify the hostname, as described in [1]. This is unfortunately not done by gtk_show_uri() or its underlying g_app_info_launch_default_for_uri().

In case a character cell belongs to both an explicit URL (this new feature) and an implicit autodetected one (the old one, using regex match), we recommend the explicit one to take precedence (we assume that the application emitting the URL knows it much better than the autodetecting regex). This is also how VTE underlines the cells, so this is what the user expects on e.g. a Ctrl+click. The right-click menu might display both entries, in GNOME Terminal we decided to display actions for the explicit hyperlink only in case of such collision.

Keep in mind that we're in a development cycle, there's a slim chance that the API will change before it's finalized in VTE 0.50 this September. I'll let you know here if it changes.

For further information on this feature, see

[1] A dedicated page with all the details: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda

[2] The GNOME Terminal bugreport (way too long and probably not that interesting at this point): https://bugzilla.gnome.org/show_bug.cgi?id=779734

[gnunn1]

I've done an initial implementation of this feature. To confirm, it looks like the intent is that the URI is always valid from a global context? In other words, a file URI always has the hostname and a fully qualified path associated with it? No using tilde for the home directory or a filename that only resolves in the context of the terminal CWD?

[egmontkob]

Yup that's absolutely correct. Full URIs all the time, no shortcuts, no context to carry.

[egmontkob]

To be a bit more precise: The syntax (e.g. hostname being present) is not enforced, whatever string is present in the escape sequence will appear to you unchanged via the API. This string might not have a scheme, a hostname etc, it could be e.g. the literal string ~/foo.txt or /home/gnunn1/foo.txt. But you should not open a local file in that case, rather, you should refuse to open anything. The semantically correct approach, in which case you should open the file, is if you see file://the-actual-hostname/home/gnunn1/foo.txt.

[egmontkob]

In gnome-terminal we call gtk_show_uri() which pretty much does this out of the box (including URI-unescaping if/as necessary for local files). We make two exceptions around it:

• It does not verify the hostname, so we do that manually (in order for file:// links over ssh to fail rather than to open the local counterpart);
• Planned: If the hostname matches after a file://, we'll remove it to workaround a LibreOffice bug.