bug#13250: 24.3.50; Add a way to show pre-highlighted candidates in completions buffer

[Stefan Monnier]

> When I return the list of candidates from the "completion table"
> function, I'd like to be able the specify the base (not user-defined)
> highlighting, so that the actual candidate text looks more visible (as
> opposed to the annotations) and easy to scan.  In my case, the candidates
> are method names and the annotations are argument lists, so using
> font-lock-function-name-face is natural.

Adding such faces in the `all-completions' return value is not ideal,
since all-completions can also be called without displaying the result
in *Completions* (e.g. it's used to build the completion in
partial-completion or in substring completion).

That's why we have the annotate-function which adds annotations
separately, only when we know we're going to display the result.

Of course, in your case annotate-function doesn't cut it because it can
only affect the annotation but not the actual completion.  But I'm
mentioning it, because the best long term solution should take it into
account (i.e. extend annotate-function to let you do what you want to
do here).

> But if I propertize the list with 'font-lock-face properties, both the
> "common" part and the "first difference" are still colored black,
> because the completion code uses the hardcoded faces for them, one of
> which inherits from `default', another from `bold'. Screenshot attached.

The problem is that the first-difference and common part will simply
replace the `font-lock-face' property.  We could try and make them
preserve a pre-existing font-lock-face instead.

> Can we change this so that those faces override the face attributes only
> if they've been explicitly customized (as opposed to inherited from
> `default')?

Not sure what you mean here.  If you refer to the ":inherit default" of
completions-common-part, I think it's just a mistake and that face
should simply have a "nil" default (not that it would change much).

> Is it possible to do that in a backwards-compatible way?
> With overlays, maybe?

Overlays can't be added to strings, so they're rather difficult to
use here.

If you really want it badly, you can probably get what you want by
adding `display' properties which replace the completion text with a new
text, identical except you can place any text-property you want on it.


        Stefan