2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/display
7 @node Display, System Interface, 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:: Displaying messages at the bottom of the screen.
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 * Temporary Displays:: Displays that go away automatically.
22 * Overlays:: Use overlays to highlight parts of the buffer.
23 * Width:: How wide a character or string is on the screen.
24 * Line Height:: Controlling the height of lines.
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 * Buttons:: Adding clickable buttons to Emacs buffers.
32 * Abstract Display:: Emacs' Widget for Object Collections.
33 * Blinking:: How Emacs shows the matching open parenthesis.
34 * Usual Display:: The usual conventions for displaying nonprinting chars.
35 * Display Tables:: How to specify other conventions.
36 * Beeping:: Audible signal to the user.
37 * Window Systems:: Which window system is being used.
41 @section Refreshing the Screen
43 The function @code{redraw-frame} clears and redisplays the entire
44 contents of a given frame (@pxref{Frames}). This is useful if the
48 @defun redraw-frame frame
49 This function clears and redisplays frame @var{frame}.
52 Even more powerful is @code{redraw-display}:
54 @deffn Command redraw-display
55 This function clears and redisplays all visible frames.
58 In Emacs, processing user input takes priority over redisplay. If
59 you call these functions when input is available, they don't redisplay
60 immediately, but the requested redisplay does happen
61 eventually---after all the input has been processed.
63 Normally, suspending and resuming Emacs also refreshes the screen.
64 Some terminal emulators record separate contents for display-oriented
65 programs such as Emacs and for ordinary sequential display. If you are
66 using such a terminal, you might want to inhibit the redisplay on
69 @defvar no-redraw-on-reenter
70 @cindex suspend (cf. @code{no-redraw-on-reenter})
71 @cindex resume (cf. @code{no-redraw-on-reenter})
72 This variable controls whether Emacs redraws the entire screen after it
73 has been suspended and resumed. Non-@code{nil} means there is no need
74 to redraw, @code{nil} means redrawing is needed. The default is @code{nil}.
77 @node Forcing Redisplay
78 @section Forcing Redisplay
79 @cindex forcing redisplay
81 Emacs normally tries to redisplay the screen whenever it waits for
82 input. With this function you can request an immediate attempt to
83 redisplay, in the middle of Lisp code, without actually waiting for
86 @defun redisplay &optional force
87 This function tries immediately to redisplay, provided there are no
88 pending input events. It is equivalent to @code{(sit-for 0)}.
90 If the optional argument @var{force} is non-@code{nil}, it does all
91 pending redisplay work even if input is available, with no
94 The function returns @code{t} if it actually tried to redisplay, and
95 @code{nil} otherwise. A value of @code{t} does not mean that
96 redisplay proceeded to completion; it could have been pre-empted by
97 newly arriving terminal input.
100 @code{redisplay} with no argument tries immediately to redisplay,
101 but has no effect on the usual rules for what parts of the screen to
102 redisplay. By contrast, the following function adds certain windows
103 to the pending redisplay work (as if their contents had completely
104 changed), but doesn't immediately try to do any redisplay work.
106 @defun force-window-update &optional object
107 This function forces some or all windows to be updated on next
108 redisplay. If @var{object} is a window, it requires eventual
109 redisplay of that window. If @var{object} is a buffer or buffer name,
110 it requires eventual redisplay of all windows displaying that buffer.
111 If @var{object} is @code{nil} (or omitted), it requires eventual
112 redisplay of all windows.
115 @code{force-window-update} does not do a redisplay immediately.
116 (Emacs will do that when it waits for input.) Rather, its effect is
117 to put more work on the queue to be done by redisplay whenever there
120 Emacs redisplay normally stops if input arrives, and does not happen
121 at all if input is available before it starts. Most of the time, this
122 is exactly what you want. However, you can prevent preemption by
123 binding @code{redisplay-dont-pause} to a non-@code{nil} value.
125 @defvar redisplay-dont-pause
126 If this variable is non-@code{nil}, pending input does not
127 prevent or halt redisplay; redisplay occurs, and finishes,
128 regardless of whether input is available.
131 @defvar redisplay-preemption-period
132 This variable specifies how many seconds Emacs waits between checks
133 for new input during redisplay. (The default is 0.1 seconds.) If
134 input has arrived when Emacs checks, it pre-empts redisplay and
135 processes the available input before trying again to redisplay.
137 If this variable is @code{nil}, Emacs does not check for input during
138 redisplay, and redisplay cannot be preempted by input.
140 This variable is only obeyed on graphical terminals. For
141 text terminals, see @ref{Terminal Output}.
146 @cindex line wrapping
147 @cindex line truncation
148 @cindex continuation lines
149 @cindex @samp{$} in display
150 @cindex @samp{\} in display
152 When a line of text extends beyond the right edge of a window, Emacs
153 can @dfn{continue} the line (make it ``wrap'' to the next screen
154 line), or @dfn{truncate} the line (limit it to one screen line). The
155 additional screen lines used to display a long text line are called
156 @dfn{continuation} lines. Continuation is not the same as filling;
157 continuation happens on the screen only, not in the buffer contents,
158 and it breaks a line precisely at the right margin, not at a word
159 boundary. @xref{Filling}.
161 On a graphical display, tiny arrow images in the window fringes
162 indicate truncated and continued lines (@pxref{Fringes}). On a text
163 terminal, a @samp{$} in the rightmost column of the window indicates
164 truncation; a @samp{\} on the rightmost column indicates a line that
165 ``wraps.'' (The display table can specify alternate characters to use
166 for this; @pxref{Display Tables}).
168 @defopt truncate-lines
169 This buffer-local variable controls how Emacs displays lines that extend
170 beyond the right edge of the window. The default is @code{nil}, which
171 specifies continuation. If the value is non-@code{nil}, then these
174 If the variable @code{truncate-partial-width-windows} is non-@code{nil},
175 then truncation is always used for side-by-side windows (within one
176 frame) regardless of the value of @code{truncate-lines}.
179 @defopt default-truncate-lines
180 This variable is the default value for @code{truncate-lines}, for
181 buffers that do not have buffer-local values for it.
184 @defopt truncate-partial-width-windows
185 This variable controls display of lines that extend beyond the right
186 edge of the window, in side-by-side windows (@pxref{Splitting Windows}).
187 If it is non-@code{nil}, these lines are truncated; otherwise,
188 @code{truncate-lines} says what to do with them.
191 When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
192 a window, that forces truncation.
195 If this buffer-local variable is non-@code{nil}, the prefix it defines
196 will be added at display-time to the beginning of every continuation
197 line due to text wrapping (so if lines are truncated, the wrap-prefix
198 is never used). It may be a string, an image, or a stretch-glyph such
199 as used by the `display' text-property. @xref{Display Property}.
201 A wrap-prefix may also be specified for regions of text using the
202 @code{wrap-prefix} text-property (which takes precedence over the
203 value of the @code{wrap-prefix} variable). @xref{Special Properties}.
207 If this buffer-local variable is non-@code{nil}, the prefix it defines
208 will be added at display-time to the beginning of every
209 non-continuation line It may be a string, an image, or a stretch-glyph
210 such as used by the `display' text-property. @xref{Display Property}.
212 A line-prefix may also be specified for regions of text using the
213 @code{line-prefix} text-property (which takes precedence over the
214 value of the @code{line-prefix} variable). @xref{Special Properties}.
217 If your buffer contains @emph{very} long lines, and you use
218 continuation to display them, just thinking about them can make Emacs
219 redisplay slow. The column computation and indentation functions also
220 become slow. Then you might find it advisable to set
221 @code{cache-long-line-scans} to @code{t}.
223 @defvar cache-long-line-scans
224 If this variable is non-@code{nil}, various indentation and motion
225 functions, and Emacs redisplay, cache the results of scanning the
226 buffer, and consult the cache to avoid rescanning regions of the buffer
227 unless they are modified.
229 Turning on the cache slows down processing of short lines somewhat.
231 This variable is automatically buffer-local in every buffer.
235 @section The Echo Area
236 @cindex error display
239 The @dfn{echo area} is used for displaying error messages
240 (@pxref{Errors}), for messages made with the @code{message} primitive,
241 and for echoing keystrokes. It is not the same as the minibuffer,
242 despite the fact that the minibuffer appears (when active) in the same
243 place on the screen as the echo area. The @cite{GNU Emacs Manual}
244 specifies the rules for resolving conflicts between the echo area and
245 the minibuffer for use of that screen space (@pxref{Minibuffer,, The
246 Minibuffer, emacs, The GNU Emacs Manual}).
248 You can write output in the echo area by using the Lisp printing
249 functions with @code{t} as the stream (@pxref{Output Functions}), or
253 * Displaying Messages:: Explicitly displaying text in the echo area.
254 * Progress:: Informing user about progress of a long operation.
255 * Logging Messages:: Echo area messages are logged for the user.
256 * Echo Area Customization:: Controlling the echo area.
259 @node Displaying Messages
260 @subsection Displaying Messages in the Echo Area
261 @cindex display message in echo area
263 This section describes the functions for explicitly producing echo
264 area messages. Many other Emacs features display messages there, too.
266 @defun message format-string &rest arguments
267 This function displays a message in the echo area. The argument
268 @var{format-string} is similar to a C language @code{printf} format
269 string. See @code{format} in @ref{Formatting Strings}, for the details
270 on the conversion specifications. @code{message} returns the
273 In batch mode, @code{message} prints the message text on the standard
274 error stream, followed by a newline.
276 If @var{format-string}, or strings among the @var{arguments}, have
277 @code{face} text properties, these affect the way the message is displayed.
280 If @var{format-string} is @code{nil} or the empty string,
281 @code{message} clears the echo area; if the echo area has been
282 expanded automatically, this brings it back to its normal size.
283 If the minibuffer is active, this brings the minibuffer contents back
284 onto the screen immediately.
288 (message "Minibuffer depth is %d."
290 @print{} Minibuffer depth is 0.
291 @result{} "Minibuffer depth is 0."
295 ---------- Echo Area ----------
296 Minibuffer depth is 0.
297 ---------- Echo Area ----------
301 To automatically display a message in the echo area or in a pop-buffer,
302 depending on its size, use @code{display-message-or-buffer} (see below).
305 @defmac with-temp-message message &rest body
306 This construct displays a message in the echo area temporarily, during
307 the execution of @var{body}. It displays @var{message}, executes
308 @var{body}, then returns the value of the last body form while restoring
309 the previous echo area contents.
312 @defun message-or-box format-string &rest arguments
313 This function displays a message like @code{message}, but may display it
314 in a dialog box instead of the echo area. If this function is called in
315 a command that was invoked using the mouse---more precisely, if
316 @code{last-nonmenu-event} (@pxref{Command Loop Info}) is either
317 @code{nil} or a list---then it uses a dialog box or pop-up menu to
318 display the message. Otherwise, it uses the echo area. (This is the
319 same criterion that @code{y-or-n-p} uses to make a similar decision; see
320 @ref{Yes-or-No Queries}.)
322 You can force use of the mouse or of the echo area by binding
323 @code{last-nonmenu-event} to a suitable value around the call.
326 @defun message-box format-string &rest arguments
328 This function displays a message like @code{message}, but uses a dialog
329 box (or a pop-up menu) whenever that is possible. If it is impossible
330 to use a dialog box or pop-up menu, because the terminal does not
331 support them, then @code{message-box} uses the echo area, like
335 @defun display-message-or-buffer message &optional buffer-name not-this-window frame
336 This function displays the message @var{message}, which may be either a
337 string or a buffer. If it is shorter than the maximum height of the
338 echo area, as defined by @code{max-mini-window-height}, it is displayed
339 in the echo area, using @code{message}. Otherwise,
340 @code{display-buffer} is used to show it in a pop-up buffer.
342 Returns either the string shown in the echo area, or when a pop-up
343 buffer is used, the window used to display it.
345 If @var{message} is a string, then the optional argument
346 @var{buffer-name} is the name of the buffer used to display it when a
347 pop-up buffer is used, defaulting to @samp{*Message*}. In the case
348 where @var{message} is a string and displayed in the echo area, it is
349 not specified whether the contents are inserted into the buffer anyway.
351 The optional arguments @var{not-this-window} and @var{frame} are as for
352 @code{display-buffer}, and only used if a buffer is displayed.
355 @defun current-message
356 This function returns the message currently being displayed in the
357 echo area, or @code{nil} if there is none.
361 @subsection Reporting Operation Progress
362 @cindex progress reporting
364 When an operation can take a while to finish, you should inform the
365 user about the progress it makes. This way the user can estimate
366 remaining time and clearly see that Emacs is busy working, not hung.
368 Functions listed in this section provide simple and efficient way of
369 reporting operation progress. Here is a working example that does
373 (let ((progress-reporter
374 (make-progress-reporter "Collecting mana for Emacs..."
378 (progress-reporter-update progress-reporter k))
379 (progress-reporter-done progress-reporter))
382 @defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
383 This function creates and returns a @dfn{progress reporter}---an
384 object you will use as an argument for all other functions listed
385 here. The idea is to precompute as much data as possible to make
386 progress reporting very fast.
388 When this progress reporter is subsequently used, it will display
389 @var{message} in the echo area, followed by progress percentage.
390 @var{message} is treated as a simple string. If you need it to depend
391 on a filename, for instance, use @code{format} before calling this
394 @var{min-value} and @var{max-value} arguments stand for starting and
395 final states of your operation. For instance, if you scan a buffer,
396 they should be the results of @code{point-min} and @code{point-max}
397 correspondingly. It is required that @var{max-value} is greater than
398 @var{min-value}. If you create progress reporter when some part of
399 the operation has already been completed, then specify
400 @var{current-value} argument. But normally you should omit it or set
401 it to @code{nil}---it will default to @var{min-value} then.
403 Remaining arguments control the rate of echo area updates. Progress
404 reporter will wait for at least @var{min-change} more percents of the
405 operation to be completed before printing next message.
406 @var{min-time} specifies the minimum time in seconds to pass between
407 successive prints. It can be fractional. Depending on Emacs and
408 system capabilities, progress reporter may or may not respect this
409 last argument or do it with varying precision. Default value for
410 @var{min-change} is 1 (one percent), for @var{min-time}---0.2
413 This function calls @code{progress-reporter-update}, so the first
414 message is printed immediately.
417 @defun progress-reporter-update reporter value
418 This function does the main work of reporting progress of your
419 operation. It displays the message of @var{reporter}, followed by
420 progress percentage determined by @var{value}. If percentage is zero,
421 or close enough according to the @var{min-change} and @var{min-time}
422 arguments, then it is omitted from the output.
424 @var{reporter} must be the result of a call to
425 @code{make-progress-reporter}. @var{value} specifies the current
426 state of your operation and must be between @var{min-value} and
427 @var{max-value} (inclusive) as passed to
428 @code{make-progress-reporter}. For instance, if you scan a buffer,
429 then @var{value} should be the result of a call to @code{point}.
431 This function respects @var{min-change} and @var{min-time} as passed
432 to @code{make-progress-reporter} and so does not output new messages
433 on every invocation. It is thus very fast and normally you should not
434 try to reduce the number of calls to it: resulting overhead will most
435 likely negate your effort.
438 @defun progress-reporter-force-update reporter value &optional new-message
439 This function is similar to @code{progress-reporter-update} except
440 that it prints a message in the echo area unconditionally.
442 The first two arguments have the same meaning as for
443 @code{progress-reporter-update}. Optional @var{new-message} allows
444 you to change the message of the @var{reporter}. Since this functions
445 always updates the echo area, such a change will be immediately
446 presented to the user.
449 @defun progress-reporter-done reporter
450 This function should be called when the operation is finished. It
451 prints the message of @var{reporter} followed by word ``done'' in the
454 You should always call this function and not hope for
455 @code{progress-reporter-update} to print ``100%.'' Firstly, it may
456 never print it, there are many good reasons for this not to happen.
457 Secondly, ``done'' is more explicit.
460 @defmac dotimes-with-progress-reporter (var count [result]) message body@dots{}
461 This is a convenience macro that works the same way as @code{dotimes}
462 does, but also reports loop progress using the functions described
463 above. It allows you to save some typing.
465 You can rewrite the example in the beginning of this node using
469 (dotimes-with-progress-reporter
471 "Collecting some mana for Emacs..."
476 @node Logging Messages
477 @subsection Logging Messages in @samp{*Messages*}
478 @cindex logging echo-area messages
480 Almost all the messages displayed in the echo area are also recorded
481 in the @samp{*Messages*} buffer so that the user can refer back to
482 them. This includes all the messages that are output with
485 @defopt message-log-max
486 This variable specifies how many lines to keep in the @samp{*Messages*}
487 buffer. The value @code{t} means there is no limit on how many lines to
488 keep. The value @code{nil} disables message logging entirely. Here's
489 how to display a message and prevent it from being logged:
492 (let (message-log-max)
497 To make @samp{*Messages*} more convenient for the user, the logging
498 facility combines successive identical messages. It also combines
499 successive related messages for the sake of two cases: question
500 followed by answer, and a series of progress messages.
502 A ``question followed by an answer'' means two messages like the
503 ones produced by @code{y-or-n-p}: the first is @samp{@var{question}},
504 and the second is @samp{@var{question}...@var{answer}}. The first
505 message conveys no additional information beyond what's in the second,
506 so logging the second message discards the first from the log.
508 A ``series of progress messages'' means successive messages like
509 those produced by @code{make-progress-reporter}. They have the form
510 @samp{@var{base}...@var{how-far}}, where @var{base} is the same each
511 time, while @var{how-far} varies. Logging each message in the series
512 discards the previous one, provided they are consecutive.
514 The functions @code{make-progress-reporter} and @code{y-or-n-p}
515 don't have to do anything special to activate the message log
516 combination feature. It operates whenever two consecutive messages
517 are logged that share a common prefix ending in @samp{...}.
519 @node Echo Area Customization
520 @subsection Echo Area Customization
522 These variables control details of how the echo area works.
524 @defvar cursor-in-echo-area
525 This variable controls where the cursor appears when a message is
526 displayed in the echo area. If it is non-@code{nil}, then the cursor
527 appears at the end of the message. Otherwise, the cursor appears at
528 point---not in the echo area at all.
530 The value is normally @code{nil}; Lisp programs bind it to @code{t}
531 for brief periods of time.
534 @defvar echo-area-clear-hook
535 This normal hook is run whenever the echo area is cleared---either by
536 @code{(message nil)} or for any other reason.
539 @defvar echo-keystrokes
540 This variable determines how much time should elapse before command
541 characters echo. Its value must be an integer or floating point number,
543 number of seconds to wait before echoing. If the user types a prefix
544 key (such as @kbd{C-x}) and then delays this many seconds before
545 continuing, the prefix key is echoed in the echo area. (Once echoing
546 begins in a key sequence, all subsequent characters in the same key
547 sequence are echoed immediately.)
549 If the value is zero, then command input is not echoed.
552 @defvar message-truncate-lines
553 Normally, displaying a long message resizes the echo area to display
554 the entire message. But if the variable @code{message-truncate-lines}
555 is non-@code{nil}, the echo area does not resize, and the message is
556 truncated to fit it, as in Emacs 20 and before.
559 The variable @code{max-mini-window-height}, which specifies the
560 maximum height for resizing minibuffer windows, also applies to the
561 echo area (which is really a special use of the minibuffer window.
562 @xref{Minibuffer Misc}.).
565 @section Reporting Warnings
568 @dfn{Warnings} are a facility for a program to inform the user of a
569 possible problem, but continue running.
572 * Warning Basics:: Warnings concepts and functions to report them.
573 * Warning Variables:: Variables programs bind to customize their warnings.
574 * Warning Options:: Variables users set to control display of warnings.
578 @subsection Warning Basics
579 @cindex severity level
581 Every warning has a textual message, which explains the problem for
582 the user, and a @dfn{severity level} which is a symbol. Here are the
583 possible severity levels, in order of decreasing severity, and their
588 A problem that will seriously impair Emacs operation soon
589 if you do not attend to it promptly.
591 A report of data or circumstances that are inherently wrong.
593 A report of data or circumstances that are not inherently wrong, but
594 raise suspicion of a possible problem.
596 A report of information that may be useful if you are debugging.
599 When your program encounters invalid input data, it can either
600 signal a Lisp error by calling @code{error} or @code{signal} or report
601 a warning with severity @code{:error}. Signaling a Lisp error is the
602 easiest thing to do, but it means the program cannot continue
603 processing. If you want to take the trouble to implement a way to
604 continue processing despite the bad data, then reporting a warning of
605 severity @code{:error} is the right way to inform the user of the
606 problem. For instance, the Emacs Lisp byte compiler can report an
607 error that way and continue compiling other functions. (If the
608 program signals a Lisp error and then handles it with
609 @code{condition-case}, the user won't see the error message; it could
610 show the message to the user by reporting it as a warning.)
613 Each warning has a @dfn{warning type} to classify it. The type is a
614 list of symbols. The first symbol should be the custom group that you
615 use for the program's user options. For example, byte compiler
616 warnings use the warning type @code{(bytecomp)}. You can also
617 subcategorize the warnings, if you wish, by using more symbols in the
620 @defun display-warning type message &optional level buffer-name
621 This function reports a warning, using @var{message} as the message
622 and @var{type} as the warning type. @var{level} should be the
623 severity level, with @code{:warning} being the default.
625 @var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
626 for logging the warning. By default, it is @samp{*Warnings*}.
629 @defun lwarn type level message &rest args
630 This function reports a warning using the value of @code{(format
631 @var{message} @var{args}...)} as the message. In other respects it is
632 equivalent to @code{display-warning}.
635 @defun warn message &rest args
636 This function reports a warning using the value of @code{(format
637 @var{message} @var{args}...)} as the message, @code{(emacs)} as the
638 type, and @code{:warning} as the severity level. It exists for
639 compatibility only; we recommend not using it, because you should
640 specify a specific warning type.
643 @node Warning Variables
644 @subsection Warning Variables
646 Programs can customize how their warnings appear by binding
647 the variables described in this section.
649 @defvar warning-levels
650 This list defines the meaning and severity order of the warning
651 severity levels. Each element defines one severity level,
652 and they are arranged in order of decreasing severity.
654 Each element has the form @code{(@var{level} @var{string}
655 @var{function})}, where @var{level} is the severity level it defines.
656 @var{string} specifies the textual description of this level.
657 @var{string} should use @samp{%s} to specify where to put the warning
658 type information, or it can omit the @samp{%s} so as not to include
661 The optional @var{function}, if non-@code{nil}, is a function to call
662 with no arguments, to get the user's attention.
664 Normally you should not change the value of this variable.
667 @defvar warning-prefix-function
668 If non-@code{nil}, the value is a function to generate prefix text for
669 warnings. Programs can bind the variable to a suitable function.
670 @code{display-warning} calls this function with the warnings buffer
671 current, and the function can insert text in it. That text becomes
672 the beginning of the warning message.
674 The function is called with two arguments, the severity level and its
675 entry in @code{warning-levels}. It should return a list to use as the
676 entry (this value need not be an actual member of
677 @code{warning-levels}). By constructing this value, the function can
678 change the severity of the warning, or specify different handling for
679 a given severity level.
681 If the variable's value is @code{nil} then there is no function
685 @defvar warning-series
686 Programs can bind this variable to @code{t} to say that the next
687 warning should begin a series. When several warnings form a series,
688 that means to leave point on the first warning of the series, rather
689 than keep moving it for each warning so that it appears on the last one.
690 The series ends when the local binding is unbound and
691 @code{warning-series} becomes @code{nil} again.
693 The value can also be a symbol with a function definition. That is
694 equivalent to @code{t}, except that the next warning will also call
695 the function with no arguments with the warnings buffer current. The
696 function can insert text which will serve as a header for the series
699 Once a series has begun, the value is a marker which points to the
700 buffer position in the warnings buffer of the start of the series.
702 The variable's normal value is @code{nil}, which means to handle
703 each warning separately.
706 @defvar warning-fill-prefix
707 When this variable is non-@code{nil}, it specifies a fill prefix to
708 use for filling each warning's text.
711 @defvar warning-type-format
712 This variable specifies the format for displaying the warning type
713 in the warning message. The result of formatting the type this way
714 gets included in the message under the control of the string in the
715 entry in @code{warning-levels}. The default value is @code{" (%s)"}.
716 If you bind it to @code{""} then the warning type won't appear at
720 @node Warning Options
721 @subsection Warning Options
723 These variables are used by users to control what happens
724 when a Lisp program reports a warning.
726 @defopt warning-minimum-level
727 This user option specifies the minimum severity level that should be
728 shown immediately to the user. The default is @code{:warning}, which
729 means to immediately display all warnings except @code{:debug}
733 @defopt warning-minimum-log-level
734 This user option specifies the minimum severity level that should be
735 logged in the warnings buffer. The default is @code{:warning}, which
736 means to log all warnings except @code{:debug} warnings.
739 @defopt warning-suppress-types
740 This list specifies which warning types should not be displayed
741 immediately for the user. Each element of the list should be a list
742 of symbols. If its elements match the first elements in a warning
743 type, then that warning is not displayed immediately.
746 @defopt warning-suppress-log-types
747 This list specifies which warning types should not be logged in the
748 warnings buffer. Each element of the list should be a list of
749 symbols. If it matches the first few elements in a warning type, then
750 that warning is not logged.
754 @section Invisible Text
756 @cindex invisible text
757 You can make characters @dfn{invisible}, so that they do not appear on
758 the screen, with the @code{invisible} property. This can be either a
759 text property (@pxref{Text Properties}) or a property of an overlay
760 (@pxref{Overlays}). Cursor motion also partly ignores these
761 characters; if the command loop finds point within them, it moves
762 point to the other side of them.
764 In the simplest case, any non-@code{nil} @code{invisible} property makes
765 a character invisible. This is the default case---if you don't alter
766 the default value of @code{buffer-invisibility-spec}, this is how the
767 @code{invisible} property works. You should normally use @code{t}
768 as the value of the @code{invisible} property if you don't plan
769 to set @code{buffer-invisibility-spec} yourself.
771 More generally, you can use the variable @code{buffer-invisibility-spec}
772 to control which values of the @code{invisible} property make text
773 invisible. This permits you to classify the text into different subsets
774 in advance, by giving them different @code{invisible} values, and
775 subsequently make various subsets visible or invisible by changing the
776 value of @code{buffer-invisibility-spec}.
778 Controlling visibility with @code{buffer-invisibility-spec} is
779 especially useful in a program to display the list of entries in a
780 database. It permits the implementation of convenient filtering
781 commands to view just a part of the entries in the database. Setting
782 this variable is very fast, much faster than scanning all the text in
783 the buffer looking for properties to change.
785 @defvar buffer-invisibility-spec
786 This variable specifies which kinds of @code{invisible} properties
787 actually make a character invisible. Setting this variable makes it
792 A character is invisible if its @code{invisible} property is
793 non-@code{nil}. This is the default.
796 Each element of the list specifies a criterion for invisibility; if a
797 character's @code{invisible} property fits any one of these criteria,
798 the character is invisible. The list can have two kinds of elements:
802 A character is invisible if its @code{invisible} property value
803 is @var{atom} or if it is a list with @var{atom} as a member.
805 @item (@var{atom} . t)
806 A character is invisible if its @code{invisible} property value is
807 @var{atom} or if it is a list with @var{atom} as a member. Moreover,
808 a sequence of such characters displays as an ellipsis.
813 Two functions are specifically provided for adding elements to
814 @code{buffer-invisibility-spec} and removing elements from it.
816 @defun add-to-invisibility-spec element
817 This function adds the element @var{element} to
818 @code{buffer-invisibility-spec}. If @code{buffer-invisibility-spec}
819 was @code{t}, it changes to a list, @code{(t)}, so that text whose
820 @code{invisible} property is @code{t} remains invisible.
823 @defun remove-from-invisibility-spec element
824 This removes the element @var{element} from
825 @code{buffer-invisibility-spec}. This does nothing if @var{element}
829 A convention for use of @code{buffer-invisibility-spec} is that a
830 major mode should use the mode's own name as an element of
831 @code{buffer-invisibility-spec} and as the value of the
832 @code{invisible} property:
835 ;; @r{If you want to display an ellipsis:}
836 (add-to-invisibility-spec '(my-symbol . t))
837 ;; @r{If you don't want ellipsis:}
838 (add-to-invisibility-spec 'my-symbol)
840 (overlay-put (make-overlay beginning end)
841 'invisible 'my-symbol)
843 ;; @r{When done with the overlays:}
844 (remove-from-invisibility-spec '(my-symbol . t))
845 ;; @r{Or respectively:}
846 (remove-from-invisibility-spec 'my-symbol)
849 @vindex line-move-ignore-invisible
850 Ordinarily, functions that operate on text or move point do not care
851 whether the text is invisible. The user-level line motion commands
852 explicitly ignore invisible newlines if
853 @code{line-move-ignore-invisible} is non-@code{nil} (the default), but
854 only because they are explicitly programmed to do so.
856 However, if a command ends with point inside or immediately before
857 invisible text, the main editing loop moves point further forward or
858 further backward (in the same direction that the command already moved
859 it) until that condition is no longer true. Thus, if the command
860 moved point back into an invisible range, Emacs moves point back to
861 the beginning of that range, and then back one more character. If the
862 command moved point forward into an invisible range, Emacs moves point
863 forward up to the first visible character that follows the invisible
866 Incremental search can make invisible overlays visible temporarily
867 and/or permanently when a match includes invisible text. To enable
868 this, the overlay should have a non-@code{nil}
869 @code{isearch-open-invisible} property. The property value should be a
870 function to be called with the overlay as an argument. This function
871 should make the overlay visible permanently; it is used when the match
872 overlaps the overlay on exit from the search.
874 During the search, such overlays are made temporarily visible by
875 temporarily modifying their invisible and intangible properties. If you
876 want this to be done differently for a certain overlay, give it an
877 @code{isearch-open-invisible-temporary} property which is a function.
878 The function is called with two arguments: the first is the overlay, and
879 the second is @code{nil} to make the overlay visible, or @code{t} to
880 make it invisible again.
882 @node Selective Display
883 @section Selective Display
884 @c @cindex selective display Duplicates selective-display
886 @dfn{Selective display} refers to a pair of related features for
887 hiding certain lines on the screen.
889 The first variant, explicit selective display, is designed for use
890 in a Lisp program: it controls which lines are hidden by altering the
891 text. This kind of hiding in some ways resembles the effect of the
892 @code{invisible} property (@pxref{Invisible Text}), but the two
893 features are different and do not work the same way.
895 In the second variant, the choice of lines to hide is made
896 automatically based on indentation. This variant is designed to be a
899 The way you control explicit selective display is by replacing a
900 newline (control-j) with a carriage return (control-m). The text that
901 was formerly a line following that newline is now hidden. Strictly
902 speaking, it is temporarily no longer a line at all, since only
903 newlines can separate lines; it is now part of the previous line.
905 Selective display does not directly affect editing commands. For
906 example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly
907 into hidden text. However, the replacement of newline characters with
908 carriage return characters affects some editing commands. For
909 example, @code{next-line} skips hidden lines, since it searches only
910 for newlines. Modes that use selective display can also define
911 commands that take account of the newlines, or that control which
912 parts of the text are hidden.
914 When you write a selectively displayed buffer into a file, all the
915 control-m's are output as newlines. This means that when you next read
916 in the file, it looks OK, with nothing hidden. The selective display
917 effect is seen only within Emacs.
919 @defvar selective-display
920 This buffer-local variable enables selective display. This means that
921 lines, or portions of lines, may be made hidden.
925 If the value of @code{selective-display} is @code{t}, then the character
926 control-m marks the start of hidden text; the control-m, and the rest
927 of the line following it, are not displayed. This is explicit selective
931 If the value of @code{selective-display} is a positive integer, then
932 lines that start with more than that many columns of indentation are not
936 When some portion of a buffer is hidden, the vertical movement
937 commands operate as if that portion did not exist, allowing a single
938 @code{next-line} command to skip any number of hidden lines.
939 However, character movement commands (such as @code{forward-char}) do
940 not skip the hidden portion, and it is possible (if tricky) to insert
941 or delete text in an hidden portion.
943 In the examples below, we show the @emph{display appearance} of the
944 buffer @code{foo}, which changes with the value of
945 @code{selective-display}. The @emph{contents} of the buffer do not
950 (setq selective-display nil)
953 ---------- Buffer: foo ----------
960 ---------- Buffer: foo ----------
964 (setq selective-display 2)
967 ---------- Buffer: foo ----------
972 ---------- Buffer: foo ----------
977 @defvar selective-display-ellipses
978 If this buffer-local variable is non-@code{nil}, then Emacs displays
979 @samp{@dots{}} at the end of a line that is followed by hidden text.
980 This example is a continuation of the previous one.
984 (setq selective-display-ellipses t)
987 ---------- Buffer: foo ----------
992 ---------- Buffer: foo ----------
996 You can use a display table to substitute other text for the ellipsis
997 (@samp{@dots{}}). @xref{Display Tables}.
1000 @node Temporary Displays
1001 @section Temporary Displays
1003 Temporary displays are used by Lisp programs to put output into a
1004 buffer and then present it to the user for perusal rather than for
1005 editing. Many help commands use this feature.
1007 @defspec with-output-to-temp-buffer buffer-name forms@dots{}
1008 This function executes @var{forms} while arranging to insert any output
1009 they print into the buffer named @var{buffer-name}, which is first
1010 created if necessary, and put into Help mode. Finally, the buffer is
1011 displayed in some window, but not selected.
1013 If the @var{forms} do not change the major mode in the output buffer,
1014 so that it is still Help mode at the end of their execution, then
1015 @code{with-output-to-temp-buffer} makes this buffer read-only at the
1016 end, and also scans it for function and variable names to make them
1017 into clickable cross-references. @xref{Docstring hyperlinks, , Tips
1018 for Documentation Strings}, in particular the item on hyperlinks in
1019 documentation strings, for more details.
1021 The string @var{buffer-name} specifies the temporary buffer, which
1022 need not already exist. The argument must be a string, not a buffer.
1023 The buffer is erased initially (with no questions asked), and it is
1024 marked as unmodified after @code{with-output-to-temp-buffer} exits.
1026 @code{with-output-to-temp-buffer} binds @code{standard-output} to the
1027 temporary buffer, then it evaluates the forms in @var{forms}. Output
1028 using the Lisp output functions within @var{forms} goes by default to
1029 that buffer (but screen display and messages in the echo area, although
1030 they are ``output'' in the general sense of the word, are not affected).
1031 @xref{Output Functions}.
1033 Several hooks are available for customizing the behavior
1034 of this construct; they are listed below.
1036 The value of the last form in @var{forms} is returned.
1040 ---------- Buffer: foo ----------
1041 This is the contents of foo.
1042 ---------- Buffer: foo ----------
1046 (with-output-to-temp-buffer "foo"
1048 (print standard-output))
1049 @result{} #<buffer foo>
1051 ---------- Buffer: foo ----------
1056 ---------- Buffer: foo ----------
1061 @defvar temp-buffer-show-function
1062 If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
1063 calls it as a function to do the job of displaying a help buffer. The
1064 function gets one argument, which is the buffer it should display.
1066 It is a good idea for this function to run @code{temp-buffer-show-hook}
1067 just as @code{with-output-to-temp-buffer} normally would, inside of
1068 @code{save-selected-window} and with the chosen window and buffer
1072 @defvar temp-buffer-setup-hook
1073 This normal hook is run by @code{with-output-to-temp-buffer} before
1074 evaluating @var{body}. When the hook runs, the temporary buffer is
1075 current. This hook is normally set up with a function to put the
1076 buffer in Help mode.
1079 @defvar temp-buffer-show-hook
1080 This normal hook is run by @code{with-output-to-temp-buffer} after
1081 displaying the temporary buffer. When the hook runs, the temporary buffer
1082 is current, and the window it was displayed in is selected.
1085 @defun momentary-string-display string position &optional char message
1086 This function momentarily displays @var{string} in the current buffer at
1087 @var{position}. It has no effect on the undo list or on the buffer's
1088 modification status.
1090 The momentary display remains until the next input event. If the next
1091 input event is @var{char}, @code{momentary-string-display} ignores it
1092 and returns. Otherwise, that event remains buffered for subsequent use
1093 as input. Thus, typing @var{char} will simply remove the string from
1094 the display, while typing (say) @kbd{C-f} will remove the string from
1095 the display and later (presumably) move point forward. The argument
1096 @var{char} is a space by default.
1098 The return value of @code{momentary-string-display} is not meaningful.
1100 If the string @var{string} does not contain control characters, you can
1101 do the same job in a more general way by creating (and then subsequently
1102 deleting) an overlay with a @code{before-string} property.
1103 @xref{Overlay Properties}.
1105 If @var{message} is non-@code{nil}, it is displayed in the echo area
1106 while @var{string} is displayed in the buffer. If it is @code{nil}, a
1107 default message says to type @var{char} to continue.
1109 In this example, point is initially located at the beginning of the
1114 ---------- Buffer: foo ----------
1115 This is the contents of foo.
1116 @point{}Second line.
1117 ---------- Buffer: foo ----------
1121 (momentary-string-display
1122 "**** Important Message! ****"
1124 "Type RET when done reading")
1129 ---------- Buffer: foo ----------
1130 This is the contents of foo.
1131 **** Important Message! ****Second line.
1132 ---------- Buffer: foo ----------
1134 ---------- Echo Area ----------
1135 Type RET when done reading
1136 ---------- Echo Area ----------
1145 You can use @dfn{overlays} to alter the appearance of a buffer's text on
1146 the screen, for the sake of presentation features. An overlay is an
1147 object that belongs to a particular buffer, and has a specified
1148 beginning and end. It also has properties that you can examine and set;
1149 these affect the display of the text within the overlay.
1151 An overlay uses markers to record its beginning and end; thus,
1152 editing the text of the buffer adjusts the beginning and end of each
1153 overlay so that it stays with the text. When you create the overlay,
1154 you can specify whether text inserted at the beginning should be
1155 inside the overlay or outside, and likewise for the end of the overlay.
1158 * Managing Overlays:: Creating and moving overlays.
1159 * Overlay Properties:: How to read and set properties.
1160 What properties do to the screen display.
1161 * Finding Overlays:: Searching for overlays.
1164 @node Managing Overlays
1165 @subsection Managing Overlays
1167 This section describes the functions to create, delete and move
1168 overlays, and to examine their contents. Overlay changes are not
1169 recorded in the buffer's undo list, since the overlays are not
1170 part of the buffer's contents.
1172 @defun overlayp object
1173 This function returns @code{t} if @var{object} is an overlay.
1176 @defun make-overlay start end &optional buffer front-advance rear-advance
1177 This function creates and returns an overlay that belongs to
1178 @var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
1179 and @var{end} must specify buffer positions; they may be integers or
1180 markers. If @var{buffer} is omitted, the overlay is created in the
1183 The arguments @var{front-advance} and @var{rear-advance} specify the
1184 marker insertion type for the start of the overlay and for the end of
1185 the overlay, respectively. @xref{Marker Insertion Types}. If they
1186 are both @code{nil}, the default, then the overlay extends to include
1187 any text inserted at the beginning, but not text inserted at the end.
1188 If @var{front-advance} is non-@code{nil}, text inserted at the
1189 beginning of the overlay is excluded from the overlay. If
1190 @var{rear-advance} is non-@code{nil}, text inserted at the end of the
1191 overlay is included in the overlay.
1194 @defun overlay-start overlay
1195 This function returns the position at which @var{overlay} starts,
1199 @defun overlay-end overlay
1200 This function returns the position at which @var{overlay} ends,
1204 @defun overlay-buffer overlay
1205 This function returns the buffer that @var{overlay} belongs to. It
1206 returns @code{nil} if @var{overlay} has been deleted.
1209 @defun delete-overlay overlay
1210 This function deletes @var{overlay}. The overlay continues to exist as
1211 a Lisp object, and its property list is unchanged, but it ceases to be
1212 attached to the buffer it belonged to, and ceases to have any effect on
1215 A deleted overlay is not permanently disconnected. You can give it a
1216 position in a buffer again by calling @code{move-overlay}.
1219 @defun move-overlay overlay start end &optional buffer
1220 This function moves @var{overlay} to @var{buffer}, and places its bounds
1221 at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
1222 must specify buffer positions; they may be integers or markers.
1224 If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
1225 was already associated with; if @var{overlay} was deleted, it goes into
1228 The return value is @var{overlay}.
1230 This is the only valid way to change the endpoints of an overlay. Do
1231 not try modifying the markers in the overlay by hand, as that fails to
1232 update other vital data structures and can cause some overlays to be
1236 @defun remove-overlays &optional start end name value
1237 This function removes all the overlays between @var{start} and
1238 @var{end} whose property @var{name} has the value @var{value}. It can
1239 move the endpoints of the overlays in the region, or split them.
1241 If @var{name} is omitted or @code{nil}, it means to delete all overlays in
1242 the specified region. If @var{start} and/or @var{end} are omitted or
1243 @code{nil}, that means the beginning and end of the buffer respectively.
1244 Therefore, @code{(remove-overlays)} removes all the overlays in the
1248 Here are some examples:
1251 ;; @r{Create an overlay.}
1252 (setq foo (make-overlay 1 10))
1253 @result{} #<overlay from 1 to 10 in display.texi>
1258 (overlay-buffer foo)
1259 @result{} #<buffer display.texi>
1260 ;; @r{Give it a property we can check later.}
1261 (overlay-put foo 'happy t)
1263 ;; @r{Verify the property is present.}
1264 (overlay-get foo 'happy)
1266 ;; @r{Move the overlay.}
1267 (move-overlay foo 5 20)
1268 @result{} #<overlay from 5 to 20 in display.texi>
1273 ;; @r{Delete the overlay.}
1274 (delete-overlay foo)
1276 ;; @r{Verify it is deleted.}
1278 @result{} #<overlay in no buffer>
1279 ;; @r{A deleted overlay has no position.}
1284 (overlay-buffer foo)
1286 ;; @r{Undelete the overlay.}
1287 (move-overlay foo 1 20)
1288 @result{} #<overlay from 1 to 20 in display.texi>
1289 ;; @r{Verify the results.}
1294 (overlay-buffer foo)
1295 @result{} #<buffer display.texi>
1296 ;; @r{Moving and deleting the overlay does not change its properties.}
1297 (overlay-get foo 'happy)
1301 Emacs stores the overlays of each buffer in two lists, divided
1302 around an arbitrary ``center position.'' One list extends backwards
1303 through the buffer from that center position, and the other extends
1304 forwards from that center position. The center position can be anywhere
1307 @defun overlay-recenter pos
1308 This function recenters the overlays of the current buffer around
1309 position @var{pos}. That makes overlay lookup faster for positions
1310 near @var{pos}, but slower for positions far away from @var{pos}.
1313 A loop that scans the buffer forwards, creating overlays, can run
1314 faster if you do @code{(overlay-recenter (point-max))} first.
1316 @node Overlay Properties
1317 @subsection Overlay Properties
1319 Overlay properties are like text properties in that the properties that
1320 alter how a character is displayed can come from either source. But in
1321 most respects they are different. @xref{Text Properties}, for comparison.
1323 Text properties are considered a part of the text; overlays and
1324 their properties are specifically considered not to be part of the
1325 text. Thus, copying text between various buffers and strings
1326 preserves text properties, but does not try to preserve overlays.
1327 Changing a buffer's text properties marks the buffer as modified,
1328 while moving an overlay or changing its properties does not. Unlike
1329 text property changes, overlay property changes are not recorded in
1330 the buffer's undo list.
1332 Since more than one overlay can specify a property value for the
1333 same character, Emacs lets you specify a priority value of each
1334 overlay. You should not make assumptions about which overlay will
1335 prevail when there is a conflict and they have the same priority.
1337 These functions read and set the properties of an overlay:
1339 @defun overlay-get overlay prop
1340 This function returns the value of property @var{prop} recorded in
1341 @var{overlay}, if any. If @var{overlay} does not record any value for
1342 that property, but it does have a @code{category} property which is a
1343 symbol, that symbol's @var{prop} property is used. Otherwise, the value
1347 @defun overlay-put overlay prop value
1348 This function sets the value of property @var{prop} recorded in
1349 @var{overlay} to @var{value}. It returns @var{value}.
1352 @defun overlay-properties overlay
1353 This returns a copy of the property list of @var{overlay}.
1356 See also the function @code{get-char-property} which checks both
1357 overlay properties and text properties for a given character.
1358 @xref{Examining Properties}.
1360 Many overlay properties have special meanings; here is a table
1365 @kindex priority @r{(overlay property)}
1366 This property's value (which should be a nonnegative integer number)
1367 determines the priority of the overlay. No priority, or @code{nil},
1370 The priority matters when two or more overlays cover the same
1371 character and both specify the same property; the one whose
1372 @code{priority} value is larger overrides the other. For the
1373 @code{face} property, the higher priority overlay's value does not
1374 completely override the other value; instead, its face attributes
1375 override the face attributes of the lower priority @code{face}
1378 Currently, all overlays take priority over text properties. Please
1379 avoid using negative priority values, as we have not yet decided just
1380 what they should mean.
1383 @kindex window @r{(overlay property)}
1384 If the @code{window} property is non-@code{nil}, then the overlay
1385 applies only on that window.
1388 @kindex category @r{(overlay property)}
1389 If an overlay has a @code{category} property, we call it the
1390 @dfn{category} of the overlay. It should be a symbol. The properties
1391 of the symbol serve as defaults for the properties of the overlay.
1394 @kindex face @r{(overlay property)}
1395 This property controls the way text is displayed---for example, which
1396 font and which colors. @xref{Faces}, for more information.
1398 In the simplest case, the value is a face name. It can also be a list;
1399 then each element can be any of these possibilities:
1403 A face name (a symbol or string).
1406 A property list of face attributes. This has the form (@var{keyword}
1407 @var{value} @dots{}), where each @var{keyword} is a face attribute
1408 name and @var{value} is a meaningful value for that attribute. With
1409 this feature, you do not need to create a face each time you want to
1410 specify a particular attribute for certain text. @xref{Face
1414 A cons cell, either of the form @code{(foreground-color . @var{color-name})} or
1415 @code{(background-color . @var{color-name})}. These elements specify
1416 just the foreground color or just the background color.
1418 @code{(foreground-color . @var{color-name})} has the same effect as
1419 @code{(:foreground @var{color-name})}; likewise for the background.
1423 @kindex mouse-face @r{(overlay property)}
1424 This property is used instead of @code{face} when the mouse is within
1425 the range of the overlay.
1428 @kindex display @r{(overlay property)}
1429 This property activates various features that change the
1430 way text is displayed. For example, it can make text appear taller
1431 or shorter, higher or lower, wider or narrower, or replaced with an image.
1432 @xref{Display Property}.
1435 @kindex help-echo @r{(overlay property)}
1436 If an overlay has a @code{help-echo} property, then when you move the
1437 mouse onto the text in the overlay, Emacs displays a help string in the
1438 echo area, or in the tooltip window. For details see @ref{Text
1441 @item modification-hooks
1442 @kindex modification-hooks @r{(overlay property)}
1443 This property's value is a list of functions to be called if any
1444 character within the overlay is changed or if text is inserted strictly
1447 The hook functions are called both before and after each change.
1448 If the functions save the information they receive, and compare notes
1449 between calls, they can determine exactly what change has been made
1452 When called before a change, each function receives four arguments: the
1453 overlay, @code{nil}, and the beginning and end of the text range to be
1456 When called after a change, each function receives five arguments: the
1457 overlay, @code{t}, the beginning and end of the text range just
1458 modified, and the length of the pre-change text replaced by that range.
1459 (For an insertion, the pre-change length is zero; for a deletion, that
1460 length is the number of characters deleted, and the post-change
1461 beginning and end are equal.)
1463 If these functions modify the buffer, they should bind
1464 @code{inhibit-modification-hooks} to @code{t} around doing so, to
1465 avoid confusing the internal mechanism that calls these hooks.
1467 Text properties also support the @code{modification-hooks} property,
1468 but the details are somewhat different (@pxref{Special Properties}).
1470 @item insert-in-front-hooks
1471 @kindex insert-in-front-hooks @r{(overlay property)}
1472 This property's value is a list of functions to be called before and
1473 after inserting text right at the beginning of the overlay. The calling
1474 conventions are the same as for the @code{modification-hooks} functions.
1476 @item insert-behind-hooks
1477 @kindex insert-behind-hooks @r{(overlay property)}
1478 This property's value is a list of functions to be called before and
1479 after inserting text right at the end of the overlay. The calling
1480 conventions are the same as for the @code{modification-hooks} functions.
1483 @kindex invisible @r{(overlay property)}
1484 The @code{invisible} property can make the text in the overlay
1485 invisible, which means that it does not appear on the screen.
1486 @xref{Invisible Text}, for details.
1489 @kindex intangible @r{(overlay property)}
1490 The @code{intangible} property on an overlay works just like the
1491 @code{intangible} text property. @xref{Special Properties}, for details.
1493 @item isearch-open-invisible
1494 This property tells incremental search how to make an invisible overlay
1495 visible, permanently, if the final match overlaps it. @xref{Invisible
1498 @item isearch-open-invisible-temporary
1499 This property tells incremental search how to make an invisible overlay
1500 visible, temporarily, during the search. @xref{Invisible Text}.
1503 @kindex before-string @r{(overlay property)}
1504 This property's value is a string to add to the display at the beginning
1505 of the overlay. The string does not appear in the buffer in any
1506 sense---only on the screen.
1509 @kindex after-string @r{(overlay property)}
1510 This property's value is a string to add to the display at the end of
1511 the overlay. The string does not appear in the buffer in any
1512 sense---only on the screen.
1515 @kindex evaporate @r{(overlay property)}
1516 If this property is non-@code{nil}, the overlay is deleted automatically
1517 if it becomes empty (i.e., if its length becomes zero). If you give
1518 an empty overlay a non-@code{nil} @code{evaporate} property, that deletes
1522 @cindex keymap of character (and overlays)
1523 @kindex local-map @r{(overlay property)}
1524 If this property is non-@code{nil}, it specifies a keymap for a portion
1525 of the text. The property's value replaces the buffer's local map, when
1526 the character after point is within the overlay. @xref{Active Keymaps}.
1529 @kindex keymap @r{(overlay property)}
1530 The @code{keymap} property is similar to @code{local-map} but overrides the
1531 buffer's local map (and the map specified by the @code{local-map}
1532 property) rather than replacing it.
1535 The @code{local-map} and @code{keymap} properties do not affect a
1536 string displayed by the @code{before-string}, @code{after-string}, or
1537 @code{display} properties. This is only relevant for mouse clicks and
1538 other mouse events that fall on the string, since point is never on
1539 the string. To bind special mouse events for the string, assign it a
1540 @code{local-map} or @code{keymap} text property. @xref{Special
1543 @node Finding Overlays
1544 @subsection Searching for Overlays
1546 @defun overlays-at pos
1547 This function returns a list of all the overlays that cover the
1548 character at position @var{pos} in the current buffer. The list is in
1549 no particular order. An overlay contains position @var{pos} if it
1550 begins at or before @var{pos}, and ends after @var{pos}.
1552 To illustrate usage, here is a Lisp function that returns a list of the
1553 overlays that specify property @var{prop} for the character at point:
1556 (defun find-overlays-specifying (prop)
1557 (let ((overlays (overlays-at (point)))
1560 (let ((overlay (car overlays)))
1561 (if (overlay-get overlay prop)
1562 (setq found (cons overlay found))))
1563 (setq overlays (cdr overlays)))
1568 @defun overlays-in beg end
1569 This function returns a list of the overlays that overlap the region
1570 @var{beg} through @var{end}. ``Overlap'' means that at least one
1571 character is contained within the overlay and also contained within the
1572 specified region; however, empty overlays are included in the result if
1573 they are located at @var{beg}, strictly between @var{beg} and @var{end},
1574 or at @var{end} when @var{end} denotes the position at the end of the
1578 @defun next-overlay-change pos
1579 This function returns the buffer position of the next beginning or end
1580 of an overlay, after @var{pos}. If there is none, it returns
1584 @defun previous-overlay-change pos
1585 This function returns the buffer position of the previous beginning or
1586 end of an overlay, before @var{pos}. If there is none, it returns
1590 As an example, here's a simplified (and inefficient) version of the
1591 primitive function @code{next-single-char-property-change}
1592 (@pxref{Property Search}). It searches forward from position
1593 @var{pos} for the next position where the value of a given property
1594 @code{prop}, as obtained from either overlays or text properties,
1598 (defun next-single-char-property-change (position prop)
1600 (goto-char position)
1601 (let ((propval (get-char-property (point) prop)))
1602 (while (and (not (eobp))
1603 (eq (get-char-property (point) prop) propval))
1604 (goto-char (min (next-overlay-change (point))
1605 (next-single-property-change (point) prop)))))
1612 Since not all characters have the same width, these functions let you
1613 check the width of a character. @xref{Primitive Indent}, and
1614 @ref{Screen Lines}, for related functions.
1616 @defun char-width char
1617 This function returns the width in columns of the character @var{char},
1618 if it were displayed in the current buffer and the selected window.
1621 @defun string-width string
1622 This function returns the width in columns of the string @var{string},
1623 if it were displayed in the current buffer and the selected window.
1626 @defun truncate-string-to-width string width &optional start-column padding ellipsis
1627 This function returns the part of @var{string} that fits within
1628 @var{width} columns, as a new string.
1630 If @var{string} does not reach @var{width}, then the result ends where
1631 @var{string} ends. If one multi-column character in @var{string}
1632 extends across the column @var{width}, that character is not included in
1633 the result. Thus, the result can fall short of @var{width} but cannot
1636 The optional argument @var{start-column} specifies the starting column.
1637 If this is non-@code{nil}, then the first @var{start-column} columns of
1638 the string are omitted from the value. If one multi-column character in
1639 @var{string} extends across the column @var{start-column}, that
1640 character is not included.
1642 The optional argument @var{padding}, if non-@code{nil}, is a padding
1643 character added at the beginning and end of the result string, to extend
1644 it to exactly @var{width} columns. The padding character is used at the
1645 end of the result if it falls short of @var{width}. It is also used at
1646 the beginning of the result if one multi-column character in
1647 @var{string} extends across the column @var{start-column}.
1649 If @var{ellipsis} is non-@code{nil}, it should be a string which will
1650 replace the end of @var{str} (including any padding) if it extends
1651 beyond @var{end-column}, unless the display width of @var{str} is
1652 equal to or less than the display width of @var{ellipsis}. If
1653 @var{ellipsis} is non-@code{nil} and not a string, it stands for
1657 (truncate-string-to-width "\tab\t" 12 4)
1659 (truncate-string-to-width "\tab\t" 12 4 ?\s)
1665 @section Line Height
1668 The total height of each display line consists of the height of the
1669 contents of the line, plus optional additional vertical line spacing
1670 above or below the display line.
1672 The height of the line contents is the maximum height of any
1673 character or image on that display line, including the final newline
1674 if there is one. (A display line that is continued doesn't include a
1675 final newline.) That is the default line height, if you do nothing to
1676 specify a greater height. (In the most common case, this equals the
1677 height of the default frame font.)
1679 There are several ways to explicitly specify a larger line height,
1680 either by specifying an absolute height for the display line, or by
1681 specifying vertical space. However, no matter what you specify, the
1682 actual line height can never be less than the default.
1684 @kindex line-height @r{(text property)}
1685 A newline can have a @code{line-height} text or overlay property
1686 that controls the total height of the display line ending in that
1689 If the property value is @code{t}, the newline character has no
1690 effect on the displayed height of the line---the visible contents
1691 alone determine the height. This is useful for tiling small images
1692 (or image slices) without adding blank areas between the images.
1694 If the property value is a list of the form @code{(@var{height}
1695 @var{total})}, that adds extra space @emph{below} the display line.
1696 First Emacs uses @var{height} as a height spec to control extra space
1697 @emph{above} the line; then it adds enough space @emph{below} the line
1698 to bring the total line height up to @var{total}. In this case, the
1699 other ways to specify the line spacing are ignored.
1701 Any other kind of property value is a height spec, which translates
1702 into a number---the specified line height. There are several ways to
1703 write a height spec; here's how each of them translates into a number:
1707 If the height spec is a positive integer, the height value is that integer.
1709 If the height spec is a float, @var{float}, the numeric height value
1710 is @var{float} times the frame's default line height.
1711 @item (@var{face} . @var{ratio})
1712 If the height spec is a cons of the format shown, the numeric height
1713 is @var{ratio} times the height of face @var{face}. @var{ratio} can
1714 be any type of number, or @code{nil} which means a ratio of 1.
1715 If @var{face} is @code{t}, it refers to the current face.
1716 @item (nil . @var{ratio})
1717 If the height spec is a cons of the format shown, the numeric height
1718 is @var{ratio} times the height of the contents of the line.
1721 Thus, any valid height spec determines the height in pixels, one way
1722 or another. If the line contents' height is less than that, Emacs
1723 adds extra vertical space above the line to achieve the specified
1726 If you don't specify the @code{line-height} property, the line's
1727 height consists of the contents' height plus the line spacing.
1728 There are several ways to specify the line spacing for different
1729 parts of Emacs text.
1731 @vindex default-line-spacing
1732 You can specify the line spacing for all lines in a frame with the
1733 @code{line-spacing} frame parameter (@pxref{Layout Parameters}).
1734 However, if the variable @code{default-line-spacing} is
1735 non-@code{nil}, it overrides the frame's @code{line-spacing}
1736 parameter. An integer value specifies the number of pixels put below
1737 lines on graphical displays. A floating point number specifies the
1738 spacing relative to the frame's default line height.
1740 @vindex line-spacing
1741 You can specify the line spacing for all lines in a buffer via the
1742 buffer-local @code{line-spacing} variable. An integer value specifies
1743 the number of pixels put below lines on graphical displays. A floating
1744 point number specifies the spacing relative to the default frame line
1745 height. This overrides line spacings specified for the frame.
1747 @kindex line-spacing @r{(text property)}
1748 Finally, a newline can have a @code{line-spacing} text or overlay
1749 property that overrides the default frame line spacing and the buffer
1750 local @code{line-spacing} variable, for the display line ending in
1753 One way or another, these mechanisms specify a Lisp value for the
1754 spacing of each line. The value is a height spec, and it translates
1755 into a Lisp value as described above. However, in this case the
1756 numeric height value specifies the line spacing, rather than the line
1763 A @dfn{face} is a named collection of graphical attributes: font
1764 family, foreground color, background color, optional underlining, and
1765 many others. Faces are used in Emacs to control the style of display of
1766 particular parts of the text or the frame. @xref{Standard Faces,,,
1767 emacs, The GNU Emacs Manual}, for the list of faces Emacs normally
1771 Each face has its own @dfn{face number}, which distinguishes faces at
1772 low levels within Emacs. However, for most purposes, you refer to
1773 faces in Lisp programs by the symbols that name them.
1776 This function returns @code{t} if @var{object} is a face name string
1777 or symbol. It returns @code{nil} otherwise.
1780 Each face name is meaningful for all frames, and by default it has the
1781 same meaning in all frames. But you can arrange to give a particular
1782 face name a special meaning in one frame if you wish.
1785 * Defining Faces:: How to define a face with @code{defface}.
1786 * Face Attributes:: What is in a face?
1787 * Attribute Functions:: Functions to examine and set face attributes.
1788 * Displaying Faces:: How Emacs combines the faces specified for a character.
1789 * Font Selection:: Finding the best available font for a face.
1790 * Face Functions:: How to define and examine faces.
1791 * Auto Faces:: Hook for automatic face assignment.
1792 * Font Lookup:: Looking up the names of available fonts
1793 and information about them.
1794 * Fontsets:: A fontset is a collection of fonts
1795 that handle a range of character sets.
1798 @node Defining Faces
1799 @subsection Defining Faces
1801 The way to define a new face is with @code{defface}. This creates a
1802 kind of customization item (@pxref{Customization}) which the user can
1803 customize using the Customization buffer (@pxref{Easy Customization,,,
1804 emacs, The GNU Emacs Manual}).
1806 People are sometimes tempted to create variables whose values specify
1807 which faces to use (for example, Font-Lock does this). In the vast
1808 majority of cases, this is not necessary, and simply using faces
1809 directly is preferable.
1811 @defmac defface face spec doc [keyword value]@dots{}
1812 This declares @var{face} as a customizable face that defaults
1813 according to @var{spec}. You should not quote the symbol @var{face},
1814 and it should not end in @samp{-face} (that would be redundant). The
1815 argument @var{doc} specifies the face documentation. The keywords you
1816 can use in @code{defface} are the same as in @code{defgroup} and
1817 @code{defcustom} (@pxref{Common Keywords}).
1819 When @code{defface} executes, it defines the face according to
1820 @var{spec}, then uses any customizations that were read from the
1821 init file (@pxref{Init File}) to override that specification.
1823 When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs
1824 Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun}
1825 overrides any customizations of the face. This way, the face reflects
1826 exactly what the @code{defface} says.
1828 The purpose of @var{spec} is to specify how the face should appear on
1829 different kinds of terminals. It should be an alist whose elements
1830 have the form @code{(@var{display} @var{atts})}. Each element's
1831 @sc{car}, @var{display}, specifies a class of terminals. (The first
1832 element, if its @sc{car} is @code{default}, is special---it specifies
1833 defaults for the remaining elements). The element's @sc{cadr},
1834 @var{atts}, is a list of face attributes and their values; it
1835 specifies what the face should look like on that kind of terminal.
1836 The possible attributes are defined in the value of
1837 @code{custom-face-attributes}.
1839 The @var{display} part of an element of @var{spec} determines which
1840 frames the element matches. If more than one element of @var{spec}
1841 matches a given frame, the first element that matches is the one used
1842 for that frame. There are three possibilities for @var{display}:
1845 @item @code{default}
1846 This element of @var{spec} doesn't match any frames; instead, it
1847 specifies defaults that apply to all frames. This kind of element, if
1848 used, must be the first element of @var{spec}. Each of the following
1849 elements can override any or all of these defaults.
1852 This element of @var{spec} matches all frames. Therefore, any
1853 subsequent elements of @var{spec} are never used. Normally
1854 @code{t} is used in the last (or only) element of @var{spec}.
1857 If @var{display} is a list, each element should have the form
1858 @code{(@var{characteristic} @var{value}@dots{})}. Here
1859 @var{characteristic} specifies a way of classifying frames, and the
1860 @var{value}s are possible classifications which @var{display} should
1861 apply to. Here are the possible values of @var{characteristic}:
1865 The kind of window system the frame uses---either @code{graphic} (any
1866 graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console),
1867 @code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty}
1868 (a non-graphics-capable display).
1869 @xref{Window Systems, window-system}.
1872 What kinds of colors the frame supports---either @code{color},
1873 @code{grayscale}, or @code{mono}.
1876 The kind of background---either @code{light} or @code{dark}.
1879 An integer that represents the minimum number of colors the frame
1880 should support. This matches a frame if its
1881 @code{display-color-cells} value is at least the specified integer.
1884 Whether or not the frame can display the face attributes given in
1885 @var{value}@dots{} (@pxref{Face Attributes}). See the documentation
1886 for the function @code{display-supports-face-attributes-p} for more
1887 information on exactly how this testing is done. @xref{Display Face
1891 If an element of @var{display} specifies more than one @var{value} for a
1892 given @var{characteristic}, any of those values is acceptable. If
1893 @var{display} has more than one element, each element should specify a
1894 different @var{characteristic}; then @emph{each} characteristic of the
1895 frame must match one of the @var{value}s specified for it in
1900 Here's how the standard face @code{region} is defined:
1905 '((((class color) (min-colors 88) (background dark))
1906 :background "blue3")
1908 (((class color) (min-colors 88) (background light))
1909 :background "lightgoldenrod2")
1910 (((class color) (min-colors 16) (background dark))
1911 :background "blue3")
1912 (((class color) (min-colors 16) (background light))
1913 :background "lightgoldenrod2")
1914 (((class color) (min-colors 8))
1915 :background "blue" :foreground "white")
1916 (((type tty) (class mono))
1918 (t :background "gray"))
1920 "Basic face for highlighting the region."
1921 :group 'basic-faces)
1925 Internally, @code{defface} uses the symbol property
1926 @code{face-defface-spec} to record the face attributes specified in
1927 @code{defface}, @code{saved-face} for the attributes saved by the user
1928 with the customization buffer, @code{customized-face} for the
1929 attributes customized by the user for the current session, but not
1930 saved, and @code{face-documentation} for the documentation string.
1932 @defopt frame-background-mode
1933 This option, if non-@code{nil}, specifies the background type to use for
1934 interpreting face definitions. If it is @code{dark}, then Emacs treats
1935 all frames as if they had a dark background, regardless of their actual
1936 background colors. If it is @code{light}, then Emacs treats all frames
1937 as if they had a light background.
1940 @node Face Attributes
1941 @subsection Face Attributes
1942 @cindex face attributes
1944 The effect of using a face is determined by a fixed set of @dfn{face
1945 attributes}. This table lists all the face attributes, and what they
1946 mean. You can specify more than one face for a given piece of text;
1947 Emacs merges the attributes of all the faces to determine how to
1948 display the text. @xref{Displaying Faces}.
1950 Any attribute in a face can have the value @code{unspecified}. This
1951 means the face doesn't specify that attribute. In face merging, when
1952 the first face fails to specify a particular attribute, that means the
1953 next face gets a chance. However, the @code{default} face must
1954 specify all attributes.
1956 Some of these font attributes are meaningful only on certain kinds of
1957 displays---if your display cannot handle a certain attribute, the
1958 attribute is ignored. (The attributes @code{:family}, @code{:width},
1959 @code{:height}, @code{:weight}, and @code{:slant} correspond to parts of
1960 an X Logical Font Descriptor.)
1964 Font family name, or fontset name (@pxref{Fontsets}). If you specify a
1965 font family name, the wild-card characters @samp{*} and @samp{?} are
1969 Relative proportionate width, also known as the character set width or
1970 set width. This should be one of the symbols @code{ultra-condensed},
1971 @code{extra-condensed}, @code{condensed}, @code{semi-condensed},
1972 @code{normal}, @code{semi-expanded}, @code{expanded},
1973 @code{extra-expanded}, or @code{ultra-expanded}.
1976 Either the font height, an integer in units of 1/10 point, a floating
1977 point number specifying the amount by which to scale the height of any
1978 underlying face, or a function, which is called with the old height
1979 (from the underlying face), and should return the new height.
1982 Font weight---a symbol from this series (from most dense to most faint):
1983 @code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
1984 @code{normal}, @code{semi-light}, @code{light}, @code{extra-light},
1985 or @code{ultra-light}.
1987 On a text-only terminal, any weight greater than normal is displayed as
1988 extra bright, and any weight less than normal is displayed as
1989 half-bright (provided the terminal supports the feature).
1992 Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal},
1993 @code{reverse-italic}, or @code{reverse-oblique}.
1995 On a text-only terminal, slanted text is displayed as half-bright, if
1996 the terminal supports the feature.
1999 Foreground color, a string. The value can be a system-defined color
2000 name, or a hexadecimal color specification of the form
2001 @samp{#@var{rr}@var{gg}@var{bb}}. (@samp{#000000} is black,
2002 @samp{#ff0000} is red, @samp{#00ff00} is green, @samp{#0000ff} is
2003 blue, and @samp{#ffffff} is white.)
2006 Background color, a string, like the foreground color.
2008 @item :inverse-video
2009 Whether or not characters should be displayed in inverse video. The
2010 value should be @code{t} (yes) or @code{nil} (no).
2013 The background stipple, a bitmap.
2015 The value can be a string; that should be the name of a file containing
2016 external-format X bitmap data. The file is found in the directories
2017 listed in the variable @code{x-bitmap-file-path}.
2019 Alternatively, the value can specify the bitmap directly, with a list
2020 of the form @code{(@var{width} @var{height} @var{data})}. Here,
2021 @var{width} and @var{height} specify the size in pixels, and
2022 @var{data} is a string containing the raw bits of the bitmap, row by
2023 row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes
2024 in the string (which should be a unibyte string for best results).
2025 This means that each row always occupies at least one whole byte.
2027 If the value is @code{nil}, that means use no stipple pattern.
2029 Normally you do not need to set the stipple attribute, because it is
2030 used automatically to handle certain shades of gray.
2033 Whether or not characters should be underlined, and in what color. If
2034 the value is @code{t}, underlining uses the foreground color of the
2035 face. If the value is a string, underlining uses that color. The
2036 value @code{nil} means do not underline.
2039 Whether or not characters should be overlined, and in what color.
2040 The value is used like that of @code{:underline}.
2042 @item :strike-through
2043 Whether or not characters should be strike-through, and in what
2044 color. The value is used like that of @code{:underline}.
2047 The name of a face from which to inherit attributes, or a list of face
2048 names. Attributes from inherited faces are merged into the face like an
2049 underlying face would be, with higher priority than underlying faces.
2050 If a list of faces is used, attributes from faces earlier in the list
2051 override those from later faces.
2054 Whether or not a box should be drawn around characters, its color, the
2055 width of the box lines, and 3D appearance.
2058 Here are the possible values of the @code{:box} attribute, and what
2066 Draw a box with lines of width 1, in the foreground color.
2069 Draw a box with lines of width 1, in color @var{color}.
2071 @item @code{(:line-width @var{width} :color @var{color} :style @var{style})}
2072 This way you can explicitly specify all aspects of the box. The value
2073 @var{width} specifies the width of the lines to draw; it defaults to 1.
2075 The value @var{color} specifies the color to draw with. The default is
2076 the foreground color of the face for simple boxes, and the background
2077 color of the face for 3D boxes.
2079 The value @var{style} specifies whether to draw a 3D box. If it is
2080 @code{released-button}, the box looks like a 3D button that is not being
2081 pressed. If it is @code{pressed-button}, the box looks like a 3D button
2082 that is being pressed. If it is @code{nil} or omitted, a plain 2D box
2086 In older versions of Emacs, before @code{:family}, @code{:height},
2087 @code{:width}, @code{:weight}, and @code{:slant} existed, these
2088 attributes were used to specify the type face. They are now
2089 semi-obsolete, but they still work:
2093 This attribute specifies the font name.
2096 A non-@code{nil} value specifies a bold font.
2099 A non-@code{nil} value specifies an italic font.
2102 For compatibility, you can still set these ``attributes,'' even
2103 though they are not real face attributes. Here is what that does:
2107 You can specify an X font name as the ``value'' of this ``attribute'';
2108 that sets the @code{:family}, @code{:width}, @code{:height},
2109 @code{:weight}, and @code{:slant} attributes according to the font name.
2111 If the value is a pattern with wildcards, the first font that matches
2112 the pattern is used to set these attributes.
2115 A non-@code{nil} makes the face bold; @code{nil} makes it normal.
2116 This actually works by setting the @code{:weight} attribute.
2119 A non-@code{nil} makes the face italic; @code{nil} makes it normal.
2120 This actually works by setting the @code{:slant} attribute.
2123 @defvar x-bitmap-file-path
2124 This variable specifies a list of directories for searching
2125 for bitmap files, for the @code{:stipple} attribute.
2128 @defun bitmap-spec-p object
2129 This returns @code{t} if @var{object} is a valid bitmap specification,
2130 suitable for use with @code{:stipple} (see above). It returns
2131 @code{nil} otherwise.
2134 @node Attribute Functions
2135 @subsection Face Attribute Functions
2137 This section describes the functions for accessing and modifying the
2138 attributes of an existing face.
2140 @defun set-face-attribute face frame &rest arguments
2141 This function sets one or more attributes of face @var{face} for frame
2142 @var{frame}. The attributes you specify this way override whatever
2143 the @code{defface} says.
2145 The extra arguments @var{arguments} specify the attributes to set, and
2146 the values for them. They should consist of alternating attribute names
2147 (such as @code{:family} or @code{:underline}) and corresponding values.
2151 (set-face-attribute 'foo nil
2158 sets the attributes @code{:width}, @code{:weight} and @code{:underline}
2159 to the corresponding values.
2161 If @var{frame} is @code{t}, this function sets the default attributes
2162 for new frames. Default attribute values specified this way override
2163 the @code{defface} for newly created frames.
2165 If @var{frame} is @code{nil}, this function sets the attributes for
2166 all existing frames, and the default for new frames.
2169 @defun face-attribute face attribute &optional frame inherit
2170 This returns the value of the @var{attribute} attribute of face
2171 @var{face} on @var{frame}. If @var{frame} is @code{nil},
2172 that means the selected frame (@pxref{Input Focus}).
2174 If @var{frame} is @code{t}, this returns whatever new-frames default
2175 value you previously specified with @code{set-face-attribute} for the
2176 @var{attribute} attribute of @var{face}. If you have not specified
2177 one, it returns @code{nil}.
2179 If @var{inherit} is @code{nil}, only attributes directly defined by
2180 @var{face} are considered, so the return value may be
2181 @code{unspecified}, or a relative value. If @var{inherit} is
2182 non-@code{nil}, @var{face}'s definition of @var{attribute} is merged
2183 with the faces specified by its @code{:inherit} attribute; however the
2184 return value may still be @code{unspecified} or relative. If
2185 @var{inherit} is a face or a list of faces, then the result is further
2186 merged with that face (or faces), until it becomes specified and
2189 To ensure that the return value is always specified and absolute, use
2190 a value of @code{default} for @var{inherit}; this will resolve any
2191 unspecified or relative values by merging with the @code{default} face
2192 (which is always completely specified).
2197 (face-attribute 'bold :weight)
2202 @defun face-attribute-relative-p attribute value
2203 This function returns non-@code{nil} if @var{value}, when used as the
2204 value of the face attribute @var{attribute}, is relative. This means
2205 it would modify, rather than completely override, any value that comes
2206 from a subsequent face in the face list or that is inherited from
2209 @code{unspecified} is a relative value for all attributes.
2210 For @code{:height}, floating point values are also relative.
2215 (face-attribute-relative-p :height 2.0)
2220 @defun merge-face-attribute attribute value1 value2
2221 If @var{value1} is a relative value for the face attribute
2222 @var{attribute}, returns it merged with the underlying value
2223 @var{value2}; otherwise, if @var{value1} is an absolute value for the
2224 face attribute @var{attribute}, returns @var{value1} unchanged.
2227 The functions above did not exist before Emacs 21. For compatibility
2228 with older Emacs versions, you can use the following functions to set
2229 and examine the face attributes which existed in those versions.
2230 They use values of @code{t} and @code{nil} for @var{frame}
2231 just like @code{set-face-attribute} and @code{face-attribute}.
2233 @defun set-face-foreground face color &optional frame
2234 @defunx set-face-background face color &optional frame
2235 These functions set the foreground (or background, respectively) color
2236 of face @var{face} to @var{color}. The argument @var{color} should be a
2237 string, the name of a color.
2239 Certain shades of gray are implemented by stipple patterns on
2240 black-and-white screens.
2243 @defun set-face-stipple face pattern &optional frame
2244 This function sets the background stipple pattern of face @var{face}
2245 to @var{pattern}. The argument @var{pattern} should be the name of a
2246 stipple pattern defined by the X server, or actual bitmap data
2247 (@pxref{Face Attributes}), or @code{nil} meaning don't use stipple.
2249 Normally there is no need to pay attention to stipple patterns, because
2250 they are used automatically to handle certain shades of gray.
2253 @defun set-face-font face font &optional frame
2254 This function sets the font of face @var{face}. This actually sets
2255 the attributes @code{:family}, @code{:width}, @code{:height},
2256 @code{:weight}, and @code{:slant} according to the font name
2260 @defun set-face-bold-p face bold-p &optional frame
2261 This function specifies whether @var{face} should be bold. If
2262 @var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no.
2263 This actually sets the @code{:weight} attribute.
2266 @defun set-face-italic-p face italic-p &optional frame
2267 This function specifies whether @var{face} should be italic. If
2268 @var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no.
2269 This actually sets the @code{:slant} attribute.
2272 @defun set-face-underline-p face underline &optional frame
2273 This function sets the underline attribute of face @var{face}.
2274 Non-@code{nil} means do underline; @code{nil} means don't.
2275 If @var{underline} is a string, underline with that color.
2278 @defun set-face-inverse-video-p face inverse-video-p &optional frame
2279 This function sets the @code{:inverse-video} attribute of face
2283 @defun invert-face face &optional frame
2284 This function swaps the foreground and background colors of face
2288 These functions examine the attributes of a face. If you don't
2289 specify @var{frame}, they refer to the selected frame; @code{t} refers
2290 to the default data for new frames. They return the symbol
2291 @code{unspecified} if the face doesn't define any value for that
2294 @defun face-foreground face &optional frame inherit
2295 @defunx face-background face &optional frame inherit
2296 These functions return the foreground color (or background color,
2297 respectively) of face @var{face}, as a string.
2299 If @var{inherit} is @code{nil}, only a color directly defined by the face is
2300 returned. If @var{inherit} is non-@code{nil}, any faces specified by its
2301 @code{:inherit} attribute are considered as well, and if @var{inherit}
2302 is a face or a list of faces, then they are also considered, until a
2303 specified color is found. To ensure that the return value is always
2304 specified, use a value of @code{default} for @var{inherit}.
2307 @defun face-stipple face &optional frame inherit
2308 This function returns the name of the background stipple pattern of face
2309 @var{face}, or @code{nil} if it doesn't have one.
2311 If @var{inherit} is @code{nil}, only a stipple directly defined by the
2312 face is returned. If @var{inherit} is non-@code{nil}, any faces
2313 specified by its @code{:inherit} attribute are considered as well, and
2314 if @var{inherit} is a face or a list of faces, then they are also
2315 considered, until a specified stipple is found. To ensure that the
2316 return value is always specified, use a value of @code{default} for
2320 @defun face-font face &optional frame
2321 This function returns the name of the font of face @var{face}.
2324 @defun face-bold-p face &optional frame
2325 This function returns @code{t} if @var{face} is bold---that is, if it is
2326 bolder than normal. It returns @code{nil} otherwise.
2329 @defun face-italic-p face &optional frame
2330 This function returns @code{t} if @var{face} is italic or oblique,
2331 @code{nil} otherwise.
2334 @defun face-underline-p face &optional frame
2335 This function returns the @code{:underline} attribute of face @var{face}.
2338 @defun face-inverse-video-p face &optional frame
2339 This function returns the @code{:inverse-video} attribute of face @var{face}.
2342 @node Displaying Faces
2343 @subsection Displaying Faces
2345 Here are the ways to specify which faces to use for display of text:
2349 With defaults. The @code{default} face is used as the ultimate
2350 default for all text. (In Emacs 19 and 20, the @code{default}
2351 face is used only when no other face is specified.)
2354 For a mode line or header line, the face @code{mode-line} or
2355 @code{mode-line-inactive}, or @code{header-line}, is merged in just
2356 before @code{default}.
2359 With text properties. A character can have a @code{face} property; if
2360 so, the faces and face attributes specified there apply. @xref{Special
2363 If the character has a @code{mouse-face} property, that is used instead
2364 of the @code{face} property when the mouse is ``near enough'' to the
2368 With overlays. An overlay can have @code{face} and @code{mouse-face}
2369 properties too; they apply to all the text covered by the overlay.
2372 With a region that is active. In Transient Mark mode, the region is
2373 highlighted with the face @code{region} (@pxref{Standard Faces,,,
2374 emacs, The GNU Emacs Manual}).
2377 With special glyphs. Each glyph can specify a particular face
2378 number. @xref{Glyphs}.
2381 If these various sources together specify more than one face for a
2382 particular character, Emacs merges the attributes of the various faces
2383 specified. For each attribute, Emacs tries first the face of any
2384 special glyph; then the face for region highlighting, if appropriate;
2385 then the faces specified by overlays, followed by those specified by
2386 text properties, then the @code{mode-line} or
2387 @code{mode-line-inactive} or @code{header-line} face (if in a mode
2388 line or a header line), and last the @code{default} face.
2390 When multiple overlays cover one character, an overlay with higher
2391 priority overrides those with lower priority. @xref{Overlays}.
2393 @defvar face-remapping-alist
2394 This variable is used for buffer-local or global changes in the
2395 appearance of a face, for instance making the @code{default} face a
2396 variable-pitch face in a particular buffer.
2398 Its value should be an alist, whose elements have the form
2399 @code{(@var{face} @var{remapping...})}. This causes Emacs to display
2400 text using the face @var{face} using @var{remapping...} instead of
2401 @var{face}'s global definition. @var{remapping...} may be any face
2402 specification suitable for a @code{face} text property, usually a face
2403 name, but also perhaps a property list of face attribute/value pairs.
2404 @xref{Special Properties}.
2406 To affect display only in a single buffer,
2407 @code{face-remapping-alist} should be made buffer-local.
2409 Two points bear emphasizing:
2413 The new definition @var{remapping...} is the complete
2414 specification of how to display @var{face}---it entirely replaces,
2415 rather than augmenting or modifying, the normal definition of that
2419 If @var{remapping...} recursively references the same face name
2420 @var{face}, either directly remapping entry, or via the
2421 @code{:inherit} attribute of some other face in
2422 @var{remapping...}, then that reference uses normal frame-wide
2423 definition of @var{face} instead of the ``remapped'' definition.
2425 For instance, if the @code{mode-line} face is remapped using this
2426 entry in @code{face-remapping-alist}:
2428 (mode-line italic mode-line)
2431 then the new definition of the @code{mode-line} face inherits from the
2432 @code{italic} face, and the @emph{normal} (non-remapped) definition of
2433 @code{mode-line} face.
2436 A typical use of the @code{face-remapping-alist} is to change a
2437 buffer's @code{default} face; for example, the following changes a
2438 buffer's @code{default} face to use the @code{variable-pitch} face,
2439 with the height doubled:
2442 (set (make-local-variable 'face-remapping-alist)
2443 '((default variable-pitch :height 2.0)))
2449 The following functions implement a somewhat higher-level interface to
2450 @code{face-remapping-alist}, making it easier to use
2451 ``cooperatively''. They are mainly intended for buffer-local use, and
2452 so all make @code{face-remapping-alist} variable buffer-local as a
2455 These functions use entries in @code{face-remapping-alist} which have
2459 (@var{face} @var{relative_specs_1} @var{relative_specs_2} @var{...} @var{base_specs})
2462 Everything except the @var{face} is a ``face spec'', a list of face
2463 names or face attribute-value pairs. All face specs are merged
2464 together, with earlier values taking precedence.
2466 The @var{relative_specs_}n values are ``relative specs'', and are
2467 added by @code{face-remap-add-relative} (and removed by
2468 @code{face-remap-remove-relative}. These are intended for face
2469 modifications (such as increasing the size). Typical users of these
2470 relative specs would be minor modes.
2472 @var{base_specs} is the lowest-priority value, and by default is just the
2473 face name, which causes the global definition of that face to be used.
2475 A non-default value of @var{base_specs} may also be set using
2476 @code{face-remap-set-base}. Because this @emph{overwrites} the
2477 default base-spec value (which inherits the global face definition),
2478 it is up to the caller of @code{face-remap-set-base} to add such
2479 inheritance if it is desired. A typical use of
2480 @code{face-remap-set-base} would be a major mode adding a face
2481 remappings, e.g., of the default face.
2484 @defun face-remap-add-relative face &rest specs
2485 This functions adds a face remapping entry of @var{face} to @var{specs}
2486 in the current buffer.
2488 It returns a ``cookie'' which can be used to later delete the remapping with
2489 @code{face-remap-remove-relative}.
2491 @var{specs} can be any value suitable for the @code{face} text
2492 property, including a face name, a list of face names, or a
2493 face-attribute property list. The attributes given by @var{specs}
2494 will be merged with any other currently active face remappings of
2495 @var{face}, and with the global definition of @var{face} (by default;
2496 this may be changed using @code{face-remap-set-base}), with the most
2497 recently added relative remapping taking precedence.
2500 @defun face-remap-remove-relative cookie
2501 This function removes a face remapping previously added by
2502 @code{face-remap-add-relative}. @var{cookie} should be a return value
2506 @defun face-remap-set-base face &rest specs
2507 This function sets the ``base remapping'' of @var{face} in the current
2508 buffer to @var{specs}. If @var{specs} is empty, the default base
2509 remapping is restored, which inherits from the global definition of
2510 @var{face}; note that this is different from @var{specs} containing a
2511 single value @code{nil}, which has the opposite result (the global
2512 definition of @var{face} is ignored).
2515 @defun face-remap-reset-base face
2516 This function sets the ``base remapping'' of @var{face} to its default
2517 value, which inherits from @var{face}'s global definition.
2520 @node Font Selection
2521 @subsection Font Selection
2523 @dfn{Selecting a font} means mapping the specified face attributes for
2524 a character to a font that is available on a particular display. The
2525 face attributes, as determined by face merging, specify most of the
2526 font choice, but not all. Part of the choice depends on what character
2529 If the face specifies a fontset name, that fontset determines a
2530 pattern for fonts of the given charset. If the face specifies a font
2531 family, a font pattern is constructed.
2533 Emacs tries to find an available font for the given face attributes
2534 and character's registry and encoding. If there is a font that matches
2535 exactly, it is used, of course. The hard case is when no available font
2536 exactly fits the specification. Then Emacs looks for one that is
2537 ``close''---one attribute at a time. You can specify the order to
2538 consider the attributes. In the case where a specified font family is
2539 not available, you can specify a set of mappings for alternatives to
2542 @defvar face-font-selection-order
2543 This variable specifies the order of importance of the face attributes
2544 @code{:width}, @code{:height}, @code{:weight}, and @code{:slant}. The
2545 value should be a list containing those four symbols, in order of
2546 decreasing importance.
2548 Font selection first finds the best available matches for the first
2549 attribute listed; then, among the fonts which are best in that way, it
2550 searches for the best matches in the second attribute, and so on.
2552 The attributes @code{:weight} and @code{:width} have symbolic values in
2553 a range centered around @code{normal}. Matches that are more extreme
2554 (farther from @code{normal}) are somewhat preferred to matches that are
2555 less extreme (closer to @code{normal}); this is designed to ensure that
2556 non-normal faces contrast with normal ones, whenever possible.
2558 The default is @code{(:width :height :weight :slant)}, which means first
2559 find the fonts closest to the specified @code{:width}, then---among the
2560 fonts with that width---find a best match for the specified font height,
2563 One example of a case where this variable makes a difference is when the
2564 default font has no italic equivalent. With the default ordering, the
2565 @code{italic} face will use a non-italic font that is similar to the
2566 default one. But if you put @code{:slant} before @code{:height}, the
2567 @code{italic} face will use an italic font, even if its height is not
2571 @defvar face-font-family-alternatives
2572 This variable lets you specify alternative font families to try, if a
2573 given family is specified and doesn't exist. Each element should have
2577 (@var{family} @var{alternate-families}@dots{})
2580 If @var{family} is specified but not available, Emacs will try the other
2581 families given in @var{alternate-families}, one by one, until it finds a
2582 family that does exist.
2585 @defvar face-font-registry-alternatives
2586 This variable lets you specify alternative font registries to try, if a
2587 given registry is specified and doesn't exist. Each element should have
2591 (@var{registry} @var{alternate-registries}@dots{})
2594 If @var{registry} is specified but not available, Emacs will try the
2595 other registries given in @var{alternate-registries}, one by one,
2596 until it finds a registry that does exist.
2599 Emacs can make use of scalable fonts, but by default it does not use
2600 them, since the use of too many or too big scalable fonts can crash
2603 @defvar scalable-fonts-allowed
2604 This variable controls which scalable fonts to use. A value of
2605 @code{nil}, the default, means do not use scalable fonts. @code{t}
2606 means to use any scalable font that seems appropriate for the text.
2608 Otherwise, the value must be a list of regular expressions. Then a
2609 scalable font is enabled for use if its name matches any regular
2610 expression in the list. For example,
2613 (setq scalable-fonts-allowed '("muleindian-2$"))
2617 allows the use of scalable fonts with registry @code{muleindian-2}.
2620 @defvar face-font-rescale-alist
2621 This variable specifies scaling for certain faces. Its value should
2622 be a list of elements of the form
2625 (@var{fontname-regexp} . @var{scale-factor})
2628 If @var{fontname-regexp} matches the font name that is about to be
2629 used, this says to choose a larger similar font according to the
2630 factor @var{scale-factor}. You would use this feature to normalize
2631 the font size if certain fonts are bigger or smaller than their
2632 nominal heights and widths would suggest.
2635 @node Face Functions
2636 @subsection Functions for Working with Faces
2638 Here are additional functions for creating and working with faces.
2640 @defun make-face name
2641 This function defines a new face named @var{name}, initially with all
2642 attributes @code{nil}. It does nothing if there is already a face named
2647 This function returns a list of all defined face names.
2650 @defun copy-face old-face new-name &optional frame new-frame
2651 This function defines a face named @var{new-name} as a copy of the existing
2652 face named @var{old-face}. It creates the face @var{new-name} if that
2653 doesn't already exist.
2655 If the optional argument @var{frame} is given, this function applies
2656 only to that frame. Otherwise it applies to each frame individually,
2657 copying attributes from @var{old-face} in each frame to @var{new-face}
2660 If the optional argument @var{new-frame} is given, then @code{copy-face}
2661 copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
2666 This function returns the face number of face @var{face}.
2669 @defun face-documentation face
2670 This function returns the documentation string of face @var{face}, or
2671 @code{nil} if none was specified for it.
2674 @defun face-equal face1 face2 &optional frame
2675 This returns @code{t} if the faces @var{face1} and @var{face2} have the
2676 same attributes for display.
2679 @defun face-differs-from-default-p face &optional frame
2680 This returns non-@code{nil} if the face @var{face} displays
2681 differently from the default face.
2685 A @dfn{face alias} provides an equivalent name for a face. You can
2686 define a face alias by giving the alias symbol the @code{face-alias}
2687 property, with a value of the target face name. The following example
2688 makes @code{modeline} an alias for the @code{mode-line} face.
2691 (put 'modeline 'face-alias 'mode-line)
2696 @subsection Automatic Face Assignment
2697 @cindex automatic face assignment
2698 @cindex faces, automatic choice
2700 This hook is used for automatically assigning faces to text in the
2701 buffer. It is part of the implementation of Jit-Lock mode, used by
2704 @defvar fontification-functions
2705 This variable holds a list of functions that are called by Emacs
2706 redisplay as needed to assign faces automatically to text in the buffer.
2708 The functions are called in the order listed, with one argument, a
2709 buffer position @var{pos}. Each function should attempt to assign faces
2710 to the text in the current buffer starting at @var{pos}.
2712 Each function should record the faces they assign by setting the
2713 @code{face} property. It should also add a non-@code{nil}
2714 @code{fontified} property for all the text it has assigned faces to.
2715 That property tells redisplay that faces have been assigned to that text
2718 It is probably a good idea for each function to do nothing if the
2719 character after @var{pos} already has a non-@code{nil} @code{fontified}
2720 property, but this is not required. If one function overrides the
2721 assignments made by a previous one, the properties as they are
2722 after the last function finishes are the ones that really matter.
2724 For efficiency, we recommend writing these functions so that they
2725 usually assign faces to around 400 to 600 characters at each call.
2729 @subsection Looking Up Fonts
2731 @defun x-list-fonts pattern &optional face frame maximum
2732 This function returns a list of available font names that match
2733 @var{pattern}. If the optional arguments @var{face} and @var{frame} are
2734 specified, then the list is limited to fonts that are the same size as
2735 @var{face} currently is on @var{frame}.
2737 The argument @var{pattern} should be a string, perhaps with wildcard
2738 characters: the @samp{*} character matches any substring, and the
2739 @samp{?} character matches any single character. Pattern matching
2740 of font names ignores case.
2742 If you specify @var{face} and @var{frame}, @var{face} should be a face name
2743 (a symbol) and @var{frame} should be a frame.
2745 The optional argument @var{maximum} sets a limit on how many fonts to
2746 return. If this is non-@code{nil}, then the return value is truncated
2747 after the first @var{maximum} matching fonts. Specifying a small value
2748 for @var{maximum} can make this function much faster, in cases where
2749 many fonts match the pattern.
2752 @defun x-family-fonts &optional family frame
2753 This function returns a list describing the available fonts for family
2754 @var{family} on @var{frame}. If @var{family} is omitted or @code{nil},
2755 this list applies to all families, and therefore, it contains all
2756 available fonts. Otherwise, @var{family} must be a string; it may
2757 contain the wildcards @samp{?} and @samp{*}.
2759 The list describes the display that @var{frame} is on; if @var{frame} is
2760 omitted or @code{nil}, it applies to the selected frame's display
2761 (@pxref{Input Focus}).
2763 The list contains a vector of the following form for each font:
2766 [@var{family} @var{width} @var{point-size} @var{weight} @var{slant}
2767 @var{fixed-p} @var{full} @var{registry-and-encoding}]
2770 The first five elements correspond to face attributes; if you
2771 specify these attributes for a face, it will use this font.
2773 The last three elements give additional information about the font.
2774 @var{fixed-p} is non-@code{nil} if the font is fixed-pitch.
2775 @var{full} is the full name of the font, and
2776 @var{registry-and-encoding} is a string giving the registry and
2777 encoding of the font.
2779 The result list is sorted according to the current face font sort order.
2782 @defun x-font-family-list &optional frame
2783 This function returns a list of the font families available for
2784 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, it
2785 describes the selected frame's display (@pxref{Input Focus}).
2787 The value is a list of elements of this form:
2790 (@var{family} . @var{fixed-p})
2794 Here @var{family} is a font family, and @var{fixed-p} is
2795 non-@code{nil} if fonts of that family are fixed-pitch.
2798 @defvar font-list-limit
2799 This variable specifies maximum number of fonts to consider in font
2800 matching. The function @code{x-family-fonts} will not return more than
2801 that many fonts, and font selection will consider only that many fonts
2802 when searching a matching font for face attributes. The default is
2807 @subsection Fontsets
2809 A @dfn{fontset} is a list of fonts, each assigned to a range of
2810 character codes. An individual font cannot display the whole range of
2811 characters that Emacs supports, but a fontset can. Fontsets have names,
2812 just as fonts do, and you can use a fontset name in place of a font name
2813 when you specify the ``font'' for a frame or a face. Here is
2814 information about defining a fontset under Lisp program control.
2816 @defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
2817 This function defines a new fontset according to the specification
2818 string @var{fontset-spec}. The string should have this format:
2821 @var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}}
2825 Whitespace characters before and after the commas are ignored.
2827 The first part of the string, @var{fontpattern}, should have the form of
2828 a standard X font name, except that the last two fields should be
2829 @samp{fontset-@var{alias}}.
2831 The new fontset has two names, one long and one short. The long name is
2832 @var{fontpattern} in its entirety. The short name is
2833 @samp{fontset-@var{alias}}. You can refer to the fontset by either
2834 name. If a fontset with the same name already exists, an error is
2835 signaled, unless @var{noerror} is non-@code{nil}, in which case this
2836 function does nothing.
2838 If optional argument @var{style-variant-p} is non-@code{nil}, that says
2839 to create bold, italic and bold-italic variants of the fontset as well.
2840 These variant fontsets do not have a short name, only a long one, which
2841 is made by altering @var{fontpattern} to indicate the bold or italic
2844 The specification string also says which fonts to use in the fontset.
2845 See below for the details.
2848 The construct @samp{@var{charset}:@var{font}} specifies which font to
2849 use (in this fontset) for one particular character set. Here,
2850 @var{charset} is the name of a character set, and @var{font} is the font
2851 to use for that character set. You can use this construct any number of
2852 times in the specification string.
2854 For the remaining character sets, those that you don't specify
2855 explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
2856 @samp{fontset-@var{alias}} with a value that names one character set.
2857 For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced
2858 with @samp{ISO8859-1}.
2860 In addition, when several consecutive fields are wildcards, Emacs
2861 collapses them into a single wildcard. This is to prevent use of
2862 auto-scaled fonts. Fonts made by scaling larger fonts are not usable
2863 for editing, and scaling a smaller font is not useful because it is
2864 better to use the smaller font in its own size, which Emacs does.
2866 Thus if @var{fontpattern} is this,
2869 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
2873 the font specification for @acronym{ASCII} characters would be this:
2876 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
2880 and the font specification for Chinese GB2312 characters would be this:
2883 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
2886 You may not have any Chinese font matching the above font
2887 specification. Most X distributions include only Chinese fonts that
2888 have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
2889 such a case, @samp{Fontset-@var{n}} can be specified as below:
2892 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
2893 chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
2897 Then, the font specifications for all but Chinese GB2312 characters have
2898 @samp{fixed} in the @var{family} field, and the font specification for
2899 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
2902 @defun set-fontset-font name character fontname &optional frame
2903 This function modifies the existing fontset @var{name} to
2904 use the font name @var{fontname} for the character @var{character}.
2906 If @var{name} is @code{nil}, this function modifies the default
2907 fontset, whose short name is @samp{fontset-default}.
2909 @var{character} may be a cons; @code{(@var{from} . @var{to})}, where
2910 @var{from} and @var{to} are character codepoints. In that case, use
2911 @var{fontname} for all characters in the range @var{from} and @var{to}
2914 @var{character} may be a charset. In that case, use
2915 @var{fontname} for all character in the charsets.
2917 @var{fontname} may be a cons; @code{(@var{family} . @var{registry})},
2918 where @var{family} is a family name of a font (possibly including a
2919 foundry name at the head), @var{registry} is a registry name of a font
2920 (possibly including an encoding name at the tail).
2922 For instance, this changes the default fontset to use a font of which
2923 registry name is @samp{JISX0208.1983} for all characters belonging to
2924 the charset @code{japanese-jisx0208}.
2927 (set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
2931 @defun char-displayable-p char
2932 This function returns @code{t} if Emacs ought to be able to display
2933 @var{char}. More precisely, if the selected frame's fontset has a
2934 font to display the character set that @var{char} belongs to.
2936 Fontsets can specify a font on a per-character basis; when the fontset
2937 does that, this function's value may not be accurate.
2944 The @dfn{fringes} of a window are thin vertical strips down the
2945 sides that are used for displaying bitmaps that indicate truncation,
2946 continuation, horizontal scrolling, and the overlay arrow.
2949 * Fringe Size/Pos:: Specifying where to put the window fringes.
2950 * Fringe Indicators:: Displaying indicator icons in the window fringes.
2951 * Fringe Cursors:: Displaying cursors in the right fringe.
2952 * Fringe Bitmaps:: Specifying bitmaps for fringe indicators.
2953 * Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes.
2954 * Overlay Arrow:: Display of an arrow to indicate position.
2957 @node Fringe Size/Pos
2958 @subsection Fringe Size and Position
2960 The following buffer-local variables control the position and width
2961 of the window fringes.
2963 @defvar fringes-outside-margins
2964 The fringes normally appear between the display margins and the window
2965 text. If the value is non-@code{nil}, they appear outside the display
2966 margins. @xref{Display Margins}.
2969 @defvar left-fringe-width
2970 This variable, if non-@code{nil}, specifies the width of the left
2971 fringe in pixels. A value of @code{nil} means to use the left fringe
2972 width from the window's frame.
2975 @defvar right-fringe-width
2976 This variable, if non-@code{nil}, specifies the width of the right
2977 fringe in pixels. A value of @code{nil} means to use the right fringe
2978 width from the window's frame.
2981 The values of these variables take effect when you display the
2982 buffer in a window. If you change them while the buffer is visible,
2983 you can call @code{set-window-buffer} to display it once again in the
2984 same window, to make the changes take effect.
2986 @defun set-window-fringes window left &optional right outside-margins
2987 This function sets the fringe widths of window @var{window}.
2988 If @var{window} is @code{nil}, the selected window is used.
2990 The argument @var{left} specifies the width in pixels of the left
2991 fringe, and likewise @var{right} for the right fringe. A value of
2992 @code{nil} for either one stands for the default width. If
2993 @var{outside-margins} is non-@code{nil}, that specifies that fringes
2994 should appear outside of the display margins.
2997 @defun window-fringes &optional window
2998 This function returns information about the fringes of a window
2999 @var{window}. If @var{window} is omitted or @code{nil}, the selected
3000 window is used. The value has the form @code{(@var{left-width}
3001 @var{right-width} @var{outside-margins})}.
3005 @node Fringe Indicators
3006 @subsection Fringe Indicators
3007 @cindex fringe indicators
3008 @cindex indicators, fringe
3010 The @dfn{fringe indicators} are tiny icons Emacs displays in the
3011 window fringe (on a graphic display) to indicate truncated or
3012 continued lines, buffer boundaries, overlay arrow, etc.
3014 @defopt indicate-empty-lines
3015 @cindex fringes, and empty line indication
3016 When this is non-@code{nil}, Emacs displays a special glyph in the
3017 fringe of each empty line at the end of the buffer, on graphical
3018 displays. @xref{Fringes}. This variable is automatically
3019 buffer-local in every buffer.
3022 @defvar indicate-buffer-boundaries
3023 This buffer-local variable controls how the buffer boundaries and
3024 window scrolling are indicated in the window fringes.
3026 Emacs can indicate the buffer boundaries---that is, the first and last
3027 line in the buffer---with angle icons when they appear on the screen.
3028 In addition, Emacs can display an up-arrow in the fringe to show
3029 that there is text above the screen, and a down-arrow to show
3030 there is text below the screen.
3032 There are three kinds of basic values:
3036 Don't display any of these fringe icons.
3038 Display the angle icons and arrows in the left fringe.
3040 Display the angle icons and arrows in the right fringe.
3042 Display the angle icons in the left fringe
3043 and don't display the arrows.
3046 Otherwise the value should be an alist that specifies which fringe
3047 indicators to display and where. Each element of the alist should
3048 have the form @code{(@var{indicator} . @var{position})}. Here,
3049 @var{indicator} is one of @code{top}, @code{bottom}, @code{up},
3050 @code{down}, and @code{t} (which covers all the icons not yet
3051 specified), while @var{position} is one of @code{left}, @code{right}
3054 For example, @code{((top . left) (t . right))} places the top angle
3055 bitmap in left fringe, and the bottom angle bitmap as well as both
3056 arrow bitmaps in right fringe. To show the angle bitmaps in the left
3057 fringe, and no arrow bitmaps, use @code{((top . left) (bottom . left))}.
3060 @defvar default-indicate-buffer-boundaries
3061 The value of this variable is the default value for
3062 @code{indicate-buffer-boundaries} in buffers that do not override it.
3065 @defvar fringe-indicator-alist
3066 This buffer-local variable specifies the mapping from logical fringe
3067 indicators to the actual bitmaps displayed in the window fringes.
3069 These symbols identify the logical fringe indicators:
3072 @item Truncation and continuation line indicators:
3073 @code{truncation}, @code{continuation}.
3075 @item Buffer position indicators:
3076 @code{up}, @code{down},
3077 @code{top}, @code{bottom},
3080 @item Empty line indicator:
3083 @item Overlay arrow indicator:
3084 @code{overlay-arrow}.
3086 @item Unknown bitmap indicator:
3090 The value is an alist where each element @code{(@var{indicator} . @var{bitmaps})}
3091 specifies the fringe bitmaps used to display a specific logical
3094 Here, @var{indicator} specifies the logical indicator type, and
3095 @var{bitmaps} is list of symbols @code{(@var{left} @var{right}
3096 [@var{left1} @var{right1}])} which specifies the actual bitmap shown
3097 in the left or right fringe for the logical indicator.
3099 The @var{left} and @var{right} symbols specify the bitmaps shown in
3100 the left and/or right fringe for the specific indicator. The
3101 @var{left1} or @var{right1} bitmaps are used only for the `bottom' and
3102 `top-bottom indicators when the last (only) line in has no final
3103 newline. Alternatively, @var{bitmaps} may be a single symbol which is
3104 used in both left and right fringes.
3106 When @code{fringe-indicator-alist} has a buffer-local value, and there
3107 is no bitmap defined for a logical indicator, or the bitmap is
3108 @code{t}, the corresponding value from the (non-local)
3109 @code{default-fringe-indicator-alist} is used.
3111 To completely hide a specific indicator, set the bitmap to @code{nil}.
3114 @defvar default-fringe-indicator-alist
3115 The value of this variable is the default value for
3116 @code{fringe-indicator-alist} in buffers that do not override it.
3119 Standard fringe bitmaps for indicators:
3121 left-arrow right-arrow up-arrow down-arrow
3122 left-curly-arrow right-curly-arrow
3123 left-triangle right-triangle
3124 top-left-angle top-right-angle
3125 bottom-left-angle bottom-right-angle
3126 left-bracket right-bracket
3127 filled-rectangle hollow-rectangle
3128 filled-square hollow-square
3129 vertical-bar horizontal-bar
3130 empty-line question-mark
3133 @node Fringe Cursors
3134 @subsection Fringe Cursors
3135 @cindex fringe cursors
3136 @cindex cursor, fringe
3138 When a line is exactly as wide as the window, Emacs displays the
3139 cursor in the right fringe instead of using two lines. Different
3140 bitmaps are used to represent the cursor in the fringe depending on
3141 the current buffer's cursor type.
3144 @item Logical cursor types:
3145 @code{box} , @code{hollow}, @code{bar},
3146 @code{hbar}, @code{hollow-small}.
3149 The @code{hollow-small} type is used instead of @code{hollow} when the
3150 normal @code{hollow-rectangle} bitmap is too tall to fit on a specific
3153 @defvar overflow-newline-into-fringe
3154 If this is non-@code{nil}, lines exactly as wide as the window (not
3155 counting the final newline character) are not continued. Instead,
3156 when point is at the end of the line, the cursor appears in the right
3160 @defvar fringe-cursor-alist
3161 This variable specifies the mapping from logical cursor type to the
3162 actual fringe bitmaps displayed in the right fringe. The value is an
3163 alist where each element @code{(@var{cursor} . @var{bitmap})} specifies
3164 the fringe bitmaps used to display a specific logical cursor type in
3165 the fringe. Here, @var{cursor} specifies the logical cursor type and
3166 @var{bitmap} is a symbol specifying the fringe bitmap to be displayed
3167 for that logical cursor type.
3169 When @code{fringe-cursor-alist} has a buffer-local value, and there is
3170 no bitmap defined for a cursor type, the corresponding value from the
3171 (non-local) @code{default-fringes-indicator-alist} is used.
3174 @defvar default-fringes-cursor-alist
3175 The value of this variable is the default value for
3176 @code{fringe-cursor-alist} in buffers that do not override it.
3179 Standard bitmaps for displaying the cursor in right fringe:
3181 filled-rectangle hollow-rectangle filled-square hollow-square
3182 vertical-bar horizontal-bar
3186 @node Fringe Bitmaps
3187 @subsection Fringe Bitmaps
3188 @cindex fringe bitmaps
3189 @cindex bitmaps, fringe
3191 The @dfn{fringe bitmaps} are the actual bitmaps which represent the
3192 logical fringe indicators for truncated or continued lines, buffer
3193 boundaries, overlay arrow, etc. Fringe bitmap symbols have their own
3194 name space. The fringe bitmaps are shared by all frames and windows.
3195 You can redefine the built-in fringe bitmaps, and you can define new
3198 The way to display a bitmap in the left or right fringes for a given
3199 line in a window is by specifying the @code{display} property for one
3200 of the characters that appears in it. Use a display specification of
3201 the form @code{(left-fringe @var{bitmap} [@var{face}])} or
3202 @code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display
3203 Property}). Here, @var{bitmap} is a symbol identifying the bitmap you
3204 want, and @var{face} (which is optional) is the name of the face whose
3205 colors should be used for displaying the bitmap, instead of the
3206 default @code{fringe} face. @var{face} is automatically merged with
3207 the @code{fringe} face, so normally @var{face} need only specify the
3208 foreground color for the bitmap.
3210 @defun fringe-bitmaps-at-pos &optional pos window
3211 This function returns the fringe bitmaps of the display line
3212 containing position @var{pos} in window @var{window}. The return
3213 value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left}
3214 is the symbol for the fringe bitmap in the left fringe (or @code{nil}
3215 if no bitmap), @var{right} is similar for the right fringe, and @var{ov}
3216 is non-@code{nil} if there is an overlay arrow in the left fringe.
3218 The value is @code{nil} if @var{pos} is not visible in @var{window}.
3219 If @var{window} is @code{nil}, that stands for the selected window.
3220 If @var{pos} is @code{nil}, that stands for the value of point in
3224 @node Customizing Bitmaps
3225 @subsection Customizing Fringe Bitmaps
3227 @defun define-fringe-bitmap bitmap bits &optional height width align
3228 This function defines the symbol @var{bitmap} as a new fringe bitmap,
3229 or replaces an existing bitmap with that name.
3231 The argument @var{bits} specifies the image to use. It should be
3232 either a string or a vector of integers, where each element (an
3233 integer) corresponds to one row of the bitmap. Each bit of an integer
3234 corresponds to one pixel of the bitmap, where the low bit corresponds
3235 to the rightmost pixel of the bitmap.
3237 The height is normally the length of @var{bits}. However, you
3238 can specify a different height with non-@code{nil} @var{height}. The width
3239 is normally 8, but you can specify a different width with non-@code{nil}
3240 @var{width}. The width must be an integer between 1 and 16.
3242 The argument @var{align} specifies the positioning of the bitmap
3243 relative to the range of rows where it is used; the default is to
3244 center the bitmap. The allowed values are @code{top}, @code{center},
3247 The @var{align} argument may also be a list @code{(@var{align}
3248 @var{periodic})} where @var{align} is interpreted as described above.
3249 If @var{periodic} is non-@code{nil}, it specifies that the rows in
3250 @code{bits} should be repeated enough times to reach the specified
3254 @defun destroy-fringe-bitmap bitmap
3255 This function destroy the fringe bitmap identified by @var{bitmap}.
3256 If @var{bitmap} identifies a standard fringe bitmap, it actually
3257 restores the standard definition of that bitmap, instead of
3258 eliminating it entirely.
3261 @defun set-fringe-bitmap-face bitmap &optional face
3262 This sets the face for the fringe bitmap @var{bitmap} to @var{face}.
3263 If @var{face} is @code{nil}, it selects the @code{fringe} face. The
3264 bitmap's face controls the color to draw it in.
3266 @var{face} is merged with the @code{fringe} face, so normally
3267 @var{face} should specify only the foreground color.
3271 @subsection The Overlay Arrow
3272 @c @cindex overlay arrow Duplicates variable names
3274 The @dfn{overlay arrow} is useful for directing the user's attention
3275 to a particular line in a buffer. For example, in the modes used for
3276 interface to debuggers, the overlay arrow indicates the line of code
3277 about to be executed. This feature has nothing to do with
3278 @dfn{overlays} (@pxref{Overlays}).
3280 @defvar overlay-arrow-string
3281 This variable holds the string to display to call attention to a
3282 particular line, or @code{nil} if the arrow feature is not in use.
3283 On a graphical display the contents of the string are ignored; instead a
3284 glyph is displayed in the fringe area to the left of the display area.
3287 @defvar overlay-arrow-position
3288 This variable holds a marker that indicates where to display the overlay
3289 arrow. It should point at the beginning of a line. On a non-graphical
3290 display the arrow text
3291 appears at the beginning of that line, overlaying any text that would
3292 otherwise appear. Since the arrow is usually short, and the line
3293 usually begins with indentation, normally nothing significant is
3296 The overlay-arrow string is displayed in any given buffer if the value
3297 of @code{overlay-arrow-position} in that buffer points into that
3298 buffer. Thus, it is possible to display multiple overlay arrow strings
3299 by creating buffer-local bindings of @code{overlay-arrow-position}.
3300 However, it is usually cleaner to use
3301 @code{overlay-arrow-variable-list} to achieve this result.
3302 @c !!! overlay-arrow-position: but the overlay string may remain in the display
3303 @c of some other buffer until an update is required. This should be fixed
3307 You can do a similar job by creating an overlay with a
3308 @code{before-string} property. @xref{Overlay Properties}.
3310 You can define multiple overlay arrows via the variable
3311 @code{overlay-arrow-variable-list}.
3313 @defvar overlay-arrow-variable-list
3314 This variable's value is a list of variables, each of which specifies
3315 the position of an overlay arrow. The variable
3316 @code{overlay-arrow-position} has its normal meaning because it is on
3320 Each variable on this list can have properties
3321 @code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that
3322 specify an overlay arrow string (for text-only terminals) or fringe
3323 bitmap (for graphical terminals) to display at the corresponding
3324 overlay arrow position. If either property is not set, the default
3325 @code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator
3329 @section Scroll Bars
3332 Normally the frame parameter @code{vertical-scroll-bars} controls
3333 whether the windows in the frame have vertical scroll bars, and
3334 whether they are on the left or right. The frame parameter
3335 @code{scroll-bar-width} specifies how wide they are (@code{nil}
3336 meaning the default). @xref{Layout Parameters}.
3338 @defun frame-current-scroll-bars &optional frame
3339 This function reports the scroll bar type settings for frame
3340 @var{frame}. The value is a cons cell
3341 @code{(@var{vertical-type} .@: @var{horizontal-type})}, where
3342 @var{vertical-type} is either @code{left}, @code{right}, or @code{nil}
3343 (which means no scroll bar.) @var{horizontal-type} is meant to
3344 specify the horizontal scroll bar type, but since they are not
3345 implemented, it is always @code{nil}.
3348 @vindex vertical-scroll-bar
3349 You can enable or disable scroll bars for a particular buffer,
3350 by setting the variable @code{vertical-scroll-bar}. This variable
3351 automatically becomes buffer-local when set. The possible values are
3352 @code{left}, @code{right}, @code{t}, which means to use the
3353 frame's default, and @code{nil} for no scroll bar.
3355 You can also control this for individual windows. Call the function
3356 @code{set-window-scroll-bars} to specify what to do for a specific window:
3358 @defun set-window-scroll-bars window width &optional vertical-type horizontal-type
3359 This function sets the width and type of scroll bars for window
3362 @var{width} specifies the scroll bar width in pixels (@code{nil} means
3363 use the width specified for the frame). @var{vertical-type} specifies
3364 whether to have a vertical scroll bar and, if so, where. The possible
3365 values are @code{left}, @code{right} and @code{nil}, just like the
3366 values of the @code{vertical-scroll-bars} frame parameter.
3368 The argument @var{horizontal-type} is meant to specify whether and
3369 where to have horizontal scroll bars, but since they are not
3370 implemented, it has no effect. If @var{window} is @code{nil}, the
3371 selected window is used.
3374 @defun window-scroll-bars &optional window
3375 Report the width and type of scroll bars specified for @var{window}.
3376 If @var{window} is omitted or @code{nil}, the selected window is used.
3377 The value is a list of the form @code{(@var{width}
3378 @var{cols} @var{vertical-type} @var{horizontal-type})}. The value
3379 @var{width} is the value that was specified for the width (which may
3380 be @code{nil}); @var{cols} is the number of columns that the scroll
3381 bar actually occupies.
3383 @var{horizontal-type} is not actually meaningful.
3386 If you don't specify these values for a window with
3387 @code{set-window-scroll-bars}, the buffer-local variables
3388 @code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being
3389 displayed control the window's vertical scroll bars. The function
3390 @code{set-window-buffer} examines these variables. If you change them
3391 in a buffer that is already visible in a window, you can make the
3392 window take note of the new values by calling @code{set-window-buffer}
3393 specifying the same buffer that is already displayed.
3395 @defvar scroll-bar-mode
3396 This variable, always local in all buffers, controls whether and where
3397 to put scroll bars in windows displaying the buffer. The possible values
3398 are @code{nil} for no scroll bar, @code{left} to put a scroll bar on
3399 the left, and @code{right} to put a scroll bar on the right.
3402 @defun window-current-scroll-bars &optional window
3403 This function reports the scroll bar type for window @var{window}.
3404 If @var{window} is omitted or @code{nil}, the selected window is used.
3405 The value is a cons cell
3406 @code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike
3407 @code{window-scroll-bars}, this reports the scroll bar type actually
3408 used, once frame defaults and @code{scroll-bar-mode} are taken into
3412 @defvar scroll-bar-width
3413 This variable, always local in all buffers, specifies the width of the
3414 buffer's scroll bars, measured in pixels. A value of @code{nil} means
3415 to use the value specified by the frame.
3418 @node Display Property
3419 @section The @code{display} Property
3420 @cindex display specification
3421 @kindex display @r{(text property)}
3423 The @code{display} text property (or overlay property) is used to
3424 insert images into text, and also control other aspects of how text
3425 displays. The value of the @code{display} property should be a
3426 display specification, or a list or vector containing several display
3427 specifications. Display specifications in the same @code{display}
3428 property value generally apply in parallel to the text they cover.
3430 If several sources (overlays and/or a text property) specify values
3431 for the @code{display} property, only one of the values takes effect,
3432 following the rules of @code{get-char-property}. @xref{Examining
3435 The rest of this section describes several kinds of
3436 display specifications and what they mean.
3439 * Replacing Specs:: Display specs that replace the text.
3440 * Specified Space:: Displaying one space with a specified width.
3441 * Pixel Specification:: Specifying space width or height in pixels.
3442 * Other Display Specs:: Displaying an image; magnifying text; moving it
3443 up or down on the page; adjusting the width
3444 of spaces within text.
3445 * Display Margins:: Displaying text or images to the side of the main text.
3448 @node Replacing Specs
3449 @subsection Display Specs That Replace The Text
3451 Some kinds of @code{display} specifications specify something to
3452 display instead of the text that has the property. These are called
3453 @dfn{replacing} display specifications. Emacs does not allow the user
3454 to interactively move point into the middle of buffer text that is
3455 replaced in this way.
3457 If a list of display specifications includes more than one replacing
3458 display specification, the first overrides the rest. Replacing
3459 display specifications make most other display specifications
3460 irrelevant, since those don't apply to the replacement.
3462 For replacing display specifications, ``the text that has the
3463 property'' means all the consecutive characters that have the same
3464 Lisp object as their @code{display} property; these characters are
3465 replaced as a single unit. By contrast, characters that have similar
3466 but distinct Lisp objects as their @code{display} properties are
3467 handled separately. Here's a function that illustrates this point:
3471 (goto-char (point-min))
3473 (let ((string (concat "A")))
3474 (put-text-property (point) (1+ (point)) 'display string)
3476 (put-text-property (point) (1+ (point)) 'display string)
3481 It gives each of the first ten characters in the buffer string
3482 @code{"A"} as the @code{display} property, but they don't all get the
3483 same string. The first two characters get the same string, so they
3484 together are replaced with one @samp{A}. The next two characters get
3485 a second string, so they together are replaced with one @samp{A}.
3486 Likewise for each following pair of characters. Thus, the ten
3487 characters appear as five A's. This function would have the same
3492 (goto-char (point-min))
3494 (let ((string (concat "A")))
3495 (put-text-property (point) (+ 2 (point)) 'display string)
3496 (put-text-property (point) (1+ (point)) 'display string)
3501 This illustrates that what matters is the property value for
3502 each character. If two consecutive characters have the same
3503 object as the @code{display} property value, it's irrelevant
3504 whether they got this property from a single call to
3505 @code{put-text-property} or from two different calls.
3507 @node Specified Space
3508 @subsection Specified Spaces
3509 @cindex spaces, specified height or width
3510 @cindex variable-width spaces
3512 To display a space of specified width and/or height, use a display
3513 specification of the form @code{(space . @var{props})}, where
3514 @var{props} is a property list (a list of alternating properties and
3515 values). You can put this property on one or more consecutive
3516 characters; a space of the specified height and width is displayed in
3517 place of @emph{all} of those characters. These are the properties you
3518 can use in @var{props} to specify the weight of the space:
3521 @item :width @var{width}
3522 If @var{width} is an integer or floating point number, it specifies
3523 that the space width should be @var{width} times the normal character
3524 width. @var{width} can also be a @dfn{pixel width} specification
3525 (@pxref{Pixel Specification}).
3527 @item :relative-width @var{factor}
3528 Specifies that the width of the stretch should be computed from the
3529 first character in the group of consecutive characters that have the
3530 same @code{display} property. The space width is the width of that
3531 character, multiplied by @var{factor}.
3533 @item :align-to @var{hpos}
3534 Specifies that the space should be wide enough to reach @var{hpos}.
3535 If @var{hpos} is a number, it is measured in units of the normal
3536 character width. @var{hpos} can also be a @dfn{pixel width}
3537 specification (@pxref{Pixel Specification}).
3540 You should use one and only one of the above properties. You can
3541 also specify the height of the space, with these properties:
3544 @item :height @var{height}
3545 Specifies the height of the space.
3546 If @var{height} is an integer or floating point number, it specifies
3547 that the space height should be @var{height} times the normal character
3548 height. The @var{height} may also be a @dfn{pixel height} specification
3549 (@pxref{Pixel Specification}).
3551 @item :relative-height @var{factor}
3552 Specifies the height of the space, multiplying the ordinary height
3553 of the text having this display specification by @var{factor}.
3555 @item :ascent @var{ascent}
3556 If the value of @var{ascent} is a non-negative number no greater than
3557 100, it specifies that @var{ascent} percent of the height of the space
3558 should be considered as the ascent of the space---that is, the part
3559 above the baseline. The ascent may also be specified in pixel units
3560 with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}).
3564 Don't use both @code{:height} and @code{:relative-height} together.
3566 The @code{:width} and @code{:align-to} properties are supported on
3567 non-graphic terminals, but the other space properties in this section
3570 @node Pixel Specification
3571 @subsection Pixel Specification for Spaces
3572 @cindex spaces, pixel specification
3574 The value of the @code{:width}, @code{:align-to}, @code{:height},
3575 and @code{:ascent} properties can be a special kind of expression that
3576 is evaluated during redisplay. The result of the evaluation is used
3577 as an absolute number of pixels.
3579 The following expressions are supported:
3583 @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form}
3584 @var{num} ::= @var{integer} | @var{float} | @var{symbol}
3585 @var{unit} ::= in | mm | cm | width | height
3588 @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin
3590 @var{pos} ::= left | center | right
3591 @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...)
3596 The form @var{num} specifies a fraction of the default frame font
3597 height or width. The form @code{(@var{num})} specifies an absolute
3598 number of pixels. If @var{num} is a symbol, @var{symbol}, its
3599 buffer-local variable binding is used.
3601 The @code{in}, @code{mm}, and @code{cm} units specify the number of
3602 pixels per inch, millimeter, and centimeter, respectively. The
3603 @code{width} and @code{height} units correspond to the default width
3604 and height of the current face. An image specification @code{image}
3605 corresponds to the width or height of the image.
3607 The @code{left-fringe}, @code{right-fringe}, @code{left-margin},
3608 @code{right-margin}, @code{scroll-bar}, and @code{text} elements
3609 specify to the width of the corresponding area of the window.
3611 The @code{left}, @code{center}, and @code{right} positions can be
3612 used with @code{:align-to} to specify a position relative to the left
3613 edge, center, or right edge of the text area.
3615 Any of the above window elements (except @code{text}) can also be
3616 used with @code{:align-to} to specify that the position is relative to
3617 the left edge of the given area. Once the base offset for a relative
3618 position has been set (by the first occurrence of one of these
3619 symbols), further occurrences of these symbols are interpreted as the
3620 width of the specified area. For example, to align to the center of
3621 the left-margin, use
3624 :align-to (+ left-margin (0.5 . left-margin))
3627 If no specific base offset is set for alignment, it is always relative
3628 to the left edge of the text area. For example, @samp{:align-to 0} in a
3629 header-line aligns with the first text column in the text area.
3631 A value of the form @code{(@var{num} . @var{expr})} stands for the
3632 product of the values of @var{num} and @var{expr}. For example,
3633 @code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 .
3634 @var{image})} specifies half the width (or height) of the specified
3637 The form @code{(+ @var{expr} ...)} adds up the value of the
3638 expressions. The form @code{(- @var{expr} ...)} negates or subtracts
3639 the value of the expressions.
3641 @node Other Display Specs
3642 @subsection Other Display Specifications
3644 Here are the other sorts of display specifications that you can use
3645 in the @code{display} text property.
3649 Display @var{string} instead of the text that has this property.
3651 Recursive display specifications are not supported---@var{string}'s
3652 @code{display} properties, if any, are not used.
3654 @item (image . @var{image-props})
3655 This kind of display specification is an image descriptor (@pxref{Images}).
3656 When used as a display specification, it means to display the image
3657 instead of the text that has the display specification.
3659 @item (slice @var{x} @var{y} @var{width} @var{height})
3660 This specification together with @code{image} specifies a @dfn{slice}
3661 (a partial area) of the image to display. The elements @var{y} and
3662 @var{x} specify the top left corner of the slice, within the image;
3663 @var{width} and @var{height} specify the width and height of the
3664 slice. Integer values are numbers of pixels. A floating point number
3665 in the range 0.0--1.0 stands for that fraction of the width or height
3666 of the entire image.
3668 @item ((margin nil) @var{string})
3669 A display specification of this form means to display @var{string}
3670 instead of the text that has the display specification, at the same
3671 position as that text. It is equivalent to using just @var{string},
3672 but it is done as a special case of marginal display (@pxref{Display
3675 @item (space-width @var{factor})
3676 This display specification affects all the space characters within the
3677 text that has the specification. It displays all of these spaces
3678 @var{factor} times as wide as normal. The element @var{factor} should
3679 be an integer or float. Characters other than spaces are not affected
3680 at all; in particular, this has no effect on tab characters.
3682 @item (height @var{height})
3683 This display specification makes the text taller or shorter.
3684 Here are the possibilities for @var{height}:
3687 @item @code{(+ @var{n})}
3688 This means to use a font that is @var{n} steps larger. A ``step'' is
3689 defined by the set of available fonts---specifically, those that match
3690 what was otherwise specified for this text, in all attributes except
3691 height. Each size for which a suitable font is available counts as
3692 another step. @var{n} should be an integer.
3694 @item @code{(- @var{n})}
3695 This means to use a font that is @var{n} steps smaller.
3697 @item a number, @var{factor}
3698 A number, @var{factor}, means to use a font that is @var{factor} times
3699 as tall as the default font.
3701 @item a symbol, @var{function}
3702 A symbol is a function to compute the height. It is called with the
3703 current height as argument, and should return the new height to use.
3705 @item anything else, @var{form}
3706 If the @var{height} value doesn't fit the previous possibilities, it is
3707 a form. Emacs evaluates it to get the new height, with the symbol
3708 @code{height} bound to the current specified font height.
3711 @item (raise @var{factor})
3712 This kind of display specification raises or lowers the text
3713 it applies to, relative to the baseline of the line.
3715 @var{factor} must be a number, which is interpreted as a multiple of the
3716 height of the affected text. If it is positive, that means to display
3717 the characters raised. If it is negative, that means to display them
3720 If the text also has a @code{height} display specification, that does
3721 not affect the amount of raising or lowering, which is based on the
3722 faces used for the text.
3725 @c We put all the `@code{(when ...)}' on one line to encourage
3726 @c makeinfo's end-of-sentence heuristics to DTRT. Previously, the dot
3727 @c was at eol; the info file ended up w/ two spaces rendered after it.
3728 You can make any display specification conditional. To do that,
3729 package it in another list of the form
3730 @code{(when @var{condition} . @var{spec})}.
3731 Then the specification @var{spec} applies only when
3732 @var{condition} evaluates to a non-@code{nil} value. During the
3733 evaluation, @code{object} is bound to the string or buffer having the
3734 conditional @code{display} property. @code{position} and
3735 @code{buffer-position} are bound to the position within @code{object}
3736 and the buffer position where the @code{display} property was found,
3737 respectively. Both positions can be different when @code{object} is a
3740 @node Display Margins
3741 @subsection Displaying in the Margins
3742 @cindex display margins
3743 @cindex margins, display
3745 A buffer can have blank areas called @dfn{display margins} on the
3746 left and on the right. Ordinary text never appears in these areas,
3747 but you can put things into the display margins using the
3748 @code{display} property. There is currently no way to make text or
3749 images in the margin mouse-sensitive.
3751 The way to display something in the margins is to specify it in a
3752 margin display specification in the @code{display} property of some
3753 text. This is a replacing display specification, meaning that the
3754 text you put it on does not get displayed; the margin display appears,
3755 but that text does not.
3757 A margin display specification looks like @code{((margin
3758 right-margin) @var{spec}} or @code{((margin left-margin) @var{spec})}.
3759 Here, @var{spec} is another display specification that says what to
3760 display in the margin. Typically it is a string of text to display,
3761 or an image descriptor.
3763 To display something in the margin @emph{in association with}
3764 certain buffer text, without altering or preventing the display of
3765 that text, put a @code{before-string} property on the text and put the
3766 margin display specification on the contents of the before-string.
3768 Before the display margins can display anything, you must give
3769 them a nonzero width. The usual way to do that is to set these
3772 @defvar left-margin-width
3773 This variable specifies the width of the left margin.
3774 It is buffer-local in all buffers.
3777 @defvar right-margin-width
3778 This variable specifies the width of the right margin.
3779 It is buffer-local in all buffers.
3782 Setting these variables does not immediately affect the window. These
3783 variables are checked when a new buffer is displayed in the window.
3784 Thus, you can make changes take effect by calling
3785 @code{set-window-buffer}.
3787 You can also set the margin widths immediately.
3789 @defun set-window-margins window left &optional right
3790 This function specifies the margin widths for window @var{window}.
3791 The argument @var{left} controls the left margin and
3792 @var{right} controls the right margin (default @code{0}).
3795 @defun window-margins &optional window
3796 This function returns the left and right margins of @var{window}
3797 as a cons cell of the form @code{(@var{left} . @var{right})}.
3798 If @var{window} is @code{nil}, the selected window is used.
3803 @cindex images in buffers
3805 To display an image in an Emacs buffer, you must first create an image
3806 descriptor, then use it as a display specifier in the @code{display}
3807 property of text that is displayed (@pxref{Display Property}).
3809 Emacs is usually able to display images when it is run on a
3810 graphical terminal. Images cannot be displayed in a text terminal, on
3811 certain graphical terminals that lack the support for this, or if
3812 Emacs is compiled without image support. You can use the function
3813 @code{display-images-p} to determine if images can in principle be
3814 displayed (@pxref{Display Feature Testing}).
3817 * Image Formats:: Supported image formats.
3818 * Image Descriptors:: How to specify an image for use in @code{:display}.
3819 * XBM Images:: Special features for XBM format.
3820 * XPM Images:: Special features for XPM format.
3821 * GIF Images:: Special features for GIF format.
3822 * TIFF Images:: Special features for TIFF format.
3823 * PostScript Images:: Special features for PostScript format.
3824 * Other Image Types:: Various other formats are supported.
3825 * Defining Images:: Convenient ways to define an image for later use.
3826 * Showing Images:: Convenient ways to display an image once it is defined.
3827 * Image Cache:: Internal mechanisms of image display.
3831 @subsection Image Formats
3832 @cindex image formats
3835 Emacs can display a number of different image formats; some of them
3836 are supported only if particular support libraries are installed on
3837 your machine. In some environments, Emacs can load image
3838 libraries on demand; if so, the variable @code{image-library-alist}
3839 can be used to modify the set of known names for these dynamic
3840 libraries (though it is not possible to add new image formats).
3842 The supported image formats include XBM, XPM (this requires the
3843 libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring
3844 @code{libungif} 4.1.0), PostScript, PBM, JPEG (requiring the
3845 @code{libjpeg} library version v6a), TIFF (requiring @code{libtiff}
3846 v3.4), PNG (requiring @code{libpng} 1.0.2), and SVG (requiring
3847 @code{librsvg} 2.0.0).
3849 You specify one of these formats with an image type symbol. The image
3850 type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
3851 @code{pbm}, @code{jpeg}, @code{tiff}, @code{png}, and @code{svg}.
3854 This variable contains a list of those image type symbols that are
3855 potentially supported in the current configuration.
3856 @emph{Potentially} here means that Emacs knows about the image types,
3857 not necessarily that they can be loaded (they could depend on
3858 unavailable dynamic libraries, for example).
3860 To know which image types are really available, use
3861 @code{image-type-available-p}.
3864 @defvar image-library-alist
3865 This in an alist of image types vs external libraries needed to
3868 Each element is a list @code{(@var{image-type} @var{library}...)},
3869 where the car is a supported image format from @code{image-types}, and
3870 the rest are strings giving alternate filenames for the corresponding
3871 external libraries to load.
3873 Emacs tries to load the libraries in the order they appear on the
3874 list; if none is loaded, the running session of Emacs won't support
3875 the image type. @code{pbm} and @code{xbm} don't need to be listed;
3876 they're always supported.
3878 This variable is ignored if the image libraries are statically linked
3882 @defun image-type-available-p type
3883 This function returns non-@code{nil} if image type @var{type} is
3884 available, i.e., if images of this type can be loaded and displayed in
3885 Emacs. @var{type} should be one of the types contained in
3888 For image types whose support libraries are statically linked, this
3889 function always returns @code{t}; for other image types, it returns
3890 @code{t} if the dynamic library could be loaded, @code{nil} otherwise.
3893 @node Image Descriptors
3894 @subsection Image Descriptors
3895 @cindex image descriptor
3897 An image description is a list of the form @code{(image . @var{props})},
3898 where @var{props} is a property list containing alternating keyword
3899 symbols (symbols whose names start with a colon) and their values.
3900 You can use any Lisp object as a property, but the only properties
3901 that have any special meaning are certain symbols, all of them keywords.
3903 Every image descriptor must contain the property @code{:type
3904 @var{type}} to specify the format of the image. The value of @var{type}
3905 should be an image type symbol; for example, @code{xpm} for an image in
3908 Here is a list of other properties that are meaningful for all image
3912 @item :file @var{file}
3913 The @code{:file} property says to load the image from file
3914 @var{file}. If @var{file} is not an absolute file name, it is expanded
3915 in @code{data-directory}.
3917 @item :data @var{data}
3918 The @code{:data} property says the actual contents of the image.
3919 Each image must use either @code{:data} or @code{:file}, but not both.
3920 For most image types, the value of the @code{:data} property should be a
3921 string containing the image data; we recommend using a unibyte string.
3923 Before using @code{:data}, look for further information in the section
3924 below describing the specific image format. For some image types,
3925 @code{:data} may not be supported; for some, it allows other data types;
3926 for some, @code{:data} alone is not enough, so you need to use other
3927 image properties along with @code{:data}.
3929 @item :margin @var{margin}
3930 The @code{:margin} property specifies how many pixels to add as an
3931 extra margin around the image. The value, @var{margin}, must be a
3932 non-negative number, or a pair @code{(@var{x} . @var{y})} of such
3933 numbers. If it is a pair, @var{x} specifies how many pixels to add
3934 horizontally, and @var{y} specifies how many pixels to add vertically.
3935 If @code{:margin} is not specified, the default is zero.
3937 @item :ascent @var{ascent}
3938 The @code{:ascent} property specifies the amount of the image's
3939 height to use for its ascent---that is, the part above the baseline.
3940 The value, @var{ascent}, must be a number in the range 0 to 100, or
3941 the symbol @code{center}.
3943 If @var{ascent} is a number, that percentage of the image's height is
3944 used for its ascent.
3946 If @var{ascent} is @code{center}, the image is vertically centered
3947 around a centerline which would be the vertical centerline of text drawn
3948 at the position of the image, in the manner specified by the text
3949 properties and overlays that apply to the image.
3951 If this property is omitted, it defaults to 50.
3953 @item :relief @var{relief}
3954 The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle
3955 around the image. The value, @var{relief}, specifies the width of the
3956 shadow lines, in pixels. If @var{relief} is negative, shadows are drawn
3957 so that the image appears as a pressed button; otherwise, it appears as
3958 an unpressed button.
3960 @item :conversion @var{algorithm}
3961 The @code{:conversion} property, if non-@code{nil}, specifies a
3962 conversion algorithm that should be applied to the image before it is
3963 displayed; the value, @var{algorithm}, specifies which algorithm.
3968 Specifies the Laplace edge detection algorithm, which blurs out small
3969 differences in color while highlighting larger differences. People
3970 sometimes consider this useful for displaying the image for a
3971 ``disabled'' button.
3973 @item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
3974 Specifies a general edge-detection algorithm. @var{matrix} must be
3975 either a nine-element list or a nine-element vector of numbers. A pixel
3976 at position @math{x/y} in the transformed image is computed from
3977 original pixels around that position. @var{matrix} specifies, for each
3978 pixel in the neighborhood of @math{x/y}, a factor with which that pixel
3979 will influence the transformed pixel; element @math{0} specifies the
3980 factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for
3981 the pixel at @math{x/y-1} etc., as shown below:
3984 $$\pmatrix{x-1/y-1 & x/y-1 & x+1/y-1 \cr
3985 x-1/y & x/y & x+1/y \cr
3986 x-1/y+1& x/y+1 & x+1/y+1 \cr}$$
3991 (x-1/y-1 x/y-1 x+1/y-1
3993 x-1/y+1 x/y+1 x+1/y+1)
3997 The resulting pixel is computed from the color intensity of the color
3998 resulting from summing up the RGB values of surrounding pixels,
3999 multiplied by the specified factors, and dividing that sum by the sum
4000 of the factors' absolute values.
4002 Laplace edge-detection currently uses a matrix of
4005 $$\pmatrix{1 & 0 & 0 \cr
4018 Emboss edge-detection uses a matrix of
4021 $$\pmatrix{ 2 & -1 & 0 \cr
4035 Specifies transforming the image so that it looks ``disabled.''
4038 @item :mask @var{mask}
4039 If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build
4040 a clipping mask for the image, so that the background of a frame is
4041 visible behind the image. If @var{bg} is not specified, or if @var{bg}
4042 is @code{t}, determine the background color of the image by looking at
4043 the four corners of the image, assuming the most frequently occurring
4044 color from the corners is the background color of the image. Otherwise,
4045 @var{bg} must be a list @code{(@var{red} @var{green} @var{blue})}
4046 specifying the color to assume for the background of the image.
4048 If @var{mask} is @code{nil}, remove a mask from the image, if it has
4049 one. Images in some formats include a mask which can be removed by
4050 specifying @code{:mask nil}.
4052 @item :pointer @var{shape}
4053 This specifies the pointer shape when the mouse pointer is over this
4054 image. @xref{Pointer Shape}, for available pointer shapes.
4056 @item :map @var{map}
4057 This associates an image map of @dfn{hot spots} with this image.
4059 An image map is an alist where each element has the format
4060 @code{(@var{area} @var{id} @var{plist})}. An @var{area} is specified
4061 as either a rectangle, a circle, or a polygon.
4063 A rectangle is a cons
4064 @code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))}
4065 which specifies the pixel coordinates of the upper left and bottom right
4066 corners of the rectangle area.
4069 @code{(circle . ((@var{x0} . @var{y0}) . @var{r}))}
4070 which specifies the center and the radius of the circle; @var{r} may
4071 be a float or integer.
4074 @code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])}
4075 where each pair in the vector describes one corner in the polygon.
4077 When the mouse pointer lies on a hot-spot area of an image, the
4078 @var{plist} of that hot-spot is consulted; if it contains a @code{help-echo}
4079 property, that defines a tool-tip for the hot-spot, and if it contains
4080 a @code{pointer} property, that defines the shape of the mouse cursor when
4081 it is on the hot-spot.
4082 @xref{Pointer Shape}, for available pointer shapes.
4084 When you click the mouse when the mouse pointer is over a hot-spot, an
4085 event is composed by combining the @var{id} of the hot-spot with the
4086 mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's
4087 @var{id} is @code{area4}.
4090 @defun image-mask-p spec &optional frame
4091 This function returns @code{t} if image @var{spec} has a mask bitmap.
4092 @var{frame} is the frame on which the image will be displayed.
4093 @var{frame} @code{nil} or omitted means to use the selected frame
4094 (@pxref{Input Focus}).
4098 @subsection XBM Images
4101 To use XBM format, specify @code{xbm} as the image type. This image
4102 format doesn't require an external library, so images of this type are
4105 Additional image properties supported for the @code{xbm} image type are:
4108 @item :foreground @var{foreground}
4109 The value, @var{foreground}, should be a string specifying the image
4110 foreground color, or @code{nil} for the default color. This color is
4111 used for each pixel in the XBM that is 1. The default is the frame's
4114 @item :background @var{background}
4115 The value, @var{background}, should be a string specifying the image
4116 background color, or @code{nil} for the default color. This color is
4117 used for each pixel in the XBM that is 0. The default is the frame's
4121 If you specify an XBM image using data within Emacs instead of an
4122 external file, use the following three properties:
4125 @item :data @var{data}
4126 The value, @var{data}, specifies the contents of the image.
4127 There are three formats you can use for @var{data}:
4131 A vector of strings or bool-vectors, each specifying one line of the
4132 image. Do specify @code{:height} and @code{:width}.
4135 A string containing the same byte sequence as an XBM file would contain.
4136 You must not specify @code{:height} and @code{:width} in this case,
4137 because omitting them is what indicates the data has the format of an
4138 XBM file. The file contents specify the height and width of the image.
4141 A string or a bool-vector containing the bits of the image (plus perhaps
4142 some extra bits at the end that will not be used). It should contain at
4143 least @var{width} * @code{height} bits. In this case, you must specify
4144 @code{:height} and @code{:width}, both to indicate that the string
4145 contains just the bits rather than a whole XBM file, and to specify the
4149 @item :width @var{width}
4150 The value, @var{width}, specifies the width of the image, in pixels.
4152 @item :height @var{height}
4153 The value, @var{height}, specifies the height of the image, in pixels.
4157 @subsection XPM Images
4160 To use XPM format, specify @code{xpm} as the image type. The
4161 additional image property @code{:color-symbols} is also meaningful with
4162 the @code{xpm} image type:
4165 @item :color-symbols @var{symbols}
4166 The value, @var{symbols}, should be an alist whose elements have the
4167 form @code{(@var{name} . @var{color})}. In each element, @var{name} is
4168 the name of a color as it appears in the image file, and @var{color}
4169 specifies the actual color to use for displaying that name.
4173 @subsection GIF Images
4176 For GIF images, specify image type @code{gif}.
4179 @item :index @var{index}
4180 You can use @code{:index} to specify one image from a GIF file that
4181 contains more than one image. This property specifies use of image
4182 number @var{index} from the file. If the GIF file doesn't contain an
4183 image with index @var{index}, the image displays as a hollow box.
4187 This could be used to implement limited support for animated GIFs.
4188 For example, the following function displays a multi-image GIF file
4189 at point-min in the current buffer, switching between sub-images
4192 (defun show-anim (file max)
4193 "Display multi-image GIF file FILE which contains MAX subimages."
4194 (display-anim (current-buffer) file 0 max t))
4196 (defun display-anim (buffer file idx max first-time)
4199 (let ((img (create-image file nil :image idx)))
4202 (goto-char (point-min))
4203 (unless first-time (delete-char 1))
4205 (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
4209 @subsection TIFF Images
4212 For TIFF images, specify image type @code{tiff}.
4215 @item :index @var{index}
4216 You can use @code{:index} to specify one image from a TIFF file that
4217 contains more than one image. This property specifies use of image
4218 number @var{index} from the file. If the TIFF file doesn't contain an
4219 image with index @var{index}, the image displays as a hollow box.
4222 @node PostScript Images
4223 @subsection PostScript Images
4224 @cindex postscript images
4226 To use PostScript for an image, specify image type @code{postscript}.
4227 This works only if you have Ghostscript installed. You must always use
4228 these three properties:
4231 @item :pt-width @var{width}
4232 The value, @var{width}, specifies the width of the image measured in
4233 points (1/72 inch). @var{width} must be an integer.
4235 @item :pt-height @var{height}
4236 The value, @var{height}, specifies the height of the image in points
4237 (1/72 inch). @var{height} must be an integer.
4239 @item :bounding-box @var{box}
4240 The value, @var{box}, must be a list or vector of four integers, which
4241 specifying the bounding box of the PostScript image, analogous to the
4242 @samp{BoundingBox} comment found in PostScript files.
4245 %%BoundingBox: 22 171 567 738
4249 Displaying PostScript images from Lisp data is not currently
4250 implemented, but it may be implemented by the time you read this.
4251 See the @file{etc/NEWS} file to make sure.
4253 @node Other Image Types
4254 @subsection Other Image Types
4257 For PBM images, specify image type @code{pbm}. Color, gray-scale and
4258 monochromatic images are supported. For mono PBM images, two additional
4259 image properties are supported.
4262 @item :foreground @var{foreground}
4263 The value, @var{foreground}, should be a string specifying the image
4264 foreground color, or @code{nil} for the default color. This color is
4265 used for each pixel in the PBM that is 1. The default is the frame's
4268 @item :background @var{background}
4269 The value, @var{background}, should be a string specifying the image
4270 background color, or @code{nil} for the default color. This color is
4271 used for each pixel in the PBM that is 0. The default is the frame's
4275 For JPEG images, specify image type @code{jpeg}.
4277 For TIFF images, specify image type @code{tiff}.
4279 For PNG images, specify image type @code{png}.
4281 For SVG images, specify image type @code{svg}.
4283 @node Defining Images
4284 @subsection Defining Images
4286 The functions @code{create-image}, @code{defimage} and
4287 @code{find-image} provide convenient ways to create image descriptors.
4289 @defun create-image file-or-data &optional type data-p &rest props
4290 This function creates and returns an image descriptor which uses the
4291 data in @var{file-or-data}. @var{file-or-data} can be a file name or
4292 a string containing the image data; @var{data-p} should be @code{nil}
4293 for the former case, non-@code{nil} for the latter case.
4295 The optional argument @var{type} is a symbol specifying the image type.
4296 If @var{type} is omitted or @code{nil}, @code{create-image} tries to
4297 determine the image type from the file's first few bytes, or else
4298 from the file's name.
4300 The remaining arguments, @var{props}, specify additional image
4301 properties---for example,
4304 (create-image "foo.xpm" 'xpm nil :heuristic-mask t)
4307 The function returns @code{nil} if images of this type are not
4308 supported. Otherwise it returns an image descriptor.
4311 @defmac defimage symbol specs &optional doc
4312 This macro defines @var{symbol} as an image name. The arguments
4313 @var{specs} is a list which specifies how to display the image.
4314 The third argument, @var{doc}, is an optional documentation string.
4316 Each argument in @var{specs} has the form of a property list, and each
4317 one should specify at least the @code{:type} property and either the
4318 @code{:file} or the @code{:data} property. The value of @code{:type}
4319 should be a symbol specifying the image type, the value of
4320 @code{:file} is the file to load the image from, and the value of
4321 @code{:data} is a string containing the actual image data. Here is an
4325 (defimage test-image
4326 ((:type xpm :file "~/test1.xpm")
4327 (:type xbm :file "~/test1.xbm")))
4330 @code{defimage} tests each argument, one by one, to see if it is
4331 usable---that is, if the type is supported and the file exists. The
4332 first usable argument is used to make an image descriptor which is
4333 stored in @var{symbol}.
4335 If none of the alternatives will work, then @var{symbol} is defined
4339 @defun find-image specs
4340 This function provides a convenient way to find an image satisfying one
4341 of a list of image specifications @var{specs}.
4343 Each specification in @var{specs} is a property list with contents
4344 depending on image type. All specifications must at least contain the
4345 properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
4346 or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
4347 the image type, e.g.@: @code{xbm}, @var{file} is the file to load the
4348 image from, and @var{data} is a string containing the actual image data.
4349 The first specification in the list whose @var{type} is supported, and
4350 @var{file} exists, is used to construct the image specification to be
4351 returned. If no specification is satisfied, @code{nil} is returned.
4353 The image is looked for in @code{image-load-path}.
4356 @defvar image-load-path
4357 This variable's value is a list of locations in which to search for
4358 image files. If an element is a string or a variable symbol whose
4359 value is a string, the string is taken to be the name of a directory
4360 to search. If an element is a variable symbol whose value is a list,
4361 that is taken to be a list of directory names to search.
4363 The default is to search in the @file{images} subdirectory of the
4364 directory specified by @code{data-directory}, then the directory
4365 specified by @code{data-directory}, and finally in the directories in
4366 @code{load-path}. Subdirectories are not automatically included in
4367 the search, so if you put an image file in a subdirectory, you have to
4368 supply the subdirectory name explicitly. For example, to find the
4369 image @file{images/foo/bar.xpm} within @code{data-directory}, you
4370 should specify the image as follows:
4373 (defimage foo-image '((:type xpm :file "foo/bar.xpm")))
4377 @defun image-load-path-for-library library image &optional path no-error
4378 This function returns a suitable search path for images used by the
4379 Lisp package @var{library}.
4381 The function searches for @var{image} first using @code{image-load-path},
4382 excluding @file{@code{data-directory}/images}, and then in
4383 @code{load-path}, followed by a path suitable for @var{library}, which
4384 includes @file{../../etc/images} and @file{../etc/images} relative to
4385 the library file itself, and finally in
4386 @file{@code{data-directory}/images}.
4388 Then this function returns a list of directories which contains first
4389 the directory in which @var{image} was found, followed by the value of
4390 @code{load-path}. If @var{path} is given, it is used instead of
4393 If @var{no-error} is non-@code{nil} and a suitable path can't be
4394 found, don't signal an error. Instead, return a list of directories as
4395 before, except that @code{nil} appears in place of the image directory.
4397 Here is an example that uses a common idiom to provide compatibility
4398 with versions of Emacs that lack the variable @code{image-load-path}:
4401 (defvar image-load-path) ; shush compiler
4402 (let* ((load-path (image-load-path-for-library
4403 "mh-e" "mh-logo.xpm"))
4404 (image-load-path (cons (car load-path)
4405 (when (boundp 'image-load-path)
4407 (mh-tool-bar-folder-buttons-init))
4411 @node Showing Images
4412 @subsection Showing Images
4414 You can use an image descriptor by setting up the @code{display}
4415 property yourself, but it is easier to use the functions in this
4418 @defun insert-image image &optional string area slice
4419 This function inserts @var{image} in the current buffer at point. The
4420 value @var{image} should be an image descriptor; it could be a value
4421 returned by @code{create-image}, or the value of a symbol defined with
4422 @code{defimage}. The argument @var{string} specifies the text to put
4423 in the buffer to hold the image. If it is omitted or @code{nil},
4424 @code{insert-image} uses @code{" "} by default.
4426 The argument @var{area} specifies whether to put the image in a margin.
4427 If it is @code{left-margin}, the image appears in the left margin;
4428 @code{right-margin} specifies the right margin. If @var{area} is
4429 @code{nil} or omitted, the image is displayed at point within the
4432 The argument @var{slice} specifies a slice of the image to insert. If
4433 @var{slice} is @code{nil} or omitted the whole image is inserted.
4434 Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width}
4435 @var{height})} which specifies the @var{x} and @var{y} positions and
4436 @var{width} and @var{height} of the image area to insert. Integer
4437 values are in units of pixels. A floating point number in the range
4438 0.0--1.0 stands for that fraction of the width or height of the entire
4441 Internally, this function inserts @var{string} in the buffer, and gives
4442 it a @code{display} property which specifies @var{image}. @xref{Display
4446 @defun insert-sliced-image image &optional string area rows cols
4447 This function inserts @var{image} in the current buffer at point, like
4448 @code{insert-image}, but splits the image into @var{rows}x@var{cols}
4449 equally sized slices.
4452 @defun put-image image pos &optional string area
4453 This function puts image @var{image} in front of @var{pos} in the
4454 current buffer. The argument @var{pos} should be an integer or a
4455 marker. It specifies the buffer position where the image should appear.
4456 The argument @var{string} specifies the text that should hold the image
4457 as an alternative to the default.
4459 The argument @var{image} must be an image descriptor, perhaps returned
4460 by @code{create-image} or stored by @code{defimage}.
4462 The argument @var{area} specifies whether to put the image in a margin.
4463 If it is @code{left-margin}, the image appears in the left margin;
4464 @code{right-margin} specifies the right margin. If @var{area} is
4465 @code{nil} or omitted, the image is displayed at point within the
4468 Internally, this function creates an overlay, and gives it a
4469 @code{before-string} property containing text that has a @code{display}
4470 property whose value is the image. (Whew!)
4473 @defun remove-images start end &optional buffer
4474 This function removes images in @var{buffer} between positions
4475 @var{start} and @var{end}. If @var{buffer} is omitted or @code{nil},
4476 images are removed from the current buffer.
4478 This removes only images that were put into @var{buffer} the way
4479 @code{put-image} does it, not images that were inserted with
4480 @code{insert-image} or in other ways.
4483 @defun image-size spec &optional pixels frame
4484 This function returns the size of an image as a pair
4485 @w{@code{(@var{width} . @var{height})}}. @var{spec} is an image
4486 specification. @var{pixels} non-@code{nil} means return sizes
4487 measured in pixels, otherwise return sizes measured in canonical
4488 character units (fractions of the width/height of the frame's default
4489 font). @var{frame} is the frame on which the image will be displayed.
4490 @var{frame} null or omitted means use the selected frame (@pxref{Input
4494 @defvar max-image-size
4495 This variable is used to define the maximum size of image that Emacs
4496 will load. Emacs will refuse to load (and display) any image that is
4497 larger than this limit.
4499 If the value is an integer, it directly specifies the maximum
4500 image height and width, measured in pixels. If it is a floating
4501 point number, it specifies the maximum image height and width
4502 as a ratio to the frame height and width. If the value is
4503 non-numeric, there is no explicit limit on the size of images.
4505 The purpose of this variable is to prevent unreasonably large images
4506 from accidentally being loaded into Emacs. It only takes effect the
4507 first time an image is loaded. Once an image is placed in the image
4508 cache, it can always be displayed, even if the value of
4509 @var{max-image-size} is subsequently changed (@pxref{Image Cache}).
4513 @subsection Image Cache
4516 Emacs stores images in an image cache so that it can display them
4517 again more efficiently. When Emacs displays an image, it searches the
4518 image cache for an existing image specification @code{equal} to the
4519 desired specification. If a match is found, the image is displayed
4520 from the cache; otherwise, Emacs loads the image normally.
4522 Occasionally, you may need to tell Emacs to refresh the images
4523 associated with a given image specification. For example, suppose you
4524 display an image using a specification that contains a @code{:file}
4525 property. The image is loaded from the given file and stored in the
4526 image cache. If you later display the image again, using the same
4527 image specification, the image is displayed from the image cache.
4528 Normally, this is not a problem. However, if the image file has
4529 changed in the meantime, Emacs would be displaying the old version of
4530 the image. In such a situation, it is necessary to ``refresh'' the
4531 image using @code{image-refresh}.
4533 @defun image-refresh spec &optional frame
4534 This function refreshes any images having image specifications
4535 @code{equal} to @var{spec} on frame @var{frame}. If @var{frame} is
4536 @code{nil}, the selected frame is used. If @var{frame} is @code{t},
4537 the refresh is applied to all existing frames.
4539 This works by removing all image with image specifications matching
4540 @var{spec} from the image cache. Thus, the next time the image is
4541 displayed, Emacs will load the image again.
4544 @defun clear-image-cache &optional filter
4545 This function clears the image cache. If @var{filter} is
4546 a frame, only the cache for that frame is cleared. If omitted or
4547 @code{nil}, clear the images on the selected frame. If @code{t},
4548 all frames' caches are cleared. Otherwise, @var{filter} is taken as
4549 a file name and only images that reference this file will be flushed.
4552 If an image in the image cache has not been displayed for a specified
4553 period of time, Emacs removes it from the cache and frees the
4556 @defvar image-cache-eviction-delay
4557 This variable specifies the number of seconds an image can remain in the
4558 cache without being displayed. When an image is not displayed for this
4559 length of time, Emacs removes it from the image cache.
4561 If the value is @code{nil}, Emacs does not remove images from the cache
4562 except when you explicitly clear it. This mode can be useful for
4568 @cindex buttons in buffers
4569 @cindex clickable buttons in buffers
4571 The @emph{button} package defines functions for inserting and
4572 manipulating clickable (with the mouse, or via keyboard commands)
4573 buttons in Emacs buffers, such as might be used for help hyper-links,
4574 etc. Emacs uses buttons for the hyper-links in help text and the like.
4576 A button is essentially a set of properties attached (via text
4577 properties or overlays) to a region of text in an Emacs buffer. These
4578 properties are called @dfn{button properties}.
4580 One of these properties (@code{action}) is a function, which will
4581 be called when the user invokes it using the keyboard or the mouse.
4582 The invoked function may then examine the button and use its other
4583 properties as desired.
4585 In some ways the Emacs button package duplicates functionality offered
4586 by the widget package (@pxref{Top, , Introduction, widget, The Emacs
4587 Widget Library}), but the button package has the advantage that it is
4588 much faster, much smaller, and much simpler to use (for elisp
4589 programmers---for users, the result is about the same). The extra
4590 speed and space savings are useful mainly if you need to create many
4591 buttons in a buffer (for instance an @code{*Apropos*} buffer uses
4592 buttons to make entries clickable, and may contain many thousands of
4596 * Button Properties:: Button properties with special meanings.
4597 * Button Types:: Defining common properties for classes of buttons.
4598 * Making Buttons:: Adding buttons to Emacs buffers.
4599 * Manipulating Buttons:: Getting and setting properties of buttons.
4600 * Button Buffer Commands:: Buffer-wide commands and bindings for buttons.
4603 @node Button Properties
4604 @subsection Button Properties
4605 @cindex button properties
4607 Buttons have an associated list of properties defining their
4608 appearance and behavior, and other arbitrary properties may be used
4609 for application specific purposes. Some properties that have special
4610 meaning to the button package include:
4614 @kindex action @r{(button property)}
4615 The function to call when the user invokes the button, which is passed
4616 the single argument @var{button}. By default this is @code{ignore},
4620 @kindex mouse-action @r{(button property)}
4621 This is similar to @code{action}, and when present, will be used
4622 instead of @code{action} for button invocations resulting from
4623 mouse-clicks (instead of the user hitting @key{RET}). If not
4624 present, mouse-clicks use @code{action} instead.
4627 @kindex face @r{(button property)}
4628 This is an Emacs face controlling how buttons of this type are
4629 displayed; by default this is the @code{button} face.
4632 @kindex mouse-face @r{(button property)}
4633 This is an additional face which controls appearance during
4634 mouse-overs (merged with the usual button face); by default this is
4635 the usual Emacs @code{highlight} face.
4638 @kindex keymap @r{(button property)}
4639 The button's keymap, defining bindings active within the button
4640 region. By default this is the usual button region keymap, stored
4641 in the variable @code{button-map}, which defines @key{RET} and
4642 @key{mouse-2} to invoke the button.
4645 @kindex type @r{(button property)}
4646 The button-type of the button. When creating a button, this is
4647 usually specified using the @code{:type} keyword argument.
4648 @xref{Button Types}.
4651 @kindex help-index @r{(button property)}
4652 A string displayed by the Emacs tool-tip help system; by default,
4653 @code{"mouse-2, RET: Push this button"}.
4656 @kindex follow-link @r{(button property)}
4657 The follow-link property, defining how a @key{Mouse-1} click behaves
4658 on this button, @xref{Links and Mouse-1}.
4661 @kindex button @r{(button property)}
4662 All buttons have a non-@code{nil} @code{button} property, which may be useful
4663 in finding regions of text that comprise buttons (which is what the
4664 standard button functions do).
4667 There are other properties defined for the regions of text in a
4668 button, but these are not generally interesting for typical uses.
4671 @subsection Button Types
4672 @cindex button types
4674 Every button has a button @emph{type}, which defines default values
4675 for the button's properties. Button types are arranged in a
4676 hierarchy, with specialized types inheriting from more general types,
4677 so that it's easy to define special-purpose types of buttons for
4680 @defun define-button-type name &rest properties
4681 Define a `button type' called @var{name} (a symbol).
4682 The remaining arguments
4683 form a sequence of @var{property value} pairs, specifying default
4684 property values for buttons with this type (a button's type may be set
4685 by giving it a @code{type} property when creating the button, using
4686 the @code{:type} keyword argument).
4688 In addition, the keyword argument @code{:supertype} may be used to
4689 specify a button-type from which @var{name} inherits its default
4690 property values. Note that this inheritance happens only when
4691 @var{name} is defined; subsequent changes to a supertype are not
4692 reflected in its subtypes.
4695 Using @code{define-button-type} to define default properties for
4696 buttons is not necessary---buttons without any specified type use the
4697 built-in button-type @code{button}---but it is encouraged, since
4698 doing so usually makes the resulting code clearer and more efficient.
4700 @node Making Buttons
4701 @subsection Making Buttons
4702 @cindex making buttons
4704 Buttons are associated with a region of text, using an overlay or
4705 text properties to hold button-specific information, all of which are
4706 initialized from the button's type (which defaults to the built-in
4707 button type @code{button}). Like all Emacs text, the appearance of
4708 the button is governed by the @code{face} property; by default (via
4709 the @code{face} property inherited from the @code{button} button-type)
4710 this is a simple underline, like a typical web-page link.
4712 For convenience, there are two sorts of button-creation functions,
4713 those that add button properties to an existing region of a buffer,
4714 called @code{make-...button}, and those that also insert the button
4715 text, called @code{insert-...button}.
4717 The button-creation functions all take the @code{&rest} argument
4718 @var{properties}, which should be a sequence of @var{property value}
4719 pairs, specifying properties to add to the button; see @ref{Button
4720 Properties}. In addition, the keyword argument @code{:type} may be
4721 used to specify a button-type from which to inherit other properties;
4722 see @ref{Button Types}. Any properties not explicitly specified
4723 during creation will be inherited from the button's type (if the type
4724 defines such a property).
4726 The following functions add a button using an overlay
4727 (@pxref{Overlays}) to hold the button properties:
4729 @defun make-button beg end &rest properties
4730 This makes a button from @var{beg} to @var{end} in the
4731 current buffer, and returns it.
4734 @defun insert-button label &rest properties
4735 This insert a button with the label @var{label} at point,
4739 The following functions are similar, but use Emacs text properties
4740 (@pxref{Text Properties}) to hold the button properties, making the
4741 button actually part of the text instead of being a property of the
4742 buffer. Buttons using text properties do not create markers into the
4743 buffer, which is important for speed when you use extremely large
4744 numbers of buttons. Both functions return the position of the start
4747 @defun make-text-button beg end &rest properties
4748 This makes a button from @var{beg} to @var{end} in the current buffer, using
4752 @defun insert-text-button label &rest properties
4753 This inserts a button with the label @var{label} at point, using text
4757 @node Manipulating Buttons
4758 @subsection Manipulating Buttons
4759 @cindex manipulating buttons
4761 These are functions for getting and setting properties of buttons.
4762 Often these are used by a button's invocation function to determine
4765 Where a @var{button} parameter is specified, it means an object
4766 referring to a specific button, either an overlay (for overlay
4767 buttons), or a buffer-position or marker (for text property buttons).
4768 Such an object is passed as the first argument to a button's
4769 invocation function when it is invoked.
4771 @defun button-start button
4772 Return the position at which @var{button} starts.
4775 @defun button-end button
4776 Return the position at which @var{button} ends.
4779 @defun button-get button prop
4780 Get the property of button @var{button} named @var{prop}.
4783 @defun button-put button prop val
4784 Set @var{button}'s @var{prop} property to @var{val}.
4787 @defun button-activate button &optional use-mouse-action
4788 Call @var{button}'s @code{action} property (i.e., invoke it). If
4789 @var{use-mouse-action} is non-@code{nil}, try to invoke the button's
4790 @code{mouse-action} property instead of @code{action}; if the button
4791 has no @code{mouse-action} property, use @code{action} as normal.
4794 @defun button-label button
4795 Return @var{button}'s text label.
4798 @defun button-type button
4799 Return @var{button}'s button-type.
4802 @defun button-has-type-p button type
4803 Return @code{t} if @var{button} has button-type @var{type}, or one of
4804 @var{type}'s subtypes.
4807 @defun button-at pos
4808 Return the button at position @var{pos} in the current buffer, or @code{nil}.
4811 @defun button-type-put type prop val
4812 Set the button-type @var{type}'s @var{prop} property to @var{val}.
4815 @defun button-type-get type prop
4816 Get the property of button-type @var{type} named @var{prop}.
4819 @defun button-type-subtype-p type supertype
4820 Return @code{t} if button-type @var{type} is a subtype of @var{supertype}.
4823 @node Button Buffer Commands
4824 @subsection Button Buffer Commands
4825 @cindex button buffer commands
4827 These are commands and functions for locating and operating on
4828 buttons in an Emacs buffer.
4830 @code{push-button} is the command that a user uses to actually `push'
4831 a button, and is bound by default in the button itself to @key{RET}
4832 and to @key{mouse-2} using a region-specific keymap. Commands
4833 that are useful outside the buttons itself, such as
4834 @code{forward-button} and @code{backward-button} are additionally
4835 available in the keymap stored in @code{button-buffer-map}; a mode
4836 which uses buttons may want to use @code{button-buffer-map} as a
4837 parent keymap for its keymap.
4839 If the button has a non-@code{nil} @code{follow-link} property, and
4840 @var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click
4841 will also activate the @code{push-button} command.
4842 @xref{Links and Mouse-1}.
4844 @deffn Command push-button &optional pos use-mouse-action
4845 Perform the action specified by a button at location @var{pos}.
4846 @var{pos} may be either a buffer position or a mouse-event. If
4847 @var{use-mouse-action} is non-@code{nil}, or @var{pos} is a
4848 mouse-event (@pxref{Mouse Events}), try to invoke the button's
4849 @code{mouse-action} property instead of @code{action}; if the button
4850 has no @code{mouse-action} property, use @code{action} as normal.
4851 @var{pos} defaults to point, except when @code{push-button} is invoked
4852 interactively as the result of a mouse-event, in which case, the mouse
4853 event's position is used. If there's no button at @var{pos}, do
4854 nothing and return @code{nil}, otherwise return @code{t}.
4857 @deffn Command forward-button n &optional wrap display-message
4858 Move to the @var{n}th next button, or @var{n}th previous button if
4859 @var{n} is negative. If @var{n} is zero, move to the start of any
4860 button at point. If @var{wrap} is non-@code{nil}, moving past either
4861 end of the buffer continues from the other end. If
4862 @var{display-message} is non-@code{nil}, the button's help-echo string
4863 is displayed. Any button with a non-@code{nil} @code{skip} property
4864 is skipped over. Returns the button found.
4867 @deffn Command backward-button n &optional wrap display-message
4868 Move to the @var{n}th previous button, or @var{n}th next button if
4869 @var{n} is negative. If @var{n} is zero, move to the start of any
4870 button at point. If @var{wrap} is non-@code{nil}, moving past either
4871 end of the buffer continues from the other end. If
4872 @var{display-message} is non-@code{nil}, the button's help-echo string
4873 is displayed. Any button with a non-@code{nil} @code{skip} property
4874 is skipped over. Returns the button found.
4877 @defun next-button pos &optional count-current
4878 @defunx previous-button pos &optional count-current
4879 Return the next button after (for @code{next-button} or before (for
4880 @code{previous-button}) position @var{pos} in the current buffer. If
4881 @var{count-current} is non-@code{nil}, count any button at @var{pos}
4882 in the search, instead of starting at the next button.
4885 @node Abstract Display
4886 @section Abstract Display
4888 @cindex display, abstract
4889 @cindex display, arbitrary objects
4890 @cindex model/view/controller
4891 @cindex view part, model/view/controller
4893 The Ewoc package constructs buffer text that represents a structure
4894 of Lisp objects, and updates the text to follow changes in that
4895 structure. This is like the ``view'' component in the
4896 ``model/view/controller'' design paradigm.
4898 An @dfn{ewoc} is a structure that organizes information required to
4899 construct buffer text that represents certain Lisp data. The buffer
4900 text of the ewoc has three parts, in order: first, fixed @dfn{header}
4901 text; next, textual descriptions of a series of data elements (Lisp
4902 objects that you specify); and last, fixed @dfn{footer} text.
4903 Specifically, an ewoc contains information on:
4907 The buffer which its text is generated in.
4910 The text's start position in the buffer.
4913 The header and footer strings.
4916 A doubly-linked chain of @dfn{nodes}, each of which contains:
4920 A @dfn{data element}, a single Lisp object.
4923 Links to the preceding and following nodes in the chain.
4927 A @dfn{pretty-printer} function which is responsible for
4928 inserting the textual representation of a data
4929 element value into the current buffer.
4932 Typically, you define an ewoc with @code{ewoc-create}, and then pass
4933 the resulting ewoc structure to other functions in the Ewoc package to
4934 build nodes within it, and display it in the buffer. Once it is
4935 displayed in the buffer, other functions determine the correspondance
4936 between buffer positions and nodes, move point from one node's textual
4937 representation to another, and so forth. @xref{Abstract Display
4940 A node @dfn{encapsulates} a data element much the way a variable
4941 holds a value. Normally, encapsulation occurs as a part of adding a
4942 node to the ewoc. You can retrieve the data element value and place a
4943 new value in its place, like so:
4946 (ewoc-data @var{node})
4949 (ewoc-set-data @var{node} @var{new-value})
4950 @result{} @var{new-value}
4954 You can also use, as the data element value, a Lisp object (list or
4955 vector) that is a container for the ``real'' value, or an index into
4956 some other structure. The example (@pxref{Abstract Display Example})
4957 uses the latter approach.
4959 When the data changes, you will want to update the text in the
4960 buffer. You can update all nodes by calling @code{ewoc-refresh}, or
4961 just specific nodes using @code{ewoc-invalidate}, or all nodes
4962 satisfying a predicate using @code{ewoc-map}. Alternatively, you can
4963 delete invalid nodes using @code{ewoc-delete} or @code{ewoc-filter},
4964 and add new nodes in their place. Deleting a node from an ewoc deletes
4965 its associated textual description from buffer, as well.
4968 * Abstract Display Functions::
4969 * Abstract Display Example::
4972 @node Abstract Display Functions
4973 @subsection Abstract Display Functions
4975 In this subsection, @var{ewoc} and @var{node} stand for the
4976 structures described above (@pxref{Abstract Display}), while
4977 @var{data} stands for an arbitrary Lisp object used as a data element.
4979 @defun ewoc-create pretty-printer &optional header footer nosep
4980 This constructs and returns a new ewoc, with no nodes (and thus no data
4981 elements). @var{pretty-printer} should be a function that takes one
4982 argument, a data element of the sort you plan to use in this ewoc, and
4983 inserts its textual description at point using @code{insert} (and never
4984 @code{insert-before-markers}, because that would interfere with the
4985 Ewoc package's internal mechanisms).
4987 Normally, a newline is automatically inserted after the header,
4988 the footer and every node's textual description. If @var{nosep}
4989 is non-@code{nil}, no newline is inserted. This may be useful for
4990 displaying an entire ewoc on a single line, for example, or for
4991 making nodes ``invisible'' by arranging for @var{pretty-printer}
4992 to do nothing for those nodes.
4994 An ewoc maintains its text in the buffer that is current when
4995 you create it, so switch to the intended buffer before calling
4999 @defun ewoc-buffer ewoc
5000 This returns the buffer where @var{ewoc} maintains its text.
5003 @defun ewoc-get-hf ewoc
5004 This returns a cons cell @code{(@var{header} . @var{footer})}
5005 made from @var{ewoc}'s header and footer.
5008 @defun ewoc-set-hf ewoc header footer
5009 This sets the header and footer of @var{ewoc} to the strings
5010 @var{header} and @var{footer}, respectively.
5013 @defun ewoc-enter-first ewoc data
5014 @defunx ewoc-enter-last ewoc data
5015 These add a new node encapsulating @var{data}, putting it, respectively,
5016 at the beginning or end of @var{ewoc}'s chain of nodes.
5019 @defun ewoc-enter-before ewoc node data
5020 @defunx ewoc-enter-after ewoc node data
5021 These add a new node encapsulating @var{data}, adding it to
5022 @var{ewoc} before or after @var{node}, respectively.
5025 @defun ewoc-prev ewoc node
5026 @defunx ewoc-next ewoc node
5027 These return, respectively, the previous node and the next node of @var{node}
5031 @defun ewoc-nth ewoc n
5032 This returns the node in @var{ewoc} found at zero-based index @var{n}.
5033 A negative @var{n} means count from the end. @code{ewoc-nth} returns
5034 @code{nil} if @var{n} is out of range.
5037 @defun ewoc-data node
5038 This extracts the data encapsulated by @var{node} and returns it.
5041 @defun ewoc-set-data node data
5042 This sets the data encapsulated by @var{node} to @var{data}.
5045 @defun ewoc-locate ewoc &optional pos guess
5046 This determines the node in @var{ewoc} which contains point (or
5047 @var{pos} if specified), and returns that node. If @var{ewoc} has no
5048 nodes, it returns @code{nil}. If @var{pos} is before the first node,
5049 it returns the first node; if @var{pos} is after the last node, it returns
5050 the last node. The optional third arg @var{guess}
5051 should be a node that is likely to be near @var{pos}; this doesn't
5052 alter the result, but makes the function run faster.
5055 @defun ewoc-location node
5056 This returns the start position of @var{node}.
5059 @defun ewoc-goto-prev ewoc arg
5060 @defunx ewoc-goto-next ewoc arg
5061 These move point to the previous or next, respectively, @var{arg}th node
5062 in @var{ewoc}. @code{ewoc-goto-prev} does not move if it is already at
5063 the first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next}
5064 moves past the last node, returning @code{nil}. Excepting this special
5065 case, these functions return the node moved to.
5068 @defun ewoc-goto-node ewoc node
5069 This moves point to the start of @var{node} in @var{ewoc}.
5072 @defun ewoc-refresh ewoc
5073 This function regenerates the text of @var{ewoc}. It works by
5074 deleting the text between the header and the footer, i.e., all the
5075 data elements' representations, and then calling the pretty-printer
5076 function for each node, one by one, in order.
5079 @defun ewoc-invalidate ewoc &rest nodes
5080 This is similar to @code{ewoc-refresh}, except that only @var{nodes} in
5081 @var{ewoc} are updated instead of the entire set.
5084 @defun ewoc-delete ewoc &rest nodes
5085 This deletes each node in @var{nodes} from @var{ewoc}.
5088 @defun ewoc-filter ewoc predicate &rest args
5089 This calls @var{predicate} for each data element in @var{ewoc} and
5090 deletes those nodes for which @var{predicate} returns @code{nil}.
5091 Any @var{args} are passed to @var{predicate}.
5094 @defun ewoc-collect ewoc predicate &rest args
5095 This calls @var{predicate} for each data element in @var{ewoc}
5096 and returns a list of those elements for which @var{predicate}
5097 returns non-@code{nil}. The elements in the list are ordered
5098 as in the buffer. Any @var{args} are passed to @var{predicate}.
5101 @defun ewoc-map map-function ewoc &rest args
5102 This calls @var{map-function} for each data element in @var{ewoc} and
5103 updates those nodes for which @var{map-function} returns non-@code{nil}.
5104 Any @var{args} are passed to @var{map-function}.
5107 @node Abstract Display Example
5108 @subsection Abstract Display Example
5110 Here is a simple example using functions of the ewoc package to
5111 implement a ``color components display,'' an area in a buffer that
5112 represents a vector of three integers (itself representing a 24-bit RGB
5113 value) in various ways.
5116 (setq colorcomp-ewoc nil
5118 colorcomp-mode-map nil
5119 colorcomp-labels ["Red" "Green" "Blue"])
5121 (defun colorcomp-pp (data)
5123 (let ((comp (aref colorcomp-data data)))
5124 (insert (aref colorcomp-labels data) "\t: #x"
5125 (format "%02X" comp) " "
5126 (make-string (ash comp -2) ?#) "\n"))
5127 (let ((cstr (format "#%02X%02X%02X"
5128 (aref colorcomp-data 0)
5129 (aref colorcomp-data 1)
5130 (aref colorcomp-data 2)))
5131 (samp " (sample text) "))
5133 (propertize samp 'face `(foreground-color . ,cstr))
5134 (propertize samp 'face `(background-color . ,cstr))
5137 (defun colorcomp (color)
5138 "Allow fiddling with COLOR in a new buffer.
5139 The buffer is in Color Components mode."
5140 (interactive "sColor (name or #RGB or #RRGGBB): ")
5141 (when (string= "" color)
5142 (setq color "green"))
5143 (unless (color-values color)
5144 (error "No such color: %S" color))
5146 (generate-new-buffer (format "originally: %s" color)))
5147 (kill-all-local-variables)
5148 (setq major-mode 'colorcomp-mode
5149 mode-name "Color Components")
5150 (use-local-map colorcomp-mode-map)
5152 (buffer-disable-undo)
5153 (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8))
5154 (color-values color))))
5155 (ewoc (ewoc-create 'colorcomp-pp
5156 "\nColor Components\n\n"
5157 (substitute-command-keys
5158 "\n\\@{colorcomp-mode-map@}"))))
5159 (set (make-local-variable 'colorcomp-data) data)
5160 (set (make-local-variable 'colorcomp-ewoc) ewoc)
5161 (ewoc-enter-last ewoc 0)
5162 (ewoc-enter-last ewoc 1)
5163 (ewoc-enter-last ewoc 2)
5164 (ewoc-enter-last ewoc nil)))
5167 @cindex controller part, model/view/controller
5168 This example can be extended to be a ``color selection widget'' (in
5169 other words, the controller part of the ``model/view/controller''
5170 design paradigm) by defining commands to modify @code{colorcomp-data}
5171 and to ``finish'' the selection process, and a keymap to tie it all
5172 together conveniently.
5175 (defun colorcomp-mod (index limit delta)
5176 (let ((cur (aref colorcomp-data index)))
5177 (unless (= limit cur)
5178 (aset colorcomp-data index (+ cur delta)))
5181 (ewoc-nth colorcomp-ewoc index)
5182 (ewoc-nth colorcomp-ewoc -1))))
5184 (defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1))
5185 (defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1))
5186 (defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1))
5187 (defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1))
5188 (defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1))
5189 (defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1))
5191 (defun colorcomp-copy-as-kill-and-exit ()
5192 "Copy the color components into the kill ring and kill the buffer.
5193 The string is formatted #RRGGBB (hash followed by six hex digits)."
5195 (kill-new (format "#%02X%02X%02X"
5196 (aref colorcomp-data 0)
5197 (aref colorcomp-data 1)
5198 (aref colorcomp-data 2)))
5201 (setq colorcomp-mode-map
5202 (let ((m (make-sparse-keymap)))
5204 (define-key m "i" 'colorcomp-R-less)
5205 (define-key m "o" 'colorcomp-R-more)
5206 (define-key m "k" 'colorcomp-G-less)
5207 (define-key m "l" 'colorcomp-G-more)
5208 (define-key m "," 'colorcomp-B-less)
5209 (define-key m "." 'colorcomp-B-more)
5210 (define-key m " " 'colorcomp-copy-as-kill-and-exit)
5214 Note that we never modify the data in each node, which is fixed when the
5215 ewoc is created to be either @code{nil} or an index into the vector
5216 @code{colorcomp-data}, the actual color components.
5219 @section Blinking Parentheses
5220 @cindex parenthesis matching
5221 @cindex blinking parentheses
5222 @cindex balancing parentheses
5224 This section describes the mechanism by which Emacs shows a matching
5225 open parenthesis when the user inserts a close parenthesis.
5227 @defvar blink-paren-function
5228 The value of this variable should be a function (of no arguments) to
5229 be called whenever a character with close parenthesis syntax is inserted.
5230 The value of @code{blink-paren-function} may be @code{nil}, in which
5231 case nothing is done.
5234 @defopt blink-matching-paren
5235 If this variable is @code{nil}, then @code{blink-matching-open} does
5239 @defopt blink-matching-paren-distance
5240 This variable specifies the maximum distance to scan for a matching
5241 parenthesis before giving up.
5244 @defopt blink-matching-delay
5245 This variable specifies the number of seconds for the cursor to remain
5246 at the matching parenthesis. A fraction of a second often gives
5247 good results, but the default is 1, which works on all systems.
5250 @deffn Command blink-matching-open
5251 This function is the default value of @code{blink-paren-function}. It
5252 assumes that point follows a character with close parenthesis syntax and
5253 moves the cursor momentarily to the matching opening character. If that
5254 character is not already on the screen, it displays the character's
5255 context in the echo area. To avoid long delays, this function does not
5256 search farther than @code{blink-matching-paren-distance} characters.
5258 Here is an example of calling this function explicitly.
5262 (defun interactive-blink-matching-open ()
5263 @c Do not break this line! -- rms.
5264 @c The first line of a doc string
5265 @c must stand alone.
5266 "Indicate momentarily the start of sexp before point."
5270 (let ((blink-matching-paren-distance
5272 (blink-matching-paren t))
5273 (blink-matching-open)))
5279 @section Usual Display Conventions
5281 The usual display conventions define how to display each character
5282 code. You can override these conventions by setting up a display table
5283 (@pxref{Display Tables}). Here are the usual display conventions:
5287 Character codes 32 through 126 map to glyph codes 32 through 126.
5288 Normally this means they display as themselves.
5291 Character code 9 is a horizontal tab. It displays as whitespace
5292 up to a position determined by @code{tab-width}.
5295 Character code 10 is a newline.
5298 All other codes in the range 0 through 31, and code 127, display in one
5299 of two ways according to the value of @code{ctl-arrow}. If it is
5300 non-@code{nil}, these codes map to sequences of two glyphs, where the
5301 first glyph is the @acronym{ASCII} code for @samp{^}. (A display table can
5302 specify a glyph to use instead of @samp{^}.) Otherwise, these codes map
5303 just like the codes in the range 128 to 255.
5305 On MS-DOS terminals, Emacs arranges by default for the character code
5306 127 to be mapped to the glyph code 127, which normally displays as an
5307 empty polygon. This glyph is used to display non-@acronym{ASCII} characters
5308 that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,,
5309 emacs, The GNU Emacs Manual}.
5312 Character codes 128 through 255 map to sequences of four glyphs, where
5313 the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are
5314 digit characters representing the character code in octal. (A display
5315 table can specify a glyph to use instead of @samp{\}.)
5318 Multibyte character codes above 256 are displayed as themselves, or as a
5319 question mark or empty box if the terminal cannot display that
5323 The usual display conventions apply even when there is a display
5324 table, for any character whose entry in the active display table is
5325 @code{nil}. Thus, when you set up a display table, you need only
5326 specify the characters for which you want special behavior.
5328 These display rules apply to carriage return (character code 13), when
5329 it appears in the buffer. But that character may not appear in the
5330 buffer where you expect it, if it was eliminated as part of end-of-line
5331 conversion (@pxref{Coding System Basics}).
5333 These variables affect the way certain characters are displayed on the
5334 screen. Since they change the number of columns the characters occupy,
5335 they also affect the indentation functions. These variables also affect
5336 how the mode line is displayed; if you want to force redisplay of the
5337 mode line using the new values, call the function
5338 @code{force-mode-line-update} (@pxref{Mode Line Format}).
5341 @cindex control characters in display
5342 This buffer-local variable controls how control characters are
5343 displayed. If it is non-@code{nil}, they are displayed as a caret
5344 followed by the character: @samp{^A}. If it is @code{nil}, they are
5345 displayed as a backslash followed by three octal digits: @samp{\001}.
5348 @c Following may have overfull hbox.
5349 @defvar default-ctl-arrow
5350 The value of this variable is the default value for @code{ctl-arrow} in
5351 buffers that do not override it. @xref{Default Value}.
5355 The value of this buffer-local variable is the spacing between tab
5356 stops used for displaying tab characters in Emacs buffers. The value
5357 is in units of columns, and the default is 8. Note that this feature
5358 is completely independent of the user-settable tab stops used by the
5359 command @code{tab-to-tab-stop}. @xref{Indent Tabs}.
5362 @node Display Tables
5363 @section Display Tables
5365 @cindex display table
5366 You can use the @dfn{display table} feature to control how all possible
5367 character codes display on the screen. This is useful for displaying
5368 European languages that have letters not in the @acronym{ASCII} character
5371 The display table maps each character code into a sequence of
5372 @dfn{glyphs}, each glyph being a graphic that takes up one character
5373 position on the screen. You can also define how to display each glyph
5374 on your terminal, using the @dfn{glyph table}.
5376 Display tables affect how the mode line is displayed; if you want to
5377 force redisplay of the mode line using a new display table, call
5378 @code{force-mode-line-update} (@pxref{Mode Line Format}).
5381 * Display Table Format:: What a display table consists of.
5382 * Active Display Table:: How Emacs selects a display table to use.
5383 * Glyphs:: How to define a glyph, and what glyphs mean.
5386 @node Display Table Format
5387 @subsection Display Table Format
5389 A display table is actually a char-table (@pxref{Char-Tables}) with
5390 @code{display-table} as its subtype.
5392 @defun make-display-table
5393 This creates and returns a display table. The table initially has
5394 @code{nil} in all elements.
5397 The ordinary elements of the display table are indexed by character
5398 codes; the element at index @var{c} says how to display the character
5399 code @var{c}. The value should be @code{nil} or a vector of the
5400 glyphs to be output (@pxref{Glyphs}). @code{nil} says to display the
5401 character @var{c} according to the usual display conventions
5402 (@pxref{Usual Display}).
5404 @strong{Warning:} if you use the display table to change the display
5405 of newline characters, the whole buffer will be displayed as one long
5408 The display table also has six ``extra slots'' which serve special
5409 purposes. Here is a table of their meanings; @code{nil} in any slot
5410 means to use the default for that slot, as stated below.
5414 The glyph for the end of a truncated screen line (the default for this
5415 is @samp{$}). @xref{Glyphs}. On graphical terminals, Emacs uses
5416 arrows in the fringes to indicate truncation, so the display table has
5420 The glyph for the end of a continued line (the default is @samp{\}).
5421 On graphical terminals, Emacs uses curved arrows in the fringes to
5422 indicate continuation, so the display table has no effect.
5425 The glyph for indicating a character displayed as an octal character
5426 code (the default is @samp{\}).
5429 The glyph for indicating a control character (the default is @samp{^}).
5432 A vector of glyphs for indicating the presence of invisible lines (the
5433 default is @samp{...}). @xref{Selective Display}.
5436 The glyph used to draw the border between side-by-side windows (the
5437 default is @samp{|}). @xref{Splitting Windows}. This takes effect only
5438 when there are no scroll bars; if scroll bars are supported and in use,
5439 a scroll bar separates the two windows.
5442 For example, here is how to construct a display table that mimics the
5443 effect of setting @code{ctl-arrow} to a non-@code{nil} value:
5446 (setq disptab (make-display-table))
5449 (or (= i ?\t) (= i ?\n)
5450 (aset disptab i (vector ?^ (+ i 64))))
5452 (aset disptab 127 (vector ?^ ??)))
5455 @defun display-table-slot display-table slot
5456 This function returns the value of the extra slot @var{slot} of
5457 @var{display-table}. The argument @var{slot} may be a number from 0 to
5458 5 inclusive, or a slot name (symbol). Valid symbols are
5459 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
5460 @code{selective-display}, and @code{vertical-border}.
5463 @defun set-display-table-slot display-table slot value
5464 This function stores @var{value} in the extra slot @var{slot} of
5465 @var{display-table}. The argument @var{slot} may be a number from 0 to
5466 5 inclusive, or a slot name (symbol). Valid symbols are
5467 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
5468 @code{selective-display}, and @code{vertical-border}.
5471 @defun describe-display-table display-table
5472 This function displays a description of the display table
5473 @var{display-table} in a help buffer.
5476 @deffn Command describe-current-display-table
5477 This command displays a description of the current display table in a
5481 @node Active Display Table
5482 @subsection Active Display Table
5483 @cindex active display table
5485 Each window can specify a display table, and so can each buffer. When
5486 a buffer @var{b} is displayed in window @var{w}, display uses the
5487 display table for window @var{w} if it has one; otherwise, the display
5488 table for buffer @var{b} if it has one; otherwise, the standard display
5489 table if any. The display table chosen is called the @dfn{active}
5492 @defun window-display-table &optional window
5493 This function returns @var{window}'s display table, or @code{nil}
5494 if @var{window} does not have an assigned display table. The default
5495 for @var{window} is the selected window.
5498 @defun set-window-display-table window table
5499 This function sets the display table of @var{window} to @var{table}.
5500 The argument @var{table} should be either a display table or
5504 @defvar buffer-display-table
5505 This variable is automatically buffer-local in all buffers; its value in
5506 a particular buffer specifies the display table for that buffer. If it
5507 is @code{nil}, that means the buffer does not have an assigned display
5511 @defvar standard-display-table
5512 This variable's value is the default display table, used whenever a
5513 window has no display table and neither does the buffer displayed in
5514 that window. This variable is @code{nil} by default.
5517 If there is no display table to use for a particular window---that is,
5518 if the window specifies none, its buffer specifies none, and
5519 @code{standard-display-table} is @code{nil}---then Emacs uses the usual
5520 display conventions for all character codes in that window. @xref{Usual
5523 A number of functions for changing the standard display table
5524 are defined in the library @file{disp-table}.
5530 A @dfn{glyph} is a generalization of a character; it stands for an
5531 image that takes up a single character position on the screen. Normally
5532 glyphs come from vectors in the display table (@pxref{Display Tables}).
5534 A glyph is represented in Lisp as a @dfn{glyph code}. A glyph code
5535 can be @dfn{simple} or it can be defined by the @dfn{glyph table}. A
5536 simple glyph code is just a way of specifying a character and a face
5537 to output it in. @xref{Faces}.
5539 The following functions are used to manipulate simple glyph codes:
5541 @defun make-glyph-code char &optional face
5542 This function returns a simple glyph code representing char @var{char}
5543 with face @var{face}.
5546 @defun glyph-char glyph
5547 This function returns the character of simple glyph code @var{glyph}.
5550 @defun glyph-face glyph
5551 This function returns face of simple glyph code @var{glyph}, or
5552 @code{nil} if @var{glyph} has the default face (face-id 0).
5555 On character terminals, you can set up a @dfn{glyph table} to define
5556 the meaning of glyph codes (represented as small integers).
5559 The value of this variable is the current glyph table. It should be
5560 @code{nil} or a vector whose @var{g}th element defines glyph code
5563 If a glyph code is greater than or equal to the length of the glyph
5564 table, that code is automatically simple. If @code{glyph-table} is
5565 @code{nil} then all glyph codes are simple.
5567 The glyph table is used only on character terminals. On graphical
5568 displays, all glyph codes are simple.
5571 Here are the meaningful types of elements in the glyph table:
5575 Send the characters in @var{string} to the terminal to output
5579 Define this glyph code as an alias for glyph code @var{code} created
5580 by @code{make-glyph-code}. You can use such an alias to define a
5581 small-numbered glyph code which specifies a character with a face.
5584 This glyph code is simple.
5587 @defun create-glyph string
5588 This function returns a newly-allocated glyph code which is set up to
5589 display by sending @var{string} to the terminal.
5594 @c @cindex beeping "beep" is adjacent
5597 This section describes how to make Emacs ring the bell (or blink the
5598 screen) to attract the user's attention. Be conservative about how
5599 often you do this; frequent bells can become irritating. Also be
5600 careful not to use just beeping when signaling an error is more
5601 appropriate. (@xref{Errors}.)
5603 @defun ding &optional do-not-terminate
5604 @cindex keyboard macro termination
5605 This function beeps, or flashes the screen (see @code{visible-bell} below).
5606 It also terminates any keyboard macro currently executing unless
5607 @var{do-not-terminate} is non-@code{nil}.
5610 @defun beep &optional do-not-terminate
5611 This is a synonym for @code{ding}.
5614 @defopt visible-bell
5615 This variable determines whether Emacs should flash the screen to
5616 represent a bell. Non-@code{nil} means yes, @code{nil} means no. This
5617 is effective on graphical displays, and on text-only terminals
5618 provided the terminal's Termcap entry defines the visible bell
5619 capability (@samp{vb}).
5622 @defvar ring-bell-function
5623 If this is non-@code{nil}, it specifies how Emacs should ``ring the
5624 bell.'' Its value should be a function of no arguments. If this is
5625 non-@code{nil}, it takes precedence over the @code{visible-bell}
5629 @node Window Systems
5630 @section Window Systems
5632 Emacs works with several window systems, most notably the X Window
5633 System. Both Emacs and X use the term ``window,'' but use it
5634 differently. An Emacs frame is a single window as far as X is
5635 concerned; the individual Emacs windows are not known to X at all.
5637 @defvar window-system
5638 This variable tells Lisp programs what window system Emacs is running
5639 under. The possible values are
5643 @cindex X Window System
5644 Emacs is displaying using X.
5646 Emacs is displaying using MS-DOS.
5648 Emacs is displaying using Windows.
5650 Emacs is using a character-based terminal.
5654 @defvar window-setup-hook
5655 This variable is a normal hook which Emacs runs after handling the
5656 initialization files. Emacs runs this hook after it has completed
5657 loading your init file, the default initialization file (if
5658 any), and the terminal-specific Lisp code, and running the hook
5659 @code{term-setup-hook}.
5661 This hook is used for internal purposes: setting up communication with
5662 the window system, and creating the initial window. Users should not
5667 arch-tag: ffdf5714-7ecf-415b-9023-fbc6b409c2c6