Icicles - Candidates with Text Properties

Previous: Icicles - Programming Multi-CompletionsIciclesIciclesIndexNext: Icicles - Defining Icicles Commands

Candidates with Text Properties

This section is for EmacsLisp programmers.

Icicles - Programming Multi-Completions explains how to apply text properties to specific parts of all multi-completion candidates in buffer ‘*Completions*’ at the same time. This section tells you how to apply text properties to specific candidates in ‘*Completions*’. The candidates need not be multi-completions, but in some cases they can be.

When you use candidates with text properties such as ‘face’ that are visible, the display candidates in ‘*Completions*’ show those properties. In addition, the candidate string that the user finally chooses can also be propertized.

There are four different methods for providing candidates with text properties, in addition to the way presented on page Icicles - Programming Multi-Completions:

1. Apply face ‘icicle-special-candidate’ to all candidates that match a given regexp.

2. Use a set of text properties as the ‘icicle-special-candidate’ property of the symbol that represents the candidate. The text properties are transferred to the string candidate that is displayed (and returned).

3. Use a propertized string as the ‘icicle-display-string’ property of the symbol that represents the candidate. That string replaces the candidate that would otherwise have been displayed, completed against, and returned.

4. Start with a propertized string in the COLLECTION argument that you pass to ‘completing-read’.

All four methods use fancy candidates, in the sense that they go beyond what vanilla Emacs offers. For methods 1--3, you must turn on fancy-candidate handling. See Icicles - Programming with Fancy Candidates.

But method 4 does not require any costly fancy-candidate encoding or decoding, because the Icicles implementation of ‘completing-read’ handles propertized string candidates, and they are transparent to the Emacs primitive completion operations.

The following sections explain methods 1--4 individually.

Using Regexp icicle-special-candidate-regexp

If you just want several candidates to have face `icicle-special-candidate’ in ‘*Completions*’, you can simply define (e.g. bind) option `icicle-special-candidate-regexp’ to a regexp that matches those candidates. The original candidates can be strings or symbols. Unlike the other methods described here, this one affects only the display in ‘*Completions*’; the completion return string does not have face ‘icicle-special-candidate’.

The highlighting applies only to the part of a candidate that matches the regexp. This selectivity is particularly useful when dealing with multi-completions. Function ‘icicle-read-file-name’ provides an example: file names that match .+/$, that is, directory names, are highlighted as special candidates. Function ‘icicle-read-color-WYSIWYG’ provides another example (using the similar, but internal, variable ‘icicle-proxy-candidate-regexp’): proxy color-name candidates such as ‘*point foreground*’ and ``icicle-region-background'’ are highlighted, but not their color swatches.

Using Property `icicle-special-candidate'

In this approach, you use the desired list of text properties as the value of property ‘icicle-special-candidate’ for the symbol that represents the candidate. This method affects the candidates that are used during completion, as well as the completion return value.

If the candidate is a string, not a symbol, then ‘intern’ it and put the property on the resulting symbol. If you want the effect to be temporary, then set property ‘icicle-special-candidate’ for the candidate to ‘nil’ when completion is finished.

As a shortcut, if you use the value ‘t’ instead of a property list for property ‘icicle-special-candidate’, then face ‘icicle-special-candidate’ will be used as the ‘face’ property of the candidate. Using a value of ‘t’ is thus equivalent to using a value of (face icicle-special-candidate). This approach is used, for instance, in the definition of command ‘icicle-complete-keys’ (‘S-TAB’).

Using Property `icicle-display-string'

This method is similar to that of using property ‘icicle-special-candidate’. The use case for both is propertizing, in a general way, candidates that are symbols. Both can be useful when you have an obarray as the COLLECTION argument for ‘completing-read’.

In this method the symbol name is not used at all; the candidate is entirely replaced by another string, which is typically propertized.

You use a propertized string as the value of property ‘icicle-display-string’ for the candidate symbol. The propertized string is displayed in ‘*Completions*’ and returned as the final completion choice.

Note that multi-completion is not available when you use an obarray. Using property ‘icicle-special-candidate’ or ‘icicle-display-string’ you can propertize candidates and parts of candidates, but you cannot manipulate multi-completion parts and there are no join or end strings.

Applying Text Properties to a Candidate String

This is the most flexible approach, and it is explained in a bit more detail. It can be used with multi-completions, and it affects the ‘*Completions*’ display and the completion return value. However, it is limited to using an alist or list of strings, not an obarray, as the COLLECTION argument to ‘completing-read’.

In this approach, you simply apply the text properties to the string(s) that represent the candidate, which you then pass to ‘completing-read’ in its COLLECTION parameter.

As with the other methods, you can use any text properties you like, including these:

As a convenience, you can use function ‘icicle-candidate-short-help’ to apply both ‘icicle-mode-line-help’ and ‘help-echo’ text properties to a candidate string.

How does this work? Icicles redefines the standard Emacs function ‘display-completion-list’ so that it retains text properties. Emacs should do the same, but it does not (yet).

2007-01-24 – RMS has agreed to fix Emacs in this way, so this will become possible in Emacs. – DrewAdams

