comparison doc/lispref/display.texi @ 102975:efeb215b8665

* display.texi (Truncation): Overlays can use line-prefix and wrap-prefix too. (Overlay Properties): Document wrap-prefix and line-prefix. (Face Attributes): Document underline-minimum-offset. (Face Remapping): Copyedits. (Low-Level Font): Copyedits. (Image Cache): Note that the image cache is shared between frames.

102974:04e540897dd1

  When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
a window, that forces truncation.

@defvar wrap-prefix
If this buffer-local variable is non-@code{nil}, it defines a
``prefix'' that is added at display-time to the beginning of every
continuation line.  (If lines are truncated, the wrap-prefix is never
used.)  It may be a string, an image, or a stretch-glyph, as used by
the @code{display} text property.  @xref{Display Property}.

A wrap-prefix may also be specified for regions of text, using the
@code{wrap-prefix} text property.  This takes precedence over the
value of the @code{wrap-prefix} variable.  @xref{Special Properties}.
@end defvar

@defvar line-prefix
If this buffer-local variable is non-@code{nil}, it defines a
``prefix'' that is added at display-time to the beginning of every
non-continuation line.  It may be a string, an image, or a
stretch-glyph, as used by the @code{display} text property.
@xref{Display Property}.

A line-prefix may also be specified for regions of text using the
@code{line-prefix} text property.  This takes precedence over the
value of the @code{line-prefix} variable.  @xref{Special Properties}.
@end defvar

  If your buffer contains @emph{very} long lines, and you use
continuation to display them, computing the continuation lines can
make Emacs redisplay slow.  The column computation and indentation

The visual effect of an overlay is the same as of the corresponding
text property (@pxref{Text Properties}).  However, due to a different
implementation, overlays generally don't scale well (many operations
take a time that is proportional to the number of overlays in the
buffer).  If you need to affect the visual appearance of many portions
in the buffer, we recommend to use text properties.

An overlay uses markers to record its beginning and end; thus,
editing the text of the buffer adjusts the beginning and end of each
overlay so that it stays with the text.  When you create the overlay,
you can specify whether text inserted at the beginning should be

@kindex after-string @r{(overlay property)}
This property's value is a string to add to the display at the end of
the overlay.  The string does not appear in the buffer in any
sense---only on the screen.

@item evaporate
@kindex evaporate @r{(overlay property)}
If this property is non-@code{nil}, the overlay is deleted automatically
if it becomes empty (i.e., if its length becomes zero).  If you give
an empty overlay a non-@code{nil} @code{evaporate} property, that deletes

This function returns a list of available font family names.  The
optional argument @var{frame} specifies the frame on which the text is
to be displayed; if it is @code{nil}, the selected frame is used.
@end defun

@defvar x-bitmap-file-path
This variable specifies a list of directories for searching
for bitmap files, for the @code{:stipple} attribute.
@end defvar

face.

@item
If @var{remapping...} recursively references the same face name
@var{face}, either directly remapping entry, or via the
@code{:inherit} attribute of some other face in
@var{remapping...}, then that reference uses normal frame-wide
definition of @var{face} instead of the ``remapped'' definition.

For instance, if the @code{mode-line} face is remapped using this
entry in @code{face-remapping-alist}:
@example
(mode-line italic mode-line)

@example
  (@var{face} @var{relative_specs_1} @var{relative_specs_2} @var{...} @var{base_specs})
@end example

Everything except the @var{face} is a ``face spec'', a list of face
names or face attribute-value pairs.  All face specs are merged
together, with earlier values taking precedence.

