Layered display API (was: bug#18195: 24.3.92; window-screen-lines is not accurate)

Layered display API (was: bug#18195: 24.3.92; window-screen-lines is not accurate)

[Dmitry Gutov]

On 08/06/2014 06:52 AM, Eli Zaretskii wrote:

 >> That sounds great, but I don't even know where to start. What we're
 >> trying to emulate, though, is multi-layered display. That sounds
 >> somewhat different from a "text layout API" to me.
 >
 > I don't mind how it is called and what is the correct abstraction.  I
 > do know that we need some abstraction and APIs to support it.  If you
 > already know what the correct abstraction is, then you are in a good
 > position to formulate the requirements.

I don't know much of the other use cases (only in-buffer calltips come 
to mind).

Basically, we'd like to be able to display a rectangle with propertized 
text inside, at an arbitrary position (I would say pixel coordinates, 
but that might not work well in terminal), so that it would be displayed 
above the buffer contents.

This would solve two issues we currently have:

1. If the buffer ends (shortly) after the current line, we're forced to 
pad it with a newline, and then carefully undo that and restore the 
buffer modification status.

2. If the buffer is already heavily using the `display' text property, 
or other similar ones, our tooltip positioning also breaks or works 
unexpectedly. Example: the `report-emacs-bug' buffer 
(https://github.com/company-mode/company-mode/issues/136).

Somewhat relatedely, I'd love to be able to sanely display smooth 
graphics spanning multiple lines in the fringe (or in the area that 
would replace it), to indicate the buffer lines that changed from the 
last VCS commit, without conflict with flymake-style warning/error 
indicators. Code folding packages might also use it to indicate the 
bounds of the function or block at point. Maybe even support buttons?

Here's an illustration from a proprietary editor: 
http://wiki.jetbrains.net/i/images/6/68/Git_general_branches_updated_code.png

Re: Layered display API (was: bug#18195: 24.3.92; window-screen-lines is not accurate)

[Eli Zaretskii]

> Date: Wed, 06 Aug 2014 16:40:37 +0400
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: rudalics@gmx.at, emacs-devel <emacs-devel@gnu.org>
> 
> Basically, we'd like to be able to display a rectangle with propertized 
> text inside, at an arbitrary position (I would say pixel coordinates, 
> but that might not work well in terminal), so that it would be displayed 
> above the buffer contents.

That you already have, don't you?  The problem is not display, AFAIU,
the problem is the decision where exactly to display it, and the
answer depends on the dimensions of the text and the window.

If some features are missing to achieve the above (and they are not
the 2 mentioned below), then please spell them out, because I thought
the display part was already solved, once the layout is decided.

(And pixel units work quite well on text terminals, except that each
character position is 1 pixel.)

> 1. If the buffer ends (shortly) after the current line, we're forced to 
> pad it with a newline, and then carefully undo that and restore the 
> buffer modification status.

Why can't you include the newline in the overlay string instead?

> 2. If the buffer is already heavily using the `display' text property, 
> or other similar ones, our tooltip positioning also breaks or works 
> unexpectedly. Example: the `report-emacs-bug' buffer 
> (https://github.com/company-mode/company-mode/issues/136).

This is indeed a missing feature.  It should be easy enough to provide
some special kind of display property that would overlay any other
displayed content, but won't that introduce the kind of arms race we
already have with overlay priorities?  IOW, what if more than one
feature wants to have its string displayed on top of everything?

Btw, why doesn't company use normal tooltips on GUI frames and
text-mode menus on a TTY?  Wouldn't that be better?

> Somewhat relatedely, I'd love to be able to sanely display smooth 
> graphics spanning multiple lines in the fringe (or in the area that 
> would replace it)

How is this different from displaying bitmaps that fill the whole
height of a screen line, so that adjacent bitmaps don't leave any
pixels between them?

> Maybe even support buttons?

Clicking on the fringes already works.

Re: Layered display API (was: bug#18195: 24.3.92; window-screen-lines is not accurate)

[Alp Aker]

[-- Attachment #1: Type: text/plain, Size: 267 bytes --]

> How is this different from displaying bitmaps that fill the whole
> height of a screen line, so that adjacent bitmaps don't leave any
> pixels between them?

With a positive value of line-spacing, this approach doesn't suffice:
you'll get gaps between the bitmaps.

[-- Attachment #2: Type: text/html, Size: 414 bytes --]

Re: Layered display API (was: bug#18195: 24.3.92; window-screen-lines is not accurate)

[Eli Zaretskii]

> Date: Wed, 6 Aug 2014 14:20:01 -0400
> From: Alp Aker <alptekin.aker@gmail.com>
> Cc: Dmitry Gutov <dgutov@yandex.ru>, martin rudalics <rudalics@gmx.at>, Emacs devel <emacs-devel@gnu.org>
> 
> > How is this different from displaying bitmaps that fill the whole
> > height of a screen line, so that adjacent bitmaps don't leave any
> > pixels between them?
> 
> With a positive value of line-spacing, this approach doesn't suffice:
> you'll get gaps between the bitmaps.

Something that should be easy enough to fix, no doubt.

Re: Layered display API

[Stefan Monnier]

>> > How is this different from displaying bitmaps that fill the whole
>> > height of a screen line, so that adjacent bitmaps don't leave any
>> > pixels between them?
>> With a positive value of line-spacing, this approach doesn't suffice:
>> you'll get gaps between the bitmaps.
> Something that should be easy enough to fix, no doubt.

Currently, it's rather hard, since the height of a line depends on many
other things (such as the content of the line) and there's no
functionality to re-compute the pixmap to display in the margin once we
know the line height.


        Stefan

Re: Layered display API

[Dmitry Gutov]

On 08/06/2014 09:19 PM, Eli Zaretskii wrote:

> That you already have, don't you?  The problem is not display, AFAIU,
> the problem is the decision where exactly to display it, and the
> answer depends on the dimensions of the text and the window.

"Below or above" are just the main choices. Correctly positioning it at 
the right line and column, without disturbing the text around, can still 
be a problem in advanced cases, like you mentioned here and in another 
thread.

> If some features are missing to achieve the above (and they are not
> the 2 mentioned below), then please spell them out, because I thought
> the display part was already solved, once the layout is decided.

Only if we use 1 overlay (the "crazy" approach) and only if we can 
easily get the text contained on the target rows, and there are physical 
buffer positions corresponding to the first and last lines where we want 
to display the popup (or thereabouts). If the whole text in the window 
is already rendered with `display' property, and we want to display the 
popup above only some part of it... good luck with that.

> (And pixel units work quite well on text terminals, except that each
> character position is 1 pixel.)

Ok.

>> 1. If the buffer ends (shortly) after the current line, we're forced to
>> pad it with a newline, and then carefully undo that and restore the
>> buffer modification status.
>
> Why can't you include the newline in the overlay string instead?

Haven't tried yet. And in the overlay-a-line case, each of them would be 
zero-length, then? Guess that could work...

>> 2. If the buffer is already heavily using the `display' text property,
>> or other similar ones, our tooltip positioning also breaks or works
>> unexpectedly. Example: the `report-emacs-bug' buffer
>> (https://github.com/company-mode/company-mode/issues/136).
>
> This is indeed a missing feature.  It should be easy enough to provide
> some special kind of display property that would overlay any other
> displayed content

That would leave a question where will it have to be set on. Would that 
new kind of overlay be able to be displayed far from the position it's 
set on?

 > , but won't that introduce the kind of arms race we
> already have with overlay priorities?  IOW, what if more than one
> feature wants to have its string displayed on top of everything?

I've only read about this "arms race" here on emacs-devel, instead of 
seeing it in practice. When we want to have layered display, using some 
kind of priorities system is probably a fact of life. I don't think 
there's a way around it.

> Btw, why doesn't company use normal tooltips on GUI frames and
> text-mode menus on a TTY?  Wouldn't that be better?

I'm not 100% sure what's text-mode menu is (by tooltip, do you mean 
`tooltip-show'?), but maybe because when active, they take over event 
handling, so you can't move up and down the list with M-n/M-p (or any 
other bindings the user prefers), press another combination of keys and 
see a doc buffer pop up, or just continue typing in the buffer and see 
the popup with completion candidates get updated unobtrusively.

And, at least in the tooltip's case, they can't be styled.

>> Somewhat relatedely, I'd love to be able to sanely display smooth
>> graphics spanning multiple lines in the fringe (or in the area that
>> would replace it)
>
> How is this different from displaying bitmaps that fill the whole
> height of a screen line, so that adjacent bitmaps don't leave any
> pixels between them?

That's what I've been trying to do in diff-hl (see ELPA), and failing to 
do the arithmetics just right when line-spacing and zoom factor and 
present. It should be easier with the recently added functions, though.

Still, this way you can only use 2 colors, each line can only contain 
one bitmap, and the way you have to define the bitmaps globally is 
pretty simplistic.

* Supporting vector graphics would be nicer, instead of having to 
redefine the bitmaps when zoom level changes.

* If two visible buffers have different zoom levels, I don't know how 
display the required bitmaps in both of their fringes right. Include the 
line height in the bitmap names, maybe? Speaking of crazy approaches.

> Clicking on the fringes already works.

We do support buttons in buffers, even though we probably could add 
click handlers and then look up coordinates. Suppose there are multiple 
modes using the fringe, and they all want to handle clicks. How would 
they handle that without conflicts?

Re: Layered display API

[Stefan Monnier]

>> Basically, we'd like to be able to display a rectangle with propertized 
>> text inside, at an arbitrary position (I would say pixel coordinates, 
>> but that might not work well in terminal), so that it would be displayed 
>> above the buffer contents.
> That you already have, don't you?

I don't think we do.

> Why can't you include the newline in the overlay string instead?

I wonder as well.

> This is indeed a missing feature.  It should be easy enough to provide
> some special kind of display property that would overlay any other
> displayed content,

A similar request was made to overlay non-text content.

> but won't that introduce the kind of arms race we already have with
> overlay priorities?

We have tons of such arms races in the current display system
(e.g. faces, invisibility, ...).  It'd be nice to solve them, but
I don't think this is an argument against providing another display
feature that also suffers from such arms races.

> Btw, why doesn't company use normal tooltips on GUI frames and
> text-mode menus on a TTY?  Wouldn't that be better?

Normal tooltips can be used but have their own problems (I'm pretty sure
one of auto-complete, completion-ui, or other uses that in some cases).
E.g. depending on compile-time choices, they may be provided by the GUI
toolkit, in which case we have very little control about what features
they provide (key-bindings, fonts, colors, ...).

But yes, one possible direction is to spice up our support for "tooltip
frames" such that it can be used for such purposes without losing the
ability to control faces and key-bindings and with control over the
precise layout and the borders that might be drawn around it.


        Stefan

Re: Layered display API

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Alp Aker <alptekin.aker@gmail.com>,  rudalics@gmx.at,  emacs-devel@gnu.org,  dgutov@yandex.ru
> Date: Wed, 06 Aug 2014 16:48:12 -0400
> 
> >> > How is this different from displaying bitmaps that fill the whole
> >> > height of a screen line, so that adjacent bitmaps don't leave any
> >> > pixels between them?
> >> With a positive value of line-spacing, this approach doesn't suffice:
> >> you'll get gaps between the bitmaps.
> > Something that should be easy enough to fix, no doubt.
> 
> Currently, it's rather hard, since the height of a line depends on many
> other things (such as the content of the line) and there's no
> functionality to re-compute the pixmap to display in the margin once we
> know the line height.

We redisplay the fringe bitmaps every time we redisplay their lines,
so it should be easy to extend the bitmap to cover all of its height.

Re: Layered display API

[Eli Zaretskii]

> Date: Thu, 07 Aug 2014 00:49:01 +0400
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: rudalics@gmx.at, emacs-devel@gnu.org
> 
>     That you already have, don't you?  The problem is not display, AFAIU,
>     the problem is the decision where exactly to display it, and the
>     answer depends on the dimensions of the text and the window.
> 
> 
> "Below or above" are just the main choices. Correctly positioning it at the right line and column, without disturbing the text around, can still be a problem in advanced cases, like you mentioned here and in another thread.

So what would be the requirements for "correct positioning"?

>     If some features are missing to achieve the above (and they are not
>     the 2 mentioned below), then please spell them out, because I thought
>     the display part was already solved, once the layout is decided.
> 
> 
> Only if we use 1 overlay (the "crazy" approach) and only if we can easily get the text contained on the target rows, and there are physical buffer positions corresponding to the first and last lines where we want to display the popup (or thereabouts). If the whole text in the window is already rendered with `display' property, and we want to display the popup above only some part of it... good luck with that.

So text with display properties is one problem.  Any others?

>         1. If the buffer ends (shortly) after the current line, we're forced to
>         pad it with a newline, and then carefully undo that and restore the
>         buffer modification status.
> 
> 
>     Why can't you include the newline in the overlay string instead?
> 
> 
> Haven't tried yet. And in the overlay-a-line case, each of them would be zero-length, then? Guess that could work...

Sorry, I don't understand the question: what would be zero-length?

What I meant is this: if you need to display below the last line of
the buffer text, put the overlay at EOB, and include newlines in the
overlay string when you need to move to the next screen line.  To
align text horizontally you could use spaces or align-to display
properties in the string.

>         2. If the buffer is already heavily using the `display' text property,
>         or other similar ones, our tooltip positioning also breaks or works
>         unexpectedly. Example: the `report-emacs-bug' buffer
>         (https://github.com/company-mode/company-mode/issues/136).
> 
> 
>     This is indeed a missing feature.  It should be easy enough to provide
>     some special kind of display property that would overlay any other
>     displayed content
> 
> 
> That would leave a question where will it have to be set on. Would that new kind of overlay be able to be displayed far from the position it's set on?

No, I meant conceal the text produced by other display properties, and
display your overlay string instead.

>     Btw, why doesn't company use normal tooltips on GUI frames and
>     text-mode menus on a TTY?  Wouldn't that be better?
> 
> 
> I'm not 100% sure what's text-mode menu is

A normal menu, created by x-popup-menu, which now works on TTYs.  You
can pop up the menu at any place in the window text area.

> (by tooltip, do you mean `tooltip-show'?)

Yes, a real tooltip.

> maybe because when active, they take over event handling, so you can't move up and down the list with M-n/M-p (or any other bindings the user prefers)

Text-mode menus support navigation with cursor movement keys, like
C-p, C-n, up-arrow, and down-arrow.  More accurately, any key bound to
next/previous-line will navigate through the menu items as you'd
expect.

> press another combination of keys and see a doc buffer pop up

Help-echo in menus is supported, and shown in the echo area
automatically, so you could have all that documentation in the
help-echo string.

> or just continue typing in the buffer and see the popup with completion candidates get updated unobtrusively.

This can be achieved programmatically, by refreshing the menu when the
user types.

> And, at least in the tooltip's case, they can't be styled.

What do you mean by "styled"?

In any case, if something is missing in tooltip frames to support this
kind of applications, we had better added that.  IMO, showing
completion candidates in a tooltip will look much more professionally
than the current text emulation.  AFAIK, other IDEs do use tooltips in
these cases.

> Still, this way you can only use 2 colors

Why only 2?

> each line can only contain one bitmap

Fringe real estate is limited, so yes, there are limits to this.

An alternative is to use line-prefix or display margins, and display
images there.

>     Clicking on the fringes already works.
> 
> We do support buttons in buffers, even though we probably could add click handlers and then look up coordinates.

Again, you can display images in the margin or the line-prefix, and so
a button could be displayed there, I think.

> Suppose there are multiple modes using the fringe, and they all want to handle clicks. How would they handle that without conflicts?

The click on the fringe is interpreted in the context of the selected
window's buffer, AFAIR.

Re: Layered display API

[Dmitry Gutov]

On 08/07/2014 07:39 PM, Eli Zaretskii wrote:

> So what would be the requirements for "correct positioning"?

Display some strings in the buffer starting with the given line and 
column, correctly lining all following lines up vertically, to form a 
rectangle

Something like the following would work:

(make-popup :x-coord 340 :y-coord 200 :width ... :height ... :contents 
"foo\nbar\nbaz" :default-face ...)

  The keyword arguments are just for show, and the above assumes that 
popups aren't tied to specific buffers (or window, I guess). Making it 
buffer-local would be fine, too, I guess, then :x-coord and :y-coord 
might be replaced with :x-offset and :y-offset, specified relative to 
the popup's reference position in the buffer's contents.

> So text with display properties is one problem.  Any others?

- `line-prefix', as discussed.

- Different values of `line-height', `line-spacing', images in the buffer.

- Changes in some lines' appearance done some other way, like the 
separator line in `log-edit' buffers.

- The `intangible' property would probably also cause some problems for 
our current implementation.

- Proportional fonts, obviously.

- Not being able to display the popup over the mode-line and window 
separators. This would be useful for completion when typing in the 
minibuffer.

- The "one big overlay" approach conflicts with other packages that use 
overlays to put information on the margins or fringes, such as linum and 
diff-hl. The lines displaying our popup lose the linum and diff-hl 
indicators.

> Sorry, I don't understand the question: what would be zero-length?

An overlay where BEG = END. It wasn't a very meaningful question, I guess.

> What I meant is this: if you need to display below the last line of
> the buffer text, put the overlay at EOB, and include newlines in the
> overlay string when you need to move to the next screen line.  To
> align text horizontally you could use spaces or align-to display
> properties in the string.

Yes, I might try this, as soon as there's some suggestion how to handle 
the problem of `line-prefix' in this multi-overlay approach.

>>      This is indeed a missing feature.  It should be easy enough to provide
>>      some special kind of display property that would overlay any other
>>      displayed content
>>
>>
>> That would leave a question where will it have to be set on. Would that new kind of overlay be able to be displayed far from the position it's set on?
>
> No, I meant conceal the text produced by other display properties, and
> display your overlay string instead.

It doesn't seem to be solving much: if I want to display something in 
the middle of, say, large `display' text, there's no specific span of 
text to set that new property on.

> Text-mode menus support navigation with cursor movement keys, like
> C-p, C-n, up-arrow, and down-arrow.  More accurately, any key bound to
> next/previous-line will navigate through the menu items as you'd
> expect.

We have different commands that move up and down, with specific logic 
behind them. Allowing the menu to handle those keys doesn't sound like a 
good idea.

>> press another combination of keys and see a doc buffer pop up
>
> Help-echo in menus is supported, and shown in the echo area
> automatically, so you could have all that documentation in the
> help-echo string.

It _might_ help with displaying the one-line help we already show in the 
echo area (although the programmatic interface seems to be incompatible: 
we only ask the backend for that information when the candidate is 
selected), but it definitely won't help with popping up the 
documentation buffer.

>> or just continue typing in the buffer and see the popup with completion candidates get updated unobtrusively.
>
> This can be achieved programmatically, by refreshing the menu when the
> user types.

Could you elaborate on that? Would that work via post-command-hook?

>> And, at least in the tooltip's case, they can't be styled.
>
> What do you mean by "styled"?

Displayed with different background color, for example.

> In any case, if something is missing in tooltip frames to support this
> kind of applications, we had better added that.  IMO, showing
> completion candidates in a tooltip will look much more professionally
> than the current text emulation.  AFAIK, other IDEs do use tooltips in
> these cases.

Of course.

>> Still, this way you can only use 2 colors
>
> Why only 2?

The fringe foreground color and the fringe background color. The fringe 
face may vary between lines, but a bitmap instance ends up using only 
two colors at a time.

>> each line can only contain one bitmap
>
> Fringe real estate is limited, so yes, there are limits to this.

Fringe size is not fixed, the user (or packages) can change it. Even 
with the current default size, I could use being able to display several 
bitmaps at a time: for example, the simple-looking indicator from 
diff-hl and, above it, `?' or `!` from flymake.

> An alternative is to use line-prefix or display margins, and display
> images there.

line-prefix is again something only one package can use at a time.

Could I display some vertical graphic in the margins that smoothly spans 
several lines?

>> Suppose there are multiple modes using the fringe, and they all want to handle clicks. How would they handle that without conflicts?
>
> The click on the fringe is interpreted in the context of the selected
> window's buffer, AFAIR.

And? Suppose there are multiple minor modes in that buffer that might 
like to handle that click?

Re: Layered display API

[Eli Zaretskii]

> Date: Mon, 11 Aug 2014 05:14:24 +0400
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: rudalics@gmx.at, emacs-devel@gnu.org
> 
> (make-popup :x-coord 340 :y-coord 200 :width ... :height ... :contents 
> "foo\nbar\nbaz" :default-face ...)

Compare this with x-popup-menu: the similarity is striking.  Which is
why I suggested to use menus on TTYs.

> > So text with display properties is one problem.  Any others?
> 
> - `line-prefix', as discussed.
> 
> - Different values of `line-height', `line-spacing', images in the buffer.
> 
> - Changes in some lines' appearance done some other way, like the 
> separator line in `log-edit' buffers.
> 
> - The `intangible' property would probably also cause some problems for 
> our current implementation.
> 
> - Proportional fonts, obviously.
> 
> - Not being able to display the popup over the mode-line and window 
> separators. This would be useful for completion when typing in the 
> minibuffer.
> 
> - The "one big overlay" approach conflicts with other packages that use 
> overlays to put information on the margins or fringes, such as linum and 
> diff-hl. The lines displaying our popup lose the linum and diff-hl 
> indicators.

Given these requirements, I think the only 2 alternatives to implement
them for GUI frames are:

  . tooltip frames, suitably beefed up to provide some features they
    currently don't, like more control of colors and faces

  . some low-level graphics feature that would allow to overlay an
    arbitrary pixmap on the window display (this is far from my area
    of expertise, so I cannot say anything more about this
    possibility)

Nothing else seems possible, because if we rely on the current display
engine, we will be unable to fully control at least the vertical
position of the lines in your popup, and in some cases (e.g.,
line-prefix) also the horizontal position.  The current display engine
is limited to displaying various "display elements" on a canvas, where
each row spans the entire width of a window, and its vertical position
is calculated to leave enough space for the tallest display element of
the row.

> > What I meant is this: if you need to display below the last line of
> > the buffer text, put the overlay at EOB, and include newlines in the
> > overlay string when you need to move to the next screen line.  To
> > align text horizontally you could use spaces or align-to display
> > properties in the string.
> 
> Yes, I might try this, as soon as there's some suggestion how to handle 
> the problem of `line-prefix' in this multi-overlay approach.

Find the longest prefix and align everything so that the left edge
keeps clear of that?

> >>      This is indeed a missing feature.  It should be easy enough to provide
> >>      some special kind of display property that would overlay any other
> >>      displayed content
> >>
> >>
> >> That would leave a question where will it have to be set on. Would that new kind of overlay be able to be displayed far from the position it's set on?
> >
> > No, I meant conceal the text produced by other display properties, and
> > display your overlay string instead.
> 
> It doesn't seem to be solving much: if I want to display something in 
> the middle of, say, large `display' text, there's no specific span of 
> text to set that new property on.

You'd put it on the overlay string.

> > Text-mode menus support navigation with cursor movement keys, like
> > C-p, C-n, up-arrow, and down-arrow.  More accurately, any key bound to
> > next/previous-line will navigate through the menu items as you'd
> > expect.
> 
> We have different commands that move up and down, with specific logic 
> behind them.

Examples?

> Allowing the menu to handle those keys doesn't sound like a good
> idea.

We could generalize the current menu code to allow something like
that.

> >> press another combination of keys and see a doc buffer pop up
> >
> > Help-echo in menus is supported, and shown in the echo area
> > automatically, so you could have all that documentation in the
> > help-echo string.
> 
> It _might_ help with displaying the one-line help we already show in the 
> echo area (although the programmatic interface seems to be incompatible: 
> we only ask the backend for that information when the candidate is 
> selected), but it definitely won't help with popping up the 
> documentation buffer.

You can always exit the menu, pop up the documentation buffer, then
redraw the menu, all this programmatically.

> >> or just continue typing in the buffer and see the popup with completion candidates get updated unobtrusively.
> >
> > This can be achieved programmatically, by refreshing the menu when the
> > user types.
> 
> Could you elaborate on that?

Same as above: exit the menu, do what you need, then redraw it.

> Would that work via post-command-hook?

No.  The current menu code simply ignores any commands it wasn't
programmed to understand and act upon.

> > An alternative is to use line-prefix or display margins, and display
> > images there.
> 
> line-prefix is again something only one package can use at a time.

That is a problem you won't be able to escape.  Emacs modes aren't
supposed to fight each other; if they do, the user is in trouble.

> Could I display some vertical graphic in the margins that smoothly spans 
> several lines?

Emacs can display image slices (see the documentation of the 'display'
property), so this should be possible.  I didn't try it, though.

> >> Suppose there are multiple modes using the fringe, and they all want to handle clicks. How would they handle that without conflicts?
> >
> > The click on the fringe is interpreted in the context of the selected
> > window's buffer, AFAIR.
> 
> And? Suppose there are multiple minor modes in that buffer that might 
> like to handle that click?

Again, fights like that should be resolved "by other means".

Re: Layered display API

[Dmitry Gutov]

On 08/11/2014 07:01 PM, Eli Zaretskii wrote:

> Compare this with x-popup-menu: the similarity is striking.  Which is
> why I suggested to use menus on TTYs.

Yes, it would be nice if we can use them. However, the fact that menus 
handle evens themselves (or try to) makes me think it's not the cleanest 
approach.

> Given these requirements, I think the only 2 alternatives to implement
> them for GUI frames are:
>
>    . tooltip frames, suitably beefed up <...>
>
>    . some low-level graphics feature <...>
>
> Nothing else seems possible, because if we rely on the current display
> engine, we will be unable to fully control at least the vertical
> position of the lines in your popup, and in some cases (e.g.,
> line-prefix) also the horizontal position.

Not even menus? My understanding was they might be able to satisfy most 
of the requirements, aside from working with proportional fonts.

>> Yes, I might try this, as soon as there's some suggestion how to handle
>> the problem of `line-prefix' in this multi-overlay approach.
>
> Find the longest prefix and align everything so that the left edge
> keeps clear of that?

Yes, sounds like a reasonable simplification. This would be a step back 
in terms of functionality, though, but possibly a justified one.

>>> No, I meant conceal the text produced by other display properties, and
>>> display your overlay string instead.
>>
>> It doesn't seem to be solving much: if I want to display something in
>> the middle of, say, large `display' text, there's no specific span of
>> text to set that new property on.
>
> You'd put it on the overlay string.

Let me rephrase the previous message: "...there's no specific span of 
text to put the overlay on". Or that's my understanding.

>>> Text-mode menus support navigation with cursor movement keys, like
>>> C-p, C-n, up-arrow, and down-arrow.  More accurately, any key bound to
>>> next/previous-line will navigate through the menu items as you'd
>>> expect.
>>
>> We have different commands that move up and down, with specific logic
>> behind them.
>
> Examples?

A simple example:

     (define-key keymap (kbd "M-n") 'company-select-next)
     (define-key keymap (kbd "M-p") 'company-select-previous)
     (define-key keymap (kbd "<down>") 'company-select-next-or-abort)
     (define-key keymap (kbd "<up>") 'company-select-previous-or-abort)

The last two abort completion, do some magic and push the event back 
into `unread-command-events'. This happens if <up> is pressed when the 
first candidate is selected, or <down> is pressed when the last one is.

Among other things, `company-select-next' and its counterpart save the 
number of the currently selected completion candidate, and the other 
commands and front-ends use that to display information related to it, 
and for correct visualization.

>> Allowing the menu to handle those keys doesn't sound like a good
>> idea.
>
> We could generalize the current menu code to allow something like
> that.

Sounds promising.

> You can always exit the menu, pop up the documentation buffer, then
> redraw the menu, all this programmatically.

Will the menu allow me to customize the keymap it's using? To be able to 
invoke the `company-show-doc-buffer' command in the first place?

> Same as above: exit the menu, do what you need, then redraw it.
>
>> Would that work via post-command-hook?
>
> No.  The current menu code simply ignores any commands it wasn't
> programmed to understand and act upon.

Ignores, or allows them to go through?

> That is a problem you won't be able to escape.  Emacs modes aren't
> supposed to fight each other; if they do, the user is in trouble.

Some packages's fringe indicators might be incompatible by their 
essence, there's not much we could do there.

Others could co-exist. If the fringe allowed "layered" display of 
bitmaps, for example, flymake could assign its overlays a higher 
priority and happily coexist with diff-hl indicators.

>> Could I display some vertical graphic in the margins that smoothly spans
>> several lines?
>
> Emacs can display image slices (see the documentation of the 'display'
> property), so this should be possible.  I didn't try it, though.

Thanks, I'll look it up sometime.

>> And? Suppose there are multiple minor modes in that buffer that might
>> like to handle that click?
>
> Again, fights like that should be resolved "by other means".

In the buffer contents, they are resolved with buttons. Why not on the 
fringe?

Re: Layered display API

[Stefan Monnier]

>> Compare this with x-popup-menu: the similarity is striking.  Which is
>> why I suggested to use menus on TTYs.
> Yes, it would be nice if we can use them. However, the fact that menus
> handle evens themselves (or try to) makes me think it's not the
> cleanest approach.

From a display point of view, I think the "tty menus" approach is indeed
the cleanest solution when running on a tty.  But they can't be used
as-is for lack of flexibility w.r.t key-bindings and appearance (we
don't really need borders for Company menus, but we do need control
over colors).

In a GUI frame, OTOH, we'd be much better off with a GUI window
(something akin to a tooltip frame).


        Stefan

Re: Layered display API

[Eli Zaretskii]

> Date: Wed, 13 Aug 2014 06:42:57 +0400
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: rudalics@gmx.at, emacs-devel@gnu.org
> 
> On 08/11/2014 07:01 PM, Eli Zaretskii wrote:
> 
> > Compare this with x-popup-menu: the similarity is striking.  Which is
> > why I suggested to use menus on TTYs.
> 
> Yes, it would be nice if we can use them. However, the fact that menus 
> handle evens themselves (or try to) makes me think it's not the cleanest 
> approach.

The menu code can be extended.  More accurately, we could refactor the
menu code to provide the capabilities of overlaying text on window
display for other Lisp features.

> > Given these requirements, I think the only 2 alternatives to implement
> > them for GUI frames are:
> >
> >    . tooltip frames, suitably beefed up <...>
> >
> >    . some low-level graphics feature <...>
> >
> > Nothing else seems possible, because if we rely on the current display
> > engine, we will be unable to fully control at least the vertical
> > position of the lines in your popup, and in some cases (e.g.,
> > line-prefix) also the horizontal position.
> 
> Not even menus? My understanding was they might be able to satisfy most 
> of the requirements, aside from working with proportional fonts.

At least with some toolkits, GUI menus have decorations, which will
look strange if we use them in this capacity.

> >>> No, I meant conceal the text produced by other display properties, and
> >>> display your overlay string instead.
> >>
> >> It doesn't seem to be solving much: if I want to display something in
> >> the middle of, say, large `display' text, there's no specific span of
> >> text to set that new property on.
> >
> > You'd put it on the overlay string.
> 
> Let me rephrase the previous message: "...there's no specific span of 
> text to put the overlay on".

The buffer text that is covered by the "large display property" is
still there, right?  It just isn't displayed.

> Will the menu allow me to customize the keymap it's using?

Of course!  This is Emacs.  See the end of menu-bar.el: the menu
navigation keys are defined as a keymap.

> > Same as above: exit the menu, do what you need, then redraw it.
> >
> >> Would that work via post-command-hook?
> >
> > No.  The current menu code simply ignores any commands it wasn't
> > programmed to understand and act upon.
> 
> Ignores, or allows them to go through?

Ignores.  They are processed and produce no effect.

> >> And? Suppose there are multiple minor modes in that buffer that might
> >> like to handle that click?
> >
> > Again, fights like that should be resolved "by other means".
> 
> In the buffer contents, they are resolved with buttons. Why not on the 
> fringe?

I don't see how buttons can resolve conflicts.  Maybe I'm missing
something.

Re: Layered display API

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Eli Zaretskii <eliz@gnu.org>,  rudalics@gmx.at,  emacs-devel@gnu.org
> Date: Wed, 13 Aug 2014 08:46:59 -0400
> 
> From a display point of view, I think the "tty menus" approach is indeed
> the cleanest solution when running on a tty.  But they can't be used
> as-is for lack of flexibility w.r.t key-bindings and appearance (we
> don't really need borders for Company menus, but we do need control
> over colors).
> 
> In a GUI frame, OTOH, we'd be much better off with a GUI window
> (something akin to a tooltip frame).

I agree.

Re: Layered display API

[Dmitry Gutov]

On 08/13/2014 04:46 PM, Stefan Monnier wrote:

> (we
> don't really need borders for Company menus, but we do need control
> over colors).

Yes, we use a one-column/row margin instead of borders. Works pretty 
well. We'll need to be able to "paint" the non-interactive scrollbar, at 
least, like we do in the current popup.

> In a GUI frame, OTOH, we'd be much better off with a GUI window
> (something akin to a tooltip frame).

When it's ready, yes. Until then, tty menus should work pretty well in 
the graphical mode, too. If they're available, of course.

Re: Layered display API

[Eli Zaretskii]

> Date: Wed, 13 Aug 2014 20:27:27 +0400
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: Eli Zaretskii <eliz@gnu.org>, rudalics@gmx.at, emacs-devel@gnu.org
> 
> tty menus should work pretty well in the graphical mode, too. If
> they're available, of course.

TTY menus work only on text-mode frames.  Sorry.

Re: Layered display API

[Stefan Monnier]

>> In a GUI frame, OTOH, we'd be much better off with a GUI window
>> (something akin to a tooltip frame).
> When it's ready, yes.

I don't think it'll get ready on its own, tho ;-)

But you might like to try a non-toolkit build of Emacs and use the
tooltip frames used in that case (e.g. IIRC they understand faces, for
one).
Then we should somehow make those "non-toolkit-tooltip-frames" available
in all builds.


        Stefan

Re: Layered display API

[Bo Lin]

Hi,

Eli Zaretskii <eliz@gnu.org> writes:

>> > What I meant is this: if you need to display below the last line of
>> > the buffer text, put the overlay at EOB, and include newlines in the
>> > overlay string when you need to move to the next screen line.  To
>> > align text horizontally you could use spaces or align-to display
>> > properties in the string.
>> 
>> Yes, I might try this, as soon as there's some suggestion how to handle 
>> the problem of `line-prefix' in this multi-overlay approach.
>
> Find the longest prefix and align everything so that the left edge
> keeps clear of that?

Zero length overlays don't get displayed so this won't work when the
buffer is empty. Not a game breaker of course, but for a completion
tooltip it's still an undesirable defect.

>> >>      This is indeed a missing feature.  It should be easy enough to provide
>> >>      some special kind of display property that would overlay any other
>> >>      displayed content
>> >>
>> >>
>> >> That would leave a question where will it have to be set on.
>> >> Would that new kind of overlay be able to be displayed far
>> >> from the position it's set on?
>> >
>> > No, I meant conceal the text produced by other display properties, and
>> > display your overlay string instead.
>> 
>> It doesn't seem to be solving much: if I want to display something in 
>> the middle of, say, large `display' text, there's no specific span of 
>> text to set that new property on.
>
> You'd put it on the overlay string.

Ideally, for a popup tooltip, it should cover only the small
rectangular area that is the tooltip, while leaving everything else
intact to minimize visual disturbances. This is, AFAICT, currently
impossible to achieve if you have to conceal anything with a
'display property, because: 1) in the simplest case the 'display is
a string, but you don't know the proper display width of each
character; and 2) the 'display can be not-strings.

-Bo

Re: Layered display API

[Dmitry Gutov]

On 08/13/2014 07:28 PM, Eli Zaretskii wrote:

> The menu code can be extended.  More accurately, we could refactor the
> menu code to provide the capabilities of overlaying text on window
> display for other Lisp features.

Cool. Like Stefan suggested, I'll try playing with a toolkit-less popup 
first, and then you could see if you can provide a similar API with tty 
menus.

I've been under impression that "tty menus" could work in graphical 
mode, too, but now I understand that they're non-portable, like the name 
suggests. That's too bad.

>> Not even menus? My understanding was they might be able to satisfy most
>> of the requirements, aside from working with proportional fonts.
>
> At least with some toolkits, GUI menus have decorations, which will
> look strange if we use them in this capacity.

Yep, I meant "tty menus" there. Not an option.

>>>>> No, I meant conceal the text produced by other display properties, and
>>>>> display your overlay string instead.
>>>>
>>>> It doesn't seem to be solving much: if I want to display something in
>>>> the middle of, say, large `display' text, there's no specific span of
>>>> text to set that new property on.
>>>
>>> You'd put it on the overlay string.
>>
>> Let me rephrase the previous message: "...there's no specific span of
>> text to put the overlay on".
>
> The buffer text that is covered by the "large display property" is
> still there, right?  It just isn't displayed.

Why use the special new property, then? Just put a new overlay over it. 
If it also has `display' and higher priority, it would take over.

>> Will the menu allow me to customize the keymap it's using?
>
> Of course!  This is Emacs.  See the end of menu-bar.el: the menu
> navigation keys are defined as a keymap.

So, you would suggest I dynamically rebind `tty-menu-navigation-map'?

> I don't see how buttons can resolve conflicts.  Maybe I'm missing
> something.

If one piece of code creates one button, and another piece of code 
creates another button, they can put different handlers into the button 
properties, so the results of clicking of these buttons will be 
different, even if they are in the same buffer, on the same line.

Same could be done the fringe, at least in theory.

Re: Layered display API

[Eli Zaretskii]

> From: Bo Lin <bo@dreamsphere.org>
> Cc: Dmitry Gutov <dgutov@yandex.ru>,  rudalics@gmx.at,  emacs-devel@gnu.org
> Date: Wed, 13 Aug 2014 22:06:26 -0400
> 
> Hi,
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> > What I meant is this: if you need to display below the last line of
> >> > the buffer text, put the overlay at EOB, and include newlines in the
> >> > overlay string when you need to move to the next screen line.  To
> >> > align text horizontally you could use spaces or align-to display
> >> > properties in the string.
> >> 
> >> Yes, I might try this, as soon as there's some suggestion how to handle 
> >> the problem of `line-prefix' in this multi-overlay approach.
> >
> > Find the longest prefix and align everything so that the left edge
> > keeps clear of that?
> 
> Zero length overlays don't get displayed so this won't work when the
> buffer is empty.

When a buffer is empty, there are no line prefixes, right?  Or did I
misunderstand what you eman?

> >> >>      This is indeed a missing feature.  It should be easy enough to provide
> >> >>      some special kind of display property that would overlay any other
> >> >>      displayed content
> >> >>
> >> >>
> >> >> That would leave a question where will it have to be set on.
> >> >> Would that new kind of overlay be able to be displayed far
> >> >> from the position it's set on?
> >> >
> >> > No, I meant conceal the text produced by other display properties, and
> >> > display your overlay string instead.
> >> 
> >> It doesn't seem to be solving much: if I want to display something in 
> >> the middle of, say, large `display' text, there's no specific span of 
> >> text to set that new property on.
> >
> > You'd put it on the overlay string.
> 
> Ideally, for a popup tooltip, it should cover only the small
> rectangular area that is the tooltip, while leaving everything else
> intact to minimize visual disturbances. This is, AFAICT, currently
> impossible to achieve if you have to conceal anything with a
> 'display property, because: 1) in the simplest case the 'display is
> a string, but you don't know the proper display width of each
> character; and 2) the 'display can be not-strings.

I wasn't talking about the currently existing display properties, I
was talking about a new property with the capabilities I described.

Re: Layered display API

[Eli Zaretskii]

> Date: Thu, 14 Aug 2014 06:35:11 +0400
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: rudalics@gmx.at, emacs-devel@gnu.org
> 
> I've been under impression that "tty menus" could work in graphical 
> mode, too, but now I understand that they're non-portable, like the name 
> suggests. That's too bad.

Doing the same on GUI frames would hit all the difficulties that we've
been discussing in this thread, due to proportional and variable-size
fonts, and other display features that don't exist on a TTY.  More
importantly, the TTY menus were developed because there were no menus
on text-mode frames, a problem that didn't exist on GUI frames.

> Why use the special new property, then? Just put a new overlay over it. 
> If it also has `display' and higher priority, it would take over.

Because you want to get priority not only over other overlays, but
also over display properties and maybe other things.

> >> Will the menu allow me to customize the keymap it's using?
> >
> > Of course!  This is Emacs.  See the end of menu-bar.el: the menu
> > navigation keys are defined as a keymap.
> 
> So, you would suggest I dynamically rebind `tty-menu-navigation-map'?

If you need that, yes.

Re: Layered display API

[Dmitry Gutov]

On 08/14/2014 06:53 AM, Eli Zaretskii wrote:

> Doing the same on GUI frames would hit all the difficulties that we've
> been discussing in this thread, due to proportional and variable-size
> fonts, and other display features that don't exist on a TTY.

Guess so. We've been living without non-monospaced fonts support for 
quite a while, though, so that wouldn't be much of a problem, if the 
menus solved at least some other problems.

>> Why use the special new property, then? Just put a new overlay over it.
>> If it also has `display' and higher priority, it would take over.
>
> Because you want to get priority not only over other overlays, but
> also over display properties and maybe other things.

Doesn't any overlay's `display' get priority over text's `display'?

If I want to get priority over "maybe other things", the first problem 
would how to know the list of all those things, and to retrieve the text 
that gets displayed in stead of each of those things. Which would be, 
again, reimplementing the display engine.

Re: Layered display API

[Eli Zaretskii]

> Date: Thu, 14 Aug 2014 17:12:35 +0400
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: rudalics@gmx.at, emacs-devel@gnu.org
> 
> >> Why use the special new property, then? Just put a new overlay over it.
> >> If it also has `display' and higher priority, it would take over.
> >
> > Because you want to get priority not only over other overlays, but
> > also over display properties and maybe other things.
> 
> Doesn't any overlay's `display' get priority over text's `display'?

I don't remember, but if it does, it's an implementation detail
subject to change without notice.

> If I want to get priority over "maybe other things", the first problem 
> would how to know the list of all those things, and to retrieve the text 
> that gets displayed in stead of each of those things. Which would be, 
> again, reimplementing the display engine.

This property we are discussing (that doesn't yet exist) will be acted
upon by the display engine.  The display engine always knows what
"things" are there at point, and the supporting logic for this
property will cause the display engine to ignore all the other
"things" and display only the overlay that has this property.  At
least that's the theory.

Re: Layered display API

[Bo Lin]

Eli Zaretskii <eliz@gnu.org> writes:

>> >> > What I meant is this: if you need to display below the last line of
>> >> > the buffer text, put the overlay at EOB, and include newlines in the
>> >> > overlay string when you need to move to the next screen line.  To
>> >> > align text horizontally you could use spaces or align-to display
>> >> > properties in the string.
>> >> 
>> >> Yes, I might try this, as soon as there's some suggestion how to handle 
>> >> the problem of `line-prefix' in this multi-overlay approach.
>> >
>> > Find the longest prefix and align everything so that the left edge
>> > keeps clear of that?
>> 
>> Zero length overlays don't get displayed so this won't work when the
>> buffer is empty.
>
> When a buffer is empty, there are no line prefixes, right?  Or did I
> misunderstand what you eman?

I thought this was about avoid padding the buffer text with
newlines?

>> >> >>      This is indeed a missing feature.  It should be easy enough to provide
>> >> >>      some special kind of display property that would overlay any other
>> >> >>      displayed content
>> >> >>
>> >> >>
>> >> >> That would leave a question where will it have to be set on.
>> >> >> Would that new kind of overlay be able to be displayed far
>> >> >> from the position it's set on?
>> >> >
>> >> > No, I meant conceal the text produced by other display properties, and
>> >> > display your overlay string instead.
>> >> 
>> >> It doesn't seem to be solving much: if I want to display something in 
>> >> the middle of, say, large `display' text, there's no specific span of 
>> >> text to set that new property on.
>> >
>> > You'd put it on the overlay string.
>> 
>> Ideally, for a popup tooltip, it should cover only the small
>> rectangular area that is the tooltip, while leaving everything else
>> intact to minimize visual disturbances. This is, AFAICT, currently
>> impossible to achieve if you have to conceal anything with a
>> 'display property, because: 1) in the simplest case the 'display is
>> a string, but you don't know the proper display width of each
>> character; and 2) the 'display can be not-strings.
>
> I wasn't talking about the currently existing display properties, I
> was talking about a new property with the capabilities I described.

Oh, I see. Yeah, that would be very nice.

-Bo

Re: Layered display API

[Eli Zaretskii]

> From: Bo Lin <bo@dreamsphere.org>
> Cc: rudalics@gmx.at,  emacs-devel@gnu.org,  dgutov@yandex.ru
> Date: Thu, 14 Aug 2014 12:08:20 -0400
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> >> > What I meant is this: if you need to display below the last line of
> >> >> > the buffer text, put the overlay at EOB, and include newlines in the
> >> >> > overlay string when you need to move to the next screen line.  To
> >> >> > align text horizontally you could use spaces or align-to display
> >> >> > properties in the string.
> >> >> 
> >> >> Yes, I might try this, as soon as there's some suggestion how to handle 
> >> >> the problem of `line-prefix' in this multi-overlay approach.
> >> >
> >> > Find the longest prefix and align everything so that the left edge
> >> > keeps clear of that?
> >> 
> >> Zero length overlays don't get displayed so this won't work when the
> >> buffer is empty.
> >
> > When a buffer is empty, there are no line prefixes, right?  Or did I
> > misunderstand what you eman?
> 
> I thought this was about avoid padding the buffer text with
> newlines?

Sorry, it wasn't clear, as the previous citations talked about both.

So turning to the padding the buffer: it's not about padding with
newlines, it's about including newlines in overlay string.  After the
newline, the overlay string would have the text to be displayed beyond
the EOB.

Re: Layered display API

[Bo Lin]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Bo Lin <bo@dreamsphere.org>
>> Cc: rudalics@gmx.at,  emacs-devel@gnu.org,  dgutov@yandex.ru
>> Date: Thu, 14 Aug 2014 12:08:20 -0400
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> >> > What I meant is this: if you need to display below the last line of
>> >> >> > the buffer text, put the overlay at EOB, and include newlines in the
>> >> >> > overlay string when you need to move to the next screen line.  To
>> >> >> > align text horizontally you could use spaces or align-to display
>> >> >> > properties in the string.
>> >> >> 
>> >> >> Yes, I might try this, as soon as there's some suggestion how to handle 
>> >> >> the problem of `line-prefix' in this multi-overlay approach.
>> >> >
>> >> > Find the longest prefix and align everything so that the left edge
>> >> > keeps clear of that?
>> >> 
>> >> Zero length overlays don't get displayed so this won't work when the
>> >> buffer is empty.
>> >
>> > When a buffer is empty, there are no line prefixes, right?  Or did I
>> > misunderstand what you eman?
>> 
>> I thought this was about avoid padding the buffer text with
>> newlines?
>
> Sorry, it wasn't clear, as the previous citations talked about both.
>
> So turning to the padding the buffer: it's not about padding with
> newlines, it's about including newlines in overlay string.  After the
> newline, the overlay string would have the text to be displayed beyond
> the EOB.

Ah, I just realized the 'before/after-string properties does get
displayed even on zero length overlays. So yeah, this does work,
sorry for noise.

-Bo

Re: Layered display API

[Dmitry Gutov]

On 08/14/2014 07:20 PM, Eli Zaretskii wrote:

>> Doesn't any overlay's `display' get priority over text's `display'?
>
> I don't remember, but if it does, it's an implementation detail
> subject to change without notice.

...

> This property we are discussing (that doesn't yet exist) will be acted
> upon by the display engine.  The display engine always knows what
> "things" are there at point, and the supporting logic for this
> property will cause the display engine to ignore all the other
> "things" and display only the overlay that has this property.  At
> least that's the theory.

Well, since we don't only need to replace the displayed characters, but 
also modify them, this doesn't do a lot of work for us.

 From what I understand, you're suggesting a property that would act 
like a combination of overlay + display does currently. Why not just 
document that current behavior and then stick to it, rather than 
introduce the new property?

Re: Layered display API

[Eli Zaretskii]

> Date: Fri, 15 Aug 2014 05:20:12 +0400
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: rudalics@gmx.at, emacs-devel@gnu.org
> 
> > This property we are discussing (that doesn't yet exist) will be acted
> > upon by the display engine.  The display engine always knows what
> > "things" are there at point, and the supporting logic for this
> > property will cause the display engine to ignore all the other
> > "things" and display only the overlay that has this property.  At
> > least that's the theory.
> 
> Well, since we don't only need to replace the displayed characters, but 
> also modify them, this doesn't do a lot of work for us.

Not sure why you would need to modify them.  My understanding is that
you include in the overlay some of the displayed text, and also
include your own text.

What I'm suggesting will allow you not to duplicate the displayed
text, but just add an overlay with your own.

>  From what I understand, you're suggesting a property that would act 
> like a combination of overlay + display does currently. Why not just 
> document that current behavior and then stick to it, rather than 
> introduce the new property?

See above: because what exists doesn't do the job for you well enough.
Copying into your overlay existing text from buffer, other overlays,
and display strings is fragile design with known deficiencies (which
were revealed in this thread).  Having a special property that would
avoid all that is a win, IMO.  For example, you will be able to stop
worrying about line-prefix and images.

Re: Layered display API

[Dmitry Gutov]

On 08/15/2014 10:39 AM, Eli Zaretskii wrote:

>> Well, since we don't only need to replace the displayed characters, but
>> also modify them, this doesn't do a lot of work for us.
>
> Not sure why you would need to modify them.  My understanding is that
> you include in the overlay some of the displayed text, and also
> include your own text.

Yes, we take the displayed text, *modify* its copy to overwrite some 
pieces of it with our text, and put it on our overlay. So one of the 
hard parts, if done perfectly, would be to obtain the displayed text 
correctly.

> What I'm suggesting will allow you not to duplicate the displayed
> text, but just add an overlay with your own.

Sorry, I'm getting strongly mixed signals here: just recently, when I 
enumerated a list of requirements for displaying our popup, you replied:

"""
Given these requirements, I think the only 2 alternatives to implement
them for GUI frames are:

   . tooltip frames, suitably beefed up to provide some features they
     currently don't, like more control of colors and faces

   . some low-level graphics feature that would allow to overlay an
     arbitrary pixmap on the window display (this is far from my area
     of expertise, so I cannot say anything more about this
     possibility)

Nothing else seems possible, because if we rely on the current display
engine, we will be unable to fully control at least the vertical
position of the lines in your popup, and in some cases (e.g.,
line-prefix) also the horizontal position.
"""

So, which part of the job would the new text property perform, and which 
part of it will be left to us to implement?

> See above: because what exists doesn't do the job for you well enough.
> Copying into your overlay existing text from buffer, other overlays,
> and display strings is fragile design with known deficiencies (which
> were revealed in this thread).  Having a special property that would
> avoid all that is a win, IMO.  For example, you will be able to stop
> worrying about line-prefix and images.

Let's imagine this sample case:

   (insert "e\naaaaaa\n")
   (insert (propertize " " 'display "bbbbbb\ncccccc")

(By the way, try this out in *scratch* and do some C-n, C-p. Do you see 
the movement error? Here, the cursor always jumps over the "aaa..." 
line when moving toward the beginning of the buffer.)

Let's say the point is at the end of the first line (after "e"), and 
we'd like to display a popup under it, 4 columns wide and 2 lines tall. 
If the popup is all filled with "x" characters, it should look like this:

e.
axxxxa
bxxxxb
cccccc

If the new property was already implemented, what would the code to do 
this look like?

Re: Layered display API

[Eli Zaretskii]

> Date: Sat, 16 Aug 2014 03:03:33 +0400
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: rudalics@gmx.at, emacs-devel@gnu.org
> 
> > What I'm suggesting will allow you not to duplicate the displayed
> > text, but just add an overlay with your own.
> 
> Sorry, I'm getting strongly mixed signals here: just recently, when I 
> enumerated a list of requirements for displaying our popup, you replied:
> 
> """
> Given these requirements, I think the only 2 alternatives to implement
> them for GUI frames are:
> 
>    . tooltip frames, suitably beefed up to provide some features they
>      currently don't, like more control of colors and faces
> 
>    . some low-level graphics feature that would allow to overlay an
>      arbitrary pixmap on the window display (this is far from my area
>      of expertise, so I cannot say anything more about this
>      possibility)
> 
> Nothing else seems possible, because if we rely on the current display
> engine, we will be unable to fully control at least the vertical
> position of the lines in your popup, and in some cases (e.g.,
> line-prefix) also the horizontal position.
> """
> 
> So, which part of the job would the new text property perform, and which 
> part of it will be left to us to implement?

None.  The new property is yet another possibility, IMO inferior to
the 2 I suggested above.

> Let's imagine this sample case:
> 
>    (insert "e\naaaaaa\n")
>    (insert (propertize " " 'display "bbbbbb\ncccccc")
> 
> (By the way, try this out in *scratch* and do some C-n, C-p. Do you see 
> the movement error? Here, the cursor always jumps over the "aaa..." 
> line when moving toward the beginning of the buffer.)

Please file a bug report.

> Let's say the point is at the end of the first line (after "e"), and 
> we'd like to display a popup under it, 4 columns wide and 2 lines tall. 
> If the popup is all filled with "x" characters, it should look like this:
> 
> e.
> axxxxa
> bxxxxb
> cccccc
> 
> If the new property was already implemented, what would the code to do 
> this look like?

Something like this:

  (put-text-property POS1 POS1+4 'eliz "xxxx")
  (put-text-property 1 5 STRING 'eliz "xxxx")
  (put-text-property 8 12 STRING 'eliz "xxxx")

where POS1 is the buffer position of the second 'a', and STRING is the
string that is the value of the 'display' property.

Re: Layered display API

[Dmitry Gutov]

On 08/16/2014 11:41 AM, Eli Zaretskii wrote:

> Please file a bug report.

http://debbugs.gnu.org/cgi/bugreport.cgi?bug=18276

> Something like this:
>
>    (put-text-property POS1 POS1+4 'eliz "xxxx")
>    (put-text-property 1 5 STRING 'eliz "xxxx")
>    (put-text-property 8 12 STRING 'eliz "xxxx")
>
> where POS1 is the buffer position of the second 'a', and STRING is the
> string that is the value of the 'display' property.

Yes, this doesn't sound too good: it will require modifying the buffer 
contents, as opposed to using an overlay, which can be removed at once.

Since we'll have to modify display strings, the code will have to 
account for the display logic, line-prefix, before-string, etc, anyway, 
if only to calculate which part of our "new" text falls on each 
respective display property, or on the "plain" buffer text.