path: root/devdocs/elisp/other-display-specs.html

 <h4 class="subsection">Other Display Specifications</h4> <p>Here are the other sorts of display specifications that you can use in the <code>display</code> text property. </p> <dl compact> <dt><code><var>string</var></code></dt> <dd>
<p>Display <var>string</var> instead of the text that has this property. </p> <p>Recursive display specifications are not supported—<var>string</var>’s <code>display</code> properties, if any, are not used. </p> </dd> <dt><code>(image . <var>image-props</var>)</code></dt> <dd>
<p>This kind of display specification is an image descriptor (see <a href="image-descriptors">Image Descriptors</a>). When used as a display specification, it means to display the image instead of the text that has the display specification. </p> </dd> <dt><code>(slice <var>x</var> <var>y</var> <var>width</var> <var>height</var>)</code></dt> <dd>
<p>This specification together with <code>image</code> specifies a <em>slice</em> (a partial area) of the image to display. The elements <var>y</var> and <var>x</var> specify the top left corner of the slice, within the image; <var>width</var> and <var>height</var> 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. </p> </dd> <dt><code>((margin nil) <var>string</var>)</code></dt> <dd>
<p>A display specification of this form means to display <var>string</var> instead of the text that has the display specification, at the same position as that text. It is equivalent to using just <var>string</var>, but it is done as a special case of marginal display (see <a href="display-margins">Display Margins</a>). </p> </dd> <dt><code>(left-fringe <var>bitmap</var> <span class="roman">[</span><var>face</var><span class="roman">]</span>)</code></dt> <dt><code>(right-fringe <var>bitmap</var> <span class="roman">[</span><var>face</var><span class="roman">]</span>)</code></dt> <dd>
<p>This display specification on any character of a line of text causes the specified <var>bitmap</var> be displayed in the left or right fringes for that line, instead of the characters that have the display specification. The optional <var>face</var> specifies the face whose colors are to be used for the bitmap display. See <a href="fringe-bitmaps">Fringe Bitmaps</a>, for the details. </p> </dd> <dt><code>(space-width <var>factor</var>)</code></dt> <dd>
<p>This display specification affects all the space characters within the text that has the specification. It displays all of these spaces <var>factor</var> times as wide as normal. The element <var>factor</var> should be an integer or float. Characters other than spaces are not affected at all; in particular, this has no effect on tab characters. </p> </dd> <dt><code>(height <var>height</var>)</code></dt> <dd>
<p>This display specification makes the text taller or shorter. Here are the possibilities for <var>height</var>: </p> <dl compact> <dt><code>(+ <var>n</var>)</code></dt> <dd>
<p>This means to use a font that is <var>n</var> steps larger. A <em>step</em> 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. <var>n</var> should be an integer. </p> </dd> <dt><code>(- <var>n</var>)</code></dt> <dd>
<p>This means to use a font that is <var>n</var> steps smaller. </p> </dd> <dt>a number, <var>factor</var>
</dt> <dd>
<p>A number, <var>factor</var>, means to use a font that is <var>factor</var> times as tall as the default font. </p> </dd> <dt>a symbol, <var>function</var>
</dt> <dd>
<p>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. </p> </dd> <dt>anything else, <var>form</var>
</dt> <dd><p>If the <var>height</var> value doesn’t fit the previous possibilities, it is a form. Emacs evaluates it to get the new height, with the symbol <code>height</code> bound to the current specified font height. </p></dd> </dl> </dd> <dt><code>(raise <var>factor</var>)</code></dt> <dd>
<p>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. </p> <p>The <var>factor</var> 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. </p> <p>Note that if the text also has a <code>height</code> display specification, which was specified before (i.e. to the left of) <code>raise</code>, 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 <code>raise</code> before <code>height</code>. </p>
</dd> </dl> <p>You can make any display specification conditional. To do that, package it in another list of the form <code>(when <var>condition</var> . <var>spec</var>)</code>. Then the specification <var>spec</var> applies only when <var>condition</var> evaluates to a non-<code>nil</code> value. During the evaluation, <code>object</code> is bound to the string or buffer having the conditional <code>display</code> property. <code>position</code> and <code>buffer-position</code> are bound to the position within <code>object</code> and the buffer position where the <code>display</code> property was found, respectively. Both positions can be different when <code>object</code> is a string. </p> <p>Note that <var>condition</var> will only be evaluated when redisplay examines the text where this display spec is located, so this feature is best suited for conditions that are relatively stable, i.e. yield, for each particular buffer position, the same results on every evaluation. If the results change for the same text location, e.g., if the result depends on the position of point, then the conditional specification might not do what you want, because redisplay examines only those parts of buffer text where it has reasons to assume that something changed since the last display cycle. </p><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Other-Display-Specs.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Other-Display-Specs.html</a>
  </p>
</div>