The @var{relative_specs_}n values are ``relative specs'', and are
added by @code{face-remap-add-relative} (and removed by
@code{face-remap-remove-relative}.  These are intended for face
modifications (such as increasing the size).  Typical users of these

@code{font-entity}.
@end defun

  A font object is a Lisp object that represents a font that Emacs has
@dfn{opened}.  Font objects cannot be modified in Lisp, but they can
be inspected.  If you call @code{set-face-attribute} and pass a font
spec, font entity, or font name string as the value of the
@code{:font} attribute, Emacs opens the best ``matching'' font that is
available for display.  It then stores the corresponding font object
as the actual value of the @code{:font} attribute for that face.

@defun font-at position &optional window string
Return the font object that is being used to display the character at
position @var{position} in the window @var{window}.  If @var{window}
is @code{nil}, it defaults to the selected window.  If @var{string} is

@var{prefer}, if non-@code{nil}, should be another font spec, which is
used to control the order of the returned list; the returned font
entities are sorted in order of decreasing ``closeness'' to that font
spec.
@end defun

  The following functions can be used to obtain information about a
font.  For these functions, the @var{font} argument can be a font
object, a font entity, or a font spec.

@node Image Cache
@subsection Image Cache
@cindex image cache

  Emacs stores images in an image cache so that it can display them
again more efficiently.  When Emacs displays an image, it searches the
image cache for an existing image specification @code{equal} to the
desired specification.  If a match is found, the image is displayed
from the cache; otherwise, Emacs loads the image normally.

  Occasionally, you may need to tell Emacs to refresh the images
associated with a given image specification.  For example, suppose you
display an image using a specification that contains a @code{:file}
property.  The image is loaded from the given file and stored in the
image cache.  If you later display the image again, using the same
image specification, the image is displayed from the image cache.
Normally, this is not a problem.  However, if the image file has
changed in the meantime, Emacs would be displaying the old version of
the image.  In such a situation, it is necessary to ``refresh'' the
image using @code{image-refresh}.

@defun image-refresh spec &optional frame
This function refreshes any images having image specifications
@code{equal} to @var{spec} on frame @var{frame}.  If @var{frame} is
@code{nil}, the selected frame is used.  If @var{frame} is @code{t},
the refresh is applied to all existing frames.

This works by removing from the image cache all the images whose image
specifications match @var{spec}.  The next time Emacs needs to display
such an image, it will reload the image anew.
@end defun

@defun clear-image-cache &optional filter
This function clears the image cache.  If @var{filter} is
a frame, only the cache for that frame is cleared.  If omitted or
@code{nil}, clear the images on the selected frame.  If @code{t},
all frames' caches are cleared.  Otherwise, @var{filter} is taken as
a file name and only images that reference this file will be flushed.
@end defun

If an image in the image cache has not been displayed for a specified
period of time, Emacs removes it from the cache and frees the
associated memory.

102975:efeb215b8665

  When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
a window, that forces truncation.

@defvar wrap-prefix
If this buffer-local variable is non-@code{nil}, it defines a
``prefix'' that is prepended to every continuation line at
display-time.  (If lines are truncated, the wrap-prefix is never
used.)  It may be a string, an image, or a stretch-glyph; the value is
interpreted in the same way as a @code{display} text property.
@xref{Display Property}.

A wrap-prefix may also be specified for regions of text, using the
@code{wrap-prefix} text or overlay property.  This takes precedence
over the @code{wrap-prefix} variable.  @xref{Special Properties}.
@end defvar

@defvar line-prefix
If this buffer-local variable is non-@code{nil}, it defines a
``prefix'' that is prepended to every non-continuation line at
display-time.  It may be a string, an image, or a stretch-glyph; the
value is interpreted in the same way as a @code{display} text
property.  @xref{Display Property}.

A line-prefix may also be specified for regions of text using the
@code{line-prefix} text or overlay property.  This takes precedence
over the @code{line-prefix} variable.  @xref{Special Properties}.
@end defvar

  If your buffer contains @emph{very} long lines, and you use
continuation to display them, computing the continuation lines can
make Emacs redisplay slow.  The column computation and indentation

The visual effect of an overlay is the same as of the corresponding
text property (@pxref{Text Properties}).  However, due to a different
implementation, overlays generally don't scale well (many operations
take a time that is proportional to the number of overlays in the
buffer).  If you need to affect the visual appearance of many portions
in the buffer, we recommend using text properties.

An overlay uses markers to record its beginning and end; thus,
editing the text of the buffer adjusts the beginning and end of each
overlay so that it stays with the text.  When you create the overlay,
you can specify whether text inserted at the beginning should be

@kindex after-string @r{(overlay property)}
This property's value is a string to add to the display at the end of
the overlay.  The string does not appear in the buffer in any
sense---only on the screen.

@item line-prefix
This property specifies a display spec to prepend to each
non-continuation line at display-time.  @xref{Truncation}.

@itemx wrap-prefix
This property specifies a display spec to prepend to each continuation
line at display-time.  @xref{Truncation}.

