@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}.
+``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 property. This takes precedence over the
-value of the @code{wrap-prefix} variable. @xref{Special Properties}.
+@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 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}.
+``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 property. This takes precedence over the
-value of the @code{line-prefix} variable. @xref{Special Properties}.
+@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
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.
+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
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
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.
@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.
+@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}:
(@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.
+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
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.
+be inspected.
@defun font-at position &optional window string
Return the font object that is being used to display the character at
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.
@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.
+ 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 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}.
+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 having image specifications
+This function refreshes any images with 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.
+@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 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.
+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