(Charsets): mention windows-1252
[emacs.git] / lispref / display.texi
blob4cfef835049f50b284c2bc0bbfac9f21574ddc2f
1 @c -*-texinfo-*-
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, 2001
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
8 @chapter Emacs Display
10   This chapter describes a number of features related to the display
11 that Emacs presents to the user.
13 @menu
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:
25                           font, colors, etc.
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.
34 @end menu
36 @node Refresh Screen
37 @section Refreshing the Screen
39 The function @code{redraw-frame} redisplays the entire contents of a
40 given frame (@pxref{Frames}).
42 @c Emacs 19 feature
43 @defun redraw-frame frame
44 This function clears and redisplays frame @var{frame}.
45 @end defun
47 Even more powerful is @code{redraw-display}:
49 @deffn Command redraw-display
50 This function clears and redisplays all visible frames.
51 @end deffn
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
62 resumption.
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}.
70 @end defvar
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
86 as of Emacs 21.
87 @end defvar
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
91 pending, do this:
93 @example
94 (let ((redisplay-dont-pause t))
95   (sit-for 0))
96 @end example
98 @node Truncation
99 @section Truncation
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
122 lines are truncated.
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}.
127 @end defopt
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.
132 @end defopt
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.
139 @end defopt
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.
162 @end defvar
164 @node The Echo Area
165 @section The Echo Area
166 @cindex error display
167 @cindex echo area
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
180 follows:
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
187 constructed string.
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.
195 @c Emacs 19 feature
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.
201 @example
202 @group
203 (message "Minibuffer depth is %d."
204          (minibuffer-depth))
205  @print{} Minibuffer depth is 0.
206 @result{} "Minibuffer depth is 0."
207 @end group
209 @group
210 ---------- Echo Area ----------
211 Minibuffer depth is 0.
212 ---------- Echo Area ----------
213 @end group
214 @end example
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}.
218 @end defun
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.
226 @end defmac
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.
240 @end defun
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
247 @code{message}.
248 @end defun
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.
269 @end defun
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.
274 @end defun
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.
284 @end defvar
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.
289 @end defvar
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:
300 @example
301 (let (message-log-max)
302   (message @dots{}))
303 @end example
304 @end defopt
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,
309 which specifies the
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.
317 @end defvar
319 @node Invisible Text
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
326 (@pxref{Overlays}).
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.
351 @table @asis
352 @item @code{t}
353 A character is invisible if its @code{invisible} property is
354 non-@code{nil}.  This is the default.
356 @item a list
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:
361 @table @code
362 @item @var{atom}
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.
371 @end table
372 @end table
373 @end defvar
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).
381 @end defun
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.
386 @end defun
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}
391 property:
393 @example
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)
406 @end example
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
445 user-level feature.
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.  
471 @itemize @bullet
472 @item
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
476 display.
478 @item
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
481 displayed.
482 @end itemize
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
494 change.
496 @example
497 @group
498 (setq selective-display nil)
499      @result{} nil
501 ---------- Buffer: foo ----------
502 1 on this column
503  2on this column
504   3n this column
505   3n this column
506  2on this column
507 1 on this column
508 ---------- Buffer: foo ----------
509 @end group
511 @group
512 (setq selective-display 2)
513      @result{} 2
515 ---------- Buffer: foo ----------
516 1 on this column
517  2on this column
518  2on this column
519 1 on this column
520 ---------- Buffer: foo ----------
521 @end group
522 @end example
523 @end defvar
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.
530 @example
531 @group
532 (setq selective-display-ellipses t)
533      @result{} t
535 ---------- Buffer: foo ----------
536 1 on this column
537  2on this column ...
538  2on this column
539 1 on this column
540 ---------- Buffer: foo ----------
541 @end group
542 @end example
544 You can use a display table to substitute other text for the ellipsis
545 (@samp{@dots{}}).  @xref{Display Tables}.
546 @end defvar
548 @node Overlay Arrow
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.
562 @end defvar
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
571 overwritten.
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
575 given time.
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
578 @c now.  Is it?
579 @end defvar
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.
620 @example
621 @group
622 ---------- Buffer: foo ----------
623  This is the contents of foo.
624 ---------- Buffer: foo ----------
625 @end group
627 @group
628 (with-output-to-temp-buffer "foo"
629     (print 20)
630     (print standard-output))
631 @result{} #<buffer foo>
633 ---------- Buffer: foo ----------
636 #<buffer foo>
638 ---------- Buffer: foo ----------
639 @end group
640 @end example
641 @end defspec
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
651 selected.
652 @end defvar
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
659 mode.
660 @end defvar
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
668 still Help mode.
669 @end defvar
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
674 modification status.
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
696 second line:
698 @example
699 @group
700 ---------- Buffer: foo ----------
701 This is the contents of foo.
702 @point{}Second line.
703 ---------- Buffer: foo ----------
704 @end group
706 @group
707 (momentary-string-display
708   "**** Important Message! ****"
709   (point) ?\r
710   "Type RET when done reading")
711 @result{} t
712 @end group
714 @group
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 ----------
723 @end group
724 @end example
725 @end defun
727 @node Overlays
728 @section Overlays
729 @cindex overlays
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.
737 @menu
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.
742 @end menu
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
759 overlay:
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
766 is @code{nil}.
767 @end defun
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}.
772 @end defun
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
779 of them:
781 @table @code
782 @item priority
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
789 priority overlay.
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.
795 @item window
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.
800 @item category
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.
806 @item face
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:
814 @itemize @bullet
815 @item
816 A face name (a symbol or string).
818 @item
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}.
826 @item
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.
833 @end itemize
835 @item mouse-face
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.
840 @item display
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}.
847 @item help-echo
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
858 within the overlay.
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
863 in the buffer text.
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
867 modified.
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.
888 @item invisible
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.
894 @item intangible
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
902 Text}.
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}.
908 @item before-string
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.
914 @item after-string
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.
920 @item evaporate
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).
925 @item local-map
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}.
932 @item keymap
933 @kindex keymap @r{(overlay property)}
934 The @code{keymap} property is similar to @code{local-map} but overrides the
935 buffer's local map (and the map specified by the @code{local-map}
936 property) rather than replacing it.
937 @end table
939 @node Managing Overlays
940 @subsection Managing Overlays
942   This section describes the functions to create, delete and move
943 overlays, and to examine their contents.
945 @defun make-overlay start end &optional buffer front-advance rear-advance
946 This function creates and returns an overlay that belongs to
947 @var{buffer} and ranges from @var{start} to @var{end}.  Both @var{start}
948 and @var{end} must specify buffer positions; they may be integers or
949 markers.  If @var{buffer} is omitted, the overlay is created in the
950 current buffer.
952 The arguments @var{front-advance} and @var{rear-advance} specify the
953 insertion type for the start of the overlay and for the end of the
954 overlay, respectively.  @xref{Marker Insertion Types}.
955 @end defun
957 @defun overlay-start overlay
958 This function returns the position at which @var{overlay} starts,
959 as an integer.
960 @end defun
962 @defun overlay-end overlay
963 This function returns the position at which @var{overlay} ends,
964 as an integer.
965 @end defun
967 @defun overlay-buffer overlay
968 This function returns the buffer that @var{overlay} belongs to.
969 @end defun
971 @defun delete-overlay overlay
972 This function deletes @var{overlay}.  The overlay continues to exist as
973 a Lisp object, and its property list is unchanged, but it ceases to be
974 attached to the buffer it belonged to, and ceases to have any effect on
975 display.
977 A deleted overlay is not permanently disconnected.  You can give it a
978 position in a buffer again by calling @code{move-overlay}.
979 @end defun
981 @defun move-overlay overlay start end &optional buffer
982 This function moves @var{overlay} to @var{buffer}, and places its bounds
983 at @var{start} and @var{end}.  Both arguments @var{start} and @var{end}
984 must specify buffer positions; they may be integers or markers.
986 If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
987 was already associated with; if @var{overlay} was deleted, it goes into
988 the current buffer.
990 The return value is @var{overlay}.
992 This is the only valid way to change the endpoints of an overlay.  Do
993 not try modifying the markers in the overlay by hand, as that fails to
994 update other vital data structures and can cause some overlays to be
995 ``lost''.
996 @end defun
998   Here are some examples:
1000 @example
1001 ;; @r{Create an overlay.}
1002 (setq foo (make-overlay 1 10))
1003      @result{} #<overlay from 1 to 10 in display.texi>
1004 (overlay-start foo)
1005      @result{} 1
1006 (overlay-end foo)
1007      @result{} 10
1008 (overlay-buffer foo)
1009      @result{} #<buffer display.texi>
1010 ;; @r{Give it a property we can check later.}
1011 (overlay-put foo 'happy t)
1012      @result{} t
1013 ;; @r{Verify the property is present.}
1014 (overlay-get foo 'happy)
1015      @result{} t
1016 ;; @r{Move the overlay.}
1017 (move-overlay foo 5 20)
1018      @result{} #<overlay from 5 to 20 in display.texi>
1019 (overlay-start foo)
1020      @result{} 5
1021 (overlay-end foo)
1022      @result{} 20
1023 ;; @r{Delete the overlay.}
1024 (delete-overlay foo)
1025      @result{} nil
1026 ;; @r{Verify it is deleted.}
1028      @result{} #<overlay in no buffer>
1029 ;; @r{A deleted overlay has no position.}
1030 (overlay-start foo)
1031      @result{} nil
1032 (overlay-end foo)
1033      @result{} nil
1034 (overlay-buffer foo)
1035      @result{} nil
1036 ;; @r{Undelete the overlay.}
1037 (move-overlay foo 1 20)
1038      @result{} #<overlay from 1 to 20 in display.texi>
1039 ;; @r{Verify the results.}
1040 (overlay-start foo)
1041      @result{} 1
1042 (overlay-end foo)
1043      @result{} 20
1044 (overlay-buffer foo)
1045      @result{} #<buffer display.texi>
1046 ;; @r{Moving and deleting the overlay does not change its properties.}
1047 (overlay-get foo 'happy)
1048      @result{} t
1049 @end example
1051 @node Finding Overlays
1052 @subsection Searching for Overlays
1054 @defun overlays-at pos
1055 This function returns a list of all the overlays that cover the
1056 character at position @var{pos} in the current buffer.  The list is in
1057 no particular order.  An overlay contains position @var{pos} if it
1058 begins at or before @var{pos}, and ends after @var{pos}.
1060 To illustrate usage, here is a Lisp function that returns a list of the
1061 overlays that specify property @var{prop} for the character at point:
1063 @smallexample
1064 (defun find-overlays-specifying (prop)
1065   (let ((overlays (overlays-at (point)))
1066         found)
1067     (while overlays
1068       (let ((overlay (cdr overlays)))
1069         (if (overlay-get overlay prop)
1070             (setq found (cons overlay found))))
1071       (setq overlays (cdr overlays)))
1072     found))
1073 @end smallexample
1074 @end defun
1076 @defun overlays-in beg end
1077 This function returns a list of the overlays that overlap the region
1078 @var{beg} through @var{end}.  ``Overlap'' means that at least one
1079 character is contained within the overlay and also contained within the
1080 specified region; however, empty overlays are included in the result if
1081 they are located at @var{beg}, or strictly between @var{beg} and @var{end}.
1082 @end defun
1084 @defun next-overlay-change pos
1085 This function returns the buffer position of the next beginning or end
1086 of an overlay, after @var{pos}.
1087 @end defun
1089 @defun previous-overlay-change pos
1090 This function returns the buffer position of the previous beginning or
1091 end of an overlay, before @var{pos}.
1092 @end defun
1094   Here's an easy way to use @code{next-overlay-change} to search for the
1095 next character which gets a non-@code{nil} @code{happy} property from
1096 either its overlays or its text properties (@pxref{Property Search}):
1098 @smallexample
1099 (defun find-overlay-prop (prop)
1100   (save-excursion
1101     (while (and (not (eobp))
1102                 (not (get-char-property (point) 'happy)))
1103       (goto-char (min (next-overlay-change (point))
1104                       (next-single-property-change (point) 'happy))))
1105     (point)))
1106 @end smallexample
1108 @node Width
1109 @section Width
1111 Since not all characters have the same width, these functions let you
1112 check the width of a character.  @xref{Primitive Indent}, and
1113 @ref{Screen Lines}, for related functions.
1115 @defun char-width char
1116 This function returns the width in columns of the character @var{char},
1117 if it were displayed in the current buffer and the selected window.
1118 @end defun
1120 @defun string-width string
1121 This function returns the width in columns of the string @var{string},
1122 if it were displayed in the current buffer and the selected window.
1123 @end defun
1125 @defun truncate-string-to-width string width &optional start-column padding
1126 This function returns the part of @var{string} that fits within
1127 @var{width} columns, as a new string.
1129 If @var{string} does not reach @var{width}, then the result ends where
1130 @var{string} ends.  If one multi-column character in @var{string}
1131 extends across the column @var{width}, that character is not included in
1132 the result.  Thus, the result can fall short of @var{width} but cannot
1133 go beyond it.
1135 The optional argument @var{start-column} specifies the starting column.
1136 If this is non-@code{nil}, then the first @var{start-column} columns of
1137 the string are omitted from the value.  If one multi-column character in
1138 @var{string} extends across the column @var{start-column}, that
1139 character is not included.
1141 The optional argument @var{padding}, if non-@code{nil}, is a padding
1142 character added at the beginning and end of the result string, to extend
1143 it to exactly @var{width} columns.  The padding character is used at the
1144 end of the result if it falls short of @var{width}.  It is also used at
1145 the beginning of the result if one multi-column character in
1146 @var{string} extends across the column @var{start-column}.
1148 @example
1149 (truncate-string-to-width "\tab\t" 12 4)
1150      @result{} "ab"
1151 (truncate-string-to-width "\tab\t" 12 4 ?\ )
1152      @result{} "    ab  "
1153 @end example
1154 @end defun
1156 @node Faces
1157 @section Faces
1158 @cindex face
1160   A @dfn{face} is a named collection of graphical attributes: font
1161 family, foreground color, background color, optional underlining, and
1162 many others.  Faces are used in Emacs to control the style of display of
1163 particular parts of the text or the frame.
1165 @cindex face id
1166 Each face has its own @dfn{face number}, which distinguishes faces at
1167 low levels within Emacs.  However, for most purposes, you refer to
1168 faces in Lisp programs by their names.
1170 @defun facep object
1171 This function returns @code{t} if @var{object} is a face name symbol (or
1172 if it is a vector of the kind used internally to record face data).  It
1173 returns @code{nil} otherwise.
1174 @end defun
1176 Each face name is meaningful for all frames, and by default it has the
1177 same meaning in all frames.  But you can arrange to give a particular
1178 face name a special meaning in one frame if you wish.
1180 @menu
1181 * Standard Faces::      The faces Emacs normally comes with.
1182 * Defining Faces::      How to define a face with @code{defface}.
1183 * Face Attributes::     What is in a face?
1184 * Attribute Functions:: Functions to examine and set face attributes.
1185 * Merging Faces::       How Emacs combines the faces specified for a character.
1186 * Font Selection::      Finding the best available font for a face.
1187 * Face Functions::      How to define and examine faces.
1188 * Auto Faces::          Hook for automatic face assignment.
1189 * Font Lookup::         Looking up the names of available fonts
1190                           and information about them.
1191 * Fontsets::            A fontset is a collection of fonts
1192                           that handle a range of character sets.
1193 @end menu
1195 @node Standard Faces
1196 @subsection Standard Faces
1198   This table lists all the standard faces and their uses.  Most of them
1199 are used for displaying certain parts of the frames or certain kinds of
1200 text; you can control how those places look by customizing these faces.
1202 @table @code
1203 @item default
1204 @kindex default @r{(face name)}
1205 This face is used for ordinary text.
1207 @item mode-line
1208 @kindex mode-line @r{(face name)}
1209 This face is used for mode lines, and for menu bars when toolkit menus
1210 are not used---but only if @code{mode-line-inverse-video} is
1211 non-@code{nil}.
1213 @item modeline
1214 @kindex modeline @r{(face name)}
1215 This is an alias for the @code{mode-line} face, for compatibility with
1216 old Emacs versions.
1218 @item header-line
1219 @kindex header-line @r{(face name)}
1220 This face is used for the header lines of windows that have them.
1222 @item menu
1223 This face controls the display of menus, both their colors and their
1224 font.  (This works only on certain systems.)
1226 @item fringe
1227 @kindex fringe @r{(face name)}
1228 This face controls the colors of window fringes, the thin areas on
1229 either side that are used to display continuation and truncation glyphs.
1231 @item scroll-bar
1232 @kindex scroll-bar @r{(face name)}
1233 This face controls the colors for display of scroll bars.
1235 @item tool-bar
1236 @kindex tool-bar @r{(face name)}
1237 This face is used for display of the tool bar, if any.
1239 @item region
1240 @kindex region @r{(face name)}
1241 This face is used for highlighting the region in Transient Mark mode.
1243 @item secondary-selection
1244 @kindex secondary-selection @r{(face name)}
1245 This face is used to show any secondary selection you have made.
1247 @item highlight
1248 @kindex highlight @r{(face name)}
1249 This face is meant to be used for highlighting for various purposes.
1251 @item trailing-whitespace
1252 @kindex trailing-whitespace @r{(face name)}
1253 This face is used to display excess whitespace at the end of a line,
1254 if @code{show-trailing-whitespace} is non-@code{nil}.
1255 @end table
1257   In contrast, these faces are provided to change the appearance of text
1258 in specific ways.  You can use them on specific text, when you want
1259 the effects they produce.
1261 @table @code
1262 @item bold
1263 @kindex bold @r{(face name)}
1264 This face uses a bold font, if possible.  It uses the bold variant of
1265 the frame's font, if it has one.  It's up to you to choose a default
1266 font that has a bold variant, if you want to use one.
1268 @item italic
1269 @kindex italic @r{(face name)}
1270 This face uses the italic variant of the frame's font, if it has one.
1272 @item bold-italic
1273 @kindex bold-italic @r{(face name)}
1274 This face uses the bold italic variant of the frame's font, if it has
1275 one.
1277 @item underline
1278 @kindex underline @r{(face name)}
1279 This face underlines text.
1281 @item fixed-patch
1282 @kindex fixed-patch @r{(face name)}
1283 This face forces use of a particular fixed-width font.
1285 @item variable-patch
1286 @kindex variable-patch @r{(face name)}
1287 This face forces use of a particular variable-width font.  It's
1288 reasonable to customize this to use a different variable-width font, if
1289 you like, but you should not make it a fixed-width font.
1290 @end table
1292 @defvar show-trailing-whitespace
1293 @tindex show-trailing-whitespace
1294 If this variable is non-@code{nil}, Emacs uses the
1295 @code{trailing-whitespace} face to display any spaces and tabs at the
1296 end of a line.
1297 @end defvar
1299 @node Defining Faces
1300 @subsection Defining Faces
1302   The way to define a new face is with @code{defface}.  This creates a
1303 kind of customization item (@pxref{Customization}) which the user can
1304 customize using the Customization buffer (@pxref{Easy Customization,,,
1305 emacs, The GNU Emacs Manual}).
1307 @defmac defface face spec doc [keyword value]... 
1308 This declares @var{face} as a customizable face that defaults according
1309 to @var{spec}.  You should not quote the symbol @var{face}.  The
1310 argument @var{doc} specifies the face documentation.  The keywords you
1311 can use in @code{defface} are the same ones that are meaningful in both
1312 @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
1314 When @code{defface} executes, it defines the face according to
1315 @var{spec}, then uses any customizations that were read from the
1316 init file (@pxref{Init File}) to override that specification.
1318 The purpose of @var{spec} is to specify how the face should appear on
1319 different kinds of terminals.  It should be an alist whose elements have
1320 the form @code{(@var{display} @var{atts})}.  Each element's @sc{car},
1321 @var{display}, specifies a class of terminals.  The element's second element,
1322 @var{atts}, is a list of face attributes and their values; it specifies
1323 what the face should look like on that kind of terminal.  The possible
1324 attributes are defined in the value of @code{custom-face-attributes}.
1326 The @var{display} part of an element of @var{spec} determines which
1327 frames the element applies to.  If more than one element of @var{spec}
1328 matches a given frame, the first matching element is the only one used
1329 for that frame.  There are two possibilities for @var{display}:
1331 @table @asis
1332 @item @code{t}
1333 This element of @var{spec} matches all frames.  Therefore, any
1334 subsequent elements of @var{spec} are never used.  Normally
1335 @code{t} is used in the last (or only) element of @var{spec}.
1337 @item a list
1338 If @var{display} is a list, each element should have the form
1339 @code{(@var{characteristic} @var{value}@dots{})}.  Here
1340 @var{characteristic} specifies a way of classifying frames, and the
1341 @var{value}s are possible classifications which @var{display} should
1342 apply to.  Here are the possible values of @var{characteristic}:
1344 @table @code
1345 @item type
1346 The kind of window system the frame uses---either @code{graphic} (any
1347 graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console),
1348 @code{w32} (for MS Windows 9X/NT), or @code{tty} (a non-graphics-capable
1349 display).
1351 @item class
1352 What kinds of colors the frame supports---either @code{color},
1353 @code{grayscale}, or @code{mono}.
1355 @item background
1356 The kind of background---either @code{light} or @code{dark}.
1357 @end table
1359 If an element of @var{display} specifies more than one @var{value} for a
1360 given @var{characteristic}, any of those values is acceptable.  If
1361 @var{display} has more than one element, each element should specify a
1362 different @var{characteristic}; then @emph{each} characteristic of the
1363 frame must match one of the @var{value}s specified for it in
1364 @var{display}.
1365 @end table
1366 @end defmac
1368   Here's how the standard face @code{region} is defined:
1370 @example
1371 @group
1372 (defface region
1373   `((((type tty) (class color))
1374      (:background "blue" :foreground "white"))
1375 @end group
1376     (((type tty) (class mono))
1377      (:inverse-video t))
1378     (((class color) (background dark))
1379      (:background "blue"))
1380     (((class color) (background light))
1381      (:background "lightblue"))
1382     (t (:background "gray")))
1383 @group
1384   "Basic face for highlighting the region."
1385   :group 'basic-faces)
1386 @end group
1387 @end example
1389   Internally, @code{defface} uses the symbol property
1390 @code{face-defface-spec} to record the face attributes specified in
1391 @code{defface}, @code{saved-face} for the attributes saved by the user
1392 with the customization buffer, and @code{face-documentation} for the
1393 documentation string.
1395 @defopt frame-background-mode
1396 This option, if non-@code{nil}, specifies the background type to use for
1397 interpreting face definitions.  If it is @code{dark}, then Emacs treats
1398 all frames as if they had a dark background, regardless of their actual
1399 background colors.  If it is @code{light}, then Emacs treats all frames
1400 as if they had a light background.
1401 @end defopt
1403 @node Face Attributes
1404 @subsection Face Attributes
1405 @cindex face attributes
1407   The effect of using a face is determined by a fixed set of @dfn{face
1408 attributes}.  This table lists all the face attributes, and what they
1409 mean.  Note that in general, more than one face can be specified for a
1410 given piece of text; when that happens, the attributes of all the faces
1411 are merged to specify how to display the text.  @xref{Merging Faces}.
1413   In Emacs 21, any attribute in a face can have the value
1414 @code{unspecified}.  This means the face doesn't specify that attribute.
1415 In face merging, when the first face fails to specify a particular
1416 attribute, that means the next face gets a chance.  However, the
1417 @code{default} face must specify all attributes.
1419   Some of these font attributes are meaningful only on certain kinds of
1420 displays---if your display cannot handle a certain attribute, the
1421 attribute is ignored.  (The attributes @code{:family}, @code{:width},
1422 @code{:height}, @code{:weight}, and @code{:slant} correspond to parts of
1423 an X Logical Font Descriptor.)
1425 @table @code
1426 @item :family
1427 Font family name, or fontset name (@pxref{Fontsets}).  If you specify a
1428 font family name, the wild-card characters @samp{*} and @samp{?} are
1429 allowed.
1431 @item :width
1432 Relative proportionate width, also known as the character set width or
1433 set width.  This should be one of the symbols @code{ultra-condensed},
1434 @code{extra-condensed}, @code{condensed}, @code{semi-condensed},
1435 @code{normal}, @code{semi-expanded}, @code{expanded},
1436 @code{extra-expanded}, or @code{ultra-expanded}.
1437    
1438 @item :height
1439 Either the font height, an integer in units of 1/10 point, a floating
1440 point number specifying the amount by which to scale the height of any
1441 underlying face, or a function, which is called with the old height
1442 (from the underlying face), and should return the new height.
1443    
1444 @item :weight
1445 Font weight---a symbol from this series (from most dense to most faint):
1446 @code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
1447 @code{normal}, @code{semi-light}, @code{light}, @code{extra-light},
1448 or @code{ultra-light}.
1450 On a text-only terminal, any weight greater than normal is displayed as
1451 extra bright, and any weight less than normal is displayed as
1452 half-bright (provided the terminal supports the feature).
1454 @item :slant
1455 Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal},
1456 @code{reverse-italic}, or @code{reverse-oblique}.
1458 On a text-only terminal, slanted text is displayed as half-bright, if
1459 the terminal supports the feature.
1461 @item :foreground
1462 Foreground color, a string.
1463    
1464 @item :background
1465 Background color, a string.
1467 @item :inverse-video
1468 Whether or not characters should be displayed in inverse video.  The
1469 value should be @code{t} (yes) or @code{nil} (no).
1471 @item :stipple
1472 The background stipple, a bitmap.
1474 The value can be a string; that should be the name of a file containing
1475 external-format X bitmap data.  The file is found in the directories
1476 listed in the variable @code{x-bitmap-file-path}.
1478 Alternatively, the value can specify the bitmap directly, with a list of
1479 the form @code{(@var{width} @var{height} @var{data})}.  Here,
1480 @var{width} and @var{height} specify the size in pixels, and @var{data}
1481 is a string containing the raw bits of the bitmap, row by row.  Each row
1482 occupies @math{(@var{width} + 7) / 8} consecutie bytes in the string
1483 (which should be a unibyte string for best results).
1485 If the value is @code{nil}, that means use no stipple pattern.
1487 Normally you do not need to set the stipple attribute, because it is
1488 used automatically to handle certain shades of gray.
1490 @item :underline
1491 Whether or not characters should be underlined, and in what color.  If
1492 the value is @code{t}, underlining uses the foreground color of the
1493 face.  If the value is a string, underlining uses that color.  The
1494 value @code{nil} means do not underline.
1496 @item :overline
1497 Whether or not characters should be overlined, and in what color.
1498 The value is used like that of @code{:underline}.
1500 @item :strike-through
1501 Whether or not characters should be strike-through, and in what
1502 color.  The value is used like that of @code{:underline}.
1504 @item :inherit
1505 The name of a face from which to inherit attributes, or a list of face
1506 names.  Attributes from inherited faces are merged into the face like an
1507 underlying face would be, with higher priority than underlying faces.
1509 @item :box
1510 Whether or not a box should be drawn around characters, its color, the
1511 width of the box lines, and 3D appearance.
1512 @end table
1514   Here are the possible values of the @code{:box} attribute, and what
1515 they mean:
1517 @table @asis
1518 @item @code{nil}
1519 Don't draw a box.
1521 @item @code{t}
1522 Draw a box with lines of width 1, in the foreground color.
1524 @item @var{color}
1525 Draw a box with lines of width 1, in color @var{color}.
1527 @item @code{(:line-width @var{width} :color @var{color} :style @var{style})}
1528 This way you can explicitly specify all aspects of the box.  The value
1529 @var{width} specifies the width of the lines to draw; it defaults to 1.
1531 The value @var{color} specifies the color to draw with.  The default is
1532 the foreground color of the face for simple boxes, and the background
1533 color of the face for 3D boxes.
1535 The value @var{style} specifies whether to draw a 3D box.  If it is
1536 @code{released-button}, the box looks like a 3D button that is not being
1537 pressed.  If it is @code{pressed-button}, the box looks like a 3D button
1538 that is being pressed.  If it is @code{nil} or omitted, a plain 2D box
1539 is used.
1540 @end table
1542   The attributes @code{:overline}, @code{:strike-through} and
1543 @code{:box} are new in Emacs 21.  The attributes @code{:family},
1544 @code{:height}, @code{:width}, @code{:weight}, @code{:slant} are also
1545 new; previous versions used the following attributes, now semi-obsolete,
1546 to specify some of the same information:
1548 @table @code
1549 @item :font
1550 This attribute specifies the font name.
1552 @item :bold
1553 A non-@code{nil} value specifies a bold font.
1555 @item :italic
1556 A non-@code{nil} value specifies an italic font.
1557 @end table
1559   For compatibility, you can still set these ``attributes'' in Emacs 21,
1560 even though they are not real face attributes.  Here is what that does:
1562 @table @code
1563 @item :font
1564 You can specify an X font name as the ``value'' of this ``attribute'';
1565 that sets the @code{:family}, @code{:width}, @code{:height},
1566 @code{:weight}, and @code{:slant} attributes according to the font name.
1568 If the value is a pattern with wildcards, the first font that matches
1569 the pattern is used to set these attributes.
1571 @item :bold
1572 A non-@code{nil} makes the face bold; @code{nil} makes it normal.
1573 This actually works by setting the @code{:weight} attribute.
1575 @item :italic
1576 A non-@code{nil} makes the face italic; @code{nil} makes it normal.
1577 This actually works by setting the @code{:slant} attribute.
1578 @end table
1580 @defvar x-bitmap-file-path
1581 This variable specifies a list of directories for searching
1582 for bitmap files, for the @code{:stipple} attribute.
1583 @end defvar
1585 @defun bitmap-spec-p object
1586 This returns @code{t} if @var{object} is a valid bitmap
1587 specification, suitable for use with @code{:stipple}.
1588 It returns @code{nil} otherwise.
1589 @end defun
1591 @node Attribute Functions
1592 @subsection Face Attribute Functions
1594   You can modify the attributes of an existing face with the following
1595 functions.  If you specify @var{frame}, they affect just that frame;
1596 otherwise, they affect all frames as well as the defaults that apply to
1597 new frames.
1599 @tindex set-face-attribute
1600 @defun set-face-attribute face frame &rest arguments
1601 This function sets one or more attributes of face @var{face}
1602 for frame @var{frame}.  If @var{frame} is @code{nil}, it sets
1603 the attribute for all frames, and the defaults for new frames.
1605 The extra arguments @var{arguments} specify the attributes to set, and
1606 the values for them.  They should consist of alternating attribute names
1607 (such as @code{:family} or @code{:underline}) and corresponding values.
1608 Thus,
1610 @example
1611 (set-face-attribute 'foo nil
1612                     :width :extended
1613                     :weight :bold
1614                     :underline "red")
1615 @end example
1617 @noindent
1618 sets the attributes @code{:width}, @code{:weight} and @code{:underline}
1619 to the corresponding values.
1620 @end defun
1622 @tindex face-attribute
1623 @defun face-attribute face attribute &optional frame
1624 This returns the value of the @var{attribute} attribute of face
1625 @var{face} on @var{frame}.  If @var{frame} is @code{nil},
1626 that means the selected frame.
1628 If @var{frame} is @code{t}, the value is the default for
1629 @var{face} for new frames.
1631 For example,
1633 @example
1634 (face-attribute 'bold :weight)
1635      @result{} bold
1636 @end example
1637 @end defun
1639   The functions above did not exist before Emacs 21.  For compatibility
1640 with older Emacs versions, you can use the following functions to set
1641 and examine the face attributes which existed in those versions.
1643 @defun set-face-foreground face color &optional frame
1644 @defunx set-face-background face color &optional frame
1645 These functions set the foreground (or background, respectively) color
1646 of face @var{face} to @var{color}.  The argument @var{color} should be a
1647 string, the name of a color.
1649 Certain shades of gray are implemented by stipple patterns on
1650 black-and-white screens.
1651 @end defun
1653 @defun set-face-stipple face pattern &optional frame
1654 This function sets the background stipple pattern of face @var{face} to
1655 @var{pattern}.  The argument @var{pattern} should be the name of a
1656 stipple pattern defined by the X server, or @code{nil} meaning don't use
1657 stipple.
1659 Normally there is no need to pay attention to stipple patterns, because
1660 they are used automatically to handle certain shades of gray.
1661 @end defun
1663 @defun set-face-font face font &optional frame
1664 This function sets the font of face @var{face}.
1666 In Emacs 21, this actually sets the attributes @code{:family},
1667 @code{:width}, @code{:height}, @code{:weight}, and @code{:slant}
1668 according to the font name @var{font}.
1670 In Emacs 20, this sets the font attribute.  Once you set the font
1671 explicitly, the bold and italic attributes cease to have any effect,
1672 because the precise font that you specified is used.
1673 @end defun
1675 @defun set-face-bold-p face bold-p &optional frame
1676 This function specifies whether @var{face} should be bold.  If
1677 @var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no.
1679 In Emacs 21, this sets the @code{:weight} attribute.
1680 In Emacs 20, it sets the @code{:bold} attribute.
1681 @end defun
1683 @defun set-face-italic-p face italic-p &optional frame
1684 This function specifies whether @var{face} should be italic.  If
1685 @var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no.
1687 In Emacs 21, this sets the @code{:slant} attribute.
1688 In Emacs 20, it sets the @code{:italic} attribute.
1689 @end defun
1691 @defun set-face-underline-p face underline-p &optional frame
1692 This function sets the underline attribute of face @var{face}.
1693 Non-@code{nil} means do underline; @code{nil} means don't.
1694 @end defun
1696 @defun invert-face face &optional frame
1697 This function inverts the @code{:inverse-video} attribute of face
1698 @var{face}.  If the attribute is @code{nil}, this function sets it to
1699 @code{t}, and vice versa.
1700 @end defun
1702   These functions examine the attributes of a face.  If you don't
1703 specify @var{frame}, they refer to the default data for new frames.
1704 They return the symbol @code{unspecified} if the face doesn't define any
1705 value for that attribute.
1707 @defun face-foreground face &optional frame
1708 @defunx face-background face &optional frame
1709 These functions return the foreground color (or background color,
1710 respectively) of face @var{face}, as a string.
1711 @end defun
1713 @defun face-stipple face &optional frame
1714 This function returns the name of the background stipple pattern of face
1715 @var{face}, or @code{nil} if it doesn't have one.
1716 @end defun
1718 @defun face-font face &optional frame
1719 This function returns the name of the font of face @var{face}.
1720 @end defun
1722 @defun face-bold-p face &optional frame
1723 This function returns @code{t} if @var{face} is bold---that is, if it is
1724 bolder than normal.  It returns @code{nil} otherwise.
1725 @end defun
1727 @defun face-italic-p face &optional frame
1728 This function returns @code{t} if @var{face} is italic or oblique,
1729 @code{nil} otherwise.
1730 @end defun
1732 @defun face-underline-p face &optional frame
1733 This function returns the @code{:underline} attribute of face @var{face}.
1734 @end defun
1736 @defun face-inverse-video-p face &optional frame
1737 This function returns the @code{:inverse-video} attribute of face @var{face}.
1738 @end defun
1740 @node Merging Faces
1741 @subsection Merging Faces for Display
1743   Here are the ways to specify which faces to use for display of text:
1745 @itemize @bullet
1746 @item
1747 With defaults.  The @code{default} face is used as the ultimate
1748 default for all text.  (In Emacs 19 and 20, the @code{default}
1749 face is used only when no other face is specified.)
1751 For a mode line or header line, the face @code{modeline} or
1752 @code{header-line} is used just before @code{default}.
1754 @item
1755 With text properties.  A character can have a @code{face} property; if
1756 so, the faces and face attributes specified there apply.  @xref{Special
1757 Properties}.
1759 If the character has a @code{mouse-face} property, that is used instead
1760 of the @code{face} property when the mouse is ``near enough'' to the
1761 character.
1763 @item
1764 With overlays.  An overlay can have @code{face} and @code{mouse-face}
1765 properties too; they apply to all the text covered by the overlay.
1767 @item
1768 With a region that is active.  In Transient Mark mode, the region is
1769 highlighted with the face @code{region} (@pxref{Standard Faces}).
1771 @item
1772 With special glyphs.  Each glyph can specify a particular face 
1773 number.  @xref{Glyphs}.
1774 @end itemize
1776   If these various sources together specify more than one face for a
1777 particular character, Emacs merges the attributes of the various faces
1778 specified.  The attributes of the faces of special glyphs come first;
1779 then comes the face for region highlighting, if appropriate;
1780 then come attributes of faces from overlays, followed by those from text
1781 properties, and last the default face.
1783   When multiple overlays cover one character, an overlay with higher
1784 priority overrides those with lower priority.  @xref{Overlays}.
1786   In Emacs 20, if an attribute such as the font or a color is not
1787 specified in any of the above ways, the frame's own font or color is
1788 used.  In newer Emacs versions, this cannot happen, because the
1789 @code{default} face specifies all attributes---in fact, the frame's own
1790 font and colors are synonymous with those of the default face.
1792 @node Font Selection
1793 @subsection Font Selection
1795   @dfn{Selecting a font} means mapping the specified face attributes for
1796 a character to a font that is available on a particular display.  The
1797 face attributes, as determined by face merging, specify most of the
1798 font choice, but not all.  Part of the choice depends on what character
1799 it is.
1801   For multibyte characters, typically each font covers only one
1802 character set.  So each character set (@pxref{Character Sets}) specifies
1803 a registry and encoding to use, with the character set's
1804 @code{x-charset-registry} property.  Its value is a string containing
1805 the registry and the encoding, with a dash between them:
1807 @example
1808 (plist-get (charset-plist 'latin-iso8859-1)
1809            'x-charset-registry)
1810      @result{} "ISO8859-1"
1811 @end example
1813   Unibyte text does not have character sets, so displaying a unibyte
1814 character takes the registry and encoding from the variable
1815 @code{face-default-registry}.
1817 @defvar face-default-registry
1818 This variable specifies which registry and encoding to use in choosing
1819 fonts for unibyte characters.  The value is initialized at Emacs startup
1820 time from the font the user specified for Emacs.
1821 @end defvar
1823   If the face specifies a fontset name, that fontset determines a
1824 pattern for fonts of the given charset.  If the face specifies a font
1825 family, a font pattern is constructed.
1827   Emacs tries to find an available font for the given face attributes
1828 and character's registry and encoding.  If there is a font that matches
1829 exactly, it is used, of course.  The hard case is when no available font
1830 exactly fits the specification.  Then Emacs looks for one that is
1831 ``close''---one attribute at a time.  You can specify the order to
1832 consider the attributes.  In the case where a specified font family is
1833 not available, you can specify a set of mappings for alternatives to
1834 try.
1836 @defvar face-font-selection-order
1837 @tindex face-font-selection-order
1838 This variable specifies the order of importance of the face attributes
1839 @code{:width}, @code{:height}, @code{:weight}, and @code{:slant}.  The
1840 value should be a list containing those four symbols, in order of
1841 decreasing importance.
1843 Font selection first finds the best available matches for the first
1844 attribute listed; then, among the fonts which are best in that way, it
1845 searches for the best matches in the second attribute, and so on.
1847 The attributes @code{:weight} and @code{:width} have symbolic values in
1848 a range centered around @code{normal}.  Matches that are more extreme
1849 (farther from @code{normal}) are somewhat preferred to matches that are
1850 less extreme (closer to @code{normal}); this is designed to ensure that
1851 non-normal faces contrast with normal ones, whenever possible.
1853 The default is @code{(:width :height :weight :slant)}, which means first
1854 find the fonts closest to the specified @code{:width}, then---among the
1855 fonts with that width---find a best match for the specified font height,
1856 and so on.
1858 One example of a case where this variable makes a difference is when the
1859 default font has no italic equivalent.  With the default ordering, the
1860 @code{italic} face will use a non-italic font that is similar to the
1861 default one.  But if you put @code{:slant} before @code{:height}, the
1862 @code{italic} face will use an italic font, even if its height is not
1863 quite right.
1864 @end defvar
1866 @defvar face-font-family-alternatives
1867 @tindex face-font-family-alternatives
1868 This variable lets you specify alternative font families to try, if a
1869 given family is specified and doesn't exist.  Each element should have
1870 this form:
1872 @example
1873 (@var{family} @var{alternate-families}@dots{})
1874 @end example
1876 If @var{family} is specified but not available, Emacs will try the other
1877 families given in @var{alternate-families}, one by one, until it finds a
1878 family that does exist.
1879 @end defvar
1881 @defvar face-font-registry-alternatives
1882 @tindex face-font-registry-alternatives
1883 This variable lets you specify alternative font registries to try, if a
1884 given registry is specified and doesn't exist.  Each element should have
1885 this form:
1887 @example
1888 (@var{registry} @var{alternate-registries}@dots{})
1889 @end example
1891 If @var{registry} is specified but not available, Emacs will try the
1892 other registries given in @var{alternate-registries}, one by one,
1893 until it finds a registry that does exist.
1894 @end defvar
1896   Emacs can make use of scalable fonts, but by default it does not use
1897 them, since the use of too many or too big scalable fonts can crash
1898 XFree86 servers.
1900 @defvar scalable-fonts-allowed
1901 @tindex scalable-fonts-allowed
1902 This variable controls which scalable fonts to use.  A value of
1903 @code{nil}, the default, means do not use scalable fonts.  @code{t}
1904 means to use any scalable font that seems appropriate for the text.
1906 Otherwise, the value must be a list of regular expressions.  Then a
1907 scalable font is enabled for use if its name matches any regular
1908 expression in the list.  For example,
1910 @example
1911 (setq scalable-fonts-allowed '("muleindian-2$"))
1912 @end example
1914 @noindent
1915 allows the use of scalable fonts with registry @code{muleindian-2}.
1916 @end defvar
1918 @defun clear-face-cache &optional unload-p
1919 @tindex clear-face-cache
1920 This function clears the face cache for all frames.
1921 If @var{unload-p} is non-@code{nil}, that means to unload
1922 all unused fonts as well.
1923 @end defun
1925 @node Face Functions
1926 @subsection Functions for Working with Faces
1928   Here are additional functions for creating and working with faces.
1930 @defun make-face name
1931 This function defines a new face named @var{name}, initially with all
1932 attributes @code{nil}.  It does nothing if there is already a face named
1933 @var{name}.
1934 @end defun
1936 @defun face-list
1937 This function returns a list of all defined face names.
1938 @end defun
1940 @defun copy-face old-face new-name &optional frame new-frame
1941 This function defines the face @var{new-name} as a copy of the existing
1942 face named @var{old-face}.  It creates the face @var{new-name} if that
1943 doesn't already exist.
1945 If the optional argument @var{frame} is given, this function applies
1946 only to that frame.  Otherwise it applies to each frame individually,
1947 copying attributes from @var{old-face} in each frame to @var{new-face}
1948 in the same frame.
1950 If the optional argument @var{new-frame} is given, then @code{copy-face}
1951 copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
1952 in @var{new-frame}.
1953 @end defun
1955 @defun face-id face
1956 This function returns the face number of face @var{face}.
1957 @end defun
1959 @defun face-documentation face
1960 This function returns the documentation string of face @var{face}, or
1961 @code{nil} if none was specified for it.
1962 @end defun
1964 @defun face-equal face1 face2 &optional frame
1965 This returns @code{t} if the faces @var{face1} and @var{face2} have the
1966 same attributes for display.
1967 @end defun
1969 @defun face-differs-from-default-p face &optional frame
1970 This returns @code{t} if the face @var{face} displays differently from
1971 the default face.  A face is considered to be ``the same'' as the
1972 default face if each attribute is either the same as that of the default
1973 face, or unspecified (meaning to inherit from the default).
1974 @end defun
1976 @node Auto Faces
1977 @subsection Automatic Face Assignment
1978 @cindex automatic face assignment
1979 @cindex faces, automatic choice
1981 @cindex Font-Lock mode
1982   Starting with Emacs 21, a hook is available for automatically
1983 assigning faces to text in the buffer.  This hook is used for part of
1984 the implementation of Font-Lock mode.
1986 @tindex fontification-functions
1987 @defvar fontification-functions
1988 This variable holds a list of functions that are called by Emacs
1989 redisplay as needed to assign faces automatically to text in the buffer.
1991 The functions are called in the order listed, with one argument, a
1992 buffer position @var{pos}.  Each function should attempt to assign faces
1993 to the text in the current buffer starting at @var{pos}.
1995 Each function should record the faces they assign by setting the
1996 @code{face} property.  It should also add a non-@code{nil}
1997 @code{fontified} property for all the text it has assigned faces to.
1998 That property tells redisplay that faces have been assigned to that text
1999 already.
2001 It is probably a good idea for each function to do nothing if the
2002 character after @var{pos} already has a non-@code{nil} @code{fontified}
2003 property, but this is not required.  If one function overrides the
2004 assignments made by a previous one, the properties as they are
2005 after the last function finishes are the ones that really matter.
2007 For efficiency, we recommend writing these functions so that they
2008 usually assign faces to around 400 to 600 characters at each call.
2009 @end defvar
2011 @node Font Lookup
2012 @subsection Looking Up Fonts
2014 @defun x-list-fonts pattern &optional face frame maximum
2015 This function returns a list of available font names that match
2016 @var{pattern}.  If the optional arguments @var{face} and @var{frame} are
2017 specified, then the list is limited to fonts that are the same size as
2018 @var{face} currently is on @var{frame}.
2020 The argument @var{pattern} should be a string, perhaps with wildcard
2021 characters: the @samp{*} character matches any substring, and the
2022 @samp{?} character matches any single character.  Pattern matching
2023 of font names ignores case.
2025 If you specify @var{face} and @var{frame}, @var{face} should be a face name
2026 (a symbol) and @var{frame} should be a frame.
2028 The optional argument @var{maximum} sets a limit on how many fonts to
2029 return.  If this is non-@code{nil}, then the return value is truncated
2030 after the first @var{maximum} matching fonts.  Specifying a small value
2031 for @var{maximum} can make this function much faster, in cases where
2032 many fonts match the pattern.
2033 @end defun
2035   These additional functions are available starting in Emacs 21.
2037 @defun x-family-fonts &optional family frame
2038 @tindex x-family-fonts
2039 This function returns a list describing the available fonts for family
2040 @var{family} on @var{frame}.  If @var{family} is omitted or @code{nil},
2041 this list applies to all families, and therefore, it contains all
2042 available fonts.  Otherwise, @var{family} must be a string; it may
2043 contain the wildcards @samp{?} and @samp{*}.
2045 The list describes the display that @var{frame} is on; if @var{frame} is
2046 omitted or @code{nil}, it applies to the selected frame's display.
2048 The list contains a vector of the following form for each font:
2050 @example
2051 [@var{family} @var{width} @var{point-size} @var{weight} @var{slant}
2052  @var{fixed-p} @var{full} @var{registry-and-encoding}]
2053 @end example
2055 The first five elements correspond to face attributes; if you
2056 specify these attributes for a face, it will use this font.
2058 The last three elements give additional information about the font.
2059 @var{fixed-p} is non-nil if the font is fixed-pitch.  @var{full} is the
2060 full name of the font, and @var{registry-and-encoding} is a string
2061 giving the registry and encoding of the font.
2063 The result list is sorted according to the current face font sort order.
2064 @end defun
2066 @defun x-font-family-list &optional frame
2067 @tindex x-font-family-list
2068 This function returns a list of the font families available for
2069 @var{frame}'s display.  If @var{frame} is omitted or @code{nil}, it
2070 describes the selected frame's display.
2072 The value is a list of elements of this form:
2074 @example
2075 (@var{family} . @var{fixed-p})
2076 @end example
2078 @noindent
2079 Here @var{family} is a font family, and @var{fixed-p} is
2080 non-@code{nil} if fonts of that family are fixed-pitch.
2081 @end defun
2083 @defvar font-list-limit
2084 @tindex font-list-limit
2085 This variable specifies maximum number of fonts to consider in font
2086 matching.  The function @code{x-family-fonts} will not return more than
2087 that many fonts, and font selection will consider only that many fonts
2088 when searching a matching font for face attributes.  The default is
2089 currently 100.
2090 @end defvar
2092 @node Fontsets
2093 @subsection Fontsets
2095   A @dfn{fontset} is a list of fonts, each assigned to a range of
2096 character codes.  An individual font cannot display the whole range of
2097 characters that Emacs supports, but a fontset can.  Fontsets have names,
2098 just as fonts do, and you can use a fontset name in place of a font name
2099 when you specify the ``font'' for a frame or a face.  Here is
2100 information about defining a fontset under Lisp program control.
2102 @defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
2103 This function defines a new fontset according to the specification
2104 string @var{fontset-spec}.  The string should have this format:
2106 @smallexample
2107 @var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
2108 @end smallexample
2110 @noindent
2111 Whitespace characters before and after the commas are ignored.
2113 The first part of the string, @var{fontpattern}, should have the form of
2114 a standard X font name, except that the last two fields should be
2115 @samp{fontset-@var{alias}}.
2117 The new fontset has two names, one long and one short.  The long name is
2118 @var{fontpattern} in its entirety.  The short name is
2119 @samp{fontset-@var{alias}}.  You can refer to the fontset by either
2120 name.  If a fontset with the same name already exists, an error is
2121 signaled, unless @var{noerror} is non-@code{nil}, in which case this
2122 function does nothing.
2124 If optional argument @var{style-variant-p} is non-@code{nil}, that says
2125 to create bold, italic and bold-italic variants of the fontset as well.
2126 These variant fontsets do not have a short name, only a long one, which
2127 is made by altering @var{fontpattern} to indicate the bold or italic
2128 status.
2130 The specification string also says which fonts to use in the fontset.
2131 See below for the details.
2132 @end defun
2134   The construct @samp{@var{charset}:@var{font}} specifies which font to
2135 use (in this fontset) for one particular character set.  Here,
2136 @var{charset} is the name of a character set, and @var{font} is the font
2137 to use for that character set.  You can use this construct any number of
2138 times in the specification string.
2140   For the remaining character sets, those that you don't specify
2141 explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
2142 @samp{fontset-@var{alias}} with a value that names one character set.
2143 For the @sc{ascii} character set, @samp{fontset-@var{alias}} is replaced
2144 with @samp{ISO8859-1}.
2146   In addition, when several consecutive fields are wildcards, Emacs
2147 collapses them into a single wildcard.  This is to prevent use of
2148 auto-scaled fonts.  Fonts made by scaling larger fonts are not usable
2149 for editing, and scaling a smaller font is not useful because it is
2150 better to use the smaller font in its own size, which Emacs does.
2152   Thus if @var{fontpattern} is this,
2154 @example
2155 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
2156 @end example
2158 @noindent
2159 the font specification for @sc{ascii} characters would be this:
2161 @example
2162 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
2163 @end example
2165 @noindent
2166 and the font specification for Chinese GB2312 characters would be this:
2168 @example
2169 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
2170 @end example
2172   You may not have any Chinese font matching the above font
2173 specification.  Most X distributions include only Chinese fonts that
2174 have @samp{song ti} or @samp{fangsong ti} in the @var{family} field.  In
2175 such a case, @samp{Fontset-@var{n}} can be specified as below:
2177 @smallexample
2178 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
2179         chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
2180 @end smallexample
2182 @noindent
2183 Then, the font specifications for all but Chinese GB2312 characters have
2184 @samp{fixed} in the @var{family} field, and the font specification for
2185 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
2186 field.
2188 @node Display Property
2189 @section The @code{display} Property
2190 @cindex display specification
2191 @kindex display @r{(text property)}
2193   The @code{display} text property (or overlay property) is used to
2194 insert images into text, and also control other aspects of how text
2195 displays.  These features are available starting in Emacs 21.  The value
2196 of the @code{display} property should be a display specification, or a
2197 list or vector containing several display specifications.  The rest of
2198 this section describes several kinds of display specifications and what
2199 they mean.
2201 @menu
2202 * Specified Space::     Displaying one space with a specified width.
2203 * Other Display Specs:: Displaying an image; magnifying text; moving it
2204                           up or down on the page; adjusting the width 
2205                           of spaces within text.
2206 * Display Margins::     Displaying text or images to the side of the main text.
2207 * Conditional Display:: Making any of the above features conditional
2208                           depending on some Lisp expression.
2209 @end menu
2211 @node Specified Space
2212 @subsection Specified Spaces
2213 @cindex spaces, specified height or width
2214 @cindex specified spaces
2215 @cindex variable-width spaces
2217   To display a space of specified width and/or height, use a display
2218 specification of the form @code{(space . @var{props})}, where
2219 @var{props} is a property list (a list of alternating properties and
2220 values).  You can put this property on one or more consecutive
2221 characters; a space of the specified height and width is displayed in
2222 place of @emph{all} of those characters.  These are the properties you
2223 can use to specify the weight of the space:
2225 @table @code
2226 @item :width @var{width}
2227 Specifies that the space width should be @var{width} times the normal
2228 character width.  @var{width} can be an integer or floating point
2229 number.
2231 @item :relative-width @var{factor}
2232 Specifies that the width of the stretch should be computed from the
2233 first character in the group of consecutive characters that have the
2234 same @code{display} property.  The space width is the width of that
2235 character, multiplied by @var{factor}.
2237 @item :align-to @var{hpos}
2238 Specifies that the space should be wide enough to reach @var{hpos}.  The
2239 value @var{hpos} is measured in units of the normal character width.  It
2240 may be an interer or a floating point number.
2241 @end table
2243   Exactly one of the above properties should be used.  You can also
2244 specify the height of the space, with other properties:
2246 @table @code
2247 @item :height @var{height}
2248 Specifies the height of the space, as @var{height},
2249 measured in terms of the normal line height.
2251 @item :relative-height @var{factor}
2252 Specifies the height of the space, multiplying the ordinary height
2253 of the text having this display specification by @var{factor}.
2255 @item :ascent @var{ascent}
2256 Specifies that @var{ascent} percent of the height of the space should be
2257 considered as the ascent of the space---that is, the part above the
2258 baseline.  The value of @var{ascent} must be a non-negative number no
2259 greater than 100.
2260 @end table
2262   You should not use both @code{:height} and @code{:relative-height}
2263 together.
2265 @node Other Display Specs
2266 @subsection Other Display Specifications
2268 @table @code
2269 @item (image . @var{image-props})
2270 This is in fact an image descriptor (@pxref{Images}).  When used as a
2271 display specification, it means to display the image instead of the text
2272 that has the display specification.
2274 @item ((margin nil) @var{string})
2275 @itemx @var{string}
2276 A display specification of this form means to display @var{string}
2277 instead of the text that has the display specification, at the same
2278 position as that text.  This is a special case of marginal display
2279 (@pxref{Display Margins}).
2281 @item (space-width @var{factor})
2282 This display specification affects all the space characters within the
2283 text that has the specification.  It displays all of these spaces
2284 @var{factor} times as wide as normal.  The element @var{factor} should
2285 be an integer or float.  Characters other than spaces are not affected
2286 at all; in particular, this has no effect on tab characters.
2288 @item (height @var{height})
2289 This display specification makes the text taller or shorter.
2290 Here are the possibilities for @var{height}:
2292 @table @asis
2293 @item @code{(+ @var{n})}
2294 This means to use a font that is @var{n} steps larger.  A ``step'' is
2295 defined by the set of available fonts---specifically, those that match
2296 what was otherwise specified for this text, in all attributes except
2297 height.  Each size for which a suitable font is available counts as
2298 another step.  @var{n} should be an integer.
2300 @item @code{(- @var{n})}
2301 This means to use a font that is @var{n} steps smaller.
2303 @item a number, @var{factor}
2304 A number, @var{factor}, means to use a font that is @var{factor} times
2305 as tall as the default font.
2307 @item a symbol, @var{function}
2308 A symbol is a function to compute the height.  It is called with the
2309 current height as argument, and should return the new height to use.
2311 @item anything else, @var{form}
2312 If the @var{height} value doesn't fit the previous possibilities, it is
2313 a form.  Emacs evaluates it to get the new height, with the symbol
2314 @code{height} bound to the current specified font height.
2315 @end table
2317 @item (raise @var{factor})
2318 This kind of display specification raises or lowers the text
2319 it applies to, relative to the baseline of the line.
2321 @var{factor} must be a number, which is interpreted as a multiple of the
2322 height of the affected text.  If it is positive, that means to display
2323 the characters raised.  If it is negative, that means to display them
2324 lower down.
2326 If the text also has a @code{height} display specification, that does
2327 not affect the amount of raising or lowering, which is based on the
2328 faces used for the text.
2329 @end table
2331 @node Display Margins
2332 @subsection Displaying in the Margins
2333 @cindex display margins
2334 @cindex margins, display
2336   A buffer can have blank areas called @dfn{display margins} on the left
2337 and on the right.  Ordinary text never appears in these areas, but you
2338 can put things into the display margins using the @code{display}
2339 property.
2341   To put text in the left or right display margin of the window, use a
2342 display specification of the form @code{(margin right-margin)} or
2343 @code{(margin left-margin)} on it.  To put an image in a display margin,
2344 use that display specification along with the display specification for
2345 the image.
2347   Before the display margins can display anything, you must give
2348 them a nonzero width.  The usual way to do that is to set these
2349 variables:
2351 @defvar left-margin-width
2352 @tindex left-margin-width
2353 This variable specifies the width of the left margin.
2354 It is buffer-local in all buffers.
2355 @end defvar
2357 @defvar right-margin-width
2358 @tindex right-margin-width
2359 This variable specifies the width of the right margin.
2360 It is buffer-local in all buffers.
2361 @end defvar
2363   Setting these variables does not immediately affect the window.  These
2364 variables are checked when a new buffer is displayed in the window.
2365 Thus, you can make changes take effect by calling
2366 @code{set-window-buffer}.
2368   You can also set the margin widths immediately.
2370 @defun set-window-margins window left right
2371 @tindex set-window-margins
2372 This function specifies the margin widths for window @var{window}.
2373 The argument @var{left} controls the left margin and 
2374 @var{right} controls the right margin.
2375 @end defun
2377 @defun window-margins &optional window
2378 @tindex window-margins
2379 This function returns the left and right margins of @var{window}
2380 as a cons cell of the form @code{(@var{left} . @var{right})}.
2381 If @var{window} is @code{nil}, the selected window is used.
2382 @end defun
2384 @node Conditional Display
2385 @subsection Conditional Display Specifications
2386 @cindex conditional display specifications
2388   You can make any display specification conditional.  To do that,
2389 package it in another list of the form @code{(when @var{condition} .
2390 @var{spec})}.  Then the specification @var{spec} applies only when
2391 @var{condition} evaluates to a non-@code{nil} value.  During the
2392 evaluation, point is temporarily set at the end position of the text
2393 having this conditional display specification.
2395 @node Images
2396 @section Images
2397 @cindex images in buffers
2399   To display an image in an Emacs buffer, you must first create an image
2400 descriptor, then use it as a display specifier in the @code{display}
2401 property of text that is displayed (@pxref{Display Property}).  Like the
2402 @code{display} property, this feature is available starting in Emacs 21.
2404   Emacs can display a number of different image formats; some of them
2405 are supported only if particular support libraries are installed on your
2406 machine.  The supported image formats include XBM, XPM (needing the
2407 libraries @code{libXpm} version 3.4k and @code{libz}), GIF (needing
2408 @code{libungif} 4.1.0), Postscript, PBM, JPEG (needing the
2409 @code{libjpeg} library version v6a), TIFF (needing @code{libtiff} v3.4),
2410 and PNG (needing @code{libpng} 1.0.2).
2412   You specify one of these formats with an image type symbol.  The image
2413 type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
2414 @code{pbm}, @code{jpeg}, @code{tiff}, and @code{png}.
2416 @defvar image-types
2417 This variable contains a list of those image type symbols that are
2418 supported in the current configuration.
2419 @end defvar
2421 @menu
2422 * Image Descriptors::   How to specify an image for use in @code{:display}.
2423 * XBM Images::          Special features for XBM format.
2424 * XPM Images::          Special features for XPM format.
2425 * GIF Images::          Special features for GIF format.
2426 * Postscript Images::   Special features for Postscript format.
2427 * Other Image Types::   Various other formats are supported.
2428 * Defining Images::     Convenient ways to define an image for later use.
2429 * Showing Images::      Convenient ways to display an image once it is defined.
2430 * Image Cache::         Internal mechanisms of image display.
2431 @end menu
2433 @node Image Descriptors
2434 @subsection Image Descriptors
2435 @cindex image descriptor
2437   An image description is a list of the form @code{(image
2438 . @var{props})}, where @var{props} is a property list containing
2439 alternating keyword symbols (symbols whose names start with a colon) and
2440 their values.  You can use any Lisp object as a property, but the only
2441 properties that have any special meaning are certain symbols, all of
2442 them keywords.
2444   Every image descriptor must contain the property @code{:type
2445 @var{type}} to specify the format of the image.  The value of @var{type}
2446 should be an image type symbol; for example, @code{xpm} for an image in
2447 XPM format.
2449   Here is a list of other properties that are meaningful for all image
2450 types:
2452 @table @code
2453 @item :ascent @var{ascent}
2454 The @code{:ascent} property specifies the amount of the image's
2455 height to use for its ascent---that is, the part above the baseline.
2456 The value, @var{ascent}, must be a number in the range 0 to 100, or
2457 the symbol @code{center}.
2459 If @var{ascent} is a number, that percentage of the image's height is
2460 used for its ascent.
2462 If @var{ascent} is @code{center}, the image is vertically centered
2463 around a centerline which would be the vertical centerline of text drawn
2464 at the position of the image, in the manner specified by the text
2465 properties and overlays that apply to the image.
2467 If this property is omitted, it defaults to 50.
2469 @item :margin @var{margin}
2470 The @code{:margin} property specifies how many pixels to add as an
2471 extra margin around the image.  The value, @var{margin}, must be a a
2472 non-negative number, or a pair @code{(@var{x} . @var{y})} of such
2473 numbers.  If it is a pair, @var{x} specifies how many pixels to add
2474 horizontally, and @var{y} specifies how many pixels to add vertically.
2475 If @code{:margin} is not specified, the default is zero.
2477 @item :relief @var{relief}
2478 The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle
2479 around the image.  The value, @var{relief}, specifies the width of the
2480 shadow lines, in pixels.  If @var{relief} is negative, shadows are drawn
2481 so that the image appears as a pressed button; otherwise, it appears as
2482 an unpressed button.
2484 @item :conversion @var{algorithm}
2485 The @code{:conversion} property, if non-@code{nil}, specifies a
2486 conversion algorithm that should be applied to the image before it is
2487 displayed; the value, @var{algorithm}, specifies which algorithm.
2489 @table @code
2490 @item laplace
2491 @itemx emboss
2492 Specifies the Laplace edge detection algorithm, which blurs out small
2493 differences in color while highlighting larger differences.  People
2494 sometimes consider this useful for displaying the image for a
2495 ``disabled'' button.
2497 @item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
2498 Specifies a general edge-detection algorithm.  @var{matrix} must be
2499 either a nine-element list or a nine-element vector of numbers.  A pixel
2500 at position @math{x/y} in the transformed image is computed from
2501 original pixels around that position.  @var{matrix} specifies, for each
2502 pixel in the neighborhood of @math{x/y}, a factor with which that pixel
2503 will influence the transformed pixel; element @math{0} specifies the
2504 factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for
2505 the pixel at @math{x/y-1} etc., as shown below:
2506 @iftex
2507 @tex
2508 $$\pmatrix{x-1/y-1 & x/y-1  & x+1/y-1 \cr
2509    x-1/y  &   x/y &    x+1/y \cr
2510    x-1/y+1&   x/y+1 &  x+1/y+1 \cr}$$
2511 @end tex
2512 @end iftex
2513 @ifnottex
2514 @display
2515   (x-1/y-1  x/y-1  x+1/y-1
2516    x-1/y    x/y    x+1/y
2517    x-1/y+1  x/y+1  x+1/y+1)
2518 @end display
2519 @end ifnottex
2521 The resulting pixel is computed from the color intensity of the color
2522 resulting from summing up the RGB values of surrounding pixels,
2523 multiplied by the specified factors, and dividing that sum by the sum
2524 of the factors' absolute values.
2526 Laplace edge-detection currently uses a matrix of
2527 @iftex
2528 @tex
2529 $$\pmatrix{1 & 0 & 0 \cr
2530    0&  0 &  0 \cr
2531    9 & 9 & -1 \cr}$$
2532 @end tex
2533 @end iftex
2534 @ifnottex
2535 @display
2536   (1  0  0
2537    0  0  0
2538    9  9 -1)
2539 @end display
2540 @end ifnottex
2542 Emboss edge-detection uses a matrix of
2543 @iftex
2544 @tex
2545 $$\pmatrix{ 2 & -1 &  0 \cr
2546    -1 &  0 &  1 \cr
2547     0  & 1 & -2 \cr}$$
2548 @end tex
2549 @end iftex
2550 @ifnottex
2551 @display
2552   ( 2 -1  0
2553    -1  0  1
2554     0  1 -2)
2555 @end display
2556 @end ifnottex
2558 @item disabled
2559 Specifies transforming the image so that it looks ``disabled''.
2560 @end table
2562 @item :mask @var{mask}
2563 If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build
2564 a clipping mask for the image, so that the background of a frame is
2565 visible behind the image.  If @var{bg} is not specified, or if @var{bg}
2566 is @code{t}, determine the background color of the image by looking at
2567 the four corners of the image, assuming the most frequently occurring
2568 color from the corners is the background color of the image.  Otherwise,
2569 @var{bg} must be a list @code{(@var{red} @var{green} @var{blue})}
2570 specifying the color to assume for the background of the image.
2572 If @var{mask} is nil, remove a mask from the image, if it has one.  Images
2573 in some formats include a mask which can be removed by specifying
2574 @code{:mask nil}.
2576 @item :file @var{file}
2577 The @code{:file} property specifies to load the image from file
2578 @var{file}.  If @var{file} is not an absolute file name, it is expanded
2579 in @code{data-directory}.
2581 @item :data @var{data}
2582 The @code{:data} property specifies the actual contents of the image.
2583 Each image must use either @code{:data} or @code{:file}, but not both.
2584 For most image types, the value of the @code{:data} property should be a
2585 string containing the image data; we recommend using a unibyte string.
2587 Before using @code{:data}, look for further information in the section
2588 below describing the specific image format.  For some image types,
2589 @code{:data} may not be supported; for some, it allows other data types;
2590 for some, @code{:data} alone is not enough, so you need to use other
2591 image properties along with @code{:data}.
2592 @end table
2594 @defun image-mask-p spec &optional frame
2595 @tindex image-mask-p
2596 This function returns @code{t} if image @var{spec} has a mask bitmap.
2597 @var{frame} is the frame on which the image will be displayed.
2598 @var{frame} @code{nil} or omitted means to use the selected frame.
2599 @end defun
2601 @node XBM Images
2602 @subsection XBM Images
2603 @cindex XBM
2605   To use XBM format, specify @code{xbm} as the image type.  This image
2606 format doesn't require an external library, so images of this type are
2607 always supported.
2609   Additional image properties supported for the @code{xbm} image type are:
2611 @table @code
2612 @item :foreground @var{foreground}
2613 The value, @var{foreground}, should be a string specifying the image
2614 foreground color.  This color is used for each pixel in the XBM that is
2615 1.  The default is the frame's foreground color.
2617 @item :background @var{background}
2618 The value, @var{background}, should be a string specifying the image
2619 background color.  This color is used for each pixel in the XBM that is
2620 0.  The default is the frame's background color.
2621 @end table
2623   If you specify an XBM image using data within Emacs instead of an
2624 external file, use the following three properties:
2626 @table @code
2627 @item :data @var{data}
2628 The value, @var{data}, specifies the contents of the image.
2629 There are three formats you can use for @var{data}:
2631 @itemize @bullet
2632 @item
2633 A vector of strings or bool-vectors, each specifying one line of the
2634 image.  Do specify @code{:height} and @code{:width}.
2636 @item
2637 A string containing the same byte sequence as an XBM file would contain.
2638 You must not specify @code{:height} and @code{:width} in this case,
2639 because omitting them is what indicates the data has the format of an
2640 XBM file.  The file contents specify the height and width of the image.
2642 @item
2643 A string or a bool-vector containing the bits of the image (plus perhaps
2644 some extra bits at the end that will not be used).  It should contain at
2645 least @var{width} * @code{height} bits.  In this case, you must specify
2646 @code{:height} and @code{:width}, both to indicate that the string
2647 contains just the bits rather than a whole XBM file, and to specify the
2648 size of the image.
2649 @end itemize
2651 @item :width @var{width}
2652 The value, @var{width}, specifies the width of the image, in pixels.
2654 @item :height @var{height}
2655 The value, @var{height}, specifies the height of the image, in pixels.
2656 @end table
2658 @node XPM Images
2659 @subsection XPM Images
2660 @cindex XPM
2662   To use XPM format, specify @code{xpm} as the image type.  The
2663 additional image property @code{:color-symbols} is also meaningful with
2664 the @code{xpm} image type:
2666 @table @code
2667 @item :color-symbols @var{symbols}
2668 The value, @var{symbols}, should be an alist whose elements have the
2669 form @code{(@var{name} . @var{color})}.  In each element, @var{name} is
2670 the name of a color as it appears in the image file, and @var{color}
2671 specifies the actual color to use for displaying that name.
2672 @end table
2674 @node GIF Images
2675 @subsection GIF Images
2676 @cindex GIF
2678   For GIF images, specify image type @code{gif}.  Because of the patents
2679 in the US covering the LZW algorithm, the continued use of GIF format is
2680 a problem for the whole Internet; to end this problem, it is a good idea
2681 for everyone, even outside the US, to stop using GIFS right away
2682 (@uref{http://www.burnallgifs.org/}).  But if you still want to use
2683 them, Emacs can display them.
2685 @table @code
2686 @item :index @var{index}
2687 You can use @code{:index} to specify one image from a GIF file that
2688 contains more than one image.  This property specifies use of image
2689 number @var{index} from the file.  An error is signaled if the GIF file
2690 doesn't contain an image with index @var{index}.
2691 @end table
2693 @ignore
2694 This could be used to implement limited support for animated GIFs.
2695 For example, the following function displays a multi-image GIF file
2696 at point-min in the current buffer, switching between sub-images
2697 every 0.1 seconds.
2699 (defun show-anim (file max)
2700   "Display multi-image GIF file FILE which contains MAX subimages."
2701   (display-anim (current-buffer) file 0 max t))
2703 (defun display-anim (buffer file idx max first-time)
2704   (when (= idx max)
2705     (setq idx 0))
2706   (let ((img (create-image file nil :image idx)))
2707     (save-excursion
2708       (set-buffer buffer)
2709       (goto-char (point-min))
2710       (unless first-time (delete-char 1))
2711       (insert-image img))
2712     (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
2713 @end ignore
2715 @node Postscript Images
2716 @subsection Postscript Images
2717 @cindex Postscript images
2719   To use Postscript for an image, specify image type @code{postscript}.
2720 This works only if you have Ghostscript installed.  You must always use
2721 these three properties:
2723 @table @code
2724 @item :pt-width @var{width}
2725 The value, @var{width}, specifies the width of the image measured in
2726 points (1/72 inch).  @var{width} must be an integer.
2728 @item :pt-height @var{height}
2729 The value, @var{height}, specifies the height of the image in points
2730 (1/72 inch).  @var{height} must be an integer.
2732 @item :bounding-box @var{box}
2733 The value, @var{box}, must be a list or vector of four integers, which
2734 specifying the bounding box of the Postscript image, analogous to the
2735 @samp{BoundingBox} comment found in Postscript files.
2737 @example
2738 %%BoundingBox: 22 171 567 738
2739 @end example
2740 @end table
2742   Displaying Postscript images from Lisp data is not currently
2743 implemented, but it may be implemented by the time you read this.
2744 See the @file{etc/NEWS} file to make sure.
2746 @node Other Image Types
2747 @subsection Other Image Types
2748 @cindex PBM
2750   For PBM images, specify image type @code{pbm}.  Color, gray-scale and
2751 monochromatic images are supported.   For mono PBM images, two additional
2752 image properties are supported.
2754 @table @code
2755 @item :foreground @var{foreground}
2756 The value, @var{foreground}, should be a string specifying the image
2757 foreground color.  This color is used for each pixel in the XBM that is
2758 1.  The default is the frame's foreground color.
2760 @item :background @var{background}
2761 The value, @var{background}, should be a string specifying the image
2762 background color.  This color is used for each pixel in the XBM that is
2763 0.  The default is the frame's background color.
2764 @end table
2766   For JPEG images, specify image type @code{jpeg}.
2768   For TIFF images, specify image type @code{tiff}.
2770   For PNG images, specify image type @code{png}.
2772 @node Defining Images
2773 @subsection Defining Images
2775   The functions @code{create-image}, @code{defimage} and
2776 @code{find-image} provide convenient ways to create image descriptors.
2778 @defun create-image file &optional type &rest props
2779 @tindex create-image
2780 This function creates and returns an image descriptor which uses the
2781 data in @var{file}.
2783 The optional argument @var{type} is a symbol specifying the image type.
2784 If @var{type} is omitted or @code{nil}, @code{create-image} tries to
2785 determine the image type from the file's first few bytes, or else
2786 from the file's name.
2788 The remaining arguments, @var{props}, specify additional image
2789 properties---for example,
2791 @example
2792 (create-image "foo.xpm" 'xpm :heuristic-mask t)
2793 @end example
2795 The function returns @code{nil} if images of this type are not
2796 supported.  Otherwise it returns an image descriptor.
2797 @end defun
2799 @defmac defimage variable doc &rest specs
2800 @tindex defimage
2801 This macro defines @var{variable} as an image name.  The second argument,
2802 @var{doc}, is an optional documentation string.  The remaining
2803 arguments, @var{specs}, specify alternative ways to display the image.
2805 Each argument in @var{specs} has the form of a property list, and each
2806 one should specify at least the @code{:type} property and the
2807 @code{:file} property.  Here is an example:
2809 @example
2810 (defimage test-image
2811   '((:type xpm :file "~/test1.xpm")
2812     (:type xbm :file "~/test1.xbm")))
2813 @end example
2815 @code{defimage} tests each argument, one by one, to see if it is
2816 usable---that is, if the type is supported and the file exists.  The
2817 first usable argument is used to make an image descriptor which is
2818 stored in the variable @var{variable}.
2820 If none of the alternatives will work, then @var{variable} is defined
2821 as @code{nil}.
2822 @end defmac
2824 @defun find-image specs
2825 @tindex find-image
2826 This function provides a convenient way to find an image satisfying one
2827 of a list of image specifications @var{specs}.
2829 Each specification in @var{specs} is a property list with contents
2830 depending on image type.  All specifications must at least contain the
2831 properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
2832 or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
2833 the image type, e.g.@: @code{xbm}, @var{file} is the file to load the
2834 image from, and @var{data} is a string containing the actual image data.
2835 The first specification in the list whose @var{type} is supported, and
2836 @var{file} exists, is used to construct the image specification to be
2837 returned.  If no specification is satisfied, @code{nil} is returned.
2839 The image is looked for first on @code{load-path} and then in
2840 @code{data-directory}.
2841 @end defun
2843 @node Showing Images
2844 @subsection Showing Images
2846   You can use an image descriptor by setting up the @code{display}
2847 property yourself, but it is easier to use the functions in this
2848 section.
2850 @defun insert-image image &optional string area
2851 This function inserts @var{image} in the current buffer at point.  The
2852 value @var{image} should be an image descriptor; it could be a value
2853 returned by @code{create-image}, or the value of a symbol defined with
2854 @code{defimage}.  The argument @var{string} specifies the text to put in
2855 the buffer to hold the image.
2857 The argument @var{area} specifies whether to put the image in a margin.
2858 If it is @code{left-margin}, the image appears in the left margin;
2859 @code{right-margin} specifies the right margin.  If @var{area} is
2860 @code{nil} or omitted, the image is displayed at point within the
2861 buffer's text.
2863 Internally, this function inserts @var{string} in the buffer, and gives
2864 it a @code{display} property which specifies @var{image}.  @xref{Display
2865 Property}.
2866 @end defun
2868 @defun put-image image pos &optional string area
2869 This function puts image @var{image} in front of @var{pos} in the
2870 current buffer.  The argument @var{pos} should be an integer or a
2871 marker.  It specifies the buffer position where the image should appear.
2872 The argument @var{string} specifies the text that should hold the image
2873 as an alternative to the default.
2875 The argument @var{image} must be an image descriptor, perhaps returned
2876 by @code{create-image} or stored by @code{defimage}.
2878 The argument @var{area} specifies whether to put the image in a margin.
2879 If it is @code{left-margin}, the image appears in the left margin;
2880 @code{right-margin} specifies the right margin.  If @var{area} is
2881 @code{nil} or omitted, the image is displayed at point within the
2882 buffer's text.
2884 Internally, this function creates an overlay, and gives it a
2885 @code{before-string} property containing text that has a @code{display}
2886 property whose value is the image.  (Whew!)
2887 @end defun
2889 @defun remove-images start end &optional buffer
2890 This function removes images in @var{buffer} between positions
2891 @var{start} and @var{end}.  If @var{buffer} is omitted or @code{nil},
2892 images are removed from the current buffer.
2894 This removes only images that were put into @var{buffer} the way
2895 @code{put-image} does it, not images that were inserted with
2896 @code{insert-image} or in other ways.
2897 @end defun
2899 @defun image-size spec &optional pixels frame
2900 @tindex image-size
2901 This function returns the size of an image as a pair
2902 @w{@code{(@var{width} . @var{height})}}.  @var{spec} is an image
2903 specification.  @var{pixels} non-nil means return sizes measured in
2904 pixels, otherwise return sizes measured in canonical character units
2905 (fractions of the width/height of the frame's default font).
2906 @var{frame} is the frame on which the image will be displayed.
2907 @var{frame} null or omitted means use the selected frame.
2908 @end defun
2910 @node Image Cache
2911 @subsection Image Cache
2913   Emacs stores images in an image cache when it displays them, so it can
2914 display them again more efficiently.  It removes an image from the cache
2915 when it hasn't been displayed for a specified period of time.
2917 When an image is looked up in the cache, its specification is compared
2918 with cached image specifications using @code{equal}.  This means that
2919 all images with equal specifications share the same image in the cache.
2921 @defvar image-cache-eviction-delay
2922 @tindex image-cache-eviction-delay
2923 This variable specifies the number of seconds an image can remain in the
2924 cache without being displayed.  When an image is not displayed for this
2925 length of time, Emacs removes it from the image cache.
2927 If the value is @code{nil}, Emacs does not remove images from the cache
2928 except when you explicitly clear it.  This mode can be useful for
2929 debugging.
2930 @end defvar
2932 @defun clear-image-cache &optional frame
2933 @tindex clear-image-cache
2934 This function clears the image cache.  If @var{frame} is non-@code{nil},
2935 only the cache for that frame is cleared.  Otherwise all frames' caches
2936 are cleared.
2937 @end defun
2939 @node Blinking
2940 @section Blinking Parentheses
2941 @cindex parenthesis matching
2942 @cindex blinking
2943 @cindex balancing parentheses
2944 @cindex close parenthesis
2946   This section describes the mechanism by which Emacs shows a matching
2947 open parenthesis when the user inserts a close parenthesis.
2949 @defvar blink-paren-function
2950 The value of this variable should be a function (of no arguments) to
2951 be called whenever a character with close parenthesis syntax is inserted.
2952 The value of @code{blink-paren-function} may be @code{nil}, in which
2953 case nothing is done.
2954 @end defvar
2956 @defopt blink-matching-paren
2957 If this variable is @code{nil}, then @code{blink-matching-open} does
2958 nothing.
2959 @end defopt
2961 @defopt blink-matching-paren-distance
2962 This variable specifies the maximum distance to scan for a matching
2963 parenthesis before giving up.
2964 @end defopt
2966 @defopt blink-matching-delay
2967 This variable specifies the number of seconds for the cursor to remain
2968 at the matching parenthesis.  A fraction of a second often gives
2969 good results, but the default is 1, which works on all systems.
2970 @end defopt
2972 @deffn Command blink-matching-open
2973 This function is the default value of @code{blink-paren-function}.  It
2974 assumes that point follows a character with close parenthesis syntax and
2975 moves the cursor momentarily to the matching opening character.  If that
2976 character is not already on the screen, it displays the character's
2977 context in the echo area.  To avoid long delays, this function does not
2978 search farther than @code{blink-matching-paren-distance} characters.
2980 Here is an example of calling this function explicitly.
2982 @smallexample
2983 @group
2984 (defun interactive-blink-matching-open ()
2985 @c Do not break this line! -- rms.
2986 @c The first line of a doc string
2987 @c must stand alone.
2988   "Indicate momentarily the start of sexp before point."
2989   (interactive)
2990 @end group
2991 @group
2992   (let ((blink-matching-paren-distance
2993          (buffer-size))
2994         (blink-matching-paren t))
2995     (blink-matching-open)))
2996 @end group
2997 @end smallexample
2998 @end deffn
3000 @node Inverse Video
3001 @section Inverse Video
3002 @cindex Inverse Video
3004 @defopt inverse-video
3005 @cindex highlighting
3006 This variable controls whether Emacs uses inverse video for all text
3007 on the screen.  Non-@code{nil} means yes, @code{nil} means no.  The
3008 default is @code{nil}.
3009 @end defopt
3011 @defopt mode-line-inverse-video
3012 This variable controls the use of inverse video for mode lines and menu
3013 bars.  If it is non-@code{nil}, then these lines are displayed in
3014 inverse video.  Otherwise, these lines are displayed normally, just like
3015 other text.  The default is @code{t}.
3017 For window frames, this feature actually applies the face named
3018 @code{mode-line}; that face is normally set up as the inverse of the
3019 default face, unless you change it.
3020 @end defopt
3022 @node Usual Display
3023 @section Usual Display Conventions
3025   The usual display conventions define how to display each character
3026 code.  You can override these conventions by setting up a display table
3027 (@pxref{Display Tables}).  Here are the usual display conventions:
3029 @itemize @bullet
3030 @item
3031 Character codes 32 through 126 map to glyph codes 32 through 126.
3032 Normally this means they display as themselves.
3034 @item
3035 Character code 9 is a horizontal tab.  It displays as whitespace
3036 up to a position determined by @code{tab-width}.
3038 @item
3039 Character code 10 is a newline.
3041 @item
3042 All other codes in the range 0 through 31, and code 127, display in one
3043 of two ways according to the value of @code{ctl-arrow}.  If it is
3044 non-@code{nil}, these codes map to sequences of two glyphs, where the
3045 first glyph is the @sc{ascii} code for @samp{^}.  (A display table can
3046 specify a glyph to use instead of @samp{^}.)  Otherwise, these codes map
3047 just like the codes in the range 128 to 255.
3049 On MS-DOS terminals, Emacs arranges by default for the character code
3050 127 to be mapped to the glyph code 127, which normally displays as an
3051 empty polygon.  This glyph is used to display non-@sc{ascii} characters
3052 that the MS-DOS terminal doesn't support.  @xref{MS-DOS and MULE,,,
3053 emacs, The GNU Emacs Manual}.
3055 @item
3056 Character codes 128 through 255 map to sequences of four glyphs, where
3057 the first glyph is the @sc{ascii} code for @samp{\}, and the others are
3058 digit characters representing the character code in octal.  (A display
3059 table can specify a glyph to use instead of @samp{\}.)
3061 @item
3062 Multibyte character codes above 256 are displayed as themselves, or as a
3063 question mark or empty box if the terminal cannot display that
3064 character.
3065 @end itemize
3067   The usual display conventions apply even when there is a display
3068 table, for any character whose entry in the active display table is
3069 @code{nil}.  Thus, when you set up a display table, you need only
3070 specify the characters for which you want special behavior.
3072   These display rules apply to carriage return (character code 13), when
3073 it appears in the buffer.  But that character may not appear in the
3074 buffer where you expect it, if it was eliminated as part of end-of-line
3075 conversion (@pxref{Coding System Basics}).
3077   These variables affect the way certain characters are displayed on the
3078 screen.  Since they change the number of columns the characters occupy,
3079 they also affect the indentation functions.  These variables also affect
3080 how the mode line is displayed; if you want to force redisplay of the
3081 mode line using the new values, call the function
3082 @code{force-mode-line-update} (@pxref{Mode Line Format}).
3084 @defopt ctl-arrow
3085 @cindex control characters in display
3086 This buffer-local variable controls how control characters are
3087 displayed.  If it is non-@code{nil}, they are displayed as a caret
3088 followed by the character: @samp{^A}.  If it is @code{nil}, they are
3089 displayed as a backslash followed by three octal digits: @samp{\001}.
3090 @end defopt
3092 @c Following may have overfull hbox.
3093 @defvar default-ctl-arrow
3094 The value of this variable is the default value for @code{ctl-arrow} in
3095 buffers that do not override it.  @xref{Default Value}.
3096 @end defvar
3098 @defopt indicate-empty-lines
3099 @tindex indicate-empty-lines
3100 When this is non-@code{nil}, Emacs displays a special glyph in
3101 each empty line at the end of the buffer, on terminals that
3102 support it (window systems).
3103 @end defopt
3105 @defopt tab-width
3106 The value of this variable is the spacing between tab stops used for
3107 displaying tab characters in Emacs buffers.  The value is in units of
3108 columns, and the default is 8.  Note that this feature is completely
3109 independent of the user-settable tab stops used by the command
3110 @code{tab-to-tab-stop}.  @xref{Indent Tabs}.
3111 @end defopt
3113 @node Display Tables
3114 @section Display Tables
3116 @cindex display table
3117 You can use the @dfn{display table} feature to control how all possible
3118 character codes display on the screen.  This is useful for displaying
3119 European languages that have letters not in the @sc{ascii} character
3120 set.
3122 The display table maps each character code into a sequence of
3123 @dfn{glyphs}, each glyph being a graphic that takes up one character
3124 position on the screen.  You can also define how to display each glyph
3125 on your terminal, using the @dfn{glyph table}.
3127 Display tables affect how the mode line is displayed; if you want to
3128 force redisplay of the mode line using a new display table, call
3129 @code{force-mode-line-update} (@pxref{Mode Line Format}).
3131 @menu
3132 * Display Table Format::        What a display table consists of.
3133 * Active Display Table::        How Emacs selects a display table to use.
3134 * Glyphs::                      How to define a glyph, and what glyphs mean.
3135 @end menu
3137 @node Display Table Format
3138 @subsection Display Table Format
3140   A display table is actually a char-table (@pxref{Char-Tables}) with
3141 @code{display-table} as its subtype.
3143 @defun make-display-table
3144 This creates and returns a display table.  The table initially has
3145 @code{nil} in all elements.
3146 @end defun
3148   The ordinary elements of the display table are indexed by character
3149 codes; the element at index @var{c} says how to display the character
3150 code @var{c}.  The value should be @code{nil} or a vector of glyph
3151 values (@pxref{Glyphs}).  If an element is @code{nil}, it says to
3152 display that character according to the usual display conventions
3153 (@pxref{Usual Display}).
3155   If you use the display table to change the display of newline
3156 characters, the whole buffer will be displayed as one long ``line.''
3158   The display table also has six ``extra slots'' which serve special
3159 purposes.  Here is a table of their meanings; @code{nil} in any slot
3160 means to use the default for that slot, as stated below.
3162 @table @asis
3163 @item 0
3164 The glyph for the end of a truncated screen line (the default for this
3165 is @samp{$}).  @xref{Glyphs}.  Newer Emacs versions, on some platforms,
3166 display arrows to indicate truncation---the display table has no effect
3167 in these situations.
3168 @item 1
3169 The glyph for the end of a continued line (the default is @samp{\}).
3170 Newer Emacs versions, on some platforms, display curved arrows to
3171 indicate truncation---the display table has no effect in these
3172 situations.
3173 @item 2
3174 The glyph for indicating a character displayed as an octal character
3175 code (the default is @samp{\}).
3176 @item 3
3177 The glyph for indicating a control character (the default is @samp{^}).
3178 @item 4
3179 A vector of glyphs for indicating the presence of invisible lines (the
3180 default is @samp{...}).  @xref{Selective Display}.
3181 @item 5
3182 The glyph used to draw the border between side-by-side windows (the
3183 default is @samp{|}).  @xref{Splitting Windows}.  This takes effect only
3184 when there are no scroll bars; if scroll bars are supported and in use,
3185 a scroll bar separates the two windows.
3186 @end table
3188   For example, here is how to construct a display table that mimics the
3189 effect of setting @code{ctl-arrow} to a non-@code{nil} value:
3191 @example
3192 (setq disptab (make-display-table))
3193 (let ((i 0))
3194   (while (< i 32)
3195     (or (= i ?\t) (= i ?\n)
3196         (aset disptab i (vector ?^ (+ i 64))))
3197     (setq i (1+ i)))
3198   (aset disptab 127 (vector ?^ ??)))
3199 @end example
3201 @defun display-table-slot display-table slot
3202 This function returns the value of the extra slot @var{slot} of
3203 @var{display-table}.  The argument @var{slot} may be a number from 0 to
3204 5 inclusive, or a slot name (symbol).  Valid symbols are
3205 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
3206 @code{selective-display}, and @code{vertical-border}.
3207 @end defun
3209 @defun set-display-table-slot display-table slot value
3210 This function stores @var{value} in the extra slot @var{slot} of
3211 @var{display-table}.  The argument @var{slot} may be a number from 0 to
3212 5 inclusive, or a slot name (symbol).  Valid symbols are
3213 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
3214 @code{selective-display}, and @code{vertical-border}.
3215 @end defun
3217 @defun describe-display-table display-table
3218 @tindex describe-display-table
3219 This function displays a description of the display table
3220 @var{display-table} in a help buffer.
3221 @end defun
3223 @deffn Command describe-current-display-table
3224 @tindex describe-current-display-table
3225 This command displays a description of the current display table in a
3226 help buffer.
3227 @end deffn
3229 @node Active Display Table
3230 @subsection Active Display Table
3231 @cindex active display table
3233   Each window can specify a display table, and so can each buffer.  When
3234 a buffer @var{b} is displayed in window @var{w}, display uses the
3235 display table for window @var{w} if it has one; otherwise, the display
3236 table for buffer @var{b} if it has one; otherwise, the standard display
3237 table if any.  The display table chosen is called the @dfn{active}
3238 display table.
3240 @defun window-display-table window
3241 This function returns @var{window}'s display table, or @code{nil}
3242 if @var{window} does not have an assigned display table.
3243 @end defun
3245 @defun set-window-display-table window table
3246 This function sets the display table of @var{window} to @var{table}.
3247 The argument @var{table} should be either a display table or
3248 @code{nil}.
3249 @end defun
3251 @defvar buffer-display-table
3252 This variable is automatically buffer-local in all buffers; its value in
3253 a particular buffer specifies the display table for that buffer.  If it
3254 is @code{nil}, that means the buffer does not have an assigned display
3255 table.
3256 @end defvar
3258 @defvar standard-display-table
3259 This variable's value is the default display table, used whenever a
3260 window has no display table and neither does the buffer displayed in
3261 that window.  This variable is @code{nil} by default.
3262 @end defvar
3264   If there is no display table to use for a particular window---that is,
3265 if the window specifies none, its buffer specifies none, and
3266 @code{standard-display-table} is @code{nil}---then Emacs uses the usual
3267 display conventions for all character codes in that window.  @xref{Usual
3268 Display}.
3270 A number of functions for changing the standard display table
3271 are defined in the library @file{disp-table}.
3273 @node Glyphs
3274 @subsection Glyphs
3276 @cindex glyph
3277   A @dfn{glyph} is a generalization of a character; it stands for an
3278 image that takes up a single character position on the screen.  Glyphs
3279 are represented in Lisp as integers, just as characters are.
3281 @cindex glyph table
3282   The meaning of each integer, as a glyph, is defined by the glyph
3283 table, which is the value of the variable @code{glyph-table}.
3285 @defvar glyph-table
3286 The value of this variable is the current glyph table.  It should be a
3287 vector; the @var{g}th element defines glyph code @var{g}.  If the value
3288 is @code{nil} instead of a vector, then all glyphs are simple (see
3289 below).
3290 @end defvar
3292   Here are the possible types of elements in the glyph table:
3294 @table @asis
3295 @item @var{string}
3296 Send the characters in @var{string} to the terminal to output
3297 this glyph.  This alternative is available on character terminals,
3298 but not under a window system.
3300 @item @var{integer}
3301 Define this glyph code as an alias for glyph code @var{integer}.  You
3302 can use an alias to specify a face code for the glyph; see below.
3304 @item @code{nil}
3305 This glyph is simple.  On an ordinary terminal, the glyph code mod
3306 524288 is the character to output.  In a window system, the glyph code
3307 mod 524288 is the character to output, and the glyph code divided by
3308 524288 specifies the face number (@pxref{Face Functions}) to use while
3309 outputting it.  (524288 is
3310 @ifnottex
3311 2**19.)
3312 @end ifnottex
3313 @tex
3314 $2^{19}$.)
3315 @end tex
3316 @xref{Faces}.
3317 @end table
3319   If a glyph code is greater than or equal to the length of the glyph
3320 table, that code is automatically simple.
3322 @defun create-glyph string
3323 @tindex create-glyph
3324 This function returns a newly-allocated glyph code which is set up to
3325 display by sending @var{string} to the terminal.
3326 @end defun
3328 @node Beeping
3329 @section Beeping
3330 @cindex beeping
3331 @cindex bell
3333   This section describes how to make Emacs ring the bell (or blink the
3334 screen) to attract the user's attention.  Be conservative about how
3335 often you do this; frequent bells can become irritating.  Also be
3336 careful not to use just beeping when signaling an error is more
3337 appropriate.  (@xref{Errors}.)
3339 @defun ding &optional do-not-terminate
3340 @cindex keyboard macro termination
3341 This function beeps, or flashes the screen (see @code{visible-bell} below).
3342 It also terminates any keyboard macro currently executing unless
3343 @var{do-not-terminate} is non-@code{nil}.
3344 @end defun
3346 @defun beep &optional do-not-terminate
3347 This is a synonym for @code{ding}.
3348 @end defun
3350 @defopt visible-bell
3351 This variable determines whether Emacs should flash the screen to
3352 represent a bell.  Non-@code{nil} means yes, @code{nil} means no.  This
3353 is effective on a window system, and on a character-only terminal
3354 provided the terminal's Termcap entry defines the visible bell
3355 capability (@samp{vb}).
3356 @end defopt
3358 @defvar ring-bell-function
3359 If this is non-@code{nil}, it specifies how Emacs should ``ring the
3360 bell.''  Its value should be a function of no arguments.  If this is
3361 non-@code{nil}, it takes precedence over the @code{visible-bell}
3362 variable.
3363 @end defvar
3365 @node Window Systems
3366 @section Window Systems
3368   Emacs works with several window systems, most notably the X Window
3369 System.  Both Emacs and X use the term ``window'', but use it
3370 differently.  An Emacs frame is a single window as far as X is
3371 concerned; the individual Emacs windows are not known to X at all.
3373 @defvar window-system
3374 This variable tells Lisp programs what window system Emacs is running
3375 under.  The possible values are
3377 @table @code
3378 @item x
3379 @cindex X Window System
3380 Emacs is displaying using X.
3381 @item pc
3382 Emacs is displaying using MS-DOS.
3383 @item w32
3384 Emacs is displaying using Windows.
3385 @item mac
3386 Emacs is displaying using a Macintosh.
3387 @item nil
3388 Emacs is using a character-based terminal.
3389 @end table
3390 @end defvar
3392 @defvar window-setup-hook
3393 This variable is a normal hook which Emacs runs after handling the
3394 initialization files.  Emacs runs this hook after it has completed
3395 loading your init file, the default initialization file (if
3396 any), and the terminal-specific Lisp code, and running the hook
3397 @code{term-setup-hook}.
3399 This hook is used for internal purposes: setting up communication with
3400 the window system, and creating the initial window.  Users should not
3401 interfere with it.
3402 @end defvar