@item evaporate
@kindex evaporate @r{(overlay property)}
If this property is non-@code{nil}, the overlay is deleted automatically
if it becomes empty (i.e., if its length becomes zero).  If you give
an empty overlay a non-@code{nil} @code{evaporate} property, that deletes

This function returns a list of available font family names.  The
optional argument @var{frame} specifies the frame on which the text is
to be displayed; if it is @code{nil}, the selected frame is used.
@end defun

@defvar underline-minimum-offset
This variable specifies the minimum distance between the baseline and
the underline, in pixels, when displaying underlined text.
@end defvar

@defvar x-bitmap-file-path
This variable specifies a list of directories for searching
for bitmap files, for the @code{:stipple} attribute.
@end defvar

face.

@item
If @var{remapping...} recursively references the same face name
@var{face}, either directly remapping entry, or via the
@code{:inherit} attribute of some other face in @var{remapping...},
then that reference uses the normal definition of @var{face} in the
selected frame, instead of the ``remapped'' definition.

For instance, if the @code{mode-line} face is remapped using this
entry in @code{face-remapping-alist}:
@example
(mode-line italic mode-line)

@example
  (@var{face} @var{relative_specs_1} @var{relative_specs_2} @var{...} @var{base_specs})
@end example

Everything except @var{face} is a ``face spec'': a list of face names
or face attribute-value pairs.  All face specs are merged together,
with earlier values taking precedence.

The @var{relative_specs_}n values are ``relative specs'', and are
added by @code{face-remap-add-relative} (and removed by
@code{face-remap-remove-relative}.  These are intended for face
modifications (such as increasing the size).  Typical users of these

@code{font-entity}.
@end defun

  A font object is a Lisp object that represents a font that Emacs has
@dfn{opened}.  Font objects cannot be modified in Lisp, but they can
be inspected.

@defun font-at position &optional window string
Return the font object that is being used to display the character at
position @var{position} in the window @var{window}.  If @var{window}
is @code{nil}, it defaults to the selected window.  If @var{string} is

@var{prefer}, if non-@code{nil}, should be another font spec, which is
used to control the order of the returned list; the returned font
entities are sorted in order of decreasing ``closeness'' to that font
spec.
@end defun

  If you call @code{set-face-attribute} and pass a font spec, font
entity, or font name string as the value of the @code{:font}
attribute, Emacs opens the best ``matching'' font that is available
for display.  It then stores the corresponding font object as the
actual value of the @code{:font} attribute for that face.

  The following functions can be used to obtain information about a
font.  For these functions, the @var{font} argument can be a font
object, a font entity, or a font spec.

@node Image Cache
@subsection Image Cache
@cindex image cache

  Emacs caches images so that it can display them again more
efficiently.  When Emacs displays an image, it searches the image
cache for an existing image specification @code{equal} to the desired
specification.  If a match is found, the image is displayed from the
cache; otherwise, Emacs loads the image normally.

  Occasionally, you may need to tell Emacs to refresh the images
associated with a given image specification.  For example, suppose you
display an image using a specification that contains a @code{:file}
property.  The image is automatically cached, and subsequent displays
of that image, with the same image specification, will use the image
cache.  If the image file changes in the meantime, Emacs would be
displaying the old version of the image.  In such a situation, you can
``refresh'' the image by calling @code{image-refresh}.

  In Emacs' current implementation, each graphical terminal possesses
an image cache, which is shared by all the frames on that terminal
(@pxref{Multiple Terminals}).  Thus, refreshing an image in one frame
also refreshes it in all other frames on the same terminal.

@defun image-refresh spec &optional frame
This function refreshes any images with image specifications
@code{equal} to @var{spec} on frame @var{frame}.  If @var{frame} is
@code{nil}, it defaults to the selected frame.  If @var{frame} is
@code{t}, the refresh is applied to all existing frames.
@end defun

@defun clear-image-cache &optional filter
This function clears an image cache, removing all the images stored in
it.  If @var{filter} is omitted or @code{nil}, it clears the cache for
the selected frame.  If @var{filter} is a frame, it clears the cache
for that frame.  If @var{filter} is @code{t}, all image caches are
cleared.  Otherwise, @var{filter} is taken to be a file name, and all
images associated with that file name are removed from all image
caches.
@end defun

If an image in the image cache has not been displayed for a specified
period of time, Emacs removes it from the cache and frees the
associated memory.