Known limitations:

• doesn't look good with listchars=eol
• doesn't look good with area highlighting (visual mode)

When the cursor moves past EOL into "non-text" space Vim calls that "virtual editing".

Is there a reason this needs to be limited to EOL? Or could it instead be offset-driven? IIUC this PR adds management for per-line annotations, it just doesn't yet give the capability to say where the offset is.

@justinmk the honest answer is I've tried that, but I've never got the cursor positioning to work. EOL is simpler as it does never affect cursor positioning...

Fair enough, I would suggest something like nvim_buf_set_virtual_text({buf}, {column}, ...) with a current limitation that {column} must be -1 which means EOL. So we have a partial implementation and can enhance it later.

EOL is simpler as it does never affect cursor positioning...

Well, unless the annotated text contains a double width char and virtualedit is active :P (for nvim it works, but terminals might not like it, pangoterm does not)

{offset} must be INTMAX which means EOL.

Agree, we have used this pattern before (parameter with forced value, sockconnect(..., {'rpc': v:true}) comes to mind)

unless the annotated text contains a double width char and virtualedit is active :P (for nvim it works, but terminals might not like it, pangoterm does not)

But actually, double-width+block visual mode already has some glitches with pangoterm (and supposedly with other terminals), so maybe this actually doesn't make stuff worse...

Instead of messing the line-drawing loop I tried another approach: add char putting to the existing post-end-of-line loop. This fixes some issues:

• reasonable interaction with lcs=eol:$
• visual selection doesn't "select" the eol text (though I have fixed this in the old implementation also)
• does not change line breaking, rather truncates the eol text. This is probably more reasonable, rather than flicker the line layout as diagnostics are received from LSP (for instance)

Changed the API to allow multiple highlights: (1-element chunk implies no highlight)

call nvim_buf_set_virtual_text(0, src_id, linenr, [["text "], ["more text", "Comment"]], {})

I think I will add a forced-empty options dict (because I have some ideas of extensions, including more control of positioning), but otherwise I think the API is good enough as a first step (and I want to release my LSP inline diagostics plugin :P).

Renamed to nvim_buf_set_virtual_text. Added some docs and some tests, marking RFC.

@bfredl I just have a try with this PR, here is my follow questions:

1. can not view help file via :h nvim_buf_set_virtual_text()
2. how to clear this virtual text?
3. after adding many virtual texts, can we group them, that will be easy to clear one group.

and this feature is to show virtual text, we can not override exist line, for example , I want to show an infor under cursorline, and start with col 1, instead of end of next line.

we can not override exist line, for example , I want to show an infor under cursorline, and start with col 1, instead of end of next line.

Not yet, but the options dict is meant for adding additional behaviors. We could add support for something like {'col': 0, 'conceal': v:true} (or maybe concealing should just be the default and not shifting, is is easier to implement anyway). Another option is simply {'replace': v:true} which just skips the ordinary text loop (but it would imply potentially changing text flow, and more redraws, something I have avoided so far).

OK，if we are using conceal in the dictionary, can I use new colorscheme group ?

OK，if we are using conceal in the dictionary, can I use new colorscheme group ?

Yes, no need to inherit arbitrary restrictions from matchaddpos().

@bfredl I just have a try with this PR, here is my follow questions:

1. can not view help file via :h nvim_buf_set_virtual_text()
2. how to clear this virtual text?
3. after adding many virtual texts, can we group them, that will be easy to clear one group.

I'm also curious about 2 and 3 here. It's pretty painful to have to track all the virutal texts added to clear one by one.

I responded to that on gitter and updated the documentation. Though api.txt docs might not have been regenerated since then. The same mechanism as for nvim_buf_add_highlight is used for grouping.

Updated API docs: b96730b

Awesome feature, thanks!

May I suggest right justification of text as one of the future opts?

How to handle wrapping?
Cause so far if the virtual text behind the line is long (or the lines content itself is quite long) it does not fit within the width of the window. So only the beginning of the text is visible. And since the virtual text is not part of the buffer, there seems to be no way to scroll to the right, cause the cursor just move to the next line.

@weilbith This is a current limitation / by design. How would you expect it to handle wrapping?

🤔

I guess as right now if using wrapping for the buffers content. The line is split into two visual lines in the buffer, while the file has only one. (isn't it the default behavior?)
Maybe in this case I could imagine the feature (configurable?) of wrapping the line, but don't start the virtual text on the first buffer line and wrap the not fitting part into the next, but display the whole virtual text in the new line of the wrapped line, just in case the content plus the virtual text would not fit for the current windows width. I believe this could look nice. 🤷‍♂️

Yes, it could maybe just trigger the wrapping with set wrap?
Not sure if this needs a configuration option though, but should rather be the default.
(It works quite nice already for when the line itself is wrapped already.)

(It works quite nice already for when the line itself is wrapped already.)

How do you mean this? Sounds more like a situation that could occur and where this looks nice, rather than something that is "working". Or did I get this wrong by you?
The sentence before the last one has no negative intention. I love this feature here. 👍

the line is split into two visual lines in the buffer, while the file has only one. (isn't it the default behavior?)

It is currently by (general, not feature-specific) design. If I just change the vertical space of a line inside win_line, the rest of the window might get garbled up. conceal has the reverse problem, a large conceal should allow a line to wrap less and occupy less vertical space, but vim currently doesn't allow this. So you will then get a line that is wrapped even if it visually shouldn't need to be. I might look into all this when my next battle with win_line.

@BFedL okay, make sense. Sound like and awful problem. 🤔
So can be mention this anywhere? Since you said the win_lin stuff is already planned, is there an issue open to do so?