2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/display
6 @node Display, Calendar, Processes, Top
9 This chapter describes a number of features related to the display
10 that Emacs presents to the user.
13 * Refresh Screen:: Clearing the screen and redrawing everything on it.
14 * Truncation:: Folding or wrapping long text lines.
15 * The Echo Area:: Where messages are displayed.
16 * Invisible Text:: Hiding part of the buffer text.
17 * Selective Display:: Hiding part of the buffer text (the old way).
18 * Overlay Arrow:: Display of an arrow to indicate position.
19 * Temporary Displays:: Displays that go away automatically.
20 * Overlays:: Use overlays to highlight parts of the buffer.
21 * Width:: How wide is a character or string.
22 * Faces:: A face defines a graphics appearance: font, color, etc.
23 * Blinking:: How Emacs shows the matching open parenthesis.
24 * Inverse Video:: Specifying how the screen looks.
25 * Usual Display:: The usual conventions for displaying nonprinting chars.
26 * Display Tables:: How to specify other conventions.
27 * Beeping:: Audible signal to the user.
28 * Window Systems:: Which window system is being used.
32 @section Refreshing the Screen
34 The function @code{redraw-frame} redisplays the entire contents of a
35 given frame (@pxref{Frames}).
38 @defun redraw-frame frame
39 This function clears and redisplays frame @var{frame}.
42 Even more powerful is @code{redraw-display}:
44 @deffn Command redraw-display
45 This function clears and redisplays all visible frames.
48 Processing user input takes absolute priority over redisplay. If you
49 call these functions when input is available, they do nothing
50 immediately, but a full redisplay does happen eventually---after all the
51 input has been processed.
53 Normally, suspending and resuming Emacs also refreshes the screen.
54 Some terminal emulators record separate contents for display-oriented
55 programs such as Emacs and for ordinary sequential display. If you are
56 using such a terminal, you might want to inhibit the redisplay on
59 @defvar no-redraw-on-reenter
60 @cindex suspend (cf. @code{no-redraw-on-reenter})
61 @cindex resume (cf. @code{no-redraw-on-reenter})
62 This variable controls whether Emacs redraws the entire screen after it
63 has been suspended and resumed. Non-@code{nil} means there is no need
64 to redraw, @code{nil} means redrawing is needed. The default is @code{nil}.
70 @cindex continuation lines
71 @cindex @samp{$} in display
72 @cindex @samp{\} in display
74 When a line of text extends beyond the right edge of a window, the
75 line can either be continued on the next screen line, or truncated to
76 one screen line. The additional screen lines used to display a long
77 text line are called @dfn{continuation} lines. Normally, a @samp{$} in
78 the rightmost column of the window indicates truncation; a @samp{\} on
79 the rightmost column indicates a line that ``wraps'' onto the next line,
80 which is also called @dfn{continuing} the line. (The display table can
81 specify alternative indicators; see @ref{Display Tables}.)
83 Note that continuation is different from filling; continuation happens
84 on the screen only, not in the buffer contents, and it breaks a line
85 precisely at the right margin, not at a word boundary. @xref{Filling}.
87 @defopt truncate-lines
88 This buffer-local variable controls how Emacs displays lines that extend
89 beyond the right edge of the window. The default is @code{nil}, which
90 specifies continuation. If the value is non-@code{nil}, then these
93 If the variable @code{truncate-partial-width-windows} is non-@code{nil},
94 then truncation is always used for side-by-side windows (within one
95 frame) regardless of the value of @code{truncate-lines}.
98 @defopt default-truncate-lines
99 This variable is the default value for @code{truncate-lines}, for
100 buffers that do not have buffer-local values for it.
103 @defopt truncate-partial-width-windows
104 This variable controls display of lines that extend beyond the right
105 edge of the window, in side-by-side windows (@pxref{Splitting Windows}).
106 If it is non-@code{nil}, these lines are truncated; otherwise,
107 @code{truncate-lines} says what to do with them.
110 When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
111 a window, that forces truncation.
113 You can override the glyphs that indicate continuation or truncation
114 using the display table; see @ref{Display Tables}.
116 If your buffer contains @emph{very} long lines, and you use
117 continuation to display them, just thinking about them can make Emacs
118 redisplay slow. The column computation and indentation functions also
119 become slow. Then you might find it advisable to set
120 @code{cache-long-line-scans} to @code{t}.
122 @defvar cache-long-line-scans
123 If this variable is non-@code{nil}, various indentation and motion
124 functions, and Emacs redisplay, cache the results of scanning the
125 buffer, and consult the cache to avoid rescanning regions of the buffer
126 unless they are modified.
128 Turning on the cache slows down processing of short lines somewhat.
130 This variable is automatically buffer-local in every buffer.
134 @section The Echo Area
135 @cindex error display
138 The @dfn{echo area} is used for displaying messages made with the
139 @code{message} primitive, and for echoing keystrokes. It is not the
140 same as the minibuffer, despite the fact that the minibuffer appears
141 (when active) in the same place on the screen as the echo area. The
142 @cite{GNU Emacs Manual} specifies the rules for resolving conflicts
143 between the echo area and the minibuffer for use of that screen space
144 (@pxref{Minibuffer,, The Minibuffer, emacs, The GNU Emacs Manual}).
145 Error messages appear in the echo area; see @ref{Errors}.
147 You can write output in the echo area by using the Lisp printing
148 functions with @code{t} as the stream (@pxref{Output Functions}), or as
151 @defun message string &rest arguments
152 This function displays a one-line message in the echo area. The
153 argument @var{string} is similar to a C language @code{printf} control
154 string. See @code{format} in @ref{String Conversion}, for the details
155 on the conversion specifications. @code{message} returns the
158 In batch mode, @code{message} prints the message text on the standard
159 error stream, followed by a newline.
162 If @var{string} is @code{nil}, @code{message} clears the echo area. If
163 the minibuffer is active, this brings the minibuffer contents back onto
164 the screen immediately.
168 (message "Minibuffer depth is %d."
170 @print{} Minibuffer depth is 0.
171 @result{} "Minibuffer depth is 0."
175 ---------- Echo Area ----------
176 Minibuffer depth is 0.
177 ---------- Echo Area ----------
182 @defun current-message
183 @tindex current-message
184 This function returns the message currently being displayed in the
185 echo area, or @code{nil} if there is none.
188 @defvar cursor-in-echo-area
189 This variable controls where the cursor appears when a message is
190 displayed in the echo area. If it is non-@code{nil}, then the cursor
191 appears at the end of the message. Otherwise, the cursor appears at
192 point---not in the echo area at all.
194 The value is normally @code{nil}; Lisp programs bind it to @code{t}
195 for brief periods of time.
198 @defvar echo-area-clear-hook
199 @tindex echo-area-clear-hook
200 This normal hook is run whenever the echo area is cleared---either by
201 @code{(message nil)} or for any other reason.
204 Almost all the messages displayed in the echo area are also recorded
205 in the @samp{*Messages*} buffer.
207 @defopt message-log-max
208 This variable specifies how many lines to keep in the @samp{*Messages*}
209 buffer. The value @code{t} means there is no limit on how many lines to
210 keep. The value @code{nil} disables message logging entirely. Here's
211 how to display a message and prevent it from being logged:
214 (let (message-log-max)
219 @defvar echo-keystrokes
220 This variable determines how much time should elapse before command
221 characters echo. Its value must be an integer, which specifies the
222 number of seconds to wait before echoing. If the user types a prefix
223 key (such as @kbd{C-x}) and then delays this many seconds before
224 continuing, the prefix key is echoed in the echo area. (Once echoing
225 begins in a key sequence, all subsequent characters in the same key
226 sequence are echoed immediately.)
228 If the value is zero, then command input is not echoed.
232 @section Invisible Text
234 @cindex invisible text
235 You can make characters @dfn{invisible}, so that they do not appear on
236 the screen, with the @code{invisible} property. This can be either a
237 text property (@pxref{Text Properties}) or a property of an overlay
240 In the simplest case, any non-@code{nil} @code{invisible} property makes
241 a character invisible. This is the default case---if you don't alter
242 the default value of @code{buffer-invisibility-spec}, this is how the
243 @code{invisible} property works.
245 More generally, you can use the variable @code{buffer-invisibility-spec}
246 to control which values of the @code{invisible} property make text
247 invisible. This permits you to classify the text into different subsets
248 in advance, by giving them different @code{invisible} values, and
249 subsequently make various subsets visible or invisible by changing the
250 value of @code{buffer-invisibility-spec}.
252 Controlling visibility with @code{buffer-invisibility-spec} is
253 especially useful in a program to display the list of entries in a data
254 base. It permits the implementation of convenient filtering commands to
255 view just a part of the entries in the data base. Setting this variable
256 is very fast, much faster than scanning all the text in the buffer
257 looking for properties to change.
259 @defvar buffer-invisibility-spec
260 This variable specifies which kinds of @code{invisible} properties
261 actually make a character invisible.
265 A character is invisible if its @code{invisible} property is
266 non-@code{nil}. This is the default.
269 Each element of the list specifies a criterion for invisibility; if a
270 character's @code{invisible} property fits any one of these criteria,
271 the character is invisible. The list can have two kinds of elements:
275 A character is invisible if its @code{invisible} property value
276 is @var{atom} or if it is a list with @var{atom} as a member.
278 @item (@var{atom} . t)
279 A character is invisible if its @code{invisible} property value
280 is @var{atom} or if it is a list with @var{atom} as a member.
281 Moreover, if this character is at the end of a line and is followed
282 by a visible newline, it displays an ellipsis.
287 Two functions are specifically provided for adding elements to
288 @code{buffer-invisibility-spec} and removing elements from it.
290 @defun add-to-invisibility-spec element
291 @tindex add-to-invisibility-spec
292 Add the element @var{element} to @code{buffer-invisibility-spec}
293 (if it is not already present in that list).
296 @defun remove-from-invisibility-spec element
297 @tindex remove-from-invisibility-spec
298 Remove the element @var{element} from @code{buffer-invisibility-spec}.
301 One convention about the use of @code{buffer-invisibility-spec} is
302 that a major mode should use the mode's own name as an element of
303 @code{buffer-invisibility-spec} and as the value of the @code{invisible}
307 ;; @r{If you want to display an ellipsis:}
308 (add-to-invisibility-spec '(my-symbol . t))
309 ;; @r{If you don't want ellipsis:}
310 (add-to-invisibility-spec 'my-symbol)
312 (overlay-put (make-overlay beginning end)
313 'invisible 'my-symbol)
315 ;; @r{When done with the overlays:}
316 (remove-from-invisibility-spec '(my-symbol . t))
317 ;; @r{Or respectively:}
318 (remove-from-invisibility-spec 'my-symbol)
321 @vindex line-move-ignore-invisible
322 Ordinarily, commands that operate on text or move point do not care
323 whether the text is invisible. The user-level line motion commands
324 explicitly ignore invisible newlines if
325 @code{line-move-ignore-invisible} is non-@code{nil}, but only because
326 they are explicitly programmed to do so.
328 Incremental search can make invisible overlays visible temporarily
329 and/or permanently when a match includes invisible text. To enable
330 this, the overlay should have a non-@code{nil}
331 @code{isearch-open-invisible} property. The property value should be a
332 function to be called with the overlay as an argument. This function
333 should make the overlay visible permanently; it is used when the match
334 overlaps the overlay on exit from the search.
336 During the search, such overlays are made temporarily visible by
337 temporarily modifying their invisible and intangible properties. If you
338 want this to be done differently for a certain overlay, give it a
339 @code{isearch-open-invisible-temporary} property which is a function.
340 The function is called with two arguments: the first is the overlay, and
341 the second is @code{t} to make the overlay visible, or @code{nil} to
342 make it invisible again.
344 @node Selective Display
345 @section Selective Display
346 @cindex selective display
348 @dfn{Selective display} refers to a pair of related features for
349 hiding certain lines on the screen.
351 The first variant, explicit selective display, is designed for use in
352 a Lisp program: it controls which lines are hidden by altering the text.
353 The invisible text feature (@pxref{Invisible Text}) has partially
354 replaced this feature.
356 In the second variant, the choice of lines to hide is made
357 automatically based on indentation. This variant is designed to be a
360 The way you control explicit selective display is by replacing a
361 newline (control-j) with a carriage return (control-m). The text that
362 was formerly a line following that newline is now invisible. Strictly
363 speaking, it is temporarily no longer a line at all, since only newlines
364 can separate lines; it is now part of the previous line.
366 Selective display does not directly affect editing commands. For
367 example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly into
368 invisible text. However, the replacement of newline characters with
369 carriage return characters affects some editing commands. For example,
370 @code{next-line} skips invisible lines, since it searches only for
371 newlines. Modes that use selective display can also define commands
372 that take account of the newlines, or that make parts of the text
373 visible or invisible.
375 When you write a selectively displayed buffer into a file, all the
376 control-m's are output as newlines. This means that when you next read
377 in the file, it looks OK, with nothing invisible. The selective display
378 effect is seen only within Emacs.
380 @defvar selective-display
381 This buffer-local variable enables selective display. This means that
382 lines, or portions of lines, may be made invisible.
386 If the value of @code{selective-display} is @code{t}, then any portion
387 of a line that follows a control-m is not displayed. This is explicit
391 If the value of @code{selective-display} is a positive integer, then
392 lines that start with more than that many columns of indentation are not
396 When some portion of a buffer is invisible, the vertical movement
397 commands operate as if that portion did not exist, allowing a single
398 @code{next-line} command to skip any number of invisible lines.
399 However, character movement commands (such as @code{forward-char}) do
400 not skip the invisible portion, and it is possible (if tricky) to insert
401 or delete text in an invisible portion.
403 In the examples below, we show the @emph{display appearance} of the
404 buffer @code{foo}, which changes with the value of
405 @code{selective-display}. The @emph{contents} of the buffer do not
410 (setq selective-display nil)
413 ---------- Buffer: foo ----------
420 ---------- Buffer: foo ----------
424 (setq selective-display 2)
427 ---------- Buffer: foo ----------
432 ---------- Buffer: foo ----------
437 @defvar selective-display-ellipses
438 If this buffer-local variable is non-@code{nil}, then Emacs displays
439 @samp{@dots{}} at the end of a line that is followed by invisible text.
440 This example is a continuation of the previous one.
444 (setq selective-display-ellipses t)
447 ---------- Buffer: foo ----------
452 ---------- Buffer: foo ----------
456 You can use a display table to substitute other text for the ellipsis
457 (@samp{@dots{}}). @xref{Display Tables}.
461 @section The Overlay Arrow
462 @cindex overlay arrow
464 The @dfn{overlay arrow} is useful for directing the user's attention
465 to a particular line in a buffer. For example, in the modes used for
466 interface to debuggers, the overlay arrow indicates the line of code
467 about to be executed.
469 @defvar overlay-arrow-string
470 This variable holds the string to display to call attention to a
471 particular line, or @code{nil} if the arrow feature is not in use.
474 @defvar overlay-arrow-position
475 This variable holds a marker that indicates where to display the overlay
476 arrow. It should point at the beginning of a line. The arrow text
477 appears at the beginning of that line, overlaying any text that would
478 otherwise appear. Since the arrow is usually short, and the line
479 usually begins with indentation, normally nothing significant is
482 The overlay string is displayed only in the buffer that this marker
483 points into. Thus, only one buffer can have an overlay arrow at any
485 @c !!! overlay-arrow-position: but the overlay string may remain in the display
486 @c of some other buffer until an update is required. This should be fixed
490 You can do a similar job by creating an overlay with a
491 @code{before-string} property. @xref{Overlay Properties}.
493 @node Temporary Displays
494 @section Temporary Displays
496 Temporary displays are used by Lisp programs to put output into a
497 buffer and then present it to the user for perusal rather than for
498 editing. Many help commands use this feature.
500 @defspec with-output-to-temp-buffer buffer-name forms@dots{}
501 This function executes @var{forms} while arranging to insert any
502 output they print into the buffer named @var{buffer-name}. The buffer
503 is then shown in some window for viewing, displayed but not selected.
505 The string @var{buffer-name} specifies the temporary buffer, which
506 need not already exist. The argument must be a string, not a buffer.
507 The buffer is erased initially (with no questions asked), and it is
508 marked as unmodified after @code{with-output-to-temp-buffer} exits.
510 @code{with-output-to-temp-buffer} binds @code{standard-output} to the
511 temporary buffer, then it evaluates the forms in @var{forms}. Output
512 using the Lisp output functions within @var{forms} goes by default to
513 that buffer (but screen display and messages in the echo area, although
514 they are ``output'' in the general sense of the word, are not affected).
515 @xref{Output Functions}.
517 The value of the last form in @var{forms} is returned.
521 ---------- Buffer: foo ----------
522 This is the contents of foo.
523 ---------- Buffer: foo ----------
527 (with-output-to-temp-buffer "foo"
529 (print standard-output))
530 @result{} #<buffer foo>
532 ---------- Buffer: foo ----------
537 ---------- Buffer: foo ----------
542 @defvar temp-buffer-show-function
543 If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
544 calls it as a function to do the job of displaying a help buffer. The
545 function gets one argument, which is the buffer it should display.
547 It is a good idea for this function to run @code{temp-buffer-show-hook}
548 just as @code{with-output-to-temp-buffer} normally would, inside of
549 @code{save-window-excursion} and with the chosen window and buffer
553 @defvar temp-buffer-show-hook
554 This normal hook is run by @code{with-output-to-temp-buffer} after
555 displaying the help buffer. When the hook runs, the help buffer is
556 current, and the window it was displayed in is selected.
559 @defun momentary-string-display string position &optional char message
560 This function momentarily displays @var{string} in the current buffer at
561 @var{position}. It has no effect on the undo list or on the buffer's
564 The momentary display remains until the next input event. If the next
565 input event is @var{char}, @code{momentary-string-display} ignores it
566 and returns. Otherwise, that event remains buffered for subsequent use
567 as input. Thus, typing @var{char} will simply remove the string from
568 the display, while typing (say) @kbd{C-f} will remove the string from
569 the display and later (presumably) move point forward. The argument
570 @var{char} is a space by default.
572 The return value of @code{momentary-string-display} is not meaningful.
574 If the string @var{string} does not contain control characters, you can
575 do the same job in a more general way by creating (and then subsequently
576 deleting) an overlay with a @code{before-string} property.
577 @xref{Overlay Properties}.
579 If @var{message} is non-@code{nil}, it is displayed in the echo area
580 while @var{string} is displayed in the buffer. If it is @code{nil}, a
581 default message says to type @var{char} to continue.
583 In this example, point is initially located at the beginning of the
588 ---------- Buffer: foo ----------
589 This is the contents of foo.
591 ---------- Buffer: foo ----------
595 (momentary-string-display
596 "**** Important Message! ****"
598 "Type RET when done reading")
603 ---------- Buffer: foo ----------
604 This is the contents of foo.
605 **** Important Message! ****Second line.
606 ---------- Buffer: foo ----------
608 ---------- Echo Area ----------
609 Type RET when done reading
610 ---------- Echo Area ----------
619 You can use @dfn{overlays} to alter the appearance of a buffer's text on
620 the screen, for the sake of presentation features. An overlay is an
621 object that belongs to a particular buffer, and has a specified
622 beginning and end. It also has properties that you can examine and set;
623 these affect the display of the text within the overlay.
626 * Overlay Properties:: How to read and set properties.
627 What properties do to the screen display.
628 * Managing Overlays:: Creating, moving, finding overlays.
631 @node Overlay Properties
632 @subsection Overlay Properties
634 Overlay properties are like text properties in that the properties that
635 alter how a character is displayed can come from either source. But in
636 most respects they are different. Text properties are considered a part
637 of the text; overlays are specifically considered not to be part of the
638 text. Thus, copying text between various buffers and strings preserves
639 text properties, but does not try to preserve overlays. Changing a
640 buffer's text properties marks the buffer as modified, while moving an
641 overlay or changing its properties does not. Unlike text property
642 changes, overlay changes are not recorded in the buffer's undo list.
643 @xref{Text Properties}, for comparison.
647 @kindex priority @r{(overlay property)}
648 This property's value (which should be a nonnegative number) determines
649 the priority of the overlay. The priority matters when two or more
650 overlays cover the same character and both specify a face for display;
651 the one whose @code{priority} value is larger takes priority over the
652 other, and its face attributes override the face attributes of the lower
655 Currently, all overlays take priority over text properties. Please
656 avoid using negative priority values, as we have not yet decided just
657 what they should mean.
660 @kindex window @r{(overlay property)}
661 If the @code{window} property is non-@code{nil}, then the overlay
662 applies only on that window.
665 @kindex category @r{(overlay property)}
666 If an overlay has a @code{category} property, we call it the
667 @dfn{category} of the overlay. It should be a symbol. The properties
668 of the symbol serve as defaults for the properties of the overlay.
671 @kindex face @r{(overlay property)}
672 This property controls the way text is displayed---for example, which
673 font and which colors. Its value is a face name or a list of face
674 names. @xref{Faces}, for more information.
676 If the property value is a list, elements may also have the form
677 @code{(foreground-color . @var{color-name})} or @code{(background-color
678 . @var{color-name})}. These elements specify just the foreground color
679 or just the background color; therefore, there is no need to create a
680 face for each color that you want to use.
683 @kindex mouse-face @r{(overlay property)}
684 This property is used instead of @code{face} when the mouse is within
685 the range of the overlay.
687 @item modification-hooks
688 @kindex modification-hooks @r{(overlay property)}
689 This property's value is a list of functions to be called if any
690 character within the overlay is changed or if text is inserted strictly
693 The hook functions are called both before and after each change.
694 If the functions save the information they receive, and compare notes
695 between calls, they can determine exactly what change has been made
698 When called before a change, each function receives four arguments: the
699 overlay, @code{nil}, and the beginning and end of the text range to be
702 When called after a change, each function receives five arguments: the
703 overlay, @code{t}, the beginning and end of the text range just
704 modified, and the length of the pre-change text replaced by that range.
705 (For an insertion, the pre-change length is zero; for a deletion, that
706 length is the number of characters deleted, and the post-change
707 beginning and end are equal.)
709 @item insert-in-front-hooks
710 @kindex insert-in-front-hooks @r{(overlay property)}
711 This property's value is a list of functions to be called before and
712 after inserting text right at the beginning of the overlay. The calling
713 conventions are the same as for the @code{modification-hooks} functions.
715 @item insert-behind-hooks
716 @kindex insert-behind-hooks @r{(overlay property)}
717 This property's value is a list of functions to be called before and
718 after inserting text right at the end of the overlay. The calling
719 conventions are the same as for the @code{modification-hooks} functions.
722 @kindex invisible @r{(overlay property)}
723 The @code{invisible} property can make the text in the overlay
724 invisible, which means that it does not appear on the screen.
725 @xref{Invisible Text}, for details.
728 @kindex intangible @r{(overlay property)}
729 The @code{intangible} property on an overlay works just like the
730 @code{intangible} text property. @xref{Special Properties}, for details.
732 @item isearch-open-invisible
733 This property tells incremental search how to make an invisible overlay
734 visible, permanently, if the final match overlaps it. @xref{Invisible
737 @item isearch-open-invisible-temporary
738 This property tells incremental search how to make an invisible overlay
739 visible, temporarily, during the search. @xref{Invisible Text}.
742 @kindex before-string @r{(overlay property)}
743 This property's value is a string to add to the display at the beginning
744 of the overlay. The string does not appear in the buffer in any
745 sense---only on the screen. The string should contain only characters
746 that display as a single column---control characters, including tabs or
747 newlines, will give strange results.
750 @kindex after-string @r{(overlay property)}
751 This property's value is a string to add to the display at the end of
752 the overlay. The string does not appear in the buffer in any
753 sense---only on the screen. The string should contain only characters
754 that display as a single column---control characters, including tabs or
755 newlines, will give strange results.
758 @kindex evaporate @r{(overlay property)}
759 If this property is non-@code{nil}, the overlay is deleted automatically
760 if it ever becomes empty (i.e., if it spans no characters).
763 @cindex keymap of character (and overlays)
764 @kindex local-map @r{(overlay property)}
765 If this property is non-@code{nil}, it specifies a keymap for a portion
766 of the text. The property's value replaces the buffer's local map, when
767 the character after point is within the overlay. @xref{Active Keymaps}.
770 These are the functions for reading and writing the properties of an
773 @defun overlay-get overlay prop
774 This function returns the value of property @var{prop} recorded in
775 @var{overlay}, if any. If @var{overlay} does not record any value for
776 that property, but it does have a @code{category} property which is a
777 symbol, that symbol's @var{prop} property is used. Otherwise, the value
781 @defun overlay-put overlay prop value
782 This function sets the value of property @var{prop} recorded in
783 @var{overlay} to @var{value}. It returns @var{value}.
786 See also the function @code{get-char-property} which checks both
787 overlay properties and text properties for a given character.
788 @xref{Examining Properties}.
790 @node Managing Overlays
791 @subsection Managing Overlays
793 This section describes the functions to create, delete and move
794 overlays, and to examine their contents.
796 @defun make-overlay start end &optional buffer front-advance rear-advance
797 This function creates and returns an overlay that belongs to
798 @var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
799 and @var{end} must specify buffer positions; they may be integers or
800 markers. If @var{buffer} is omitted, the overlay is created in the
803 The arguments @var{front-advance} and @var{rear-advance} specify the
804 insertion type for the start of the overlay and for the end of the
805 overlay. @xref{Marker Insertion Types}.
808 @defun overlay-start overlay
809 This function returns the position at which @var{overlay} starts,
813 @defun overlay-end overlay
814 This function returns the position at which @var{overlay} ends,
818 @defun overlay-buffer overlay
819 This function returns the buffer that @var{overlay} belongs to.
822 @defun delete-overlay overlay
823 This function deletes @var{overlay}. The overlay continues to exist as
824 a Lisp object, but ceases to be attached to the buffer it belonged to,
825 and ceases to have any effect on display.
827 A deleted overlay is not permanently useless. You can give it
828 a new buffer position by calling @code{move-overlay}.
831 @defun move-overlay overlay start end &optional buffer
832 This function moves @var{overlay} to @var{buffer}, and places its bounds
833 at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
834 must specify buffer positions; they may be integers or markers. If
835 @var{buffer} is omitted, the overlay stays in the same buffer.
837 The return value is @var{overlay}.
839 This is the only valid way to change the endpoints of an overlay. Do
840 not try modifying the markers in the overlay by hand, as that fails to
841 update other vital data structures and can cause some overlays to be
845 @defun overlays-at pos
846 This function returns a list of all the overlays that contain position
847 @var{pos} in the current buffer. The list is in no particular order.
848 An overlay contains position @var{pos} if it begins at or before
849 @var{pos}, and ends after @var{pos}.
852 @defun overlays-in beg end
854 This function returns a list of the overlays that overlap the region
855 @var{beg} through @var{end}. ``Overlap'' means that at least one
856 character is contained within the overlay and also contained within the
857 specified region; however, empty overlays are included in the result if
858 they are located at @var{beg} or between @var{beg} and @var{end}.
861 @defun next-overlay-change pos
862 This function returns the buffer position of the next beginning or end
863 of an overlay, after @var{pos}.
866 @defun previous-overlay-change pos
867 This function returns the buffer position of the previous beginning or
868 end of an overlay, before @var{pos}.
874 Since not all characters have the same width, these functions let you
875 check the width of a character. @xref{Primitive Indent}, and
876 @ref{Screen Lines}, for related functions.
878 @defun char-width char
880 This function returns the width in columns of the character @var{char},
881 if it were displayed in the current buffer and the selected window.
884 @defun string-width string
886 This function returns the width in columns of the string @var{string},
887 if it were displayed in the current buffer and the selected window.
890 @defun truncate-string-to-width string width &optional start-column padding
891 @tindex truncate-string-to-width
892 This function returns the part of @var{string} that fits within
893 @var{width} columns, as a new string.
895 If @var{string} does not reach @var{width}, then the result ends where
896 @var{string} ends. If one multi-column character in @var{string}
897 extends across the column @var{width}, that character is not included in
898 the result. Thus, the result can fall short of @var{width} but cannot
901 The optional argument @var{start-column} specifies the starting column.
902 If this is non-@code{nil}, then the first @var{start-column} columns of
903 the string are omitted from the value. If one multi-column character in
904 @var{string} extends across the column @var{start-column}, that
905 character is not included.
907 The optional argument @var{padding}, if non-@code{nil}, is a padding
908 character added at the beginning and end of the result string, to extend
909 it to exactly @var{width} columns. The padding character is used at the
910 end of the result if it falls short of @var{width}. It is also used at
911 the beginning of the result if one multi-column character in
912 @var{string} extends across the column @var{start-column}.
915 (truncate-string-to-width "\tab\t" 12 4)
917 (truncate-string-to-width "\tab\t" 12 4 ?\ )
926 A @dfn{face} is a named collection of graphical attributes: font,
927 foreground color, background color, and optional underlining. Faces
928 control the display of text on the screen.
931 Each face has its own @dfn{face number}, which distinguishes faces at
932 low levels within Emacs. However, for most purposes, you can refer to
933 faces in Lisp programs by their names.
936 This function returns @code{t} if @var{object} is a face name symbol (or
937 if it is a vector of the kind used internally to record face data). It
938 returns @code{nil} otherwise.
941 Each face name is meaningful for all frames, and by default it has the
942 same meaning in all frames. But you can arrange to give a particular
943 face name a special meaning in one frame if you wish.
946 * Standard Faces:: The faces Emacs normally comes with.
947 * Defining Faces:: How to define a face with @code{defface}.
948 * Merging Faces:: How Emacs decides which face to use for a character.
949 * Face Functions:: How to define and examine faces.
953 @subsection Standard Faces
955 This table lists all the standard faces and their uses.
959 @kindex default @r{(face name)}
960 This face is used for ordinary text.
963 @kindex modeline @r{(face name)}
964 This face is used for mode lines and menu bars.
967 @kindex region @r{(face name)}
968 This face is used for highlighting the region in Transient Mark mode.
970 @item secondary-selection
971 @kindex secondary-selection @r{(face name)}
972 This face is used to show any secondary selection you have made.
975 @kindex highlight @r{(face name)}
976 This face is meant to be used for highlighting for various purposes.
979 @kindex underline @r{(face name)}
980 This face underlines text.
983 @kindex bold @r{(face name)}
984 This face uses a bold font, if possible. It uses the bold variant of
985 the frame's font, if it has one. It's up to you to choose a default
986 font that has a bold variant, if you want to use one.
989 @kindex italic @r{(face name)}
990 This face uses the italic variant of the frame's font, if it has one.
993 @kindex bold-italic @r{(face name)}
994 This face uses the bold italic variant of the frame's font, if it has
999 @subsection Defining Faces
1001 The way to define a new face is with @code{defface}. This creates a
1002 kind of customization item (@pxref{Customization}) which the user can
1003 customize using the Customization buffer (@pxref{Easy Customization,,,
1004 emacs, The GNU Emacs Manual}).
1006 @defmac defface face spec doc [keyword value]...
1008 Declare @var{face} as a customizable face that defaults according to
1009 @var{spec}. Do not quote the symbol @var{face}. The argument @var{doc}
1010 specifies the face documentation.
1012 When @code{defface} executes, it defines the face according to
1013 @var{spec}, then uses any customizations that were read from the
1014 @file{.emacs} file to override that specification.
1016 The purpose of @var{spec} is to specify how the face should appear on
1017 different kinds of terminals. It should be an alist whose elements have
1018 the form @code{(@var{display} @var{atts})}. The element's @sc{car},
1019 @var{display}, specifies a class of terminals. The @sc{cdr},
1020 @var{atts}, is a list of face attributes and their values; it specifies
1021 what the face should look like on that kind of terminal. The possible
1022 attributes are defined in the value of @code{custom-face-attributes}.
1024 The @var{display} part of an element of @var{spec} determines which
1025 frames the element applies to. If more than one element of @var{spec}
1026 matches a given frame, the first matching element is the only one used
1027 for that frame. There are two possibilities for @var{display}:
1031 This element of @var{spec} matches all frames. Therefore, any
1032 subsequent elements of @var{spec} are never used. Normally
1033 @code{t} is used in the last (or only) element of @var{spec}.
1036 If @var{display} is a list, each element should have the form
1037 @code{(@var{characteristic} @var{value}@dots{})}. Here
1038 @var{characteristic} specifies a way of classifying frames, and the
1039 @var{value}s are possible classifications which @var{display} should
1040 apply to. Here are the possible values of @var{characteristic}:
1044 The kind of window system the frame uses---either @code{x}, @code{pc}
1045 (for the MS-DOS console), @code{w32} (for MS Windows 9X/NT), or
1049 What kinds of colors the frame supports---either @code{color},
1050 @code{grayscale}, or @code{mono}.
1053 The kind of background---either @code{light} or @code{dark}.
1056 If an element of @var{display} specifies more than one @var{value} for a
1057 given @var{characteristic}, any of those values is acceptable. If
1058 @var{display} has more than one element, each element should specify a
1059 different @var{characteristic}; then @emph{each} characteristic of the
1060 frame must match one of the @var{value}s specified for it in
1065 Here's how the standard face @code{region} could be defined
1066 with @code{defface}:
1070 ((((class color) (background dark))
1071 (:background "blue"))
1072 (t (:background "gray")))
1073 "Used for displaying the region.")
1076 Internally, @code{defface} uses the symbol property
1077 @code{face-defface-spec} to record the face attributes specified in
1078 @code{defface}, @code{saved-face} for the attributes saved by the user
1079 with the customization buffer, and @code{face-documentation} for the
1080 documentation string.
1082 @tindex frame-background-mode
1083 @defopt frame-background-mode
1084 This option, if non-@code{nil}, specifies the background type to use for
1085 interpreting face definitions. If it is @code{dark}, then Emacs treats
1086 all frames as if they had a dark background, regardless of their actual
1087 background colors. If it is @code{light}, then Emacs treats all frames
1088 as if they had a light background.
1092 @subsection Merging Faces for Display
1094 Here are all the ways to specify which face to use for display of text:
1098 With defaults. Each frame has a @dfn{default face}, which is used for
1099 all text that doesn't somehow specify another face. (We may change this
1100 in a forthcoming Emacs version to serve as a default for all text.)
1103 With text properties. A character may have a @code{face} property; if so,
1104 it is displayed with that face. @xref{Special Properties}.
1106 If the character has a @code{mouse-face} property, that is used instead
1107 of the @code{face} property when the mouse is ``near enough'' to the
1111 With overlays. An overlay may have @code{face} and @code{mouse-face}
1112 properties too; they apply to all the text covered by the overlay.
1115 With a region that is active. In Transient Mark mode, the region is
1116 highlighted with a particular face (see @code{region-face}, below).
1119 With special glyphs. Each glyph can specify a particular face
1120 number. @xref{Glyphs}.
1123 If these various sources together specify more than one face for a
1124 particular character, Emacs merges the attributes of the various faces
1125 specified. The attributes of the faces of special glyphs come first;
1126 then comes the face for region highlighting, if appropriate;
1127 then come attributes of faces from overlays, followed by those from text
1128 properties, and last the default face.
1130 When multiple overlays cover one character, an overlay with higher
1131 priority overrides those with lower priority. @xref{Overlays}.
1133 If an attribute such as the font or a color is not specified in any of
1134 the above ways, the frame's own font or color is used.
1136 @node Face Functions
1137 @subsection Functions for Working with Faces
1139 The attributes a face can specify include the font, the foreground
1140 color, the background color, and underlining. The face can also leave
1141 these unspecified by giving the value @code{nil} for them.
1143 Here are the primitives for creating and changing faces.
1145 @defun make-face name
1146 This function defines a new face named @var{name}, initially with all
1147 attributes @code{nil}. It does nothing if there is already a face named
1152 This function returns a list of all defined face names.
1155 @defun copy-face old-face new-name &optional frame new-frame
1156 This function defines the face @var{new-name} as a copy of the existing
1157 face named @var{old-face}. It creates the face @var{new-name} if that
1158 doesn't already exist.
1160 If the optional argument @var{frame} is given, this function applies
1161 only to that frame. Otherwise it applies to each frame individually,
1162 copying attributes from @var{old-face} in each frame to @var{new-face}
1165 If the optional argument @var{new-frame} is given, then @code{copy-face}
1166 copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
1170 You can modify the attributes of an existing face with the following
1171 functions. If you specify @var{frame}, they affect just that frame;
1172 otherwise, they affect all frames as well as the defaults that apply to
1175 @defun set-face-foreground face color &optional frame
1176 @defunx set-face-background face color &optional frame
1177 These functions set the foreground (or background, respectively) color
1178 of face @var{face} to @var{color}. The argument @var{color} should be a
1179 string, the name of a color.
1181 Certain shades of gray are implemented by stipple patterns on
1182 black-and-white screens.
1185 @defun set-face-stipple face pattern &optional frame
1186 This function sets the background stipple pattern of face @var{face} to
1187 @var{pattern}. The argument @var{pattern} should be the name of a
1188 stipple pattern defined by the X server, or @code{nil} meaning don't use
1191 Normally there is no need to pay attention to stipple patterns, because
1192 they are used automatically to handle certain shades of gray.
1195 @defun set-face-font face font &optional frame
1196 This function sets the font of face @var{face}. The argument @var{font}
1197 should be a string, either a valid font name for your system or the name
1198 of an Emacs fontset (@pxref{Fontsets}). Note that if you set the font
1199 explicitly, the bold and italic attributes cease to have any effect,
1200 because the precise font that you specified is always used.
1203 @defun set-face-bold-p face bold-p &optional frame
1204 @tindex set-face-bold-p
1205 This function sets the bold attribute of face @var{face}.
1206 Non-@code{nil} means bold; @code{nil} means non-bold.
1209 @defun set-face-italic-p face italic-p &optional frame
1210 @tindex set-face-italic-p
1211 This function sets the italic attribute of face @var{face}.
1212 Non-@code{nil} means italic; @code{nil} means non-italic.
1215 @defun set-face-underline-p face underline-p &optional frame
1216 This function sets the underline attribute of face @var{face}.
1217 Non-@code{nil} means do underline; @code{nil} means don't.
1220 @defun invert-face face &optional frame
1221 Swap the foreground and background colors of face @var{face}. If the
1222 face doesn't specify both foreground and background, then its foreground
1223 and background are set to the default background and foreground,
1227 These functions examine the attributes of a face. If you don't
1228 specify @var{frame}, they refer to the default data for new frames.
1230 @defun face-foreground face &optional frame
1231 @defunx face-background face &optional frame
1232 These functions return the foreground color (or background color,
1233 respectively) of face @var{face}, as a string.
1236 @defun face-stipple face &optional frame
1237 This function returns the name of the background stipple pattern of face
1238 @var{face}, or @code{nil} if it doesn't have one.
1241 @defun face-font face &optional frame
1242 This function returns the name of the font of face @var{face}.
1245 @defun face-bold-p face &optional frame
1247 This function returns the bold attribute of face @var{face}.
1250 @defun face-italic-p face &optional frame
1251 @tindex face-italic-p
1252 This function returns the italic attribute of face @var{face}.
1255 @defun face-underline-p face &optional frame
1256 This function returns the underline attribute of face @var{face}.
1260 This function returns the face number of face @var{face}.
1263 @defun face-documentation face
1264 @tindex face-documentation
1265 This function returns the documentation string of face @var{face}, or
1266 @code{nil} if none was specified for it.
1269 @defun face-equal face1 face2 &optional frame
1270 This returns @code{t} if the faces @var{face1} and @var{face2} have the
1271 same attributes for display.
1274 @defun face-differs-from-default-p face &optional frame
1275 This returns @code{t} if the face @var{face} displays differently from
1276 the default face. A face is considered to be ``the same'' as the normal
1277 face if each attribute is either the same as that of the default face or
1278 @code{nil} (meaning to inherit from the default).
1282 This variable's value specifies the face number to use to display characters
1283 in the region when it is active (in Transient Mark mode only). The face
1284 thus specified takes precedence over all faces that come from text
1285 properties and overlays, for characters in the region. @xref{The Mark},
1286 for more information about Transient Mark mode.
1288 Normally, the value is the face number of the face named @code{region}.
1291 @tindex frame-update-face-colors
1292 @defun frame-update-face-colors frame
1293 This function updates the way faces display on @var{frame}, for a change
1294 in @var{frame}'s foreground or background color.
1298 @section Blinking Parentheses
1299 @cindex parenthesis matching
1301 @cindex balancing parentheses
1302 @cindex close parenthesis
1304 This section describes the mechanism by which Emacs shows a matching
1305 open parenthesis when the user inserts a close parenthesis.
1307 @defvar blink-paren-function
1308 The value of this variable should be a function (of no arguments) to
1309 be called whenever a character with close parenthesis syntax is inserted.
1310 The value of @code{blink-paren-function} may be @code{nil}, in which
1311 case nothing is done.
1314 @defopt blink-matching-paren
1315 If this variable is @code{nil}, then @code{blink-matching-open} does
1319 @defopt blink-matching-paren-distance
1320 This variable specifies the maximum distance to scan for a matching
1321 parenthesis before giving up.
1324 @defopt blink-matching-delay
1325 This variable specifies the number of seconds for the cursor to remain
1326 at the matching parenthesis. A fraction of a second often gives
1327 good results, but the default is 1, which works on all systems.
1330 @deffn Command blink-matching-open
1331 This function is the default value of @code{blink-paren-function}. It
1332 assumes that point follows a character with close parenthesis syntax and
1333 moves the cursor momentarily to the matching opening character. If that
1334 character is not already on the screen, it displays the character's
1335 context in the echo area. To avoid long delays, this function does not
1336 search farther than @code{blink-matching-paren-distance} characters.
1338 Here is an example of calling this function explicitly.
1342 (defun interactive-blink-matching-open ()
1343 @c Do not break this line! -- rms.
1344 @c The first line of a doc string
1345 @c must stand alone.
1346 "Indicate momentarily the start of sexp before point."
1350 (let ((blink-matching-paren-distance
1352 (blink-matching-paren t))
1353 (blink-matching-open)))
1359 @section Inverse Video
1360 @cindex Inverse Video
1362 @defopt inverse-video
1363 @cindex highlighting
1364 This variable controls whether Emacs uses inverse video for all text
1365 on the screen. Non-@code{nil} means yes, @code{nil} means no. The
1366 default is @code{nil}.
1369 @defopt mode-line-inverse-video
1370 This variable controls the use of inverse video for mode lines. If it
1371 is non-@code{nil}, then mode lines are displayed in inverse video.
1372 Otherwise, mode lines are displayed normally, just like text. The
1373 default is @code{t}.
1375 For window frames, this displays mode lines using the face named
1376 @code{modeline}, which is normally the inverse of the default face
1377 unless you change it.
1381 @section Usual Display Conventions
1383 The usual display conventions define how to display each character
1384 code. You can override these conventions by setting up a display table
1385 (@pxref{Display Tables}). Here are the usual display conventions:
1389 Character codes 32 through 126 map to glyph codes 32 through 126.
1390 Normally this means they display as themselves.
1393 Character code 9 is a horizontal tab. It displays as whitespace
1394 up to a position determined by @code{tab-width}.
1397 Character code 10 is a newline.
1400 All other codes in the range 0 through 31, and code 127, display in one
1401 of two ways according to the value of @code{ctl-arrow}. If it is
1402 non-@code{nil}, these codes map to sequences of two glyphs, where the
1403 first glyph is the @sc{ASCII} code for @samp{^}. (A display table can
1404 specify a glyph to use instead of @samp{^}.) Otherwise, these codes map
1405 just like the codes in the range 128 to 255.
1408 Character codes 128 through 255 map to sequences of four glyphs, where
1409 the first glyph is the @sc{ASCII} code for @samp{\}, and the others are
1410 digit characters representing the character code in octal. (A display
1411 table can specify a glyph to use instead of @samp{\}.)
1414 Multibyte character codes above 256 are displayed as themselves, or as a
1415 question mark or empty box if the terminal cannot display that
1419 The usual display conventions apply even when there is a display
1420 table, for any character whose entry in the active display table is
1421 @code{nil}. Thus, when you set up a display table, you need only
1422 specify the characters for which you want special behavior.
1424 These variables affect the way certain characters are displayed on the
1425 screen. Since they change the number of columns the characters occupy,
1426 they also affect the indentation functions. These variables also affect
1427 how the mode line is displayed; if you want to force redisplay of the
1428 mode line using the new values, call the function
1429 @code{force-mode-line-update} (@pxref{Mode Line Format}).
1432 @cindex control characters in display
1433 This buffer-local variable controls how control characters are
1434 displayed. If it is non-@code{nil}, they are displayed as a caret
1435 followed by the character: @samp{^A}. If it is @code{nil}, they are
1436 displayed as a backslash followed by three octal digits: @samp{\001}.
1439 @c Following may have overfull hbox.
1440 @defvar default-ctl-arrow
1441 The value of this variable is the default value for @code{ctl-arrow} in
1442 buffers that do not override it. @xref{Default Value}.
1446 The value of this variable is the spacing between tab stops used for
1447 displaying tab characters in Emacs buffers. The default is 8. Note
1448 that this feature is completely independent of the user-settable tab
1449 stops used by the command @code{tab-to-tab-stop}. @xref{Indent Tabs}.
1452 @node Display Tables
1453 @section Display Tables
1455 @cindex display table
1456 You can use the @dfn{display table} feature to control how all possible
1457 character codes display on the screen. This is useful for displaying
1458 European languages that have letters not in the @sc{ASCII} character
1461 The display table maps each character code into a sequence of
1462 @dfn{glyphs}, each glyph being an image that takes up one character
1463 position on the screen. You can also define how to display each glyph
1464 on your terminal, using the @dfn{glyph table}.
1466 Display tables affect how the mode line is displayed; if you want to
1467 force redisplay of the mode line using a new display table, call
1468 @code{force-mode-line-update} (@pxref{Mode Line Format}).
1471 * Display Table Format:: What a display table consists of.
1472 * Active Display Table:: How Emacs selects a display table to use.
1473 * Glyphs:: How to define a glyph, and what glyphs mean.
1476 @node Display Table Format
1477 @subsection Display Table Format
1479 A display table is actually a char-table (@pxref{Char-Tables}) with
1480 @code{display-table} as its subtype.
1482 @defun make-display-table
1483 This creates and returns a display table. The table initially has
1484 @code{nil} in all elements.
1487 The ordinary elements of the display table are indexed by character
1488 codes; the element at index @var{c} says how to display the character
1489 code @var{c}. The value should be @code{nil} or a vector of glyph
1490 values (@pxref{Glyphs}). If an element is @code{nil}, it says to
1491 display that character according to the usual display conventions
1492 (@pxref{Usual Display}).
1494 If you use the display table to change the display of newline
1495 characters, the whole buffer will be displayed as one long ``line.''
1497 The display table also has six ``extra slots'' which serve special
1498 purposes. Here is a table of their meanings; @code{nil} in any slot
1499 means to use the default for that slot, as stated below.
1503 The glyph for the end of a truncated screen line (the default for this
1504 is @samp{$}). @xref{Glyphs}.
1506 The glyph for the end of a continued line (the default is @samp{\}).
1508 The glyph for indicating a character displayed as an octal character
1509 code (the default is @samp{\}).
1511 The glyph for indicating a control character (the default is @samp{^}).
1513 A vector of glyphs for indicating the presence of invisible lines (the
1514 default is @samp{...}). @xref{Selective Display}.
1516 The glyph used to draw the border between side-by-side windows (the
1517 default is @samp{|}). @xref{Splitting Windows}.
1520 For example, here is how to construct a display table that mimics the
1521 effect of setting @code{ctl-arrow} to a non-@code{nil} value:
1524 (setq disptab (make-display-table))
1527 (or (= i ?\t) (= i ?\n)
1528 (aset disptab i (vector ?^ (+ i 64))))
1530 (aset disptab 127 (vector ?^ ??)))
1533 @defun display-table-slot display-table slot
1534 @tindex display-table-slot
1535 This function returns the value of the extra slot @var{slot} of
1536 @var{display-table}. The argument @var{slot} may be a number from 0 to
1537 5 inclusive, or a slot name (symbol). Valid symbols are
1538 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
1539 @code{selective-display}, and @code{vertical-border}.
1542 @defun set-display-table-slot display-table slot value
1543 @tindex set-display-table-slot
1544 This function stores @var{value} in the extra slot @var{slot} of
1545 @var{display-table}. The argument @var{slot} may be a number from 0 to
1546 5 inclusive, or a slot name (symbol). Valid symbols are
1547 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
1548 @code{selective-display}, and @code{vertical-border}.
1551 @node Active Display Table
1552 @subsection Active Display Table
1553 @cindex active display table
1555 Each window can specify a display table, and so can each buffer. When
1556 a buffer @var{b} is displayed in window @var{w}, display uses the
1557 display table for window @var{w} if it has one; otherwise, the display
1558 table for buffer @var{b} if it has one; otherwise, the standard display
1559 table if any. The display table chosen is called the @dfn{active}
1562 @defun window-display-table window
1563 This function returns @var{window}'s display table, or @code{nil}
1564 if @var{window} does not have an assigned display table.
1567 @defun set-window-display-table window table
1568 This function sets the display table of @var{window} to @var{table}.
1569 The argument @var{table} should be either a display table or
1573 @defvar buffer-display-table
1574 This variable is automatically buffer-local in all buffers; its value in
1575 a particular buffer specifies the display table for that buffer. If it
1576 is @code{nil}, that means the buffer does not have an assigned display
1580 @defvar standard-display-table
1581 This variable's value is the default display table, used whenever a
1582 window has no display table and neither does the buffer displayed in
1583 that window. This variable is @code{nil} by default.
1586 If there is no display table to use for a particular window---that is,
1587 if the window specifies none, its buffer specifies none, and
1588 @code{standard-display-table} is @code{nil}---then Emacs uses the usual
1589 display conventions for all character codes in that window. @xref{Usual
1596 A @dfn{glyph} is a generalization of a character; it stands for an
1597 image that takes up a single character position on the screen. Glyphs
1598 are represented in Lisp as integers, just as characters are.
1601 The meaning of each integer, as a glyph, is defined by the glyph
1602 table, which is the value of the variable @code{glyph-table}.
1605 The value of this variable is the current glyph table. It should be a
1606 vector; the @var{g}th element defines glyph code @var{g}. If the value
1607 is @code{nil} instead of a vector, then all glyphs are simple (see
1611 Here are the possible types of elements in the glyph table:
1615 Send the characters in @var{string} to the terminal to output
1616 this glyph. This alternative is available on character terminals,
1617 but not under a window system.
1620 Define this glyph code as an alias for glyph code @var{integer}. You
1621 can use an alias to specify a face code for the glyph; see below.
1624 This glyph is simple. On an ordinary terminal, the glyph code mod
1625 524288 is the character to output. In a window system, the glyph code
1626 mod 524288 is the character to output, and the glyph code divided by
1627 524288 specifies the face number (@pxref{Face Functions}) to use while
1628 outputting it. (524288 is
1638 If a glyph code is greater than or equal to the length of the glyph
1639 table, that code is automatically simple.
1646 This section describes how to make Emacs ring the bell (or blink the
1647 screen) to attract the user's attention. Be conservative about how
1648 often you do this; frequent bells can become irritating. Also be
1649 careful not to use just beeping when signaling an error is more
1650 appropriate. (@xref{Errors}.)
1652 @defun ding &optional do-not-terminate
1653 @cindex keyboard macro termination
1654 This function beeps, or flashes the screen (see @code{visible-bell} below).
1655 It also terminates any keyboard macro currently executing unless
1656 @var{do-not-terminate} is non-@code{nil}.
1659 @defun beep &optional do-not-terminate
1660 This is a synonym for @code{ding}.
1663 @defopt visible-bell
1664 This variable determines whether Emacs should flash the screen to
1665 represent a bell. Non-@code{nil} means yes, @code{nil} means no. This
1666 is effective on a window system, and on a character-only terminal
1667 provided the terminal's Termcap entry defines the visible bell
1668 capability (@samp{vb}).
1671 @defvar ring-bell-function
1672 @tindex ring-bell-function
1673 If this is non-@code{nil}, it specifies how Emacs should ``ring the
1674 bell.'' Its value should be a function of no arguments.
1677 @node Window Systems
1678 @section Window Systems
1680 Emacs works with several window systems, most notably the X Window
1681 System. Both Emacs and X use the term ``window'', but use it
1682 differently. An Emacs frame is a single window as far as X is
1683 concerned; the individual Emacs windows are not known to X at all.
1685 @defvar window-system
1686 This variable tells Lisp programs what window system Emacs is running
1687 under. The possible values are
1691 @cindex X Window System
1692 Emacs is displaying using X.
1694 Emacs is displaying using MSDOS.
1696 Emacs is displaying using Windows NT or Windows 95.
1698 Emacs is using a character-based terminal.
1702 @defvar window-setup-hook
1703 This variable is a normal hook which Emacs runs after handling the
1704 initialization files. Emacs runs this hook after it has completed
1705 loading your @file{.emacs} file, the default initialization file (if
1706 any), and the terminal-specific Lisp code, and running the hook
1707 @code{term-setup-hook}.
1709 This hook is used for internal purposes: setting up communication with
1710 the window system, and creating the initial window. Users should not