Skip to content

Hyperlink support

Submitted by Egmont Koblinger

Assigned to Igor @f2404

Link to original bug (#13534)

Description

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