feature request: hover text
albertz opened this issue · comments
It would be nice to let some hover-text appear when I move over some text with the mouse (such as additional information about some object, file, or so).
The terminal escape code syntax could be something like <start-hover>visible<mid-hover>hover-text<end-hover> (similar syntax as hyperlinks). The hover text ideally could again contain other escape codes (such as support for colors).
How about this:
\e]120;options\a visible-text\e]121;\a
"Options" has the form of a JSON object, with the outer "{}" removed.
This is the same as visible-text but surrounded by a <span> that cases certain actions (depending on the options) to happen on mouse-over (hover).
The following options seem desirable:
"hover-class": "NAME"
On mouseover, (temporarily) add "NAME" to the class of the <span>.
"hover-style": "STYLE"
On mouseover, (temporarily) set the class of the <span> to "STYLE".
"info-html": "HTMLTEXT"
On mouseover show the "info block" (by default a rectangle over the lower right, also used by link hovers) to "HTMLTEXT"
"popup-html": "HTMLTEXT"
On mouseover create a popup "window" (actually a <div> element) containing "HTMLTEXT".
"hover-timeout": SECONDS
Undo the above actions after the specified SECONDS (or mouse-leave, whichever comes first). A value of 0, or a missing hover-timeout means no timeout.
Not sure what the difference between info-html and popup-html would be.
Also, another problem is, that it has to be HTML code then. At least for the use case I have in mind, it would be much simpler if I can use the standard escape codes (for color etc) to format some string.
"Not sure what the difference between info-html and popup-html would be."
The info-html uses the "info block" - the little "mini-buffer" you see on the lower-right when re-sie the window, or when you hover a link. It is normally a single short line. The pop-html would be shown near the mouse, and may be multiple lines.
An alternative would be use the same option, but with a separate position option to select where to put the popup.
"Also, another problem is, that it has to be HTML code then"
HTML seems a bit easier to deal with in terms of implementation, at least if using an options object or OSC text. If the hover_text can contain standard escape codes, it needs to be processed by the insertString function - but I think it would be wiser to avoid recursive calls to insertString. So we need "start-hover-text"/"end-hover-text" escape sequences: "start-hover-text" creates a new invisible <div>; subsequent text is added to this <div>; "end-hover-text" goes back to the normal flow. I expect some complications but doable.
I think we should not think in terms of what is simple to implement for DomTerm, but rather:
- What is simple for the user. (And I already have lots of code in place to format my output with escape codes. Needing HTML output would mean to duplicate all that, but for HTML instead of escape codes.)
- What is a clean definition of the feature so that it is simple for other terminal emulators to adopt this feature.
I think if this feature is HTML only, this will probably always stay a DomTerm-only implementation.
Well, we do have to also consider implementation complexity. However, I agree that text-with-escape-codes is preferable, and I think I can implement that with modest effort.
Some tentative conclusions and suggestions:
-
It is indeed desirable to use an escape sequence that is "invisible" and harmless to terminals that don't recognize it, assuming they ignore unrecognized OSC sequences. This does complicate the protocol a bit, but it seems worth it.
-
That does suggest something in the spirit of the hyperlinks specification. Tentatively we'll use OSC 9 as a place-holder, but some research is needed to check if that is in use. (A repository of OSC extensions used by various terminals would be helpful.)
OSC 9 ; params ; hover-text ST visible-text OSC 9; ST
-
However, we'd like to support escape sequences in the hover-text, to change styling. Some escape sequences may include
OSCandST. Thus we need some kind of escaping mechanism, and using JSON escapes seems the obvious. -
As long as you're using JSON for the hover-text, we might as well use it to the options, and combine them:
OSC 9 ; options ST visible-text OSC 9; ST
where options has the form of a JSON object with the outer curly braces removed. For example:
\e]9;"text":"hover-text","timeout": 2.0\avisible-text\e]9;\a
- Using JSON5 instead of plain JSON would be slightly more complact and readable:
\e]9;text:"hover-text",timeout: 2.0\avisible-text\e]9;\a
However, since the escape sequences will be machine-generated and machine-read (rather than human-read), the benefits are probably not worth the extra complication.
- Some suggested options:
"text": hover-text
Display hover-text (plain text but possibly with escape sequences) on hover.
"html": hover-html
If the terminal understand HTML, display hover-html (embedded in a <div>) instead of hover_text. This is somewhat redundant if hover_text could include an HTML escape (as in DomTerm's OSC 72 escape) but this allows different text or styling for html-enabled and regular terminals.
"hover-class": " class-name"
Specific to terminals that use HTML/DOM, which will create a <span> element to surround the visible-text: On hover, (temporarily) add class-name to the class attribute of the <span>.
"hover-style": "styling"
(Specific to terminals that use HTML/DOM.) On hover, (temporarily) set the style attribute of the <span> (mentioned above) to styling.
"timeout": seconds
Undo the above actions after the specified seconds (or mouse-leave, whichever comes first). A value of 0, or a missing timeout options means no timeout.
It might make sense to extend the OSC 8 hyperlink escape sequence. DomTerm recently got a nice mechanism for displaying links (see the screenshot here) and it could be easily extended for application-supplied hover information. Rather than come up with a new OSC code, reusing OSC 8 migh be best:
OSC 8 ; _ params_ ; link-text ST visible-text OSC 9; ST
The following _ params_ are suggsted:
rtext=data
- "Rich text". Base-64 encoding of text to display. The text may include escape sequences, including (on DomTerm) HTML escapes. Conceptually, data is decoded from base-64, and interpreted as input bytes in a fresh terminal. This rendering may be done either when the OSC 8 escape sequence is handled, in which case the rendered text is saved somewhere non-visible until needed. Alternatively, the rendering may be done on-the-fly as needed. Therefore the decoded data may not send any requests to the application.
When a rtext option is specied, it is used for the hover popup. The link-text provides a fallback for terminals that don't understand the rtext option. Also, if the visible-text is clicked (perhaps with a modifier like Ctrl or a context-menu) then the link-text should be used for resolving the link. If link-text is empty, clicking is ignored (except for focus)..
max-size=width[,height]
- The rendering of decoded data should be a a pseudo terminal of the given width and height. This is a suggestion and the terminal may ignore them. These are maximums: After rendering is done, empty right columns and empty final lines are removed. Then terminal-dependent padding, and borders are added before display "near" the mouse cursor. If the rendered number of lines is greater than lines, a scrollbar should be added. The numbers width and height are numbers (in columns and rows) with optional decimals.
ha-class-hclass
- Set the
classattribute of the hover element to hclass. Normally only relevant for HTML-based terminals.