Icicles command ‘icicle-read-color-WYSIWYG’ presents an illustration, using the ‘face’ property. (It also uses properties ‘icicle-mode-line-help’ and ‘help-echo’, to provide RGB and HSV information in the mode-line and via tooltip.)

In ‘icicle-read-color-WYSIWYG’, a multi-completion candidate is used, composed of an unpropertized string that names a color and a propertized string that names its RGB (red, green, blue) value. The RGB string, by default, has a background of the same color – each completion candidate is thus accompanied by its own color swatch.

The code that does this is in function ‘icicle-make-color-candidate’, which is used by ‘icicle-read-color-WYSIWYG’ and other Icicles commands that read colors. Here is a simplified definition:

  (defun icicle-make-color-candidate (color-name)
    "Return candidate of COLOR-NAME and its hex RGB string.
  If `icicle-WYSIWYG-Completions-flag' is non-nil, then the hex RGB
  string has the color as its background text property."
    (let ((rgb-string  (hexrgb-color-name-to-hex color-name)))
      (when icicle-WYSIWYG-Completions-flag
          0 (length rgb-string) 'face
          (cons 'background-color rgb-string) rgb-string))
      (list (list color-name rgb-string))))

You’ll notice that the face property is added only when option `icicle-WYSIWYG-Completions-flag’ is non-‘nil’. You can toggle this option during completion, using ‘C-S-pause’, to change the behavior. (The new value takes effect for the next act of completion.)

You can match any part of the multi-completion: color name or RGB value. Command ‘icicle-read-color-WYSIWYG’ defines a set of sort orders that are pertinent to the color candidates.

You can use `C-,’ to sort by color name, amount of red, blue, green, all RGB components (in order), RGB distance from a base color, hue, saturation, value, all HSV components (in order), or HSV distance from a base color.

Here is a screenshot showing candidates sorted by color saturation (purity):


And here is a screenshot showing candidates sorted by color name:


For this screenshot, I turned on inclusion of proxy candidates. For ‘icicle-read-color-WYSIWYG’, the proxies are placeholders for colors; they are not, themselves, color-name-and-RGB pairs. Proxies are highlighted with face `icicle-proxy-candidate’ for easier recognition. As always, you can toggle the use of proxy candidates using `C-M-_’ in the minibuffer.

The proxy candidates for colors include the single-quoted names of user options (variables) whose custom type is ‘color’. So, for example, option ‘icicle-region-background’ appears as proxy color candidate `'icicle-region-background'’. Color proxies also include the following:

  • ‘*copied foreground*’ – last copied foreground, if available
  • ‘*copied background*’ – last copied background, if available
  • ‘*mouse-2 foreground*’ – foreground where you click ‘mouse-2’
  • ‘*mouse-2 background*’ – background where you click ‘mouse-2’
  • ‘*point foreground*’ – foreground under the text cursor
  • ‘*point background*’ – background under the text cursor

When you choose a proxy color candidate, the color referred to is used. For example, ‘*point foreground*’ means to use the foreground color at the cursor position (point), whatever it might be. Choosing a ‘mouse-2’ candidate lets you then click ‘mouse-2’ to pick up a color somewhere. If you use library palette.el or eyedropper.el, and you have already copied a color, then you can choose ‘*copied foreground*’ (or background) to use that color.

Icicles treats reading face names similarly to reading colors, by redefining standard function ‘read-face-name’ when you are in Icicle mode. In this case, multi-completions are not used. The pertinent function is ‘icicle-make-face-candidate’, which provides a WYSIWYG face sample whenever ‘icicle-WYSIWYG-Completions-flag’ is non-‘nil’.

A string value for ‘icicle-WYSIWYG-Completions-flag’ presents the face name accompanied by that string as a separate sample swatch. A value of ‘t’ presents the face name itself in the face it names.

  (defun icicle-make-face-candidate (face)
    "Return a completion candidate for FACE.
  The value of option `icicle-WYSIWYG-Completions-flag' determines
  the kind of candidate to use.
   If nil, then the face name is used (a string).
   If a string, then a multi-completion candidate is used, with the
   face name followed by a sample swatch using FACE on the string's
   If t, then the candidate is the face name itself, propertized
   with FACE."
    (if (stringp icicle-WYSIWYG-Completions-flag)
        (let ((swatch  (copy-sequence
           0 (length icicle-WYSIWYG-Completions-flag)
           'face face swatch)
          (list (list (symbol-name face) swatch)))
      (let ((face-name  (copy-sequence (symbol-name face))))
        (when icicle-WYSIWYG-Completions-flag
          (put-text-property 0 (length face-name)
                             'face face face-name))
        (list face-name))))

Here is a screenshot showing some of the face-name candidates:


See Also:

Previous: Icicles - Programming Multi-CompletionsIciclesIciclesIndexNext: Icicles - Defining Icicles Commands

DrewsElispLibraries referenced here: Lisp:icicles.el

CategoryCommands CategoryCompletion CategoryProgrammerUtils CategoryCode CategoryFaces