2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/display
7 @node Display, Calendar, Processes, Top
10 This chapter describes a number of features related to the display
11 that Emacs presents to the user.
14 * Refresh Screen:: Clearing the screen and redrawing everything on it.
15 * Forcing Redisplay:: Forcing redisplay.
16 * Truncation:: Folding or wrapping long text lines.
17 * The Echo Area:: Where messages are displayed.
18 * Invisible Text:: Hiding part of the buffer text.
19 * Selective Display:: Hiding part of the buffer text (the old way).
20 * Overlay Arrow:: Display of an arrow to indicate position.
21 * Temporary Displays:: Displays that go away automatically.
22 * Overlays:: Use overlays to highlight parts of the buffer.
23 * Width:: How wide a character or string is on the screen.
24 * Faces:: A face defines a graphics style for text characters:
26 * Display Property:: Enabling special display features.
27 * Images:: Displaying images in Emacs buffers.
28 * Blinking:: How Emacs shows the matching open parenthesis.
29 * Inverse Video:: Specifying how the screen looks.
30 * Usual Display:: The usual conventions for displaying nonprinting chars.
31 * Display Tables:: How to specify other conventions.
32 * Beeping:: Audible signal to the user.
33 * Window Systems:: Which window system is being used.
37 @section Refreshing the Screen
39 The function @code{redraw-frame} redisplays the entire contents of a
40 given frame (@pxref{Frames}).
43 @defun redraw-frame frame
44 This function clears and redisplays frame @var{frame}.
47 Even more powerful is @code{redraw-display}:
49 @deffn Command redraw-display
50 This function clears and redisplays all visible frames.
53 Processing user input takes absolute priority over redisplay. If you
54 call these functions when input is available, they do nothing
55 immediately, but a full redisplay does happen eventually---after all the
56 input has been processed.
58 Normally, suspending and resuming Emacs also refreshes the screen.
59 Some terminal emulators record separate contents for display-oriented
60 programs such as Emacs and for ordinary sequential display. If you are
61 using such a terminal, you might want to inhibit the redisplay on
64 @defvar no-redraw-on-reenter
65 @cindex suspend (cf. @code{no-redraw-on-reenter})
66 @cindex resume (cf. @code{no-redraw-on-reenter})
67 This variable controls whether Emacs redraws the entire screen after it
68 has been suspended and resumed. Non-@code{nil} means there is no need
69 to redraw, @code{nil} means redrawing is needed. The default is @code{nil}.
72 @node Forcing Redisplay
73 @section Forcing Redisplay
74 @cindex forcing redisplay
76 Emacs redisplay normally stops if input arrives, and does not happen
77 at all if input is available before it starts. Most of the time, this
78 is exactly what you want. However, you can prevent preemption by
79 binding @code{redisplay-dont-pause} to a non-@code{nil} value.
81 @tindex redisplay-dont-pause
82 @defvar redisplay-dont-pause
83 If this variable is non-@code{nil}, pending input does not
84 prevent or halt redisplay; redisplay occurs, and finishes,
85 regardless of whether input is available. This feature is available
89 You can request a display update, but only if no input is pending,
90 with @code{(sit-for 0)}. To force a display update even when input is
94 (let ((redisplay-dont-pause t))
100 @cindex line wrapping
101 @cindex continuation lines
102 @cindex @samp{$} in display
103 @cindex @samp{\} in display
105 When a line of text extends beyond the right edge of a window, the
106 line can either be continued on the next screen line, or truncated to
107 one screen line. The additional screen lines used to display a long
108 text line are called @dfn{continuation} lines. Normally, a @samp{$} in
109 the rightmost column of the window indicates truncation; a @samp{\} on
110 the rightmost column indicates a line that ``wraps'' onto the next line,
111 which is also called @dfn{continuing} the line. (The display table can
112 specify alternative indicators; see @ref{Display Tables}.)
114 Note that continuation is different from filling; continuation happens
115 on the screen only, not in the buffer contents, and it breaks a line
116 precisely at the right margin, not at a word boundary. @xref{Filling}.
118 @defopt truncate-lines
119 This buffer-local variable controls how Emacs displays lines that extend
120 beyond the right edge of the window. The default is @code{nil}, which
121 specifies continuation. If the value is non-@code{nil}, then these
124 If the variable @code{truncate-partial-width-windows} is non-@code{nil},
125 then truncation is always used for side-by-side windows (within one
126 frame) regardless of the value of @code{truncate-lines}.
129 @defopt default-truncate-lines
130 This variable is the default value for @code{truncate-lines}, for
131 buffers that do not have buffer-local values for it.
134 @defopt truncate-partial-width-windows
135 This variable controls display of lines that extend beyond the right
136 edge of the window, in side-by-side windows (@pxref{Splitting Windows}).
137 If it is non-@code{nil}, these lines are truncated; otherwise,
138 @code{truncate-lines} says what to do with them.
141 When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
142 a window, that forces truncation.
144 You can override the glyphs that indicate continuation or truncation
145 using the display table; see @ref{Display Tables}.
147 If your buffer contains @emph{very} long lines, and you use
148 continuation to display them, just thinking about them can make Emacs
149 redisplay slow. The column computation and indentation functions also
150 become slow. Then you might find it advisable to set
151 @code{cache-long-line-scans} to @code{t}.
153 @defvar cache-long-line-scans
154 If this variable is non-@code{nil}, various indentation and motion
155 functions, and Emacs redisplay, cache the results of scanning the
156 buffer, and consult the cache to avoid rescanning regions of the buffer
157 unless they are modified.
159 Turning on the cache slows down processing of short lines somewhat.
161 This variable is automatically buffer-local in every buffer.
165 @section The Echo Area
166 @cindex error display
169 The @dfn{echo area} is used for displaying messages made with the
170 @code{message} primitive, and for echoing keystrokes. It is not the
171 same as the minibuffer, despite the fact that the minibuffer appears
172 (when active) in the same place on the screen as the echo area. The
173 @cite{GNU Emacs Manual} specifies the rules for resolving conflicts
174 between the echo area and the minibuffer for use of that screen space
175 (@pxref{Minibuffer,, The Minibuffer, emacs, The GNU Emacs Manual}).
176 Error messages appear in the echo area; see @ref{Errors}.
178 You can write output in the echo area by using the Lisp printing
179 functions with @code{t} as the stream (@pxref{Output Functions}), or as
182 @defun message string &rest arguments
183 This function displays a one-line message in the echo area. The
184 argument @var{string} is similar to a C language @code{printf} control
185 string. See @code{format} in @ref{String Conversion}, for the details
186 on the conversion specifications. @code{message} returns the
189 In batch mode, @code{message} prints the message text on the standard
190 error stream, followed by a newline.
192 If @var{string}, or strings among the @var{arguments}, have @code{face}
193 text properties, these affect the way the message is displayed.
196 If @var{string} is @code{nil}, @code{message} clears the echo area; if
197 the echo area has been expanded automatically, this brings it back to
198 its normal size. If the minibuffer is active, this brings the
199 minibuffer contents back onto the screen immediately.
203 (message "Minibuffer depth is %d."
205 @print{} Minibuffer depth is 0.
206 @result{} "Minibuffer depth is 0."
210 ---------- Echo Area ----------
211 Minibuffer depth is 0.
212 ---------- Echo Area ----------
216 To automatically display a message in the echo area or in a pop-buffer,
217 depending on its size, use @code{display-message-or-buffer}.
220 @tindex with-temp-message
221 @defmac with-temp-message message &rest body
222 This construct displays a message in the echo area temporarily, during
223 the execution of @var{body}. It displays @var{message}, executes
224 @var{body}, then returns the value of the last body form while restoring
225 the previous echo area contents.
228 @defun message-or-box string &rest arguments
229 This function displays a message like @code{message}, but may display it
230 in a dialog box instead of the echo area. If this function is called in
231 a command that was invoked using the mouse---more precisely, if
232 @code{last-nonmenu-event} (@pxref{Command Loop Info}) is either
233 @code{nil} or a list---then it uses a dialog box or pop-up menu to
234 display the message. Otherwise, it uses the echo area. (This is the
235 same criterion that @code{y-or-n-p} uses to make a similar decision; see
236 @ref{Yes-or-No Queries}.)
238 You can force use of the mouse or of the echo area by binding
239 @code{last-nonmenu-event} to a suitable value around the call.
242 @defun message-box string &rest arguments
243 This function displays a message like @code{message}, but uses a dialog
244 box (or a pop-up menu) whenever that is possible. If it is impossible
245 to use a dialog box or pop-up menu, because the terminal does not
246 support them, then @code{message-box} uses the echo area, like
250 @defun display-message-or-buffer message &optional buffer-name not-this-window frame
251 @tindex display-message-or-buffer
252 This function displays the message @var{message}, which may be either a
253 string or a buffer. If it is shorter than the maximum height of the
254 echo area, as defined by @code{max-mini-window-height}, it is displayed
255 in the echo area, using @code{message}. Otherwise,
256 @code{display-buffer} is used to show it in a pop-up buffer.
258 Returns either the string shown in the echo area, or when a pop-up
259 buffer is used, the window used to display it.
261 If @var{message} is a string, then the optional argument
262 @var{buffer-name} is the name of the buffer used to display it when a
263 pop-up buffer is used, defaulting to @samp{*Message*}. In the case
264 where @var{message} is a string and displayed in the echo area, it is
265 not specified whether the contents are inserted into the buffer anyway.
267 The optional arguments @var{not-this-window} and @var{frame} are as for
268 @code{display-buffer}, and only used if a buffer is displayed.
271 @defun current-message
272 This function returns the message currently being displayed in the
273 echo area, or @code{nil} if there is none.
276 @defvar cursor-in-echo-area
277 This variable controls where the cursor appears when a message is
278 displayed in the echo area. If it is non-@code{nil}, then the cursor
279 appears at the end of the message. Otherwise, the cursor appears at
280 point---not in the echo area at all.
282 The value is normally @code{nil}; Lisp programs bind it to @code{t}
283 for brief periods of time.
286 @defvar echo-area-clear-hook
287 This normal hook is run whenever the echo area is cleared---either by
288 @code{(message nil)} or for any other reason.
291 Almost all the messages displayed in the echo area are also recorded
292 in the @samp{*Messages*} buffer.
294 @defopt message-log-max
295 This variable specifies how many lines to keep in the @samp{*Messages*}
296 buffer. The value @code{t} means there is no limit on how many lines to
297 keep. The value @code{nil} disables message logging entirely. Here's
298 how to display a message and prevent it from being logged:
301 (let (message-log-max)
306 @defvar echo-keystrokes
307 This variable determines how much time should elapse before command
308 characters echo. Its value must be an integer or floating point number,
310 number of seconds to wait before echoing. If the user types a prefix
311 key (such as @kbd{C-x}) and then delays this many seconds before
312 continuing, the prefix key is echoed in the echo area. (Once echoing
313 begins in a key sequence, all subsequent characters in the same key
314 sequence are echoed immediately.)
316 If the value is zero, then command input is not echoed.
320 @section Invisible Text
322 @cindex invisible text
323 You can make characters @dfn{invisible}, so that they do not appear on
324 the screen, with the @code{invisible} property. This can be either a
325 text property (@pxref{Text Properties}) or a property of an overlay
328 In the simplest case, any non-@code{nil} @code{invisible} property makes
329 a character invisible. This is the default case---if you don't alter
330 the default value of @code{buffer-invisibility-spec}, this is how the
331 @code{invisible} property works.
333 More generally, you can use the variable @code{buffer-invisibility-spec}
334 to control which values of the @code{invisible} property make text
335 invisible. This permits you to classify the text into different subsets
336 in advance, by giving them different @code{invisible} values, and
337 subsequently make various subsets visible or invisible by changing the
338 value of @code{buffer-invisibility-spec}.
340 Controlling visibility with @code{buffer-invisibility-spec} is
341 especially useful in a program to display the list of entries in a
342 database. It permits the implementation of convenient filtering
343 commands to view just a part of the entries in the database. Setting
344 this variable is very fast, much faster than scanning all the text in
345 the buffer looking for properties to change.
347 @defvar buffer-invisibility-spec
348 This variable specifies which kinds of @code{invisible} properties
349 actually make a character invisible.
353 A character is invisible if its @code{invisible} property is
354 non-@code{nil}. This is the default.
357 Each element of the list specifies a criterion for invisibility; if a
358 character's @code{invisible} property fits any one of these criteria,
359 the character is invisible. The list can have two kinds of elements:
363 A character is invisible if its @code{invisible} property value
364 is @var{atom} or if it is a list with @var{atom} as a member.
366 @item (@var{atom} . t)
367 A character is invisible if its @code{invisible} property value
368 is @var{atom} or if it is a list with @var{atom} as a member.
369 Moreover, if this character is at the end of a line and is followed
370 by a visible newline, it displays an ellipsis.
375 Two functions are specifically provided for adding elements to
376 @code{buffer-invisibility-spec} and removing elements from it.
378 @defun add-to-invisibility-spec element
379 Add the element @var{element} to @code{buffer-invisibility-spec}
380 (if it is not already present in that list).
383 @defun remove-from-invisibility-spec element
384 Remove the element @var{element} from @code{buffer-invisibility-spec}.
385 This does nothing if @var{element} is not in the list.
388 One convention about the use of @code{buffer-invisibility-spec} is
389 that a major mode should use the mode's own name as an element of
390 @code{buffer-invisibility-spec} and as the value of the @code{invisible}
394 ;; @r{If you want to display an ellipsis:}
395 (add-to-invisibility-spec '(my-symbol . t))
396 ;; @r{If you don't want ellipsis:}
397 (add-to-invisibility-spec 'my-symbol)
399 (overlay-put (make-overlay beginning end)
400 'invisible 'my-symbol)
402 ;; @r{When done with the overlays:}
403 (remove-from-invisibility-spec '(my-symbol . t))
404 ;; @r{Or respectively:}
405 (remove-from-invisibility-spec 'my-symbol)
408 @vindex line-move-ignore-invisible
409 Ordinarily, commands that operate on text or move point do not care
410 whether the text is invisible. The user-level line motion commands
411 explicitly ignore invisible newlines if
412 @code{line-move-ignore-invisible} is non-@code{nil}, but only because
413 they are explicitly programmed to do so.
415 Incremental search can make invisible overlays visible temporarily
416 and/or permanently when a match includes invisible text. To enable
417 this, the overlay should have a non-@code{nil}
418 @code{isearch-open-invisible} property. The property value should be a
419 function to be called with the overlay as an argument. This function
420 should make the overlay visible permanently; it is used when the match
421 overlaps the overlay on exit from the search.
423 During the search, such overlays are made temporarily visible by
424 temporarily modifying their invisible and intangible properties. If you
425 want this to be done differently for a certain overlay, give it an
426 @code{isearch-open-invisible-temporary} property which is a function.
427 The function is called with two arguments: the first is the overlay, and
428 the second is @code{nil} to make the overlay visible, or @code{t} to
429 make it invisible again.
431 @node Selective Display
432 @section Selective Display
433 @cindex selective display
435 @dfn{Selective display} refers to a pair of related features for
436 hiding certain lines on the screen.
438 The first variant, explicit selective display, is designed for use in
439 a Lisp program: it controls which lines are hidden by altering the text.
440 The invisible text feature (@pxref{Invisible Text}) has partially
441 replaced this feature.
443 In the second variant, the choice of lines to hide is made
444 automatically based on indentation. This variant is designed to be a
447 The way you control explicit selective display is by replacing a
448 newline (control-j) with a carriage return (control-m). The text that
449 was formerly a line following that newline is now invisible. Strictly
450 speaking, it is temporarily no longer a line at all, since only newlines
451 can separate lines; it is now part of the previous line.
453 Selective display does not directly affect editing commands. For
454 example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly into
455 invisible text. However, the replacement of newline characters with
456 carriage return characters affects some editing commands. For example,
457 @code{next-line} skips invisible lines, since it searches only for
458 newlines. Modes that use selective display can also define commands
459 that take account of the newlines, or that make parts of the text
460 visible or invisible.
462 When you write a selectively displayed buffer into a file, all the
463 control-m's are output as newlines. This means that when you next read
464 in the file, it looks OK, with nothing invisible. The selective display
465 effect is seen only within Emacs.
467 @defvar selective-display
468 This buffer-local variable enables selective display. This means that
469 lines, or portions of lines, may be made invisible.
473 If the value of @code{selective-display} is @code{t}, then the character
474 control-m marks the start of invisible text; the control-m, and the rest
475 of the line following it, are not displayed. This is explicit selective
479 If the value of @code{selective-display} is a positive integer, then
480 lines that start with more than that many columns of indentation are not
484 When some portion of a buffer is invisible, the vertical movement
485 commands operate as if that portion did not exist, allowing a single
486 @code{next-line} command to skip any number of invisible lines.
487 However, character movement commands (such as @code{forward-char}) do
488 not skip the invisible portion, and it is possible (if tricky) to insert
489 or delete text in an invisible portion.
491 In the examples below, we show the @emph{display appearance} of the
492 buffer @code{foo}, which changes with the value of
493 @code{selective-display}. The @emph{contents} of the buffer do not
498 (setq selective-display nil)
501 ---------- Buffer: foo ----------
508 ---------- Buffer: foo ----------
512 (setq selective-display 2)
515 ---------- Buffer: foo ----------
520 ---------- Buffer: foo ----------
525 @defvar selective-display-ellipses
526 If this buffer-local variable is non-@code{nil}, then Emacs displays
527 @samp{@dots{}} at the end of a line that is followed by invisible text.
528 This example is a continuation of the previous one.
532 (setq selective-display-ellipses t)
535 ---------- Buffer: foo ----------
540 ---------- Buffer: foo ----------
544 You can use a display table to substitute other text for the ellipsis
545 (@samp{@dots{}}). @xref{Display Tables}.
549 @section The Overlay Arrow
550 @cindex overlay arrow
552 The @dfn{overlay arrow} is useful for directing the user's attention
553 to a particular line in a buffer. For example, in the modes used for
554 interface to debuggers, the overlay arrow indicates the line of code
555 about to be executed.
557 @defvar overlay-arrow-string
558 This variable holds the string to display to call attention to a
559 particular line, or @code{nil} if the arrow feature is not in use.
560 On a graphical display the contents of the string are ignored; instead a
561 glyph is displayed in the fringe area to the left of the display area.
564 @defvar overlay-arrow-position
565 This variable holds a marker that indicates where to display the overlay
566 arrow. It should point at the beginning of a line. On a non-graphical
567 display the arrow text
568 appears at the beginning of that line, overlaying any text that would
569 otherwise appear. Since the arrow is usually short, and the line
570 usually begins with indentation, normally nothing significant is
573 The overlay string is displayed only in the buffer that this marker
574 points into. Thus, only one buffer can have an overlay arrow at any
576 @c !!! overlay-arrow-position: but the overlay string may remain in the display
577 @c of some other buffer until an update is required. This should be fixed
581 You can do a similar job by creating an overlay with a
582 @code{before-string} property. @xref{Overlay Properties}.
584 @node Temporary Displays
585 @section Temporary Displays
587 Temporary displays are used by Lisp programs to put output into a
588 buffer and then present it to the user for perusal rather than for
589 editing. Many help commands use this feature.
591 @defspec with-output-to-temp-buffer buffer-name forms@dots{}
592 This function executes @var{forms} while arranging to insert any output
593 they print into the buffer named @var{buffer-name}, which is first
594 created if necessary, and put into Help mode. Finally, the buffer is
595 displayed in some window, but not selected.
597 If the @var{forms} do not change the major mode in the output buffer, so
598 that it is still Help mode at the end of their execution, then
599 @code{with-output-to-temp-buffer} makes this buffer read-only at the
600 end, and also scans it for function and variable names to make them into
601 clickable cross-references.
603 The string @var{buffer-name} specifies the temporary buffer, which
604 need not already exist. The argument must be a string, not a buffer.
605 The buffer is erased initially (with no questions asked), and it is
606 marked as unmodified after @code{with-output-to-temp-buffer} exits.
608 @code{with-output-to-temp-buffer} binds @code{standard-output} to the
609 temporary buffer, then it evaluates the forms in @var{forms}. Output
610 using the Lisp output functions within @var{forms} goes by default to
611 that buffer (but screen display and messages in the echo area, although
612 they are ``output'' in the general sense of the word, are not affected).
613 @xref{Output Functions}.
615 Several hooks are available for customizing the behavior
616 of this construct; they are listed below.
618 The value of the last form in @var{forms} is returned.
622 ---------- Buffer: foo ----------
623 This is the contents of foo.
624 ---------- Buffer: foo ----------
628 (with-output-to-temp-buffer "foo"
630 (print standard-output))
631 @result{} #<buffer foo>
633 ---------- Buffer: foo ----------
638 ---------- Buffer: foo ----------
643 @defvar temp-buffer-show-function
644 If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
645 calls it as a function to do the job of displaying a help buffer. The
646 function gets one argument, which is the buffer it should display.
648 It is a good idea for this function to run @code{temp-buffer-show-hook}
649 just as @code{with-output-to-temp-buffer} normally would, inside of
650 @code{save-selected-window} and with the chosen window and buffer
654 @defvar temp-buffer-setup-hook
655 @tindex temp-buffer-setup-hook
656 This normal hook is run by @code{with-output-to-temp-buffer} before
657 evaluating @var{body}. When the hook runs, the help buffer is current.
658 This hook is normally set up with a function to put the buffer in Help
662 @defvar temp-buffer-show-hook
663 This normal hook is run by @code{with-output-to-temp-buffer} after
664 displaying the help buffer. When the hook runs, the help buffer is
665 current, and the window it was displayed in is selected. This hook is
666 normally set up with a function to make the buffer read only, and find
667 function names and variable names in it, provided the major mode is
671 @defun momentary-string-display string position &optional char message
672 This function momentarily displays @var{string} in the current buffer at
673 @var{position}. It has no effect on the undo list or on the buffer's
676 The momentary display remains until the next input event. If the next
677 input event is @var{char}, @code{momentary-string-display} ignores it
678 and returns. Otherwise, that event remains buffered for subsequent use
679 as input. Thus, typing @var{char} will simply remove the string from
680 the display, while typing (say) @kbd{C-f} will remove the string from
681 the display and later (presumably) move point forward. The argument
682 @var{char} is a space by default.
684 The return value of @code{momentary-string-display} is not meaningful.
686 If the string @var{string} does not contain control characters, you can
687 do the same job in a more general way by creating (and then subsequently
688 deleting) an overlay with a @code{before-string} property.
689 @xref{Overlay Properties}.
691 If @var{message} is non-@code{nil}, it is displayed in the echo area
692 while @var{string} is displayed in the buffer. If it is @code{nil}, a
693 default message says to type @var{char} to continue.
695 In this example, point is initially located at the beginning of the
700 ---------- Buffer: foo ----------
701 This is the contents of foo.
703 ---------- Buffer: foo ----------
707 (momentary-string-display
708 "**** Important Message! ****"
710 "Type RET when done reading")
715 ---------- Buffer: foo ----------
716 This is the contents of foo.
717 **** Important Message! ****Second line.
718 ---------- Buffer: foo ----------
720 ---------- Echo Area ----------
721 Type RET when done reading
722 ---------- Echo Area ----------
731 You can use @dfn{overlays} to alter the appearance of a buffer's text on
732 the screen, for the sake of presentation features. An overlay is an
733 object that belongs to a particular buffer, and has a specified
734 beginning and end. It also has properties that you can examine and set;
735 these affect the display of the text within the overlay.
738 * Overlay Properties:: How to read and set properties.
739 What properties do to the screen display.
740 * Managing Overlays:: Creating and moving overlays.
741 * Finding Overlays:: Searching for overlays.
744 @node Overlay Properties
745 @subsection Overlay Properties
747 Overlay properties are like text properties in that the properties that
748 alter how a character is displayed can come from either source. But in
749 most respects they are different. Text properties are considered a part
750 of the text; overlays are specifically considered not to be part of the
751 text. Thus, copying text between various buffers and strings preserves
752 text properties, but does not try to preserve overlays. Changing a
753 buffer's text properties marks the buffer as modified, while moving an
754 overlay or changing its properties does not. Unlike text property
755 changes, overlay changes are not recorded in the buffer's undo list.
756 @xref{Text Properties}, for comparison.
758 These functions are used for reading and writing the properties of an
761 @defun overlay-get overlay prop
762 This function returns the value of property @var{prop} recorded in
763 @var{overlay}, if any. If @var{overlay} does not record any value for
764 that property, but it does have a @code{category} property which is a
765 symbol, that symbol's @var{prop} property is used. Otherwise, the value
769 @defun overlay-put overlay prop value
770 This function sets the value of property @var{prop} recorded in
771 @var{overlay} to @var{value}. It returns @var{value}.
774 See also the function @code{get-char-property} which checks both
775 overlay properties and text properties for a given character.
776 @xref{Examining Properties}.
778 Many overlay properties have special meanings; here is a table
783 @kindex priority @r{(overlay property)}
784 This property's value (which should be a nonnegative number) determines
785 the priority of the overlay. The priority matters when two or more
786 overlays cover the same character and both specify a face for display;
787 the one whose @code{priority} value is larger takes priority over the
788 other, and its face attributes override the face attributes of the lower
791 Currently, all overlays take priority over text properties. Please
792 avoid using negative priority values, as we have not yet decided just
793 what they should mean.
796 @kindex window @r{(overlay property)}
797 If the @code{window} property is non-@code{nil}, then the overlay
798 applies only on that window.
801 @kindex category @r{(overlay property)}
802 If an overlay has a @code{category} property, we call it the
803 @dfn{category} of the overlay. It should be a symbol. The properties
804 of the symbol serve as defaults for the properties of the overlay.
807 @kindex face @r{(overlay property)}
808 This property controls the way text is displayed---for example, which
809 font and which colors. @xref{Faces}, for more information.
811 In the simplest case, the value is a face name. It can also be a list;
812 then each element can be any of these possibilities:
816 A face name (a symbol or string).
819 Starting in Emacs 21, a property list of face attributes. This has the
820 form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
821 face attribute name and @var{value} is a meaningful value for that
822 attribute. With this feature, you do not need to create a face each
823 time you want to specify a particular attribute for certain text.
824 @xref{Face Attributes}.
827 A cons cell of the form @code{(foreground-color . @var{color-name})} or
828 @code{(background-color . @var{color-name})}. These elements specify
829 just the foreground color or just the background color.
831 @code{(foreground-color . @var{color-name})} is equivalent to
832 @code{(:foreground @var{color-name})}, and likewise for the background.
836 @kindex mouse-face @r{(overlay property)}
837 This property is used instead of @code{face} when the mouse is within
838 the range of the overlay.
841 @kindex display @r{(overlay property)}
842 This property activates various features that change the
843 way text is displayed. For example, it can make text appear taller
844 or shorter, higher or lower, wider or narror, or replaced with an image.
845 @xref{Display Property}.
848 @kindex help-echo @r{(text property)}
849 If an overlay has a @code{help-echo} property, then when you move the
850 mouse onto the text in the overlay, Emacs displays a help string in the
851 echo area, or in the tooltip window. For details see @ref{Text
852 help-echo}. This feature is available starting in Emacs 21.
854 @item modification-hooks
855 @kindex modification-hooks @r{(overlay property)}
856 This property's value is a list of functions to be called if any
857 character within the overlay is changed or if text is inserted strictly
860 The hook functions are called both before and after each change.
861 If the functions save the information they receive, and compare notes
862 between calls, they can determine exactly what change has been made
865 When called before a change, each function receives four arguments: the
866 overlay, @code{nil}, and the beginning and end of the text range to be
869 When called after a change, each function receives five arguments: the
870 overlay, @code{t}, the beginning and end of the text range just
871 modified, and the length of the pre-change text replaced by that range.
872 (For an insertion, the pre-change length is zero; for a deletion, that
873 length is the number of characters deleted, and the post-change
874 beginning and end are equal.)
876 @item insert-in-front-hooks
877 @kindex insert-in-front-hooks @r{(overlay property)}
878 This property's value is a list of functions to be called before and
879 after inserting text right at the beginning of the overlay. The calling
880 conventions are the same as for the @code{modification-hooks} functions.
882 @item insert-behind-hooks
883 @kindex insert-behind-hooks @r{(overlay property)}
884 This property's value is a list of functions to be called before and
885 after inserting text right at the end of the overlay. The calling
886 conventions are the same as for the @code{modification-hooks} functions.
889 @kindex invisible @r{(overlay property)}
890 The @code{invisible} property can make the text in the overlay
891 invisible, which means that it does not appear on the screen.
892 @xref{Invisible Text}, for details.
895 @kindex intangible @r{(overlay property)}
896 The @code{intangible} property on an overlay works just like the
897 @code{intangible} text property. @xref{Special Properties}, for details.
899 @item isearch-open-invisible
900 This property tells incremental search how to make an invisible overlay
901 visible, permanently, if the final match overlaps it. @xref{Invisible
904 @item isearch-open-invisible-temporary
905 This property tells incremental search how to make an invisible overlay
906 visible, temporarily, during the search. @xref{Invisible Text}.
909 @kindex before-string @r{(overlay property)}
910 This property's value is a string to add to the display at the beginning
911 of the overlay. The string does not appear in the buffer in any
912 sense---only on the screen.
915 @kindex after-string @r{(overlay property)}
916 This property's value is a string to add to the display at the end of
917 the overlay. The string does not appear in the buffer in any
918 sense---only on the screen.
921 @kindex evaporate @r{(overlay property)}
922 If this property is non-@code{nil}, the overlay is deleted automatically
923 if it ever becomes empty (i.e., if it spans no characters).
926 @cindex keymap of character (and overlays)
927 @kindex local-map @r{(overlay property)}
928 If this property is non-@code{nil}, it specifies a keymap for a portion
929 of the text. The property's value replaces the buffer's local map, when
930 the character after point is within the overlay. @xref{Active Keymaps}.
933 @node Managing Overlays
934 @subsection Managing Overlays
936 This section describes the functions to create, delete and move
937 overlays, and to examine their contents.
939 @defun make-overlay start end &optional buffer front-advance rear-advance
940 This function creates and returns an overlay that belongs to
941 @var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
942 and @var{end} must specify buffer positions; they may be integers or
943 markers. If @var{buffer} is omitted, the overlay is created in the
946 The arguments @var{front-advance} and @var{rear-advance} specify the
947 insertion type for the start of the overlay and for the end of the
948 overlay, respectively. @xref{Marker Insertion Types}.
951 @defun overlay-start overlay
952 This function returns the position at which @var{overlay} starts,
956 @defun overlay-end overlay
957 This function returns the position at which @var{overlay} ends,
961 @defun overlay-buffer overlay
962 This function returns the buffer that @var{overlay} belongs to.
965 @defun delete-overlay overlay
966 This function deletes @var{overlay}. The overlay continues to exist as
967 a Lisp object, and its property list is unchanged, but it ceases to be
968 attached to the buffer it belonged to, and ceases to have any effect on
971 A deleted overlay is not permanently disconnected. You can give it a
972 position in a buffer again by calling @code{move-overlay}.
975 @defun move-overlay overlay start end &optional buffer
976 This function moves @var{overlay} to @var{buffer}, and places its bounds
977 at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
978 must specify buffer positions; they may be integers or markers.
980 If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
981 was already associated with; if @var{overlay} was deleted, it goes into
984 The return value is @var{overlay}.
986 This is the only valid way to change the endpoints of an overlay. Do
987 not try modifying the markers in the overlay by hand, as that fails to
988 update other vital data structures and can cause some overlays to be
992 Here are some examples:
995 ;; @r{Create an overlay.}
996 (setq foo (make-overlay 1 10))
997 @result{} #<overlay from 1 to 10 in display.texi>
1002 (overlay-buffer foo)
1003 @result{} #<buffer display.texi>
1004 ;; @r{Give it a property we can check later.}
1005 (overlay-put foo 'happy t)
1007 ;; @r{Verify the property is present.}
1008 (overlay-get foo 'happy)
1010 ;; @r{Move the overlay.}
1011 (move-overlay foo 5 20)
1012 @result{} #<overlay from 5 to 20 in display.texi>
1017 ;; @r{Delete the overlay.}
1018 (delete-overlay foo)
1020 ;; @r{Verify it is deleted.}
1022 @result{} #<overlay in no buffer>
1023 ;; @r{A deleted overlay has no position.}
1028 (overlay-buffer foo)
1030 ;; @r{Undelete the overlay.}
1031 (move-overlay foo 1 20)
1032 @result{} #<overlay from 1 to 20 in display.texi>
1033 ;; @r{Verify the results.}
1038 (overlay-buffer foo)
1039 @result{} #<buffer display.texi>
1040 ;; @r{Moving and deleting the overlay does not change its properties.}
1041 (overlay-get foo 'happy)
1045 @node Finding Overlays
1046 @subsection Searching for Overlays
1048 @defun overlays-at pos
1049 This function returns a list of all the overlays that cover the
1050 character at position @var{pos} in the current buffer. The list is in
1051 no particular order. An overlay contains position @var{pos} if it
1052 begins at or before @var{pos}, and ends after @var{pos}.
1054 To illustrate usage, here is a Lisp function that returns a list of the
1055 overlays that specify property @var{prop} for the character at point:
1058 (defun find-overlays-specifying (prop)
1059 (let ((overlays (overlays-at (point)))
1062 (let ((overlay (cdr overlays)))
1063 (if (overlay-get overlay prop)
1064 (setq found (cons overlay found))))
1065 (setq overlays (cdr overlays)))
1070 @defun overlays-in beg end
1071 This function returns a list of the overlays that overlap the region
1072 @var{beg} through @var{end}. ``Overlap'' means that at least one
1073 character is contained within the overlay and also contained within the
1074 specified region; however, empty overlays are included in the result if
1075 they are located at @var{beg}, or strictly between @var{beg} and @var{end}.
1078 @defun next-overlay-change pos
1079 This function returns the buffer position of the next beginning or end
1080 of an overlay, after @var{pos}.
1083 @defun previous-overlay-change pos
1084 This function returns the buffer position of the previous beginning or
1085 end of an overlay, before @var{pos}.
1088 Here's an easy way to use @code{next-overlay-change} to search for the
1089 next character which gets a non-@code{nil} @code{happy} property from
1090 either its overlays or its text properties (@pxref{Property Search}):
1093 (defun find-overlay-prop (prop)
1095 (while (and (not (eobp))
1096 (not (get-char-property (point) 'happy)))
1097 (goto-char (min (next-overlay-change (point))
1098 (next-single-property-change (point) 'happy))))
1105 Since not all characters have the same width, these functions let you
1106 check the width of a character. @xref{Primitive Indent}, and
1107 @ref{Screen Lines}, for related functions.
1109 @defun char-width char
1110 This function returns the width in columns of the character @var{char},
1111 if it were displayed in the current buffer and the selected window.
1114 @defun string-width string
1115 This function returns the width in columns of the string @var{string},
1116 if it were displayed in the current buffer and the selected window.
1119 @defun truncate-string-to-width string width &optional start-column padding
1120 This function returns the part of @var{string} that fits within
1121 @var{width} columns, as a new string.
1123 If @var{string} does not reach @var{width}, then the result ends where
1124 @var{string} ends. If one multi-column character in @var{string}
1125 extends across the column @var{width}, that character is not included in
1126 the result. Thus, the result can fall short of @var{width} but cannot
1129 The optional argument @var{start-column} specifies the starting column.
1130 If this is non-@code{nil}, then the first @var{start-column} columns of
1131 the string are omitted from the value. If one multi-column character in
1132 @var{string} extends across the column @var{start-column}, that
1133 character is not included.
1135 The optional argument @var{padding}, if non-@code{nil}, is a padding
1136 character added at the beginning and end of the result string, to extend
1137 it to exactly @var{width} columns. The padding character is used at the
1138 end of the result if it falls short of @var{width}. It is also used at
1139 the beginning of the result if one multi-column character in
1140 @var{string} extends across the column @var{start-column}.
1143 (truncate-string-to-width "\tab\t" 12 4)
1145 (truncate-string-to-width "\tab\t" 12 4 ?\ )
1154 A @dfn{face} is a named collection of graphical attributes: font
1155 family, foreground color, background color, optional underlining, and
1156 many others. Faces are used in Emacs to control the style of display of
1157 particular parts of the text or the frame.
1160 Each face has its own @dfn{face number}, which distinguishes faces at
1161 low levels within Emacs. However, for most purposes, you refer to
1162 faces in Lisp programs by their names.
1165 This function returns @code{t} if @var{object} is a face name symbol (or
1166 if it is a vector of the kind used internally to record face data). It
1167 returns @code{nil} otherwise.
1170 Each face name is meaningful for all frames, and by default it has the
1171 same meaning in all frames. But you can arrange to give a particular
1172 face name a special meaning in one frame if you wish.
1175 * Standard Faces:: The faces Emacs normally comes with.
1176 * Defining Faces:: How to define a face with @code{defface}.
1177 * Face Attributes:: What is in a face?
1178 * Attribute Functions:: Functions to examine and set face attributes.
1179 * Merging Faces:: How Emacs combines the faces specified for a character.
1180 * Font Selection:: Finding the best available font for a face.
1181 * Face Functions:: How to define and examine faces.
1182 * Auto Faces:: Hook for automatic face assignment.
1183 * Font Lookup:: Looking up the names of available fonts
1184 and information about them.
1185 * Fontsets:: A fontset is a collection of fonts
1186 that handle a range of character sets.
1189 @node Standard Faces
1190 @subsection Standard Faces
1192 This table lists all the standard faces and their uses. Most of them
1193 are used for displaying certain parts of the frames or certain kinds of
1194 text; you can control how those places look by customizing these faces.
1198 @kindex default @r{(face name)}
1199 This face is used for ordinary text.
1202 @kindex mode-line @r{(face name)}
1203 This face is used for mode lines, and for menu bars when toolkit menus
1204 are not used---but only if @code{mode-line-inverse-video} is
1208 @kindex modeline @r{(face name)}
1209 This is an alias for the @code{mode-line} face, for compatibility with
1213 @kindex header-line @r{(face name)}
1214 This face is used for the header lines of windows that have them.
1217 This face controls the display of menus, both their colors and their
1218 font. (This works only on certain systems.)
1221 @kindex fringe @r{(face name)}
1222 This face controls the colors of window fringes, the thin areas on
1223 either side that are used to display continuation and truncation glyphs.
1226 @kindex scroll-bar @r{(face name)}
1227 This face controls the colors for display of scroll bars.
1230 @kindex tool-bar @r{(face name)}
1231 This face is used for display of the tool bar, if any.
1234 @kindex region @r{(face name)}
1235 This face is used for highlighting the region in Transient Mark mode.
1237 @item secondary-selection
1238 @kindex secondary-selection @r{(face name)}
1239 This face is used to show any secondary selection you have made.
1242 @kindex highlight @r{(face name)}
1243 This face is meant to be used for highlighting for various purposes.
1245 @item trailing-whitespace
1246 @kindex trailing-whitespace @r{(face name)}
1247 This face is used to display excess whitespace at the end of a line,
1248 if @code{show-trailing-whitespace} is non-@code{nil}.
1251 In contrast, these faces are provided to change the appearance of text
1252 in specific ways. You can use them on specific text, when you want
1253 the effects they produce.
1257 @kindex bold @r{(face name)}
1258 This face uses a bold font, if possible. It uses the bold variant of
1259 the frame's font, if it has one. It's up to you to choose a default
1260 font that has a bold variant, if you want to use one.
1263 @kindex italic @r{(face name)}
1264 This face uses the italic variant of the frame's font, if it has one.
1267 @kindex bold-italic @r{(face name)}
1268 This face uses the bold italic variant of the frame's font, if it has
1272 @kindex underline @r{(face name)}
1273 This face underlines text.
1276 @kindex fixed-patch @r{(face name)}
1277 This face forces use of a particular fixed-width font.
1279 @item variable-patch
1280 @kindex variable-patch @r{(face name)}
1281 This face forces use of a particular variable-width font. It's
1282 reasonable to customize this to use a different variable-width font, if
1283 you like, but you should not make it a fixed-width font.
1286 @defvar show-trailing-whitespace
1287 @tindex show-trailing-whitespace
1288 If this variable is non-@code{nil}, Emacs uses the
1289 @code{trailing-whitespace} face to display any spaces and tabs at the
1293 @node Defining Faces
1294 @subsection Defining Faces
1296 The way to define a new face is with @code{defface}. This creates a
1297 kind of customization item (@pxref{Customization}) which the user can
1298 customize using the Customization buffer (@pxref{Easy Customization,,,
1299 emacs, The GNU Emacs Manual}).
1301 @defmac defface face spec doc [keyword value]...
1302 This declares @var{face} as a customizable face that defaults according
1303 to @var{spec}. You should not quote the symbol @var{face}. The
1304 argument @var{doc} specifies the face documentation. The keywords you
1305 can use in @code{defface} are the same ones that are meaningful in both
1306 @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
1308 When @code{defface} executes, it defines the face according to
1309 @var{spec}, then uses any customizations that were read from the
1310 init file (@pxref{Init File}) to override that specification.
1312 The purpose of @var{spec} is to specify how the face should appear on
1313 different kinds of terminals. It should be an alist whose elements have
1314 the form @code{(@var{display} @var{atts})}. Each element's @sc{car},
1315 @var{display}, specifies a class of terminals. The element's second element,
1316 @var{atts}, is a list of face attributes and their values; it specifies
1317 what the face should look like on that kind of terminal. The possible
1318 attributes are defined in the value of @code{custom-face-attributes}.
1320 The @var{display} part of an element of @var{spec} determines which
1321 frames the element applies to. If more than one element of @var{spec}
1322 matches a given frame, the first matching element is the only one used
1323 for that frame. There are two possibilities for @var{display}:
1327 This element of @var{spec} matches all frames. Therefore, any
1328 subsequent elements of @var{spec} are never used. Normally
1329 @code{t} is used in the last (or only) element of @var{spec}.
1332 If @var{display} is a list, each element should have the form
1333 @code{(@var{characteristic} @var{value}@dots{})}. Here
1334 @var{characteristic} specifies a way of classifying frames, and the
1335 @var{value}s are possible classifications which @var{display} should
1336 apply to. Here are the possible values of @var{characteristic}:
1340 The kind of window system the frame uses---either @code{graphic} (any
1341 graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console),
1342 @code{w32} (for MS Windows 9X/NT), or @code{tty} (a non-graphics-capable
1346 What kinds of colors the frame supports---either @code{color},
1347 @code{grayscale}, or @code{mono}.
1350 The kind of background---either @code{light} or @code{dark}.
1353 If an element of @var{display} specifies more than one @var{value} for a
1354 given @var{characteristic}, any of those values is acceptable. If
1355 @var{display} has more than one element, each element should specify a
1356 different @var{characteristic}; then @emph{each} characteristic of the
1357 frame must match one of the @var{value}s specified for it in
1362 Here's how the standard face @code{region} is defined:
1367 `((((type tty) (class color))
1368 (:background "blue" :foreground "white"))
1370 (((type tty) (class mono))
1372 (((class color) (background dark))
1373 (:background "blue"))
1374 (((class color) (background light))
1375 (:background "lightblue"))
1376 (t (:background "gray")))
1378 "Basic face for highlighting the region."
1379 :group 'basic-faces)
1383 Internally, @code{defface} uses the symbol property
1384 @code{face-defface-spec} to record the face attributes specified in
1385 @code{defface}, @code{saved-face} for the attributes saved by the user
1386 with the customization buffer, and @code{face-documentation} for the
1387 documentation string.
1389 @defopt frame-background-mode
1390 This option, if non-@code{nil}, specifies the background type to use for
1391 interpreting face definitions. If it is @code{dark}, then Emacs treats
1392 all frames as if they had a dark background, regardless of their actual
1393 background colors. If it is @code{light}, then Emacs treats all frames
1394 as if they had a light background.
1397 @node Face Attributes
1398 @subsection Face Attributes
1399 @cindex face attributes
1401 The effect of using a face is determined by a fixed set of @dfn{face
1402 attributes}. This table lists all the face attributes, and what they
1403 mean. Note that in general, more than one face can be specified for a
1404 given piece of text; when that happens, the attributes of all the faces
1405 are merged to specify how to display the text. @xref{Merging Faces}.
1407 In Emacs 21, any attribute in a face can have the value
1408 @code{unspecified}. This means the face doesn't specify that attribute.
1409 In face merging, when the first face fails to specify a particular
1410 attribute, that means the next face gets a chance. However, the
1411 @code{default} face must specify all attributes.
1413 Some of these font attributes are meaningful only on certain kinds of
1414 displays---if your display cannot handle a certain attribute, the
1415 attribute is ignored. (The attributes @code{:family}, @code{:width},
1416 @code{:height}, @code{:weight}, and @code{:slant} correspond to parts of
1417 an X Logical Font Descriptor.)
1421 Font family name, or fontset name (@pxref{Fontsets}). If you specify a
1422 font family name, the wild-card characters @samp{*} and @samp{?} are
1426 Relative proportionate width, also known as the character set width or
1427 set width. This should be one of the symbols @code{ultra-condensed},
1428 @code{extra-condensed}, @code{condensed}, @code{semi-condensed},
1429 @code{normal}, @code{semi-expanded}, @code{expanded},
1430 @code{extra-expanded}, or @code{ultra-expanded}.
1433 Either the font height, an integer in units of 1/10 point, a floating
1434 point number specifying the amount by which to scale the height of any
1435 underlying face, or a function, which is called with the old height
1436 (from the underlying face), and should return the new height.
1439 Font weight---a symbol from this series (from most dense to most faint):
1440 @code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
1441 @code{normal}, @code{semi-light}, @code{light}, @code{extra-light},
1442 or @code{ultra-light}.
1444 On a text-only terminal, any weight greater than normal is displayed as
1445 extra bright, and any weight less than normal is displayed as
1446 half-bright (provided the terminal supports the feature).
1449 Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal},
1450 @code{reverse-italic}, or @code{reverse-oblique}.
1452 On a text-only terminal, slanted text is displayed as half-bright, if
1453 the terminal supports the feature.
1456 Foreground color, a string.
1459 Background color, a string.
1461 @item :inverse-video
1462 Whether or not characters should be displayed in inverse video. The
1463 value should be @code{t} (yes) or @code{nil} (no).
1466 The background stipple, a bitmap.
1468 The value can be a string; that should be the name of a file containing
1469 external-format X bitmap data. The file is found in the directories
1470 listed in the variable @code{x-bitmap-file-path}.
1472 Alternatively, the value can specify the bitmap directly, with a list of
1473 the form @code{(@var{width} @var{height} @var{data})}. Here,
1474 @var{width} and @var{height} specify the size in pixels, and @var{data}
1475 is a string containing the raw bits of the bitmap, row by row. Each row
1476 occupies @math{(@var{width} + 7) / 8} consecutie bytes in the string
1477 (which should be a unibyte string for best results).
1479 If the value is @code{nil}, that means use no stipple pattern.
1481 Normally you do not need to set the stipple attribute, because it is
1482 used automatically to handle certain shades of gray.
1485 Whether or not characters should be underlined, and in what color. If
1486 the value is @code{t}, underlining uses the foreground color of the
1487 face. If the value is a string, underlining uses that color. The
1488 value @code{nil} means do not underline.
1491 Whether or not characters should be overlined, and in what color.
1492 The value is used like that of @code{:underline}.
1494 @item :strike-through
1495 Whether or not characters should be strike-through, and in what
1496 color. The value is used like that of @code{:underline}.
1499 The name of a face from which to inherit attributes, or a list of face
1500 names. Attributes from inherited faces are merged into the face like an
1501 underlying face would be, with higher priority than underlying faces.
1504 Whether or not a box should be drawn around characters, its color, the
1505 width of the box lines, and 3D appearance.
1508 Here are the possible values of the @code{:box} attribute, and what
1516 Draw a box with lines of width 1, in the foreground color.
1519 Draw a box with lines of width 1, in color @var{color}.
1521 @item @code{(:line-width @var{width} :color @var{color} :style @var{style})}
1522 This way you can explicitly specify all aspects of the box. The value
1523 @var{width} specifies the width of the lines to draw; it defaults to 1.
1525 The value @var{color} specifies the color to draw with. The default is
1526 the foreground color of the face for simple boxes, and the background
1527 color of the face for 3D boxes.
1529 The value @var{style} specifies whether to draw a 3D box. If it is
1530 @code{released-button}, the box looks like a 3D button that is not being
1531 pressed. If it is @code{pressed-button}, the box looks like a 3D button
1532 that is being pressed. If it is @code{nil} or omitted, a plain 2D box
1536 The attributes @code{:overline}, @code{:strike-through} and
1537 @code{:box} are new in Emacs 21. The attributes @code{:family},
1538 @code{:height}, @code{:width}, @code{:weight}, @code{:slant} are also
1539 new; previous versions used the following attributes, now semi-obsolete,
1540 to specify some of the same information:
1544 This attribute specifies the font name.
1547 A non-@code{nil} value specifies a bold font.
1550 A non-@code{nil} value specifies an italic font.
1553 For compatibility, you can still set these ``attributes'' in Emacs 21,
1554 even though they are not real face attributes. Here is what that does:
1558 You can specify an X font name as the ``value'' of this ``attribute'';
1559 that sets the @code{:family}, @code{:width}, @code{:height},
1560 @code{:weight}, and @code{:slant} attributes according to the font name.
1562 If the value is a pattern with wildcards, the first font that matches
1563 the pattern is used to set these attributes.
1566 A non-@code{nil} makes the face bold; @code{nil} makes it normal.
1567 This actually works by setting the @code{:weight} attribute.
1570 A non-@code{nil} makes the face italic; @code{nil} makes it normal.
1571 This actually works by setting the @code{:slant} attribute.
1574 @defvar x-bitmap-file-path
1575 This variable specifies a list of directories for searching
1576 for bitmap files, for the @code{:stipple} attribute.
1579 @defun bitmap-spec-p object
1580 This returns @code{t} if @var{object} is a valid bitmap
1581 specification, suitable for use with @code{:stipple}.
1582 It returns @code{nil} otherwise.
1585 @node Attribute Functions
1586 @subsection Face Attribute Functions
1588 You can modify the attributes of an existing face with the following
1589 functions. If you specify @var{frame}, they affect just that frame;
1590 otherwise, they affect all frames as well as the defaults that apply to
1593 @tindex set-face-attribute
1594 @defun set-face-attribute face frame &rest arguments
1595 This function sets one or more attributes of face @var{face}
1596 for frame @var{frame}. If @var{frame} is @code{nil}, it sets
1597 the attribute for all frames, and the defaults for new frames.
1599 The extra arguments @var{arguments} specify the attributes to set, and
1600 the values for them. They should consist of alternating attribute names
1601 (such as @code{:family} or @code{:underline}) and corresponding values.
1605 (set-face-attribute 'foo nil
1612 sets the attributes @code{:width}, @code{:weight} and @code{:underline}
1613 to the corresponding values.
1616 @tindex face-attribute
1617 @defun face-attribute face attribute &optional frame
1618 This returns the value of the @var{attribute} attribute of face
1619 @var{face} on @var{frame}. If @var{frame} is @code{nil},
1620 that means the selected frame.
1622 If @var{frame} is @code{t}, the value is the default for
1623 @var{face} for new frames.
1628 (face-attribute 'bold :weight)
1633 The functions above did not exist before Emacs 21. For compatibility
1634 with older Emacs versions, you can use the following functions to set
1635 and examine the face attributes which existed in those versions.
1637 @defun set-face-foreground face color &optional frame
1638 @defunx set-face-background face color &optional frame
1639 These functions set the foreground (or background, respectively) color
1640 of face @var{face} to @var{color}. The argument @var{color} should be a
1641 string, the name of a color.
1643 Certain shades of gray are implemented by stipple patterns on
1644 black-and-white screens.
1647 @defun set-face-stipple face pattern &optional frame
1648 This function sets the background stipple pattern of face @var{face} to
1649 @var{pattern}. The argument @var{pattern} should be the name of a
1650 stipple pattern defined by the X server, or @code{nil} meaning don't use
1653 Normally there is no need to pay attention to stipple patterns, because
1654 they are used automatically to handle certain shades of gray.
1657 @defun set-face-font face font &optional frame
1658 This function sets the font of face @var{face}.
1660 In Emacs 21, this actually sets the attributes @code{:family},
1661 @code{:width}, @code{:height}, @code{:weight}, and @code{:slant}
1662 according to the font name @var{font}.
1664 In Emacs 20, this sets the font attribute. Once you set the font
1665 explicitly, the bold and italic attributes cease to have any effect,
1666 because the precise font that you specified is used.
1669 @defun set-face-bold-p face bold-p &optional frame
1670 This function specifies whether @var{face} should be bold. If
1671 @var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no.
1673 In Emacs 21, this sets the @code{:weight} attribute.
1674 In Emacs 20, it sets the @code{:bold} attribute.
1677 @defun set-face-italic-p face italic-p &optional frame
1678 This function specifies whether @var{face} should be italic. If
1679 @var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no.
1681 In Emacs 21, this sets the @code{:slant} attribute.
1682 In Emacs 20, it sets the @code{:italic} attribute.
1685 @defun set-face-underline-p face underline-p &optional frame
1686 This function sets the underline attribute of face @var{face}.
1687 Non-@code{nil} means do underline; @code{nil} means don't.
1690 @defun invert-face face &optional frame
1691 This function inverts the @code{:inverse-video} attribute of face
1692 @var{face}. If the attribute is @code{nil}, this function sets it to
1693 @code{t}, and vice versa.
1696 These functions examine the attributes of a face. If you don't
1697 specify @var{frame}, they refer to the default data for new frames.
1698 They return the symbol @code{unspecified} if the face doesn't define any
1699 value for that attribute.
1701 @defun face-foreground face &optional frame
1702 @defunx face-background face &optional frame
1703 These functions return the foreground color (or background color,
1704 respectively) of face @var{face}, as a string.
1707 @defun face-stipple face &optional frame
1708 This function returns the name of the background stipple pattern of face
1709 @var{face}, or @code{nil} if it doesn't have one.
1712 @defun face-font face &optional frame
1713 This function returns the name of the font of face @var{face}.
1716 @defun face-bold-p face &optional frame
1717 This function returns @code{t} if @var{face} is bold---that is, if it is
1718 bolder than normal. It returns @code{nil} otherwise.
1721 @defun face-italic-p face &optional frame
1722 This function returns @code{t} if @var{face} is italic or oblique,
1723 @code{nil} otherwise.
1726 @defun face-underline-p face &optional frame
1727 This function returns the @code{:underline} attribute of face @var{face}.
1730 @defun face-inverse-video-p face &optional frame
1731 This function returns the @code{:inverse-video} attribute of face @var{face}.
1735 @subsection Merging Faces for Display
1737 Here are the ways to specify which faces to use for display of text:
1741 With defaults. The @code{default} face is used as the ultimate
1742 default for all text. (In Emacs 19 and 20, the @code{default}
1743 face is used only when no other face is specified.)
1745 For a mode line or header line, the face @code{modeline} or
1746 @code{header-line} is used just before @code{default}.
1749 With text properties. A character can have a @code{face} property; if
1750 so, the faces and face attributes specified there apply. @xref{Special
1753 If the character has a @code{mouse-face} property, that is used instead
1754 of the @code{face} property when the mouse is ``near enough'' to the
1758 With overlays. An overlay can have @code{face} and @code{mouse-face}
1759 properties too; they apply to all the text covered by the overlay.
1762 With a region that is active. In Transient Mark mode, the region is
1763 highlighted with the face @code{region} (@pxref{Standard Faces}).
1766 With special glyphs. Each glyph can specify a particular face
1767 number. @xref{Glyphs}.
1770 If these various sources together specify more than one face for a
1771 particular character, Emacs merges the attributes of the various faces
1772 specified. The attributes of the faces of special glyphs come first;
1773 then comes the face for region highlighting, if appropriate;
1774 then come attributes of faces from overlays, followed by those from text
1775 properties, and last the default face.
1777 When multiple overlays cover one character, an overlay with higher
1778 priority overrides those with lower priority. @xref{Overlays}.
1780 In Emacs 20, if an attribute such as the font or a color is not
1781 specified in any of the above ways, the frame's own font or color is
1782 used. In newer Emacs versions, this cannot happen, because the
1783 @code{default} face specifies all attributes---in fact, the frame's own
1784 font and colors are synonymous with those of the default face.
1786 @node Font Selection
1787 @subsection Font Selection
1789 @dfn{Selecting a font} means mapping the specified face attributes for
1790 a character to a font that is available on a particular display. The
1791 face attributes, as determined by face merging, specify most of the
1792 font choice, but not all. Part of the choice depends on what character
1795 For multibyte characters, typically each font covers only one
1796 character set. So each character set (@pxref{Character Sets}) specifies
1797 a registry and encoding to use, with the character set's
1798 @code{x-charset-registry} property. Its value is a string containing
1799 the registry and the encoding, with a dash between them:
1802 (plist-get (charset-plist 'latin-iso8859-1)
1803 'x-charset-registry)
1804 @result{} "ISO8859-1"
1807 Unibyte text does not have character sets, so displaying a unibyte
1808 character takes the registry and encoding from the variable
1809 @code{face-default-registry}.
1811 @defvar face-default-registry
1812 This variable specifies which registry and encoding to use in choosing
1813 fonts for unibyte characters. The value is initialized at Emacs startup
1814 time from the font the user specified for Emacs.
1817 If the face specifies a fontset name, that fontset determines a
1818 pattern for fonts of the given charset. If the face specifies a font
1819 family, a font pattern is constructed.
1821 Emacs tries to find an available font for the given face attributes
1822 and character's registry and encoding. If there is a font that matches
1823 exactly, it is used, of course. The hard case is when no available font
1824 exactly fits the specification. Then Emacs looks for one that is
1825 ``close''---one attribute at a time. You can specify the order to
1826 consider the attributes. In the case where a specified font family is
1827 not available, you can specify a set of mappings for alternatives to
1830 @defvar face-font-selection-order
1831 @tindex face-font-selection-order
1832 This variable specifies the order of importance of the face attributes
1833 @code{:width}, @code{:height}, @code{:weight}, and @code{:slant}. The
1834 value should be a list containing those four symbols, in order of
1835 decreasing importance.
1837 Font selection first finds the best available matches for the first
1838 attribute listed; then, among the fonts which are best in that way, it
1839 searches for the best matches in the second attribute, and so on.
1841 The attributes @code{:weight} and @code{:width} have symbolic values in
1842 a range centered around @code{normal}. Matches that are more extreme
1843 (farther from @code{normal}) are somewhat preferred to matches that are
1844 less extreme (closer to @code{normal}); this is designed to ensure that
1845 non-normal faces contrast with normal ones, whenever possible.
1847 The default is @code{(:width :height :weight :slant)}, which means first
1848 find the fonts closest to the specified @code{:width}, then---among the
1849 fonts with that width---find a best match for the specified font height,
1852 One example of a case where this variable makes a difference is when the
1853 default font has no italic equivalent. With the default ordering, the
1854 @code{italic} face will use a non-italic font that is similar to the
1855 default one. But if you put @code{:slant} before @code{:height}, the
1856 @code{italic} face will use an italic font, even if its height is not
1860 @defvar face-font-family-alternatives
1861 @tindex face-font-family-alternatives
1862 This variable lets you specify alternative font families to try, if a
1863 given family is specified and doesn't exist. Each element should have
1867 (@var{family} @var{alternate-families}@dots{})
1870 If @var{family} is specified but not available, Emacs will try the other
1871 families given in @var{alternate-families}, one by one, until it finds a
1872 family that does exist.
1875 @defvar face-font-registry-alternatives
1876 @tindex face-font-registry-alternatives
1877 This variable lets you specify alternative font registries to try, if a
1878 given registry is specified and doesn't exist. Each element should have
1882 (@var{registry} @var{alternate-registries}@dots{})
1885 If @var{registry} is specified but not available, Emacs will try the
1886 other registries given in @var{alternate-registries}, one by one,
1887 until it finds a registry that does exist.
1890 Emacs can make use of scalable fonts, but by default it does not use
1891 them, since the use of too many or too big scalable fonts can crash
1894 @defvar scalable-fonts-allowed
1895 @tindex scalable-fonts-allowed
1896 This variable controls which scalable fonts to use. A value of
1897 @code{nil}, the default, means do not use scalable fonts. @code{t}
1898 means to use any scalable font that seems appropriate for the text.
1900 Otherwise, the value must be a list of regular expressions. Then a
1901 scalable font is enabled for use if its name matches any regular
1902 expression in the list. For example,
1905 (setq scalable-fonts-allowed '("muleindian-2$"))
1909 allows the use of scalable fonts with registry @code{muleindian-2}.
1912 @defun clear-face-cache &optional unload-p
1913 @tindex clear-face-cache
1914 This function clears the face cache for all frames.
1915 If @var{unload-p} is non-@code{nil}, that means to unload
1916 all unused fonts as well.
1919 @node Face Functions
1920 @subsection Functions for Working with Faces
1922 Here are additional functions for creating and working with faces.
1924 @defun make-face name
1925 This function defines a new face named @var{name}, initially with all
1926 attributes @code{nil}. It does nothing if there is already a face named
1931 This function returns a list of all defined face names.
1934 @defun copy-face old-face new-name &optional frame new-frame
1935 This function defines the face @var{new-name} as a copy of the existing
1936 face named @var{old-face}. It creates the face @var{new-name} if that
1937 doesn't already exist.
1939 If the optional argument @var{frame} is given, this function applies
1940 only to that frame. Otherwise it applies to each frame individually,
1941 copying attributes from @var{old-face} in each frame to @var{new-face}
1944 If the optional argument @var{new-frame} is given, then @code{copy-face}
1945 copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
1950 This function returns the face number of face @var{face}.
1953 @defun face-documentation face
1954 This function returns the documentation string of face @var{face}, or
1955 @code{nil} if none was specified for it.
1958 @defun face-equal face1 face2 &optional frame
1959 This returns @code{t} if the faces @var{face1} and @var{face2} have the
1960 same attributes for display.
1963 @defun face-differs-from-default-p face &optional frame
1964 This returns @code{t} if the face @var{face} displays differently from
1965 the default face. A face is considered to be ``the same'' as the
1966 default face if each attribute is either the same as that of the default
1967 face, or unspecified (meaning to inherit from the default).
1971 @subsection Automatic Face Assignment
1972 @cindex automatic face assignment
1973 @cindex faces, automatic choice
1975 @cindex Font-Lock mode
1976 Starting with Emacs 21, a hook is available for automatically
1977 assigning faces to text in the buffer. This hook is used for part of
1978 the implementation of Font-Lock mode.
1980 @tindex fontification-functions
1981 @defvar fontification-functions
1982 This variable holds a list of functions that are called by Emacs
1983 redisplay as needed to assign faces automatically to text in the buffer.
1985 The functions are called in the order listed, with one argument, a
1986 buffer position @var{pos}. Each function should attempt to assign faces
1987 to the text in the current buffer starting at @var{pos}.
1989 Each function should record the faces they assign by setting the
1990 @code{face} property. It should also add a non-@code{nil}
1991 @code{fontified} property for all the text it has assigned faces to.
1992 That property tells redisplay that faces have been assigned to that text
1995 It is probably a good idea for each function to do nothing if the
1996 character after @var{pos} already has a non-@code{nil} @code{fontified}
1997 property, but this is not required. If one function overrides the
1998 assignments made by a previous one, the properties as they are
1999 after the last function finishes are the ones that really matter.
2001 For efficiency, we recommend writing these functions so that they
2002 usually assign faces to around 400 to 600 characters at each call.
2006 @subsection Looking Up Fonts
2008 @defun x-list-fonts pattern &optional face frame maximum
2009 This function returns a list of available font names that match
2010 @var{pattern}. If the optional arguments @var{face} and @var{frame} are
2011 specified, then the list is limited to fonts that are the same size as
2012 @var{face} currently is on @var{frame}.
2014 The argument @var{pattern} should be a string, perhaps with wildcard
2015 characters: the @samp{*} character matches any substring, and the
2016 @samp{?} character matches any single character. Pattern matching
2017 of font names ignores case.
2019 If you specify @var{face} and @var{frame}, @var{face} should be a face name
2020 (a symbol) and @var{frame} should be a frame.
2022 The optional argument @var{maximum} sets a limit on how many fonts to
2023 return. If this is non-@code{nil}, then the return value is truncated
2024 after the first @var{maximum} matching fonts. Specifying a small value
2025 for @var{maximum} can make this function much faster, in cases where
2026 many fonts match the pattern.
2029 These additional functions are available starting in Emacs 21.
2031 @defun x-family-fonts &optional family frame
2032 @tindex x-family-fonts
2033 This function returns a list describing the available fonts for family
2034 @var{family} on @var{frame}. If @var{family} is omitted or @code{nil},
2035 this list applies to all families, and therefore, it contains all
2036 available fonts. Otherwise, @var{family} must be a string; it may
2037 contain the wildcards @samp{?} and @samp{*}.
2039 The list describes the display that @var{frame} is on; if @var{frame} is
2040 omitted or @code{nil}, it applies to the selected frame's display.
2042 The list contains a vector of the following form for each font:
2045 [@var{family} @var{width} @var{point-size} @var{weight} @var{slant}
2046 @var{fixed-p} @var{full} @var{registry-and-encoding}]
2049 The first five elements correspond to face attributes; if you
2050 specify these attributes for a face, it will use this font.
2052 The last three elements give additional information about the font.
2053 @var{fixed-p} is non-nil if the font is fixed-pitch. @var{full} is the
2054 full name of the font, and @var{registry-and-encoding} is a string
2055 giving the registry and encoding of the font.
2057 The result list is sorted according to the current face font sort order.
2060 @defun x-font-family-list &optional frame
2061 @tindex x-font-family-list
2062 This function returns a list of the font families available for
2063 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, it
2064 describes the selected frame's display.
2066 The value is a list of elements of this form:
2069 (@var{family} . @var{fixed-p})
2073 Here @var{family} is a font family, and @var{fixed-p} is
2074 non-@code{nil} if fonts of that family are fixed-pitch.
2077 @defvar font-list-limit
2078 @tindex font-list-limit
2079 This variable specifies maximum number of fonts to consider in font
2080 matching. The function @code{x-family-fonts} will not return more than
2081 that many fonts, and font selection will consider only that many fonts
2082 when searching a matching font for face attributes. The default is
2087 @subsection Fontsets
2089 A @dfn{fontset} is a list of fonts, each assigned to a range of
2090 character codes. An individual font cannot display the whole range of
2091 characters that Emacs supports, but a fontset can. Fontsets have names,
2092 just as fonts do, and you can use a fontset name in place of a font name
2093 when you specify the ``font'' for a frame or a face. Here is
2094 information about defining a fontset under Lisp program control.
2096 @defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
2097 This function defines a new fontset according to the specification
2098 string @var{fontset-spec}. The string should have this format:
2101 @var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
2105 Whitespace characters before and after the commas are ignored.
2107 The first part of the string, @var{fontpattern}, should have the form of
2108 a standard X font name, except that the last two fields should be
2109 @samp{fontset-@var{alias}}.
2111 The new fontset has two names, one long and one short. The long name is
2112 @var{fontpattern} in its entirety. The short name is
2113 @samp{fontset-@var{alias}}. You can refer to the fontset by either
2114 name. If a fontset with the same name already exists, an error is
2115 signaled, unless @var{noerror} is non-@code{nil}, in which case this
2116 function does nothing.
2118 If optional argument @var{style-variant-p} is non-@code{nil}, that says
2119 to create bold, italic and bold-italic variants of the fontset as well.
2120 These variant fontsets do not have a short name, only a long one, which
2121 is made by altering @var{fontpattern} to indicate the bold or italic
2124 The specification string also says which fonts to use in the fontset.
2125 See below for the details.
2128 The construct @samp{@var{charset}:@var{font}} specifies which font to
2129 use (in this fontset) for one particular character set. Here,
2130 @var{charset} is the name of a character set, and @var{font} is the font
2131 to use for that character set. You can use this construct any number of
2132 times in the specification string.
2134 For the remaining character sets, those that you don't specify
2135 explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
2136 @samp{fontset-@var{alias}} with a value that names one character set.
2137 For the @sc{ascii} character set, @samp{fontset-@var{alias}} is replaced
2138 with @samp{ISO8859-1}.
2140 In addition, when several consecutive fields are wildcards, Emacs
2141 collapses them into a single wildcard. This is to prevent use of
2142 auto-scaled fonts. Fonts made by scaling larger fonts are not usable
2143 for editing, and scaling a smaller font is not useful because it is
2144 better to use the smaller font in its own size, which Emacs does.
2146 Thus if @var{fontpattern} is this,
2149 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
2153 the font specification for @sc{ascii} characters would be this:
2156 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
2160 and the font specification for Chinese GB2312 characters would be this:
2163 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
2166 You may not have any Chinese font matching the above font
2167 specification. Most X distributions include only Chinese fonts that
2168 have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
2169 such a case, @samp{Fontset-@var{n}} can be specified as below:
2172 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
2173 chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
2177 Then, the font specifications for all but Chinese GB2312 characters have
2178 @samp{fixed} in the @var{family} field, and the font specification for
2179 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
2182 @node Display Property
2183 @section The @code{display} Property
2184 @cindex display specification
2185 @kindex display @r{(text property)}
2187 The @code{display} text property (or overlay property) is used to
2188 insert images into text, and also control other aspects of how text
2189 displays. These features are available starting in Emacs 21. The value
2190 of the @code{display} property should be a display specification, or a
2191 list or vector containing several display specifications. The rest of
2192 this section describes several kinds of display specifications and what
2196 * Specified Space:: Displaying one space with a specified width.
2197 * Other Display Specs:: Displaying an image; magnifying text; moving it
2198 up or down on the page; adjusting the width
2199 of spaces within text.
2200 * Display Margins:: Displaying text or images to the side of the main text.
2201 * Conditional Display:: Making any of the above features conditional
2202 depending on some Lisp expression.
2205 @node Specified Space
2206 @subsection Specified Spaces
2207 @cindex spaces, specified height or width
2208 @cindex specified spaces
2209 @cindex variable-width spaces
2211 To display a space of specified width and/or height, use a display
2212 specification of the form @code{(space . @var{props})}, where
2213 @var{props} is a property list (a list of alternating properties and
2214 values). You can put this property on one or more consecutive
2215 characters; a space of the specified height and width is displayed in
2216 place of @emph{all} of those characters. These are the properties you
2217 can use to specify the weight of the space:
2220 @item :width @var{width}
2221 Specifies that the space width should be @var{width} times the normal
2222 character width. @var{width} can be an integer or floating point
2225 @item :relative-width @var{factor}
2226 Specifies that the width of the stretch should be computed from the
2227 first character in the group of consecutive characters that have the
2228 same @code{display} property. The space width is the width of that
2229 character, multiplied by @var{factor}.
2231 @item :align-to @var{hpos}
2232 Specifies that the space should be wide enough to reach @var{hpos}. The
2233 value @var{hpos} is measured in units of the normal character width. It
2234 may be an interer or a floating point number.
2237 Exactly one of the above properties should be used. You can also
2238 specify the height of the space, with other properties:
2241 @item :height @var{height}
2242 Specifies the height of the space, as @var{height},
2243 measured in terms of the normal line height.
2245 @item :relative-height @var{factor}
2246 Specifies the height of the space, multiplying the ordinary height
2247 of the text having this display specification by @var{factor}.
2249 @item :ascent @var{ascent}
2250 Specifies that @var{ascent} percent of the height of the space should be
2251 considered as the ascent of the space---that is, the part above the
2252 baseline. The value of @var{ascent} must be a non-negative number no
2256 You should not use both @code{:height} and @code{:relative-height}
2259 @node Other Display Specs
2260 @subsection Other Display Specifications
2263 @item (image . @var{image-props})
2264 This is in fact an image descriptor (@pxref{Images}). When used as a
2265 display specification, it means to display the image instead of the text
2266 that has the display specification.
2268 @item ((margin nil) @var{string})
2270 A display specification of this form means to display @var{string}
2271 instead of the text that has the display specification, at the same
2272 position as that text. This is a special case of marginal display
2273 (@pxref{Display Margins}).
2275 @item (space-width @var{factor})
2276 This display specification affects all the space characters within the
2277 text that has the specification. It displays all of these spaces
2278 @var{factor} times as wide as normal. The element @var{factor} should
2279 be an integer or float. Characters other than spaces are not affected
2280 at all; in particular, this has no effect on tab characters.
2282 @item (height @var{height})
2283 This display specification makes the text taller or shorter.
2284 Here are the possibilities for @var{height}:
2287 @item @code{(+ @var{n})}
2288 This means to use a font that is @var{n} steps larger. A ``step'' is
2289 defined by the set of available fonts---specifically, those that match
2290 what was otherwise specified for this text, in all attributes except
2291 height. Each size for which a suitable font is available counts as
2292 another step. @var{n} should be an integer.
2294 @item @code{(- @var{n})}
2295 This means to use a font that is @var{n} steps smaller.
2297 @item a number, @var{factor}
2298 A number, @var{factor}, means to use a font that is @var{factor} times
2299 as tall as the default font.
2301 @item a symbol, @var{function}
2302 A symbol is a function to compute the height. It is called with the
2303 current height as argument, and should return the new height to use.
2305 @item anything else, @var{form}
2306 If the @var{height} value doesn't fit the previous possibilities, it is
2307 a form. Emacs evaluates it to get the new height, with the symbol
2308 @code{height} bound to the current specified font height.
2311 @item (raise @var{factor})
2312 This kind of display specification raises or lowers the text
2313 it applies to, relative to the baseline of the line.
2315 @var{factor} must be a number, which is interpreted as a multiple of the
2316 height of the affected text. If it is positive, that means to display
2317 the characters raised. If it is negative, that means to display them
2320 If the text also has a @code{height} display specification, that does
2321 not affect the amount of raising or lowering, which is based on the
2322 faces used for the text.
2325 @node Display Margins
2326 @subsection Displaying in the Margins
2327 @cindex display margins
2328 @cindex margins, display
2330 A buffer can have blank areas called @dfn{display margins} on the left
2331 and on the right. Ordinary text never appears in these areas, but you
2332 can put things into the display margins using the @code{display}
2335 To put text in the left or right display margin of the window, use a
2336 display specification of the form @code{(margin right-margin)} or
2337 @code{(margin left-margin)} on it. To put an image in a display margin,
2338 use that display specification along with the display specification for
2341 Before the display margins can display anything, you must give
2342 them a nonzero width. The usual way to do that is to set these
2345 @defvar left-margin-width
2346 @tindex left-margin-width
2347 This variable specifies the width of the left margin.
2348 It is buffer-local in all buffers.
2351 @defvar right-margin-width
2352 @tindex right-margin-width
2353 This variable specifies the width of the right margin.
2354 It is buffer-local in all buffers.
2357 Setting these variables does not immediately affect the window. These
2358 variables are checked when a new buffer is displayed in the window.
2359 Thus, you can make changes take effect by calling
2360 @code{set-window-buffer}.
2362 You can also set the margin widths immediately.
2364 @defun set-window-margins window left right
2365 @tindex set-window-margins
2366 This function specifies the margin widths for window @var{window}.
2367 The argument @var{left} controls the left margin and
2368 @var{right} controls the right margin.
2371 @defun window-margins &optional window
2372 @tindex window-margins
2373 This function returns the left and right margins of @var{window}
2374 as a cons cell of the form @code{(@var{left} . @var{right})}.
2375 If @var{window} is @code{nil}, the selected window is used.
2378 @node Conditional Display
2379 @subsection Conditional Display Specifications
2380 @cindex conditional display specifications
2382 You can make any display specification conditional. To do that,
2383 package it in another list of the form @code{(when @var{condition} .
2384 @var{spec})}. Then the specification @var{spec} applies only when
2385 @var{condition} evaluates to a non-@code{nil} value. During the
2386 evaluation, point is temporarily set at the end position of the text
2387 having this conditional display specification.
2391 @cindex images in buffers
2393 To display an image in an Emacs buffer, you must first create an image
2394 descriptor, then use it as a display specifier in the @code{display}
2395 property of text that is displayed (@pxref{Display Property}). Like the
2396 @code{display} property, this feature is available starting in Emacs 21.
2398 Emacs can display a number of different image formats; some of them
2399 are supported only if particular support libraries are installed on your
2400 machine. The supported image formats include XBM, XPM (needing the
2401 libraries @code{libXpm} version 3.4k and @code{libz}), GIF (needing
2402 @code{libungif} 4.1.0), Postscript, PBM, JPEG (needing the
2403 @code{libjpeg} library version v6a), TIFF (needing @code{libtiff} v3.4),
2404 and PNG (needing @code{libpng} 1.0.2).
2406 You specify one of these formats with an image type symbol. The image
2407 type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
2408 @code{pbm}, @code{jpeg}, @code{tiff}, and @code{png}.
2411 This variable contains a list of those image type symbols that are
2412 supported in the current configuration.
2416 * Image Descriptors:: How to specify an image for use in @code{:display}.
2417 * XBM Images:: Special features for XBM format.
2418 * XPM Images:: Special features for XPM format.
2419 * GIF Images:: Special features for GIF format.
2420 * Postscript Images:: Special features for Postscript format.
2421 * Other Image Types:: Various other formats are supported.
2422 * Defining Images:: Convenient ways to define an image for later use.
2423 * Showing Images:: Convenient ways to display an image once it is defined.
2424 * Image Cache:: Internal mechanisms of image display.
2427 @node Image Descriptors
2428 @subsection Image Descriptors
2429 @cindex image descriptor
2431 An image description is a list of the form @code{(image
2432 . @var{props})}, where @var{props} is a property list containing
2433 alternating keyword symbols (symbols whose names start with a colon) and
2434 their values. You can use any Lisp object as a property, but the only
2435 properties that have any special meaning are certain symbols, all of
2438 Every image descriptor must contain the property @code{:type
2439 @var{type}} to specify the format of the image. The value of @var{type}
2440 should be an image type symbol; for example, @code{xpm} for an image in
2443 Here is a list of other properties that are meaningful for all image
2447 @item :ascent @var{ascent}
2448 The @code{:ascent} property specifies the amount of the image's
2449 height to use for its ascent---that is, the part above the baseline.
2450 The value, @var{ascent}, must be a number in the range 0 to 100, or
2451 the symbol @code{center}.
2453 If @var{ascent} is a number, that percentage of the image's height is
2454 used for its ascent.
2456 If @var{ascent} is @code{center}, the image is vertically centered
2457 around a centerline which would be the vertical centerline of text drawn
2458 at the position of the image, in the manner specified by the text
2459 properties and overlays that apply to the image.
2461 If this property is omitted, it defaults to 50.
2463 @item :margin @var{margin}
2464 The @code{:margin} property specifies how many pixels to add as an extra
2465 margin around the image. The value, @var{margin}, must be a
2466 non-negative number; if it is not specified, the default is zero.
2468 @item :relief @var{relief}
2469 The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle
2470 around the image. The value, @var{relief}, specifies the width of the
2471 shadow lines, in pixels. If @var{relief} is negative, shadows are drawn
2472 so that the image appears as a pressed button; otherwise, it appears as
2473 an unpressed button.
2475 @item :algorithm @var{algorithm}
2476 The @code{:algorithm} property, if non-@code{nil}, specifies a
2477 conversion algorithm that should be applied to the image before it is
2478 displayed; the value, @var{algorithm}, specifies which algorithm.
2480 Currently, the only meaningful value for @var{algorithm} (aside from
2481 @code{nil}) is @code{laplace}; this applies the Laplace edge detection
2482 algorithm, which blurs out small differences in color while highlighting
2483 larger differences. People sometimes consider this useful for
2484 displaying the image for a ``disabled'' button.
2486 @item :heuristic-mask @var{transparent-color}
2487 The @code{:heuristic-mask} property, if non-@code{nil}, specifies that a
2488 certain color in the image should be transparent. Each pixel where this
2489 color appears will actually allow the frame's background to show
2492 If @var{transparent-color} is @code{t}, then determine the transparent
2493 color by looking at the four corners of the image. This uses the color
2494 that occurs most frequently near the corners as the transparent color.
2496 Otherwise, @var{heuristic-mask} should specify the transparent color
2497 directly, as a list of three integers in the form @code{(@var{red}
2498 @var{green} @var{blue})}.
2500 @item :file @var{file}
2501 The @code{:file} property specifies to load the image from file
2502 @var{file}. If @var{file} is not an absolute file name, it is expanded
2503 in @code{data-directory}.
2505 @item :data @var{data}
2506 The @code{:data} property specifies the actual contents of the image.
2507 Each image must use either @code{:data} or @code{:file}, but not both.
2508 For most image types, the value of the @code{:data} property should be a
2509 string containing the image data; we recommend using a unibyte string.
2511 Before using @code{:data}, look for further information in the section
2512 below describing the specific image format. For some image types,
2513 @code{:data} may not be supported; for some, it allows other data types;
2514 for some, @code{:data} alone is not enough, so you need to use other
2515 image properties along with @code{:data}.
2519 @subsection XBM Images
2522 To use XBM format, specify @code{xbm} as the image type. This image
2523 format doesn't require an external library, so images of this type are
2526 Additional image properties supported for the @code{xbm} image type are:
2529 @item :foreground @var{foreground}
2530 The value, @var{foreground}, should be a string specifying the image
2531 foreground color. This color is used for each pixel in the XBM that is
2532 1. The default is the frame's foreground color.
2534 @item :background @var{background}
2535 The value, @var{background}, should be a string specifying the image
2536 background color. This color is used for each pixel in the XBM that is
2537 0. The default is the frame's background color.
2540 If you specify an XBM image using data within Emacs instead of an
2541 external file, use the following three properties:
2544 @item :data @var{data}
2545 The value, @var{data}, specifies the contents of the image.
2546 There are three formats you can use for @var{data}:
2550 A vector of strings or bool-vectors, each specifying one line of the
2551 image. Do specify @code{:height} and @code{:width}.
2554 A string containing the same byte sequence as an XBM file would contain.
2555 You must not specify @code{:height} and @code{:width} in this case,
2556 because omitting them is what indicates the data has the format of an
2557 XBM file. The file contents specify the height and width of the image.
2560 A string or a bool-vector containing the bits of the image (plus perhaps
2561 some extra bits at the end that will not be used). It should contain at
2562 least @var{width} * @code{height} bits. In this case, you must specify
2563 @code{:height} and @code{:width}, both to indicate that the string
2564 contains just the bits rather than a whole XBM file, and to specify the
2568 @item :width @var{width}
2569 The value, @var{width}, specifies the width of the image, in pixels.
2571 @item :height @var{height}
2572 The value, @var{height}, specifies the height of the image, in pixels.
2576 @subsection XPM Images
2579 To use XPM format, specify @code{xpm} as the image type. The
2580 additional image property @code{:color-symbols} is also meaningful with
2581 the @code{xpm} image type:
2584 @item :color-symbols @var{symbols}
2585 The value, @var{symbols}, should be an alist whose elements have the
2586 form @code{(@var{name} . @var{color})}. In each element, @var{name} is
2587 the name of a color as it appears in the image file, and @var{color}
2588 specifies the actual color to use for displaying that name.
2592 @subsection GIF Images
2595 For GIF images, specify image type @code{gif}. Because of the patents
2596 in the US covering the LZW algorithm, the continued use of GIF format is
2597 a problem for the whole Internet; to end this problem, it is a good idea
2598 for everyone, even outside the US, to stop using GIFS right away
2599 (@uref{http://www.burnallgifs.org/}). But if you still want to use
2600 them, Emacs can display them.
2603 @item :index @var{index}
2604 You can use @code{:index} to specify one image from a GIF file that
2605 contains more than one image. This property specifies use of image
2606 number @var{index} from the file. An error is signaled if the GIF file
2607 doesn't contain an image with index @var{index}.
2611 This could be used to implement limited support for animated GIFs.
2612 For example, the following function displays a multi-image GIF file
2613 at point-min in the current buffer, switching between sub-images
2616 (defun show-anim (file max)
2617 "Display multi-image GIF file FILE which contains MAX subimages."
2618 (display-anim (current-buffer) file 0 max t))
2620 (defun display-anim (buffer file idx max first-time)
2623 (let ((img (create-image file nil :image idx)))
2626 (goto-char (point-min))
2627 (unless first-time (delete-char 1))
2629 (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
2632 @node Postscript Images
2633 @subsection Postscript Images
2634 @cindex Postscript images
2636 To use Postscript for an image, specify image type @code{postscript}.
2637 This works only if you have Ghostscript installed. You must always use
2638 these three properties:
2641 @item :pt-width @var{width}
2642 The value, @var{width}, specifies the width of the image measured in
2643 points (1/72 inch). @var{width} must be an integer.
2645 @item :pt-height @var{height}
2646 The value, @var{height}, specifies the height of the image in points
2647 (1/72 inch). @var{height} must be an integer.
2649 @item :bounding-box @var{box}
2650 The value, @var{box}, must be a list or vector of four integers, which
2651 specifying the bounding box of the Postscript image, analogous to the
2652 @samp{BoundingBox} comment found in Postscript files.
2655 %%BoundingBox: 22 171 567 738
2659 Displaying Postscript images from Lisp data is not currently
2660 implemented, but it may be implemented by the time you read this.
2661 See the @file{etc/NEWS} file to make sure.
2663 @node Other Image Types
2664 @subsection Other Image Types
2667 For PBM images, specify image type @code{pbm}. Color, gray-scale and
2668 monochromatic images are supported. For mono PBM images, two additional
2669 image properties are supported.
2672 @item :foreground @var{foreground}
2673 The value, @var{foreground}, should be a string specifying the image
2674 foreground color. This color is used for each pixel in the XBM that is
2675 1. The default is the frame's foreground color.
2677 @item :background @var{background}
2678 The value, @var{background}, should be a string specifying the image
2679 background color. This color is used for each pixel in the XBM that is
2680 0. The default is the frame's background color.
2683 For JPEG images, specify image type @code{jpeg}.
2685 For TIFF images, specify image type @code{tiff}.
2687 For PNG images, specify image type @code{png}.
2689 @node Defining Images
2690 @subsection Defining Images
2692 The functions @code{create-image}, @code{defimage} and
2693 @code{find-image} provide convenient ways to create image descriptors.
2695 @defun create-image file &optional type &rest props
2696 @tindex create-image
2697 This function creates and returns an image descriptor which uses the
2700 The optional argument @var{type} is a symbol specifying the image type.
2701 If @var{type} is omitted or @code{nil}, @code{create-image} tries to
2702 determine the image type from the file's first few bytes, or else
2703 from the file's name.
2705 The remaining arguments, @var{props}, specify additional image
2706 properties---for example,
2709 (create-image "foo.xpm" 'xpm :heuristic-mask t)
2712 The function returns @code{nil} if images of this type are not
2713 supported. Otherwise it returns an image descriptor.
2716 @defmac defimage variable doc &rest specs
2718 This macro defines @var{variable} as an image name. The second argument,
2719 @var{doc}, is an optional documentation string. The remaining
2720 arguments, @var{specs}, specify alternative ways to display the image.
2722 Each argument in @var{specs} has the form of a property list, and each
2723 one should specify at least the @code{:type} property and the
2724 @code{:file} property. Here is an example:
2727 (defimage test-image
2728 '((:type xpm :file "~/test1.xpm")
2729 (:type xbm :file "~/test1.xbm")))
2732 @code{defimage} tests each argument, one by one, to see if it is
2733 usable---that is, if the type is supported and the file exists. The
2734 first usable argument is used to make an image descriptor which is
2735 stored in the variable @var{variable}.
2737 If none of the alternatives will work, then @var{variable} is defined
2741 @defun find-image specs
2743 This function provides a convenient way to find an image satisfying one
2744 of a list of image specifications @var{specs}.
2746 Each specification in @var{specs} is a property list with contents
2747 depending on image type. All specifications must at least contain the
2748 properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
2749 or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
2750 the image type, e.g.@: @code{xbm}, @var{file} is the file to load the
2751 image from, and @var{data} is a string containing the actual image data.
2752 The first specification in the list whose @var{type} is supported, and
2753 @var{file} exists, is used to construct the image specification to be
2754 returned. If no specification is satisfied, @code{nil} is returned.
2756 The image is looked for first on @code{load-path} and then in
2757 @code{data-directory}.
2760 @node Showing Images
2761 @subsection Showing Images
2763 You can use an image descriptor by setting up the @code{display}
2764 property yourself, but it is easier to use the functions in this
2767 @defun insert-image image &optional string area
2768 This function inserts @var{image} in the current buffer at point. The
2769 value @var{image} should be an image descriptor; it could be a value
2770 returned by @code{create-image}, or the value of a symbol defined with
2771 @code{defimage}. The argument @var{string} specifies the text to put in
2772 the buffer to hold the image.
2774 The argument @var{area} specifies whether to put the image in a margin.
2775 If it is @code{left-margin}, the image appears in the left margin;
2776 @code{right-margin} specifies the right margin. If @var{area} is
2777 @code{nil} or omitted, the image is displayed at point within the
2780 Internally, this function inserts @var{string} in the buffer, and gives
2781 it a @code{display} property which specifies @var{image}. @xref{Display
2785 @defun put-image image pos &optional string area
2786 This function puts image @var{image} in front of @var{pos} in the
2787 current buffer. The argument @var{pos} should be an integer or a
2788 marker. It specifies the buffer position where the image should appear.
2789 The argument @var{string} specifies the text that should hold the image
2790 as an alternative to the default.
2792 The argument @var{image} must be an image descriptor, perhaps returned
2793 by @code{create-image} or stored by @code{defimage}.
2795 The argument @var{area} specifies whether to put the image in a margin.
2796 If it is @code{left-margin}, the image appears in the left margin;
2797 @code{right-margin} specifies the right margin. If @var{area} is
2798 @code{nil} or omitted, the image is displayed at point within the
2801 Internally, this function creates an overlay, and gives it a
2802 @code{before-string} property containing text that has a @code{display}
2803 property whose value is the image. (Whew!)
2806 @defun remove-images start end &optional buffer
2807 This function removes images in @var{buffer} between positions
2808 @var{start} and @var{end}. If @var{buffer} is omitted or @code{nil},
2809 images are removed from the current buffer.
2811 This removes only images that were put into @var{buffer} the way
2812 @code{put-image} does it, not images that were inserted with
2813 @code{insert-image} or in other ways.
2816 @defun image-size spec &optional pixels frame
2818 This function returns the size of an image as a pair
2819 @w{@code{(@var{width} . @var{height})}}. @var{spec} is an image
2820 specification. @var{pixels} non-nil means return sizes measured in
2821 pixels, otherwise return sizes measured in canonical character units
2822 (fractions of the width/height of the frame's default font).
2823 @var{frame} is the frame on which the image will be displayed.
2824 @var{frame} null or omitted means use the selected frame.
2828 @subsection Image Cache
2830 Emacs stores images in an image cache when it displays them, so it can
2831 display them again more efficiently. It removes an image from the cache
2832 when it hasn't been displayed for a specified period of time.
2834 When an image is looked up in the cache, its specification is compared
2835 with cached image specifications using @code{equal}. This means that
2836 all images with equal specifications share the same image in the cache.
2838 @defvar image-cache-eviction-delay
2839 @tindex image-cache-eviction-delay
2840 This variable specifies the number of seconds an image can remain in the
2841 cache without being displayed. When an image is not displayed for this
2842 length of time, Emacs removes it from the image cache.
2844 If the value is @code{nil}, Emacs does not remove images from the cache
2845 except when you explicitly clear it. This mode can be useful for
2849 @defun clear-image-cache &optional frame
2850 @tindex clear-image-cache
2851 This function clears the image cache. If @var{frame} is non-@code{nil},
2852 only the cache for that frame is cleared. Otherwise all frames' caches
2857 @section Blinking Parentheses
2858 @cindex parenthesis matching
2860 @cindex balancing parentheses
2861 @cindex close parenthesis
2863 This section describes the mechanism by which Emacs shows a matching
2864 open parenthesis when the user inserts a close parenthesis.
2866 @defvar blink-paren-function
2867 The value of this variable should be a function (of no arguments) to
2868 be called whenever a character with close parenthesis syntax is inserted.
2869 The value of @code{blink-paren-function} may be @code{nil}, in which
2870 case nothing is done.
2873 @defopt blink-matching-paren
2874 If this variable is @code{nil}, then @code{blink-matching-open} does
2878 @defopt blink-matching-paren-distance
2879 This variable specifies the maximum distance to scan for a matching
2880 parenthesis before giving up.
2883 @defopt blink-matching-delay
2884 This variable specifies the number of seconds for the cursor to remain
2885 at the matching parenthesis. A fraction of a second often gives
2886 good results, but the default is 1, which works on all systems.
2889 @deffn Command blink-matching-open
2890 This function is the default value of @code{blink-paren-function}. It
2891 assumes that point follows a character with close parenthesis syntax and
2892 moves the cursor momentarily to the matching opening character. If that
2893 character is not already on the screen, it displays the character's
2894 context in the echo area. To avoid long delays, this function does not
2895 search farther than @code{blink-matching-paren-distance} characters.
2897 Here is an example of calling this function explicitly.
2901 (defun interactive-blink-matching-open ()
2902 @c Do not break this line! -- rms.
2903 @c The first line of a doc string
2904 @c must stand alone.
2905 "Indicate momentarily the start of sexp before point."
2909 (let ((blink-matching-paren-distance
2911 (blink-matching-paren t))
2912 (blink-matching-open)))
2918 @section Inverse Video
2919 @cindex Inverse Video
2921 @defopt inverse-video
2922 @cindex highlighting
2923 This variable controls whether Emacs uses inverse video for all text
2924 on the screen. Non-@code{nil} means yes, @code{nil} means no. The
2925 default is @code{nil}.
2928 @defopt mode-line-inverse-video
2929 This variable controls the use of inverse video for mode lines and menu
2930 bars. If it is non-@code{nil}, then these lines are displayed in
2931 inverse video. Otherwise, these lines are displayed normally, just like
2932 other text. The default is @code{t}.
2934 For window frames, this feature actually applies the face named
2935 @code{mode-line}; that face is normally set up as the inverse of the
2936 default face, unless you change it.
2940 @section Usual Display Conventions
2942 The usual display conventions define how to display each character
2943 code. You can override these conventions by setting up a display table
2944 (@pxref{Display Tables}). Here are the usual display conventions:
2948 Character codes 32 through 126 map to glyph codes 32 through 126.
2949 Normally this means they display as themselves.
2952 Character code 9 is a horizontal tab. It displays as whitespace
2953 up to a position determined by @code{tab-width}.
2956 Character code 10 is a newline.
2959 All other codes in the range 0 through 31, and code 127, display in one
2960 of two ways according to the value of @code{ctl-arrow}. If it is
2961 non-@code{nil}, these codes map to sequences of two glyphs, where the
2962 first glyph is the @sc{ascii} code for @samp{^}. (A display table can
2963 specify a glyph to use instead of @samp{^}.) Otherwise, these codes map
2964 just like the codes in the range 128 to 255.
2966 On MS-DOS terminals, Emacs arranges by default for the character code
2967 127 to be mapped to the glyph code 127, which normally displays as an
2968 empty polygon. This glyph is used to display non-@sc{ascii} characters
2969 that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,,
2970 emacs, The GNU Emacs Manual}.
2973 Character codes 128 through 255 map to sequences of four glyphs, where
2974 the first glyph is the @sc{ascii} code for @samp{\}, and the others are
2975 digit characters representing the character code in octal. (A display
2976 table can specify a glyph to use instead of @samp{\}.)
2979 Multibyte character codes above 256 are displayed as themselves, or as a
2980 question mark or empty box if the terminal cannot display that
2984 The usual display conventions apply even when there is a display
2985 table, for any character whose entry in the active display table is
2986 @code{nil}. Thus, when you set up a display table, you need only
2987 specify the characters for which you want special behavior.
2989 These display rules apply to carriage return (character code 13), when
2990 it appears in the buffer. But that character may not appear in the
2991 buffer where you expect it, if it was eliminated as part of end-of-line
2992 conversion (@pxref{Coding System Basics}).
2994 These variables affect the way certain characters are displayed on the
2995 screen. Since they change the number of columns the characters occupy,
2996 they also affect the indentation functions. These variables also affect
2997 how the mode line is displayed; if you want to force redisplay of the
2998 mode line using the new values, call the function
2999 @code{force-mode-line-update} (@pxref{Mode Line Format}).
3002 @cindex control characters in display
3003 This buffer-local variable controls how control characters are
3004 displayed. If it is non-@code{nil}, they are displayed as a caret
3005 followed by the character: @samp{^A}. If it is @code{nil}, they are
3006 displayed as a backslash followed by three octal digits: @samp{\001}.
3009 @c Following may have overfull hbox.
3010 @defvar default-ctl-arrow
3011 The value of this variable is the default value for @code{ctl-arrow} in
3012 buffers that do not override it. @xref{Default Value}.
3015 @defopt indicate-empty-lines
3016 @tindex indicate-empty-lines
3017 When this is non-@code{nil}, Emacs displays a special glyph in
3018 each empty line at the end of the buffer, on terminals that
3019 support it (window systems).
3023 The value of this variable is the spacing between tab stops used for
3024 displaying tab characters in Emacs buffers. The value is in units of
3025 columns, and the default is 8. Note that this feature is completely
3026 independent of the user-settable tab stops used by the command
3027 @code{tab-to-tab-stop}. @xref{Indent Tabs}.
3030 @node Display Tables
3031 @section Display Tables
3033 @cindex display table
3034 You can use the @dfn{display table} feature to control how all possible
3035 character codes display on the screen. This is useful for displaying
3036 European languages that have letters not in the @sc{ascii} character
3039 The display table maps each character code into a sequence of
3040 @dfn{glyphs}, each glyph being a graphic that takes up one character
3041 position on the screen. You can also define how to display each glyph
3042 on your terminal, using the @dfn{glyph table}.
3044 Display tables affect how the mode line is displayed; if you want to
3045 force redisplay of the mode line using a new display table, call
3046 @code{force-mode-line-update} (@pxref{Mode Line Format}).
3049 * Display Table Format:: What a display table consists of.
3050 * Active Display Table:: How Emacs selects a display table to use.
3051 * Glyphs:: How to define a glyph, and what glyphs mean.
3054 @node Display Table Format
3055 @subsection Display Table Format
3057 A display table is actually a char-table (@pxref{Char-Tables}) with
3058 @code{display-table} as its subtype.
3060 @defun make-display-table
3061 This creates and returns a display table. The table initially has
3062 @code{nil} in all elements.
3065 The ordinary elements of the display table are indexed by character
3066 codes; the element at index @var{c} says how to display the character
3067 code @var{c}. The value should be @code{nil} or a vector of glyph
3068 values (@pxref{Glyphs}). If an element is @code{nil}, it says to
3069 display that character according to the usual display conventions
3070 (@pxref{Usual Display}).
3072 If you use the display table to change the display of newline
3073 characters, the whole buffer will be displayed as one long ``line.''
3075 The display table also has six ``extra slots'' which serve special
3076 purposes. Here is a table of their meanings; @code{nil} in any slot
3077 means to use the default for that slot, as stated below.
3081 The glyph for the end of a truncated screen line (the default for this
3082 is @samp{$}). @xref{Glyphs}. Newer Emacs versions, on some platforms,
3083 display arrows to indicate truncation---the display table has no effect
3084 in these situations.
3086 The glyph for the end of a continued line (the default is @samp{\}).
3087 Newer Emacs versions, on some platforms, display curved arrows to
3088 indicate truncation---the display table has no effect in these
3091 The glyph for indicating a character displayed as an octal character
3092 code (the default is @samp{\}).
3094 The glyph for indicating a control character (the default is @samp{^}).
3096 A vector of glyphs for indicating the presence of invisible lines (the
3097 default is @samp{...}). @xref{Selective Display}.
3099 The glyph used to draw the border between side-by-side windows (the
3100 default is @samp{|}). @xref{Splitting Windows}. This takes effect only
3101 when there are no scroll bars; if scroll bars are supported and in use,
3102 a scroll bar separates the two windows.
3105 For example, here is how to construct a display table that mimics the
3106 effect of setting @code{ctl-arrow} to a non-@code{nil} value:
3109 (setq disptab (make-display-table))
3112 (or (= i ?\t) (= i ?\n)
3113 (aset disptab i (vector ?^ (+ i 64))))
3115 (aset disptab 127 (vector ?^ ??)))
3118 @defun display-table-slot display-table slot
3119 This function returns the value of the extra slot @var{slot} of
3120 @var{display-table}. The argument @var{slot} may be a number from 0 to
3121 5 inclusive, or a slot name (symbol). Valid symbols are
3122 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
3123 @code{selective-display}, and @code{vertical-border}.
3126 @defun set-display-table-slot display-table slot value
3127 This function stores @var{value} in the extra slot @var{slot} of
3128 @var{display-table}. The argument @var{slot} may be a number from 0 to
3129 5 inclusive, or a slot name (symbol). Valid symbols are
3130 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
3131 @code{selective-display}, and @code{vertical-border}.
3134 @defun describe-display-table display-table
3135 @tindex describe-display-table
3136 This function displays a description of the display table
3137 @var{display-table} in a help buffer.
3140 @deffn Command describe-current-display-table
3141 @tindex describe-current-display-table
3142 This command displays a description of the current display table in a
3146 @node Active Display Table
3147 @subsection Active Display Table
3148 @cindex active display table
3150 Each window can specify a display table, and so can each buffer. When
3151 a buffer @var{b} is displayed in window @var{w}, display uses the
3152 display table for window @var{w} if it has one; otherwise, the display
3153 table for buffer @var{b} if it has one; otherwise, the standard display
3154 table if any. The display table chosen is called the @dfn{active}
3157 @defun window-display-table window
3158 This function returns @var{window}'s display table, or @code{nil}
3159 if @var{window} does not have an assigned display table.
3162 @defun set-window-display-table window table
3163 This function sets the display table of @var{window} to @var{table}.
3164 The argument @var{table} should be either a display table or
3168 @defvar buffer-display-table
3169 This variable is automatically buffer-local in all buffers; its value in
3170 a particular buffer specifies the display table for that buffer. If it
3171 is @code{nil}, that means the buffer does not have an assigned display
3175 @defvar standard-display-table
3176 This variable's value is the default display table, used whenever a
3177 window has no display table and neither does the buffer displayed in
3178 that window. This variable is @code{nil} by default.
3181 If there is no display table to use for a particular window---that is,
3182 if the window specifies none, its buffer specifies none, and
3183 @code{standard-display-table} is @code{nil}---then Emacs uses the usual
3184 display conventions for all character codes in that window. @xref{Usual
3187 A number of functions for changing the standard display table
3188 are defined in the library @file{disp-table}.
3194 A @dfn{glyph} is a generalization of a character; it stands for an
3195 image that takes up a single character position on the screen. Glyphs
3196 are represented in Lisp as integers, just as characters are.
3199 The meaning of each integer, as a glyph, is defined by the glyph
3200 table, which is the value of the variable @code{glyph-table}.
3203 The value of this variable is the current glyph table. It should be a
3204 vector; the @var{g}th element defines glyph code @var{g}. If the value
3205 is @code{nil} instead of a vector, then all glyphs are simple (see
3209 Here are the possible types of elements in the glyph table:
3213 Send the characters in @var{string} to the terminal to output
3214 this glyph. This alternative is available on character terminals,
3215 but not under a window system.
3218 Define this glyph code as an alias for glyph code @var{integer}. You
3219 can use an alias to specify a face code for the glyph; see below.
3222 This glyph is simple. On an ordinary terminal, the glyph code mod
3223 524288 is the character to output. In a window system, the glyph code
3224 mod 524288 is the character to output, and the glyph code divided by
3225 524288 specifies the face number (@pxref{Face Functions}) to use while
3226 outputting it. (524288 is
3236 If a glyph code is greater than or equal to the length of the glyph
3237 table, that code is automatically simple.
3239 @defun create-glyph string
3240 @tindex create-glyph
3241 This function returns a newly-allocated glyph code which is set up to
3242 display by sending @var{string} to the terminal.
3250 This section describes how to make Emacs ring the bell (or blink the
3251 screen) to attract the user's attention. Be conservative about how
3252 often you do this; frequent bells can become irritating. Also be
3253 careful not to use just beeping when signaling an error is more
3254 appropriate. (@xref{Errors}.)
3256 @defun ding &optional do-not-terminate
3257 @cindex keyboard macro termination
3258 This function beeps, or flashes the screen (see @code{visible-bell} below).
3259 It also terminates any keyboard macro currently executing unless
3260 @var{do-not-terminate} is non-@code{nil}.
3263 @defun beep &optional do-not-terminate
3264 This is a synonym for @code{ding}.
3267 @defopt visible-bell
3268 This variable determines whether Emacs should flash the screen to
3269 represent a bell. Non-@code{nil} means yes, @code{nil} means no. This
3270 is effective on a window system, and on a character-only terminal
3271 provided the terminal's Termcap entry defines the visible bell
3272 capability (@samp{vb}).
3275 @defvar ring-bell-function
3276 If this is non-@code{nil}, it specifies how Emacs should ``ring the
3277 bell.'' Its value should be a function of no arguments. If this is
3278 non-@code{nil}, it takes precedence over the @code{visible-bell}
3282 @node Window Systems
3283 @section Window Systems
3285 Emacs works with several window systems, most notably the X Window
3286 System. Both Emacs and X use the term ``window'', but use it
3287 differently. An Emacs frame is a single window as far as X is
3288 concerned; the individual Emacs windows are not known to X at all.
3290 @defvar window-system
3291 This variable tells Lisp programs what window system Emacs is running
3292 under. The possible values are
3296 @cindex X Window System
3297 Emacs is displaying using X.
3299 Emacs is displaying using MS-DOS.
3301 Emacs is displaying using Windows.
3303 Emacs is displaying using a Macintosh.
3305 Emacs is using a character-based terminal.
3309 @defvar window-setup-hook
3310 This variable is a normal hook which Emacs runs after handling the
3311 initialization files. Emacs runs this hook after it has completed
3312 loading your init file, the default initialization file (if
3313 any), and the terminal-specific Lisp code, and running the hook
3314 @code{term-setup-hook}.
3316 This hook is used for internal purposes: setting up communication with
3317 the window system, and creating the initial window. Users should not