Mercurial > emacs
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.
author | Chong Yidong <cyd@stupidchicken.com> |
---|---|
date | Wed, 15 Apr 2009 03:07:06 +0000 |
parents | 6a1a6758ec3e |
children | 789bf99f58e7 |
comparison
equal
deleted
inserted
replaced
102974:04e540897dd1 | 102975:efeb215b8665 |
---|---|
196 When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in | 196 When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in |
197 a window, that forces truncation. | 197 a window, that forces truncation. |
198 | 198 |
199 @defvar wrap-prefix | 199 @defvar wrap-prefix |
200 If this buffer-local variable is non-@code{nil}, it defines a | 200 If this buffer-local variable is non-@code{nil}, it defines a |
201 ``prefix'' that is added at display-time to the beginning of every | 201 ``prefix'' that is prepended to every continuation line at |
202 continuation line. (If lines are truncated, the wrap-prefix is never | 202 display-time. (If lines are truncated, the wrap-prefix is never |
203 used.) It may be a string, an image, or a stretch-glyph, as used by | 203 used.) It may be a string, an image, or a stretch-glyph; the value is |
204 the @code{display} text property. @xref{Display Property}. | 204 interpreted in the same way as a @code{display} text property. |
205 @xref{Display Property}. | |
205 | 206 |
206 A wrap-prefix may also be specified for regions of text, using the | 207 A wrap-prefix may also be specified for regions of text, using the |
207 @code{wrap-prefix} text property. This takes precedence over the | 208 @code{wrap-prefix} text or overlay property. This takes precedence |
208 value of the @code{wrap-prefix} variable. @xref{Special Properties}. | 209 over the @code{wrap-prefix} variable. @xref{Special Properties}. |
209 @end defvar | 210 @end defvar |
210 | 211 |
211 @defvar line-prefix | 212 @defvar line-prefix |
212 If this buffer-local variable is non-@code{nil}, it defines a | 213 If this buffer-local variable is non-@code{nil}, it defines a |
213 ``prefix'' that is added at display-time to the beginning of every | 214 ``prefix'' that is prepended to every non-continuation line at |
214 non-continuation line. It may be a string, an image, or a | 215 display-time. It may be a string, an image, or a stretch-glyph; the |
215 stretch-glyph, as used by the @code{display} text property. | 216 value is interpreted in the same way as a @code{display} text |
216 @xref{Display Property}. | 217 property. @xref{Display Property}. |
217 | 218 |
218 A line-prefix may also be specified for regions of text using the | 219 A line-prefix may also be specified for regions of text using the |
219 @code{line-prefix} text property. This takes precedence over the | 220 @code{line-prefix} text or overlay property. This takes precedence |
220 value of the @code{line-prefix} variable. @xref{Special Properties}. | 221 over the @code{line-prefix} variable. @xref{Special Properties}. |
221 @end defvar | 222 @end defvar |
222 | 223 |
223 If your buffer contains @emph{very} long lines, and you use | 224 If your buffer contains @emph{very} long lines, and you use |
224 continuation to display them, computing the continuation lines can | 225 continuation to display them, computing the continuation lines can |
225 make Emacs redisplay slow. The column computation and indentation | 226 make Emacs redisplay slow. The column computation and indentation |
1171 The visual effect of an overlay is the same as of the corresponding | 1172 The visual effect of an overlay is the same as of the corresponding |
1172 text property (@pxref{Text Properties}). However, due to a different | 1173 text property (@pxref{Text Properties}). However, due to a different |
1173 implementation, overlays generally don't scale well (many operations | 1174 implementation, overlays generally don't scale well (many operations |
1174 take a time that is proportional to the number of overlays in the | 1175 take a time that is proportional to the number of overlays in the |
1175 buffer). If you need to affect the visual appearance of many portions | 1176 buffer). If you need to affect the visual appearance of many portions |
1176 in the buffer, we recommend to use text properties. | 1177 in the buffer, we recommend using text properties. |
1177 | 1178 |
1178 An overlay uses markers to record its beginning and end; thus, | 1179 An overlay uses markers to record its beginning and end; thus, |
1179 editing the text of the buffer adjusts the beginning and end of each | 1180 editing the text of the buffer adjusts the beginning and end of each |
1180 overlay so that it stays with the text. When you create the overlay, | 1181 overlay so that it stays with the text. When you create the overlay, |
1181 you can specify whether text inserted at the beginning should be | 1182 you can specify whether text inserted at the beginning should be |
1536 @kindex after-string @r{(overlay property)} | 1537 @kindex after-string @r{(overlay property)} |
1537 This property's value is a string to add to the display at the end of | 1538 This property's value is a string to add to the display at the end of |
1538 the overlay. The string does not appear in the buffer in any | 1539 the overlay. The string does not appear in the buffer in any |
1539 sense---only on the screen. | 1540 sense---only on the screen. |
1540 | 1541 |
1542 @item line-prefix | |
1543 This property specifies a display spec to prepend to each | |
1544 non-continuation line at display-time. @xref{Truncation}. | |
1545 | |
1546 @itemx wrap-prefix | |
1547 This property specifies a display spec to prepend to each continuation | |
1548 line at display-time. @xref{Truncation}. | |
1549 | |
1541 @item evaporate | 1550 @item evaporate |
1542 @kindex evaporate @r{(overlay property)} | 1551 @kindex evaporate @r{(overlay property)} |
1543 If this property is non-@code{nil}, the overlay is deleted automatically | 1552 If this property is non-@code{nil}, the overlay is deleted automatically |
1544 if it becomes empty (i.e., if its length becomes zero). If you give | 1553 if it becomes empty (i.e., if its length becomes zero). If you give |
1545 an empty overlay a non-@code{nil} @code{evaporate} property, that deletes | 1554 an empty overlay a non-@code{nil} @code{evaporate} property, that deletes |
2149 This function returns a list of available font family names. The | 2158 This function returns a list of available font family names. The |
2150 optional argument @var{frame} specifies the frame on which the text is | 2159 optional argument @var{frame} specifies the frame on which the text is |
2151 to be displayed; if it is @code{nil}, the selected frame is used. | 2160 to be displayed; if it is @code{nil}, the selected frame is used. |
2152 @end defun | 2161 @end defun |
2153 | 2162 |
2163 @defvar underline-minimum-offset | |
2164 This variable specifies the minimum distance between the baseline and | |
2165 the underline, in pixels, when displaying underlined text. | |
2166 @end defvar | |
2167 | |
2154 @defvar x-bitmap-file-path | 2168 @defvar x-bitmap-file-path |
2155 This variable specifies a list of directories for searching | 2169 This variable specifies a list of directories for searching |
2156 for bitmap files, for the @code{:stipple} attribute. | 2170 for bitmap files, for the @code{:stipple} attribute. |
2157 @end defvar | 2171 @end defvar |
2158 | 2172 |
2452 face. | 2466 face. |
2453 | 2467 |
2454 @item | 2468 @item |
2455 If @var{remapping...} recursively references the same face name | 2469 If @var{remapping...} recursively references the same face name |
2456 @var{face}, either directly remapping entry, or via the | 2470 @var{face}, either directly remapping entry, or via the |
2457 @code{:inherit} attribute of some other face in | 2471 @code{:inherit} attribute of some other face in @var{remapping...}, |
2458 @var{remapping...}, then that reference uses normal frame-wide | 2472 then that reference uses the normal definition of @var{face} in the |
2459 definition of @var{face} instead of the ``remapped'' definition. | 2473 selected frame, instead of the ``remapped'' definition. |
2460 | 2474 |
2461 For instance, if the @code{mode-line} face is remapped using this | 2475 For instance, if the @code{mode-line} face is remapped using this |
2462 entry in @code{face-remapping-alist}: | 2476 entry in @code{face-remapping-alist}: |
2463 @example | 2477 @example |
2464 (mode-line italic mode-line) | 2478 (mode-line italic mode-line) |
2489 | 2503 |
2490 @example | 2504 @example |
2491 (@var{face} @var{relative_specs_1} @var{relative_specs_2} @var{...} @var{base_specs}) | 2505 (@var{face} @var{relative_specs_1} @var{relative_specs_2} @var{...} @var{base_specs}) |
2492 @end example | 2506 @end example |
2493 | 2507 |
2494 Everything except the @var{face} is a ``face spec'', a list of face | 2508 Everything except @var{face} is a ``face spec'': a list of face names |
2495 names or face attribute-value pairs. All face specs are merged | 2509 or face attribute-value pairs. All face specs are merged together, |
2496 together, with earlier values taking precedence. | 2510 with earlier values taking precedence. |
2497 | 2511 |
2498 The @var{relative_specs_}n values are ``relative specs'', and are | 2512 The @var{relative_specs_}n values are ``relative specs'', and are |
2499 added by @code{face-remap-add-relative} (and removed by | 2513 added by @code{face-remap-add-relative} (and removed by |
2500 @code{face-remap-remove-relative}. These are intended for face | 2514 @code{face-remap-remove-relative}. These are intended for face |
2501 modifications (such as increasing the size). Typical users of these | 2515 modifications (such as increasing the size). Typical users of these |
2984 @code{font-entity}. | 2998 @code{font-entity}. |
2985 @end defun | 2999 @end defun |
2986 | 3000 |
2987 A font object is a Lisp object that represents a font that Emacs has | 3001 A font object is a Lisp object that represents a font that Emacs has |
2988 @dfn{opened}. Font objects cannot be modified in Lisp, but they can | 3002 @dfn{opened}. Font objects cannot be modified in Lisp, but they can |
2989 be inspected. If you call @code{set-face-attribute} and pass a font | 3003 be inspected. |
2990 spec, font entity, or font name string as the value of the | |
2991 @code{:font} attribute, Emacs opens the best ``matching'' font that is | |
2992 available for display. It then stores the corresponding font object | |
2993 as the actual value of the @code{:font} attribute for that face. | |
2994 | 3004 |
2995 @defun font-at position &optional window string | 3005 @defun font-at position &optional window string |
2996 Return the font object that is being used to display the character at | 3006 Return the font object that is being used to display the character at |
2997 position @var{position} in the window @var{window}. If @var{window} | 3007 position @var{position} in the window @var{window}. If @var{window} |
2998 is @code{nil}, it defaults to the selected window. If @var{string} is | 3008 is @code{nil}, it defaults to the selected window. If @var{string} is |
3069 @var{prefer}, if non-@code{nil}, should be another font spec, which is | 3079 @var{prefer}, if non-@code{nil}, should be another font spec, which is |
3070 used to control the order of the returned list; the returned font | 3080 used to control the order of the returned list; the returned font |
3071 entities are sorted in order of decreasing ``closeness'' to that font | 3081 entities are sorted in order of decreasing ``closeness'' to that font |
3072 spec. | 3082 spec. |
3073 @end defun | 3083 @end defun |
3084 | |
3085 If you call @code{set-face-attribute} and pass a font spec, font | |
3086 entity, or font name string as the value of the @code{:font} | |
3087 attribute, Emacs opens the best ``matching'' font that is available | |
3088 for display. It then stores the corresponding font object as the | |
3089 actual value of the @code{:font} attribute for that face. | |
3074 | 3090 |
3075 The following functions can be used to obtain information about a | 3091 The following functions can be used to obtain information about a |
3076 font. For these functions, the @var{font} argument can be a font | 3092 font. For these functions, the @var{font} argument can be a font |
3077 object, a font entity, or a font spec. | 3093 object, a font entity, or a font spec. |
3078 | 3094 |
4684 | 4700 |
4685 @node Image Cache | 4701 @node Image Cache |
4686 @subsection Image Cache | 4702 @subsection Image Cache |
4687 @cindex image cache | 4703 @cindex image cache |
4688 | 4704 |
4689 Emacs stores images in an image cache so that it can display them | 4705 Emacs caches images so that it can display them again more |
4690 again more efficiently. When Emacs displays an image, it searches the | 4706 efficiently. When Emacs displays an image, it searches the image |
4691 image cache for an existing image specification @code{equal} to the | 4707 cache for an existing image specification @code{equal} to the desired |
4692 desired specification. If a match is found, the image is displayed | 4708 specification. If a match is found, the image is displayed from the |
4693 from the cache; otherwise, Emacs loads the image normally. | 4709 cache; otherwise, Emacs loads the image normally. |
4694 | 4710 |
4695 Occasionally, you may need to tell Emacs to refresh the images | 4711 Occasionally, you may need to tell Emacs to refresh the images |
4696 associated with a given image specification. For example, suppose you | 4712 associated with a given image specification. For example, suppose you |
4697 display an image using a specification that contains a @code{:file} | 4713 display an image using a specification that contains a @code{:file} |
4698 property. The image is loaded from the given file and stored in the | 4714 property. The image is automatically cached, and subsequent displays |
4699 image cache. If you later display the image again, using the same | 4715 of that image, with the same image specification, will use the image |
4700 image specification, the image is displayed from the image cache. | 4716 cache. If the image file changes in the meantime, Emacs would be |
4701 Normally, this is not a problem. However, if the image file has | 4717 displaying the old version of the image. In such a situation, you can |
4702 changed in the meantime, Emacs would be displaying the old version of | 4718 ``refresh'' the image by calling @code{image-refresh}. |
4703 the image. In such a situation, it is necessary to ``refresh'' the | 4719 |
4704 image using @code{image-refresh}. | 4720 In Emacs' current implementation, each graphical terminal possesses |
4721 an image cache, which is shared by all the frames on that terminal | |
4722 (@pxref{Multiple Terminals}). Thus, refreshing an image in one frame | |
4723 also refreshes it in all other frames on the same terminal. | |
4705 | 4724 |
4706 @defun image-refresh spec &optional frame | 4725 @defun image-refresh spec &optional frame |
4707 This function refreshes any images having image specifications | 4726 This function refreshes any images with image specifications |
4708 @code{equal} to @var{spec} on frame @var{frame}. If @var{frame} is | 4727 @code{equal} to @var{spec} on frame @var{frame}. If @var{frame} is |
4709 @code{nil}, the selected frame is used. If @var{frame} is @code{t}, | 4728 @code{nil}, it defaults to the selected frame. If @var{frame} is |
4710 the refresh is applied to all existing frames. | 4729 @code{t}, the refresh is applied to all existing frames. |
4711 | |
4712 This works by removing from the image cache all the images whose image | |
4713 specifications match @var{spec}. The next time Emacs needs to display | |
4714 such an image, it will reload the image anew. | |
4715 @end defun | 4730 @end defun |
4716 | 4731 |
4717 @defun clear-image-cache &optional filter | 4732 @defun clear-image-cache &optional filter |
4718 This function clears the image cache. If @var{filter} is | 4733 This function clears an image cache, removing all the images stored in |
4719 a frame, only the cache for that frame is cleared. If omitted or | 4734 it. If @var{filter} is omitted or @code{nil}, it clears the cache for |
4720 @code{nil}, clear the images on the selected frame. If @code{t}, | 4735 the selected frame. If @var{filter} is a frame, it clears the cache |
4721 all frames' caches are cleared. Otherwise, @var{filter} is taken as | 4736 for that frame. If @var{filter} is @code{t}, all image caches are |
4722 a file name and only images that reference this file will be flushed. | 4737 cleared. Otherwise, @var{filter} is taken to be a file name, and all |
4738 images associated with that file name are removed from all image | |
4739 caches. | |
4723 @end defun | 4740 @end defun |
4724 | 4741 |
4725 If an image in the image cache has not been displayed for a specified | 4742 If an image in the image cache has not been displayed for a specified |
4726 period of time, Emacs removes it from the cache and frees the | 4743 period of time, Emacs removes it from the cache and frees the |
4727 associated memory. | 4744 associated memory. |