elisp: Other Display Specs
37.16.4 Other Display Specifications
------------------------------------
Here are the other sorts of display specifications that you can use in
the ‘display’ text property.
‘STRING’
Display STRING instead of the text that has this property.
Recursive display specifications are not supported—STRING’s
‘display’ properties, if any, are not used.
‘(image . IMAGE-PROPS)’
This kind of display specification is an image descriptor (
Images). When used as a display specification, it means to
display the image instead of the text that has the display
specification.
‘(slice X Y WIDTH HEIGHT)’
This specification together with ‘image’ specifies a “slice” (a
partial area) of the image to display. The elements Y and X
specify the top left corner of the slice, within the image; WIDTH
and HEIGHT specify the width and height of the slice. Integers are
numbers of pixels. A floating-point number in the range 0.0–1.0
stands for that fraction of the width or height of the entire
image.
‘((margin nil) STRING)’
A display specification of this form means to display STRING
instead of the text that has the display specification, at the same
position as that text. It is equivalent to using just STRING, but
it is done as a special case of marginal display (Display
Margins).
‘(left-fringe BITMAP [FACE])’
‘(right-fringe BITMAP [FACE])’
This display specification on any character of a line of text
causes the specified BITMAP be displayed in the left or right
fringes for that line, instead of the characters that have the
display specification. The optional FACE specifies the colors to
be used for the bitmap. Fringe Bitmaps, for the details.
‘(space-width FACTOR)’
This display specification affects all the space characters within
the text that has the specification. It displays all of these
spaces FACTOR times as wide as normal. The element FACTOR should
be an integer or float. Characters other than spaces are not
affected at all; in particular, this has no effect on tab
characters.
‘(height HEIGHT)’
This display specification makes the text taller or shorter. Here
are the possibilities for HEIGHT:
‘(+ N)’
This means to use a font that is N steps larger. A “step” is
defined by the set of available fonts—specifically, those that
match what was otherwise specified for this text, in all
attributes except height. Each size for which a suitable font
is available counts as another step. N should be an integer.
‘(- N)’
This means to use a font that is N steps smaller.
a number, FACTOR
A number, FACTOR, means to use a font that is FACTOR times as
tall as the default font.
a symbol, FUNCTION
A symbol is a function to compute the height. It is called
with the current height as argument, and should return the new
height to use.
anything else, FORM
If the HEIGHT value doesn’t fit the previous possibilities, it
is a form. Emacs evaluates it to get the new height, with the
symbol ‘height’ bound to the current specified font height.
‘(raise FACTOR)’
This kind of display specification raises or lowers the text it
applies to, relative to the baseline of the line. It is mainly
meant to support display of subscripts and superscripts.
The FACTOR must be a number, which is interpreted as a multiple of
the height of the affected text. If it is positive, that means to
display the characters raised. If it is negative, that means to
display them lower down.
Note that if the text also has a ‘height’ display specification,
which was specified before (i.e. to the left of) ‘raise’, the
latter will affect the amount of raising or lowering in pixels,
because that is based on the height of the text being raised.
Therefore, if you want to display a sub- or superscript that is
smaller than the normal text height, consider specifying ‘raise’
before ‘height’.
You can make any display specification conditional. To do that,
package it in another list of the form ‘(when CONDITION . SPEC)’. Then
the specification SPEC applies only when CONDITION evaluates to a
non-‘nil’ value. During the evaluation, ‘object’ is bound to the string
or buffer having the conditional ‘display’ property. ‘position’ and
‘buffer-position’ are bound to the position within ‘object’ and the
buffer position where the ‘display’ property was found, respectively.
Both positions can be different when ‘object’ is a string.
Info Catalog
elisp: Pixel Specification
elisp: Display Property
elisp: Display Margins