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, 2002
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/display
7 @node Display, Calendar, Processes, Top
10 This chapter describes a number of features related to the display
11 that Emacs presents to the user.
14 * Refresh Screen:: Clearing the screen and redrawing everything on it.
15 * Forcing Redisplay:: Forcing redisplay.
16 * Truncation:: Folding or wrapping long text lines.
17 * The Echo Area:: Where messages are displayed.
18 * Warnings:: Displaying warning messages for the user.
19 * Invisible Text:: Hiding part of the buffer text.
20 * Selective Display:: Hiding part of the buffer text (the old way).
21 * Overlay Arrow:: Display of an arrow to indicate position.
22 * Temporary Displays:: Displays that go away automatically.
23 * Overlays:: Use overlays to highlight parts of the buffer.
24 * Width:: How wide a character or string is on the screen.
25 * Faces:: A face defines a graphics style for text characters:
27 * Fringes:: Controlling window fringes.
28 * Scroll Bars:: Controlling vertical scroll bars.
29 * Display Property:: Enabling special display features.
30 * Images:: Displaying images in Emacs buffers.
31 * Blinking:: How Emacs shows the matching open parenthesis.
32 * Inverse Video:: Specifying how the screen looks.
33 * Usual Display:: The usual conventions for displaying nonprinting chars.
34 * Display Tables:: How to specify other conventions.
35 * Beeping:: Audible signal to the user.
36 * Window Systems:: Which window system is being used.
40 @section Refreshing the Screen
42 The function @code{redraw-frame} redisplays the entire contents of a
43 given frame (@pxref{Frames}).
46 @defun redraw-frame frame
47 This function clears and redisplays frame @var{frame}.
50 Even more powerful is @code{redraw-display}:
52 @deffn Command redraw-display
53 This function clears and redisplays all visible frames.
56 Processing user input takes absolute priority over redisplay. If you
57 call these functions when input is available, they do nothing
58 immediately, but a full redisplay does happen eventually---after all the
59 input has been processed.
61 Normally, suspending and resuming Emacs also refreshes the screen.
62 Some terminal emulators record separate contents for display-oriented
63 programs such as Emacs and for ordinary sequential display. If you are
64 using such a terminal, you might want to inhibit the redisplay on
67 @defvar no-redraw-on-reenter
68 @cindex suspend (cf. @code{no-redraw-on-reenter})
69 @cindex resume (cf. @code{no-redraw-on-reenter})
70 This variable controls whether Emacs redraws the entire screen after it
71 has been suspended and resumed. Non-@code{nil} means there is no need
72 to redraw, @code{nil} means redrawing is needed. The default is @code{nil}.
75 @node Forcing Redisplay
76 @section Forcing Redisplay
77 @cindex forcing redisplay
79 Emacs redisplay normally stops if input arrives, and does not happen
80 at all if input is available before it starts. Most of the time, this
81 is exactly what you want. However, you can prevent preemption by
82 binding @code{redisplay-dont-pause} to a non-@code{nil} value.
84 @tindex redisplay-dont-pause
85 @defvar redisplay-dont-pause
86 If this variable is non-@code{nil}, pending input does not
87 prevent or halt redisplay; redisplay occurs, and finishes,
88 regardless of whether input is available. This feature is available
92 You can request a display update, but only if no input is pending,
93 with @code{(sit-for 0)}. To force a display update even when input is
97 (let ((redisplay-dont-pause t))
103 @cindex line wrapping
104 @cindex continuation lines
105 @cindex @samp{$} in display
106 @cindex @samp{\} in display
108 When a line of text extends beyond the right edge of a window, the
109 line can either be continued on the next screen line, or truncated to
110 one screen line. The additional screen lines used to display a long
111 text line are called @dfn{continuation} lines. Normally, a @samp{$} in
112 the rightmost column of the window indicates truncation; a @samp{\} on
113 the rightmost column indicates a line that ``wraps'' onto the next line,
114 which is also called @dfn{continuing} the line. (The display table can
115 specify alternative indicators; see @ref{Display Tables}.)
117 On a windowed display, the @samp{$} and @samp{\} indicators are
118 replaced with graphics bitmaps displayed in the window fringes
121 Note that continuation is different from filling; continuation happens
122 on the screen only, not in the buffer contents, and it breaks a line
123 precisely at the right margin, not at a word boundary. @xref{Filling}.
125 @defopt truncate-lines
126 This buffer-local variable controls how Emacs displays lines that extend
127 beyond the right edge of the window. The default is @code{nil}, which
128 specifies continuation. If the value is non-@code{nil}, then these
131 If the variable @code{truncate-partial-width-windows} is non-@code{nil},
132 then truncation is always used for side-by-side windows (within one
133 frame) regardless of the value of @code{truncate-lines}.
136 @defopt default-truncate-lines
137 This variable is the default value for @code{truncate-lines}, for
138 buffers that do not have buffer-local values for it.
141 @defopt truncate-partial-width-windows
142 This variable controls display of lines that extend beyond the right
143 edge of the window, in side-by-side windows (@pxref{Splitting Windows}).
144 If it is non-@code{nil}, these lines are truncated; otherwise,
145 @code{truncate-lines} says what to do with them.
148 When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
149 a window, that forces truncation.
151 You can override the glyphs that indicate continuation or truncation
152 using the display table; see @ref{Display Tables}.
154 If your buffer contains @emph{very} long lines, and you use
155 continuation to display them, just thinking about them can make Emacs
156 redisplay slow. The column computation and indentation functions also
157 become slow. Then you might find it advisable to set
158 @code{cache-long-line-scans} to @code{t}.
160 @defvar cache-long-line-scans
161 If this variable is non-@code{nil}, various indentation and motion
162 functions, and Emacs redisplay, cache the results of scanning the
163 buffer, and consult the cache to avoid rescanning regions of the buffer
164 unless they are modified.
166 Turning on the cache slows down processing of short lines somewhat.
168 This variable is automatically buffer-local in every buffer.
172 @section The Echo Area
173 @cindex error display
176 The @dfn{echo area} is used for displaying messages made with the
177 @code{message} primitive, and for echoing keystrokes. It is not the
178 same as the minibuffer, despite the fact that the minibuffer appears
179 (when active) in the same place on the screen as the echo area. The
180 @cite{GNU Emacs Manual} specifies the rules for resolving conflicts
181 between the echo area and the minibuffer for use of that screen space
182 (@pxref{Minibuffer,, The Minibuffer, emacs, The GNU Emacs Manual}).
183 Error messages appear in the echo area; see @ref{Errors}.
185 You can write output in the echo area by using the Lisp printing
186 functions with @code{t} as the stream (@pxref{Output Functions}), or as
189 @defun message string &rest arguments
190 This function displays a message in the echo area. The
191 argument @var{string} is similar to a C language @code{printf} control
192 string. See @code{format} in @ref{String Conversion}, for the details
193 on the conversion specifications. @code{message} returns the
196 In batch mode, @code{message} prints the message text on the standard
197 error stream, followed by a newline.
199 If @var{string}, or strings among the @var{arguments}, have @code{face}
200 text properties, these affect the way the message is displayed.
203 If @var{string} is @code{nil}, @code{message} clears the echo area; if
204 the echo area has been expanded automatically, this brings it back to
205 its normal size. If the minibuffer is active, this brings the
206 minibuffer contents back onto the screen immediately.
208 @vindex message-truncate-lines
209 Normally, displaying a long message resizes the echo area to display
210 the entire message. But if the variable @code{message-truncate-lines}
211 is non-@code{nil}, the echo area does not resize, and the message is
212 truncated to fit it, as in Emacs 20 and before.
216 (message "Minibuffer depth is %d."
218 @print{} Minibuffer depth is 0.
219 @result{} "Minibuffer depth is 0."
223 ---------- Echo Area ----------
224 Minibuffer depth is 0.
225 ---------- Echo Area ----------
229 To automatically display a message in the echo area or in a pop-buffer,
230 depending on its size, use @code{display-message-or-buffer}.
233 @tindex with-temp-message
234 @defmac with-temp-message message &rest body
235 This construct displays a message in the echo area temporarily, during
236 the execution of @var{body}. It displays @var{message}, executes
237 @var{body}, then returns the value of the last body form while restoring
238 the previous echo area contents.
241 @defun message-or-box string &rest arguments
242 This function displays a message like @code{message}, but may display it
243 in a dialog box instead of the echo area. If this function is called in
244 a command that was invoked using the mouse---more precisely, if
245 @code{last-nonmenu-event} (@pxref{Command Loop Info}) is either
246 @code{nil} or a list---then it uses a dialog box or pop-up menu to
247 display the message. Otherwise, it uses the echo area. (This is the
248 same criterion that @code{y-or-n-p} uses to make a similar decision; see
249 @ref{Yes-or-No Queries}.)
251 You can force use of the mouse or of the echo area by binding
252 @code{last-nonmenu-event} to a suitable value around the call.
255 @defun message-box string &rest arguments
256 This function displays a message like @code{message}, but uses a dialog
257 box (or a pop-up menu) whenever that is possible. If it is impossible
258 to use a dialog box or pop-up menu, because the terminal does not
259 support them, then @code{message-box} uses the echo area, like
263 @defun display-message-or-buffer message &optional buffer-name not-this-window frame
264 @tindex display-message-or-buffer
265 This function displays the message @var{message}, which may be either a
266 string or a buffer. If it is shorter than the maximum height of the
267 echo area, as defined by @code{max-mini-window-height}, it is displayed
268 in the echo area, using @code{message}. Otherwise,
269 @code{display-buffer} is used to show it in a pop-up buffer.
271 Returns either the string shown in the echo area, or when a pop-up
272 buffer is used, the window used to display it.
274 If @var{message} is a string, then the optional argument
275 @var{buffer-name} is the name of the buffer used to display it when a
276 pop-up buffer is used, defaulting to @samp{*Message*}. In the case
277 where @var{message} is a string and displayed in the echo area, it is
278 not specified whether the contents are inserted into the buffer anyway.
280 The optional arguments @var{not-this-window} and @var{frame} are as for
281 @code{display-buffer}, and only used if a buffer is displayed.
284 @defun current-message
285 This function returns the message currently being displayed in the
286 echo area, or @code{nil} if there is none.
289 @defvar cursor-in-echo-area
290 This variable controls where the cursor appears when a message is
291 displayed in the echo area. If it is non-@code{nil}, then the cursor
292 appears at the end of the message. Otherwise, the cursor appears at
293 point---not in the echo area at all.
295 The value is normally @code{nil}; Lisp programs bind it to @code{t}
296 for brief periods of time.
299 @defvar echo-area-clear-hook
300 This normal hook is run whenever the echo area is cleared---either by
301 @code{(message nil)} or for any other reason.
304 Almost all the messages displayed in the echo area are also recorded
305 in the @samp{*Messages*} buffer.
307 @defopt message-log-max
308 This variable specifies how many lines to keep in the @samp{*Messages*}
309 buffer. The value @code{t} means there is no limit on how many lines to
310 keep. The value @code{nil} disables message logging entirely. Here's
311 how to display a message and prevent it from being logged:
314 (let (message-log-max)
319 @defvar echo-keystrokes
320 This variable determines how much time should elapse before command
321 characters echo. Its value must be an integer or floating point number,
323 number of seconds to wait before echoing. If the user types a prefix
324 key (such as @kbd{C-x}) and then delays this many seconds before
325 continuing, the prefix key is echoed in the echo area. (Once echoing
326 begins in a key sequence, all subsequent characters in the same key
327 sequence are echoed immediately.)
329 If the value is zero, then command input is not echoed.
333 @section Reporting Warnings
336 @dfn{Warnings} are a facility for a program to inform the user of a
337 possible problem, but continue running.
340 * Warning Basics:: Warnings concepts and functions to report them.
341 * Warning Variables:: Variables programs bind to customize their warnings.
342 * Warning Options:: Variables users set to control display of warnings.
346 @subsection Warning Basics
347 @cindex severity level
349 Every warning has a textual message, which explains the problem for
350 the user, and a @dfn{severity level} which is a symbol. Here are the
351 possible severity levels, in order of decreasing severity, and their
356 A problem that will seriously impair Emacs operation soon
357 if you do not attend to it promptly.
359 A report of data or circumstances that are inherently wrong.
361 A report of data or circumstances that are not inherently wrong, but
362 raise suspicion of a possible problem.
364 A report of information that may be useful if you are debugging.
367 When your program encounters invalid input data, it can either
368 signal a Lisp error by calling @code{error} or @code{signal} or report
369 a warning with severity @code{:error}. Signaling a Lisp error is the
370 easiest thing to do, but it means the program cannot continue
371 processing. If you want to take the trouble to implement a way to
372 continue processing despite the bad data, then reporting a warning of
373 severity @code{:error} is the right way to inform the user of the
374 problem. For instance, the Emacs Lisp byte compiler can report an
375 error that way and continue compiling other functions. (If the
376 program signals a Lisp error and then handles it with
377 @code{condition-case}, the user won't see the error message; it could
378 show the message to the user by reporting it as a warning.)
381 Each warning has a @dfn{warning type} to classify it. The type is a
382 list of symbols. The first symbol should be the custom group that you
383 use for the program's user options. For example, byte compiler
384 warnings use the warning type @code{(bytecomp)}. You can also
385 subcategorize the warnings, if you wish, by using more symbols in the
388 @defun display-warning type message &optional level buffer-name
389 This function reports a warning, using @var{message} as the message
390 and @var{type} as the warning type. @var{level} should be the
391 severity level, with @code{:warning} being the default.
393 @var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
394 for logging the warning. By default, it is @samp{*Warnings*}.
397 @defun lwarn type level message &rest args
398 This function reports a warning using the value of @code{(format
399 @var{message} @var{args}...)} as the message. In other respects it is
400 equivalent to @code{display-warning}.
403 @defun warn message &rest args
404 This function reports a warning using the value of @code{(format
405 @var{message} @var{args}...)} as the message, @code{(emacs)} as the
406 type, and @code{:warning} as the severity level. It exists for
407 compatibility only; we recommend not using it, because you should
408 specify a specific warning type.
411 @node Warning Variables
412 @subsection Warning Variables
414 Programs can customize how their warnings appear by binding
415 the variables described in this section.
417 @defvar warning-levels
418 This list defines the meaning and severity order of the warning
419 severity levels. Each element defines one severity level,
420 and they are arranged in order of decreasing severity.
422 Each element has the form @code{(@var{level} @var{string}
423 @var{function})}, where @var{level} is the severity level it defines.
424 @var{string} specifies the textual description of this level.
425 @var{string} should use @samp{%s} to specify where to put the warning
426 type information, or it can omit the @samp{%s} so as not to include
429 The optional @var{function}, if non-@code{nil}, is a function to call
430 with no arguments, to get the user's attention.
432 Normally you should not change the value of this variable.
435 @defvar warning-prefix-function
436 If non-@code{nil}, te value is a function to generate prefix text for
437 warnings. Programs can bind the variable to a suitable function.
438 @code{display-warning} calls this function with the warnings buffer
439 current, and the function can insert text in it. That text becomes
440 the beginning of the warning message.
442 The function is called with two arguments, the severity level and its
443 entry in @code{warning-levels}. It should return a list to use as the
444 entry (this value need not be an actual member of
445 @code{warning-levels}). By constructing this value, the function to
446 change the severity of the warning, or specify different handling for
447 a given severity level.
449 If the variable's value is @code{nil} then there is no function
453 @defvar warning-series
454 Programs can bind this variable to @code{t} to say that the next
455 warning should begin a series. When several warnings form a series,
456 that means to leave point on the first warning of the series, rather
457 than keep move it for each warning so that it appears on the last one.
458 The series ends when the local binding is unbound and
459 @code{warning-series} becomes @code{nil} again.
461 The value can also be a symbol with a function definition. That is
462 equivalent to @code{t}, except that the next warning will also call
463 the function with no arguments with the warnings buffer current. The
464 function can insert text which will serve as a header for the series
467 Once a series has begun, the value is a marker which points to the
468 buffer position in the warnings buffer of the start of the series.
470 The variable's normal value is @code{nil}, which means to handle
471 each warning separately.
474 @defvar warning-fill-prefix
475 When this variable is non-@code{nil}, it specifies a fill prefix to
476 use for filling each warning's text.
479 @defvar warning-type-format
480 This variable specifies the format for displaying the warning type
481 in the warning message. The result of formatting the type this way
482 gets included in the message under the control of the string in the
483 entry in @code{warning-levels}. The default value is @code{" (%s)"}.
484 If you bind it to @code{""} then the warning type won't appear at
488 @node Warning Options
489 @subsection Warning Options
491 These variables are used by users to control what happens
492 when a Lisp program reports a warning.
494 @defopt warning-minimum-level
495 This user option specifies the minimum severity level that should be
496 shown immediately to the user. The default is @code{:warning}, which
497 means to immediately display all warnings except @code{:debug}
501 @defopt warning-minimum-log-level
502 This user option specifies the minimum severity level that should be
503 logged in the warnings buffer. The default is @code{:warning}, which
504 means to log all warnings except @code{:debug} warnings.
507 @defopt warning-suppress-types
508 This list specifies which warning types should not be displayed
509 immediately for the user. Each element of the list should be a list
510 of symbols. If its elements match the first elements in a warning
511 type, then that warning is not displayed immediately.
514 @defopt warning-suppress-log-types
515 This list specifies which warning types should not be logged in the
516 warnings buffer. Each element of the list should be a list of
517 symbols. If it matches the first few elements in a warning type, then
518 that warning is not logged.
521 @section Invisible Text
523 @cindex invisible text
524 You can make characters @dfn{invisible}, so that they do not appear on
525 the screen, with the @code{invisible} property. This can be either a
526 text property (@pxref{Text Properties}) or a property of an overlay
529 In the simplest case, any non-@code{nil} @code{invisible} property makes
530 a character invisible. This is the default case---if you don't alter
531 the default value of @code{buffer-invisibility-spec}, this is how the
532 @code{invisible} property works. You should normally use @code{t}
533 as the value of the @code{invisible} property if you don't plan
534 to set @code{buffer-invisibility-spec} yourself.
536 More generally, you can use the variable @code{buffer-invisibility-spec}
537 to control which values of the @code{invisible} property make text
538 invisible. This permits you to classify the text into different subsets
539 in advance, by giving them different @code{invisible} values, and
540 subsequently make various subsets visible or invisible by changing the
541 value of @code{buffer-invisibility-spec}.
543 Controlling visibility with @code{buffer-invisibility-spec} is
544 especially useful in a program to display the list of entries in a
545 database. It permits the implementation of convenient filtering
546 commands to view just a part of the entries in the database. Setting
547 this variable is very fast, much faster than scanning all the text in
548 the buffer looking for properties to change.
550 @defvar buffer-invisibility-spec
551 This variable specifies which kinds of @code{invisible} properties
552 actually make a character invisible.
556 A character is invisible if its @code{invisible} property is
557 non-@code{nil}. This is the default.
560 Each element of the list specifies a criterion for invisibility; if a
561 character's @code{invisible} property fits any one of these criteria,
562 the character is invisible. The list can have two kinds of elements:
566 A character is invisible if its @code{invisible} property value
567 is @var{atom} or if it is a list with @var{atom} as a member.
569 @item (@var{atom} . t)
570 A character is invisible if its @code{invisible} property value
571 is @var{atom} or if it is a list with @var{atom} as a member.
572 Moreover, if this character is at the end of a line and is followed
573 by a visible newline, it displays an ellipsis.
578 Two functions are specifically provided for adding elements to
579 @code{buffer-invisibility-spec} and removing elements from it.
581 @defun add-to-invisibility-spec element
582 This function adds the element @var{element} to
583 @code{buffer-invisibility-spec} (if it is not already present in that
584 list). If @code{buffer-invisibility-spec} was @code{t}, it changes to
585 a list, @code{(t)}, so that text whose @code{invisible} property
586 is @code{t} remains invisible.
589 @defun remove-from-invisibility-spec element
590 This removeds the element @var{element} from
591 @code{buffer-invisibility-spec}. This does nothing if @var{element}
595 A convention for use of @code{buffer-invisibility-spec} is that a
596 major mode should use the mode's own name as an element of
597 @code{buffer-invisibility-spec} and as the value of the
598 @code{invisible} property:
601 ;; @r{If you want to display an ellipsis:}
602 (add-to-invisibility-spec '(my-symbol . t))
603 ;; @r{If you don't want ellipsis:}
604 (add-to-invisibility-spec 'my-symbol)
606 (overlay-put (make-overlay beginning end)
607 'invisible 'my-symbol)
609 ;; @r{When done with the overlays:}
610 (remove-from-invisibility-spec '(my-symbol . t))
611 ;; @r{Or respectively:}
612 (remove-from-invisibility-spec 'my-symbol)
615 @vindex line-move-ignore-invisible
616 Ordinarily, commands that operate on text or move point do not care
617 whether the text is invisible. The user-level line motion commands
618 explicitly ignore invisible newlines if
619 @code{line-move-ignore-invisible} is non-@code{nil}, but only because
620 they are explicitly programmed to do so.
622 Incremental search can make invisible overlays visible temporarily
623 and/or permanently when a match includes invisible text. To enable
624 this, the overlay should have a non-@code{nil}
625 @code{isearch-open-invisible} property. The property value should be a
626 function to be called with the overlay as an argument. This function
627 should make the overlay visible permanently; it is used when the match
628 overlaps the overlay on exit from the search.
630 During the search, such overlays are made temporarily visible by
631 temporarily modifying their invisible and intangible properties. If you
632 want this to be done differently for a certain overlay, give it an
633 @code{isearch-open-invisible-temporary} property which is a function.
634 The function is called with two arguments: the first is the overlay, and
635 the second is @code{nil} to make the overlay visible, or @code{t} to
636 make it invisible again.
638 @node Selective Display
639 @section Selective Display
640 @cindex selective display
642 @dfn{Selective display} refers to a pair of related features for
643 hiding certain lines on the screen.
645 The first variant, explicit selective display, is designed for use in
646 a Lisp program: it controls which lines are hidden by altering the text.
647 The invisible text feature (@pxref{Invisible Text}) has partially
648 replaced this feature.
650 In the second variant, the choice of lines to hide is made
651 automatically based on indentation. This variant is designed to be a
654 The way you control explicit selective display is by replacing a
655 newline (control-j) with a carriage return (control-m). The text that
656 was formerly a line following that newline is now invisible. Strictly
657 speaking, it is temporarily no longer a line at all, since only newlines
658 can separate lines; it is now part of the previous line.
660 Selective display does not directly affect editing commands. For
661 example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly into
662 invisible text. However, the replacement of newline characters with
663 carriage return characters affects some editing commands. For example,
664 @code{next-line} skips invisible lines, since it searches only for
665 newlines. Modes that use selective display can also define commands
666 that take account of the newlines, or that make parts of the text
667 visible or invisible.
669 When you write a selectively displayed buffer into a file, all the
670 control-m's are output as newlines. This means that when you next read
671 in the file, it looks OK, with nothing invisible. The selective display
672 effect is seen only within Emacs.
674 @defvar selective-display
675 This buffer-local variable enables selective display. This means that
676 lines, or portions of lines, may be made invisible.
680 If the value of @code{selective-display} is @code{t}, then the character
681 control-m marks the start of invisible text; the control-m, and the rest
682 of the line following it, are not displayed. This is explicit selective
686 If the value of @code{selective-display} is a positive integer, then
687 lines that start with more than that many columns of indentation are not
691 When some portion of a buffer is invisible, the vertical movement
692 commands operate as if that portion did not exist, allowing a single
693 @code{next-line} command to skip any number of invisible lines.
694 However, character movement commands (such as @code{forward-char}) do
695 not skip the invisible portion, and it is possible (if tricky) to insert
696 or delete text in an invisible portion.
698 In the examples below, we show the @emph{display appearance} of the
699 buffer @code{foo}, which changes with the value of
700 @code{selective-display}. The @emph{contents} of the buffer do not
705 (setq selective-display nil)
708 ---------- Buffer: foo ----------
715 ---------- Buffer: foo ----------
719 (setq selective-display 2)
722 ---------- Buffer: foo ----------
727 ---------- Buffer: foo ----------
732 @defvar selective-display-ellipses
733 If this buffer-local variable is non-@code{nil}, then Emacs displays
734 @samp{@dots{}} at the end of a line that is followed by invisible text.
735 This example is a continuation of the previous one.
739 (setq selective-display-ellipses t)
742 ---------- Buffer: foo ----------
747 ---------- Buffer: foo ----------
751 You can use a display table to substitute other text for the ellipsis
752 (@samp{@dots{}}). @xref{Display Tables}.
756 @section The Overlay Arrow
757 @cindex overlay arrow
759 The @dfn{overlay arrow} is useful for directing the user's attention
760 to a particular line in a buffer. For example, in the modes used for
761 interface to debuggers, the overlay arrow indicates the line of code
762 about to be executed.
764 @defvar overlay-arrow-string
765 This variable holds the string to display to call attention to a
766 particular line, or @code{nil} if the arrow feature is not in use.
767 On a graphical display the contents of the string are ignored; instead a
768 glyph is displayed in the fringe area to the left of the display area.
771 @defvar overlay-arrow-position
772 This variable holds a marker that indicates where to display the overlay
773 arrow. It should point at the beginning of a line. On a non-graphical
774 display the arrow text
775 appears at the beginning of that line, overlaying any text that would
776 otherwise appear. Since the arrow is usually short, and the line
777 usually begins with indentation, normally nothing significant is
780 The overlay string is displayed only in the buffer that this marker
781 points into. Thus, only one buffer can have an overlay arrow at any
783 @c !!! overlay-arrow-position: but the overlay string may remain in the display
784 @c of some other buffer until an update is required. This should be fixed
788 You can do a similar job by creating an overlay with a
789 @code{before-string} property. @xref{Overlay Properties}.
791 @node Temporary Displays
792 @section Temporary Displays
794 Temporary displays are used by Lisp programs to put output into a
795 buffer and then present it to the user for perusal rather than for
796 editing. Many help commands use this feature.
798 @defspec with-output-to-temp-buffer buffer-name forms@dots{}
799 This function executes @var{forms} while arranging to insert any output
800 they print into the buffer named @var{buffer-name}, which is first
801 created if necessary, and put into Help mode. Finally, the buffer is
802 displayed in some window, but not selected.
804 If the @var{forms} do not change the major mode in the output buffer, so
805 that it is still Help mode at the end of their execution, then
806 @code{with-output-to-temp-buffer} makes this buffer read-only at the
807 end, and also scans it for function and variable names to make them into
808 clickable cross-references.
810 The string @var{buffer-name} specifies the temporary buffer, which
811 need not already exist. The argument must be a string, not a buffer.
812 The buffer is erased initially (with no questions asked), and it is
813 marked as unmodified after @code{with-output-to-temp-buffer} exits.
815 @code{with-output-to-temp-buffer} binds @code{standard-output} to the
816 temporary buffer, then it evaluates the forms in @var{forms}. Output
817 using the Lisp output functions within @var{forms} goes by default to
818 that buffer (but screen display and messages in the echo area, although
819 they are ``output'' in the general sense of the word, are not affected).
820 @xref{Output Functions}.
822 Several hooks are available for customizing the behavior
823 of this construct; they are listed below.
825 The value of the last form in @var{forms} is returned.
829 ---------- Buffer: foo ----------
830 This is the contents of foo.
831 ---------- Buffer: foo ----------
835 (with-output-to-temp-buffer "foo"
837 (print standard-output))
838 @result{} #<buffer foo>
840 ---------- Buffer: foo ----------
845 ---------- Buffer: foo ----------
850 @defvar temp-buffer-show-function
851 If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
852 calls it as a function to do the job of displaying a help buffer. The
853 function gets one argument, which is the buffer it should display.
855 It is a good idea for this function to run @code{temp-buffer-show-hook}
856 just as @code{with-output-to-temp-buffer} normally would, inside of
857 @code{save-selected-window} and with the chosen window and buffer
861 @defvar temp-buffer-setup-hook
862 @tindex temp-buffer-setup-hook
863 This normal hook is run by @code{with-output-to-temp-buffer} before
864 evaluating @var{body}. When the hook runs, the temporary buffer is
865 current. This hook is normally set up with a function to put the
869 @defvar temp-buffer-show-hook
870 This normal hook is run by @code{with-output-to-temp-buffer} after
871 displaying the temporary buffer. When the hook runs, the temporary buffer
872 is current, and the window it was displayed in is selected. This hook
873 is normally set up with a function to make the buffer read only, and
874 find function names and variable names in it, provided the major mode
878 @defun momentary-string-display string position &optional char message
879 This function momentarily displays @var{string} in the current buffer at
880 @var{position}. It has no effect on the undo list or on the buffer's
883 The momentary display remains until the next input event. If the next
884 input event is @var{char}, @code{momentary-string-display} ignores it
885 and returns. Otherwise, that event remains buffered for subsequent use
886 as input. Thus, typing @var{char} will simply remove the string from
887 the display, while typing (say) @kbd{C-f} will remove the string from
888 the display and later (presumably) move point forward. The argument
889 @var{char} is a space by default.
891 The return value of @code{momentary-string-display} is not meaningful.
893 If the string @var{string} does not contain control characters, you can
894 do the same job in a more general way by creating (and then subsequently
895 deleting) an overlay with a @code{before-string} property.
896 @xref{Overlay Properties}.
898 If @var{message} is non-@code{nil}, it is displayed in the echo area
899 while @var{string} is displayed in the buffer. If it is @code{nil}, a
900 default message says to type @var{char} to continue.
902 In this example, point is initially located at the beginning of the
907 ---------- Buffer: foo ----------
908 This is the contents of foo.
910 ---------- Buffer: foo ----------
914 (momentary-string-display
915 "**** Important Message! ****"
917 "Type RET when done reading")
922 ---------- Buffer: foo ----------
923 This is the contents of foo.
924 **** Important Message! ****Second line.
925 ---------- Buffer: foo ----------
927 ---------- Echo Area ----------
928 Type RET when done reading
929 ---------- Echo Area ----------
938 You can use @dfn{overlays} to alter the appearance of a buffer's text on
939 the screen, for the sake of presentation features. An overlay is an
940 object that belongs to a particular buffer, and has a specified
941 beginning and end. It also has properties that you can examine and set;
942 these affect the display of the text within the overlay.
945 * Overlay Properties:: How to read and set properties.
946 What properties do to the screen display.
947 * Managing Overlays:: Creating and moving overlays.
948 * Finding Overlays:: Searching for overlays.
951 @node Overlay Properties
952 @subsection Overlay Properties
954 Overlay properties are like text properties in that the properties that
955 alter how a character is displayed can come from either source. But in
956 most respects they are different. Text properties are considered a part
957 of the text; overlays are specifically considered not to be part of the
958 text. Thus, copying text between various buffers and strings preserves
959 text properties, but does not try to preserve overlays. Changing a
960 buffer's text properties marks the buffer as modified, while moving an
961 overlay or changing its properties does not. Unlike text property
962 changes, overlay changes are not recorded in the buffer's undo list.
963 @xref{Text Properties}, for comparison.
965 These functions are used for reading and writing the properties of an
968 @defun overlay-get overlay prop
969 This function returns the value of property @var{prop} recorded in
970 @var{overlay}, if any. If @var{overlay} does not record any value for
971 that property, but it does have a @code{category} property which is a
972 symbol, that symbol's @var{prop} property is used. Otherwise, the value
976 @defun overlay-put overlay prop value
977 This function sets the value of property @var{prop} recorded in
978 @var{overlay} to @var{value}. It returns @var{value}.
981 See also the function @code{get-char-property} which checks both
982 overlay properties and text properties for a given character.
983 @xref{Examining Properties}.
985 Many overlay properties have special meanings; here is a table
990 @kindex priority @r{(overlay property)}
991 This property's value (which should be a nonnegative integer number)
992 determines the priority of the overlay. The priority matters when two
993 or more overlays cover the same character and both specify the same
994 property; the one whose @code{priority} value is larger takes priority
995 over the other. For the @code{face} property, the higher priority
996 value does not completely replace the other; instead, its face
997 attributes override the face attributes of the lower priority
998 @code{face} property.
1000 Currently, all overlays take priority over text properties. Please
1001 avoid using negative priority values, as we have not yet decided just
1002 what they should mean.
1005 @kindex window @r{(overlay property)}
1006 If the @code{window} property is non-@code{nil}, then the overlay
1007 applies only on that window.
1010 @kindex category @r{(overlay property)}
1011 If an overlay has a @code{category} property, we call it the
1012 @dfn{category} of the overlay. It should be a symbol. The properties
1013 of the symbol serve as defaults for the properties of the overlay.
1016 @kindex face @r{(overlay property)}
1017 This property controls the way text is displayed---for example, which
1018 font and which colors. @xref{Faces}, for more information.
1020 In the simplest case, the value is a face name. It can also be a list;
1021 then each element can be any of these possibilities:
1025 A face name (a symbol or string).
1028 Starting in Emacs 21, a property list of face attributes. This has the
1029 form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
1030 face attribute name and @var{value} is a meaningful value for that
1031 attribute. With this feature, you do not need to create a face each
1032 time you want to specify a particular attribute for certain text.
1033 @xref{Face Attributes}.
1036 A cons cell of the form @code{(foreground-color . @var{color-name})} or
1037 @code{(background-color . @var{color-name})}. These elements specify
1038 just the foreground color or just the background color.
1040 @code{(foreground-color . @var{color-name})} is equivalent to
1041 @code{(:foreground @var{color-name})}, and likewise for the background.
1045 @kindex mouse-face @r{(overlay property)}
1046 This property is used instead of @code{face} when the mouse is within
1047 the range of the overlay.
1050 @kindex display @r{(overlay property)}
1051 This property activates various features that change the
1052 way text is displayed. For example, it can make text appear taller
1053 or shorter, higher or lower, wider or narrower, or replaced with an image.
1054 @xref{Display Property}.
1057 @kindex help-echo @r{(text property)}
1058 If an overlay has a @code{help-echo} property, then when you move the
1059 mouse onto the text in the overlay, Emacs displays a help string in the
1060 echo area, or in the tooltip window. For details see @ref{Text
1063 @item modification-hooks
1064 @kindex modification-hooks @r{(overlay property)}
1065 This property's value is a list of functions to be called if any
1066 character within the overlay is changed or if text is inserted strictly
1069 The hook functions are called both before and after each change.
1070 If the functions save the information they receive, and compare notes
1071 between calls, they can determine exactly what change has been made
1074 When called before a change, each function receives four arguments: the
1075 overlay, @code{nil}, and the beginning and end of the text range to be
1078 When called after a change, each function receives five arguments: the
1079 overlay, @code{t}, the beginning and end of the text range just
1080 modified, and the length of the pre-change text replaced by that range.
1081 (For an insertion, the pre-change length is zero; for a deletion, that
1082 length is the number of characters deleted, and the post-change
1083 beginning and end are equal.)
1085 @item insert-in-front-hooks
1086 @kindex insert-in-front-hooks @r{(overlay property)}
1087 This property's value is a list of functions to be called before and
1088 after inserting text right at the beginning of the overlay. The calling
1089 conventions are the same as for the @code{modification-hooks} functions.
1091 @item insert-behind-hooks
1092 @kindex insert-behind-hooks @r{(overlay property)}
1093 This property's value is a list of functions to be called before and
1094 after inserting text right at the end of the overlay. The calling
1095 conventions are the same as for the @code{modification-hooks} functions.
1098 @kindex invisible @r{(overlay property)}
1099 The @code{invisible} property can make the text in the overlay
1100 invisible, which means that it does not appear on the screen.
1101 @xref{Invisible Text}, for details.
1104 @kindex intangible @r{(overlay property)}
1105 The @code{intangible} property on an overlay works just like the
1106 @code{intangible} text property. @xref{Special Properties}, for details.
1108 @item isearch-open-invisible
1109 This property tells incremental search how to make an invisible overlay
1110 visible, permanently, if the final match overlaps it. @xref{Invisible
1113 @item isearch-open-invisible-temporary
1114 This property tells incremental search how to make an invisible overlay
1115 visible, temporarily, during the search. @xref{Invisible Text}.
1118 @kindex before-string @r{(overlay property)}
1119 This property's value is a string to add to the display at the beginning
1120 of the overlay. The string does not appear in the buffer in any
1121 sense---only on the screen.
1124 @kindex after-string @r{(overlay property)}
1125 This property's value is a string to add to the display at the end of
1126 the overlay. The string does not appear in the buffer in any
1127 sense---only on the screen.
1130 @kindex evaporate @r{(overlay property)}
1131 If this property is non-@code{nil}, the overlay is deleted automatically
1132 if it becomes empty (i.e., if its length becomes zero). However,
1133 if the overlay is @emph{already} empty, @code{evaporate} does not
1137 @cindex keymap of character (and overlays)
1138 @kindex local-map @r{(overlay property)}
1139 If this property is non-@code{nil}, it specifies a keymap for a portion
1140 of the text. The property's value replaces the buffer's local map, when
1141 the character after point is within the overlay. @xref{Active Keymaps}.
1144 @kindex keymap @r{(overlay property)}
1145 The @code{keymap} property is similar to @code{local-map} but overrides the
1146 buffer's local map (and the map specified by the @code{local-map}
1147 property) rather than replacing it.
1150 @node Managing Overlays
1151 @subsection Managing Overlays
1153 This section describes the functions to create, delete and move
1154 overlays, and to examine their contents.
1156 @defun make-overlay start end &optional buffer front-advance rear-advance
1157 This function creates and returns an overlay that belongs to
1158 @var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
1159 and @var{end} must specify buffer positions; they may be integers or
1160 markers. If @var{buffer} is omitted, the overlay is created in the
1163 The arguments @var{front-advance} and @var{rear-advance} specify the
1164 insertion type for the start of the overlay and for the end of the
1165 overlay, respectively. @xref{Marker Insertion Types}.
1168 @defun overlay-start overlay
1169 This function returns the position at which @var{overlay} starts,
1173 @defun overlay-end overlay
1174 This function returns the position at which @var{overlay} ends,
1178 @defun overlay-buffer overlay
1179 This function returns the buffer that @var{overlay} belongs to.
1182 @defun delete-overlay overlay
1183 This function deletes @var{overlay}. The overlay continues to exist as
1184 a Lisp object, and its property list is unchanged, but it ceases to be
1185 attached to the buffer it belonged to, and ceases to have any effect on
1188 A deleted overlay is not permanently disconnected. You can give it a
1189 position in a buffer again by calling @code{move-overlay}.
1192 @defun move-overlay overlay start end &optional buffer
1193 This function moves @var{overlay} to @var{buffer}, and places its bounds
1194 at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
1195 must specify buffer positions; they may be integers or markers.
1197 If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
1198 was already associated with; if @var{overlay} was deleted, it goes into
1201 The return value is @var{overlay}.
1203 This is the only valid way to change the endpoints of an overlay. Do
1204 not try modifying the markers in the overlay by hand, as that fails to
1205 update other vital data structures and can cause some overlays to be
1209 Here are some examples:
1212 ;; @r{Create an overlay.}
1213 (setq foo (make-overlay 1 10))
1214 @result{} #<overlay from 1 to 10 in display.texi>
1219 (overlay-buffer foo)
1220 @result{} #<buffer display.texi>
1221 ;; @r{Give it a property we can check later.}
1222 (overlay-put foo 'happy t)
1224 ;; @r{Verify the property is present.}
1225 (overlay-get foo 'happy)
1227 ;; @r{Move the overlay.}
1228 (move-overlay foo 5 20)
1229 @result{} #<overlay from 5 to 20 in display.texi>
1234 ;; @r{Delete the overlay.}
1235 (delete-overlay foo)
1237 ;; @r{Verify it is deleted.}
1239 @result{} #<overlay in no buffer>
1240 ;; @r{A deleted overlay has no position.}
1245 (overlay-buffer foo)
1247 ;; @r{Undelete the overlay.}
1248 (move-overlay foo 1 20)
1249 @result{} #<overlay from 1 to 20 in display.texi>
1250 ;; @r{Verify the results.}
1255 (overlay-buffer foo)
1256 @result{} #<buffer display.texi>
1257 ;; @r{Moving and deleting the overlay does not change its properties.}
1258 (overlay-get foo 'happy)
1262 @node Finding Overlays
1263 @subsection Searching for Overlays
1265 @defun overlays-at pos
1266 This function returns a list of all the overlays that cover the
1267 character at position @var{pos} in the current buffer. The list is in
1268 no particular order. An overlay contains position @var{pos} if it
1269 begins at or before @var{pos}, and ends after @var{pos}.
1271 To illustrate usage, here is a Lisp function that returns a list of the
1272 overlays that specify property @var{prop} for the character at point:
1275 (defun find-overlays-specifying (prop)
1276 (let ((overlays (overlays-at (point)))
1279 (let ((overlay (car overlays)))
1280 (if (overlay-get overlay prop)
1281 (setq found (cons overlay found))))
1282 (setq overlays (cdr overlays)))
1287 @defun overlays-in beg end
1288 This function returns a list of the overlays that overlap the region
1289 @var{beg} through @var{end}. ``Overlap'' means that at least one
1290 character is contained within the overlay and also contained within the
1291 specified region; however, empty overlays are included in the result if
1292 they are located at @var{beg}, or strictly between @var{beg} and @var{end}.
1295 @defun next-overlay-change pos
1296 This function returns the buffer position of the next beginning or end
1297 of an overlay, after @var{pos}.
1300 @defun previous-overlay-change pos
1301 This function returns the buffer position of the previous beginning or
1302 end of an overlay, before @var{pos}.
1305 Here's an easy way to use @code{next-overlay-change} to search for the
1306 next character which gets a non-@code{nil} @code{happy} property from
1307 either its overlays or its text properties (@pxref{Property Search}):
1310 (defun find-overlay-prop (prop)
1312 (while (and (not (eobp))
1313 (not (get-char-property (point) 'happy)))
1314 (goto-char (min (next-overlay-change (point))
1315 (next-single-property-change (point) 'happy))))
1322 Since not all characters have the same width, these functions let you
1323 check the width of a character. @xref{Primitive Indent}, and
1324 @ref{Screen Lines}, for related functions.
1326 @defun char-width char
1327 This function returns the width in columns of the character @var{char},
1328 if it were displayed in the current buffer and the selected window.
1331 @defun string-width string
1332 This function returns the width in columns of the string @var{string},
1333 if it were displayed in the current buffer and the selected window.
1336 @defun truncate-string-to-width string width &optional start-column padding
1337 This function returns the part of @var{string} that fits within
1338 @var{width} columns, as a new string.
1340 If @var{string} does not reach @var{width}, then the result ends where
1341 @var{string} ends. If one multi-column character in @var{string}
1342 extends across the column @var{width}, that character is not included in
1343 the result. Thus, the result can fall short of @var{width} but cannot
1346 The optional argument @var{start-column} specifies the starting column.
1347 If this is non-@code{nil}, then the first @var{start-column} columns of
1348 the string are omitted from the value. If one multi-column character in
1349 @var{string} extends across the column @var{start-column}, that
1350 character is not included.
1352 The optional argument @var{padding}, if non-@code{nil}, is a padding
1353 character added at the beginning and end of the result string, to extend
1354 it to exactly @var{width} columns. The padding character is used at the
1355 end of the result if it falls short of @var{width}. It is also used at
1356 the beginning of the result if one multi-column character in
1357 @var{string} extends across the column @var{start-column}.
1360 (truncate-string-to-width "\tab\t" 12 4)
1362 (truncate-string-to-width "\tab\t" 12 4 ?\s)
1371 A @dfn{face} is a named collection of graphical attributes: font
1372 family, foreground color, background color, optional underlining, and
1373 many others. Faces are used in Emacs to control the style of display of
1374 particular parts of the text or the frame.
1377 Each face has its own @dfn{face number}, which distinguishes faces at
1378 low levels within Emacs. However, for most purposes, you refer to
1379 faces in Lisp programs by their names.
1382 This function returns @code{t} if @var{object} is a face name symbol (or
1383 if it is a vector of the kind used internally to record face data). It
1384 returns @code{nil} otherwise.
1387 Each face name is meaningful for all frames, and by default it has the
1388 same meaning in all frames. But you can arrange to give a particular
1389 face name a special meaning in one frame if you wish.
1392 * Standard Faces:: The faces Emacs normally comes with.
1393 * Defining Faces:: How to define a face with @code{defface}.
1394 * Face Attributes:: What is in a face?
1395 * Attribute Functions:: Functions to examine and set face attributes.
1396 * Merging Faces:: How Emacs combines the faces specified for a character.
1397 * Font Selection:: Finding the best available font for a face.
1398 * Face Functions:: How to define and examine faces.
1399 * Auto Faces:: Hook for automatic face assignment.
1400 * Font Lookup:: Looking up the names of available fonts
1401 and information about them.
1402 * Fontsets:: A fontset is a collection of fonts
1403 that handle a range of character sets.
1406 @node Standard Faces
1407 @subsection Standard Faces
1409 This table lists all the standard faces and their uses. Most of them
1410 are used for displaying certain parts of the frames or certain kinds of
1411 text; you can control how those places look by customizing these faces.
1415 @kindex default @r{(face name)}
1416 This face is used for ordinary text.
1419 @kindex mode-line @r{(face name)}
1420 This face is used for the mode line of the selected window, and for
1421 menu bars when toolkit menus are not used---but only if
1422 @code{mode-line-inverse-video} is non-@code{nil}.
1425 @kindex modeline @r{(face name)}
1426 This is an alias for the @code{mode-line} face, for compatibility with
1429 @item mode-line-inactive
1430 @kindex mode-line-inactive @r{(face name)}
1431 This face is used for mode lines of non-selected windows.
1432 This face inherits from @code{mode-line}, so changes
1433 in that face affect all windows.
1436 @kindex header-line @r{(face name)}
1437 This face is used for the header lines of windows that have them.
1440 This face controls the display of menus, both their colors and their
1441 font. (This works only on certain systems.)
1444 @kindex fringe @r{(face name)}
1445 This face controls the colors of window fringes, the thin areas on
1446 either side that are used to display continuation and truncation glyphs.
1448 @item minibuffer-prompt
1449 @kindex minibuffer-prompt @r{(face name)}
1450 @vindex minibuffer-prompt-properties
1451 This face is used for the text of minibuffer prompts. By default,
1452 Emacs automatically adds this face to the value of
1453 @code{minibuffer-prompt-properties}, which is a list of text
1454 properties used to display the prompt text.
1457 @kindex scroll-bar @r{(face name)}
1458 This face controls the colors for display of scroll bars.
1461 @kindex tool-bar @r{(face name)}
1462 This face is used for display of the tool bar, if any.
1465 @kindex region @r{(face name)}
1466 This face is used for highlighting the region in Transient Mark mode.
1468 @item secondary-selection
1469 @kindex secondary-selection @r{(face name)}
1470 This face is used to show any secondary selection you have made.
1473 @kindex highlight @r{(face name)}
1474 This face is meant to be used for highlighting for various purposes.
1476 @item trailing-whitespace
1477 @kindex trailing-whitespace @r{(face name)}
1478 This face is used to display excess whitespace at the end of a line,
1479 if @code{show-trailing-whitespace} is non-@code{nil}.
1482 In contrast, these faces are provided to change the appearance of text
1483 in specific ways. You can use them on specific text, when you want
1484 the effects they produce.
1488 @kindex bold @r{(face name)}
1489 This face uses a bold font, if possible. It uses the bold variant of
1490 the frame's font, if it has one. It's up to you to choose a default
1491 font that has a bold variant, if you want to use one.
1494 @kindex italic @r{(face name)}
1495 This face uses the italic variant of the frame's font, if it has one.
1498 @kindex bold-italic @r{(face name)}
1499 This face uses the bold italic variant of the frame's font, if it has
1503 @kindex underline @r{(face name)}
1504 This face underlines text.
1507 @kindex fixed-pitch @r{(face name)}
1508 This face forces use of a particular fixed-width font.
1510 @item variable-pitch
1511 @kindex variable-pitch @r{(face name)}
1512 This face forces use of a particular variable-width font. It's
1513 reasonable to customize this to use a different variable-width font, if
1514 you like, but you should not make it a fixed-width font.
1517 @defvar show-trailing-whitespace
1518 @tindex show-trailing-whitespace
1519 If this variable is non-@code{nil}, Emacs uses the
1520 @code{trailing-whitespace} face to display any spaces and tabs at the
1524 @node Defining Faces
1525 @subsection Defining Faces
1527 The way to define a new face is with @code{defface}. This creates a
1528 kind of customization item (@pxref{Customization}) which the user can
1529 customize using the Customization buffer (@pxref{Easy Customization,,,
1530 emacs, The GNU Emacs Manual}).
1532 @defmac defface face spec doc [keyword value]...
1533 This declares @var{face} as a customizable face that defaults according
1534 to @var{spec}. You should not quote the symbol @var{face}. The
1535 argument @var{doc} specifies the face documentation. The keywords you
1536 can use in @code{defface} are the same ones that are meaningful in both
1537 @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
1539 When @code{defface} executes, it defines the face according to
1540 @var{spec}, then uses any customizations that were read from the
1541 init file (@pxref{Init File}) to override that specification.
1543 The purpose of @var{spec} is to specify how the face should appear on
1544 different kinds of terminals. It should be an alist whose elements have
1545 the form @code{(@var{display} @var{atts})}. Each element's @sc{car},
1546 @var{display}, specifies a class of terminals. The element's second element,
1547 @var{atts}, is a list of face attributes and their values; it specifies
1548 what the face should look like on that kind of terminal. The possible
1549 attributes are defined in the value of @code{custom-face-attributes}.
1551 The @var{display} part of an element of @var{spec} determines which
1552 frames the element applies to. If more than one element of @var{spec}
1553 matches a given frame, the first matching element is the only one used
1554 for that frame. There are two possibilities for @var{display}:
1558 This element of @var{spec} matches all frames. Therefore, any
1559 subsequent elements of @var{spec} are never used. Normally
1560 @code{t} is used in the last (or only) element of @var{spec}.
1563 If @var{display} is a list, each element should have the form
1564 @code{(@var{characteristic} @var{value}@dots{})}. Here
1565 @var{characteristic} specifies a way of classifying frames, and the
1566 @var{value}s are possible classifications which @var{display} should
1567 apply to. Here are the possible values of @var{characteristic}:
1571 The kind of window system the frame uses---either @code{graphic} (any
1572 graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console),
1573 @code{w32} (for MS Windows 9X/NT), or @code{tty} (a non-graphics-capable
1577 What kinds of colors the frame supports---either @code{color},
1578 @code{grayscale}, or @code{mono}.
1581 The kind of background---either @code{light} or @code{dark}.
1584 Whether or not the frame can display the face attributes given in
1585 @var{value}@dots{} (@pxref{Face Attributes}). See the documentation
1586 for the function @code{display-supports-face-attributes-p} for more
1587 information on exactly how this testing is done. @xref{Display Face
1591 If an element of @var{display} specifies more than one @var{value} for a
1592 given @var{characteristic}, any of those values is acceptable. If
1593 @var{display} has more than one element, each element should specify a
1594 different @var{characteristic}; then @emph{each} characteristic of the
1595 frame must match one of the @var{value}s specified for it in
1600 Here's how the standard face @code{region} is defined:
1605 `((((type tty) (class color))
1606 (:background "blue" :foreground "white"))
1608 (((type tty) (class mono))
1610 (((class color) (background dark))
1611 (:background "blue"))
1612 (((class color) (background light))
1613 (:background "lightblue"))
1614 (t (:background "gray")))
1616 "Basic face for highlighting the region."
1617 :group 'basic-faces)
1621 Internally, @code{defface} uses the symbol property
1622 @code{face-defface-spec} to record the face attributes specified in
1623 @code{defface}, @code{saved-face} for the attributes saved by the user
1624 with the customization buffer, and @code{face-documentation} for the
1625 documentation string.
1627 @defopt frame-background-mode
1628 This option, if non-@code{nil}, specifies the background type to use for
1629 interpreting face definitions. If it is @code{dark}, then Emacs treats
1630 all frames as if they had a dark background, regardless of their actual
1631 background colors. If it is @code{light}, then Emacs treats all frames
1632 as if they had a light background.
1635 @node Face Attributes
1636 @subsection Face Attributes
1637 @cindex face attributes
1639 The effect of using a face is determined by a fixed set of @dfn{face
1640 attributes}. This table lists all the face attributes, and what they
1641 mean. Note that in general, more than one face can be specified for a
1642 given piece of text; when that happens, the attributes of all the faces
1643 are merged to specify how to display the text. @xref{Merging Faces}.
1645 In Emacs 21, any attribute in a face can have the value
1646 @code{unspecified}. This means the face doesn't specify that attribute.
1647 In face merging, when the first face fails to specify a particular
1648 attribute, that means the next face gets a chance. However, the
1649 @code{default} face must specify all attributes.
1651 Some of these font attributes are meaningful only on certain kinds of
1652 displays---if your display cannot handle a certain attribute, the
1653 attribute is ignored. (The attributes @code{:family}, @code{:width},
1654 @code{:height}, @code{:weight}, and @code{:slant} correspond to parts of
1655 an X Logical Font Descriptor.)
1659 Font family name, or fontset name (@pxref{Fontsets}). If you specify a
1660 font family name, the wild-card characters @samp{*} and @samp{?} are
1664 Relative proportionate width, also known as the character set width or
1665 set width. This should be one of the symbols @code{ultra-condensed},
1666 @code{extra-condensed}, @code{condensed}, @code{semi-condensed},
1667 @code{normal}, @code{semi-expanded}, @code{expanded},
1668 @code{extra-expanded}, or @code{ultra-expanded}.
1671 Either the font height, an integer in units of 1/10 point, a floating
1672 point number specifying the amount by which to scale the height of any
1673 underlying face, or a function, which is called with the old height
1674 (from the underlying face), and should return the new height.
1677 Font weight---a symbol from this series (from most dense to most faint):
1678 @code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
1679 @code{normal}, @code{semi-light}, @code{light}, @code{extra-light},
1680 or @code{ultra-light}.
1682 On a text-only terminal, any weight greater than normal is displayed as
1683 extra bright, and any weight less than normal is displayed as
1684 half-bright (provided the terminal supports the feature).
1687 Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal},
1688 @code{reverse-italic}, or @code{reverse-oblique}.
1690 On a text-only terminal, slanted text is displayed as half-bright, if
1691 the terminal supports the feature.
1694 Foreground color, a string.
1697 Background color, a string.
1699 @item :inverse-video
1700 Whether or not characters should be displayed in inverse video. The
1701 value should be @code{t} (yes) or @code{nil} (no).
1704 The background stipple, a bitmap.
1706 The value can be a string; that should be the name of a file containing
1707 external-format X bitmap data. The file is found in the directories
1708 listed in the variable @code{x-bitmap-file-path}.
1710 Alternatively, the value can specify the bitmap directly, with a list
1711 of the form @code{(@var{width} @var{height} @var{data})}. Here,
1712 @var{width} and @var{height} specify the size in pixels, and
1713 @var{data} is a string containing the raw bits of the bitmap, row by
1714 row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes
1715 in the string (which should be a unibyte string for best results).
1716 This means that each row always occupies at least one whole byte.
1718 If the value is @code{nil}, that means use no stipple pattern.
1720 Normally you do not need to set the stipple attribute, because it is
1721 used automatically to handle certain shades of gray.
1724 Whether or not characters should be underlined, and in what color. If
1725 the value is @code{t}, underlining uses the foreground color of the
1726 face. If the value is a string, underlining uses that color. The
1727 value @code{nil} means do not underline.
1730 Whether or not characters should be overlined, and in what color.
1731 The value is used like that of @code{:underline}.
1733 @item :strike-through
1734 Whether or not characters should be strike-through, and in what
1735 color. The value is used like that of @code{:underline}.
1738 The name of a face from which to inherit attributes, or a list of face
1739 names. Attributes from inherited faces are merged into the face like an
1740 underlying face would be, with higher priority than underlying faces.
1743 Whether or not a box should be drawn around characters, its color, the
1744 width of the box lines, and 3D appearance.
1747 Here are the possible values of the @code{:box} attribute, and what
1755 Draw a box with lines of width 1, in the foreground color.
1758 Draw a box with lines of width 1, in color @var{color}.
1760 @item @code{(:line-width @var{width} :color @var{color} :style @var{style})}
1761 This way you can explicitly specify all aspects of the box. The value
1762 @var{width} specifies the width of the lines to draw; it defaults to 1.
1764 The value @var{color} specifies the color to draw with. The default is
1765 the foreground color of the face for simple boxes, and the background
1766 color of the face for 3D boxes.
1768 The value @var{style} specifies whether to draw a 3D box. If it is
1769 @code{released-button}, the box looks like a 3D button that is not being
1770 pressed. If it is @code{pressed-button}, the box looks like a 3D button
1771 that is being pressed. If it is @code{nil} or omitted, a plain 2D box
1775 The attributes @code{:overline}, @code{:strike-through} and
1776 @code{:box} are new in Emacs 21. The attributes @code{:family},
1777 @code{:height}, @code{:width}, @code{:weight}, @code{:slant} are also
1778 new; previous versions used the following attributes, now semi-obsolete,
1779 to specify some of the same information:
1783 This attribute specifies the font name.
1786 A non-@code{nil} value specifies a bold font.
1789 A non-@code{nil} value specifies an italic font.
1792 For compatibility, you can still set these ``attributes'' in Emacs 21,
1793 even though they are not real face attributes. Here is what that does:
1797 You can specify an X font name as the ``value'' of this ``attribute'';
1798 that sets the @code{:family}, @code{:width}, @code{:height},
1799 @code{:weight}, and @code{:slant} attributes according to the font name.
1801 If the value is a pattern with wildcards, the first font that matches
1802 the pattern is used to set these attributes.
1805 A non-@code{nil} makes the face bold; @code{nil} makes it normal.
1806 This actually works by setting the @code{:weight} attribute.
1809 A non-@code{nil} makes the face italic; @code{nil} makes it normal.
1810 This actually works by setting the @code{:slant} attribute.
1813 @defvar x-bitmap-file-path
1814 This variable specifies a list of directories for searching
1815 for bitmap files, for the @code{:stipple} attribute.
1818 @defun bitmap-spec-p object
1819 This returns @code{t} if @var{object} is a valid bitmap specification,
1820 suitable for use with @code{:stipple} (see above). It returns
1821 @code{nil} otherwise.
1824 @node Attribute Functions
1825 @subsection Face Attribute Functions
1827 You can modify the attributes of an existing face with the following
1828 functions. If you specify @var{frame}, they affect just that frame;
1829 otherwise, they affect all frames as well as the defaults that apply to
1832 @tindex set-face-attribute
1833 @defun set-face-attribute face frame &rest arguments
1834 This function sets one or more attributes of face @var{face}
1835 for frame @var{frame}. If @var{frame} is @code{nil}, it sets
1836 the attribute for all frames, and the defaults for new frames.
1838 The extra arguments @var{arguments} specify the attributes to set, and
1839 the values for them. They should consist of alternating attribute names
1840 (such as @code{:family} or @code{:underline}) and corresponding values.
1844 (set-face-attribute 'foo nil
1851 sets the attributes @code{:width}, @code{:weight} and @code{:underline}
1852 to the corresponding values.
1855 @tindex face-attribute
1856 @defun face-attribute face attribute &optional frame inherit
1857 This returns the value of the @var{attribute} attribute of face
1858 @var{face} on @var{frame}. If @var{frame} is @code{nil},
1859 that means the selected frame (@pxref{Input Focus}).
1861 If @var{frame} is @code{t}, the value is the default for
1862 @var{face} for new frames.
1864 If @var{inherit} is @code{nil}, only attributes directly defined by
1865 @var{face} are considered, so the return value may be
1866 @code{unspecified}, or a relative value. If @var{inherit} is
1867 non-@code{nil}, @var{face}'s definition of @var{attribute} is merged
1868 with the faces specified by its @code{:inherit} attribute; however the
1869 return value may still be @code{unspecified} or relative. If
1870 @var{inherit} is a face or a list of faces, then the result is further
1871 merged with that face (or faces), until it becomes specified and
1874 To ensure that the return value is always specified and absolute, use
1875 a value of @code{default} for @var{inherit}; this will resolve any
1876 unspecified or relative values by merging with the @code{default} face
1877 (which is always completely specified).
1882 (face-attribute 'bold :weight)
1887 The functions above did not exist before Emacs 21. For compatibility
1888 with older Emacs versions, you can use the following functions to set
1889 and examine the face attributes which existed in those versions.
1891 @tindex face-attribute-relative-p
1892 @defun face-attribute-relative-p attribute value
1893 This function returns non-@code{nil} if @var{value}, when used as a
1894 the value of the face attribute @var{attribute}, is relative (that is,
1895 if it modifies an underlying or inherited value of @var{attribute}).
1898 @tindex merge-face-attribute
1899 @defun merge-face-attribute attribute value1 value2
1900 If @var{value1} is a relative value for the face attribute
1901 @var{attribute}, returns it merged with the underlying value
1902 @var{value2}; otherwise, if @var{value1} is an absolute value for the
1903 face attribute @var{attribute}, returns @var{value1} unchanged.
1906 @defun set-face-foreground face color &optional frame
1907 @defunx set-face-background face color &optional frame
1908 These functions set the foreground (or background, respectively) color
1909 of face @var{face} to @var{color}. The argument @var{color} should be a
1910 string, the name of a color.
1912 Certain shades of gray are implemented by stipple patterns on
1913 black-and-white screens.
1916 @defun set-face-stipple face pattern &optional frame
1917 This function sets the background stipple pattern of face @var{face}
1918 to @var{pattern}. The argument @var{pattern} should be the name of a
1919 stipple pattern defined by the X server, or actual bitmap data
1920 (@pxref{Face Attributes}), or @code{nil} meaning don't use stipple.
1922 Normally there is no need to pay attention to stipple patterns, because
1923 they are used automatically to handle certain shades of gray.
1926 @defun set-face-font face font &optional frame
1927 This function sets the font of face @var{face}.
1929 In Emacs 21, this actually sets the attributes @code{:family},
1930 @code{:width}, @code{:height}, @code{:weight}, and @code{:slant}
1931 according to the font name @var{font}.
1933 In Emacs 20, this sets the font attribute. Once you set the font
1934 explicitly, the bold and italic attributes cease to have any effect,
1935 because the precise font that you specified is used.
1938 @defun set-face-bold-p face bold-p &optional frame
1939 This function specifies whether @var{face} should be bold. If
1940 @var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no.
1942 In Emacs 21, this sets the @code{:weight} attribute.
1943 In Emacs 20, it sets the @code{:bold} attribute.
1946 @defun set-face-italic-p face italic-p &optional frame
1947 This function specifies whether @var{face} should be italic. If
1948 @var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no.
1950 In Emacs 21, this sets the @code{:slant} attribute.
1951 In Emacs 20, it sets the @code{:italic} attribute.
1954 @defun set-face-underline-p face underline-p &optional frame
1955 This function sets the underline attribute of face @var{face}.
1956 Non-@code{nil} means do underline; @code{nil} means don't.
1959 @defun invert-face face &optional frame
1960 This function inverts the @code{:inverse-video} attribute of face
1961 @var{face}. If the attribute is @code{nil}, this function sets it to
1962 @code{t}, and vice versa.
1965 These functions examine the attributes of a face. If you don't
1966 specify @var{frame}, they refer to the default data for new frames.
1967 They return the symbol @code{unspecified} if the face doesn't define any
1968 value for that attribute.
1970 @defun face-foreground face &optional frame inherit
1971 @defunx face-background face &optional frame
1972 These functions return the foreground color (or background color,
1973 respectively) of face @var{face}, as a string.
1975 If @var{inherit} is nil, only a color directly defined by the face is
1976 returned. If @var{inherit} is non-nil, any faces specified by its
1977 @code{:inherit} attribute are considered as well, and if @var{inherit}
1978 is a face or a list of faces, then they are also considered, until a
1979 specified color is found. To ensure that the return value is always
1980 specified, use a value of @code{default} for @var{inherit}.
1983 @defun face-stipple face &optional frame inherit
1984 This function returns the name of the background stipple pattern of face
1985 @var{face}, or @code{nil} if it doesn't have one.
1987 If @var{inherit} is @code{nil}, only a stipple directly defined by the
1988 face is returned. If @var{inherit} is non-@code{nil}, any faces
1989 specified by its @code{:inherit} attribute are considered as well, and
1990 if @var{inherit} is a face or a list of faces, then they are also
1991 considered, until a specified stipple is found. To ensure that the
1992 return value is always specified, use a value of @code{default} for
1996 @defun face-font face &optional frame
1997 This function returns the name of the font of face @var{face}.
2000 @defun face-bold-p face &optional frame
2001 This function returns @code{t} if @var{face} is bold---that is, if it is
2002 bolder than normal. It returns @code{nil} otherwise.
2005 @defun face-italic-p face &optional frame
2006 This function returns @code{t} if @var{face} is italic or oblique,
2007 @code{nil} otherwise.
2010 @defun face-underline-p face &optional frame
2011 This function returns the @code{:underline} attribute of face @var{face}.
2014 @defun face-inverse-video-p face &optional frame
2015 This function returns the @code{:inverse-video} attribute of face @var{face}.
2019 @subsection Merging Faces for Display
2021 Here are the ways to specify which faces to use for display of text:
2025 With defaults. The @code{default} face is used as the ultimate
2026 default for all text. (In Emacs 19 and 20, the @code{default}
2027 face is used only when no other face is specified.)
2029 For a mode line or header line, the face @code{modeline} or
2030 @code{header-line} is used just before @code{default}.
2033 With text properties. A character can have a @code{face} property; if
2034 so, the faces and face attributes specified there apply. @xref{Special
2037 If the character has a @code{mouse-face} property, that is used instead
2038 of the @code{face} property when the mouse is ``near enough'' to the
2042 With overlays. An overlay can have @code{face} and @code{mouse-face}
2043 properties too; they apply to all the text covered by the overlay.
2046 With a region that is active. In Transient Mark mode, the region is
2047 highlighted with the face @code{region} (@pxref{Standard Faces}).
2050 With special glyphs. Each glyph can specify a particular face
2051 number. @xref{Glyphs}.
2054 If these various sources together specify more than one face for a
2055 particular character, Emacs merges the attributes of the various faces
2056 specified. The attributes of the faces of special glyphs come first;
2057 then comes the face for region highlighting, if appropriate;
2058 then come attributes of faces from overlays, followed by those from text
2059 properties, and last the default face.
2061 When multiple overlays cover one character, an overlay with higher
2062 priority overrides those with lower priority. @xref{Overlays}.
2064 In Emacs 20, if an attribute such as the font or a color is not
2065 specified in any of the above ways, the frame's own font or color is
2066 used. In newer Emacs versions, this cannot happen, because the
2067 @code{default} face specifies all attributes---in fact, the frame's own
2068 font and colors are synonymous with those of the default face.
2070 @node Font Selection
2071 @subsection Font Selection
2073 @dfn{Selecting a font} means mapping the specified face attributes for
2074 a character to a font that is available on a particular display. The
2075 face attributes, as determined by face merging, specify most of the
2076 font choice, but not all. Part of the choice depends on what character
2079 For multibyte characters, typically each font covers only one
2080 character set. So each character set (@pxref{Character Sets}) specifies
2081 a registry and encoding to use, with the character set's
2082 @code{x-charset-registry} property. Its value is a string containing
2083 the registry and the encoding, with a dash between them:
2086 (plist-get (charset-plist 'latin-iso8859-1)
2087 'x-charset-registry)
2088 @result{} "ISO8859-1"
2091 Unibyte text does not have character sets, so displaying a unibyte
2092 character takes the registry and encoding from the variable
2093 @code{face-default-registry}.
2095 @defvar face-default-registry
2096 This variable specifies which registry and encoding to use in choosing
2097 fonts for unibyte characters. The value is initialized at Emacs startup
2098 time from the font the user specified for Emacs.
2101 If the face specifies a fontset name, that fontset determines a
2102 pattern for fonts of the given charset. If the face specifies a font
2103 family, a font pattern is constructed.
2105 Emacs tries to find an available font for the given face attributes
2106 and character's registry and encoding. If there is a font that matches
2107 exactly, it is used, of course. The hard case is when no available font
2108 exactly fits the specification. Then Emacs looks for one that is
2109 ``close''---one attribute at a time. You can specify the order to
2110 consider the attributes. In the case where a specified font family is
2111 not available, you can specify a set of mappings for alternatives to
2114 @defvar face-font-selection-order
2115 @tindex face-font-selection-order
2116 This variable specifies the order of importance of the face attributes
2117 @code{:width}, @code{:height}, @code{:weight}, and @code{:slant}. The
2118 value should be a list containing those four symbols, in order of
2119 decreasing importance.
2121 Font selection first finds the best available matches for the first
2122 attribute listed; then, among the fonts which are best in that way, it
2123 searches for the best matches in the second attribute, and so on.
2125 The attributes @code{:weight} and @code{:width} have symbolic values in
2126 a range centered around @code{normal}. Matches that are more extreme
2127 (farther from @code{normal}) are somewhat preferred to matches that are
2128 less extreme (closer to @code{normal}); this is designed to ensure that
2129 non-normal faces contrast with normal ones, whenever possible.
2131 The default is @code{(:width :height :weight :slant)}, which means first
2132 find the fonts closest to the specified @code{:width}, then---among the
2133 fonts with that width---find a best match for the specified font height,
2136 One example of a case where this variable makes a difference is when the
2137 default font has no italic equivalent. With the default ordering, the
2138 @code{italic} face will use a non-italic font that is similar to the
2139 default one. But if you put @code{:slant} before @code{:height}, the
2140 @code{italic} face will use an italic font, even if its height is not
2144 @defvar face-font-family-alternatives
2145 @tindex face-font-family-alternatives
2146 This variable lets you specify alternative font families to try, if a
2147 given family is specified and doesn't exist. Each element should have
2151 (@var{family} @var{alternate-families}@dots{})
2154 If @var{family} is specified but not available, Emacs will try the other
2155 families given in @var{alternate-families}, one by one, until it finds a
2156 family that does exist.
2159 @defvar face-font-registry-alternatives
2160 @tindex face-font-registry-alternatives
2161 This variable lets you specify alternative font registries to try, if a
2162 given registry is specified and doesn't exist. Each element should have
2166 (@var{registry} @var{alternate-registries}@dots{})
2169 If @var{registry} is specified but not available, Emacs will try the
2170 other registries given in @var{alternate-registries}, one by one,
2171 until it finds a registry that does exist.
2174 Emacs can make use of scalable fonts, but by default it does not use
2175 them, since the use of too many or too big scalable fonts can crash
2178 @defvar scalable-fonts-allowed
2179 @tindex scalable-fonts-allowed
2180 This variable controls which scalable fonts to use. A value of
2181 @code{nil}, the default, means do not use scalable fonts. @code{t}
2182 means to use any scalable font that seems appropriate for the text.
2184 Otherwise, the value must be a list of regular expressions. Then a
2185 scalable font is enabled for use if its name matches any regular
2186 expression in the list. For example,
2189 (setq scalable-fonts-allowed '("muleindian-2$"))
2193 allows the use of scalable fonts with registry @code{muleindian-2}.
2196 @defun clear-face-cache &optional unload-p
2197 @tindex clear-face-cache
2198 This function clears the face cache for all frames.
2199 If @var{unload-p} is non-@code{nil}, that means to unload
2200 all unused fonts as well.
2203 @defvar face-font-rescale-alist
2204 This variable specifies scaling for certain faces. Its value should
2205 be a list of elements of the form
2208 (@var{fontname-regexp} . @var{scale-factor})
2211 If @var{fontname-regexp} matches the font name that is about to be
2212 used, this says to choose a larger similar font according to the
2213 factor @var{scale-factor}. You would use this feature to normalize
2214 the font size if certain fonts are bigger or smaller than their
2215 nominal heights and widths would suggest.
2218 @node Face Functions
2219 @subsection Functions for Working with Faces
2221 Here are additional functions for creating and working with faces.
2223 @defun make-face name
2224 This function defines a new face named @var{name}, initially with all
2225 attributes @code{nil}. It does nothing if there is already a face named
2230 This function returns a list of all defined face names.
2233 @defun copy-face old-face new-name &optional frame new-frame
2234 This function defines the face @var{new-name} as a copy of the existing
2235 face named @var{old-face}. It creates the face @var{new-name} if that
2236 doesn't already exist.
2238 If the optional argument @var{frame} is given, this function applies
2239 only to that frame. Otherwise it applies to each frame individually,
2240 copying attributes from @var{old-face} in each frame to @var{new-face}
2243 If the optional argument @var{new-frame} is given, then @code{copy-face}
2244 copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
2249 This function returns the face number of face @var{face}.
2252 @defun face-documentation face
2253 This function returns the documentation string of face @var{face}, or
2254 @code{nil} if none was specified for it.
2257 @defun face-equal face1 face2 &optional frame
2258 This returns @code{t} if the faces @var{face1} and @var{face2} have the
2259 same attributes for display.
2262 @defun face-differs-from-default-p face &optional frame
2263 This returns @code{t} if the face @var{face} displays differently from
2264 the default face. A face is considered to be ``the same'' as the
2265 default face if each attribute is either the same as that of the default
2266 face, or unspecified (meaning to inherit from the default).
2270 @subsection Automatic Face Assignment
2271 @cindex automatic face assignment
2272 @cindex faces, automatic choice
2274 @cindex Font-Lock mode
2275 Starting with Emacs 21, a hook is available for automatically
2276 assigning faces to text in the buffer. This hook is used for part of
2277 the implementation of Font-Lock mode.
2279 @tindex fontification-functions
2280 @defvar fontification-functions
2281 This variable holds a list of functions that are called by Emacs
2282 redisplay as needed to assign faces automatically to text in the buffer.
2284 The functions are called in the order listed, with one argument, a
2285 buffer position @var{pos}. Each function should attempt to assign faces
2286 to the text in the current buffer starting at @var{pos}.
2288 Each function should record the faces they assign by setting the
2289 @code{face} property. It should also add a non-@code{nil}
2290 @code{fontified} property for all the text it has assigned faces to.
2291 That property tells redisplay that faces have been assigned to that text
2294 It is probably a good idea for each function to do nothing if the
2295 character after @var{pos} already has a non-@code{nil} @code{fontified}
2296 property, but this is not required. If one function overrides the
2297 assignments made by a previous one, the properties as they are
2298 after the last function finishes are the ones that really matter.
2300 For efficiency, we recommend writing these functions so that they
2301 usually assign faces to around 400 to 600 characters at each call.
2305 @subsection Looking Up Fonts
2307 @defun x-list-fonts pattern &optional face frame maximum
2308 This function returns a list of available font names that match
2309 @var{pattern}. If the optional arguments @var{face} and @var{frame} are
2310 specified, then the list is limited to fonts that are the same size as
2311 @var{face} currently is on @var{frame}.
2313 The argument @var{pattern} should be a string, perhaps with wildcard
2314 characters: the @samp{*} character matches any substring, and the
2315 @samp{?} character matches any single character. Pattern matching
2316 of font names ignores case.
2318 If you specify @var{face} and @var{frame}, @var{face} should be a face name
2319 (a symbol) and @var{frame} should be a frame.
2321 The optional argument @var{maximum} sets a limit on how many fonts to
2322 return. If this is non-@code{nil}, then the return value is truncated
2323 after the first @var{maximum} matching fonts. Specifying a small value
2324 for @var{maximum} can make this function much faster, in cases where
2325 many fonts match the pattern.
2328 These additional functions are available starting in Emacs 21.
2330 @defun x-family-fonts &optional family frame
2331 @tindex x-family-fonts
2332 This function returns a list describing the available fonts for family
2333 @var{family} on @var{frame}. If @var{family} is omitted or @code{nil},
2334 this list applies to all families, and therefore, it contains all
2335 available fonts. Otherwise, @var{family} must be a string; it may
2336 contain the wildcards @samp{?} and @samp{*}.
2338 The list describes the display that @var{frame} is on; if @var{frame} is
2339 omitted or @code{nil}, it applies to the selected frame's display
2340 (@pxref{Input Focus}).
2342 The list contains a vector of the following form for each font:
2345 [@var{family} @var{width} @var{point-size} @var{weight} @var{slant}
2346 @var{fixed-p} @var{full} @var{registry-and-encoding}]
2349 The first five elements correspond to face attributes; if you
2350 specify these attributes for a face, it will use this font.
2352 The last three elements give additional information about the font.
2353 @var{fixed-p} is non-@code{nil} if the font is fixed-pitch.
2354 @var{full} is the full name of the font, and
2355 @var{registry-and-encoding} is a string giving the registry and
2356 encoding of the font.
2358 The result list is sorted according to the current face font sort order.
2361 @defun x-font-family-list &optional frame
2362 @tindex x-font-family-list
2363 This function returns a list of the font families available for
2364 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, it
2365 describes the selected frame's display (@pxref{Input Focus}).
2367 The value is a list of elements of this form:
2370 (@var{family} . @var{fixed-p})
2374 Here @var{family} is a font family, and @var{fixed-p} is
2375 non-@code{nil} if fonts of that family are fixed-pitch.
2378 @defvar font-list-limit
2379 @tindex font-list-limit
2380 This variable specifies maximum number of fonts to consider in font
2381 matching. The function @code{x-family-fonts} will not return more than
2382 that many fonts, and font selection will consider only that many fonts
2383 when searching a matching font for face attributes. The default is
2388 @subsection Fontsets
2390 A @dfn{fontset} is a list of fonts, each assigned to a range of
2391 character codes. An individual font cannot display the whole range of
2392 characters that Emacs supports, but a fontset can. Fontsets have names,
2393 just as fonts do, and you can use a fontset name in place of a font name
2394 when you specify the ``font'' for a frame or a face. Here is
2395 information about defining a fontset under Lisp program control.
2397 @defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
2398 This function defines a new fontset according to the specification
2399 string @var{fontset-spec}. The string should have this format:
2402 @var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
2406 Whitespace characters before and after the commas are ignored.
2408 The first part of the string, @var{fontpattern}, should have the form of
2409 a standard X font name, except that the last two fields should be
2410 @samp{fontset-@var{alias}}.
2412 The new fontset has two names, one long and one short. The long name is
2413 @var{fontpattern} in its entirety. The short name is
2414 @samp{fontset-@var{alias}}. You can refer to the fontset by either
2415 name. If a fontset with the same name already exists, an error is
2416 signaled, unless @var{noerror} is non-@code{nil}, in which case this
2417 function does nothing.
2419 If optional argument @var{style-variant-p} is non-@code{nil}, that says
2420 to create bold, italic and bold-italic variants of the fontset as well.
2421 These variant fontsets do not have a short name, only a long one, which
2422 is made by altering @var{fontpattern} to indicate the bold or italic
2425 The specification string also says which fonts to use in the fontset.
2426 See below for the details.
2429 The construct @samp{@var{charset}:@var{font}} specifies which font to
2430 use (in this fontset) for one particular character set. Here,
2431 @var{charset} is the name of a character set, and @var{font} is the font
2432 to use for that character set. You can use this construct any number of
2433 times in the specification string.
2435 For the remaining character sets, those that you don't specify
2436 explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
2437 @samp{fontset-@var{alias}} with a value that names one character set.
2438 For the @sc{ascii} character set, @samp{fontset-@var{alias}} is replaced
2439 with @samp{ISO8859-1}.
2441 In addition, when several consecutive fields are wildcards, Emacs
2442 collapses them into a single wildcard. This is to prevent use of
2443 auto-scaled fonts. Fonts made by scaling larger fonts are not usable
2444 for editing, and scaling a smaller font is not useful because it is
2445 better to use the smaller font in its own size, which Emacs does.
2447 Thus if @var{fontpattern} is this,
2450 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
2454 the font specification for @sc{ascii} characters would be this:
2457 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
2461 and the font specification for Chinese GB2312 characters would be this:
2464 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
2467 You may not have any Chinese font matching the above font
2468 specification. Most X distributions include only Chinese fonts that
2469 have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
2470 such a case, @samp{Fontset-@var{n}} can be specified as below:
2473 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
2474 chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
2478 Then, the font specifications for all but Chinese GB2312 characters have
2479 @samp{fixed} in the @var{family} field, and the font specification for
2480 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
2483 @defun char-displayable-p char
2484 This function returns @code{t} if Emacs ought to be able to display
2485 @var{char}. More precisely, if the selected frame's fontset has a
2486 font to display the character set that @var{char} belongs to.
2488 Fontsets can specify a font on a per-character basis; when the fontset
2489 does that, this function's value may not be accurate.
2496 The @dfn{fringes} of a window are thin vertical strips down the
2497 sides that are used for displaying bitmaps that indicate truncation,
2498 continuation, and horizontal scrolling, the overlay arrow. The
2499 fringes normally appear between the display margins and the window
2500 text, but you can put them outside the display margins for a specific
2501 buffer by setting @code{fringes-outside-margins} buffer-locally to a
2502 non-@code{nil} value.
2504 @defvar fringes-outside-margins
2505 If the value is non-@code{nil}, the frames appear outside
2506 the display margins.
2509 @defvar left-fringe-width
2510 This variable, if non-@code{nil}, specifies the width of the left
2514 @defvar right-fringe-width
2515 This variable, if non-@code{nil}, specifies the width of the right
2519 The values of these variables take effect when you display the
2520 buffer in a window. If you change them while the buffer is visible,
2521 you can call @code{set-buffer-window} to display it in a window again.
2523 @defun set-window-fringes window left &optional right outside-margins
2524 This function sets the fringe widthes of window @var{window}.
2525 If window is @code{nil}, that stands for the selected window.
2527 The argument @var{left} specifies the width in pixels of the left
2528 fringe, and likewise @var{right} for the right fringe. A value of
2529 @code{nil} for either one stands for the default width. If
2530 @var{outside-margins} is non-@code{nil}, that specifies that fringes
2531 should appear outside of the display margins.
2534 @defun window-fringes window
2535 This function returns information about the fringes of a window
2536 @var{window}. The value has the form @code{(@var{left-width}
2537 @var{right-width} @var{frames-outside-margins})}.
2541 @section Scroll Bars
2543 Normally the frame parameter @code{vertical-scroll-bars} controls
2544 whether the windows in the frame have vertical scroll bars. A
2545 non-@code{nil} parameter value means they do. The frame parameter
2546 @code{scroll-bar-width} specifies how wide they are (@code{nil}
2547 meaning the default). @xref{Window Frame Parameters}.
2549 You can also control this for individual windows. Call the function
2550 @code{set-window-scroll-bars} to specify what to do for a specific window:
2552 @defun set-window-scroll-bars window width &optional vertical-type horizontal-type
2553 Set width and type of scroll bars of window @var{window}. (If
2554 @var{window} is @code{nil}, this applies to the selected window.)
2555 @var{width} specifies the scroll bar width in pixels (@code{nil} means
2556 use whatever is specified for width for the frame).
2557 @var{vertical-type} specifies whether to have a vertical scroll bar
2558 and, if so, where. The possible values are @code{left}, @code{right}
2559 and @code{nil}, just like the values of the
2560 @code{vertical-scroll-bars} frame parameter.
2562 The argument @var{horizontal-type} is meant to specify whether and
2563 where to have horizontal scroll bars, but since they are not
2564 implemented, it has no effect.
2567 @defun window-scroll-bars &optional window
2568 Report the width and type of scroll bars specified for @var{window}.
2569 If @var{window} is omitted or @code{nil}, it defaults to the currently
2570 selected window. The value is a list of the form @code{(@var{width}
2571 @var{cols} @var{vertical-type} @var{horizontal-type})}. The value
2572 @var{width} is the value that was specified for the width (which may
2573 be @code{nil}); @var{cols} is the number of columns that the scroll
2574 bar actually occupies.
2576 @var{horizontal-type} is not actually meaningful.
2579 If you don't specify these values for a window with
2580 @code{set-window-scroll-bars}, the buffer-local variables
2581 @code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being
2582 displayed control the window's vertical scroll bars. The function
2583 @code{set-window-buffer} examines these variables. If you change them
2584 in a buffer that is already visible in a window, you can make the
2585 window take note of the new values by calling @code{set-window-buffer}
2586 specifying the same buffer that is already displayed.
2588 @node Display Property
2589 @section The @code{display} Property
2590 @cindex display specification
2591 @kindex display @r{(text property)}
2593 The @code{display} text property (or overlay property) is used to
2594 insert images into text, and also control other aspects of how text
2595 displays. These features are available starting in Emacs 21. The value
2596 of the @code{display} property should be a display specification, or a
2597 list or vector containing several display specifications. The rest of
2598 this section describes several kinds of display specifications and what
2602 * Specified Space:: Displaying one space with a specified width.
2603 * Other Display Specs:: Displaying an image; magnifying text; moving it
2604 up or down on the page; adjusting the width
2605 of spaces within text.
2606 * Display Margins:: Displaying text or images to the side of the main text.
2607 * Conditional Display:: Making any of the above features conditional
2608 depending on some Lisp expression.
2611 @node Specified Space
2612 @subsection Specified Spaces
2613 @cindex spaces, specified height or width
2614 @cindex specified spaces
2615 @cindex variable-width spaces
2617 To display a space of specified width and/or height, use a display
2618 specification of the form @code{(space . @var{props})}, where
2619 @var{props} is a property list (a list of alternating properties and
2620 values). You can put this property on one or more consecutive
2621 characters; a space of the specified height and width is displayed in
2622 place of @emph{all} of those characters. These are the properties you
2623 can use in @var{props} to specify the weight of the space:
2626 @item :width @var{width}
2627 Specifies that the space width should be @var{width} times the normal
2628 character width. @var{width} can be an integer or floating point
2631 @item :relative-width @var{factor}
2632 Specifies that the width of the stretch should be computed from the
2633 first character in the group of consecutive characters that have the
2634 same @code{display} property. The space width is the width of that
2635 character, multiplied by @var{factor}.
2637 @item :align-to @var{hpos}
2638 Specifies that the space should be wide enough to reach @var{hpos}. The
2639 value @var{hpos} is measured in units of the normal character width. It
2640 may be an integer or a floating point number.
2643 You should use one and only one of the above properties. You can
2644 also specify the height of the space, with other properties:
2647 @item :height @var{height}
2648 Specifies the height of the space, as @var{height},
2649 measured in terms of the normal line height.
2651 @item :relative-height @var{factor}
2652 Specifies the height of the space, multiplying the ordinary height
2653 of the text having this display specification by @var{factor}.
2655 @item :ascent @var{ascent}
2656 Specifies that @var{ascent} percent of the height of the space should be
2657 considered as the ascent of the space---that is, the part above the
2658 baseline. The value of @var{ascent} must be a non-negative number no
2662 Don't use both @code{:height} and @code{:relative-height} together.
2664 @node Other Display Specs
2665 @subsection Other Display Specifications
2668 @item (image . @var{image-props})
2669 This is in fact an image descriptor (@pxref{Images}). When used as a
2670 display specification, it means to display the image instead of the text
2671 that has the display specification.
2673 @item ((margin nil) @var{string})
2675 A display specification of this form means to display @var{string}
2676 instead of the text that has the display specification, at the same
2677 position as that text. This is a special case of marginal display
2678 (@pxref{Display Margins}).
2680 Recursive display specifications are not supported---string display
2681 specifications must not have @code{display} properties themselves.
2683 @item (space-width @var{factor})
2684 This display specification affects all the space characters within the
2685 text that has the specification. It displays all of these spaces
2686 @var{factor} times as wide as normal. The element @var{factor} should
2687 be an integer or float. Characters other than spaces are not affected
2688 at all; in particular, this has no effect on tab characters.
2690 @item (height @var{height})
2691 This display specification makes the text taller or shorter.
2692 Here are the possibilities for @var{height}:
2695 @item @code{(+ @var{n})}
2696 This means to use a font that is @var{n} steps larger. A ``step'' is
2697 defined by the set of available fonts---specifically, those that match
2698 what was otherwise specified for this text, in all attributes except
2699 height. Each size for which a suitable font is available counts as
2700 another step. @var{n} should be an integer.
2702 @item @code{(- @var{n})}
2703 This means to use a font that is @var{n} steps smaller.
2705 @item a number, @var{factor}
2706 A number, @var{factor}, means to use a font that is @var{factor} times
2707 as tall as the default font.
2709 @item a symbol, @var{function}
2710 A symbol is a function to compute the height. It is called with the
2711 current height as argument, and should return the new height to use.
2713 @item anything else, @var{form}
2714 If the @var{height} value doesn't fit the previous possibilities, it is
2715 a form. Emacs evaluates it to get the new height, with the symbol
2716 @code{height} bound to the current specified font height.
2719 @item (raise @var{factor})
2720 This kind of display specification raises or lowers the text
2721 it applies to, relative to the baseline of the line.
2723 @var{factor} must be a number, which is interpreted as a multiple of the
2724 height of the affected text. If it is positive, that means to display
2725 the characters raised. If it is negative, that means to display them
2728 If the text also has a @code{height} display specification, that does
2729 not affect the amount of raising or lowering, which is based on the
2730 faces used for the text.
2733 @node Display Margins
2734 @subsection Displaying in the Margins
2735 @cindex display margins
2736 @cindex margins, display
2738 A buffer can have blank areas called @dfn{display margins} on the left
2739 and on the right. Ordinary text never appears in these areas, but you
2740 can put things into the display margins using the @code{display}
2743 To put text in the left or right display margin of the window, use a
2744 display specification of the form @code{(margin right-margin)} or
2745 @code{(margin left-margin)} on it. To put an image in a display margin,
2746 use that display specification along with the display specification for
2747 the image. Unfortunately, there is currently no way to make
2748 text or images in the margin mouse-sensitive.
2750 If you put such a display specification directly on text in the
2751 buffer, the specified margin display appears @emph{instead of} that
2752 buffer text itself. To put something in the margin @emph{in
2753 association with} certain buffer text without preventing or altering
2754 the display of that text, put a @code{before-string} property on the
2755 text and put the display specification on the contents of the
2758 Before the display margins can display anything, you must give
2759 them a nonzero width. The usual way to do that is to set these
2762 @defvar left-margin-width
2763 @tindex left-margin-width
2764 This variable specifies the width of the left margin.
2765 It is buffer-local in all buffers.
2768 @defvar right-margin-width
2769 @tindex right-margin-width
2770 This variable specifies the width of the right margin.
2771 It is buffer-local in all buffers.
2774 Setting these variables does not immediately affect the window. These
2775 variables are checked when a new buffer is displayed in the window.
2776 Thus, you can make changes take effect by calling
2777 @code{set-window-buffer}.
2779 You can also set the margin widths immediately.
2781 @defun set-window-margins window left &optional right
2782 @tindex set-window-margins
2783 This function specifies the margin widths for window @var{window}.
2784 The argument @var{left} controls the left margin and
2785 @var{right} controls the right margin (default @code{0}).
2788 @defun window-margins &optional window
2789 @tindex window-margins
2790 This function returns the left and right margins of @var{window}
2791 as a cons cell of the form @code{(@var{left} . @var{right})}.
2792 If @var{window} is @code{nil}, the selected window is used.
2795 @node Conditional Display
2796 @subsection Conditional Display Specifications
2797 @cindex conditional display specifications
2799 You can make any display specification conditional. To do that,
2800 package it in another list of the form @code{(when @var{condition} .
2801 @var{spec})}. Then the specification @var{spec} applies only when
2802 @var{condition} evaluates to a non-@code{nil} value. During the
2803 evaluation, @code{object} is bound to the string or buffer having the
2804 conditional @code{display} property. @code{position} and
2805 @code{buffer-position} are bound to the position within @code{object}
2806 and the buffer position where the @code{display} property was found,
2807 respectively. Both positions can be different when @code{object} is a
2812 @cindex images in buffers
2814 To display an image in an Emacs buffer, you must first create an image
2815 descriptor, then use it as a display specifier in the @code{display}
2816 property of text that is displayed (@pxref{Display Property}). Like the
2817 @code{display} property, this feature is available starting in Emacs 21.
2819 Emacs can display a number of different image formats; some of them
2820 are supported only if particular support libraries are installed on your
2821 machine. The supported image formats include XBM, XPM (needing the
2822 libraries @code{libXpm} version 3.4k and @code{libz}), GIF (needing
2823 @code{libungif} 4.1.0), Postscript, PBM, JPEG (needing the
2824 @code{libjpeg} library version v6a), TIFF (needing @code{libtiff} v3.4),
2825 and PNG (needing @code{libpng} 1.0.2).
2827 You specify one of these formats with an image type symbol. The image
2828 type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
2829 @code{pbm}, @code{jpeg}, @code{tiff}, and @code{png}.
2832 This variable contains a list of those image type symbols that are
2833 supported in the current configuration.
2837 * Image Descriptors:: How to specify an image for use in @code{:display}.
2838 * XBM Images:: Special features for XBM format.
2839 * XPM Images:: Special features for XPM format.
2840 * GIF Images:: Special features for GIF format.
2841 * Postscript Images:: Special features for Postscript format.
2842 * Other Image Types:: Various other formats are supported.
2843 * Defining Images:: Convenient ways to define an image for later use.
2844 * Showing Images:: Convenient ways to display an image once it is defined.
2845 * Image Cache:: Internal mechanisms of image display.
2848 @node Image Descriptors
2849 @subsection Image Descriptors
2850 @cindex image descriptor
2852 An image description is a list of the form @code{(image
2853 . @var{props})}, where @var{props} is a property list containing
2854 alternating keyword symbols (symbols whose names start with a colon) and
2855 their values. You can use any Lisp object as a property, but the only
2856 properties that have any special meaning are certain symbols, all of
2859 Every image descriptor must contain the property @code{:type
2860 @var{type}} to specify the format of the image. The value of @var{type}
2861 should be an image type symbol; for example, @code{xpm} for an image in
2864 Here is a list of other properties that are meaningful for all image
2868 @item :file @var{file}
2869 The @code{:file} property specifies to load the image from file
2870 @var{file}. If @var{file} is not an absolute file name, it is expanded
2871 in @code{data-directory}.
2873 @item :data @var{data}
2874 The @code{:data} property specifies the actual contents of the image.
2875 Each image must use either @code{:data} or @code{:file}, but not both.
2876 For most image types, the value of the @code{:data} property should be a
2877 string containing the image data; we recommend using a unibyte string.
2879 Before using @code{:data}, look for further information in the section
2880 below describing the specific image format. For some image types,
2881 @code{:data} may not be supported; for some, it allows other data types;
2882 for some, @code{:data} alone is not enough, so you need to use other
2883 image properties along with @code{:data}.
2885 @item :margin @var{margin}
2886 The @code{:margin} property specifies how many pixels to add as an
2887 extra margin around the image. The value, @var{margin}, must be a
2888 non-negative number, or a pair @code{(@var{x} . @var{y})} of such
2889 numbers. If it is a pair, @var{x} specifies how many pixels to add
2890 horizontally, and @var{y} specifies how many pixels to add vertically.
2891 If @code{:margin} is not specified, the default is zero.
2893 @item :ascent @var{ascent}
2894 The @code{:ascent} property specifies the amount of the image's
2895 height to use for its ascent---that is, the part above the baseline.
2896 The value, @var{ascent}, must be a number in the range 0 to 100, or
2897 the symbol @code{center}.
2899 If @var{ascent} is a number, that percentage of the image's height is
2900 used for its ascent.
2902 If @var{ascent} is @code{center}, the image is vertically centered
2903 around a centerline which would be the vertical centerline of text drawn
2904 at the position of the image, in the manner specified by the text
2905 properties and overlays that apply to the image.
2907 If this property is omitted, it defaults to 50.
2909 @item :relief @var{relief}
2910 The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle
2911 around the image. The value, @var{relief}, specifies the width of the
2912 shadow lines, in pixels. If @var{relief} is negative, shadows are drawn
2913 so that the image appears as a pressed button; otherwise, it appears as
2914 an unpressed button.
2916 @item :conversion @var{algorithm}
2917 The @code{:conversion} property, if non-@code{nil}, specifies a
2918 conversion algorithm that should be applied to the image before it is
2919 displayed; the value, @var{algorithm}, specifies which algorithm.
2924 Specifies the Laplace edge detection algorithm, which blurs out small
2925 differences in color while highlighting larger differences. People
2926 sometimes consider this useful for displaying the image for a
2927 ``disabled'' button.
2929 @item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
2930 Specifies a general edge-detection algorithm. @var{matrix} must be
2931 either a nine-element list or a nine-element vector of numbers. A pixel
2932 at position @math{x/y} in the transformed image is computed from
2933 original pixels around that position. @var{matrix} specifies, for each
2934 pixel in the neighborhood of @math{x/y}, a factor with which that pixel
2935 will influence the transformed pixel; element @math{0} specifies the
2936 factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for
2937 the pixel at @math{x/y-1} etc., as shown below:
2940 $$\pmatrix{x-1/y-1 & x/y-1 & x+1/y-1 \cr
2941 x-1/y & x/y & x+1/y \cr
2942 x-1/y+1& x/y+1 & x+1/y+1 \cr}$$
2947 (x-1/y-1 x/y-1 x+1/y-1
2949 x-1/y+1 x/y+1 x+1/y+1)
2953 The resulting pixel is computed from the color intensity of the color
2954 resulting from summing up the RGB values of surrounding pixels,
2955 multiplied by the specified factors, and dividing that sum by the sum
2956 of the factors' absolute values.
2958 Laplace edge-detection currently uses a matrix of
2961 $$\pmatrix{1 & 0 & 0 \cr
2974 Emboss edge-detection uses a matrix of
2977 $$\pmatrix{ 2 & -1 & 0 \cr
2991 Specifies transforming the image so that it looks ``disabled''.
2994 @item :mask @var{mask}
2995 If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build
2996 a clipping mask for the image, so that the background of a frame is
2997 visible behind the image. If @var{bg} is not specified, or if @var{bg}
2998 is @code{t}, determine the background color of the image by looking at
2999 the four corners of the image, assuming the most frequently occurring
3000 color from the corners is the background color of the image. Otherwise,
3001 @var{bg} must be a list @code{(@var{red} @var{green} @var{blue})}
3002 specifying the color to assume for the background of the image.
3004 If @var{mask} is @code{nil}, remove a mask from the image, if it has
3005 one. Images in some formats include a mask which can be removed by
3006 specifying @code{:mask nil}.
3009 @defun image-mask-p spec &optional frame
3010 @tindex image-mask-p
3011 This function returns @code{t} if image @var{spec} has a mask bitmap.
3012 @var{frame} is the frame on which the image will be displayed.
3013 @var{frame} @code{nil} or omitted means to use the selected frame
3014 (@pxref{Input Focus}).
3018 @subsection XBM Images
3021 To use XBM format, specify @code{xbm} as the image type. This image
3022 format doesn't require an external library, so images of this type are
3025 Additional image properties supported for the @code{xbm} image type are:
3028 @item :foreground @var{foreground}
3029 The value, @var{foreground}, should be a string specifying the image
3030 foreground color, or @code{nil} for the default color. This color is
3031 used for each pixel in the XBM that is 1. The default is the frame's
3034 @item :background @var{background}
3035 The value, @var{background}, should be a string specifying the image
3036 background color, or @code{nil} for the default color. This color is
3037 used for each pixel in the XBM that is 0. The default is the frame's
3041 If you specify an XBM image using data within Emacs instead of an
3042 external file, use the following three properties:
3045 @item :data @var{data}
3046 The value, @var{data}, specifies the contents of the image.
3047 There are three formats you can use for @var{data}:
3051 A vector of strings or bool-vectors, each specifying one line of the
3052 image. Do specify @code{:height} and @code{:width}.
3055 A string containing the same byte sequence as an XBM file would contain.
3056 You must not specify @code{:height} and @code{:width} in this case,
3057 because omitting them is what indicates the data has the format of an
3058 XBM file. The file contents specify the height and width of the image.
3061 A string or a bool-vector containing the bits of the image (plus perhaps
3062 some extra bits at the end that will not be used). It should contain at
3063 least @var{width} * @code{height} bits. In this case, you must specify
3064 @code{:height} and @code{:width}, both to indicate that the string
3065 contains just the bits rather than a whole XBM file, and to specify the
3069 @item :width @var{width}
3070 The value, @var{width}, specifies the width of the image, in pixels.
3072 @item :height @var{height}
3073 The value, @var{height}, specifies the height of the image, in pixels.
3077 @subsection XPM Images
3080 To use XPM format, specify @code{xpm} as the image type. The
3081 additional image property @code{:color-symbols} is also meaningful with
3082 the @code{xpm} image type:
3085 @item :color-symbols @var{symbols}
3086 The value, @var{symbols}, should be an alist whose elements have the
3087 form @code{(@var{name} . @var{color})}. In each element, @var{name} is
3088 the name of a color as it appears in the image file, and @var{color}
3089 specifies the actual color to use for displaying that name.
3093 @subsection GIF Images
3096 For GIF images, specify image type @code{gif}. Because of the patents
3097 in the US covering the LZW algorithm, the continued use of GIF format is
3098 a problem for the whole Internet; to end this problem, it is a good idea
3099 for everyone, even outside the US, to stop using GIFS right away
3100 (@uref{http://www.burnallgifs.org/}). But if you still want to use
3101 them, Emacs can display them.
3104 @item :index @var{index}
3105 You can use @code{:index} to specify one image from a GIF file that
3106 contains more than one image. This property specifies use of image
3107 number @var{index} from the file. An error is signaled if the GIF file
3108 doesn't contain an image with index @var{index}.
3112 This could be used to implement limited support for animated GIFs.
3113 For example, the following function displays a multi-image GIF file
3114 at point-min in the current buffer, switching between sub-images
3117 (defun show-anim (file max)
3118 "Display multi-image GIF file FILE which contains MAX subimages."
3119 (display-anim (current-buffer) file 0 max t))
3121 (defun display-anim (buffer file idx max first-time)
3124 (let ((img (create-image file nil :image idx)))
3127 (goto-char (point-min))
3128 (unless first-time (delete-char 1))
3130 (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
3133 @node Postscript Images
3134 @subsection Postscript Images
3135 @cindex Postscript images
3137 To use Postscript for an image, specify image type @code{postscript}.
3138 This works only if you have Ghostscript installed. You must always use
3139 these three properties:
3142 @item :pt-width @var{width}
3143 The value, @var{width}, specifies the width of the image measured in
3144 points (1/72 inch). @var{width} must be an integer.
3146 @item :pt-height @var{height}
3147 The value, @var{height}, specifies the height of the image in points
3148 (1/72 inch). @var{height} must be an integer.
3150 @item :bounding-box @var{box}
3151 The value, @var{box}, must be a list or vector of four integers, which
3152 specifying the bounding box of the Postscript image, analogous to the
3153 @samp{BoundingBox} comment found in Postscript files.
3156 %%BoundingBox: 22 171 567 738
3160 Displaying Postscript images from Lisp data is not currently
3161 implemented, but it may be implemented by the time you read this.
3162 See the @file{etc/NEWS} file to make sure.
3164 @node Other Image Types
3165 @subsection Other Image Types
3168 For PBM images, specify image type @code{pbm}. Color, gray-scale and
3169 monochromatic images are supported. For mono PBM images, two additional
3170 image properties are supported.
3173 @item :foreground @var{foreground}
3174 The value, @var{foreground}, should be a string specifying the image
3175 foreground color, or @code{nil} for the default color. This color is
3176 used for each pixel in the XBM that is 1. The default is the frame's
3179 @item :background @var{background}
3180 The value, @var{background}, should be a string specifying the image
3181 background color, or @code{nil} for the default color. This color is
3182 used for each pixel in the XBM that is 0. The default is the frame's
3186 For JPEG images, specify image type @code{jpeg}.
3188 For TIFF images, specify image type @code{tiff}.
3190 For PNG images, specify image type @code{png}.
3192 @node Defining Images
3193 @subsection Defining Images
3195 The functions @code{create-image}, @code{defimage} and
3196 @code{find-image} provide convenient ways to create image descriptors.
3198 @defun create-image file &optional type &rest props
3199 @tindex create-image
3200 This function creates and returns an image descriptor which uses the
3203 The optional argument @var{type} is a symbol specifying the image type.
3204 If @var{type} is omitted or @code{nil}, @code{create-image} tries to
3205 determine the image type from the file's first few bytes, or else
3206 from the file's name.
3208 The remaining arguments, @var{props}, specify additional image
3209 properties---for example,
3212 (create-image "foo.xpm" 'xpm :heuristic-mask t)
3215 The function returns @code{nil} if images of this type are not
3216 supported. Otherwise it returns an image descriptor.
3219 @defmac defimage symbol specs &optional doc
3221 This macro defines @var{symbol} as an image name. The arguments
3222 @var{specs} is a list which specifies how to display the image.
3223 The third argument, @var{doc}, is an optional documentation string.
3225 Each argument in @var{specs} has the form of a property list, and each
3226 one should specify at least the @code{:type} property and either the
3227 @code{:file} or the @code{:data} property. The value of @code{:type}
3228 should be a symbol specifying the image type, the value of
3229 @code{:file} is the file to load the image from, and the value of
3230 @code{:data} is a string containing the actual image data. Here is an
3234 (defimage test-image
3235 ((:type xpm :file "~/test1.xpm")
3236 (:type xbm :file "~/test1.xbm")))
3239 @code{defimage} tests each argument, one by one, to see if it is
3240 usable---that is, if the type is supported and the file exists. The
3241 first usable argument is used to make an image descriptor which is
3242 stored in @var{symbol}.
3244 If none of the alternatives will work, then @var{symbol} is defined
3248 @defun find-image specs
3250 This function provides a convenient way to find an image satisfying one
3251 of a list of image specifications @var{specs}.
3253 Each specification in @var{specs} is a property list with contents
3254 depending on image type. All specifications must at least contain the
3255 properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
3256 or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
3257 the image type, e.g.@: @code{xbm}, @var{file} is the file to load the
3258 image from, and @var{data} is a string containing the actual image data.
3259 The first specification in the list whose @var{type} is supported, and
3260 @var{file} exists, is used to construct the image specification to be
3261 returned. If no specification is satisfied, @code{nil} is returned.
3263 The image is looked for first on @code{load-path} and then in
3264 @code{data-directory}.
3267 @node Showing Images
3268 @subsection Showing Images
3270 You can use an image descriptor by setting up the @code{display}
3271 property yourself, but it is easier to use the functions in this
3274 @defun insert-image image &optional string area
3275 This function inserts @var{image} in the current buffer at point. The
3276 value @var{image} should be an image descriptor; it could be a value
3277 returned by @code{create-image}, or the value of a symbol defined with
3278 @code{defimage}. The argument @var{string} specifies the text to put in
3279 the buffer to hold the image.
3281 The argument @var{area} specifies whether to put the image in a margin.
3282 If it is @code{left-margin}, the image appears in the left margin;
3283 @code{right-margin} specifies the right margin. If @var{area} is
3284 @code{nil} or omitted, the image is displayed at point within the
3287 Internally, this function inserts @var{string} in the buffer, and gives
3288 it a @code{display} property which specifies @var{image}. @xref{Display
3292 @defun put-image image pos &optional string area
3293 This function puts image @var{image} in front of @var{pos} in the
3294 current buffer. The argument @var{pos} should be an integer or a
3295 marker. It specifies the buffer position where the image should appear.
3296 The argument @var{string} specifies the text that should hold the image
3297 as an alternative to the default.
3299 The argument @var{image} must be an image descriptor, perhaps returned
3300 by @code{create-image} or stored by @code{defimage}.
3302 The argument @var{area} specifies whether to put the image in a margin.
3303 If it is @code{left-margin}, the image appears in the left margin;
3304 @code{right-margin} specifies the right margin. If @var{area} is
3305 @code{nil} or omitted, the image is displayed at point within the
3308 Internally, this function creates an overlay, and gives it a
3309 @code{before-string} property containing text that has a @code{display}
3310 property whose value is the image. (Whew!)
3313 @defun remove-images start end &optional buffer
3314 This function removes images in @var{buffer} between positions
3315 @var{start} and @var{end}. If @var{buffer} is omitted or @code{nil},
3316 images are removed from the current buffer.
3318 This removes only images that were put into @var{buffer} the way
3319 @code{put-image} does it, not images that were inserted with
3320 @code{insert-image} or in other ways.
3323 @defun image-size spec &optional pixels frame
3325 This function returns the size of an image as a pair
3326 @w{@code{(@var{width} . @var{height})}}. @var{spec} is an image
3327 specification. @var{pixels} non-@code{nil} means return sizes
3328 measured in pixels, otherwise return sizes measured in canonical
3329 character units (fractions of the width/height of the frame's default
3330 font). @var{frame} is the frame on which the image will be displayed.
3331 @var{frame} null or omitted means use the selected frame (@pxref{Input
3336 @subsection Image Cache
3338 Emacs stores images in an image cache when it displays them, so it can
3339 display them again more efficiently. It removes an image from the cache
3340 when it hasn't been displayed for a specified period of time.
3342 When an image is looked up in the cache, its specification is compared
3343 with cached image specifications using @code{equal}. This means that
3344 all images with equal specifications share the same image in the cache.
3346 @defvar image-cache-eviction-delay
3347 @tindex image-cache-eviction-delay
3348 This variable specifies the number of seconds an image can remain in the
3349 cache without being displayed. When an image is not displayed for this
3350 length of time, Emacs removes it from the image cache.
3352 If the value is @code{nil}, Emacs does not remove images from the cache
3353 except when you explicitly clear it. This mode can be useful for
3357 @defun clear-image-cache &optional frame
3358 @tindex clear-image-cache
3359 This function clears the image cache. If @var{frame} is non-@code{nil},
3360 only the cache for that frame is cleared. Otherwise all frames' caches
3365 @section Blinking Parentheses
3366 @cindex parenthesis matching
3368 @cindex balancing parentheses
3369 @cindex close parenthesis
3371 This section describes the mechanism by which Emacs shows a matching
3372 open parenthesis when the user inserts a close parenthesis.
3374 @defvar blink-paren-function
3375 The value of this variable should be a function (of no arguments) to
3376 be called whenever a character with close parenthesis syntax is inserted.
3377 The value of @code{blink-paren-function} may be @code{nil}, in which
3378 case nothing is done.
3381 @defopt blink-matching-paren
3382 If this variable is @code{nil}, then @code{blink-matching-open} does
3386 @defopt blink-matching-paren-distance
3387 This variable specifies the maximum distance to scan for a matching
3388 parenthesis before giving up.
3391 @defopt blink-matching-delay
3392 This variable specifies the number of seconds for the cursor to remain
3393 at the matching parenthesis. A fraction of a second often gives
3394 good results, but the default is 1, which works on all systems.
3397 @deffn Command blink-matching-open
3398 This function is the default value of @code{blink-paren-function}. It
3399 assumes that point follows a character with close parenthesis syntax and
3400 moves the cursor momentarily to the matching opening character. If that
3401 character is not already on the screen, it displays the character's
3402 context in the echo area. To avoid long delays, this function does not
3403 search farther than @code{blink-matching-paren-distance} characters.
3405 Here is an example of calling this function explicitly.
3409 (defun interactive-blink-matching-open ()
3410 @c Do not break this line! -- rms.
3411 @c The first line of a doc string
3412 @c must stand alone.
3413 "Indicate momentarily the start of sexp before point."
3417 (let ((blink-matching-paren-distance
3419 (blink-matching-paren t))
3420 (blink-matching-open)))
3426 @section Inverse Video
3427 @cindex Inverse Video
3429 @defopt inverse-video
3430 @cindex highlighting
3431 This variable controls whether Emacs uses inverse video for all text
3432 on the screen. Non-@code{nil} means yes, @code{nil} means no. The
3433 default is @code{nil}.
3436 @defopt mode-line-inverse-video
3437 This variable controls the use of inverse video for mode lines and menu
3438 bars. If it is non-@code{nil}, then these lines are displayed in
3439 inverse video. Otherwise, these lines are displayed normally, just like
3440 other text. The default is @code{t}.
3442 For window frames, this feature actually applies the face named
3443 @code{mode-line}; that face is normally set up as the inverse of the
3444 default face, unless you change it.
3448 @section Usual Display Conventions
3450 The usual display conventions define how to display each character
3451 code. You can override these conventions by setting up a display table
3452 (@pxref{Display Tables}). Here are the usual display conventions:
3456 Character codes 32 through 126 map to glyph codes 32 through 126.
3457 Normally this means they display as themselves.
3460 Character code 9 is a horizontal tab. It displays as whitespace
3461 up to a position determined by @code{tab-width}.
3464 Character code 10 is a newline.
3467 All other codes in the range 0 through 31, and code 127, display in one
3468 of two ways according to the value of @code{ctl-arrow}. If it is
3469 non-@code{nil}, these codes map to sequences of two glyphs, where the
3470 first glyph is the @sc{ascii} code for @samp{^}. (A display table can
3471 specify a glyph to use instead of @samp{^}.) Otherwise, these codes map
3472 just like the codes in the range 128 to 255.
3474 On MS-DOS terminals, Emacs arranges by default for the character code
3475 127 to be mapped to the glyph code 127, which normally displays as an
3476 empty polygon. This glyph is used to display non-@sc{ascii} characters
3477 that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,,
3478 emacs, The GNU Emacs Manual}.
3481 Character codes 128 through 255 map to sequences of four glyphs, where
3482 the first glyph is the @sc{ascii} code for @samp{\}, and the others are
3483 digit characters representing the character code in octal. (A display
3484 table can specify a glyph to use instead of @samp{\}.)
3487 Multibyte character codes above 256 are displayed as themselves, or as a
3488 question mark or empty box if the terminal cannot display that
3492 The usual display conventions apply even when there is a display
3493 table, for any character whose entry in the active display table is
3494 @code{nil}. Thus, when you set up a display table, you need only
3495 specify the characters for which you want special behavior.
3497 These display rules apply to carriage return (character code 13), when
3498 it appears in the buffer. But that character may not appear in the
3499 buffer where you expect it, if it was eliminated as part of end-of-line
3500 conversion (@pxref{Coding System Basics}).
3502 These variables affect the way certain characters are displayed on the
3503 screen. Since they change the number of columns the characters occupy,
3504 they also affect the indentation functions. These variables also affect
3505 how the mode line is displayed; if you want to force redisplay of the
3506 mode line using the new values, call the function
3507 @code{force-mode-line-update} (@pxref{Mode Line Format}).
3510 @cindex control characters in display
3511 This buffer-local variable controls how control characters are
3512 displayed. If it is non-@code{nil}, they are displayed as a caret
3513 followed by the character: @samp{^A}. If it is @code{nil}, they are
3514 displayed as a backslash followed by three octal digits: @samp{\001}.
3517 @c Following may have overfull hbox.
3518 @defvar default-ctl-arrow
3519 The value of this variable is the default value for @code{ctl-arrow} in
3520 buffers that do not override it. @xref{Default Value}.
3523 @defopt indicate-empty-lines
3524 @tindex indicate-empty-lines
3525 @cindex fringes, and empty line indication
3526 When this is non-@code{nil}, Emacs displays a special glyph in the
3527 fringe of each empty line at the end of the buffer, on terminals that
3528 support it (window systems). @xref{Fringes}.
3532 The value of this variable is the spacing between tab stops used for
3533 displaying tab characters in Emacs buffers. The value is in units of
3534 columns, and the default is 8. Note that this feature is completely
3535 independent of the user-settable tab stops used by the command
3536 @code{tab-to-tab-stop}. @xref{Indent Tabs}.
3539 @node Display Tables
3540 @section Display Tables
3542 @cindex display table
3543 You can use the @dfn{display table} feature to control how all possible
3544 character codes display on the screen. This is useful for displaying
3545 European languages that have letters not in the @sc{ascii} character
3548 The display table maps each character code into a sequence of
3549 @dfn{glyphs}, each glyph being a graphic that takes up one character
3550 position on the screen. You can also define how to display each glyph
3551 on your terminal, using the @dfn{glyph table}.
3553 Display tables affect how the mode line is displayed; if you want to
3554 force redisplay of the mode line using a new display table, call
3555 @code{force-mode-line-update} (@pxref{Mode Line Format}).
3558 * Display Table Format:: What a display table consists of.
3559 * Active Display Table:: How Emacs selects a display table to use.
3560 * Glyphs:: How to define a glyph, and what glyphs mean.
3563 @node Display Table Format
3564 @subsection Display Table Format
3566 A display table is actually a char-table (@pxref{Char-Tables}) with
3567 @code{display-table} as its subtype.
3569 @defun make-display-table
3570 This creates and returns a display table. The table initially has
3571 @code{nil} in all elements.
3574 The ordinary elements of the display table are indexed by character
3575 codes; the element at index @var{c} says how to display the character
3576 code @var{c}. The value should be @code{nil} or a vector of glyph
3577 values (@pxref{Glyphs}). If an element is @code{nil}, it says to
3578 display that character according to the usual display conventions
3579 (@pxref{Usual Display}).
3581 If you use the display table to change the display of newline
3582 characters, the whole buffer will be displayed as one long ``line.''
3584 The display table also has six ``extra slots'' which serve special
3585 purposes. Here is a table of their meanings; @code{nil} in any slot
3586 means to use the default for that slot, as stated below.
3590 The glyph for the end of a truncated screen line (the default for this
3591 is @samp{$}). @xref{Glyphs}. Newer Emacs versions, on some platforms,
3592 display arrows to indicate truncation---the display table has no effect
3593 in these situations.
3595 The glyph for the end of a continued line (the default is @samp{\}).
3596 Newer Emacs versions, on some platforms, display curved arrows to
3597 indicate truncation---the display table has no effect in these
3600 The glyph for indicating a character displayed as an octal character
3601 code (the default is @samp{\}).
3603 The glyph for indicating a control character (the default is @samp{^}).
3605 A vector of glyphs for indicating the presence of invisible lines (the
3606 default is @samp{...}). @xref{Selective Display}.
3608 The glyph used to draw the border between side-by-side windows (the
3609 default is @samp{|}). @xref{Splitting Windows}. This takes effect only
3610 when there are no scroll bars; if scroll bars are supported and in use,
3611 a scroll bar separates the two windows.
3614 For example, here is how to construct a display table that mimics the
3615 effect of setting @code{ctl-arrow} to a non-@code{nil} value:
3618 (setq disptab (make-display-table))
3621 (or (= i ?\t) (= i ?\n)
3622 (aset disptab i (vector ?^ (+ i 64))))
3624 (aset disptab 127 (vector ?^ ??)))
3627 @defun display-table-slot display-table slot
3628 This function returns the value of the extra slot @var{slot} of
3629 @var{display-table}. The argument @var{slot} may be a number from 0 to
3630 5 inclusive, or a slot name (symbol). Valid symbols are
3631 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
3632 @code{selective-display}, and @code{vertical-border}.
3635 @defun set-display-table-slot display-table slot value
3636 This function stores @var{value} in the extra slot @var{slot} of
3637 @var{display-table}. The argument @var{slot} may be a number from 0 to
3638 5 inclusive, or a slot name (symbol). Valid symbols are
3639 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
3640 @code{selective-display}, and @code{vertical-border}.
3643 @defun describe-display-table display-table
3644 @tindex describe-display-table
3645 This function displays a description of the display table
3646 @var{display-table} in a help buffer.
3649 @deffn Command describe-current-display-table
3650 @tindex describe-current-display-table
3651 This command displays a description of the current display table in a
3655 @node Active Display Table
3656 @subsection Active Display Table
3657 @cindex active display table
3659 Each window can specify a display table, and so can each buffer. When
3660 a buffer @var{b} is displayed in window @var{w}, display uses the
3661 display table for window @var{w} if it has one; otherwise, the display
3662 table for buffer @var{b} if it has one; otherwise, the standard display
3663 table if any. The display table chosen is called the @dfn{active}
3666 @defun window-display-table window
3667 This function returns @var{window}'s display table, or @code{nil}
3668 if @var{window} does not have an assigned display table.
3671 @defun set-window-display-table window table
3672 This function sets the display table of @var{window} to @var{table}.
3673 The argument @var{table} should be either a display table or
3677 @defvar buffer-display-table
3678 This variable is automatically buffer-local in all buffers; its value in
3679 a particular buffer specifies the display table for that buffer. If it
3680 is @code{nil}, that means the buffer does not have an assigned display
3684 @defvar standard-display-table
3685 This variable's value is the default display table, used whenever a
3686 window has no display table and neither does the buffer displayed in
3687 that window. This variable is @code{nil} by default.
3690 If there is no display table to use for a particular window---that is,
3691 if the window specifies none, its buffer specifies none, and
3692 @code{standard-display-table} is @code{nil}---then Emacs uses the usual
3693 display conventions for all character codes in that window. @xref{Usual
3696 A number of functions for changing the standard display table
3697 are defined in the library @file{disp-table}.
3703 A @dfn{glyph} is a generalization of a character; it stands for an
3704 image that takes up a single character position on the screen. Glyphs
3705 are represented in Lisp as integers, just as characters are. Normally
3706 Emacs finds glyphs in the display table (@pxref{Display Tables}).
3708 A glyph can be @dfn{simple} or it can be defined by the @dfn{glyph
3709 table}. A simple glyph is just a way of specifying a character and a
3710 face to output it in. The glyph code for a simple glyph, mod 524288,
3711 is the character to output, and the glyph code divided by 524288
3712 specifies the face number (@pxref{Face Functions}) to use while
3713 outputting it. (524288 is
3722 On character terminals, you can set up a @dfn{glyph table} to define
3723 the meaning of glyph codes. The glyph codes is the value of the
3724 variable @code{glyph-table}.
3727 The value of this variable is the current glyph table. It should be a
3728 vector; the @var{g}th element defines glyph code @var{g}.
3730 If a glyph code is greater than or equal to the length of the glyph
3731 table, that code is automatically simple. If the value of
3732 @code{glyph-table} is @code{nil} instead of a vector, then all glyphs
3733 are simple. The glyph table is not used on graphical displays, only
3734 on character terminals. On graphical displays, all glyphs are simple.
3737 Here are the possible types of elements in the glyph table:
3741 Send the characters in @var{string} to the terminal to output
3742 this glyph. This alternative is available on character terminals,
3743 but not under a window system.
3746 Define this glyph code as an alias for glyph code @var{integer}. You
3747 can use an alias to specify a face code for the glyph and use a small
3751 This glyph is simple.
3754 @defun create-glyph string
3755 @tindex create-glyph
3756 This function returns a newly-allocated glyph code which is set up to
3757 display by sending @var{string} to the terminal.
3765 This section describes how to make Emacs ring the bell (or blink the
3766 screen) to attract the user's attention. Be conservative about how
3767 often you do this; frequent bells can become irritating. Also be
3768 careful not to use just beeping when signaling an error is more
3769 appropriate. (@xref{Errors}.)
3771 @defun ding &optional do-not-terminate
3772 @cindex keyboard macro termination
3773 This function beeps, or flashes the screen (see @code{visible-bell} below).
3774 It also terminates any keyboard macro currently executing unless
3775 @var{do-not-terminate} is non-@code{nil}.
3778 @defun beep &optional do-not-terminate
3779 This is a synonym for @code{ding}.
3782 @defopt visible-bell
3783 This variable determines whether Emacs should flash the screen to
3784 represent a bell. Non-@code{nil} means yes, @code{nil} means no. This
3785 is effective on a window system, and on a character-only terminal
3786 provided the terminal's Termcap entry defines the visible bell
3787 capability (@samp{vb}).
3790 @defvar ring-bell-function
3791 If this is non-@code{nil}, it specifies how Emacs should ``ring the
3792 bell.'' Its value should be a function of no arguments. If this is
3793 non-@code{nil}, it takes precedence over the @code{visible-bell}
3797 @node Window Systems
3798 @section Window Systems
3800 Emacs works with several window systems, most notably the X Window
3801 System. Both Emacs and X use the term ``window'', but use it
3802 differently. An Emacs frame is a single window as far as X is
3803 concerned; the individual Emacs windows are not known to X at all.
3805 @defvar window-system
3806 This variable tells Lisp programs what window system Emacs is running
3807 under. The possible values are
3811 @cindex X Window System
3812 Emacs is displaying using X.
3814 Emacs is displaying using MS-DOS.
3816 Emacs is displaying using Windows.
3818 Emacs is displaying using a Macintosh.
3820 Emacs is using a character-based terminal.
3824 @defvar window-setup-hook
3825 This variable is a normal hook which Emacs runs after handling the
3826 initialization files. Emacs runs this hook after it has completed
3827 loading your init file, the default initialization file (if
3828 any), and the terminal-specific Lisp code, and running the hook
3829 @code{term-setup-hook}.
3831 This hook is used for internal purposes: setting up communication with
3832 the window system, and creating the initial window. Users should not
3837 arch-tag: ffdf5714-7ecf-415b-9023-fbc6b409c2c6