Re: Layered display API

[Eli Zaretskii]

> Date: Mon, 11 Aug 2014 05:14:24 +0400
> From: Dmitry Gutov <address@hidden>
> CC: address@hidden, address@hidden
> 
> (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".