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

[janza]

Is there a way to get a list of hyperlinks in the visible part of the terminal? It would be useful to have that for termite's URL hints mode.

[egmontkob]

No, not at the moment, and I'm afraid an efficient implementation would require quite a bit of refactoring. (Maintaining a target URL for each and every character cell is obviously potentially very expensive, addressing this has caused quite a bit of headachechallenge in vte. For the "normal" part of the screen these URLs are available straight away. For the scrollback contents, however, the actual URLs are not pulled into memory. Only the URL of the cell under the mouse is available straight away in memory, and for the other cells it's only known whether they're part of a hyperlink at all, and if so, whether it's the same hyperlink (that is, to be underlined differently). This would need to be changed completely. Or, you can probably loop through all the possible positions and query the URL underneath, which would be truly unefficient.)

I guess you'd also need this kind of information for regex matches, which isn't available in vte either, right? I'm not sure if vte-ng adds this.

As you obviously know, vte is not focused on keyboard-oriented use. There are quite a bit of places where this should be improved, probably getting a list of all the hyperlinks is yet another of this kind.

[janza]

Yeah, from what I can see it gets the visible content and then does regex matching on it in find_urls. It only happens when user requests it, so maybe having a loop there might be OK.

To show the hints it would only need to get hyperlink positions. Only after user selects a specific hyperlink it would need to get the actual URL at the selected position.

[czardien]

Anyone has any update on this? Very keen on that feature 👍

[thestinger]

Termite is obsolete. Please use Alacritty instead. See https://github.com/thestinger/termite#termite-is-obsoleted-by-alacritty for more details.