Mercurial > emacs
diff 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.
author | Chong Yidong <cyd@stupidchicken.com> |
---|---|
date | Wed, 15 Apr 2009 03:07:06 +0000 |
parents | 6a1a6758ec3e |
children | 789bf99f58e7 |
line wrap: on
line diff
--- a/doc/lispref/display.texi Wed Apr 15 00:32:47 2009 +0000 +++ b/doc/lispref/display.texi Wed Apr 15 03:07:06 2009 +0000 @@ -198,26 +198,27 @@ @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 @@ -1173,7 +1174,7 @@ 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 @@ -1538,6 +1539,14 @@ 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 @@ -2151,6 +2160,11 @@ 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. @@ -2454,9 +2468,9 @@ @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}: @@ -2491,9 +2505,9 @@ (@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 @@ -2986,11 +3000,7 @@ 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 @@ -3072,6 +3082,12 @@ 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. @@ -4686,40 +4702,41 @@ @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