]> code.delx.au - gnu-emacs/blob - lispref/display.texi
Don't include coff.h unless HAVE_COFF_H is defined.
[gnu-emacs] / lispref / display.texi
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
9
10 This chapter describes a number of features related to the display
11 that Emacs presents to the user.
12
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
35
36 @node Refresh Screen
37 @section Refreshing the Screen
38
39 The function @code{redraw-frame} redisplays the entire contents of a
40 given frame (@pxref{Frames}).
41
42 @c Emacs 19 feature
43 @defun redraw-frame frame
44 This function clears and redisplays frame @var{frame}.
45 @end defun
46
47 Even more powerful is @code{redraw-display}:
48
49 @deffn Command redraw-display
50 This function clears and redisplays all visible frames.
51 @end deffn
52
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.
57
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.
63
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
71
72 @node Forcing Redisplay
73 @section Forcing Redisplay
74 @cindex forcing redisplay
75
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.
80
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
88
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:
92
93 @example
94 (let ((redisplay-dont-pause t))
95 (sit-for 0))
96 @end example
97
98 @node Truncation
99 @section Truncation
100 @cindex line wrapping
101 @cindex continuation lines
102 @cindex @samp{$} in display
103 @cindex @samp{\} in display
104
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}.)
113
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}.
117
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.
123
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
128
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
133
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
140
141 When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
142 a window, that forces truncation.
143
144 You can override the glyphs that indicate continuation or truncation
145 using the display table; see @ref{Display Tables}.
146
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}.
152
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.
158
159 Turning on the cache slows down processing of short lines somewhat.
160
161 This variable is automatically buffer-local in every buffer.
162 @end defvar
163
164 @node The Echo Area
165 @section The Echo Area
166 @cindex error display
167 @cindex echo area
168
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}.
177
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:
181
182 @defun message string &rest arguments
183 This function displays a 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.
188
189 In batch mode, @code{message} prints the message text on the standard
190 error stream, followed by a newline.
191
192 If @var{string}, or strings among the @var{arguments}, have @code{face}
193 text properties, these affect the way the message is displayed.
194
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.
200
201 @vindex message-truncate-lines
202 Normally, displaying a long message resizes the echo area to display
203 the entire message. But if the variable @code{message-truncate-lines}
204 is non-@code{nil}, the echo area does not resize, and the message is
205 truncated to fit it, as in Emacs 20 and before.
206
207 @example
208 @group
209 (message "Minibuffer depth is %d."
210 (minibuffer-depth))
211 @print{} Minibuffer depth is 0.
212 @result{} "Minibuffer depth is 0."
213 @end group
214
215 @group
216 ---------- Echo Area ----------
217 Minibuffer depth is 0.
218 ---------- Echo Area ----------
219 @end group
220 @end example
221
222 To automatically display a message in the echo area or in a pop-buffer,
223 depending on its size, use @code{display-message-or-buffer}.
224 @end defun
225
226 @tindex with-temp-message
227 @defmac with-temp-message message &rest body
228 This construct displays a message in the echo area temporarily, during
229 the execution of @var{body}. It displays @var{message}, executes
230 @var{body}, then returns the value of the last body form while restoring
231 the previous echo area contents.
232 @end defmac
233
234 @defun message-or-box string &rest arguments
235 This function displays a message like @code{message}, but may display it
236 in a dialog box instead of the echo area. If this function is called in
237 a command that was invoked using the mouse---more precisely, if
238 @code{last-nonmenu-event} (@pxref{Command Loop Info}) is either
239 @code{nil} or a list---then it uses a dialog box or pop-up menu to
240 display the message. Otherwise, it uses the echo area. (This is the
241 same criterion that @code{y-or-n-p} uses to make a similar decision; see
242 @ref{Yes-or-No Queries}.)
243
244 You can force use of the mouse or of the echo area by binding
245 @code{last-nonmenu-event} to a suitable value around the call.
246 @end defun
247
248 @defun message-box string &rest arguments
249 This function displays a message like @code{message}, but uses a dialog
250 box (or a pop-up menu) whenever that is possible. If it is impossible
251 to use a dialog box or pop-up menu, because the terminal does not
252 support them, then @code{message-box} uses the echo area, like
253 @code{message}.
254 @end defun
255
256 @defun display-message-or-buffer message &optional buffer-name not-this-window frame
257 @tindex display-message-or-buffer
258 This function displays the message @var{message}, which may be either a
259 string or a buffer. If it is shorter than the maximum height of the
260 echo area, as defined by @code{max-mini-window-height}, it is displayed
261 in the echo area, using @code{message}. Otherwise,
262 @code{display-buffer} is used to show it in a pop-up buffer.
263
264 Returns either the string shown in the echo area, or when a pop-up
265 buffer is used, the window used to display it.
266
267 If @var{message} is a string, then the optional argument
268 @var{buffer-name} is the name of the buffer used to display it when a
269 pop-up buffer is used, defaulting to @samp{*Message*}. In the case
270 where @var{message} is a string and displayed in the echo area, it is
271 not specified whether the contents are inserted into the buffer anyway.
272
273 The optional arguments @var{not-this-window} and @var{frame} are as for
274 @code{display-buffer}, and only used if a buffer is displayed.
275 @end defun
276
277 @defun current-message
278 This function returns the message currently being displayed in the
279 echo area, or @code{nil} if there is none.
280 @end defun
281
282 @defvar cursor-in-echo-area
283 This variable controls where the cursor appears when a message is
284 displayed in the echo area. If it is non-@code{nil}, then the cursor
285 appears at the end of the message. Otherwise, the cursor appears at
286 point---not in the echo area at all.
287
288 The value is normally @code{nil}; Lisp programs bind it to @code{t}
289 for brief periods of time.
290 @end defvar
291
292 @defvar echo-area-clear-hook
293 This normal hook is run whenever the echo area is cleared---either by
294 @code{(message nil)} or for any other reason.
295 @end defvar
296
297 Almost all the messages displayed in the echo area are also recorded
298 in the @samp{*Messages*} buffer.
299
300 @defopt message-log-max
301 This variable specifies how many lines to keep in the @samp{*Messages*}
302 buffer. The value @code{t} means there is no limit on how many lines to
303 keep. The value @code{nil} disables message logging entirely. Here's
304 how to display a message and prevent it from being logged:
305
306 @example
307 (let (message-log-max)
308 (message @dots{}))
309 @end example
310 @end defopt
311
312 @defvar echo-keystrokes
313 This variable determines how much time should elapse before command
314 characters echo. Its value must be an integer or floating point number,
315 which specifies the
316 number of seconds to wait before echoing. If the user types a prefix
317 key (such as @kbd{C-x}) and then delays this many seconds before
318 continuing, the prefix key is echoed in the echo area. (Once echoing
319 begins in a key sequence, all subsequent characters in the same key
320 sequence are echoed immediately.)
321
322 If the value is zero, then command input is not echoed.
323 @end defvar
324
325 @node Invisible Text
326 @section Invisible Text
327
328 @cindex invisible text
329 You can make characters @dfn{invisible}, so that they do not appear on
330 the screen, with the @code{invisible} property. This can be either a
331 text property (@pxref{Text Properties}) or a property of an overlay
332 (@pxref{Overlays}).
333
334 In the simplest case, any non-@code{nil} @code{invisible} property makes
335 a character invisible. This is the default case---if you don't alter
336 the default value of @code{buffer-invisibility-spec}, this is how the
337 @code{invisible} property works.
338
339 More generally, you can use the variable @code{buffer-invisibility-spec}
340 to control which values of the @code{invisible} property make text
341 invisible. This permits you to classify the text into different subsets
342 in advance, by giving them different @code{invisible} values, and
343 subsequently make various subsets visible or invisible by changing the
344 value of @code{buffer-invisibility-spec}.
345
346 Controlling visibility with @code{buffer-invisibility-spec} is
347 especially useful in a program to display the list of entries in a
348 database. It permits the implementation of convenient filtering
349 commands to view just a part of the entries in the database. Setting
350 this variable is very fast, much faster than scanning all the text in
351 the buffer looking for properties to change.
352
353 @defvar buffer-invisibility-spec
354 This variable specifies which kinds of @code{invisible} properties
355 actually make a character invisible.
356
357 @table @asis
358 @item @code{t}
359 A character is invisible if its @code{invisible} property is
360 non-@code{nil}. This is the default.
361
362 @item a list
363 Each element of the list specifies a criterion for invisibility; if a
364 character's @code{invisible} property fits any one of these criteria,
365 the character is invisible. The list can have two kinds of elements:
366
367 @table @code
368 @item @var{atom}
369 A character is invisible if its @code{invisible} property value
370 is @var{atom} or if it is a list with @var{atom} as a member.
371
372 @item (@var{atom} . t)
373 A character is invisible if its @code{invisible} property value
374 is @var{atom} or if it is a list with @var{atom} as a member.
375 Moreover, if this character is at the end of a line and is followed
376 by a visible newline, it displays an ellipsis.
377 @end table
378 @end table
379 @end defvar
380
381 Two functions are specifically provided for adding elements to
382 @code{buffer-invisibility-spec} and removing elements from it.
383
384 @defun add-to-invisibility-spec element
385 Add the element @var{element} to @code{buffer-invisibility-spec}
386 (if it is not already present in that list).
387 @end defun
388
389 @defun remove-from-invisibility-spec element
390 Remove the element @var{element} from @code{buffer-invisibility-spec}.
391 This does nothing if @var{element} is not in the list.
392 @end defun
393
394 One convention about the use of @code{buffer-invisibility-spec} is
395 that a major mode should use the mode's own name as an element of
396 @code{buffer-invisibility-spec} and as the value of the @code{invisible}
397 property:
398
399 @example
400 ;; @r{If you want to display an ellipsis:}
401 (add-to-invisibility-spec '(my-symbol . t))
402 ;; @r{If you don't want ellipsis:}
403 (add-to-invisibility-spec 'my-symbol)
404
405 (overlay-put (make-overlay beginning end)
406 'invisible 'my-symbol)
407
408 ;; @r{When done with the overlays:}
409 (remove-from-invisibility-spec '(my-symbol . t))
410 ;; @r{Or respectively:}
411 (remove-from-invisibility-spec 'my-symbol)
412 @end example
413
414 @vindex line-move-ignore-invisible
415 Ordinarily, commands that operate on text or move point do not care
416 whether the text is invisible. The user-level line motion commands
417 explicitly ignore invisible newlines if
418 @code{line-move-ignore-invisible} is non-@code{nil}, but only because
419 they are explicitly programmed to do so.
420
421 Incremental search can make invisible overlays visible temporarily
422 and/or permanently when a match includes invisible text. To enable
423 this, the overlay should have a non-@code{nil}
424 @code{isearch-open-invisible} property. The property value should be a
425 function to be called with the overlay as an argument. This function
426 should make the overlay visible permanently; it is used when the match
427 overlaps the overlay on exit from the search.
428
429 During the search, such overlays are made temporarily visible by
430 temporarily modifying their invisible and intangible properties. If you
431 want this to be done differently for a certain overlay, give it an
432 @code{isearch-open-invisible-temporary} property which is a function.
433 The function is called with two arguments: the first is the overlay, and
434 the second is @code{nil} to make the overlay visible, or @code{t} to
435 make it invisible again.
436
437 @node Selective Display
438 @section Selective Display
439 @cindex selective display
440
441 @dfn{Selective display} refers to a pair of related features for
442 hiding certain lines on the screen.
443
444 The first variant, explicit selective display, is designed for use in
445 a Lisp program: it controls which lines are hidden by altering the text.
446 The invisible text feature (@pxref{Invisible Text}) has partially
447 replaced this feature.
448
449 In the second variant, the choice of lines to hide is made
450 automatically based on indentation. This variant is designed to be a
451 user-level feature.
452
453 The way you control explicit selective display is by replacing a
454 newline (control-j) with a carriage return (control-m). The text that
455 was formerly a line following that newline is now invisible. Strictly
456 speaking, it is temporarily no longer a line at all, since only newlines
457 can separate lines; it is now part of the previous line.
458
459 Selective display does not directly affect editing commands. For
460 example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly into
461 invisible text. However, the replacement of newline characters with
462 carriage return characters affects some editing commands. For example,
463 @code{next-line} skips invisible lines, since it searches only for
464 newlines. Modes that use selective display can also define commands
465 that take account of the newlines, or that make parts of the text
466 visible or invisible.
467
468 When you write a selectively displayed buffer into a file, all the
469 control-m's are output as newlines. This means that when you next read
470 in the file, it looks OK, with nothing invisible. The selective display
471 effect is seen only within Emacs.
472
473 @defvar selective-display
474 This buffer-local variable enables selective display. This means that
475 lines, or portions of lines, may be made invisible.
476
477 @itemize @bullet
478 @item
479 If the value of @code{selective-display} is @code{t}, then the character
480 control-m marks the start of invisible text; the control-m, and the rest
481 of the line following it, are not displayed. This is explicit selective
482 display.
483
484 @item
485 If the value of @code{selective-display} is a positive integer, then
486 lines that start with more than that many columns of indentation are not
487 displayed.
488 @end itemize
489
490 When some portion of a buffer is invisible, the vertical movement
491 commands operate as if that portion did not exist, allowing a single
492 @code{next-line} command to skip any number of invisible lines.
493 However, character movement commands (such as @code{forward-char}) do
494 not skip the invisible portion, and it is possible (if tricky) to insert
495 or delete text in an invisible portion.
496
497 In the examples below, we show the @emph{display appearance} of the
498 buffer @code{foo}, which changes with the value of
499 @code{selective-display}. The @emph{contents} of the buffer do not
500 change.
501
502 @example
503 @group
504 (setq selective-display nil)
505 @result{} nil
506
507 ---------- Buffer: foo ----------
508 1 on this column
509 2on this column
510 3n this column
511 3n this column
512 2on this column
513 1 on this column
514 ---------- Buffer: foo ----------
515 @end group
516
517 @group
518 (setq selective-display 2)
519 @result{} 2
520
521 ---------- Buffer: foo ----------
522 1 on this column
523 2on this column
524 2on this column
525 1 on this column
526 ---------- Buffer: foo ----------
527 @end group
528 @end example
529 @end defvar
530
531 @defvar selective-display-ellipses
532 If this buffer-local variable is non-@code{nil}, then Emacs displays
533 @samp{@dots{}} at the end of a line that is followed by invisible text.
534 This example is a continuation of the previous one.
535
536 @example
537 @group
538 (setq selective-display-ellipses t)
539 @result{} t
540
541 ---------- Buffer: foo ----------
542 1 on this column
543 2on this column ...
544 2on this column
545 1 on this column
546 ---------- Buffer: foo ----------
547 @end group
548 @end example
549
550 You can use a display table to substitute other text for the ellipsis
551 (@samp{@dots{}}). @xref{Display Tables}.
552 @end defvar
553
554 @node Overlay Arrow
555 @section The Overlay Arrow
556 @cindex overlay arrow
557
558 The @dfn{overlay arrow} is useful for directing the user's attention
559 to a particular line in a buffer. For example, in the modes used for
560 interface to debuggers, the overlay arrow indicates the line of code
561 about to be executed.
562
563 @defvar overlay-arrow-string
564 This variable holds the string to display to call attention to a
565 particular line, or @code{nil} if the arrow feature is not in use.
566 On a graphical display the contents of the string are ignored; instead a
567 glyph is displayed in the fringe area to the left of the display area.
568 @end defvar
569
570 @defvar overlay-arrow-position
571 This variable holds a marker that indicates where to display the overlay
572 arrow. It should point at the beginning of a line. On a non-graphical
573 display the arrow text
574 appears at the beginning of that line, overlaying any text that would
575 otherwise appear. Since the arrow is usually short, and the line
576 usually begins with indentation, normally nothing significant is
577 overwritten.
578
579 The overlay string is displayed only in the buffer that this marker
580 points into. Thus, only one buffer can have an overlay arrow at any
581 given time.
582 @c !!! overlay-arrow-position: but the overlay string may remain in the display
583 @c of some other buffer until an update is required. This should be fixed
584 @c now. Is it?
585 @end defvar
586
587 You can do a similar job by creating an overlay with a
588 @code{before-string} property. @xref{Overlay Properties}.
589
590 @node Temporary Displays
591 @section Temporary Displays
592
593 Temporary displays are used by Lisp programs to put output into a
594 buffer and then present it to the user for perusal rather than for
595 editing. Many help commands use this feature.
596
597 @defspec with-output-to-temp-buffer buffer-name forms@dots{}
598 This function executes @var{forms} while arranging to insert any output
599 they print into the buffer named @var{buffer-name}, which is first
600 created if necessary, and put into Help mode. Finally, the buffer is
601 displayed in some window, but not selected.
602
603 If the @var{forms} do not change the major mode in the output buffer, so
604 that it is still Help mode at the end of their execution, then
605 @code{with-output-to-temp-buffer} makes this buffer read-only at the
606 end, and also scans it for function and variable names to make them into
607 clickable cross-references.
608
609 The string @var{buffer-name} specifies the temporary buffer, which
610 need not already exist. The argument must be a string, not a buffer.
611 The buffer is erased initially (with no questions asked), and it is
612 marked as unmodified after @code{with-output-to-temp-buffer} exits.
613
614 @code{with-output-to-temp-buffer} binds @code{standard-output} to the
615 temporary buffer, then it evaluates the forms in @var{forms}. Output
616 using the Lisp output functions within @var{forms} goes by default to
617 that buffer (but screen display and messages in the echo area, although
618 they are ``output'' in the general sense of the word, are not affected).
619 @xref{Output Functions}.
620
621 Several hooks are available for customizing the behavior
622 of this construct; they are listed below.
623
624 The value of the last form in @var{forms} is returned.
625
626 @example
627 @group
628 ---------- Buffer: foo ----------
629 This is the contents of foo.
630 ---------- Buffer: foo ----------
631 @end group
632
633 @group
634 (with-output-to-temp-buffer "foo"
635 (print 20)
636 (print standard-output))
637 @result{} #<buffer foo>
638
639 ---------- Buffer: foo ----------
640 20
641
642 #<buffer foo>
643
644 ---------- Buffer: foo ----------
645 @end group
646 @end example
647 @end defspec
648
649 @defvar temp-buffer-show-function
650 If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
651 calls it as a function to do the job of displaying a help buffer. The
652 function gets one argument, which is the buffer it should display.
653
654 It is a good idea for this function to run @code{temp-buffer-show-hook}
655 just as @code{with-output-to-temp-buffer} normally would, inside of
656 @code{save-selected-window} and with the chosen window and buffer
657 selected.
658 @end defvar
659
660 @defvar temp-buffer-setup-hook
661 @tindex temp-buffer-setup-hook
662 This normal hook is run by @code{with-output-to-temp-buffer} before
663 evaluating @var{body}. When the hook runs, the help buffer is current.
664 This hook is normally set up with a function to put the buffer in Help
665 mode.
666 @end defvar
667
668 @defvar temp-buffer-show-hook
669 This normal hook is run by @code{with-output-to-temp-buffer} after
670 displaying the help buffer. When the hook runs, the help buffer is
671 current, and the window it was displayed in is selected. This hook is
672 normally set up with a function to make the buffer read only, and find
673 function names and variable names in it, provided the major mode is
674 still Help mode.
675 @end defvar
676
677 @defun momentary-string-display string position &optional char message
678 This function momentarily displays @var{string} in the current buffer at
679 @var{position}. It has no effect on the undo list or on the buffer's
680 modification status.
681
682 The momentary display remains until the next input event. If the next
683 input event is @var{char}, @code{momentary-string-display} ignores it
684 and returns. Otherwise, that event remains buffered for subsequent use
685 as input. Thus, typing @var{char} will simply remove the string from
686 the display, while typing (say) @kbd{C-f} will remove the string from
687 the display and later (presumably) move point forward. The argument
688 @var{char} is a space by default.
689
690 The return value of @code{momentary-string-display} is not meaningful.
691
692 If the string @var{string} does not contain control characters, you can
693 do the same job in a more general way by creating (and then subsequently
694 deleting) an overlay with a @code{before-string} property.
695 @xref{Overlay Properties}.
696
697 If @var{message} is non-@code{nil}, it is displayed in the echo area
698 while @var{string} is displayed in the buffer. If it is @code{nil}, a
699 default message says to type @var{char} to continue.
700
701 In this example, point is initially located at the beginning of the
702 second line:
703
704 @example
705 @group
706 ---------- Buffer: foo ----------
707 This is the contents of foo.
708 @point{}Second line.
709 ---------- Buffer: foo ----------
710 @end group
711
712 @group
713 (momentary-string-display
714 "**** Important Message! ****"
715 (point) ?\r
716 "Type RET when done reading")
717 @result{} t
718 @end group
719
720 @group
721 ---------- Buffer: foo ----------
722 This is the contents of foo.
723 **** Important Message! ****Second line.
724 ---------- Buffer: foo ----------
725
726 ---------- Echo Area ----------
727 Type RET when done reading
728 ---------- Echo Area ----------
729 @end group
730 @end example
731 @end defun
732
733 @node Overlays
734 @section Overlays
735 @cindex overlays
736
737 You can use @dfn{overlays} to alter the appearance of a buffer's text on
738 the screen, for the sake of presentation features. An overlay is an
739 object that belongs to a particular buffer, and has a specified
740 beginning and end. It also has properties that you can examine and set;
741 these affect the display of the text within the overlay.
742
743 @menu
744 * Overlay Properties:: How to read and set properties.
745 What properties do to the screen display.
746 * Managing Overlays:: Creating and moving overlays.
747 * Finding Overlays:: Searching for overlays.
748 @end menu
749
750 @node Overlay Properties
751 @subsection Overlay Properties
752
753 Overlay properties are like text properties in that the properties that
754 alter how a character is displayed can come from either source. But in
755 most respects they are different. Text properties are considered a part
756 of the text; overlays are specifically considered not to be part of the
757 text. Thus, copying text between various buffers and strings preserves
758 text properties, but does not try to preserve overlays. Changing a
759 buffer's text properties marks the buffer as modified, while moving an
760 overlay or changing its properties does not. Unlike text property
761 changes, overlay changes are not recorded in the buffer's undo list.
762 @xref{Text Properties}, for comparison.
763
764 These functions are used for reading and writing the properties of an
765 overlay:
766
767 @defun overlay-get overlay prop
768 This function returns the value of property @var{prop} recorded in
769 @var{overlay}, if any. If @var{overlay} does not record any value for
770 that property, but it does have a @code{category} property which is a
771 symbol, that symbol's @var{prop} property is used. Otherwise, the value
772 is @code{nil}.
773 @end defun
774
775 @defun overlay-put overlay prop value
776 This function sets the value of property @var{prop} recorded in
777 @var{overlay} to @var{value}. It returns @var{value}.
778 @end defun
779
780 See also the function @code{get-char-property} which checks both
781 overlay properties and text properties for a given character.
782 @xref{Examining Properties}.
783
784 Many overlay properties have special meanings; here is a table
785 of them:
786
787 @table @code
788 @item priority
789 @kindex priority @r{(overlay property)}
790 This property's value (which should be a nonnegative number) determines
791 the priority of the overlay. The priority matters when two or more
792 overlays cover the same character and both specify a face for display;
793 the one whose @code{priority} value is larger takes priority over the
794 other, and its face attributes override the face attributes of the lower
795 priority overlay.
796
797 Currently, all overlays take priority over text properties. Please
798 avoid using negative priority values, as we have not yet decided just
799 what they should mean.
800
801 @item window
802 @kindex window @r{(overlay property)}
803 If the @code{window} property is non-@code{nil}, then the overlay
804 applies only on that window.
805
806 @item category
807 @kindex category @r{(overlay property)}
808 If an overlay has a @code{category} property, we call it the
809 @dfn{category} of the overlay. It should be a symbol. The properties
810 of the symbol serve as defaults for the properties of the overlay.
811
812 @item face
813 @kindex face @r{(overlay property)}
814 This property controls the way text is displayed---for example, which
815 font and which colors. @xref{Faces}, for more information.
816
817 In the simplest case, the value is a face name. It can also be a list;
818 then each element can be any of these possibilities:
819
820 @itemize @bullet
821 @item
822 A face name (a symbol or string).
823
824 @item
825 Starting in Emacs 21, a property list of face attributes. This has the
826 form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
827 face attribute name and @var{value} is a meaningful value for that
828 attribute. With this feature, you do not need to create a face each
829 time you want to specify a particular attribute for certain text.
830 @xref{Face Attributes}.
831
832 @item
833 A cons cell of the form @code{(foreground-color . @var{color-name})} or
834 @code{(background-color . @var{color-name})}. These elements specify
835 just the foreground color or just the background color.
836
837 @code{(foreground-color . @var{color-name})} is equivalent to
838 @code{(:foreground @var{color-name})}, and likewise for the background.
839 @end itemize
840
841 @item mouse-face
842 @kindex mouse-face @r{(overlay property)}
843 This property is used instead of @code{face} when the mouse is within
844 the range of the overlay.
845
846 @item display
847 @kindex display @r{(overlay property)}
848 This property activates various features that change the
849 way text is displayed. For example, it can make text appear taller
850 or shorter, higher or lower, wider or narrower, or replaced with an image.
851 @xref{Display Property}.
852
853 @item help-echo
854 @kindex help-echo @r{(text property)}
855 If an overlay has a @code{help-echo} property, then when you move the
856 mouse onto the text in the overlay, Emacs displays a help string in the
857 echo area, or in the tooltip window. For details see @ref{Text
858 help-echo}. This feature is available starting in Emacs 21.
859
860 @item modification-hooks
861 @kindex modification-hooks @r{(overlay property)}
862 This property's value is a list of functions to be called if any
863 character within the overlay is changed or if text is inserted strictly
864 within the overlay.
865
866 The hook functions are called both before and after each change.
867 If the functions save the information they receive, and compare notes
868 between calls, they can determine exactly what change has been made
869 in the buffer text.
870
871 When called before a change, each function receives four arguments: the
872 overlay, @code{nil}, and the beginning and end of the text range to be
873 modified.
874
875 When called after a change, each function receives five arguments: the
876 overlay, @code{t}, the beginning and end of the text range just
877 modified, and the length of the pre-change text replaced by that range.
878 (For an insertion, the pre-change length is zero; for a deletion, that
879 length is the number of characters deleted, and the post-change
880 beginning and end are equal.)
881
882 @item insert-in-front-hooks
883 @kindex insert-in-front-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 beginning of the overlay. The calling
886 conventions are the same as for the @code{modification-hooks} functions.
887
888 @item insert-behind-hooks
889 @kindex insert-behind-hooks @r{(overlay property)}
890 This property's value is a list of functions to be called before and
891 after inserting text right at the end of the overlay. The calling
892 conventions are the same as for the @code{modification-hooks} functions.
893
894 @item invisible
895 @kindex invisible @r{(overlay property)}
896 The @code{invisible} property can make the text in the overlay
897 invisible, which means that it does not appear on the screen.
898 @xref{Invisible Text}, for details.
899
900 @item intangible
901 @kindex intangible @r{(overlay property)}
902 The @code{intangible} property on an overlay works just like the
903 @code{intangible} text property. @xref{Special Properties}, for details.
904
905 @item isearch-open-invisible
906 This property tells incremental search how to make an invisible overlay
907 visible, permanently, if the final match overlaps it. @xref{Invisible
908 Text}.
909
910 @item isearch-open-invisible-temporary
911 This property tells incremental search how to make an invisible overlay
912 visible, temporarily, during the search. @xref{Invisible Text}.
913
914 @item before-string
915 @kindex before-string @r{(overlay property)}
916 This property's value is a string to add to the display at the beginning
917 of the overlay. The string does not appear in the buffer in any
918 sense---only on the screen.
919
920 @item after-string
921 @kindex after-string @r{(overlay property)}
922 This property's value is a string to add to the display at the end of
923 the overlay. The string does not appear in the buffer in any
924 sense---only on the screen.
925
926 @item evaporate
927 @kindex evaporate @r{(overlay property)}
928 If this property is non-@code{nil}, the overlay is deleted automatically
929 if it ever becomes empty (i.e., if it spans no characters).
930
931 @item local-map
932 @cindex keymap of character (and overlays)
933 @kindex local-map @r{(overlay property)}
934 If this property is non-@code{nil}, it specifies a keymap for a portion
935 of the text. The property's value replaces the buffer's local map, when
936 the character after point is within the overlay. @xref{Active Keymaps}.
937
938 @item keymap
939 @kindex keymap @r{(overlay property)}
940 The @code{keymap} property is similar to @code{local-map} but overrides the
941 buffer's local map (and the map specified by the @code{local-map}
942 property) rather than replacing it.
943 @end table
944
945 @node Managing Overlays
946 @subsection Managing Overlays
947
948 This section describes the functions to create, delete and move
949 overlays, and to examine their contents.
950
951 @defun make-overlay start end &optional buffer front-advance rear-advance
952 This function creates and returns an overlay that belongs to
953 @var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
954 and @var{end} must specify buffer positions; they may be integers or
955 markers. If @var{buffer} is omitted, the overlay is created in the
956 current buffer.
957
958 The arguments @var{front-advance} and @var{rear-advance} specify the
959 insertion type for the start of the overlay and for the end of the
960 overlay, respectively. @xref{Marker Insertion Types}.
961 @end defun
962
963 @defun overlay-start overlay
964 This function returns the position at which @var{overlay} starts,
965 as an integer.
966 @end defun
967
968 @defun overlay-end overlay
969 This function returns the position at which @var{overlay} ends,
970 as an integer.
971 @end defun
972
973 @defun overlay-buffer overlay
974 This function returns the buffer that @var{overlay} belongs to.
975 @end defun
976
977 @defun delete-overlay overlay
978 This function deletes @var{overlay}. The overlay continues to exist as
979 a Lisp object, and its property list is unchanged, but it ceases to be
980 attached to the buffer it belonged to, and ceases to have any effect on
981 display.
982
983 A deleted overlay is not permanently disconnected. You can give it a
984 position in a buffer again by calling @code{move-overlay}.
985 @end defun
986
987 @defun move-overlay overlay start end &optional buffer
988 This function moves @var{overlay} to @var{buffer}, and places its bounds
989 at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
990 must specify buffer positions; they may be integers or markers.
991
992 If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
993 was already associated with; if @var{overlay} was deleted, it goes into
994 the current buffer.
995
996 The return value is @var{overlay}.
997
998 This is the only valid way to change the endpoints of an overlay. Do
999 not try modifying the markers in the overlay by hand, as that fails to
1000 update other vital data structures and can cause some overlays to be
1001 ``lost''.
1002 @end defun
1003
1004 Here are some examples:
1005
1006 @example
1007 ;; @r{Create an overlay.}
1008 (setq foo (make-overlay 1 10))
1009 @result{} #<overlay from 1 to 10 in display.texi>
1010 (overlay-start foo)
1011 @result{} 1
1012 (overlay-end foo)
1013 @result{} 10
1014 (overlay-buffer foo)
1015 @result{} #<buffer display.texi>
1016 ;; @r{Give it a property we can check later.}
1017 (overlay-put foo 'happy t)
1018 @result{} t
1019 ;; @r{Verify the property is present.}
1020 (overlay-get foo 'happy)
1021 @result{} t
1022 ;; @r{Move the overlay.}
1023 (move-overlay foo 5 20)
1024 @result{} #<overlay from 5 to 20 in display.texi>
1025 (overlay-start foo)
1026 @result{} 5
1027 (overlay-end foo)
1028 @result{} 20
1029 ;; @r{Delete the overlay.}
1030 (delete-overlay foo)
1031 @result{} nil
1032 ;; @r{Verify it is deleted.}
1033 foo
1034 @result{} #<overlay in no buffer>
1035 ;; @r{A deleted overlay has no position.}
1036 (overlay-start foo)
1037 @result{} nil
1038 (overlay-end foo)
1039 @result{} nil
1040 (overlay-buffer foo)
1041 @result{} nil
1042 ;; @r{Undelete the overlay.}
1043 (move-overlay foo 1 20)
1044 @result{} #<overlay from 1 to 20 in display.texi>
1045 ;; @r{Verify the results.}
1046 (overlay-start foo)
1047 @result{} 1
1048 (overlay-end foo)
1049 @result{} 20
1050 (overlay-buffer foo)
1051 @result{} #<buffer display.texi>
1052 ;; @r{Moving and deleting the overlay does not change its properties.}
1053 (overlay-get foo 'happy)
1054 @result{} t
1055 @end example
1056
1057 @node Finding Overlays
1058 @subsection Searching for Overlays
1059
1060 @defun overlays-at pos
1061 This function returns a list of all the overlays that cover the
1062 character at position @var{pos} in the current buffer. The list is in
1063 no particular order. An overlay contains position @var{pos} if it
1064 begins at or before @var{pos}, and ends after @var{pos}.
1065
1066 To illustrate usage, here is a Lisp function that returns a list of the
1067 overlays that specify property @var{prop} for the character at point:
1068
1069 @smallexample
1070 (defun find-overlays-specifying (prop)
1071 (let ((overlays (overlays-at (point)))
1072 found)
1073 (while overlays
1074 (let ((overlay (car overlays)))
1075 (if (overlay-get overlay prop)
1076 (setq found (cons overlay found))))
1077 (setq overlays (cdr overlays)))
1078 found))
1079 @end smallexample
1080 @end defun
1081
1082 @defun overlays-in beg end
1083 This function returns a list of the overlays that overlap the region
1084 @var{beg} through @var{end}. ``Overlap'' means that at least one
1085 character is contained within the overlay and also contained within the
1086 specified region; however, empty overlays are included in the result if
1087 they are located at @var{beg}, or strictly between @var{beg} and @var{end}.
1088 @end defun
1089
1090 @defun next-overlay-change pos
1091 This function returns the buffer position of the next beginning or end
1092 of an overlay, after @var{pos}.
1093 @end defun
1094
1095 @defun previous-overlay-change pos
1096 This function returns the buffer position of the previous beginning or
1097 end of an overlay, before @var{pos}.
1098 @end defun
1099
1100 Here's an easy way to use @code{next-overlay-change} to search for the
1101 next character which gets a non-@code{nil} @code{happy} property from
1102 either its overlays or its text properties (@pxref{Property Search}):
1103
1104 @smallexample
1105 (defun find-overlay-prop (prop)
1106 (save-excursion
1107 (while (and (not (eobp))
1108 (not (get-char-property (point) 'happy)))
1109 (goto-char (min (next-overlay-change (point))
1110 (next-single-property-change (point) 'happy))))
1111 (point)))
1112 @end smallexample
1113
1114 @node Width
1115 @section Width
1116
1117 Since not all characters have the same width, these functions let you
1118 check the width of a character. @xref{Primitive Indent}, and
1119 @ref{Screen Lines}, for related functions.
1120
1121 @defun char-width char
1122 This function returns the width in columns of the character @var{char},
1123 if it were displayed in the current buffer and the selected window.
1124 @end defun
1125
1126 @defun string-width string
1127 This function returns the width in columns of the string @var{string},
1128 if it were displayed in the current buffer and the selected window.
1129 @end defun
1130
1131 @defun truncate-string-to-width string width &optional start-column padding
1132 This function returns the part of @var{string} that fits within
1133 @var{width} columns, as a new string.
1134
1135 If @var{string} does not reach @var{width}, then the result ends where
1136 @var{string} ends. If one multi-column character in @var{string}
1137 extends across the column @var{width}, that character is not included in
1138 the result. Thus, the result can fall short of @var{width} but cannot
1139 go beyond it.
1140
1141 The optional argument @var{start-column} specifies the starting column.
1142 If this is non-@code{nil}, then the first @var{start-column} columns of
1143 the string are omitted from the value. If one multi-column character in
1144 @var{string} extends across the column @var{start-column}, that
1145 character is not included.
1146
1147 The optional argument @var{padding}, if non-@code{nil}, is a padding
1148 character added at the beginning and end of the result string, to extend
1149 it to exactly @var{width} columns. The padding character is used at the
1150 end of the result if it falls short of @var{width}. It is also used at
1151 the beginning of the result if one multi-column character in
1152 @var{string} extends across the column @var{start-column}.
1153
1154 @example
1155 (truncate-string-to-width "\tab\t" 12 4)
1156 @result{} "ab"
1157 (truncate-string-to-width "\tab\t" 12 4 ?\ )
1158 @result{} " ab "
1159 @end example
1160 @end defun
1161
1162 @node Faces
1163 @section Faces
1164 @cindex faces
1165
1166 A @dfn{face} is a named collection of graphical attributes: font
1167 family, foreground color, background color, optional underlining, and
1168 many others. Faces are used in Emacs to control the style of display of
1169 particular parts of the text or the frame.
1170
1171 @cindex face id
1172 Each face has its own @dfn{face number}, which distinguishes faces at
1173 low levels within Emacs. However, for most purposes, you refer to
1174 faces in Lisp programs by their names.
1175
1176 @defun facep object
1177 This function returns @code{t} if @var{object} is a face name symbol (or
1178 if it is a vector of the kind used internally to record face data). It
1179 returns @code{nil} otherwise.
1180 @end defun
1181
1182 Each face name is meaningful for all frames, and by default it has the
1183 same meaning in all frames. But you can arrange to give a particular
1184 face name a special meaning in one frame if you wish.
1185
1186 @menu
1187 * Standard Faces:: The faces Emacs normally comes with.
1188 * Defining Faces:: How to define a face with @code{defface}.
1189 * Face Attributes:: What is in a face?
1190 * Attribute Functions:: Functions to examine and set face attributes.
1191 * Merging Faces:: How Emacs combines the faces specified for a character.
1192 * Font Selection:: Finding the best available font for a face.
1193 * Face Functions:: How to define and examine faces.
1194 * Auto Faces:: Hook for automatic face assignment.
1195 * Font Lookup:: Looking up the names of available fonts
1196 and information about them.
1197 * Fontsets:: A fontset is a collection of fonts
1198 that handle a range of character sets.
1199 @end menu
1200
1201 @node Standard Faces
1202 @subsection Standard Faces
1203
1204 This table lists all the standard faces and their uses. Most of them
1205 are used for displaying certain parts of the frames or certain kinds of
1206 text; you can control how those places look by customizing these faces.
1207
1208 @table @code
1209 @item default
1210 @kindex default @r{(face name)}
1211 This face is used for ordinary text.
1212
1213 @item mode-line
1214 @kindex mode-line @r{(face name)}
1215 This face is used for mode lines, and for menu bars when toolkit menus
1216 are not used---but only if @code{mode-line-inverse-video} is
1217 non-@code{nil}.
1218
1219 @item modeline
1220 @kindex modeline @r{(face name)}
1221 This is an alias for the @code{mode-line} face, for compatibility with
1222 old Emacs versions.
1223
1224 @item header-line
1225 @kindex header-line @r{(face name)}
1226 This face is used for the header lines of windows that have them.
1227
1228 @item menu
1229 This face controls the display of menus, both their colors and their
1230 font. (This works only on certain systems.)
1231
1232 @item fringe
1233 @kindex fringe @r{(face name)}
1234 This face controls the colors of window fringes, the thin areas on
1235 either side that are used to display continuation and truncation glyphs.
1236
1237 @item scroll-bar
1238 @kindex scroll-bar @r{(face name)}
1239 This face controls the colors for display of scroll bars.
1240
1241 @item tool-bar
1242 @kindex tool-bar @r{(face name)}
1243 This face is used for display of the tool bar, if any.
1244
1245 @item region
1246 @kindex region @r{(face name)}
1247 This face is used for highlighting the region in Transient Mark mode.
1248
1249 @item secondary-selection
1250 @kindex secondary-selection @r{(face name)}
1251 This face is used to show any secondary selection you have made.
1252
1253 @item highlight
1254 @kindex highlight @r{(face name)}
1255 This face is meant to be used for highlighting for various purposes.
1256
1257 @item trailing-whitespace
1258 @kindex trailing-whitespace @r{(face name)}
1259 This face is used to display excess whitespace at the end of a line,
1260 if @code{show-trailing-whitespace} is non-@code{nil}.
1261 @end table
1262
1263 In contrast, these faces are provided to change the appearance of text
1264 in specific ways. You can use them on specific text, when you want
1265 the effects they produce.
1266
1267 @table @code
1268 @item bold
1269 @kindex bold @r{(face name)}
1270 This face uses a bold font, if possible. It uses the bold variant of
1271 the frame's font, if it has one. It's up to you to choose a default
1272 font that has a bold variant, if you want to use one.
1273
1274 @item italic
1275 @kindex italic @r{(face name)}
1276 This face uses the italic variant of the frame's font, if it has one.
1277
1278 @item bold-italic
1279 @kindex bold-italic @r{(face name)}
1280 This face uses the bold italic variant of the frame's font, if it has
1281 one.
1282
1283 @item underline
1284 @kindex underline @r{(face name)}
1285 This face underlines text.
1286
1287 @item fixed-pitch
1288 @kindex fixed-pitch @r{(face name)}
1289 This face forces use of a particular fixed-width font.
1290
1291 @item variable-pitch
1292 @kindex variable-pitch @r{(face name)}
1293 This face forces use of a particular variable-width font. It's
1294 reasonable to customize this to use a different variable-width font, if
1295 you like, but you should not make it a fixed-width font.
1296 @end table
1297
1298 @defvar show-trailing-whitespace
1299 @tindex show-trailing-whitespace
1300 If this variable is non-@code{nil}, Emacs uses the
1301 @code{trailing-whitespace} face to display any spaces and tabs at the
1302 end of a line.
1303 @end defvar
1304
1305 @node Defining Faces
1306 @subsection Defining Faces
1307
1308 The way to define a new face is with @code{defface}. This creates a
1309 kind of customization item (@pxref{Customization}) which the user can
1310 customize using the Customization buffer (@pxref{Easy Customization,,,
1311 emacs, The GNU Emacs Manual}).
1312
1313 @defmac defface face spec doc [keyword value]...
1314 This declares @var{face} as a customizable face that defaults according
1315 to @var{spec}. You should not quote the symbol @var{face}. The
1316 argument @var{doc} specifies the face documentation. The keywords you
1317 can use in @code{defface} are the same ones that are meaningful in both
1318 @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
1319
1320 When @code{defface} executes, it defines the face according to
1321 @var{spec}, then uses any customizations that were read from the
1322 init file (@pxref{Init File}) to override that specification.
1323
1324 The purpose of @var{spec} is to specify how the face should appear on
1325 different kinds of terminals. It should be an alist whose elements have
1326 the form @code{(@var{display} @var{atts})}. Each element's @sc{car},
1327 @var{display}, specifies a class of terminals. The element's second element,
1328 @var{atts}, is a list of face attributes and their values; it specifies
1329 what the face should look like on that kind of terminal. The possible
1330 attributes are defined in the value of @code{custom-face-attributes}.
1331
1332 The @var{display} part of an element of @var{spec} determines which
1333 frames the element applies to. If more than one element of @var{spec}
1334 matches a given frame, the first matching element is the only one used
1335 for that frame. There are two possibilities for @var{display}:
1336
1337 @table @asis
1338 @item @code{t}
1339 This element of @var{spec} matches all frames. Therefore, any
1340 subsequent elements of @var{spec} are never used. Normally
1341 @code{t} is used in the last (or only) element of @var{spec}.
1342
1343 @item a list
1344 If @var{display} is a list, each element should have the form
1345 @code{(@var{characteristic} @var{value}@dots{})}. Here
1346 @var{characteristic} specifies a way of classifying frames, and the
1347 @var{value}s are possible classifications which @var{display} should
1348 apply to. Here are the possible values of @var{characteristic}:
1349
1350 @table @code
1351 @item type
1352 The kind of window system the frame uses---either @code{graphic} (any
1353 graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console),
1354 @code{w32} (for MS Windows 9X/NT), or @code{tty} (a non-graphics-capable
1355 display).
1356
1357 @item class
1358 What kinds of colors the frame supports---either @code{color},
1359 @code{grayscale}, or @code{mono}.
1360
1361 @item background
1362 The kind of background---either @code{light} or @code{dark}.
1363 @end table
1364
1365 If an element of @var{display} specifies more than one @var{value} for a
1366 given @var{characteristic}, any of those values is acceptable. If
1367 @var{display} has more than one element, each element should specify a
1368 different @var{characteristic}; then @emph{each} characteristic of the
1369 frame must match one of the @var{value}s specified for it in
1370 @var{display}.
1371 @end table
1372 @end defmac
1373
1374 Here's how the standard face @code{region} is defined:
1375
1376 @example
1377 @group
1378 (defface region
1379 `((((type tty) (class color))
1380 (:background "blue" :foreground "white"))
1381 @end group
1382 (((type tty) (class mono))
1383 (:inverse-video t))
1384 (((class color) (background dark))
1385 (:background "blue"))
1386 (((class color) (background light))
1387 (:background "lightblue"))
1388 (t (:background "gray")))
1389 @group
1390 "Basic face for highlighting the region."
1391 :group 'basic-faces)
1392 @end group
1393 @end example
1394
1395 Internally, @code{defface} uses the symbol property
1396 @code{face-defface-spec} to record the face attributes specified in
1397 @code{defface}, @code{saved-face} for the attributes saved by the user
1398 with the customization buffer, and @code{face-documentation} for the
1399 documentation string.
1400
1401 @defopt frame-background-mode
1402 This option, if non-@code{nil}, specifies the background type to use for
1403 interpreting face definitions. If it is @code{dark}, then Emacs treats
1404 all frames as if they had a dark background, regardless of their actual
1405 background colors. If it is @code{light}, then Emacs treats all frames
1406 as if they had a light background.
1407 @end defopt
1408
1409 @node Face Attributes
1410 @subsection Face Attributes
1411 @cindex face attributes
1412
1413 The effect of using a face is determined by a fixed set of @dfn{face
1414 attributes}. This table lists all the face attributes, and what they
1415 mean. Note that in general, more than one face can be specified for a
1416 given piece of text; when that happens, the attributes of all the faces
1417 are merged to specify how to display the text. @xref{Merging Faces}.
1418
1419 In Emacs 21, any attribute in a face can have the value
1420 @code{unspecified}. This means the face doesn't specify that attribute.
1421 In face merging, when the first face fails to specify a particular
1422 attribute, that means the next face gets a chance. However, the
1423 @code{default} face must specify all attributes.
1424
1425 Some of these font attributes are meaningful only on certain kinds of
1426 displays---if your display cannot handle a certain attribute, the
1427 attribute is ignored. (The attributes @code{:family}, @code{:width},
1428 @code{:height}, @code{:weight}, and @code{:slant} correspond to parts of
1429 an X Logical Font Descriptor.)
1430
1431 @table @code
1432 @item :family
1433 Font family name, or fontset name (@pxref{Fontsets}). If you specify a
1434 font family name, the wild-card characters @samp{*} and @samp{?} are
1435 allowed.
1436
1437 @item :width
1438 Relative proportionate width, also known as the character set width or
1439 set width. This should be one of the symbols @code{ultra-condensed},
1440 @code{extra-condensed}, @code{condensed}, @code{semi-condensed},
1441 @code{normal}, @code{semi-expanded}, @code{expanded},
1442 @code{extra-expanded}, or @code{ultra-expanded}.
1443
1444 @item :height
1445 Either the font height, an integer in units of 1/10 point, a floating
1446 point number specifying the amount by which to scale the height of any
1447 underlying face, or a function, which is called with the old height
1448 (from the underlying face), and should return the new height.
1449
1450 @item :weight
1451 Font weight---a symbol from this series (from most dense to most faint):
1452 @code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
1453 @code{normal}, @code{semi-light}, @code{light}, @code{extra-light},
1454 or @code{ultra-light}.
1455
1456 On a text-only terminal, any weight greater than normal is displayed as
1457 extra bright, and any weight less than normal is displayed as
1458 half-bright (provided the terminal supports the feature).
1459
1460 @item :slant
1461 Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal},
1462 @code{reverse-italic}, or @code{reverse-oblique}.
1463
1464 On a text-only terminal, slanted text is displayed as half-bright, if
1465 the terminal supports the feature.
1466
1467 @item :foreground
1468 Foreground color, a string.
1469
1470 @item :background
1471 Background color, a string.
1472
1473 @item :inverse-video
1474 Whether or not characters should be displayed in inverse video. The
1475 value should be @code{t} (yes) or @code{nil} (no).
1476
1477 @item :stipple
1478 The background stipple, a bitmap.
1479
1480 The value can be a string; that should be the name of a file containing
1481 external-format X bitmap data. The file is found in the directories
1482 listed in the variable @code{x-bitmap-file-path}.
1483
1484 Alternatively, the value can specify the bitmap directly, with a list
1485 of the form @code{(@var{width} @var{height} @var{data})}. Here,
1486 @var{width} and @var{height} specify the size in pixels, and
1487 @var{data} is a string containing the raw bits of the bitmap, row by
1488 row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes
1489 in the string (which should be a unibyte string for best results).
1490 This means that each row always occupies at least one whole byte.
1491
1492 If the value is @code{nil}, that means use no stipple pattern.
1493
1494 Normally you do not need to set the stipple attribute, because it is
1495 used automatically to handle certain shades of gray.
1496
1497 @item :underline
1498 Whether or not characters should be underlined, and in what color. If
1499 the value is @code{t}, underlining uses the foreground color of the
1500 face. If the value is a string, underlining uses that color. The
1501 value @code{nil} means do not underline.
1502
1503 @item :overline
1504 Whether or not characters should be overlined, and in what color.
1505 The value is used like that of @code{:underline}.
1506
1507 @item :strike-through
1508 Whether or not characters should be strike-through, and in what
1509 color. The value is used like that of @code{:underline}.
1510
1511 @item :inherit
1512 The name of a face from which to inherit attributes, or a list of face
1513 names. Attributes from inherited faces are merged into the face like an
1514 underlying face would be, with higher priority than underlying faces.
1515
1516 @item :box
1517 Whether or not a box should be drawn around characters, its color, the
1518 width of the box lines, and 3D appearance.
1519 @end table
1520
1521 Here are the possible values of the @code{:box} attribute, and what
1522 they mean:
1523
1524 @table @asis
1525 @item @code{nil}
1526 Don't draw a box.
1527
1528 @item @code{t}
1529 Draw a box with lines of width 1, in the foreground color.
1530
1531 @item @var{color}
1532 Draw a box with lines of width 1, in color @var{color}.
1533
1534 @item @code{(:line-width @var{width} :color @var{color} :style @var{style})}
1535 This way you can explicitly specify all aspects of the box. The value
1536 @var{width} specifies the width of the lines to draw; it defaults to 1.
1537
1538 The value @var{color} specifies the color to draw with. The default is
1539 the foreground color of the face for simple boxes, and the background
1540 color of the face for 3D boxes.
1541
1542 The value @var{style} specifies whether to draw a 3D box. If it is
1543 @code{released-button}, the box looks like a 3D button that is not being
1544 pressed. If it is @code{pressed-button}, the box looks like a 3D button
1545 that is being pressed. If it is @code{nil} or omitted, a plain 2D box
1546 is used.
1547 @end table
1548
1549 The attributes @code{:overline}, @code{:strike-through} and
1550 @code{:box} are new in Emacs 21. The attributes @code{:family},
1551 @code{:height}, @code{:width}, @code{:weight}, @code{:slant} are also
1552 new; previous versions used the following attributes, now semi-obsolete,
1553 to specify some of the same information:
1554
1555 @table @code
1556 @item :font
1557 This attribute specifies the font name.
1558
1559 @item :bold
1560 A non-@code{nil} value specifies a bold font.
1561
1562 @item :italic
1563 A non-@code{nil} value specifies an italic font.
1564 @end table
1565
1566 For compatibility, you can still set these ``attributes'' in Emacs 21,
1567 even though they are not real face attributes. Here is what that does:
1568
1569 @table @code
1570 @item :font
1571 You can specify an X font name as the ``value'' of this ``attribute'';
1572 that sets the @code{:family}, @code{:width}, @code{:height},
1573 @code{:weight}, and @code{:slant} attributes according to the font name.
1574
1575 If the value is a pattern with wildcards, the first font that matches
1576 the pattern is used to set these attributes.
1577
1578 @item :bold
1579 A non-@code{nil} makes the face bold; @code{nil} makes it normal.
1580 This actually works by setting the @code{:weight} attribute.
1581
1582 @item :italic
1583 A non-@code{nil} makes the face italic; @code{nil} makes it normal.
1584 This actually works by setting the @code{:slant} attribute.
1585 @end table
1586
1587 @defvar x-bitmap-file-path
1588 This variable specifies a list of directories for searching
1589 for bitmap files, for the @code{:stipple} attribute.
1590 @end defvar
1591
1592 @defun bitmap-spec-p object
1593 This returns @code{t} if @var{object} is a valid bitmap
1594 specification, suitable for use with @code{:stipple}.
1595 It returns @code{nil} otherwise.
1596 @end defun
1597
1598 @node Attribute Functions
1599 @subsection Face Attribute Functions
1600
1601 You can modify the attributes of an existing face with the following
1602 functions. If you specify @var{frame}, they affect just that frame;
1603 otherwise, they affect all frames as well as the defaults that apply to
1604 new frames.
1605
1606 @tindex set-face-attribute
1607 @defun set-face-attribute face frame &rest arguments
1608 This function sets one or more attributes of face @var{face}
1609 for frame @var{frame}. If @var{frame} is @code{nil}, it sets
1610 the attribute for all frames, and the defaults for new frames.
1611
1612 The extra arguments @var{arguments} specify the attributes to set, and
1613 the values for them. They should consist of alternating attribute names
1614 (such as @code{:family} or @code{:underline}) and corresponding values.
1615 Thus,
1616
1617 @example
1618 (set-face-attribute 'foo nil
1619 :width :extended
1620 :weight :bold
1621 :underline "red")
1622 @end example
1623
1624 @noindent
1625 sets the attributes @code{:width}, @code{:weight} and @code{:underline}
1626 to the corresponding values.
1627 @end defun
1628
1629 @tindex face-attribute
1630 @defun face-attribute face attribute &optional frame
1631 This returns the value of the @var{attribute} attribute of face
1632 @var{face} on @var{frame}. If @var{frame} is @code{nil},
1633 that means the selected frame (@pxref{Input Focus}).
1634
1635 If @var{frame} is @code{t}, the value is the default for
1636 @var{face} for new frames.
1637
1638 For example,
1639
1640 @example
1641 (face-attribute 'bold :weight)
1642 @result{} bold
1643 @end example
1644 @end defun
1645
1646 The functions above did not exist before Emacs 21. For compatibility
1647 with older Emacs versions, you can use the following functions to set
1648 and examine the face attributes which existed in those versions.
1649
1650 @defun set-face-foreground face color &optional frame
1651 @defunx set-face-background face color &optional frame
1652 These functions set the foreground (or background, respectively) color
1653 of face @var{face} to @var{color}. The argument @var{color} should be a
1654 string, the name of a color.
1655
1656 Certain shades of gray are implemented by stipple patterns on
1657 black-and-white screens.
1658 @end defun
1659
1660 @defun set-face-stipple face pattern &optional frame
1661 This function sets the background stipple pattern of face @var{face} to
1662 @var{pattern}. The argument @var{pattern} should be the name of a
1663 stipple pattern defined by the X server, or @code{nil} meaning don't use
1664 stipple.
1665
1666 Normally there is no need to pay attention to stipple patterns, because
1667 they are used automatically to handle certain shades of gray.
1668 @end defun
1669
1670 @defun set-face-font face font &optional frame
1671 This function sets the font of face @var{face}.
1672
1673 In Emacs 21, this actually sets the attributes @code{:family},
1674 @code{:width}, @code{:height}, @code{:weight}, and @code{:slant}
1675 according to the font name @var{font}.
1676
1677 In Emacs 20, this sets the font attribute. Once you set the font
1678 explicitly, the bold and italic attributes cease to have any effect,
1679 because the precise font that you specified is used.
1680 @end defun
1681
1682 @defun set-face-bold-p face bold-p &optional frame
1683 This function specifies whether @var{face} should be bold. If
1684 @var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no.
1685
1686 In Emacs 21, this sets the @code{:weight} attribute.
1687 In Emacs 20, it sets the @code{:bold} attribute.
1688 @end defun
1689
1690 @defun set-face-italic-p face italic-p &optional frame
1691 This function specifies whether @var{face} should be italic. If
1692 @var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no.
1693
1694 In Emacs 21, this sets the @code{:slant} attribute.
1695 In Emacs 20, it sets the @code{:italic} attribute.
1696 @end defun
1697
1698 @defun set-face-underline-p face underline-p &optional frame
1699 This function sets the underline attribute of face @var{face}.
1700 Non-@code{nil} means do underline; @code{nil} means don't.
1701 @end defun
1702
1703 @defun invert-face face &optional frame
1704 This function inverts the @code{:inverse-video} attribute of face
1705 @var{face}. If the attribute is @code{nil}, this function sets it to
1706 @code{t}, and vice versa.
1707 @end defun
1708
1709 These functions examine the attributes of a face. If you don't
1710 specify @var{frame}, they refer to the default data for new frames.
1711 They return the symbol @code{unspecified} if the face doesn't define any
1712 value for that attribute.
1713
1714 @defun face-foreground face &optional frame
1715 @defunx face-background face &optional frame
1716 These functions return the foreground color (or background color,
1717 respectively) of face @var{face}, as a string.
1718 @end defun
1719
1720 @defun face-stipple face &optional frame
1721 This function returns the name of the background stipple pattern of face
1722 @var{face}, or @code{nil} if it doesn't have one.
1723 @end defun
1724
1725 @defun face-font face &optional frame
1726 This function returns the name of the font of face @var{face}.
1727 @end defun
1728
1729 @defun face-bold-p face &optional frame
1730 This function returns @code{t} if @var{face} is bold---that is, if it is
1731 bolder than normal. It returns @code{nil} otherwise.
1732 @end defun
1733
1734 @defun face-italic-p face &optional frame
1735 This function returns @code{t} if @var{face} is italic or oblique,
1736 @code{nil} otherwise.
1737 @end defun
1738
1739 @defun face-underline-p face &optional frame
1740 This function returns the @code{:underline} attribute of face @var{face}.
1741 @end defun
1742
1743 @defun face-inverse-video-p face &optional frame
1744 This function returns the @code{:inverse-video} attribute of face @var{face}.
1745 @end defun
1746
1747 @node Merging Faces
1748 @subsection Merging Faces for Display
1749
1750 Here are the ways to specify which faces to use for display of text:
1751
1752 @itemize @bullet
1753 @item
1754 With defaults. The @code{default} face is used as the ultimate
1755 default for all text. (In Emacs 19 and 20, the @code{default}
1756 face is used only when no other face is specified.)
1757
1758 For a mode line or header line, the face @code{modeline} or
1759 @code{header-line} is used just before @code{default}.
1760
1761 @item
1762 With text properties. A character can have a @code{face} property; if
1763 so, the faces and face attributes specified there apply. @xref{Special
1764 Properties}.
1765
1766 If the character has a @code{mouse-face} property, that is used instead
1767 of the @code{face} property when the mouse is ``near enough'' to the
1768 character.
1769
1770 @item
1771 With overlays. An overlay can have @code{face} and @code{mouse-face}
1772 properties too; they apply to all the text covered by the overlay.
1773
1774 @item
1775 With a region that is active. In Transient Mark mode, the region is
1776 highlighted with the face @code{region} (@pxref{Standard Faces}).
1777
1778 @item
1779 With special glyphs. Each glyph can specify a particular face
1780 number. @xref{Glyphs}.
1781 @end itemize
1782
1783 If these various sources together specify more than one face for a
1784 particular character, Emacs merges the attributes of the various faces
1785 specified. The attributes of the faces of special glyphs come first;
1786 then comes the face for region highlighting, if appropriate;
1787 then come attributes of faces from overlays, followed by those from text
1788 properties, and last the default face.
1789
1790 When multiple overlays cover one character, an overlay with higher
1791 priority overrides those with lower priority. @xref{Overlays}.
1792
1793 In Emacs 20, if an attribute such as the font or a color is not
1794 specified in any of the above ways, the frame's own font or color is
1795 used. In newer Emacs versions, this cannot happen, because the
1796 @code{default} face specifies all attributes---in fact, the frame's own
1797 font and colors are synonymous with those of the default face.
1798
1799 @node Font Selection
1800 @subsection Font Selection
1801
1802 @dfn{Selecting a font} means mapping the specified face attributes for
1803 a character to a font that is available on a particular display. The
1804 face attributes, as determined by face merging, specify most of the
1805 font choice, but not all. Part of the choice depends on what character
1806 it is.
1807
1808 For multibyte characters, typically each font covers only one
1809 character set. So each character set (@pxref{Character Sets}) specifies
1810 a registry and encoding to use, with the character set's
1811 @code{x-charset-registry} property. Its value is a string containing
1812 the registry and the encoding, with a dash between them:
1813
1814 @example
1815 (plist-get (charset-plist 'latin-iso8859-1)
1816 'x-charset-registry)
1817 @result{} "ISO8859-1"
1818 @end example
1819
1820 Unibyte text does not have character sets, so displaying a unibyte
1821 character takes the registry and encoding from the variable
1822 @code{face-default-registry}.
1823
1824 @defvar face-default-registry
1825 This variable specifies which registry and encoding to use in choosing
1826 fonts for unibyte characters. The value is initialized at Emacs startup
1827 time from the font the user specified for Emacs.
1828 @end defvar
1829
1830 If the face specifies a fontset name, that fontset determines a
1831 pattern for fonts of the given charset. If the face specifies a font
1832 family, a font pattern is constructed.
1833
1834 Emacs tries to find an available font for the given face attributes
1835 and character's registry and encoding. If there is a font that matches
1836 exactly, it is used, of course. The hard case is when no available font
1837 exactly fits the specification. Then Emacs looks for one that is
1838 ``close''---one attribute at a time. You can specify the order to
1839 consider the attributes. In the case where a specified font family is
1840 not available, you can specify a set of mappings for alternatives to
1841 try.
1842
1843 @defvar face-font-selection-order
1844 @tindex face-font-selection-order
1845 This variable specifies the order of importance of the face attributes
1846 @code{:width}, @code{:height}, @code{:weight}, and @code{:slant}. The
1847 value should be a list containing those four symbols, in order of
1848 decreasing importance.
1849
1850 Font selection first finds the best available matches for the first
1851 attribute listed; then, among the fonts which are best in that way, it
1852 searches for the best matches in the second attribute, and so on.
1853
1854 The attributes @code{:weight} and @code{:width} have symbolic values in
1855 a range centered around @code{normal}. Matches that are more extreme
1856 (farther from @code{normal}) are somewhat preferred to matches that are
1857 less extreme (closer to @code{normal}); this is designed to ensure that
1858 non-normal faces contrast with normal ones, whenever possible.
1859
1860 The default is @code{(:width :height :weight :slant)}, which means first
1861 find the fonts closest to the specified @code{:width}, then---among the
1862 fonts with that width---find a best match for the specified font height,
1863 and so on.
1864
1865 One example of a case where this variable makes a difference is when the
1866 default font has no italic equivalent. With the default ordering, the
1867 @code{italic} face will use a non-italic font that is similar to the
1868 default one. But if you put @code{:slant} before @code{:height}, the
1869 @code{italic} face will use an italic font, even if its height is not
1870 quite right.
1871 @end defvar
1872
1873 @defvar face-font-family-alternatives
1874 @tindex face-font-family-alternatives
1875 This variable lets you specify alternative font families to try, if a
1876 given family is specified and doesn't exist. Each element should have
1877 this form:
1878
1879 @example
1880 (@var{family} @var{alternate-families}@dots{})
1881 @end example
1882
1883 If @var{family} is specified but not available, Emacs will try the other
1884 families given in @var{alternate-families}, one by one, until it finds a
1885 family that does exist.
1886 @end defvar
1887
1888 @defvar face-font-registry-alternatives
1889 @tindex face-font-registry-alternatives
1890 This variable lets you specify alternative font registries to try, if a
1891 given registry is specified and doesn't exist. Each element should have
1892 this form:
1893
1894 @example
1895 (@var{registry} @var{alternate-registries}@dots{})
1896 @end example
1897
1898 If @var{registry} is specified but not available, Emacs will try the
1899 other registries given in @var{alternate-registries}, one by one,
1900 until it finds a registry that does exist.
1901 @end defvar
1902
1903 Emacs can make use of scalable fonts, but by default it does not use
1904 them, since the use of too many or too big scalable fonts can crash
1905 XFree86 servers.
1906
1907 @defvar scalable-fonts-allowed
1908 @tindex scalable-fonts-allowed
1909 This variable controls which scalable fonts to use. A value of
1910 @code{nil}, the default, means do not use scalable fonts. @code{t}
1911 means to use any scalable font that seems appropriate for the text.
1912
1913 Otherwise, the value must be a list of regular expressions. Then a
1914 scalable font is enabled for use if its name matches any regular
1915 expression in the list. For example,
1916
1917 @example
1918 (setq scalable-fonts-allowed '("muleindian-2$"))
1919 @end example
1920
1921 @noindent
1922 allows the use of scalable fonts with registry @code{muleindian-2}.
1923 @end defvar
1924
1925 @defun clear-face-cache &optional unload-p
1926 @tindex clear-face-cache
1927 This function clears the face cache for all frames.
1928 If @var{unload-p} is non-@code{nil}, that means to unload
1929 all unused fonts as well.
1930 @end defun
1931
1932 @node Face Functions
1933 @subsection Functions for Working with Faces
1934
1935 Here are additional functions for creating and working with faces.
1936
1937 @defun make-face name
1938 This function defines a new face named @var{name}, initially with all
1939 attributes @code{nil}. It does nothing if there is already a face named
1940 @var{name}.
1941 @end defun
1942
1943 @defun face-list
1944 This function returns a list of all defined face names.
1945 @end defun
1946
1947 @defun copy-face old-face new-name &optional frame new-frame
1948 This function defines the face @var{new-name} as a copy of the existing
1949 face named @var{old-face}. It creates the face @var{new-name} if that
1950 doesn't already exist.
1951
1952 If the optional argument @var{frame} is given, this function applies
1953 only to that frame. Otherwise it applies to each frame individually,
1954 copying attributes from @var{old-face} in each frame to @var{new-face}
1955 in the same frame.
1956
1957 If the optional argument @var{new-frame} is given, then @code{copy-face}
1958 copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
1959 in @var{new-frame}.
1960 @end defun
1961
1962 @defun face-id face
1963 This function returns the face number of face @var{face}.
1964 @end defun
1965
1966 @defun face-documentation face
1967 This function returns the documentation string of face @var{face}, or
1968 @code{nil} if none was specified for it.
1969 @end defun
1970
1971 @defun face-equal face1 face2 &optional frame
1972 This returns @code{t} if the faces @var{face1} and @var{face2} have the
1973 same attributes for display.
1974 @end defun
1975
1976 @defun face-differs-from-default-p face &optional frame
1977 This returns @code{t} if the face @var{face} displays differently from
1978 the default face. A face is considered to be ``the same'' as the
1979 default face if each attribute is either the same as that of the default
1980 face, or unspecified (meaning to inherit from the default).
1981 @end defun
1982
1983 @node Auto Faces
1984 @subsection Automatic Face Assignment
1985 @cindex automatic face assignment
1986 @cindex faces, automatic choice
1987
1988 @cindex Font-Lock mode
1989 Starting with Emacs 21, a hook is available for automatically
1990 assigning faces to text in the buffer. This hook is used for part of
1991 the implementation of Font-Lock mode.
1992
1993 @tindex fontification-functions
1994 @defvar fontification-functions
1995 This variable holds a list of functions that are called by Emacs
1996 redisplay as needed to assign faces automatically to text in the buffer.
1997
1998 The functions are called in the order listed, with one argument, a
1999 buffer position @var{pos}. Each function should attempt to assign faces
2000 to the text in the current buffer starting at @var{pos}.
2001
2002 Each function should record the faces they assign by setting the
2003 @code{face} property. It should also add a non-@code{nil}
2004 @code{fontified} property for all the text it has assigned faces to.
2005 That property tells redisplay that faces have been assigned to that text
2006 already.
2007
2008 It is probably a good idea for each function to do nothing if the
2009 character after @var{pos} already has a non-@code{nil} @code{fontified}
2010 property, but this is not required. If one function overrides the
2011 assignments made by a previous one, the properties as they are
2012 after the last function finishes are the ones that really matter.
2013
2014 For efficiency, we recommend writing these functions so that they
2015 usually assign faces to around 400 to 600 characters at each call.
2016 @end defvar
2017
2018 @node Font Lookup
2019 @subsection Looking Up Fonts
2020
2021 @defun x-list-fonts pattern &optional face frame maximum
2022 This function returns a list of available font names that match
2023 @var{pattern}. If the optional arguments @var{face} and @var{frame} are
2024 specified, then the list is limited to fonts that are the same size as
2025 @var{face} currently is on @var{frame}.
2026
2027 The argument @var{pattern} should be a string, perhaps with wildcard
2028 characters: the @samp{*} character matches any substring, and the
2029 @samp{?} character matches any single character. Pattern matching
2030 of font names ignores case.
2031
2032 If you specify @var{face} and @var{frame}, @var{face} should be a face name
2033 (a symbol) and @var{frame} should be a frame.
2034
2035 The optional argument @var{maximum} sets a limit on how many fonts to
2036 return. If this is non-@code{nil}, then the return value is truncated
2037 after the first @var{maximum} matching fonts. Specifying a small value
2038 for @var{maximum} can make this function much faster, in cases where
2039 many fonts match the pattern.
2040 @end defun
2041
2042 These additional functions are available starting in Emacs 21.
2043
2044 @defun x-family-fonts &optional family frame
2045 @tindex x-family-fonts
2046 This function returns a list describing the available fonts for family
2047 @var{family} on @var{frame}. If @var{family} is omitted or @code{nil},
2048 this list applies to all families, and therefore, it contains all
2049 available fonts. Otherwise, @var{family} must be a string; it may
2050 contain the wildcards @samp{?} and @samp{*}.
2051
2052 The list describes the display that @var{frame} is on; if @var{frame} is
2053 omitted or @code{nil}, it applies to the selected frame's display
2054 (@pxref{Input Focus}).
2055
2056 The list contains a vector of the following form for each font:
2057
2058 @example
2059 [@var{family} @var{width} @var{point-size} @var{weight} @var{slant}
2060 @var{fixed-p} @var{full} @var{registry-and-encoding}]
2061 @end example
2062
2063 The first five elements correspond to face attributes; if you
2064 specify these attributes for a face, it will use this font.
2065
2066 The last three elements give additional information about the font.
2067 @var{fixed-p} is non-nil if the font is fixed-pitch. @var{full} is the
2068 full name of the font, and @var{registry-and-encoding} is a string
2069 giving the registry and encoding of the font.
2070
2071 The result list is sorted according to the current face font sort order.
2072 @end defun
2073
2074 @defun x-font-family-list &optional frame
2075 @tindex x-font-family-list
2076 This function returns a list of the font families available for
2077 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, it
2078 describes the selected frame's display (@pxref{Input Focus}).
2079
2080 The value is a list of elements of this form:
2081
2082 @example
2083 (@var{family} . @var{fixed-p})
2084 @end example
2085
2086 @noindent
2087 Here @var{family} is a font family, and @var{fixed-p} is
2088 non-@code{nil} if fonts of that family are fixed-pitch.
2089 @end defun
2090
2091 @defvar font-list-limit
2092 @tindex font-list-limit
2093 This variable specifies maximum number of fonts to consider in font
2094 matching. The function @code{x-family-fonts} will not return more than
2095 that many fonts, and font selection will consider only that many fonts
2096 when searching a matching font for face attributes. The default is
2097 currently 100.
2098 @end defvar
2099
2100 @node Fontsets
2101 @subsection Fontsets
2102
2103 A @dfn{fontset} is a list of fonts, each assigned to a range of
2104 character codes. An individual font cannot display the whole range of
2105 characters that Emacs supports, but a fontset can. Fontsets have names,
2106 just as fonts do, and you can use a fontset name in place of a font name
2107 when you specify the ``font'' for a frame or a face. Here is
2108 information about defining a fontset under Lisp program control.
2109
2110 @defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
2111 This function defines a new fontset according to the specification
2112 string @var{fontset-spec}. The string should have this format:
2113
2114 @smallexample
2115 @var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
2116 @end smallexample
2117
2118 @noindent
2119 Whitespace characters before and after the commas are ignored.
2120
2121 The first part of the string, @var{fontpattern}, should have the form of
2122 a standard X font name, except that the last two fields should be
2123 @samp{fontset-@var{alias}}.
2124
2125 The new fontset has two names, one long and one short. The long name is
2126 @var{fontpattern} in its entirety. The short name is
2127 @samp{fontset-@var{alias}}. You can refer to the fontset by either
2128 name. If a fontset with the same name already exists, an error is
2129 signaled, unless @var{noerror} is non-@code{nil}, in which case this
2130 function does nothing.
2131
2132 If optional argument @var{style-variant-p} is non-@code{nil}, that says
2133 to create bold, italic and bold-italic variants of the fontset as well.
2134 These variant fontsets do not have a short name, only a long one, which
2135 is made by altering @var{fontpattern} to indicate the bold or italic
2136 status.
2137
2138 The specification string also says which fonts to use in the fontset.
2139 See below for the details.
2140 @end defun
2141
2142 The construct @samp{@var{charset}:@var{font}} specifies which font to
2143 use (in this fontset) for one particular character set. Here,
2144 @var{charset} is the name of a character set, and @var{font} is the font
2145 to use for that character set. You can use this construct any number of
2146 times in the specification string.
2147
2148 For the remaining character sets, those that you don't specify
2149 explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
2150 @samp{fontset-@var{alias}} with a value that names one character set.
2151 For the @sc{ascii} character set, @samp{fontset-@var{alias}} is replaced
2152 with @samp{ISO8859-1}.
2153
2154 In addition, when several consecutive fields are wildcards, Emacs
2155 collapses them into a single wildcard. This is to prevent use of
2156 auto-scaled fonts. Fonts made by scaling larger fonts are not usable
2157 for editing, and scaling a smaller font is not useful because it is
2158 better to use the smaller font in its own size, which Emacs does.
2159
2160 Thus if @var{fontpattern} is this,
2161
2162 @example
2163 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
2164 @end example
2165
2166 @noindent
2167 the font specification for @sc{ascii} characters would be this:
2168
2169 @example
2170 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
2171 @end example
2172
2173 @noindent
2174 and the font specification for Chinese GB2312 characters would be this:
2175
2176 @example
2177 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
2178 @end example
2179
2180 You may not have any Chinese font matching the above font
2181 specification. Most X distributions include only Chinese fonts that
2182 have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
2183 such a case, @samp{Fontset-@var{n}} can be specified as below:
2184
2185 @smallexample
2186 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
2187 chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
2188 @end smallexample
2189
2190 @noindent
2191 Then, the font specifications for all but Chinese GB2312 characters have
2192 @samp{fixed} in the @var{family} field, and the font specification for
2193 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
2194 field.
2195
2196 @node Display Property
2197 @section The @code{display} Property
2198 @cindex display specification
2199 @kindex display @r{(text property)}
2200
2201 The @code{display} text property (or overlay property) is used to
2202 insert images into text, and also control other aspects of how text
2203 displays. These features are available starting in Emacs 21. The value
2204 of the @code{display} property should be a display specification, or a
2205 list or vector containing several display specifications. The rest of
2206 this section describes several kinds of display specifications and what
2207 they mean.
2208
2209 @menu
2210 * Specified Space:: Displaying one space with a specified width.
2211 * Other Display Specs:: Displaying an image; magnifying text; moving it
2212 up or down on the page; adjusting the width
2213 of spaces within text.
2214 * Display Margins:: Displaying text or images to the side of the main text.
2215 * Conditional Display:: Making any of the above features conditional
2216 depending on some Lisp expression.
2217 @end menu
2218
2219 @node Specified Space
2220 @subsection Specified Spaces
2221 @cindex spaces, specified height or width
2222 @cindex specified spaces
2223 @cindex variable-width spaces
2224
2225 To display a space of specified width and/or height, use a display
2226 specification of the form @code{(space . @var{props})}, where
2227 @var{props} is a property list (a list of alternating properties and
2228 values). You can put this property on one or more consecutive
2229 characters; a space of the specified height and width is displayed in
2230 place of @emph{all} of those characters. These are the properties you
2231 can use to specify the weight of the space:
2232
2233 @table @code
2234 @item :width @var{width}
2235 Specifies that the space width should be @var{width} times the normal
2236 character width. @var{width} can be an integer or floating point
2237 number.
2238
2239 @item :relative-width @var{factor}
2240 Specifies that the width of the stretch should be computed from the
2241 first character in the group of consecutive characters that have the
2242 same @code{display} property. The space width is the width of that
2243 character, multiplied by @var{factor}.
2244
2245 @item :align-to @var{hpos}
2246 Specifies that the space should be wide enough to reach @var{hpos}. The
2247 value @var{hpos} is measured in units of the normal character width. It
2248 may be an interer or a floating point number.
2249 @end table
2250
2251 Exactly one of the above properties should be used. You can also
2252 specify the height of the space, with other properties:
2253
2254 @table @code
2255 @item :height @var{height}
2256 Specifies the height of the space, as @var{height},
2257 measured in terms of the normal line height.
2258
2259 @item :relative-height @var{factor}
2260 Specifies the height of the space, multiplying the ordinary height
2261 of the text having this display specification by @var{factor}.
2262
2263 @item :ascent @var{ascent}
2264 Specifies that @var{ascent} percent of the height of the space should be
2265 considered as the ascent of the space---that is, the part above the
2266 baseline. The value of @var{ascent} must be a non-negative number no
2267 greater than 100.
2268 @end table
2269
2270 You should not use both @code{:height} and @code{:relative-height}
2271 together.
2272
2273 @node Other Display Specs
2274 @subsection Other Display Specifications
2275
2276 @table @code
2277 @item (image . @var{image-props})
2278 This is in fact an image descriptor (@pxref{Images}). When used as a
2279 display specification, it means to display the image instead of the text
2280 that has the display specification.
2281
2282 @item ((margin nil) @var{string})
2283 @itemx @var{string}
2284 A display specification of this form means to display @var{string}
2285 instead of the text that has the display specification, at the same
2286 position as that text. This is a special case of marginal display
2287 (@pxref{Display Margins}).
2288
2289 Recursive display specifications are not supported, i.e.@: string
2290 display specifications that have a display specification property
2291 themselves.
2292
2293 @item (space-width @var{factor})
2294 This display specification affects all the space characters within the
2295 text that has the specification. It displays all of these spaces
2296 @var{factor} times as wide as normal. The element @var{factor} should
2297 be an integer or float. Characters other than spaces are not affected
2298 at all; in particular, this has no effect on tab characters.
2299
2300 @item (height @var{height})
2301 This display specification makes the text taller or shorter.
2302 Here are the possibilities for @var{height}:
2303
2304 @table @asis
2305 @item @code{(+ @var{n})}
2306 This means to use a font that is @var{n} steps larger. A ``step'' is
2307 defined by the set of available fonts---specifically, those that match
2308 what was otherwise specified for this text, in all attributes except
2309 height. Each size for which a suitable font is available counts as
2310 another step. @var{n} should be an integer.
2311
2312 @item @code{(- @var{n})}
2313 This means to use a font that is @var{n} steps smaller.
2314
2315 @item a number, @var{factor}
2316 A number, @var{factor}, means to use a font that is @var{factor} times
2317 as tall as the default font.
2318
2319 @item a symbol, @var{function}
2320 A symbol is a function to compute the height. It is called with the
2321 current height as argument, and should return the new height to use.
2322
2323 @item anything else, @var{form}
2324 If the @var{height} value doesn't fit the previous possibilities, it is
2325 a form. Emacs evaluates it to get the new height, with the symbol
2326 @code{height} bound to the current specified font height.
2327 @end table
2328
2329 @item (raise @var{factor})
2330 This kind of display specification raises or lowers the text
2331 it applies to, relative to the baseline of the line.
2332
2333 @var{factor} must be a number, which is interpreted as a multiple of the
2334 height of the affected text. If it is positive, that means to display
2335 the characters raised. If it is negative, that means to display them
2336 lower down.
2337
2338 If the text also has a @code{height} display specification, that does
2339 not affect the amount of raising or lowering, which is based on the
2340 faces used for the text.
2341 @end table
2342
2343 @node Display Margins
2344 @subsection Displaying in the Margins
2345 @cindex display margins
2346 @cindex margins, display
2347
2348 A buffer can have blank areas called @dfn{display margins} on the left
2349 and on the right. Ordinary text never appears in these areas, but you
2350 can put things into the display margins using the @code{display}
2351 property.
2352
2353 To put text in the left or right display margin of the window, use a
2354 display specification of the form @code{(margin right-margin)} or
2355 @code{(margin left-margin)} on it. To put an image in a display margin,
2356 use that display specification along with the display specification for
2357 the image.
2358
2359 Before the display margins can display anything, you must give
2360 them a nonzero width. The usual way to do that is to set these
2361 variables:
2362
2363 @defvar left-margin-width
2364 @tindex left-margin-width
2365 This variable specifies the width of the left margin.
2366 It is buffer-local in all buffers.
2367 @end defvar
2368
2369 @defvar right-margin-width
2370 @tindex right-margin-width
2371 This variable specifies the width of the right margin.
2372 It is buffer-local in all buffers.
2373 @end defvar
2374
2375 Setting these variables does not immediately affect the window. These
2376 variables are checked when a new buffer is displayed in the window.
2377 Thus, you can make changes take effect by calling
2378 @code{set-window-buffer}.
2379
2380 You can also set the margin widths immediately.
2381
2382 @defun set-window-margins window left &optional right
2383 @tindex set-window-margins
2384 This function specifies the margin widths for window @var{window}.
2385 The argument @var{left} controls the left margin and
2386 @var{right} controls the right margin (default @code{0}).
2387 @end defun
2388
2389 @defun window-margins &optional window
2390 @tindex window-margins
2391 This function returns the left and right margins of @var{window}
2392 as a cons cell of the form @code{(@var{left} . @var{right})}.
2393 If @var{window} is @code{nil}, the selected window is used.
2394 @end defun
2395
2396 @node Conditional Display
2397 @subsection Conditional Display Specifications
2398 @cindex conditional display specifications
2399
2400 You can make any display specification conditional. To do that,
2401 package it in another list of the form @code{(when @var{condition} .
2402 @var{spec})}. Then the specification @var{spec} applies only when
2403 @var{condition} evaluates to a non-@code{nil} value. During the
2404 evaluation, @code{object} is bound to the string or buffer having the
2405 conditional @code{display} property. @code{position} and
2406 @code{buffer-position} are bound to the position within @code{object}
2407 and the buffer position where the @code{display} property was found,
2408 respectively. Both positions can be different when @code{object} is a
2409 string.
2410
2411 @node Images
2412 @section Images
2413 @cindex images in buffers
2414
2415 To display an image in an Emacs buffer, you must first create an image
2416 descriptor, then use it as a display specifier in the @code{display}
2417 property of text that is displayed (@pxref{Display Property}). Like the
2418 @code{display} property, this feature is available starting in Emacs 21.
2419
2420 Emacs can display a number of different image formats; some of them
2421 are supported only if particular support libraries are installed on your
2422 machine. The supported image formats include XBM, XPM (needing the
2423 libraries @code{libXpm} version 3.4k and @code{libz}), GIF (needing
2424 @code{libungif} 4.1.0), Postscript, PBM, JPEG (needing the
2425 @code{libjpeg} library version v6a), TIFF (needing @code{libtiff} v3.4),
2426 and PNG (needing @code{libpng} 1.0.2).
2427
2428 You specify one of these formats with an image type symbol. The image
2429 type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
2430 @code{pbm}, @code{jpeg}, @code{tiff}, and @code{png}.
2431
2432 @defvar image-types
2433 This variable contains a list of those image type symbols that are
2434 supported in the current configuration.
2435 @end defvar
2436
2437 @menu
2438 * Image Descriptors:: How to specify an image for use in @code{:display}.
2439 * XBM Images:: Special features for XBM format.
2440 * XPM Images:: Special features for XPM format.
2441 * GIF Images:: Special features for GIF format.
2442 * Postscript Images:: Special features for Postscript format.
2443 * Other Image Types:: Various other formats are supported.
2444 * Defining Images:: Convenient ways to define an image for later use.
2445 * Showing Images:: Convenient ways to display an image once it is defined.
2446 * Image Cache:: Internal mechanisms of image display.
2447 @end menu
2448
2449 @node Image Descriptors
2450 @subsection Image Descriptors
2451 @cindex image descriptor
2452
2453 An image description is a list of the form @code{(image
2454 . @var{props})}, where @var{props} is a property list containing
2455 alternating keyword symbols (symbols whose names start with a colon) and
2456 their values. You can use any Lisp object as a property, but the only
2457 properties that have any special meaning are certain symbols, all of
2458 them keywords.
2459
2460 Every image descriptor must contain the property @code{:type
2461 @var{type}} to specify the format of the image. The value of @var{type}
2462 should be an image type symbol; for example, @code{xpm} for an image in
2463 XPM format.
2464
2465 Here is a list of other properties that are meaningful for all image
2466 types:
2467
2468 @table @code
2469 @item :file @var{file}
2470 The @code{:file} property specifies to load the image from file
2471 @var{file}. If @var{file} is not an absolute file name, it is expanded
2472 in @code{data-directory}.
2473
2474 @item :data @var{data}
2475 The @code{:data} property specifies the actual contents of the image.
2476 Each image must use either @code{:data} or @code{:file}, but not both.
2477 For most image types, the value of the @code{:data} property should be a
2478 string containing the image data; we recommend using a unibyte string.
2479
2480 Before using @code{:data}, look for further information in the section
2481 below describing the specific image format. For some image types,
2482 @code{:data} may not be supported; for some, it allows other data types;
2483 for some, @code{:data} alone is not enough, so you need to use other
2484 image properties along with @code{:data}.
2485
2486 @item :margin @var{margin}
2487 The @code{:margin} property specifies how many pixels to add as an
2488 extra margin around the image. The value, @var{margin}, must be a a
2489 non-negative number, or a pair @code{(@var{x} . @var{y})} of such
2490 numbers. If it is a pair, @var{x} specifies how many pixels to add
2491 horizontally, and @var{y} specifies how many pixels to add vertically.
2492 If @code{:margin} is not specified, the default is zero.
2493
2494 @item :ascent @var{ascent}
2495 The @code{:ascent} property specifies the amount of the image's
2496 height to use for its ascent---that is, the part above the baseline.
2497 The value, @var{ascent}, must be a number in the range 0 to 100, or
2498 the symbol @code{center}.
2499
2500 If @var{ascent} is a number, that percentage of the image's height is
2501 used for its ascent.
2502
2503 If @var{ascent} is @code{center}, the image is vertically centered
2504 around a centerline which would be the vertical centerline of text drawn
2505 at the position of the image, in the manner specified by the text
2506 properties and overlays that apply to the image.
2507
2508 If this property is omitted, it defaults to 50.
2509
2510 @item :relief @var{relief}
2511 The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle
2512 around the image. The value, @var{relief}, specifies the width of the
2513 shadow lines, in pixels. If @var{relief} is negative, shadows are drawn
2514 so that the image appears as a pressed button; otherwise, it appears as
2515 an unpressed button.
2516
2517 @item :conversion @var{algorithm}
2518 The @code{:conversion} property, if non-@code{nil}, specifies a
2519 conversion algorithm that should be applied to the image before it is
2520 displayed; the value, @var{algorithm}, specifies which algorithm.
2521
2522 @table @code
2523 @item laplace
2524 @itemx emboss
2525 Specifies the Laplace edge detection algorithm, which blurs out small
2526 differences in color while highlighting larger differences. People
2527 sometimes consider this useful for displaying the image for a
2528 ``disabled'' button.
2529
2530 @item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
2531 Specifies a general edge-detection algorithm. @var{matrix} must be
2532 either a nine-element list or a nine-element vector of numbers. A pixel
2533 at position @math{x/y} in the transformed image is computed from
2534 original pixels around that position. @var{matrix} specifies, for each
2535 pixel in the neighborhood of @math{x/y}, a factor with which that pixel
2536 will influence the transformed pixel; element @math{0} specifies the
2537 factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for
2538 the pixel at @math{x/y-1} etc., as shown below:
2539 @iftex
2540 @tex
2541 $$\pmatrix{x-1/y-1 & x/y-1 & x+1/y-1 \cr
2542 x-1/y & x/y & x+1/y \cr
2543 x-1/y+1& x/y+1 & x+1/y+1 \cr}$$
2544 @end tex
2545 @end iftex
2546 @ifnottex
2547 @display
2548 (x-1/y-1 x/y-1 x+1/y-1
2549 x-1/y x/y x+1/y
2550 x-1/y+1 x/y+1 x+1/y+1)
2551 @end display
2552 @end ifnottex
2553
2554 The resulting pixel is computed from the color intensity of the color
2555 resulting from summing up the RGB values of surrounding pixels,
2556 multiplied by the specified factors, and dividing that sum by the sum
2557 of the factors' absolute values.
2558
2559 Laplace edge-detection currently uses a matrix of
2560 @iftex
2561 @tex
2562 $$\pmatrix{1 & 0 & 0 \cr
2563 0& 0 & 0 \cr
2564 9 & 9 & -1 \cr}$$
2565 @end tex
2566 @end iftex
2567 @ifnottex
2568 @display
2569 (1 0 0
2570 0 0 0
2571 9 9 -1)
2572 @end display
2573 @end ifnottex
2574
2575 Emboss edge-detection uses a matrix of
2576 @iftex
2577 @tex
2578 $$\pmatrix{ 2 & -1 & 0 \cr
2579 -1 & 0 & 1 \cr
2580 0 & 1 & -2 \cr}$$
2581 @end tex
2582 @end iftex
2583 @ifnottex
2584 @display
2585 ( 2 -1 0
2586 -1 0 1
2587 0 1 -2)
2588 @end display
2589 @end ifnottex
2590
2591 @item disabled
2592 Specifies transforming the image so that it looks ``disabled''.
2593 @end table
2594
2595 @item :mask @var{mask}
2596 If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build
2597 a clipping mask for the image, so that the background of a frame is
2598 visible behind the image. If @var{bg} is not specified, or if @var{bg}
2599 is @code{t}, determine the background color of the image by looking at
2600 the four corners of the image, assuming the most frequently occurring
2601 color from the corners is the background color of the image. Otherwise,
2602 @var{bg} must be a list @code{(@var{red} @var{green} @var{blue})}
2603 specifying the color to assume for the background of the image.
2604
2605 If @var{mask} is nil, remove a mask from the image, if it has one. Images
2606 in some formats include a mask which can be removed by specifying
2607 @code{:mask nil}.
2608 @end table
2609
2610 @defun image-mask-p spec &optional frame
2611 @tindex image-mask-p
2612 This function returns @code{t} if image @var{spec} has a mask bitmap.
2613 @var{frame} is the frame on which the image will be displayed.
2614 @var{frame} @code{nil} or omitted means to use the selected frame
2615 (@pxref{Input Focus}).
2616 @end defun
2617
2618 @node XBM Images
2619 @subsection XBM Images
2620 @cindex XBM
2621
2622 To use XBM format, specify @code{xbm} as the image type. This image
2623 format doesn't require an external library, so images of this type are
2624 always supported.
2625
2626 Additional image properties supported for the @code{xbm} image type are:
2627
2628 @table @code
2629 @item :foreground @var{foreground}
2630 The value, @var{foreground}, should be a string specifying the image
2631 foreground color, or @code{nil} for the default color. This color is
2632 used for each pixel in the XBM that is 1. The default is the frame's
2633 foreground color.
2634
2635 @item :background @var{background}
2636 The value, @var{background}, should be a string specifying the image
2637 background color, or @code{nil} for the default color. This color is
2638 used for each pixel in the XBM that is 0. The default is the frame's
2639 background color.
2640 @end table
2641
2642 If you specify an XBM image using data within Emacs instead of an
2643 external file, use the following three properties:
2644
2645 @table @code
2646 @item :data @var{data}
2647 The value, @var{data}, specifies the contents of the image.
2648 There are three formats you can use for @var{data}:
2649
2650 @itemize @bullet
2651 @item
2652 A vector of strings or bool-vectors, each specifying one line of the
2653 image. Do specify @code{:height} and @code{:width}.
2654
2655 @item
2656 A string containing the same byte sequence as an XBM file would contain.
2657 You must not specify @code{:height} and @code{:width} in this case,
2658 because omitting them is what indicates the data has the format of an
2659 XBM file. The file contents specify the height and width of the image.
2660
2661 @item
2662 A string or a bool-vector containing the bits of the image (plus perhaps
2663 some extra bits at the end that will not be used). It should contain at
2664 least @var{width} * @code{height} bits. In this case, you must specify
2665 @code{:height} and @code{:width}, both to indicate that the string
2666 contains just the bits rather than a whole XBM file, and to specify the
2667 size of the image.
2668 @end itemize
2669
2670 @item :width @var{width}
2671 The value, @var{width}, specifies the width of the image, in pixels.
2672
2673 @item :height @var{height}
2674 The value, @var{height}, specifies the height of the image, in pixels.
2675 @end table
2676
2677 @node XPM Images
2678 @subsection XPM Images
2679 @cindex XPM
2680
2681 To use XPM format, specify @code{xpm} as the image type. The
2682 additional image property @code{:color-symbols} is also meaningful with
2683 the @code{xpm} image type:
2684
2685 @table @code
2686 @item :color-symbols @var{symbols}
2687 The value, @var{symbols}, should be an alist whose elements have the
2688 form @code{(@var{name} . @var{color})}. In each element, @var{name} is
2689 the name of a color as it appears in the image file, and @var{color}
2690 specifies the actual color to use for displaying that name.
2691 @end table
2692
2693 @node GIF Images
2694 @subsection GIF Images
2695 @cindex GIF
2696
2697 For GIF images, specify image type @code{gif}. Because of the patents
2698 in the US covering the LZW algorithm, the continued use of GIF format is
2699 a problem for the whole Internet; to end this problem, it is a good idea
2700 for everyone, even outside the US, to stop using GIFS right away
2701 (@uref{http://www.burnallgifs.org/}). But if you still want to use
2702 them, Emacs can display them.
2703
2704 @table @code
2705 @item :index @var{index}
2706 You can use @code{:index} to specify one image from a GIF file that
2707 contains more than one image. This property specifies use of image
2708 number @var{index} from the file. An error is signaled if the GIF file
2709 doesn't contain an image with index @var{index}.
2710 @end table
2711
2712 @ignore
2713 This could be used to implement limited support for animated GIFs.
2714 For example, the following function displays a multi-image GIF file
2715 at point-min in the current buffer, switching between sub-images
2716 every 0.1 seconds.
2717
2718 (defun show-anim (file max)
2719 "Display multi-image GIF file FILE which contains MAX subimages."
2720 (display-anim (current-buffer) file 0 max t))
2721
2722 (defun display-anim (buffer file idx max first-time)
2723 (when (= idx max)
2724 (setq idx 0))
2725 (let ((img (create-image file nil :image idx)))
2726 (save-excursion
2727 (set-buffer buffer)
2728 (goto-char (point-min))
2729 (unless first-time (delete-char 1))
2730 (insert-image img))
2731 (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
2732 @end ignore
2733
2734 @node Postscript Images
2735 @subsection Postscript Images
2736 @cindex Postscript images
2737
2738 To use Postscript for an image, specify image type @code{postscript}.
2739 This works only if you have Ghostscript installed. You must always use
2740 these three properties:
2741
2742 @table @code
2743 @item :pt-width @var{width}
2744 The value, @var{width}, specifies the width of the image measured in
2745 points (1/72 inch). @var{width} must be an integer.
2746
2747 @item :pt-height @var{height}
2748 The value, @var{height}, specifies the height of the image in points
2749 (1/72 inch). @var{height} must be an integer.
2750
2751 @item :bounding-box @var{box}
2752 The value, @var{box}, must be a list or vector of four integers, which
2753 specifying the bounding box of the Postscript image, analogous to the
2754 @samp{BoundingBox} comment found in Postscript files.
2755
2756 @example
2757 %%BoundingBox: 22 171 567 738
2758 @end example
2759 @end table
2760
2761 Displaying Postscript images from Lisp data is not currently
2762 implemented, but it may be implemented by the time you read this.
2763 See the @file{etc/NEWS} file to make sure.
2764
2765 @node Other Image Types
2766 @subsection Other Image Types
2767 @cindex PBM
2768
2769 For PBM images, specify image type @code{pbm}. Color, gray-scale and
2770 monochromatic images are supported. For mono PBM images, two additional
2771 image properties are supported.
2772
2773 @table @code
2774 @item :foreground @var{foreground}
2775 The value, @var{foreground}, should be a string specifying the image
2776 foreground color, or @code{nil} for the default color. This color is
2777 used for each pixel in the XBM that is 1. The default is the frame's
2778 foreground color.
2779
2780 @item :background @var{background}
2781 The value, @var{background}, should be a string specifying the image
2782 background color, or @code{nil} for the default color. This color is
2783 used for each pixel in the XBM that is 0. The default is the frame's
2784 background color.
2785 @end table
2786
2787 For JPEG images, specify image type @code{jpeg}.
2788
2789 For TIFF images, specify image type @code{tiff}.
2790
2791 For PNG images, specify image type @code{png}.
2792
2793 @node Defining Images
2794 @subsection Defining Images
2795
2796 The functions @code{create-image}, @code{defimage} and
2797 @code{find-image} provide convenient ways to create image descriptors.
2798
2799 @defun create-image file &optional type &rest props
2800 @tindex create-image
2801 This function creates and returns an image descriptor which uses the
2802 data in @var{file}.
2803
2804 The optional argument @var{type} is a symbol specifying the image type.
2805 If @var{type} is omitted or @code{nil}, @code{create-image} tries to
2806 determine the image type from the file's first few bytes, or else
2807 from the file's name.
2808
2809 The remaining arguments, @var{props}, specify additional image
2810 properties---for example,
2811
2812 @example
2813 (create-image "foo.xpm" 'xpm :heuristic-mask t)
2814 @end example
2815
2816 The function returns @code{nil} if images of this type are not
2817 supported. Otherwise it returns an image descriptor.
2818 @end defun
2819
2820 @defmac defimage symbol specs &optional doc
2821 @tindex defimage
2822 This macro defines @var{symbol} as an image name. The arguments
2823 @var{specs} is a list which specifies how to display the image.
2824 The third argument, @var{doc}, is an optional documentation string.
2825
2826 Each argument in @var{specs} has the form of a property list, and each
2827 one should specify at least the @code{:type} property and either the
2828 @code{:file} or the @code{:data} property. The value of @code{:type}
2829 should be a symbol specifying the image type, the value of
2830 @code{:file} is the file to load the image from, and the value of
2831 @code{:data} is a string containing the actual image data. Here is an
2832 example:
2833
2834 @example
2835 (defimage test-image
2836 '((:type xpm :file "~/test1.xpm")
2837 (:type xbm :file "~/test1.xbm")))
2838 @end example
2839
2840 @code{defimage} tests each argument, one by one, to see if it is
2841 usable---that is, if the type is supported and the file exists. The
2842 first usable argument is used to make an image descriptor which is
2843 stored in @var{symbol}.
2844
2845 If none of the alternatives will work, then @var{symbol} is defined
2846 as @code{nil}.
2847 @end defmac
2848
2849 @defun find-image specs
2850 @tindex find-image
2851 This function provides a convenient way to find an image satisfying one
2852 of a list of image specifications @var{specs}.
2853
2854 Each specification in @var{specs} is a property list with contents
2855 depending on image type. All specifications must at least contain the
2856 properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
2857 or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
2858 the image type, e.g.@: @code{xbm}, @var{file} is the file to load the
2859 image from, and @var{data} is a string containing the actual image data.
2860 The first specification in the list whose @var{type} is supported, and
2861 @var{file} exists, is used to construct the image specification to be
2862 returned. If no specification is satisfied, @code{nil} is returned.
2863
2864 The image is looked for first on @code{load-path} and then in
2865 @code{data-directory}.
2866 @end defun
2867
2868 @node Showing Images
2869 @subsection Showing Images
2870
2871 You can use an image descriptor by setting up the @code{display}
2872 property yourself, but it is easier to use the functions in this
2873 section.
2874
2875 @defun insert-image image &optional string area
2876 This function inserts @var{image} in the current buffer at point. The
2877 value @var{image} should be an image descriptor; it could be a value
2878 returned by @code{create-image}, or the value of a symbol defined with
2879 @code{defimage}. The argument @var{string} specifies the text to put in
2880 the buffer to hold the image.
2881
2882 The argument @var{area} specifies whether to put the image in a margin.
2883 If it is @code{left-margin}, the image appears in the left margin;
2884 @code{right-margin} specifies the right margin. If @var{area} is
2885 @code{nil} or omitted, the image is displayed at point within the
2886 buffer's text.
2887
2888 Internally, this function inserts @var{string} in the buffer, and gives
2889 it a @code{display} property which specifies @var{image}. @xref{Display
2890 Property}.
2891 @end defun
2892
2893 @defun put-image image pos &optional string area
2894 This function puts image @var{image} in front of @var{pos} in the
2895 current buffer. The argument @var{pos} should be an integer or a
2896 marker. It specifies the buffer position where the image should appear.
2897 The argument @var{string} specifies the text that should hold the image
2898 as an alternative to the default.
2899
2900 The argument @var{image} must be an image descriptor, perhaps returned
2901 by @code{create-image} or stored by @code{defimage}.
2902
2903 The argument @var{area} specifies whether to put the image in a margin.
2904 If it is @code{left-margin}, the image appears in the left margin;
2905 @code{right-margin} specifies the right margin. If @var{area} is
2906 @code{nil} or omitted, the image is displayed at point within the
2907 buffer's text.
2908
2909 Internally, this function creates an overlay, and gives it a
2910 @code{before-string} property containing text that has a @code{display}
2911 property whose value is the image. (Whew!)
2912 @end defun
2913
2914 @defun remove-images start end &optional buffer
2915 This function removes images in @var{buffer} between positions
2916 @var{start} and @var{end}. If @var{buffer} is omitted or @code{nil},
2917 images are removed from the current buffer.
2918
2919 This removes only images that were put into @var{buffer} the way
2920 @code{put-image} does it, not images that were inserted with
2921 @code{insert-image} or in other ways.
2922 @end defun
2923
2924 @defun image-size spec &optional pixels frame
2925 @tindex image-size
2926 This function returns the size of an image as a pair
2927 @w{@code{(@var{width} . @var{height})}}. @var{spec} is an image
2928 specification. @var{pixels} non-nil means return sizes measured in
2929 pixels, otherwise return sizes measured in canonical character units
2930 (fractions of the width/height of the frame's default font).
2931 @var{frame} is the frame on which the image will be displayed.
2932 @var{frame} null or omitted means use the selected frame (@pxref{Input
2933 Focus}).
2934 @end defun
2935
2936 @node Image Cache
2937 @subsection Image Cache
2938
2939 Emacs stores images in an image cache when it displays them, so it can
2940 display them again more efficiently. It removes an image from the cache
2941 when it hasn't been displayed for a specified period of time.
2942
2943 When an image is looked up in the cache, its specification is compared
2944 with cached image specifications using @code{equal}. This means that
2945 all images with equal specifications share the same image in the cache.
2946
2947 @defvar image-cache-eviction-delay
2948 @tindex image-cache-eviction-delay
2949 This variable specifies the number of seconds an image can remain in the
2950 cache without being displayed. When an image is not displayed for this
2951 length of time, Emacs removes it from the image cache.
2952
2953 If the value is @code{nil}, Emacs does not remove images from the cache
2954 except when you explicitly clear it. This mode can be useful for
2955 debugging.
2956 @end defvar
2957
2958 @defun clear-image-cache &optional frame
2959 @tindex clear-image-cache
2960 This function clears the image cache. If @var{frame} is non-@code{nil},
2961 only the cache for that frame is cleared. Otherwise all frames' caches
2962 are cleared.
2963 @end defun
2964
2965 @node Blinking
2966 @section Blinking Parentheses
2967 @cindex parenthesis matching
2968 @cindex blinking
2969 @cindex balancing parentheses
2970 @cindex close parenthesis
2971
2972 This section describes the mechanism by which Emacs shows a matching
2973 open parenthesis when the user inserts a close parenthesis.
2974
2975 @defvar blink-paren-function
2976 The value of this variable should be a function (of no arguments) to
2977 be called whenever a character with close parenthesis syntax is inserted.
2978 The value of @code{blink-paren-function} may be @code{nil}, in which
2979 case nothing is done.
2980 @end defvar
2981
2982 @defopt blink-matching-paren
2983 If this variable is @code{nil}, then @code{blink-matching-open} does
2984 nothing.
2985 @end defopt
2986
2987 @defopt blink-matching-paren-distance
2988 This variable specifies the maximum distance to scan for a matching
2989 parenthesis before giving up.
2990 @end defopt
2991
2992 @defopt blink-matching-delay
2993 This variable specifies the number of seconds for the cursor to remain
2994 at the matching parenthesis. A fraction of a second often gives
2995 good results, but the default is 1, which works on all systems.
2996 @end defopt
2997
2998 @deffn Command blink-matching-open
2999 This function is the default value of @code{blink-paren-function}. It
3000 assumes that point follows a character with close parenthesis syntax and
3001 moves the cursor momentarily to the matching opening character. If that
3002 character is not already on the screen, it displays the character's
3003 context in the echo area. To avoid long delays, this function does not
3004 search farther than @code{blink-matching-paren-distance} characters.
3005
3006 Here is an example of calling this function explicitly.
3007
3008 @smallexample
3009 @group
3010 (defun interactive-blink-matching-open ()
3011 @c Do not break this line! -- rms.
3012 @c The first line of a doc string
3013 @c must stand alone.
3014 "Indicate momentarily the start of sexp before point."
3015 (interactive)
3016 @end group
3017 @group
3018 (let ((blink-matching-paren-distance
3019 (buffer-size))
3020 (blink-matching-paren t))
3021 (blink-matching-open)))
3022 @end group
3023 @end smallexample
3024 @end deffn
3025
3026 @node Inverse Video
3027 @section Inverse Video
3028 @cindex Inverse Video
3029
3030 @defopt inverse-video
3031 @cindex highlighting
3032 This variable controls whether Emacs uses inverse video for all text
3033 on the screen. Non-@code{nil} means yes, @code{nil} means no. The
3034 default is @code{nil}.
3035 @end defopt
3036
3037 @defopt mode-line-inverse-video
3038 This variable controls the use of inverse video for mode lines and menu
3039 bars. If it is non-@code{nil}, then these lines are displayed in
3040 inverse video. Otherwise, these lines are displayed normally, just like
3041 other text. The default is @code{t}.
3042
3043 For window frames, this feature actually applies the face named
3044 @code{mode-line}; that face is normally set up as the inverse of the
3045 default face, unless you change it.
3046 @end defopt
3047
3048 @node Usual Display
3049 @section Usual Display Conventions
3050
3051 The usual display conventions define how to display each character
3052 code. You can override these conventions by setting up a display table
3053 (@pxref{Display Tables}). Here are the usual display conventions:
3054
3055 @itemize @bullet
3056 @item
3057 Character codes 32 through 126 map to glyph codes 32 through 126.
3058 Normally this means they display as themselves.
3059
3060 @item
3061 Character code 9 is a horizontal tab. It displays as whitespace
3062 up to a position determined by @code{tab-width}.
3063
3064 @item
3065 Character code 10 is a newline.
3066
3067 @item
3068 All other codes in the range 0 through 31, and code 127, display in one
3069 of two ways according to the value of @code{ctl-arrow}. If it is
3070 non-@code{nil}, these codes map to sequences of two glyphs, where the
3071 first glyph is the @sc{ascii} code for @samp{^}. (A display table can
3072 specify a glyph to use instead of @samp{^}.) Otherwise, these codes map
3073 just like the codes in the range 128 to 255.
3074
3075 On MS-DOS terminals, Emacs arranges by default for the character code
3076 127 to be mapped to the glyph code 127, which normally displays as an
3077 empty polygon. This glyph is used to display non-@sc{ascii} characters
3078 that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,,
3079 emacs, The GNU Emacs Manual}.
3080
3081 @item
3082 Character codes 128 through 255 map to sequences of four glyphs, where
3083 the first glyph is the @sc{ascii} code for @samp{\}, and the others are
3084 digit characters representing the character code in octal. (A display
3085 table can specify a glyph to use instead of @samp{\}.)
3086
3087 @item
3088 Multibyte character codes above 256 are displayed as themselves, or as a
3089 question mark or empty box if the terminal cannot display that
3090 character.
3091 @end itemize
3092
3093 The usual display conventions apply even when there is a display
3094 table, for any character whose entry in the active display table is
3095 @code{nil}. Thus, when you set up a display table, you need only
3096 specify the characters for which you want special behavior.
3097
3098 These display rules apply to carriage return (character code 13), when
3099 it appears in the buffer. But that character may not appear in the
3100 buffer where you expect it, if it was eliminated as part of end-of-line
3101 conversion (@pxref{Coding System Basics}).
3102
3103 These variables affect the way certain characters are displayed on the
3104 screen. Since they change the number of columns the characters occupy,
3105 they also affect the indentation functions. These variables also affect
3106 how the mode line is displayed; if you want to force redisplay of the
3107 mode line using the new values, call the function
3108 @code{force-mode-line-update} (@pxref{Mode Line Format}).
3109
3110 @defopt ctl-arrow
3111 @cindex control characters in display
3112 This buffer-local variable controls how control characters are
3113 displayed. If it is non-@code{nil}, they are displayed as a caret
3114 followed by the character: @samp{^A}. If it is @code{nil}, they are
3115 displayed as a backslash followed by three octal digits: @samp{\001}.
3116 @end defopt
3117
3118 @c Following may have overfull hbox.
3119 @defvar default-ctl-arrow
3120 The value of this variable is the default value for @code{ctl-arrow} in
3121 buffers that do not override it. @xref{Default Value}.
3122 @end defvar
3123
3124 @defopt indicate-empty-lines
3125 @tindex indicate-empty-lines
3126 When this is non-@code{nil}, Emacs displays a special glyph in
3127 each empty line at the end of the buffer, on terminals that
3128 support it (window systems).
3129 @end defopt
3130
3131 @defopt tab-width
3132 The value of this variable is the spacing between tab stops used for
3133 displaying tab characters in Emacs buffers. The value is in units of
3134 columns, and the default is 8. Note that this feature is completely
3135 independent of the user-settable tab stops used by the command
3136 @code{tab-to-tab-stop}. @xref{Indent Tabs}.
3137 @end defopt
3138
3139 @node Display Tables
3140 @section Display Tables
3141
3142 @cindex display table
3143 You can use the @dfn{display table} feature to control how all possible
3144 character codes display on the screen. This is useful for displaying
3145 European languages that have letters not in the @sc{ascii} character
3146 set.
3147
3148 The display table maps each character code into a sequence of
3149 @dfn{glyphs}, each glyph being a graphic that takes up one character
3150 position on the screen. You can also define how to display each glyph
3151 on your terminal, using the @dfn{glyph table}.
3152
3153 Display tables affect how the mode line is displayed; if you want to
3154 force redisplay of the mode line using a new display table, call
3155 @code{force-mode-line-update} (@pxref{Mode Line Format}).
3156
3157 @menu
3158 * Display Table Format:: What a display table consists of.
3159 * Active Display Table:: How Emacs selects a display table to use.
3160 * Glyphs:: How to define a glyph, and what glyphs mean.
3161 @end menu
3162
3163 @node Display Table Format
3164 @subsection Display Table Format
3165
3166 A display table is actually a char-table (@pxref{Char-Tables}) with
3167 @code{display-table} as its subtype.
3168
3169 @defun make-display-table
3170 This creates and returns a display table. The table initially has
3171 @code{nil} in all elements.
3172 @end defun
3173
3174 The ordinary elements of the display table are indexed by character
3175 codes; the element at index @var{c} says how to display the character
3176 code @var{c}. The value should be @code{nil} or a vector of glyph
3177 values (@pxref{Glyphs}). If an element is @code{nil}, it says to
3178 display that character according to the usual display conventions
3179 (@pxref{Usual Display}).
3180
3181 If you use the display table to change the display of newline
3182 characters, the whole buffer will be displayed as one long ``line.''
3183
3184 The display table also has six ``extra slots'' which serve special
3185 purposes. Here is a table of their meanings; @code{nil} in any slot
3186 means to use the default for that slot, as stated below.
3187
3188 @table @asis
3189 @item 0
3190 The glyph for the end of a truncated screen line (the default for this
3191 is @samp{$}). @xref{Glyphs}. Newer Emacs versions, on some platforms,
3192 display arrows to indicate truncation---the display table has no effect
3193 in these situations.
3194 @item 1
3195 The glyph for the end of a continued line (the default is @samp{\}).
3196 Newer Emacs versions, on some platforms, display curved arrows to
3197 indicate truncation---the display table has no effect in these
3198 situations.
3199 @item 2
3200 The glyph for indicating a character displayed as an octal character
3201 code (the default is @samp{\}).
3202 @item 3
3203 The glyph for indicating a control character (the default is @samp{^}).
3204 @item 4
3205 A vector of glyphs for indicating the presence of invisible lines (the
3206 default is @samp{...}). @xref{Selective Display}.
3207 @item 5
3208 The glyph used to draw the border between side-by-side windows (the
3209 default is @samp{|}). @xref{Splitting Windows}. This takes effect only
3210 when there are no scroll bars; if scroll bars are supported and in use,
3211 a scroll bar separates the two windows.
3212 @end table
3213
3214 For example, here is how to construct a display table that mimics the
3215 effect of setting @code{ctl-arrow} to a non-@code{nil} value:
3216
3217 @example
3218 (setq disptab (make-display-table))
3219 (let ((i 0))
3220 (while (< i 32)
3221 (or (= i ?\t) (= i ?\n)
3222 (aset disptab i (vector ?^ (+ i 64))))
3223 (setq i (1+ i)))
3224 (aset disptab 127 (vector ?^ ??)))
3225 @end example
3226
3227 @defun display-table-slot display-table slot
3228 This function returns the value of the extra slot @var{slot} of
3229 @var{display-table}. The argument @var{slot} may be a number from 0 to
3230 5 inclusive, or a slot name (symbol). Valid symbols are
3231 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
3232 @code{selective-display}, and @code{vertical-border}.
3233 @end defun
3234
3235 @defun set-display-table-slot display-table slot value
3236 This function stores @var{value} in the extra slot @var{slot} of
3237 @var{display-table}. The argument @var{slot} may be a number from 0 to
3238 5 inclusive, or a slot name (symbol). Valid symbols are
3239 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
3240 @code{selective-display}, and @code{vertical-border}.
3241 @end defun
3242
3243 @defun describe-display-table display-table
3244 @tindex describe-display-table
3245 This function displays a description of the display table
3246 @var{display-table} in a help buffer.
3247 @end defun
3248
3249 @deffn Command describe-current-display-table
3250 @tindex describe-current-display-table
3251 This command displays a description of the current display table in a
3252 help buffer.
3253 @end deffn
3254
3255 @node Active Display Table
3256 @subsection Active Display Table
3257 @cindex active display table
3258
3259 Each window can specify a display table, and so can each buffer. When
3260 a buffer @var{b} is displayed in window @var{w}, display uses the
3261 display table for window @var{w} if it has one; otherwise, the display
3262 table for buffer @var{b} if it has one; otherwise, the standard display
3263 table if any. The display table chosen is called the @dfn{active}
3264 display table.
3265
3266 @defun window-display-table window
3267 This function returns @var{window}'s display table, or @code{nil}
3268 if @var{window} does not have an assigned display table.
3269 @end defun
3270
3271 @defun set-window-display-table window table
3272 This function sets the display table of @var{window} to @var{table}.
3273 The argument @var{table} should be either a display table or
3274 @code{nil}.
3275 @end defun
3276
3277 @defvar buffer-display-table
3278 This variable is automatically buffer-local in all buffers; its value in
3279 a particular buffer specifies the display table for that buffer. If it
3280 is @code{nil}, that means the buffer does not have an assigned display
3281 table.
3282 @end defvar
3283
3284 @defvar standard-display-table
3285 This variable's value is the default display table, used whenever a
3286 window has no display table and neither does the buffer displayed in
3287 that window. This variable is @code{nil} by default.
3288 @end defvar
3289
3290 If there is no display table to use for a particular window---that is,
3291 if the window specifies none, its buffer specifies none, and
3292 @code{standard-display-table} is @code{nil}---then Emacs uses the usual
3293 display conventions for all character codes in that window. @xref{Usual
3294 Display}.
3295
3296 A number of functions for changing the standard display table
3297 are defined in the library @file{disp-table}.
3298
3299 @node Glyphs
3300 @subsection Glyphs
3301
3302 @cindex glyph
3303 A @dfn{glyph} is a generalization of a character; it stands for an
3304 image that takes up a single character position on the screen. Glyphs
3305 are represented in Lisp as integers, just as characters are.
3306
3307 @cindex glyph table
3308 The meaning of each integer, as a glyph, is defined by the glyph
3309 table, which is the value of the variable @code{glyph-table}.
3310
3311 @defvar glyph-table
3312 The value of this variable is the current glyph table. It should be a
3313 vector; the @var{g}th element defines glyph code @var{g}. If the value
3314 is @code{nil} instead of a vector, then all glyphs are simple (see
3315 below). The glyph table is not used on windowed displays.
3316 @end defvar
3317
3318 Here are the possible types of elements in the glyph table:
3319
3320 @table @asis
3321 @item @var{string}
3322 Send the characters in @var{string} to the terminal to output
3323 this glyph. This alternative is available on character terminals,
3324 but not under a window system.
3325
3326 @item @var{integer}
3327 Define this glyph code as an alias for glyph code @var{integer}. You
3328 can use an alias to specify a face code for the glyph; see below.
3329
3330 @item @code{nil}
3331 This glyph is simple. On an ordinary terminal, the glyph code mod
3332 524288 is the character to output. In a window system, the glyph code
3333 mod 524288 is the character to output, and the glyph code divided by
3334 524288 specifies the face number (@pxref{Face Functions}) to use while
3335 outputting it. (524288 is
3336 @ifnottex
3337 2**19.)
3338 @end ifnottex
3339 @tex
3340 $2^{19}$.)
3341 @end tex
3342 @xref{Faces}.
3343 @end table
3344
3345 If a glyph code is greater than or equal to the length of the glyph
3346 table, that code is automatically simple.
3347
3348 @defun create-glyph string
3349 @tindex create-glyph
3350 This function returns a newly-allocated glyph code which is set up to
3351 display by sending @var{string} to the terminal.
3352 @end defun
3353
3354 @node Beeping
3355 @section Beeping
3356 @cindex beeping
3357 @cindex bell
3358
3359 This section describes how to make Emacs ring the bell (or blink the
3360 screen) to attract the user's attention. Be conservative about how
3361 often you do this; frequent bells can become irritating. Also be
3362 careful not to use just beeping when signaling an error is more
3363 appropriate. (@xref{Errors}.)
3364
3365 @defun ding &optional do-not-terminate
3366 @cindex keyboard macro termination
3367 This function beeps, or flashes the screen (see @code{visible-bell} below).
3368 It also terminates any keyboard macro currently executing unless
3369 @var{do-not-terminate} is non-@code{nil}.
3370 @end defun
3371
3372 @defun beep &optional do-not-terminate
3373 This is a synonym for @code{ding}.
3374 @end defun
3375
3376 @defopt visible-bell
3377 This variable determines whether Emacs should flash the screen to
3378 represent a bell. Non-@code{nil} means yes, @code{nil} means no. This
3379 is effective on a window system, and on a character-only terminal
3380 provided the terminal's Termcap entry defines the visible bell
3381 capability (@samp{vb}).
3382 @end defopt
3383
3384 @defvar ring-bell-function
3385 If this is non-@code{nil}, it specifies how Emacs should ``ring the
3386 bell.'' Its value should be a function of no arguments. If this is
3387 non-@code{nil}, it takes precedence over the @code{visible-bell}
3388 variable.
3389 @end defvar
3390
3391 @node Window Systems
3392 @section Window Systems
3393
3394 Emacs works with several window systems, most notably the X Window
3395 System. Both Emacs and X use the term ``window'', but use it
3396 differently. An Emacs frame is a single window as far as X is
3397 concerned; the individual Emacs windows are not known to X at all.
3398
3399 @defvar window-system
3400 This variable tells Lisp programs what window system Emacs is running
3401 under. The possible values are
3402
3403 @table @code
3404 @item x
3405 @cindex X Window System
3406 Emacs is displaying using X.
3407 @item pc
3408 Emacs is displaying using MS-DOS.
3409 @item w32
3410 Emacs is displaying using Windows.
3411 @item mac
3412 Emacs is displaying using a Macintosh.
3413 @item nil
3414 Emacs is using a character-based terminal.
3415 @end table
3416 @end defvar
3417
3418 @defvar window-setup-hook
3419 This variable is a normal hook which Emacs runs after handling the
3420 initialization files. Emacs runs this hook after it has completed
3421 loading your init file, the default initialization file (if
3422 any), and the terminal-specific Lisp code, and running the hook
3423 @code{term-setup-hook}.
3424
3425 This hook is used for internal purposes: setting up communication with
3426 the window system, and creating the initial window. Users should not
3427 interfere with it.
3428 @end defvar