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 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.
194 If your buffer contains @emph{very} long lines, and you use
195 continuation to display them, just thinking about them can make Emacs
196 redisplay slow. The column computation and indentation functions also
197 become slow. Then you might find it advisable to set
198 @code{cache-long-line-scans} to @code{t}.
200 @defvar cache-long-line-scans
201 If this variable is non-@code{nil}, various indentation and motion
202 functions, and Emacs redisplay, cache the results of scanning the
203 buffer, and consult the cache to avoid rescanning regions of the buffer
204 unless they are modified.
206 Turning on the cache slows down processing of short lines somewhat.
208 This variable is automatically buffer-local in every buffer.
212 @section The Echo Area
213 @cindex error display
216 The @dfn{echo area} is used for displaying error messages
217 (@pxref{Errors}), for messages made with the @code{message} primitive,
218 and for echoing keystrokes. It is not the same as the minibuffer,
219 despite the fact that the minibuffer appears (when active) in the same
220 place on the screen as the echo area. The @cite{GNU Emacs Manual}
221 specifies the rules for resolving conflicts between the echo area and
222 the minibuffer for use of that screen space (@pxref{Minibuffer,, The
223 Minibuffer, emacs, The GNU Emacs Manual}).
225 You can write output in the echo area by using the Lisp printing
226 functions with @code{t} as the stream (@pxref{Output Functions}), or
230 * Displaying Messages:: Explicitly displaying text in the echo area.
231 * Progress:: Informing user about progress of a long operation.
232 * Logging Messages:: Echo area messages are logged for the user.
233 * Echo Area Customization:: Controlling the echo area.
236 @node Displaying Messages
237 @subsection Displaying Messages in the Echo Area
238 @cindex display message in echo area
240 This section describes the functions for explicitly producing echo
241 area messages. Many other Emacs features display messages there, too.
243 @defun message format-string &rest arguments
244 This function displays a message in the echo area. The argument
245 @var{format-string} is similar to a C language @code{printf} format
246 string. See @code{format} in @ref{Formatting Strings}, for the details
247 on the conversion specifications. @code{message} returns the
250 In batch mode, @code{message} prints the message text on the standard
251 error stream, followed by a newline.
253 If @var{format-string}, or strings among the @var{arguments}, have
254 @code{face} text properties, these affect the way the message is displayed.
257 If @var{format-string} is @code{nil} or the empty string,
258 @code{message} clears the echo area; if the echo area has been
259 expanded automatically, this brings it back to its normal size.
260 If the minibuffer is active, this brings the minibuffer contents back
261 onto the screen immediately.
265 (message "Minibuffer depth is %d."
267 @print{} Minibuffer depth is 0.
268 @result{} "Minibuffer depth is 0."
272 ---------- Echo Area ----------
273 Minibuffer depth is 0.
274 ---------- Echo Area ----------
278 To automatically display a message in the echo area or in a pop-buffer,
279 depending on its size, use @code{display-message-or-buffer} (see below).
282 @defmac with-temp-message message &rest body
283 This construct displays a message in the echo area temporarily, during
284 the execution of @var{body}. It displays @var{message}, executes
285 @var{body}, then returns the value of the last body form while restoring
286 the previous echo area contents.
289 @defun message-or-box format-string &rest arguments
290 This function displays a message like @code{message}, but may display it
291 in a dialog box instead of the echo area. If this function is called in
292 a command that was invoked using the mouse---more precisely, if
293 @code{last-nonmenu-event} (@pxref{Command Loop Info}) is either
294 @code{nil} or a list---then it uses a dialog box or pop-up menu to
295 display the message. Otherwise, it uses the echo area. (This is the
296 same criterion that @code{y-or-n-p} uses to make a similar decision; see
297 @ref{Yes-or-No Queries}.)
299 You can force use of the mouse or of the echo area by binding
300 @code{last-nonmenu-event} to a suitable value around the call.
303 @defun message-box format-string &rest arguments
305 This function displays a message like @code{message}, but uses a dialog
306 box (or a pop-up menu) whenever that is possible. If it is impossible
307 to use a dialog box or pop-up menu, because the terminal does not
308 support them, then @code{message-box} uses the echo area, like
312 @defun display-message-or-buffer message &optional buffer-name not-this-window frame
313 This function displays the message @var{message}, which may be either a
314 string or a buffer. If it is shorter than the maximum height of the
315 echo area, as defined by @code{max-mini-window-height}, it is displayed
316 in the echo area, using @code{message}. Otherwise,
317 @code{display-buffer} is used to show it in a pop-up buffer.
319 Returns either the string shown in the echo area, or when a pop-up
320 buffer is used, the window used to display it.
322 If @var{message} is a string, then the optional argument
323 @var{buffer-name} is the name of the buffer used to display it when a
324 pop-up buffer is used, defaulting to @samp{*Message*}. In the case
325 where @var{message} is a string and displayed in the echo area, it is
326 not specified whether the contents are inserted into the buffer anyway.
328 The optional arguments @var{not-this-window} and @var{frame} are as for
329 @code{display-buffer}, and only used if a buffer is displayed.
332 @defun current-message
333 This function returns the message currently being displayed in the
334 echo area, or @code{nil} if there is none.
338 @subsection Reporting Operation Progress
339 @cindex progress reporting
341 When an operation can take a while to finish, you should inform the
342 user about the progress it makes. This way the user can estimate
343 remaining time and clearly see that Emacs is busy working, not hung.
345 Functions listed in this section provide simple and efficient way of
346 reporting operation progress. Here is a working example that does
350 (let ((progress-reporter
351 (make-progress-reporter "Collecting mana for Emacs..."
355 (progress-reporter-update progress-reporter k))
356 (progress-reporter-done progress-reporter))
359 @defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
360 This function creates and returns a @dfn{progress reporter}---an
361 object you will use as an argument for all other functions listed
362 here. The idea is to precompute as much data as possible to make
363 progress reporting very fast.
365 When this progress reporter is subsequently used, it will display
366 @var{message} in the echo area, followed by progress percentage.
367 @var{message} is treated as a simple string. If you need it to depend
368 on a filename, for instance, use @code{format} before calling this
371 @var{min-value} and @var{max-value} arguments stand for starting and
372 final states of your operation. For instance, if you scan a buffer,
373 they should be the results of @code{point-min} and @code{point-max}
374 correspondingly. It is required that @var{max-value} is greater than
375 @var{min-value}. If you create progress reporter when some part of
376 the operation has already been completed, then specify
377 @var{current-value} argument. But normally you should omit it or set
378 it to @code{nil}---it will default to @var{min-value} then.
380 Remaining arguments control the rate of echo area updates. Progress
381 reporter will wait for at least @var{min-change} more percents of the
382 operation to be completed before printing next message.
383 @var{min-time} specifies the minimum time in seconds to pass between
384 successive prints. It can be fractional. Depending on Emacs and
385 system capabilities, progress reporter may or may not respect this
386 last argument or do it with varying precision. Default value for
387 @var{min-change} is 1 (one percent), for @var{min-time}---0.2
390 This function calls @code{progress-reporter-update}, so the first
391 message is printed immediately.
394 @defun progress-reporter-update reporter value
395 This function does the main work of reporting progress of your
396 operation. It displays the message of @var{reporter}, followed by
397 progress percentage determined by @var{value}. If percentage is zero,
398 or close enough according to the @var{min-change} and @var{min-time}
399 arguments, then it is omitted from the output.
401 @var{reporter} must be the result of a call to
402 @code{make-progress-reporter}. @var{value} specifies the current
403 state of your operation and must be between @var{min-value} and
404 @var{max-value} (inclusive) as passed to
405 @code{make-progress-reporter}. For instance, if you scan a buffer,
406 then @var{value} should be the result of a call to @code{point}.
408 This function respects @var{min-change} and @var{min-time} as passed
409 to @code{make-progress-reporter} and so does not output new messages
410 on every invocation. It is thus very fast and normally you should not
411 try to reduce the number of calls to it: resulting overhead will most
412 likely negate your effort.
415 @defun progress-reporter-force-update reporter value &optional new-message
416 This function is similar to @code{progress-reporter-update} except
417 that it prints a message in the echo area unconditionally.
419 The first two arguments have the same meaning as for
420 @code{progress-reporter-update}. Optional @var{new-message} allows
421 you to change the message of the @var{reporter}. Since this functions
422 always updates the echo area, such a change will be immediately
423 presented to the user.
426 @defun progress-reporter-done reporter
427 This function should be called when the operation is finished. It
428 prints the message of @var{reporter} followed by word ``done'' in the
431 You should always call this function and not hope for
432 @code{progress-reporter-update} to print ``100%.'' Firstly, it may
433 never print it, there are many good reasons for this not to happen.
434 Secondly, ``done'' is more explicit.
437 @defmac dotimes-with-progress-reporter (var count [result]) message body@dots{}
438 This is a convenience macro that works the same way as @code{dotimes}
439 does, but also reports loop progress using the functions described
440 above. It allows you to save some typing.
442 You can rewrite the example in the beginning of this node using
446 (dotimes-with-progress-reporter
448 "Collecting some mana for Emacs..."
453 @node Logging Messages
454 @subsection Logging Messages in @samp{*Messages*}
455 @cindex logging echo-area messages
457 Almost all the messages displayed in the echo area are also recorded
458 in the @samp{*Messages*} buffer so that the user can refer back to
459 them. This includes all the messages that are output with
462 @defopt message-log-max
463 This variable specifies how many lines to keep in the @samp{*Messages*}
464 buffer. The value @code{t} means there is no limit on how many lines to
465 keep. The value @code{nil} disables message logging entirely. Here's
466 how to display a message and prevent it from being logged:
469 (let (message-log-max)
474 To make @samp{*Messages*} more convenient for the user, the logging
475 facility combines successive identical messages. It also combines
476 successive related messages for the sake of two cases: question
477 followed by answer, and a series of progress messages.
479 A ``question followed by an answer'' means two messages like the
480 ones produced by @code{y-or-n-p}: the first is @samp{@var{question}},
481 and the second is @samp{@var{question}...@var{answer}}. The first
482 message conveys no additional information beyond what's in the second,
483 so logging the second message discards the first from the log.
485 A ``series of progress messages'' means successive messages like
486 those produced by @code{make-progress-reporter}. They have the form
487 @samp{@var{base}...@var{how-far}}, where @var{base} is the same each
488 time, while @var{how-far} varies. Logging each message in the series
489 discards the previous one, provided they are consecutive.
491 The functions @code{make-progress-reporter} and @code{y-or-n-p}
492 don't have to do anything special to activate the message log
493 combination feature. It operates whenever two consecutive messages
494 are logged that share a common prefix ending in @samp{...}.
496 @node Echo Area Customization
497 @subsection Echo Area Customization
499 These variables control details of how the echo area works.
501 @defvar cursor-in-echo-area
502 This variable controls where the cursor appears when a message is
503 displayed in the echo area. If it is non-@code{nil}, then the cursor
504 appears at the end of the message. Otherwise, the cursor appears at
505 point---not in the echo area at all.
507 The value is normally @code{nil}; Lisp programs bind it to @code{t}
508 for brief periods of time.
511 @defvar echo-area-clear-hook
512 This normal hook is run whenever the echo area is cleared---either by
513 @code{(message nil)} or for any other reason.
516 @defvar echo-keystrokes
517 This variable determines how much time should elapse before command
518 characters echo. Its value must be an integer or floating point number,
520 number of seconds to wait before echoing. If the user types a prefix
521 key (such as @kbd{C-x}) and then delays this many seconds before
522 continuing, the prefix key is echoed in the echo area. (Once echoing
523 begins in a key sequence, all subsequent characters in the same key
524 sequence are echoed immediately.)
526 If the value is zero, then command input is not echoed.
529 @defvar message-truncate-lines
530 Normally, displaying a long message resizes the echo area to display
531 the entire message. But if the variable @code{message-truncate-lines}
532 is non-@code{nil}, the echo area does not resize, and the message is
533 truncated to fit it, as in Emacs 20 and before.
536 The variable @code{max-mini-window-height}, which specifies the
537 maximum height for resizing minibuffer windows, also applies to the
538 echo area (which is really a special use of the minibuffer window.
539 @xref{Minibuffer Misc}.
542 @section Reporting Warnings
545 @dfn{Warnings} are a facility for a program to inform the user of a
546 possible problem, but continue running.
549 * Warning Basics:: Warnings concepts and functions to report them.
550 * Warning Variables:: Variables programs bind to customize their warnings.
551 * Warning Options:: Variables users set to control display of warnings.
555 @subsection Warning Basics
556 @cindex severity level
558 Every warning has a textual message, which explains the problem for
559 the user, and a @dfn{severity level} which is a symbol. Here are the
560 possible severity levels, in order of decreasing severity, and their
565 A problem that will seriously impair Emacs operation soon
566 if you do not attend to it promptly.
568 A report of data or circumstances that are inherently wrong.
570 A report of data or circumstances that are not inherently wrong, but
571 raise suspicion of a possible problem.
573 A report of information that may be useful if you are debugging.
576 When your program encounters invalid input data, it can either
577 signal a Lisp error by calling @code{error} or @code{signal} or report
578 a warning with severity @code{:error}. Signaling a Lisp error is the
579 easiest thing to do, but it means the program cannot continue
580 processing. If you want to take the trouble to implement a way to
581 continue processing despite the bad data, then reporting a warning of
582 severity @code{:error} is the right way to inform the user of the
583 problem. For instance, the Emacs Lisp byte compiler can report an
584 error that way and continue compiling other functions. (If the
585 program signals a Lisp error and then handles it with
586 @code{condition-case}, the user won't see the error message; it could
587 show the message to the user by reporting it as a warning.)
590 Each warning has a @dfn{warning type} to classify it. The type is a
591 list of symbols. The first symbol should be the custom group that you
592 use for the program's user options. For example, byte compiler
593 warnings use the warning type @code{(bytecomp)}. You can also
594 subcategorize the warnings, if you wish, by using more symbols in the
597 @defun display-warning type message &optional level buffer-name
598 This function reports a warning, using @var{message} as the message
599 and @var{type} as the warning type. @var{level} should be the
600 severity level, with @code{:warning} being the default.
602 @var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
603 for logging the warning. By default, it is @samp{*Warnings*}.
606 @defun lwarn type level message &rest args
607 This function reports a warning using the value of @code{(format
608 @var{message} @var{args}...)} as the message. In other respects it is
609 equivalent to @code{display-warning}.
612 @defun warn message &rest args
613 This function reports a warning using the value of @code{(format
614 @var{message} @var{args}...)} as the message, @code{(emacs)} as the
615 type, and @code{:warning} as the severity level. It exists for
616 compatibility only; we recommend not using it, because you should
617 specify a specific warning type.
620 @node Warning Variables
621 @subsection Warning Variables
623 Programs can customize how their warnings appear by binding
624 the variables described in this section.
626 @defvar warning-levels
627 This list defines the meaning and severity order of the warning
628 severity levels. Each element defines one severity level,
629 and they are arranged in order of decreasing severity.
631 Each element has the form @code{(@var{level} @var{string}
632 @var{function})}, where @var{level} is the severity level it defines.
633 @var{string} specifies the textual description of this level.
634 @var{string} should use @samp{%s} to specify where to put the warning
635 type information, or it can omit the @samp{%s} so as not to include
638 The optional @var{function}, if non-@code{nil}, is a function to call
639 with no arguments, to get the user's attention.
641 Normally you should not change the value of this variable.
644 @defvar warning-prefix-function
645 If non-@code{nil}, the value is a function to generate prefix text for
646 warnings. Programs can bind the variable to a suitable function.
647 @code{display-warning} calls this function with the warnings buffer
648 current, and the function can insert text in it. That text becomes
649 the beginning of the warning message.
651 The function is called with two arguments, the severity level and its
652 entry in @code{warning-levels}. It should return a list to use as the
653 entry (this value need not be an actual member of
654 @code{warning-levels}). By constructing this value, the function can
655 change the severity of the warning, or specify different handling for
656 a given severity level.
658 If the variable's value is @code{nil} then there is no function
662 @defvar warning-series
663 Programs can bind this variable to @code{t} to say that the next
664 warning should begin a series. When several warnings form a series,
665 that means to leave point on the first warning of the series, rather
666 than keep moving it for each warning so that it appears on the last one.
667 The series ends when the local binding is unbound and
668 @code{warning-series} becomes @code{nil} again.
670 The value can also be a symbol with a function definition. That is
671 equivalent to @code{t}, except that the next warning will also call
672 the function with no arguments with the warnings buffer current. The
673 function can insert text which will serve as a header for the series
676 Once a series has begun, the value is a marker which points to the
677 buffer position in the warnings buffer of the start of the series.
679 The variable's normal value is @code{nil}, which means to handle
680 each warning separately.
683 @defvar warning-fill-prefix
684 When this variable is non-@code{nil}, it specifies a fill prefix to
685 use for filling each warning's text.
688 @defvar warning-type-format
689 This variable specifies the format for displaying the warning type
690 in the warning message. The result of formatting the type this way
691 gets included in the message under the control of the string in the
692 entry in @code{warning-levels}. The default value is @code{" (%s)"}.
693 If you bind it to @code{""} then the warning type won't appear at
697 @node Warning Options
698 @subsection Warning Options
700 These variables are used by users to control what happens
701 when a Lisp program reports a warning.
703 @defopt warning-minimum-level
704 This user option specifies the minimum severity level that should be
705 shown immediately to the user. The default is @code{:warning}, which
706 means to immediately display all warnings except @code{:debug}
710 @defopt warning-minimum-log-level
711 This user option specifies the minimum severity level that should be
712 logged in the warnings buffer. The default is @code{:warning}, which
713 means to log all warnings except @code{:debug} warnings.
716 @defopt warning-suppress-types
717 This list specifies which warning types should not be displayed
718 immediately for the user. Each element of the list should be a list
719 of symbols. If its elements match the first elements in a warning
720 type, then that warning is not displayed immediately.
723 @defopt warning-suppress-log-types
724 This list specifies which warning types should not be logged in the
725 warnings buffer. Each element of the list should be a list of
726 symbols. If it matches the first few elements in a warning type, then
727 that warning is not logged.
731 @section Invisible Text
733 @cindex invisible text
734 You can make characters @dfn{invisible}, so that they do not appear on
735 the screen, with the @code{invisible} property. This can be either a
736 text property (@pxref{Text Properties}) or a property of an overlay
737 (@pxref{Overlays}). Cursor motion also partly ignores these
738 characters; if the command loop finds point within them, it moves
739 point to the other side of them.
741 In the simplest case, any non-@code{nil} @code{invisible} property makes
742 a character invisible. This is the default case---if you don't alter
743 the default value of @code{buffer-invisibility-spec}, this is how the
744 @code{invisible} property works. You should normally use @code{t}
745 as the value of the @code{invisible} property if you don't plan
746 to set @code{buffer-invisibility-spec} yourself.
748 More generally, you can use the variable @code{buffer-invisibility-spec}
749 to control which values of the @code{invisible} property make text
750 invisible. This permits you to classify the text into different subsets
751 in advance, by giving them different @code{invisible} values, and
752 subsequently make various subsets visible or invisible by changing the
753 value of @code{buffer-invisibility-spec}.
755 Controlling visibility with @code{buffer-invisibility-spec} is
756 especially useful in a program to display the list of entries in a
757 database. It permits the implementation of convenient filtering
758 commands to view just a part of the entries in the database. Setting
759 this variable is very fast, much faster than scanning all the text in
760 the buffer looking for properties to change.
762 @defvar buffer-invisibility-spec
763 This variable specifies which kinds of @code{invisible} properties
764 actually make a character invisible. Setting this variable makes it
769 A character is invisible if its @code{invisible} property is
770 non-@code{nil}. This is the default.
773 Each element of the list specifies a criterion for invisibility; if a
774 character's @code{invisible} property fits any one of these criteria,
775 the character is invisible. The list can have two kinds of elements:
779 A character is invisible if its @code{invisible} property value
780 is @var{atom} or if it is a list with @var{atom} as a member.
782 @item (@var{atom} . t)
783 A character is invisible if its @code{invisible} property value is
784 @var{atom} or if it is a list with @var{atom} as a member. Moreover,
785 a sequence of such characters displays as an ellipsis.
790 Two functions are specifically provided for adding elements to
791 @code{buffer-invisibility-spec} and removing elements from it.
793 @defun add-to-invisibility-spec element
794 This function adds the element @var{element} to
795 @code{buffer-invisibility-spec}. If @code{buffer-invisibility-spec}
796 was @code{t}, it changes to a list, @code{(t)}, so that text whose
797 @code{invisible} property is @code{t} remains invisible.
800 @defun remove-from-invisibility-spec element
801 This removes the element @var{element} from
802 @code{buffer-invisibility-spec}. This does nothing if @var{element}
806 A convention for use of @code{buffer-invisibility-spec} is that a
807 major mode should use the mode's own name as an element of
808 @code{buffer-invisibility-spec} and as the value of the
809 @code{invisible} property:
812 ;; @r{If you want to display an ellipsis:}
813 (add-to-invisibility-spec '(my-symbol . t))
814 ;; @r{If you don't want ellipsis:}
815 (add-to-invisibility-spec 'my-symbol)
817 (overlay-put (make-overlay beginning end)
818 'invisible 'my-symbol)
820 ;; @r{When done with the overlays:}
821 (remove-from-invisibility-spec '(my-symbol . t))
822 ;; @r{Or respectively:}
823 (remove-from-invisibility-spec 'my-symbol)
826 @vindex line-move-ignore-invisible
827 Ordinarily, functions that operate on text or move point do not care
828 whether the text is invisible. The user-level line motion commands
829 explicitly ignore invisible newlines if
830 @code{line-move-ignore-invisible} is non-@code{nil} (the default), but
831 only because they are explicitly programmed to do so.
833 However, if a command ends with point inside or immediately before
834 invisible text, the main editing loop moves point further forward or
835 further backward (in the same direction that the command already moved
836 it) until that condition is no longer true. Thus, if the command
837 moved point back into an invisible range, Emacs moves point back to
838 the beginning of that range, and then back one more character. If the
839 command moved point forward into an invisible range, Emacs moves point
840 forward up to the first visible character that follows the invisible
843 Incremental search can make invisible overlays visible temporarily
844 and/or permanently when a match includes invisible text. To enable
845 this, the overlay should have a non-@code{nil}
846 @code{isearch-open-invisible} property. The property value should be a
847 function to be called with the overlay as an argument. This function
848 should make the overlay visible permanently; it is used when the match
849 overlaps the overlay on exit from the search.
851 During the search, such overlays are made temporarily visible by
852 temporarily modifying their invisible and intangible properties. If you
853 want this to be done differently for a certain overlay, give it an
854 @code{isearch-open-invisible-temporary} property which is a function.
855 The function is called with two arguments: the first is the overlay, and
856 the second is @code{nil} to make the overlay visible, or @code{t} to
857 make it invisible again.
859 @node Selective Display
860 @section Selective Display
861 @c @cindex selective display Duplicates selective-display
863 @dfn{Selective display} refers to a pair of related features for
864 hiding certain lines on the screen.
866 The first variant, explicit selective display, is designed for use
867 in a Lisp program: it controls which lines are hidden by altering the
868 text. This kind of hiding in some ways resembles the effect of the
869 @code{invisible} property (@pxref{Invisible Text}), but the two
870 features are different and do not work the same way.
872 In the second variant, the choice of lines to hide is made
873 automatically based on indentation. This variant is designed to be a
876 The way you control explicit selective display is by replacing a
877 newline (control-j) with a carriage return (control-m). The text that
878 was formerly a line following that newline is now hidden. Strictly
879 speaking, it is temporarily no longer a line at all, since only
880 newlines can separate lines; it is now part of the previous line.
882 Selective display does not directly affect editing commands. For
883 example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly
884 into hidden text. However, the replacement of newline characters with
885 carriage return characters affects some editing commands. For
886 example, @code{next-line} skips hidden lines, since it searches only
887 for newlines. Modes that use selective display can also define
888 commands that take account of the newlines, or that control which
889 parts of the text are hidden.
891 When you write a selectively displayed buffer into a file, all the
892 control-m's are output as newlines. This means that when you next read
893 in the file, it looks OK, with nothing hidden. The selective display
894 effect is seen only within Emacs.
896 @defvar selective-display
897 This buffer-local variable enables selective display. This means that
898 lines, or portions of lines, may be made hidden.
902 If the value of @code{selective-display} is @code{t}, then the character
903 control-m marks the start of hidden text; the control-m, and the rest
904 of the line following it, are not displayed. This is explicit selective
908 If the value of @code{selective-display} is a positive integer, then
909 lines that start with more than that many columns of indentation are not
913 When some portion of a buffer is hidden, the vertical movement
914 commands operate as if that portion did not exist, allowing a single
915 @code{next-line} command to skip any number of hidden lines.
916 However, character movement commands (such as @code{forward-char}) do
917 not skip the hidden portion, and it is possible (if tricky) to insert
918 or delete text in an hidden portion.
920 In the examples below, we show the @emph{display appearance} of the
921 buffer @code{foo}, which changes with the value of
922 @code{selective-display}. The @emph{contents} of the buffer do not
927 (setq selective-display nil)
930 ---------- Buffer: foo ----------
937 ---------- Buffer: foo ----------
941 (setq selective-display 2)
944 ---------- Buffer: foo ----------
949 ---------- Buffer: foo ----------
954 @defvar selective-display-ellipses
955 If this buffer-local variable is non-@code{nil}, then Emacs displays
956 @samp{@dots{}} at the end of a line that is followed by hidden text.
957 This example is a continuation of the previous one.
961 (setq selective-display-ellipses t)
964 ---------- Buffer: foo ----------
969 ---------- Buffer: foo ----------
973 You can use a display table to substitute other text for the ellipsis
974 (@samp{@dots{}}). @xref{Display Tables}.
977 @node Temporary Displays
978 @section Temporary Displays
980 Temporary displays are used by Lisp programs to put output into a
981 buffer and then present it to the user for perusal rather than for
982 editing. Many help commands use this feature.
984 @defspec with-output-to-temp-buffer buffer-name forms@dots{}
985 This function executes @var{forms} while arranging to insert any output
986 they print into the buffer named @var{buffer-name}, which is first
987 created if necessary, and put into Help mode. Finally, the buffer is
988 displayed in some window, but not selected.
990 If the @var{forms} do not change the major mode in the output buffer,
991 so that it is still Help mode at the end of their execution, then
992 @code{with-output-to-temp-buffer} makes this buffer read-only at the
993 end, and also scans it for function and variable names to make them
994 into clickable cross-references. @xref{Docstring hyperlinks, , Tips
995 for Documentation Strings}, in particular the item on hyperlinks in
996 documentation strings, for more details.
998 The string @var{buffer-name} specifies the temporary buffer, which
999 need not already exist. The argument must be a string, not a buffer.
1000 The buffer is erased initially (with no questions asked), and it is
1001 marked as unmodified after @code{with-output-to-temp-buffer} exits.
1003 @code{with-output-to-temp-buffer} binds @code{standard-output} to the
1004 temporary buffer, then it evaluates the forms in @var{forms}. Output
1005 using the Lisp output functions within @var{forms} goes by default to
1006 that buffer (but screen display and messages in the echo area, although
1007 they are ``output'' in the general sense of the word, are not affected).
1008 @xref{Output Functions}.
1010 Several hooks are available for customizing the behavior
1011 of this construct; they are listed below.
1013 The value of the last form in @var{forms} is returned.
1017 ---------- Buffer: foo ----------
1018 This is the contents of foo.
1019 ---------- Buffer: foo ----------
1023 (with-output-to-temp-buffer "foo"
1025 (print standard-output))
1026 @result{} #<buffer foo>
1028 ---------- Buffer: foo ----------
1033 ---------- Buffer: foo ----------
1038 @defvar temp-buffer-show-function
1039 If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
1040 calls it as a function to do the job of displaying a help buffer. The
1041 function gets one argument, which is the buffer it should display.
1043 It is a good idea for this function to run @code{temp-buffer-show-hook}
1044 just as @code{with-output-to-temp-buffer} normally would, inside of
1045 @code{save-selected-window} and with the chosen window and buffer
1049 @defvar temp-buffer-setup-hook
1050 This normal hook is run by @code{with-output-to-temp-buffer} before
1051 evaluating @var{body}. When the hook runs, the temporary buffer is
1052 current. This hook is normally set up with a function to put the
1053 buffer in Help mode.
1056 @defvar temp-buffer-show-hook
1057 This normal hook is run by @code{with-output-to-temp-buffer} after
1058 displaying the temporary buffer. When the hook runs, the temporary buffer
1059 is current, and the window it was displayed in is selected. This hook
1060 is normally set up with a function to make the buffer read only, and
1061 find function names and variable names in it, provided the major mode
1065 @defun momentary-string-display string position &optional char message
1066 This function momentarily displays @var{string} in the current buffer at
1067 @var{position}. It has no effect on the undo list or on the buffer's
1068 modification status.
1070 The momentary display remains until the next input event. If the next
1071 input event is @var{char}, @code{momentary-string-display} ignores it
1072 and returns. Otherwise, that event remains buffered for subsequent use
1073 as input. Thus, typing @var{char} will simply remove the string from
1074 the display, while typing (say) @kbd{C-f} will remove the string from
1075 the display and later (presumably) move point forward. The argument
1076 @var{char} is a space by default.
1078 The return value of @code{momentary-string-display} is not meaningful.
1080 If the string @var{string} does not contain control characters, you can
1081 do the same job in a more general way by creating (and then subsequently
1082 deleting) an overlay with a @code{before-string} property.
1083 @xref{Overlay Properties}.
1085 If @var{message} is non-@code{nil}, it is displayed in the echo area
1086 while @var{string} is displayed in the buffer. If it is @code{nil}, a
1087 default message says to type @var{char} to continue.
1089 In this example, point is initially located at the beginning of the
1094 ---------- Buffer: foo ----------
1095 This is the contents of foo.
1096 @point{}Second line.
1097 ---------- Buffer: foo ----------
1101 (momentary-string-display
1102 "**** Important Message! ****"
1104 "Type RET when done reading")
1109 ---------- Buffer: foo ----------
1110 This is the contents of foo.
1111 **** Important Message! ****Second line.
1112 ---------- Buffer: foo ----------
1114 ---------- Echo Area ----------
1115 Type RET when done reading
1116 ---------- Echo Area ----------
1125 You can use @dfn{overlays} to alter the appearance of a buffer's text on
1126 the screen, for the sake of presentation features. An overlay is an
1127 object that belongs to a particular buffer, and has a specified
1128 beginning and end. It also has properties that you can examine and set;
1129 these affect the display of the text within the overlay.
1131 An overlay uses markers to record its beginning and end; thus,
1132 editing the text of the buffer adjusts the beginning and end of each
1133 overlay so that it stays with the text. When you create the overlay,
1134 you can specify whether text inserted at the beginning should be
1135 inside the overlay or outside, and likewise for the end of the overlay.
1138 * Managing Overlays:: Creating and moving overlays.
1139 * Overlay Properties:: How to read and set properties.
1140 What properties do to the screen display.
1141 * Finding Overlays:: Searching for overlays.
1144 @node Managing Overlays
1145 @subsection Managing Overlays
1147 This section describes the functions to create, delete and move
1148 overlays, and to examine their contents. Overlay changes are not
1149 recorded in the buffer's undo list, since the overlays are not
1150 part of the buffer's contents.
1152 @defun overlayp object
1153 This function returns @code{t} if @var{object} is an overlay.
1156 @defun make-overlay start end &optional buffer front-advance rear-advance
1157 This function creates and returns an overlay that belongs to
1158 @var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
1159 and @var{end} must specify buffer positions; they may be integers or
1160 markers. If @var{buffer} is omitted, the overlay is created in the
1163 The arguments @var{front-advance} and @var{rear-advance} specify the
1164 marker insertion type for the start of the overlay and for the end of
1165 the overlay, respectively. @xref{Marker Insertion Types}. If they
1166 are both @code{nil}, the default, then the overlay extends to include
1167 any text inserted at the beginning, but not text inserted at the end.
1168 If @var{front-advance} is non-@code{nil}, text inserted at the
1169 beginning of the overlay is excluded from the overlay. If
1170 @var{rear-advance} is non-@code{nil}, text inserted at the end of the
1171 overlay is included in the overlay.
1174 @defun overlay-start overlay
1175 This function returns the position at which @var{overlay} starts,
1179 @defun overlay-end overlay
1180 This function returns the position at which @var{overlay} ends,
1184 @defun overlay-buffer overlay
1185 This function returns the buffer that @var{overlay} belongs to. It
1186 returns @code{nil} if @var{overlay} has been deleted.
1189 @defun delete-overlay overlay
1190 This function deletes @var{overlay}. The overlay continues to exist as
1191 a Lisp object, and its property list is unchanged, but it ceases to be
1192 attached to the buffer it belonged to, and ceases to have any effect on
1195 A deleted overlay is not permanently disconnected. You can give it a
1196 position in a buffer again by calling @code{move-overlay}.
1199 @defun move-overlay overlay start end &optional buffer
1200 This function moves @var{overlay} to @var{buffer}, and places its bounds
1201 at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
1202 must specify buffer positions; they may be integers or markers.
1204 If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
1205 was already associated with; if @var{overlay} was deleted, it goes into
1208 The return value is @var{overlay}.
1210 This is the only valid way to change the endpoints of an overlay. Do
1211 not try modifying the markers in the overlay by hand, as that fails to
1212 update other vital data structures and can cause some overlays to be
1216 @defun remove-overlays &optional start end name value
1217 This function removes all the overlays between @var{start} and
1218 @var{end} whose property @var{name} has the value @var{value}. It can
1219 move the endpoints of the overlays in the region, or split them.
1221 If @var{name} is omitted or @code{nil}, it means to delete all overlays in
1222 the specified region. If @var{start} and/or @var{end} are omitted or
1223 @code{nil}, that means the beginning and end of the buffer respectively.
1224 Therefore, @code{(remove-overlays)} removes all the overlays in the
1228 Here are some examples:
1231 ;; @r{Create an overlay.}
1232 (setq foo (make-overlay 1 10))
1233 @result{} #<overlay from 1 to 10 in display.texi>
1238 (overlay-buffer foo)
1239 @result{} #<buffer display.texi>
1240 ;; @r{Give it a property we can check later.}
1241 (overlay-put foo 'happy t)
1243 ;; @r{Verify the property is present.}
1244 (overlay-get foo 'happy)
1246 ;; @r{Move the overlay.}
1247 (move-overlay foo 5 20)
1248 @result{} #<overlay from 5 to 20 in display.texi>
1253 ;; @r{Delete the overlay.}
1254 (delete-overlay foo)
1256 ;; @r{Verify it is deleted.}
1258 @result{} #<overlay in no buffer>
1259 ;; @r{A deleted overlay has no position.}
1264 (overlay-buffer foo)
1266 ;; @r{Undelete the overlay.}
1267 (move-overlay foo 1 20)
1268 @result{} #<overlay from 1 to 20 in display.texi>
1269 ;; @r{Verify the results.}
1274 (overlay-buffer foo)
1275 @result{} #<buffer display.texi>
1276 ;; @r{Moving and deleting the overlay does not change its properties.}
1277 (overlay-get foo 'happy)
1281 Emacs stores the overlays of each buffer in two lists, divided
1282 around an arbitrary ``center position.'' One list extends backwards
1283 through the buffer from that center position, and the other extends
1284 forwards from that center position. The center position can be anywhere
1287 @defun overlay-recenter pos
1288 This function recenters the overlays of the current buffer around
1289 position @var{pos}. That makes overlay lookup faster for positions
1290 near @var{pos}, but slower for positions far away from @var{pos}.
1293 A loop that scans the buffer forwards, creating overlays, can run
1294 faster if you do @code{(overlay-recenter (point-max))} first.
1296 @node Overlay Properties
1297 @subsection Overlay Properties
1299 Overlay properties are like text properties in that the properties that
1300 alter how a character is displayed can come from either source. But in
1301 most respects they are different. @xref{Text Properties}, for comparison.
1303 Text properties are considered a part of the text; overlays and
1304 their properties are specifically considered not to be part of the
1305 text. Thus, copying text between various buffers and strings
1306 preserves text properties, but does not try to preserve overlays.
1307 Changing a buffer's text properties marks the buffer as modified,
1308 while moving an overlay or changing its properties does not. Unlike
1309 text property changes, overlay property changes are not recorded in
1310 the buffer's undo list.
1312 Since more than one overlay can specify a property value for the
1313 same character, Emacs lets you specify a priority value of each
1314 overlay. You should not make assumptions about which overlay will
1315 prevail when there is a conflict and they have the same priority.
1317 These functions read and set the properties of an overlay:
1319 @defun overlay-get overlay prop
1320 This function returns the value of property @var{prop} recorded in
1321 @var{overlay}, if any. If @var{overlay} does not record any value for
1322 that property, but it does have a @code{category} property which is a
1323 symbol, that symbol's @var{prop} property is used. Otherwise, the value
1327 @defun overlay-put overlay prop value
1328 This function sets the value of property @var{prop} recorded in
1329 @var{overlay} to @var{value}. It returns @var{value}.
1332 @defun overlay-properties overlay
1333 This returns a copy of the property list of @var{overlay}.
1336 See also the function @code{get-char-property} which checks both
1337 overlay properties and text properties for a given character.
1338 @xref{Examining Properties}.
1340 Many overlay properties have special meanings; here is a table
1345 @kindex priority @r{(overlay property)}
1346 This property's value (which should be a nonnegative integer number)
1347 determines the priority of the overlay. No priority, or @code{nil},
1350 The priority matters when two or more overlays cover the same
1351 character and both specify the same property; the one whose
1352 @code{priority} value is larger overrides the other. For the
1353 @code{face} property, the higher priority overlay's value does not
1354 completely override the other value; instead, its face attributes
1355 override the face attributes of the lower priority @code{face}
1358 Currently, all overlays take priority over text properties. Please
1359 avoid using negative priority values, as we have not yet decided just
1360 what they should mean.
1363 @kindex window @r{(overlay property)}
1364 If the @code{window} property is non-@code{nil}, then the overlay
1365 applies only on that window.
1368 @kindex category @r{(overlay property)}
1369 If an overlay has a @code{category} property, we call it the
1370 @dfn{category} of the overlay. It should be a symbol. The properties
1371 of the symbol serve as defaults for the properties of the overlay.
1374 @kindex face @r{(overlay property)}
1375 This property controls the way text is displayed---for example, which
1376 font and which colors. @xref{Faces}, for more information.
1378 In the simplest case, the value is a face name. It can also be a list;
1379 then each element can be any of these possibilities:
1383 A face name (a symbol or string).
1386 A property list of face attributes. This has the form (@var{keyword}
1387 @var{value} @dots{}), where each @var{keyword} is a face attribute
1388 name and @var{value} is a meaningful value for that attribute. With
1389 this feature, you do not need to create a face each time you want to
1390 specify a particular attribute for certain text. @xref{Face
1394 A cons cell, either of the form @code{(foreground-color . @var{color-name})} or
1395 @code{(background-color . @var{color-name})}. These elements specify
1396 just the foreground color or just the background color.
1398 @code{(foreground-color . @var{color-name})} has the same effect as
1399 @code{(:foreground @var{color-name})}; likewise for the background.
1403 @kindex mouse-face @r{(overlay property)}
1404 This property is used instead of @code{face} when the mouse is within
1405 the range of the overlay.
1408 @kindex display @r{(overlay property)}
1409 This property activates various features that change the
1410 way text is displayed. For example, it can make text appear taller
1411 or shorter, higher or lower, wider or narrower, or replaced with an image.
1412 @xref{Display Property}.
1415 @kindex help-echo @r{(overlay property)}
1416 If an overlay has a @code{help-echo} property, then when you move the
1417 mouse onto the text in the overlay, Emacs displays a help string in the
1418 echo area, or in the tooltip window. For details see @ref{Text
1421 @item modification-hooks
1422 @kindex modification-hooks @r{(overlay property)}
1423 This property's value is a list of functions to be called if any
1424 character within the overlay is changed or if text is inserted strictly
1427 The hook functions are called both before and after each change.
1428 If the functions save the information they receive, and compare notes
1429 between calls, they can determine exactly what change has been made
1432 When called before a change, each function receives four arguments: the
1433 overlay, @code{nil}, and the beginning and end of the text range to be
1436 When called after a change, each function receives five arguments: the
1437 overlay, @code{t}, the beginning and end of the text range just
1438 modified, and the length of the pre-change text replaced by that range.
1439 (For an insertion, the pre-change length is zero; for a deletion, that
1440 length is the number of characters deleted, and the post-change
1441 beginning and end are equal.)
1443 If these functions modify the buffer, they should bind
1444 @code{inhibit-modification-hooks} to @code{t} around doing so, to
1445 avoid confusing the internal mechanism that calls these hooks.
1447 Text properties also support the @code{modification-hooks} property,
1448 but the details are somewhat different (@pxref{Special Properties}).
1450 @item insert-in-front-hooks
1451 @kindex insert-in-front-hooks @r{(overlay property)}
1452 This property's value is a list of functions to be called before and
1453 after inserting text right at the beginning of the overlay. The calling
1454 conventions are the same as for the @code{modification-hooks} functions.
1456 @item insert-behind-hooks
1457 @kindex insert-behind-hooks @r{(overlay property)}
1458 This property's value is a list of functions to be called before and
1459 after inserting text right at the end of the overlay. The calling
1460 conventions are the same as for the @code{modification-hooks} functions.
1463 @kindex invisible @r{(overlay property)}
1464 The @code{invisible} property can make the text in the overlay
1465 invisible, which means that it does not appear on the screen.
1466 @xref{Invisible Text}, for details.
1469 @kindex intangible @r{(overlay property)}
1470 The @code{intangible} property on an overlay works just like the
1471 @code{intangible} text property. @xref{Special Properties}, for details.
1473 @item isearch-open-invisible
1474 This property tells incremental search how to make an invisible overlay
1475 visible, permanently, if the final match overlaps it. @xref{Invisible
1478 @item isearch-open-invisible-temporary
1479 This property tells incremental search how to make an invisible overlay
1480 visible, temporarily, during the search. @xref{Invisible Text}.
1483 @kindex before-string @r{(overlay property)}
1484 This property's value is a string to add to the display at the beginning
1485 of the overlay. The string does not appear in the buffer in any
1486 sense---only on the screen.
1489 @kindex after-string @r{(overlay property)}
1490 This property's value is a string to add to the display at the end of
1491 the overlay. The string does not appear in the buffer in any
1492 sense---only on the screen.
1495 @kindex evaporate @r{(overlay property)}
1496 If this property is non-@code{nil}, the overlay is deleted automatically
1497 if it becomes empty (i.e., if its length becomes zero). If you give
1498 an empty overlay a non-@code{nil} @code{evaporate} property, that deletes
1502 @cindex keymap of character (and overlays)
1503 @kindex local-map @r{(overlay property)}
1504 If this property is non-@code{nil}, it specifies a keymap for a portion
1505 of the text. The property's value replaces the buffer's local map, when
1506 the character after point is within the overlay. @xref{Active Keymaps}.
1509 @kindex keymap @r{(overlay property)}
1510 The @code{keymap} property is similar to @code{local-map} but overrides the
1511 buffer's local map (and the map specified by the @code{local-map}
1512 property) rather than replacing it.
1515 @node Finding Overlays
1516 @subsection Searching for Overlays
1518 @defun overlays-at pos
1519 This function returns a list of all the overlays that cover the
1520 character at position @var{pos} in the current buffer. The list is in
1521 no particular order. An overlay contains position @var{pos} if it
1522 begins at or before @var{pos}, and ends after @var{pos}.
1524 To illustrate usage, here is a Lisp function that returns a list of the
1525 overlays that specify property @var{prop} for the character at point:
1528 (defun find-overlays-specifying (prop)
1529 (let ((overlays (overlays-at (point)))
1532 (let ((overlay (car overlays)))
1533 (if (overlay-get overlay prop)
1534 (setq found (cons overlay found))))
1535 (setq overlays (cdr overlays)))
1540 @defun overlays-in beg end
1541 This function returns a list of the overlays that overlap the region
1542 @var{beg} through @var{end}. ``Overlap'' means that at least one
1543 character is contained within the overlay and also contained within the
1544 specified region; however, empty overlays are included in the result if
1545 they are located at @var{beg}, or strictly between @var{beg} and @var{end}.
1548 @defun next-overlay-change pos
1549 This function returns the buffer position of the next beginning or end
1550 of an overlay, after @var{pos}. If there is none, it returns
1554 @defun previous-overlay-change pos
1555 This function returns the buffer position of the previous beginning or
1556 end of an overlay, before @var{pos}. If there is none, it returns
1560 As an example, here's a simplified (and inefficient) version of the
1561 primitive function @code{next-single-char-property-change}
1562 (@pxref{Property Search}). It searches forward from position
1563 @var{pos} for the next position where the value of a given property
1564 @code{prop}, as obtained from either overlays or text properties,
1568 (defun next-single-char-property-change (position prop)
1570 (goto-char position)
1571 (let ((propval (get-char-property (point) prop)))
1572 (while (and (not (eobp))
1573 (eq (get-char-property (point) prop) propval))
1574 (goto-char (min (next-overlay-change (point))
1575 (next-single-property-change (point) prop)))))
1582 Since not all characters have the same width, these functions let you
1583 check the width of a character. @xref{Primitive Indent}, and
1584 @ref{Screen Lines}, for related functions.
1586 @defun char-width char
1587 This function returns the width in columns of the character @var{char},
1588 if it were displayed in the current buffer and the selected window.
1591 @defun string-width string
1592 This function returns the width in columns of the string @var{string},
1593 if it were displayed in the current buffer and the selected window.
1596 @defun truncate-string-to-width string width &optional start-column padding ellipsis
1597 This function returns the part of @var{string} that fits within
1598 @var{width} columns, as a new string.
1600 If @var{string} does not reach @var{width}, then the result ends where
1601 @var{string} ends. If one multi-column character in @var{string}
1602 extends across the column @var{width}, that character is not included in
1603 the result. Thus, the result can fall short of @var{width} but cannot
1606 The optional argument @var{start-column} specifies the starting column.
1607 If this is non-@code{nil}, then the first @var{start-column} columns of
1608 the string are omitted from the value. If one multi-column character in
1609 @var{string} extends across the column @var{start-column}, that
1610 character is not included.
1612 The optional argument @var{padding}, if non-@code{nil}, is a padding
1613 character added at the beginning and end of the result string, to extend
1614 it to exactly @var{width} columns. The padding character is used at the
1615 end of the result if it falls short of @var{width}. It is also used at
1616 the beginning of the result if one multi-column character in
1617 @var{string} extends across the column @var{start-column}.
1619 If @var{ellipsis} is non-@code{nil}, it should be a string which will
1620 replace the end of @var{str} (including any padding) if it extends
1621 beyond @var{end-column}, unless the display width of @var{str} is
1622 equal to or less than the display width of @var{ellipsis}. If
1623 @var{ellipsis} is non-@code{nil} and not a string, it stands for
1627 (truncate-string-to-width "\tab\t" 12 4)
1629 (truncate-string-to-width "\tab\t" 12 4 ?\s)
1635 @section Line Height
1638 The total height of each display line consists of the height of the
1639 contents of the line, plus optional additional vertical line spacing
1640 above or below the display line.
1642 The height of the line contents is the maximum height of any
1643 character or image on that display line, including the final newline
1644 if there is one. (A display line that is continued doesn't include a
1645 final newline.) That is the default line height, if you do nothing to
1646 specify a greater height. (In the most common case, this equals the
1647 height of the default frame font.)
1649 There are several ways to explicitly specify a larger line height,
1650 either by specifying an absolute height for the display line, or by
1651 specifying vertical space. However, no matter what you specify, the
1652 actual line height can never be less than the default.
1654 @kindex line-height @r{(text property)}
1655 A newline can have a @code{line-height} text or overlay property
1656 that controls the total height of the display line ending in that
1659 If the property value is @code{t}, the newline character has no
1660 effect on the displayed height of the line---the visible contents
1661 alone determine the height. This is useful for tiling small images
1662 (or image slices) without adding blank areas between the images.
1664 If the property value is a list of the form @code{(@var{height}
1665 @var{total})}, that adds extra space @emph{below} the display line.
1666 First Emacs uses @var{height} as a height spec to control extra space
1667 @emph{above} the line; then it adds enough space @emph{below} the line
1668 to bring the total line height up to @var{total}. In this case, the
1669 other ways to specify the line spacing are ignored.
1671 Any other kind of property value is a height spec, which translates
1672 into a number---the specified line height. There are several ways to
1673 write a height spec; here's how each of them translates into a number:
1677 If the height spec is a positive integer, the height value is that integer.
1679 If the height spec is a float, @var{float}, the numeric height value
1680 is @var{float} times the frame's default line height.
1681 @item (@var{face} . @var{ratio})
1682 If the height spec is a cons of the format shown, the numeric height
1683 is @var{ratio} times the height of face @var{face}. @var{ratio} can
1684 be any type of number, or @code{nil} which means a ratio of 1.
1685 If @var{face} is @code{t}, it refers to the current face.
1686 @item (nil . @var{ratio})
1687 If the height spec is a cons of the format shown, the numeric height
1688 is @var{ratio} times the height of the contents of the line.
1691 Thus, any valid height spec determines the height in pixels, one way
1692 or another. If the line contents' height is less than that, Emacs
1693 adds extra vertical space above the line to achieve the specified
1696 If you don't specify the @code{line-height} property, the line's
1697 height consists of the contents' height plus the line spacing.
1698 There are several ways to specify the line spacing for different
1699 parts of Emacs text.
1701 @vindex default-line-spacing
1702 You can specify the line spacing for all lines in a frame with the
1703 @code{line-spacing} frame parameter (@pxref{Layout Parameters}).
1704 However, if the variable @code{default-line-spacing} is
1705 non-@code{nil}, it overrides the frame's @code{line-spacing}
1706 parameter. An integer value specifies the number of pixels put below
1707 lines on graphical displays. A floating point number specifies the
1708 spacing relative to the frame's default line height.
1710 @vindex line-spacing
1711 You can specify the line spacing for all lines in a buffer via the
1712 buffer-local @code{line-spacing} variable. An integer value specifies
1713 the number of pixels put below lines on graphical displays. A floating
1714 point number specifies the spacing relative to the default frame line
1715 height. This overrides line spacings specified for the frame.
1717 @kindex line-spacing @r{(text property)}
1718 Finally, a newline can have a @code{line-spacing} text or overlay
1719 property that overrides the default frame line spacing and the buffer
1720 local @code{line-spacing} variable, for the display line ending in
1723 One way or another, these mechanisms specify a Lisp value for the
1724 spacing of each line. The value is a height spec, and it translates
1725 into a Lisp value as described above. However, in this case the
1726 numeric height value specifies the line spacing, rather than the line
1733 A @dfn{face} is a named collection of graphical attributes: font
1734 family, foreground color, background color, optional underlining, and
1735 many others. Faces are used in Emacs to control the style of display of
1736 particular parts of the text or the frame. @xref{Standard Faces,,,
1737 emacs, The GNU Emacs Manual}, for the list of faces Emacs normally
1741 Each face has its own @dfn{face number}, which distinguishes faces at
1742 low levels within Emacs. However, for most purposes, you refer to
1743 faces in Lisp programs by the symbols that name them.
1746 This function returns @code{t} if @var{object} is a face name string
1747 or symbol (or if it is a vector of the kind used internally to record
1748 face data). It returns @code{nil} otherwise.
1751 Each face name is meaningful for all frames, and by default it has the
1752 same meaning in all frames. But you can arrange to give a particular
1753 face name a special meaning in one frame if you wish.
1756 * Defining Faces:: How to define a face with @code{defface}.
1757 * Face Attributes:: What is in a face?
1758 * Attribute Functions:: Functions to examine and set face attributes.
1759 * Displaying Faces:: How Emacs combines the faces specified for a character.
1760 * Font Selection:: Finding the best available font for a face.
1761 * Face Functions:: How to define and examine faces.
1762 * Auto Faces:: Hook for automatic face assignment.
1763 * Font Lookup:: Looking up the names of available fonts
1764 and information about them.
1765 * Fontsets:: A fontset is a collection of fonts
1766 that handle a range of character sets.
1769 @node Defining Faces
1770 @subsection Defining Faces
1772 The way to define a new face is with @code{defface}. This creates a
1773 kind of customization item (@pxref{Customization}) which the user can
1774 customize using the Customization buffer (@pxref{Easy Customization,,,
1775 emacs, The GNU Emacs Manual}).
1777 @defmac defface face spec doc [keyword value]@dots{}
1778 This declares @var{face} as a customizable face that defaults
1779 according to @var{spec}. You should not quote the symbol @var{face},
1780 and it should not end in @samp{-face} (that would be redundant). The
1781 argument @var{doc} specifies the face documentation. The keywords you
1782 can use in @code{defface} are the same as in @code{defgroup} and
1783 @code{defcustom} (@pxref{Common Keywords}).
1785 When @code{defface} executes, it defines the face according to
1786 @var{spec}, then uses any customizations that were read from the
1787 init file (@pxref{Init File}) to override that specification.
1789 When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs
1790 Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun}
1791 overrides any customizations of the face. This way, the face reflects
1792 exactly what the @code{defface} says.
1794 The purpose of @var{spec} is to specify how the face should appear on
1795 different kinds of terminals. It should be an alist whose elements
1796 have the form @code{(@var{display} @var{atts})}. Each element's
1797 @sc{car}, @var{display}, specifies a class of terminals. (The first
1798 element, if its @sc{car} is @code{default}, is special---it specifies
1799 defaults for the remaining elements). The element's @sc{cadr},
1800 @var{atts}, is a list of face attributes and their values; it
1801 specifies what the face should look like on that kind of terminal.
1802 The possible attributes are defined in the value of
1803 @code{custom-face-attributes}.
1805 The @var{display} part of an element of @var{spec} determines which
1806 frames the element matches. If more than one element of @var{spec}
1807 matches a given frame, the first element that matches is the one used
1808 for that frame. There are three possibilities for @var{display}:
1811 @item @code{default}
1812 This element of @var{spec} doesn't match any frames; instead, it
1813 specifies defaults that apply to all frames. This kind of element, if
1814 used, must be the first element of @var{spec}. Each of the following
1815 elements can override any or all of these defaults.
1818 This element of @var{spec} matches all frames. Therefore, any
1819 subsequent elements of @var{spec} are never used. Normally
1820 @code{t} is used in the last (or only) element of @var{spec}.
1823 If @var{display} is a list, each element should have the form
1824 @code{(@var{characteristic} @var{value}@dots{})}. Here
1825 @var{characteristic} specifies a way of classifying frames, and the
1826 @var{value}s are possible classifications which @var{display} should
1827 apply to. Here are the possible values of @var{characteristic}:
1831 The kind of window system the frame uses---either @code{graphic} (any
1832 graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console),
1833 @code{w32} (for MS Windows 9X/NT/2K/XP), @code{mac} (for the Macintosh
1834 display), or @code{tty} (a non-graphics-capable display).
1835 @xref{Window Systems, window-system}.
1838 What kinds of colors the frame supports---either @code{color},
1839 @code{grayscale}, or @code{mono}.
1842 The kind of background---either @code{light} or @code{dark}.
1845 An integer that represents the minimum number of colors the frame
1846 should support. This matches a frame if its
1847 @code{display-color-cells} value is at least the specified integer.
1850 Whether or not the frame can display the face attributes given in
1851 @var{value}@dots{} (@pxref{Face Attributes}). See the documentation
1852 for the function @code{display-supports-face-attributes-p} for more
1853 information on exactly how this testing is done. @xref{Display Face
1857 If an element of @var{display} specifies more than one @var{value} for a
1858 given @var{characteristic}, any of those values is acceptable. If
1859 @var{display} has more than one element, each element should specify a
1860 different @var{characteristic}; then @emph{each} characteristic of the
1861 frame must match one of the @var{value}s specified for it in
1866 Here's how the standard face @code{region} is defined:
1871 '((((class color) (min-colors 88) (background dark))
1872 :background "blue3")
1874 (((class color) (min-colors 88) (background light))
1875 :background "lightgoldenrod2")
1876 (((class color) (min-colors 16) (background dark))
1877 :background "blue3")
1878 (((class color) (min-colors 16) (background light))
1879 :background "lightgoldenrod2")
1880 (((class color) (min-colors 8))
1881 :background "blue" :foreground "white")
1882 (((type tty) (class mono))
1884 (t :background "gray"))
1886 "Basic face for highlighting the region."
1887 :group 'basic-faces)
1891 Internally, @code{defface} uses the symbol property
1892 @code{face-defface-spec} to record the face attributes specified in
1893 @code{defface}, @code{saved-face} for the attributes saved by the user
1894 with the customization buffer, @code{customized-face} for the
1895 attributes customized by the user for the current session, but not
1896 saved, and @code{face-documentation} for the documentation string.
1898 @defopt frame-background-mode
1899 This option, if non-@code{nil}, specifies the background type to use for
1900 interpreting face definitions. If it is @code{dark}, then Emacs treats
1901 all frames as if they had a dark background, regardless of their actual
1902 background colors. If it is @code{light}, then Emacs treats all frames
1903 as if they had a light background.
1906 @node Face Attributes
1907 @subsection Face Attributes
1908 @cindex face attributes
1910 The effect of using a face is determined by a fixed set of @dfn{face
1911 attributes}. This table lists all the face attributes, and what they
1912 mean. You can specify more than one face for a given piece of text;
1913 Emacs merges the attributes of all the faces to determine how to
1914 display the text. @xref{Displaying Faces}.
1916 Any attribute in a face can have the value @code{unspecified}. This
1917 means the face doesn't specify that attribute. In face merging, when
1918 the first face fails to specify a particular attribute, that means the
1919 next face gets a chance. However, the @code{default} face must
1920 specify all attributes.
1922 Some of these font attributes are meaningful only on certain kinds of
1923 displays---if your display cannot handle a certain attribute, the
1924 attribute is ignored. (The attributes @code{:family}, @code{:width},
1925 @code{:height}, @code{:weight}, and @code{:slant} correspond to parts of
1926 an X Logical Font Descriptor.)
1930 Font family name, or fontset name (@pxref{Fontsets}). If you specify a
1931 font family name, the wild-card characters @samp{*} and @samp{?} are
1935 Relative proportionate width, also known as the character set width or
1936 set width. This should be one of the symbols @code{ultra-condensed},
1937 @code{extra-condensed}, @code{condensed}, @code{semi-condensed},
1938 @code{normal}, @code{semi-expanded}, @code{expanded},
1939 @code{extra-expanded}, or @code{ultra-expanded}.
1942 Either the font height, an integer in units of 1/10 point, a floating
1943 point number specifying the amount by which to scale the height of any
1944 underlying face, or a function, which is called with the old height
1945 (from the underlying face), and should return the new height.
1948 Font weight---a symbol from this series (from most dense to most faint):
1949 @code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
1950 @code{normal}, @code{semi-light}, @code{light}, @code{extra-light},
1951 or @code{ultra-light}.
1953 On a text-only terminal, any weight greater than normal is displayed as
1954 extra bright, and any weight less than normal is displayed as
1955 half-bright (provided the terminal supports the feature).
1958 Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal},
1959 @code{reverse-italic}, or @code{reverse-oblique}.
1961 On a text-only terminal, slanted text is displayed as half-bright, if
1962 the terminal supports the feature.
1965 Foreground color, a string. The value can be a system-defined color
1966 name, or a hexadecimal color specification of the form
1967 @samp{#@var{rr}@var{gg}@var{bb}}. (@samp{#000000} is black,
1968 @samp{#ff0000} is red, @samp{#00ff00} is green, @samp{#0000ff} is
1969 blue, and @samp{#ffffff} is white.)
1972 Background color, a string, like the foreground color.
1974 @item :inverse-video
1975 Whether or not characters should be displayed in inverse video. The
1976 value should be @code{t} (yes) or @code{nil} (no).
1979 The background stipple, a bitmap.
1981 The value can be a string; that should be the name of a file containing
1982 external-format X bitmap data. The file is found in the directories
1983 listed in the variable @code{x-bitmap-file-path}.
1985 Alternatively, the value can specify the bitmap directly, with a list
1986 of the form @code{(@var{width} @var{height} @var{data})}. Here,
1987 @var{width} and @var{height} specify the size in pixels, and
1988 @var{data} is a string containing the raw bits of the bitmap, row by
1989 row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes
1990 in the string (which should be a unibyte string for best results).
1991 This means that each row always occupies at least one whole byte.
1993 If the value is @code{nil}, that means use no stipple pattern.
1995 Normally you do not need to set the stipple attribute, because it is
1996 used automatically to handle certain shades of gray.
1999 Whether or not characters should be underlined, and in what color. If
2000 the value is @code{t}, underlining uses the foreground color of the
2001 face. If the value is a string, underlining uses that color. The
2002 value @code{nil} means do not underline.
2005 Whether or not characters should be overlined, and in what color.
2006 The value is used like that of @code{:underline}.
2008 @item :strike-through
2009 Whether or not characters should be strike-through, and in what
2010 color. The value is used like that of @code{:underline}.
2013 The name of a face from which to inherit attributes, or a list of face
2014 names. Attributes from inherited faces are merged into the face like an
2015 underlying face would be, with higher priority than underlying faces.
2016 If a list of faces is used, attributes from faces earlier in the list
2017 override those from later faces.
2020 Whether or not a box should be drawn around characters, its color, the
2021 width of the box lines, and 3D appearance.
2024 Here are the possible values of the @code{:box} attribute, and what
2032 Draw a box with lines of width 1, in the foreground color.
2035 Draw a box with lines of width 1, in color @var{color}.
2037 @item @code{(:line-width @var{width} :color @var{color} :style @var{style})}
2038 This way you can explicitly specify all aspects of the box. The value
2039 @var{width} specifies the width of the lines to draw; it defaults to 1.
2041 The value @var{color} specifies the color to draw with. The default is
2042 the foreground color of the face for simple boxes, and the background
2043 color of the face for 3D boxes.
2045 The value @var{style} specifies whether to draw a 3D box. If it is
2046 @code{released-button}, the box looks like a 3D button that is not being
2047 pressed. If it is @code{pressed-button}, the box looks like a 3D button
2048 that is being pressed. If it is @code{nil} or omitted, a plain 2D box
2052 In older versions of Emacs, before @code{:family}, @code{:height},
2053 @code{:width}, @code{:weight}, and @code{:slant} existed, these
2054 attributes were used to specify the type face. They are now
2055 semi-obsolete, but they still work:
2059 This attribute specifies the font name.
2062 A non-@code{nil} value specifies a bold font.
2065 A non-@code{nil} value specifies an italic font.
2068 For compatibility, you can still set these ``attributes,'' even
2069 though they are not real face attributes. Here is what that does:
2073 You can specify an X font name as the ``value'' of this ``attribute'';
2074 that sets the @code{:family}, @code{:width}, @code{:height},
2075 @code{:weight}, and @code{:slant} attributes according to the font name.
2077 If the value is a pattern with wildcards, the first font that matches
2078 the pattern is used to set these attributes.
2081 A non-@code{nil} makes the face bold; @code{nil} makes it normal.
2082 This actually works by setting the @code{:weight} attribute.
2085 A non-@code{nil} makes the face italic; @code{nil} makes it normal.
2086 This actually works by setting the @code{:slant} attribute.
2089 @defvar x-bitmap-file-path
2090 This variable specifies a list of directories for searching
2091 for bitmap files, for the @code{:stipple} attribute.
2094 @defun bitmap-spec-p object
2095 This returns @code{t} if @var{object} is a valid bitmap specification,
2096 suitable for use with @code{:stipple} (see above). It returns
2097 @code{nil} otherwise.
2100 @node Attribute Functions
2101 @subsection Face Attribute Functions
2103 This section describes the functions for accessing and modifying the
2104 attributes of an existing face.
2106 @defun set-face-attribute face frame &rest arguments
2107 This function sets one or more attributes of face @var{face} for frame
2108 @var{frame}. The attributes you specify this way override whatever
2109 the @code{defface} says.
2111 The extra arguments @var{arguments} specify the attributes to set, and
2112 the values for them. They should consist of alternating attribute names
2113 (such as @code{:family} or @code{:underline}) and corresponding values.
2117 (set-face-attribute 'foo nil
2124 sets the attributes @code{:width}, @code{:weight} and @code{:underline}
2125 to the corresponding values.
2127 If @var{frame} is @code{t}, this function sets the default attributes
2128 for new frames. Default attribute values specified this way override
2129 the @code{defface} for newly created frames.
2131 If @var{frame} is @code{nil}, this function sets the attributes for
2132 all existing frames, and the default for new frames.
2135 @defun face-attribute face attribute &optional frame inherit
2136 This returns the value of the @var{attribute} attribute of face
2137 @var{face} on @var{frame}. If @var{frame} is @code{nil},
2138 that means the selected frame (@pxref{Input Focus}).
2140 If @var{frame} is @code{t}, this returns whatever new-frames default
2141 value you previously specified with @code{set-face-attribute} for the
2142 @var{attribute} attribute of @var{face}. If you have not specified
2143 one, it returns @code{nil}.
2145 If @var{inherit} is @code{nil}, only attributes directly defined by
2146 @var{face} are considered, so the return value may be
2147 @code{unspecified}, or a relative value. If @var{inherit} is
2148 non-@code{nil}, @var{face}'s definition of @var{attribute} is merged
2149 with the faces specified by its @code{:inherit} attribute; however the
2150 return value may still be @code{unspecified} or relative. If
2151 @var{inherit} is a face or a list of faces, then the result is further
2152 merged with that face (or faces), until it becomes specified and
2155 To ensure that the return value is always specified and absolute, use
2156 a value of @code{default} for @var{inherit}; this will resolve any
2157 unspecified or relative values by merging with the @code{default} face
2158 (which is always completely specified).
2163 (face-attribute 'bold :weight)
2168 @defun face-attribute-relative-p attribute value
2169 This function returns non-@code{nil} if @var{value}, when used as the
2170 value of the face attribute @var{attribute}, is relative. This means
2171 it would modify, rather than completely override, any value that comes
2172 from a subsequent face in the face list or that is inherited from
2175 @code{unspecified} is a relative value for all attributes.
2176 For @code{:height}, floating point values are also relative.
2181 (face-attribute-relative-p :height 2.0)
2186 @defun merge-face-attribute attribute value1 value2
2187 If @var{value1} is a relative value for the face attribute
2188 @var{attribute}, returns it merged with the underlying value
2189 @var{value2}; otherwise, if @var{value1} is an absolute value for the
2190 face attribute @var{attribute}, returns @var{value1} unchanged.
2193 The functions above did not exist before Emacs 21. For compatibility
2194 with older Emacs versions, you can use the following functions to set
2195 and examine the face attributes which existed in those versions.
2196 They use values of @code{t} and @code{nil} for @var{frame}
2197 just like @code{set-face-attribute} and @code{face-attribute}.
2199 @defun set-face-foreground face color &optional frame
2200 @defunx set-face-background face color &optional frame
2201 These functions set the foreground (or background, respectively) color
2202 of face @var{face} to @var{color}. The argument @var{color} should be a
2203 string, the name of a color.
2205 Certain shades of gray are implemented by stipple patterns on
2206 black-and-white screens.
2209 @defun set-face-stipple face pattern &optional frame
2210 This function sets the background stipple pattern of face @var{face}
2211 to @var{pattern}. The argument @var{pattern} should be the name of a
2212 stipple pattern defined by the X server, or actual bitmap data
2213 (@pxref{Face Attributes}), or @code{nil} meaning don't use stipple.
2215 Normally there is no need to pay attention to stipple patterns, because
2216 they are used automatically to handle certain shades of gray.
2219 @defun set-face-font face font &optional frame
2220 This function sets the font of face @var{face}. This actually sets
2221 the attributes @code{:family}, @code{:width}, @code{:height},
2222 @code{:weight}, and @code{:slant} according to the font name
2226 @defun set-face-bold-p face bold-p &optional frame
2227 This function specifies whether @var{face} should be bold. If
2228 @var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no.
2229 This actually sets the @code{:weight} attribute.
2232 @defun set-face-italic-p face italic-p &optional frame
2233 This function specifies whether @var{face} should be italic. If
2234 @var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no.
2235 This actually sets the @code{:slant} attribute.
2238 @defun set-face-underline-p face underline &optional frame
2239 This function sets the underline attribute of face @var{face}.
2240 Non-@code{nil} means do underline; @code{nil} means don't.
2241 If @var{underline} is a string, underline with that color.
2244 @defun set-face-inverse-video-p face inverse-video-p &optional frame
2245 This function sets the @code{:inverse-video} attribute of face
2249 @defun invert-face face &optional frame
2250 This function swaps the foreground and background colors of face
2254 These functions examine the attributes of a face. If you don't
2255 specify @var{frame}, they refer to the selected frame; @code{t} refers
2256 to the default data for new frames. They return the symbol
2257 @code{unspecified} if the face doesn't define any value for that
2260 @defun face-foreground face &optional frame inherit
2261 @defunx face-background face &optional frame inherit
2262 These functions return the foreground color (or background color,
2263 respectively) of face @var{face}, as a string.
2265 If @var{inherit} is @code{nil}, only a color directly defined by the face is
2266 returned. If @var{inherit} is non-@code{nil}, any faces specified by its
2267 @code{:inherit} attribute are considered as well, and if @var{inherit}
2268 is a face or a list of faces, then they are also considered, until a
2269 specified color is found. To ensure that the return value is always
2270 specified, use a value of @code{default} for @var{inherit}.
2273 @defun face-stipple face &optional frame inherit
2274 This function returns the name of the background stipple pattern of face
2275 @var{face}, or @code{nil} if it doesn't have one.
2277 If @var{inherit} is @code{nil}, only a stipple directly defined by the
2278 face is returned. If @var{inherit} is non-@code{nil}, any faces
2279 specified by its @code{:inherit} attribute are considered as well, and
2280 if @var{inherit} is a face or a list of faces, then they are also
2281 considered, until a specified stipple is found. To ensure that the
2282 return value is always specified, use a value of @code{default} for
2286 @defun face-font face &optional frame
2287 This function returns the name of the font of face @var{face}.
2290 @defun face-bold-p face &optional frame
2291 This function returns @code{t} if @var{face} is bold---that is, if it is
2292 bolder than normal. It returns @code{nil} otherwise.
2295 @defun face-italic-p face &optional frame
2296 This function returns @code{t} if @var{face} is italic or oblique,
2297 @code{nil} otherwise.
2300 @defun face-underline-p face &optional frame
2301 This function returns the @code{:underline} attribute of face @var{face}.
2304 @defun face-inverse-video-p face &optional frame
2305 This function returns the @code{:inverse-video} attribute of face @var{face}.
2308 @node Displaying Faces
2309 @subsection Displaying Faces
2311 Here are the ways to specify which faces to use for display of text:
2315 With defaults. The @code{default} face is used as the ultimate
2316 default for all text. (In Emacs 19 and 20, the @code{default}
2317 face is used only when no other face is specified.)
2320 For a mode line or header line, the face @code{mode-line} or
2321 @code{mode-line-inactive}, or @code{header-line}, is merged in just
2322 before @code{default}.
2325 With text properties. A character can have a @code{face} property; if
2326 so, the faces and face attributes specified there apply. @xref{Special
2329 If the character has a @code{mouse-face} property, that is used instead
2330 of the @code{face} property when the mouse is ``near enough'' to the
2334 With overlays. An overlay can have @code{face} and @code{mouse-face}
2335 properties too; they apply to all the text covered by the overlay.
2338 With a region that is active. In Transient Mark mode, the region is
2339 highlighted with the face @code{region} (@pxref{Standard Faces,,,
2340 emacs, The GNU Emacs Manual}).
2343 With special glyphs. Each glyph can specify a particular face
2344 number. @xref{Glyphs}.
2347 If these various sources together specify more than one face for a
2348 particular character, Emacs merges the attributes of the various faces
2349 specified. For each attribute, Emacs tries first the face of any
2350 special glyph; then the face for region highlighting, if appropriate;
2351 then the faces specified by overlays, followed by those specified by
2352 text properties, then the @code{mode-line} or
2353 @code{mode-line-inactive} or @code{header-line} face (if in a mode
2354 line or a header line), and last the @code{default} face.
2356 When multiple overlays cover one character, an overlay with higher
2357 priority overrides those with lower priority. @xref{Overlays}.
2359 @node Font Selection
2360 @subsection Font Selection
2362 @dfn{Selecting a font} means mapping the specified face attributes for
2363 a character to a font that is available on a particular display. The
2364 face attributes, as determined by face merging, specify most of the
2365 font choice, but not all. Part of the choice depends on what character
2368 If the face specifies a fontset name, that fontset determines a
2369 pattern for fonts of the given charset. If the face specifies a font
2370 family, a font pattern is constructed.
2372 Emacs tries to find an available font for the given face attributes
2373 and character's registry and encoding. If there is a font that matches
2374 exactly, it is used, of course. The hard case is when no available font
2375 exactly fits the specification. Then Emacs looks for one that is
2376 ``close''---one attribute at a time. You can specify the order to
2377 consider the attributes. In the case where a specified font family is
2378 not available, you can specify a set of mappings for alternatives to
2381 @defvar face-font-selection-order
2382 This variable specifies the order of importance of the face attributes
2383 @code{:width}, @code{:height}, @code{:weight}, and @code{:slant}. The
2384 value should be a list containing those four symbols, in order of
2385 decreasing importance.
2387 Font selection first finds the best available matches for the first
2388 attribute listed; then, among the fonts which are best in that way, it
2389 searches for the best matches in the second attribute, and so on.
2391 The attributes @code{:weight} and @code{:width} have symbolic values in
2392 a range centered around @code{normal}. Matches that are more extreme
2393 (farther from @code{normal}) are somewhat preferred to matches that are
2394 less extreme (closer to @code{normal}); this is designed to ensure that
2395 non-normal faces contrast with normal ones, whenever possible.
2397 The default is @code{(:width :height :weight :slant)}, which means first
2398 find the fonts closest to the specified @code{:width}, then---among the
2399 fonts with that width---find a best match for the specified font height,
2402 One example of a case where this variable makes a difference is when the
2403 default font has no italic equivalent. With the default ordering, the
2404 @code{italic} face will use a non-italic font that is similar to the
2405 default one. But if you put @code{:slant} before @code{:height}, the
2406 @code{italic} face will use an italic font, even if its height is not
2410 @defvar face-font-family-alternatives
2411 This variable lets you specify alternative font families to try, if a
2412 given family is specified and doesn't exist. Each element should have
2416 (@var{family} @var{alternate-families}@dots{})
2419 If @var{family} is specified but not available, Emacs will try the other
2420 families given in @var{alternate-families}, one by one, until it finds a
2421 family that does exist.
2424 @defvar face-font-registry-alternatives
2425 This variable lets you specify alternative font registries to try, if a
2426 given registry is specified and doesn't exist. Each element should have
2430 (@var{registry} @var{alternate-registries}@dots{})
2433 If @var{registry} is specified but not available, Emacs will try the
2434 other registries given in @var{alternate-registries}, one by one,
2435 until it finds a registry that does exist.
2438 Emacs can make use of scalable fonts, but by default it does not use
2439 them, since the use of too many or too big scalable fonts can crash
2442 @defvar scalable-fonts-allowed
2443 This variable controls which scalable fonts to use. A value of
2444 @code{nil}, the default, means do not use scalable fonts. @code{t}
2445 means to use any scalable font that seems appropriate for the text.
2447 Otherwise, the value must be a list of regular expressions. Then a
2448 scalable font is enabled for use if its name matches any regular
2449 expression in the list. For example,
2452 (setq scalable-fonts-allowed '("muleindian-2$"))
2456 allows the use of scalable fonts with registry @code{muleindian-2}.
2459 @defvar face-font-rescale-alist
2460 This variable specifies scaling for certain faces. Its value should
2461 be a list of elements of the form
2464 (@var{fontname-regexp} . @var{scale-factor})
2467 If @var{fontname-regexp} matches the font name that is about to be
2468 used, this says to choose a larger similar font according to the
2469 factor @var{scale-factor}. You would use this feature to normalize
2470 the font size if certain fonts are bigger or smaller than their
2471 nominal heights and widths would suggest.
2474 @node Face Functions
2475 @subsection Functions for Working with Faces
2477 Here are additional functions for creating and working with faces.
2479 @defun make-face name
2480 This function defines a new face named @var{name}, initially with all
2481 attributes @code{nil}. It does nothing if there is already a face named
2486 This function returns a list of all defined face names.
2489 @defun copy-face old-face new-name &optional frame new-frame
2490 This function defines a face named @var{new-name} as a copy of the existing
2491 face named @var{old-face}. It creates the face @var{new-name} if that
2492 doesn't already exist.
2494 If the optional argument @var{frame} is given, this function applies
2495 only to that frame. Otherwise it applies to each frame individually,
2496 copying attributes from @var{old-face} in each frame to @var{new-face}
2499 If the optional argument @var{new-frame} is given, then @code{copy-face}
2500 copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
2505 This function returns the face number of face @var{face}.
2508 @defun face-documentation face
2509 This function returns the documentation string of face @var{face}, or
2510 @code{nil} if none was specified for it.
2513 @defun face-equal face1 face2 &optional frame
2514 This returns @code{t} if the faces @var{face1} and @var{face2} have the
2515 same attributes for display.
2518 @defun face-differs-from-default-p face &optional frame
2519 This returns non-@code{nil} if the face @var{face} displays
2520 differently from the default face.
2524 A @dfn{face alias} provides an equivalent name for a face. You can
2525 define a face alias by giving the alias symbol the @code{face-alias}
2526 property, with a value of the target face name. The following example
2527 makes @code{modeline} an alias for the @code{mode-line} face.
2530 (put 'modeline 'face-alias 'mode-line)
2535 @subsection Automatic Face Assignment
2536 @cindex automatic face assignment
2537 @cindex faces, automatic choice
2539 This hook is used for automatically assigning faces to text in the
2540 buffer. It is part of the implementation of Jit-Lock mode, used by
2543 @defvar fontification-functions
2544 This variable holds a list of functions that are called by Emacs
2545 redisplay as needed to assign faces automatically to text in the buffer.
2547 The functions are called in the order listed, with one argument, a
2548 buffer position @var{pos}. Each function should attempt to assign faces
2549 to the text in the current buffer starting at @var{pos}.
2551 Each function should record the faces they assign by setting the
2552 @code{face} property. It should also add a non-@code{nil}
2553 @code{fontified} property for all the text it has assigned faces to.
2554 That property tells redisplay that faces have been assigned to that text
2557 It is probably a good idea for each function to do nothing if the
2558 character after @var{pos} already has a non-@code{nil} @code{fontified}
2559 property, but this is not required. If one function overrides the
2560 assignments made by a previous one, the properties as they are
2561 after the last function finishes are the ones that really matter.
2563 For efficiency, we recommend writing these functions so that they
2564 usually assign faces to around 400 to 600 characters at each call.
2568 @subsection Looking Up Fonts
2570 @defun x-list-fonts pattern &optional face frame maximum
2571 This function returns a list of available font names that match
2572 @var{pattern}. If the optional arguments @var{face} and @var{frame} are
2573 specified, then the list is limited to fonts that are the same size as
2574 @var{face} currently is on @var{frame}.
2576 The argument @var{pattern} should be a string, perhaps with wildcard
2577 characters: the @samp{*} character matches any substring, and the
2578 @samp{?} character matches any single character. Pattern matching
2579 of font names ignores case.
2581 If you specify @var{face} and @var{frame}, @var{face} should be a face name
2582 (a symbol) and @var{frame} should be a frame.
2584 The optional argument @var{maximum} sets a limit on how many fonts to
2585 return. If this is non-@code{nil}, then the return value is truncated
2586 after the first @var{maximum} matching fonts. Specifying a small value
2587 for @var{maximum} can make this function much faster, in cases where
2588 many fonts match the pattern.
2591 @defun x-family-fonts &optional family frame
2592 This function returns a list describing the available fonts for family
2593 @var{family} on @var{frame}. If @var{family} is omitted or @code{nil},
2594 this list applies to all families, and therefore, it contains all
2595 available fonts. Otherwise, @var{family} must be a string; it may
2596 contain the wildcards @samp{?} and @samp{*}.
2598 The list describes the display that @var{frame} is on; if @var{frame} is
2599 omitted or @code{nil}, it applies to the selected frame's display
2600 (@pxref{Input Focus}).
2602 The list contains a vector of the following form for each font:
2605 [@var{family} @var{width} @var{point-size} @var{weight} @var{slant}
2606 @var{fixed-p} @var{full} @var{registry-and-encoding}]
2609 The first five elements correspond to face attributes; if you
2610 specify these attributes for a face, it will use this font.
2612 The last three elements give additional information about the font.
2613 @var{fixed-p} is non-@code{nil} if the font is fixed-pitch.
2614 @var{full} is the full name of the font, and
2615 @var{registry-and-encoding} is a string giving the registry and
2616 encoding of the font.
2618 The result list is sorted according to the current face font sort order.
2621 @defun x-font-family-list &optional frame
2622 This function returns a list of the font families available for
2623 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, it
2624 describes the selected frame's display (@pxref{Input Focus}).
2626 The value is a list of elements of this form:
2629 (@var{family} . @var{fixed-p})
2633 Here @var{family} is a font family, and @var{fixed-p} is
2634 non-@code{nil} if fonts of that family are fixed-pitch.
2637 @defvar font-list-limit
2638 This variable specifies maximum number of fonts to consider in font
2639 matching. The function @code{x-family-fonts} will not return more than
2640 that many fonts, and font selection will consider only that many fonts
2641 when searching a matching font for face attributes. The default is
2646 @subsection Fontsets
2648 A @dfn{fontset} is a list of fonts, each assigned to a range of
2649 character codes. An individual font cannot display the whole range of
2650 characters that Emacs supports, but a fontset can. Fontsets have names,
2651 just as fonts do, and you can use a fontset name in place of a font name
2652 when you specify the ``font'' for a frame or a face. Here is
2653 information about defining a fontset under Lisp program control.
2655 @defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
2656 This function defines a new fontset according to the specification
2657 string @var{fontset-spec}. The string should have this format:
2660 @var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
2664 Whitespace characters before and after the commas are ignored.
2666 The first part of the string, @var{fontpattern}, should have the form of
2667 a standard X font name, except that the last two fields should be
2668 @samp{fontset-@var{alias}}.
2670 The new fontset has two names, one long and one short. The long name is
2671 @var{fontpattern} in its entirety. The short name is
2672 @samp{fontset-@var{alias}}. You can refer to the fontset by either
2673 name. If a fontset with the same name already exists, an error is
2674 signaled, unless @var{noerror} is non-@code{nil}, in which case this
2675 function does nothing.
2677 If optional argument @var{style-variant-p} is non-@code{nil}, that says
2678 to create bold, italic and bold-italic variants of the fontset as well.
2679 These variant fontsets do not have a short name, only a long one, which
2680 is made by altering @var{fontpattern} to indicate the bold or italic
2683 The specification string also says which fonts to use in the fontset.
2684 See below for the details.
2687 The construct @samp{@var{charset}:@var{font}} specifies which font to
2688 use (in this fontset) for one particular character set. Here,
2689 @var{charset} is the name of a character set, and @var{font} is the font
2690 to use for that character set. You can use this construct any number of
2691 times in the specification string.
2693 For the remaining character sets, those that you don't specify
2694 explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
2695 @samp{fontset-@var{alias}} with a value that names one character set.
2696 For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced
2697 with @samp{ISO8859-1}.
2699 In addition, when several consecutive fields are wildcards, Emacs
2700 collapses them into a single wildcard. This is to prevent use of
2701 auto-scaled fonts. Fonts made by scaling larger fonts are not usable
2702 for editing, and scaling a smaller font is not useful because it is
2703 better to use the smaller font in its own size, which Emacs does.
2705 Thus if @var{fontpattern} is this,
2708 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
2712 the font specification for @acronym{ASCII} characters would be this:
2715 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
2719 and the font specification for Chinese GB2312 characters would be this:
2722 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
2725 You may not have any Chinese font matching the above font
2726 specification. Most X distributions include only Chinese fonts that
2727 have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
2728 such a case, @samp{Fontset-@var{n}} can be specified as below:
2731 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
2732 chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
2736 Then, the font specifications for all but Chinese GB2312 characters have
2737 @samp{fixed} in the @var{family} field, and the font specification for
2738 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
2741 @defun set-fontset-font name character fontname &optional frame
2742 This function modifies the existing fontset @var{name} to
2743 use the font name @var{fontname} for the character @var{character}.
2745 If @var{name} is @code{nil}, this function modifies the default
2746 fontset, whose short name is @samp{fontset-default}.
2748 @var{character} may be a cons; @code{(@var{from} . @var{to})}, where
2749 @var{from} and @var{to} are non-generic characters. In that case, use
2750 @var{fontname} for all characters in the range @var{from} and @var{to}
2753 @var{character} may be a charset. In that case, use
2754 @var{fontname} for all character in the charsets.
2756 @var{fontname} may be a cons; @code{(@var{family} . @var{registry})},
2757 where @var{family} is a family name of a font (possibly including a
2758 foundry name at the head), @var{registry} is a registry name of a font
2759 (possibly including an encoding name at the tail).
2761 For instance, this changes the default fontset to use a font of which
2762 registry name is @samp{JISX0208.1983} for all characters belonging to
2763 the charset @code{japanese-jisx0208}.
2766 (set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
2770 @defun char-displayable-p char
2771 This function returns @code{t} if Emacs ought to be able to display
2772 @var{char}. More precisely, if the selected frame's fontset has a
2773 font to display the character set that @var{char} belongs to.
2775 Fontsets can specify a font on a per-character basis; when the fontset
2776 does that, this function's value may not be accurate.
2783 The @dfn{fringes} of a window are thin vertical strips down the
2784 sides that are used for displaying bitmaps that indicate truncation,
2785 continuation, horizontal scrolling, and the overlay arrow.
2788 * Fringe Size/Pos:: Specifying where to put the window fringes.
2789 * Fringe Indicators:: Displaying indicator icons in the window fringes.
2790 * Fringe Cursors:: Displaying cursors in the right fringe.
2791 * Fringe Bitmaps:: Specifying bitmaps for fringe indicators.
2792 * Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes.
2793 * Overlay Arrow:: Display of an arrow to indicate position.
2796 @node Fringe Size/Pos
2797 @subsection Fringe Size and Position
2799 The following buffer-local variables control the position and width
2800 of the window fringes.
2802 @defvar fringes-outside-margins
2803 The fringes normally appear between the display margins and the window
2804 text. If the value is non-@code{nil}, they appear outside the display
2805 margins. @xref{Display Margins}.
2808 @defvar left-fringe-width
2809 This variable, if non-@code{nil}, specifies the width of the left
2810 fringe in pixels. A value of @code{nil} means to use the left fringe
2811 width from the window's frame.
2814 @defvar right-fringe-width
2815 This variable, if non-@code{nil}, specifies the width of the right
2816 fringe in pixels. A value of @code{nil} means to use the right fringe
2817 width from the window's frame.
2820 The values of these variables take effect when you display the
2821 buffer in a window. If you change them while the buffer is visible,
2822 you can call @code{set-window-buffer} to display it once again in the
2823 same window, to make the changes take effect.
2825 @defun set-window-fringes window left &optional right outside-margins
2826 This function sets the fringe widths of window @var{window}.
2827 If @var{window} is @code{nil}, the selected window is used.
2829 The argument @var{left} specifies the width in pixels of the left
2830 fringe, and likewise @var{right} for the right fringe. A value of
2831 @code{nil} for either one stands for the default width. If
2832 @var{outside-margins} is non-@code{nil}, that specifies that fringes
2833 should appear outside of the display margins.
2836 @defun window-fringes &optional window
2837 This function returns information about the fringes of a window
2838 @var{window}. If @var{window} is omitted or @code{nil}, the selected
2839 window is used. The value has the form @code{(@var{left-width}
2840 @var{right-width} @var{outside-margins})}.
2844 @node Fringe Indicators
2845 @subsection Fringe Indicators
2846 @cindex fringe indicators
2847 @cindex indicators, fringe
2849 The @dfn{fringe indicators} are tiny icons Emacs displays in the
2850 window fringe (on a graphic display) to indicate truncated or
2851 continued lines, buffer boundaries, overlay arrow, etc.
2853 @defopt indicate-empty-lines
2854 @cindex fringes, and empty line indication
2855 When this is non-@code{nil}, Emacs displays a special glyph in the
2856 fringe of each empty line at the end of the buffer, on graphical
2857 displays. @xref{Fringes}. This variable is automatically
2858 buffer-local in every buffer.
2861 @defvar indicate-buffer-boundaries
2862 This buffer-local variable controls how the buffer boundaries and
2863 window scrolling are indicated in the window fringes.
2865 Emacs can indicate the buffer boundaries---that is, the first and last
2866 line in the buffer---with angle icons when they appear on the screen.
2867 In addition, Emacs can display an up-arrow in the fringe to show
2868 that there is text above the screen, and a down-arrow to show
2869 there is text below the screen.
2871 There are three kinds of basic values:
2875 Don't display any of these fringe icons.
2877 Display the angle icons and arrows in the left fringe.
2879 Display the angle icons and arrows in the right fringe.
2881 Display the angle icons in the left fringe
2882 and don't display the arrows.
2885 Otherwise the value should be an alist that specifies which fringe
2886 indicators to display and where. Each element of the alist should
2887 have the form @code{(@var{indicator} . @var{position})}. Here,
2888 @var{indicator} is one of @code{top}, @code{bottom}, @code{up},
2889 @code{down}, and @code{t} (which covers all the icons not yet
2890 specified), while @var{position} is one of @code{left}, @code{right}
2893 For example, @code{((top . left) (t . right))} places the top angle
2894 bitmap in left fringe, and the bottom angle bitmap as well as both
2895 arrow bitmaps in right fringe. To show the angle bitmaps in the left
2896 fringe, and no arrow bitmaps, use @code{((top . left) (bottom . left))}.
2899 @defvar default-indicate-buffer-boundaries
2900 The value of this variable is the default value for
2901 @code{indicate-buffer-boundaries} in buffers that do not override it.
2904 @defvar fringe-indicator-alist
2905 This buffer-local variable specifies the mapping from logical fringe
2906 indicators to the actual bitmaps displayed in the window fringes.
2908 These symbols identify the logical fringe indicators:
2911 @item Truncation and continuation line indicators:
2912 @code{truncation}, @code{continuation}.
2914 @item Buffer position indicators:
2915 @code{up}, @code{down},
2916 @code{top}, @code{bottom},
2919 @item Empty line indicator:
2922 @item Overlay arrow indicator:
2923 @code{overlay-arrow}.
2925 @item Unknown bitmap indicator:
2929 The value is an alist where each element @code{(@var{indicator} . @var{bitmaps})}
2930 specifies the fringe bitmaps used to display a specific logical
2933 Here, @var{indicator} specifies the logical indicator type, and
2934 @var{bitmaps} is list of symbols @code{(@var{left} @var{right}
2935 [@var{left1} @var{right1}])} which specifies the actual bitmap shown
2936 in the left or right fringe for the logical indicator.
2938 The @var{left} and @var{right} symbols specify the bitmaps shown in
2939 the left and/or right fringe for the specific indicator. The
2940 @var{left1} or @var{right1} bitmaps are used only for the `bottom' and
2941 `top-bottom indicators when the last (only) line in has no final
2942 newline. Alternatively, @var{bitmaps} may be a single symbol which is
2943 used in both left and right fringes.
2945 When @code{fringe-indicator-alist} has a buffer-local value, and there
2946 is no bitmap defined for a logical indicator, or the bitmap is
2947 @code{t}, the corresponding value from the (non-local)
2948 @code{default-fringe-indicator-alist} is used.
2950 To completely hide a specific indicator, set the bitmap to @code{nil}.
2953 @defvar default-fringe-indicator-alist
2954 The value of this variable is the default value for
2955 @code{fringe-indicator-alist} in buffers that do not override it.
2958 Standard fringe bitmaps for indicators:
2960 left-arrow right-arrow up-arrow down-arrow
2961 left-curly-arrow right-curly-arrow
2962 left-triangle right-triangle
2963 top-left-angle top-right-angle
2964 bottom-left-angle bottom-right-angle
2965 left-bracket right-bracket
2966 filled-rectangle hollow-rectangle
2967 filled-square hollow-square
2968 vertical-bar horizontal-bar
2969 empty-line question-mark
2972 @node Fringe Cursors
2973 @subsection Fringe Cursors
2974 @cindex fringe cursors
2975 @cindex cursor, fringe
2977 When a line is exactly as wide as the window, Emacs displays the
2978 cursor in the right fringe instead of using two lines. Different
2979 bitmaps are used to represent the cursor in the fringe depending on
2980 the current buffer's cursor type.
2983 @item Logical cursor types:
2984 @code{box} , @code{hollow}, @code{bar},
2985 @code{hbar}, @code{hollow-small}.
2988 The @code{hollow-small} type is used instead of @code{hollow} when the
2989 normal @code{hollow-rectangle} bitmap is too tall to fit on a specific
2992 @defvar overflow-newline-into-fringe
2993 If this is non-@code{nil}, lines exactly as wide as the window (not
2994 counting the final newline character) are not continued. Instead,
2995 when point is at the end of the line, the cursor appears in the right
2999 @defvar fringe-cursor-alist
3000 This variable specifies the mapping from logical cursor type to the
3001 actual fringe bitmaps displayed in the right fringe. The value is an
3002 alist where each element @code{(@var{cursor} . @var{bitmap})} specifies
3003 the fringe bitmaps used to display a specific logical cursor type in
3004 the fringe. Here, @var{cursor} specifies the logical cursor type and
3005 @var{bitmap} is a symbol specifying the fringe bitmap to be displayed
3006 for that logical cursor type.
3008 When @code{fringe-cursor-alist} has a buffer-local value, and there is
3009 no bitmap defined for a cursor type, the corresponding value from the
3010 (non-local) @code{default-fringes-indicator-alist} is used.
3013 @defvar default-fringes-cursor-alist
3014 The value of this variable is the default value for
3015 @code{fringe-cursor-alist} in buffers that do not override it.
3018 Standard bitmaps for displaying the cursor in right fringe:
3020 filled-rectangle hollow-rectangle filled-square hollow-square
3021 vertical-bar horizontal-bar
3025 @node Fringe Bitmaps
3026 @subsection Fringe Bitmaps
3027 @cindex fringe bitmaps
3028 @cindex bitmaps, fringe
3030 The @dfn{fringe bitmaps} are the actual bitmaps which represent the
3031 logical fringe indicators for truncated or continued lines, buffer
3032 boundaries, overlay arrow, etc. Fringe bitmap symbols have their own
3033 name space. The fringe bitmaps are shared by all frames and windows.
3034 You can redefine the built-in fringe bitmaps, and you can define new
3037 The way to display a bitmap in the left or right fringes for a given
3038 line in a window is by specifying the @code{display} property for one
3039 of the characters that appears in it. Use a display specification of
3040 the form @code{(left-fringe @var{bitmap} [@var{face}])} or
3041 @code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display
3042 Property}). Here, @var{bitmap} is a symbol identifying the bitmap you
3043 want, and @var{face} (which is optional) is the name of the face whose
3044 colors should be used for displaying the bitmap, instead of the
3045 default @code{fringe} face. @var{face} is automatically merged with
3046 the @code{fringe} face, so normally @var{face} need only specify the
3047 foreground color for the bitmap.
3049 @defun fringe-bitmaps-at-pos &optional pos window
3050 This function returns the fringe bitmaps of the display line
3051 containing position @var{pos} in window @var{window}. The return
3052 value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left}
3053 is the symbol for the fringe bitmap in the left fringe (or @code{nil}
3054 if no bitmap), @var{right} is similar for the right fringe, and @var{ov}
3055 is non-@code{nil} if there is an overlay arrow in the left fringe.
3057 The value is @code{nil} if @var{pos} is not visible in @var{window}.
3058 If @var{window} is @code{nil}, that stands for the selected window.
3059 If @var{pos} is @code{nil}, that stands for the value of point in
3063 @node Customizing Bitmaps
3064 @subsection Customizing Fringe Bitmaps
3066 @defun define-fringe-bitmap bitmap bits &optional height width align
3067 This function defines the symbol @var{bitmap} as a new fringe bitmap,
3068 or replaces an existing bitmap with that name.
3070 The argument @var{bits} specifies the image to use. It should be
3071 either a string or a vector of integers, where each element (an
3072 integer) corresponds to one row of the bitmap. Each bit of an integer
3073 corresponds to one pixel of the bitmap, where the low bit corresponds
3074 to the rightmost pixel of the bitmap.
3076 The height is normally the length of @var{bits}. However, you
3077 can specify a different height with non-@code{nil} @var{height}. The width
3078 is normally 8, but you can specify a different width with non-@code{nil}
3079 @var{width}. The width must be an integer between 1 and 16.
3081 The argument @var{align} specifies the positioning of the bitmap
3082 relative to the range of rows where it is used; the default is to
3083 center the bitmap. The allowed values are @code{top}, @code{center},
3086 The @var{align} argument may also be a list @code{(@var{align}
3087 @var{periodic})} where @var{align} is interpreted as described above.
3088 If @var{periodic} is non-@code{nil}, it specifies that the rows in
3089 @code{bits} should be repeated enough times to reach the specified
3093 @defun destroy-fringe-bitmap bitmap
3094 This function destroy the fringe bitmap identified by @var{bitmap}.
3095 If @var{bitmap} identifies a standard fringe bitmap, it actually
3096 restores the standard definition of that bitmap, instead of
3097 eliminating it entirely.
3100 @defun set-fringe-bitmap-face bitmap &optional face
3101 This sets the face for the fringe bitmap @var{bitmap} to @var{face}.
3102 If @var{face} is @code{nil}, it selects the @code{fringe} face. The
3103 bitmap's face controls the color to draw it in.
3105 @var{face} is merged with the @code{fringe} face, so normally
3106 @var{face} should specify only the foreground color.
3110 @subsection The Overlay Arrow
3111 @c @cindex overlay arrow Duplicates variable names
3113 The @dfn{overlay arrow} is useful for directing the user's attention
3114 to a particular line in a buffer. For example, in the modes used for
3115 interface to debuggers, the overlay arrow indicates the line of code
3116 about to be executed. This feature has nothing to do with
3117 @dfn{overlays} (@pxref{Overlays}).
3119 @defvar overlay-arrow-string
3120 This variable holds the string to display to call attention to a
3121 particular line, or @code{nil} if the arrow feature is not in use.
3122 On a graphical display the contents of the string are ignored; instead a
3123 glyph is displayed in the fringe area to the left of the display area.
3126 @defvar overlay-arrow-position
3127 This variable holds a marker that indicates where to display the overlay
3128 arrow. It should point at the beginning of a line. On a non-graphical
3129 display the arrow text
3130 appears at the beginning of that line, overlaying any text that would
3131 otherwise appear. Since the arrow is usually short, and the line
3132 usually begins with indentation, normally nothing significant is
3135 The overlay-arrow string is displayed in any given buffer if the value
3136 of @code{overlay-arrow-position} in that buffer points into that
3137 buffer. Thus, it is possible to display multiple overlay arrow strings
3138 by creating buffer-local bindings of @code{overlay-arrow-position}.
3139 However, it is usually cleaner to use
3140 @code{overlay-arrow-variable-list} to achieve this result.
3141 @c !!! overlay-arrow-position: but the overlay string may remain in the display
3142 @c of some other buffer until an update is required. This should be fixed
3146 You can do a similar job by creating an overlay with a
3147 @code{before-string} property. @xref{Overlay Properties}.
3149 You can define multiple overlay arrows via the variable
3150 @code{overlay-arrow-variable-list}.
3152 @defvar overlay-arrow-variable-list
3153 This variable's value is a list of variables, each of which specifies
3154 the position of an overlay arrow. The variable
3155 @code{overlay-arrow-position} has its normal meaning because it is on
3159 Each variable on this list can have properties
3160 @code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that
3161 specify an overlay arrow string (for text-only terminals) or fringe
3162 bitmap (for graphical terminals) to display at the corresponding
3163 overlay arrow position. If either property is not set, the default
3164 @code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator
3168 @section Scroll Bars
3171 Normally the frame parameter @code{vertical-scroll-bars} controls
3172 whether the windows in the frame have vertical scroll bars, and
3173 whether they are on the left or right. The frame parameter
3174 @code{scroll-bar-width} specifies how wide they are (@code{nil}
3175 meaning the default). @xref{Layout Parameters}.
3177 @defun frame-current-scroll-bars &optional frame
3178 This function reports the scroll bar type settings for frame
3179 @var{frame}. The value is a cons cell
3180 @code{(@var{vertical-type} .@: @var{horizontal-type})}, where
3181 @var{vertical-type} is either @code{left}, @code{right}, or @code{nil}
3182 (which means no scroll bar.) @var{horizontal-type} is meant to
3183 specify the horizontal scroll bar type, but since they are not
3184 implemented, it is always @code{nil}.
3187 @vindex vertical-scroll-bar
3188 You can enable or disable scroll bars for a particular buffer,
3189 by setting the variable @code{vertical-scroll-bar}. This variable
3190 automatically becomes buffer-local when set. The possible values are
3191 @code{left}, @code{right}, @code{t}, which means to use the
3192 frame's default, and @code{nil} for no scroll bar.
3194 You can also control this for individual windows. Call the function
3195 @code{set-window-scroll-bars} to specify what to do for a specific window:
3197 @defun set-window-scroll-bars window width &optional vertical-type horizontal-type
3198 This function sets the width and type of scroll bars for window
3201 @var{width} specifies the scroll bar width in pixels (@code{nil} means
3202 use the width specified for the frame). @var{vertical-type} specifies
3203 whether to have a vertical scroll bar and, if so, where. The possible
3204 values are @code{left}, @code{right} and @code{nil}, just like the
3205 values of the @code{vertical-scroll-bars} frame parameter.
3207 The argument @var{horizontal-type} is meant to specify whether and
3208 where to have horizontal scroll bars, but since they are not
3209 implemented, it has no effect. If @var{window} is @code{nil}, the
3210 selected window is used.
3213 @defun window-scroll-bars &optional window
3214 Report the width and type of scroll bars specified for @var{window}.
3215 If @var{window} is omitted or @code{nil}, the selected window is used.
3216 The value is a list of the form @code{(@var{width}
3217 @var{cols} @var{vertical-type} @var{horizontal-type})}. The value
3218 @var{width} is the value that was specified for the width (which may
3219 be @code{nil}); @var{cols} is the number of columns that the scroll
3220 bar actually occupies.
3222 @var{horizontal-type} is not actually meaningful.
3225 If you don't specify these values for a window with
3226 @code{set-window-scroll-bars}, the buffer-local variables
3227 @code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being
3228 displayed control the window's vertical scroll bars. The function
3229 @code{set-window-buffer} examines these variables. If you change them
3230 in a buffer that is already visible in a window, you can make the
3231 window take note of the new values by calling @code{set-window-buffer}
3232 specifying the same buffer that is already displayed.
3234 @defvar scroll-bar-mode
3235 This variable, always local in all buffers, controls whether and where
3236 to put scroll bars in windows displaying the buffer. The possible values
3237 are @code{nil} for no scroll bar, @code{left} to put a scroll bar on
3238 the left, and @code{right} to put a scroll bar on the right.
3241 @defun window-current-scroll-bars &optional window
3242 This function reports the scroll bar type for window @var{window}.
3243 If @var{window} is omitted or @code{nil}, the selected window is used.
3244 The value is a cons cell
3245 @code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike
3246 @code{window-scroll-bars}, this reports the scroll bar type actually
3247 used, once frame defaults and @code{scroll-bar-mode} are taken into
3251 @defvar scroll-bar-width
3252 This variable, always local in all buffers, specifies the width of the
3253 buffer's scroll bars, measured in pixels. A value of @code{nil} means
3254 to use the value specified by the frame.
3257 @node Display Property
3258 @section The @code{display} Property
3259 @cindex display specification
3260 @kindex display @r{(text property)}
3262 The @code{display} text property (or overlay property) is used to
3263 insert images into text, and also control other aspects of how text
3264 displays. The value of the @code{display} property should be a
3265 display specification, or a list or vector containing several display
3266 specifications. Display specifications in the same @code{display}
3267 property value generally apply in parallel to the text they cover.
3269 If several sources (overlays and/or a text property) specify values
3270 for the @code{display} property, only one of the values takes effect,
3271 following the rules of @code{get-char-property}. @xref{Examining
3274 The rest of this section describes several kinds of
3275 display specifications and what they mean.
3278 * Replacing Specs:: Display specs that replace the text.
3279 * Specified Space:: Displaying one space with a specified width.
3280 * Pixel Specification:: Specifying space width or height in pixels.
3281 * Other Display Specs:: Displaying an image; magnifying text; moving it
3282 up or down on the page; adjusting the width
3283 of spaces within text.
3284 * Display Margins:: Displaying text or images to the side of the main text.
3287 @node Replacing Specs
3288 @subsection Display Specs That Replace The Text
3290 Some kinds of @code{display} specifications specify something to
3291 display instead of the text that has the property. These are called
3292 @dfn{replacing} display specifications. Emacs does not allow the user
3293 to interactively move point into the middle of buffer text that is
3294 replaced in this way.
3296 If a list of display specifications includes more than one replacing
3297 display specification, the first overrides the rest. Replacing
3298 display specifications make most other display specifications
3299 irrelevant, since those don't apply to the replacement.
3301 For replacing display specifications, ``the text that has the
3302 property'' means all the consecutive characters that have the same
3303 Lisp object as their @code{display} property; these characters are
3304 replaced as a single unit. By contrast, characters that have similar
3305 but distinct Lisp objects as their @code{display} properties are
3306 handled separately. Here's a function that illustrates this point:
3310 (goto-char (point-min))
3312 (let ((string (concat "A")))
3313 (put-text-property (point) (1+ (point)) 'display string)
3315 (put-text-property (point) (1+ (point)) 'display string)
3320 It gives each of the first ten characters in the buffer string
3321 @code{"A"} as the @code{display} property, but they don't all get the
3322 same string. The first two characters get the same string, so they
3323 together are replaced with one @samp{A}. The next two characters get
3324 a second string, so they together are replaced with one @samp{A}.
3325 Likewise for each following pair of characters. Thus, the ten
3326 characters appear as five A's. This function would have the same
3331 (goto-char (point-min))
3333 (let ((string (concat "A")))
3334 (put-text-property (point) (+ 2 (point)) 'display string)
3335 (put-text-property (point) (1+ (point)) 'display string)
3340 This illustrates that what matters is the property value for
3341 each character. If two consecutive characters have the same
3342 object as the @code{display} property value, it's irrelevant
3343 whether they got this property from a single call to
3344 @code{put-text-property} or from two different calls.
3346 @node Specified Space
3347 @subsection Specified Spaces
3348 @cindex spaces, specified height or width
3349 @cindex variable-width spaces
3351 To display a space of specified width and/or height, use a display
3352 specification of the form @code{(space . @var{props})}, where
3353 @var{props} is a property list (a list of alternating properties and
3354 values). You can put this property on one or more consecutive
3355 characters; a space of the specified height and width is displayed in
3356 place of @emph{all} of those characters. These are the properties you
3357 can use in @var{props} to specify the weight of the space:
3360 @item :width @var{width}
3361 If @var{width} is an integer or floating point number, it specifies
3362 that the space width should be @var{width} times the normal character
3363 width. @var{width} can also be a @dfn{pixel width} specification
3364 (@pxref{Pixel Specification}).
3366 @item :relative-width @var{factor}
3367 Specifies that the width of the stretch should be computed from the
3368 first character in the group of consecutive characters that have the
3369 same @code{display} property. The space width is the width of that
3370 character, multiplied by @var{factor}.
3372 @item :align-to @var{hpos}
3373 Specifies that the space should be wide enough to reach @var{hpos}.
3374 If @var{hpos} is a number, it is measured in units of the normal
3375 character width. @var{hpos} can also be a @dfn{pixel width}
3376 specification (@pxref{Pixel Specification}).
3379 You should use one and only one of the above properties. You can
3380 also specify the height of the space, with these properties:
3383 @item :height @var{height}
3384 Specifies the height of the space.
3385 If @var{height} is an integer or floating point number, it specifies
3386 that the space height should be @var{height} times the normal character
3387 height. The @var{height} may also be a @dfn{pixel height} specification
3388 (@pxref{Pixel Specification}).
3390 @item :relative-height @var{factor}
3391 Specifies the height of the space, multiplying the ordinary height
3392 of the text having this display specification by @var{factor}.
3394 @item :ascent @var{ascent}
3395 If the value of @var{ascent} is a non-negative number no greater than
3396 100, it specifies that @var{ascent} percent of the height of the space
3397 should be considered as the ascent of the space---that is, the part
3398 above the baseline. The ascent may also be specified in pixel units
3399 with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}).
3403 Don't use both @code{:height} and @code{:relative-height} together.
3405 The @code{:width} and @code{:align-to} properties are supported on
3406 non-graphic terminals, but the other space properties in this section
3409 @node Pixel Specification
3410 @subsection Pixel Specification for Spaces
3411 @cindex spaces, pixel specification
3413 The value of the @code{:width}, @code{:align-to}, @code{:height},
3414 and @code{:ascent} properties can be a special kind of expression that
3415 is evaluated during redisplay. The result of the evaluation is used
3416 as an absolute number of pixels.
3418 The following expressions are supported:
3422 @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form}
3423 @var{num} ::= @var{integer} | @var{float} | @var{symbol}
3424 @var{unit} ::= in | mm | cm | width | height
3427 @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin
3429 @var{pos} ::= left | center | right
3430 @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...)
3435 The form @var{num} specifies a fraction of the default frame font
3436 height or width. The form @code{(@var{num})} specifies an absolute
3437 number of pixels. If @var{num} is a symbol, @var{symbol}, its
3438 buffer-local variable binding is used.
3440 The @code{in}, @code{mm}, and @code{cm} units specify the number of
3441 pixels per inch, millimeter, and centimeter, respectively. The
3442 @code{width} and @code{height} units correspond to the default width
3443 and height of the current face. An image specification @code{image}
3444 corresponds to the width or height of the image.
3446 The @code{left-fringe}, @code{right-fringe}, @code{left-margin},
3447 @code{right-margin}, @code{scroll-bar}, and @code{text} elements
3448 specify to the width of the corresponding area of the window.
3450 The @code{left}, @code{center}, and @code{right} positions can be
3451 used with @code{:align-to} to specify a position relative to the left
3452 edge, center, or right edge of the text area.
3454 Any of the above window elements (except @code{text}) can also be
3455 used with @code{:align-to} to specify that the position is relative to
3456 the left edge of the given area. Once the base offset for a relative
3457 position has been set (by the first occurrence of one of these
3458 symbols), further occurrences of these symbols are interpreted as the
3459 width of the specified area. For example, to align to the center of
3460 the left-margin, use
3463 :align-to (+ left-margin (0.5 . left-margin))
3466 If no specific base offset is set for alignment, it is always relative
3467 to the left edge of the text area. For example, @samp{:align-to 0} in a
3468 header-line aligns with the first text column in the text area.
3470 A value of the form @code{(@var{num} . @var{expr})} stands for the
3471 product of the values of @var{num} and @var{expr}. For example,
3472 @code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 .
3473 @var{image})} specifies half the width (or height) of the specified
3476 The form @code{(+ @var{expr} ...)} adds up the value of the
3477 expressions. The form @code{(- @var{expr} ...)} negates or subtracts
3478 the value of the expressions.
3480 @node Other Display Specs
3481 @subsection Other Display Specifications
3483 Here are the other sorts of display specifications that you can use
3484 in the @code{display} text property.
3488 Display @var{string} instead of the text that has this property.
3490 Recursive display specifications are not supported---@var{string}'s
3491 @code{display} properties, if any, are not used.
3493 @item (image . @var{image-props})
3494 This kind of display specification is an image descriptor (@pxref{Images}).
3495 When used as a display specification, it means to display the image
3496 instead of the text that has the display specification.
3498 @item (slice @var{x} @var{y} @var{width} @var{height})
3499 This specification together with @code{image} specifies a @dfn{slice}
3500 (a partial area) of the image to display. The elements @var{y} and
3501 @var{x} specify the top left corner of the slice, within the image;
3502 @var{width} and @var{height} specify the width and height of the
3503 slice. Integer values are numbers of pixels. A floating point number
3504 in the range 0.0--1.0 stands for that fraction of the width or height
3505 of the entire image.
3507 @item ((margin nil) @var{string})
3508 A display specification of this form means to display @var{string}
3509 instead of the text that has the display specification, at the same
3510 position as that text. It is equivalent to using just @var{string},
3511 but it is done as a special case of marginal display (@pxref{Display
3514 @item (space-width @var{factor})
3515 This display specification affects all the space characters within the
3516 text that has the specification. It displays all of these spaces
3517 @var{factor} times as wide as normal. The element @var{factor} should
3518 be an integer or float. Characters other than spaces are not affected
3519 at all; in particular, this has no effect on tab characters.
3521 @item (height @var{height})
3522 This display specification makes the text taller or shorter.
3523 Here are the possibilities for @var{height}:
3526 @item @code{(+ @var{n})}
3527 This means to use a font that is @var{n} steps larger. A ``step'' is
3528 defined by the set of available fonts---specifically, those that match
3529 what was otherwise specified for this text, in all attributes except
3530 height. Each size for which a suitable font is available counts as
3531 another step. @var{n} should be an integer.
3533 @item @code{(- @var{n})}
3534 This means to use a font that is @var{n} steps smaller.
3536 @item a number, @var{factor}
3537 A number, @var{factor}, means to use a font that is @var{factor} times
3538 as tall as the default font.
3540 @item a symbol, @var{function}
3541 A symbol is a function to compute the height. It is called with the
3542 current height as argument, and should return the new height to use.
3544 @item anything else, @var{form}
3545 If the @var{height} value doesn't fit the previous possibilities, it is
3546 a form. Emacs evaluates it to get the new height, with the symbol
3547 @code{height} bound to the current specified font height.
3550 @item (raise @var{factor})
3551 This kind of display specification raises or lowers the text
3552 it applies to, relative to the baseline of the line.
3554 @var{factor} must be a number, which is interpreted as a multiple of the
3555 height of the affected text. If it is positive, that means to display
3556 the characters raised. If it is negative, that means to display them
3559 If the text also has a @code{height} display specification, that does
3560 not affect the amount of raising or lowering, which is based on the
3561 faces used for the text.
3564 @c We put all the `@code{(when ...)}' on one line to encourage
3565 @c makeinfo's end-of-sentence heuristics to DTRT. Previously, the dot
3566 @c was at eol; the info file ended up w/ two spaces rendered after it.
3567 You can make any display specification conditional. To do that,
3568 package it in another list of the form
3569 @code{(when @var{condition} . @var{spec})}.
3570 Then the specification @var{spec} applies only when
3571 @var{condition} evaluates to a non-@code{nil} value. During the
3572 evaluation, @code{object} is bound to the string or buffer having the
3573 conditional @code{display} property. @code{position} and
3574 @code{buffer-position} are bound to the position within @code{object}
3575 and the buffer position where the @code{display} property was found,
3576 respectively. Both positions can be different when @code{object} is a
3579 @node Display Margins
3580 @subsection Displaying in the Margins
3581 @cindex display margins
3582 @cindex margins, display
3584 A buffer can have blank areas called @dfn{display margins} on the
3585 left and on the right. Ordinary text never appears in these areas,
3586 but you can put things into the display margins using the
3587 @code{display} property. There is currently no way to make text or
3588 images in the margin mouse-sensitive.
3590 The way to display something in the margins is to specify it in a
3591 margin display specification in the @code{display} property of some
3592 text. This is a replacing display specification, meaning that the
3593 text you put it on does not get displayed; the margin display appears,
3594 but that text does not.
3596 A margin display specification looks like @code{((margin
3597 right-margin) @var{spec}} or @code{((margin left-margin) @var{spec})}.
3598 Here, @var{spec} is another display specification that says what to
3599 display in the margin. Typically it is a string of text to display,
3600 or an image descriptor.
3602 To display something in the margin @emph{in association with}
3603 certain buffer text, without altering or preventing the display of
3604 that text, put a @code{before-string} property on the text and put the
3605 margin display specification on the contents of the before-string.
3607 Before the display margins can display anything, you must give
3608 them a nonzero width. The usual way to do that is to set these
3611 @defvar left-margin-width
3612 This variable specifies the width of the left margin.
3613 It is buffer-local in all buffers.
3616 @defvar right-margin-width
3617 This variable specifies the width of the right margin.
3618 It is buffer-local in all buffers.
3621 Setting these variables does not immediately affect the window. These
3622 variables are checked when a new buffer is displayed in the window.
3623 Thus, you can make changes take effect by calling
3624 @code{set-window-buffer}.
3626 You can also set the margin widths immediately.
3628 @defun set-window-margins window left &optional right
3629 This function specifies the margin widths for window @var{window}.
3630 The argument @var{left} controls the left margin and
3631 @var{right} controls the right margin (default @code{0}).
3634 @defun window-margins &optional window
3635 This function returns the left and right margins of @var{window}
3636 as a cons cell of the form @code{(@var{left} . @var{right})}.
3637 If @var{window} is @code{nil}, the selected window is used.
3642 @cindex images in buffers
3644 To display an image in an Emacs buffer, you must first create an image
3645 descriptor, then use it as a display specifier in the @code{display}
3646 property of text that is displayed (@pxref{Display Property}).
3648 Emacs is usually able to display images when it is run on a
3649 graphical terminal. Images cannot be displayed in a text terminal, on
3650 certain graphical terminals that lack the support for this, or if
3651 Emacs is compiled without image support. You can use the function
3652 @code{display-images-p} to determine if images can in principle be
3653 displayed (@pxref{Display Feature Testing}).
3656 * Image Formats:: Supported image formats.
3657 * Image Descriptors:: How to specify an image for use in @code{:display}.
3658 * XBM Images:: Special features for XBM format.
3659 * XPM Images:: Special features for XPM format.
3660 * GIF Images:: Special features for GIF format.
3661 * PostScript Images:: Special features for PostScript format.
3662 * Other Image Types:: Various other formats are supported.
3663 * Defining Images:: Convenient ways to define an image for later use.
3664 * Showing Images:: Convenient ways to display an image once it is defined.
3665 * Image Cache:: Internal mechanisms of image display.
3669 @subsection Image Formats
3670 @cindex image formats
3673 Emacs can display a number of different image formats; some of them
3674 are supported only if particular support libraries are installed on
3675 your machine. In some environments, Emacs can load image
3676 libraries on demand; if so, the variable @code{image-library-alist}
3677 can be used to modify the set of known names for these dynamic
3678 libraries (though it is not possible to add new image formats).
3680 The supported image formats include XBM, XPM (this requires the
3681 libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring
3682 @code{libungif} 4.1.0), PostScript, PBM, JPEG (requiring the
3683 @code{libjpeg} library version v6a), TIFF (requiring @code{libtiff}
3684 v3.4), PNG (requiring @code{libpng} 1.0.2), and SVG (requiring
3685 @code{librsvg} 2.0.0).
3687 You specify one of these formats with an image type symbol. The image
3688 type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
3689 @code{pbm}, @code{jpeg}, @code{tiff}, @code{png}, and @code{svg}.
3692 This variable contains a list of those image type symbols that are
3693 potentially supported in the current configuration.
3694 @emph{Potentially} here means that Emacs knows about the image types,
3695 not necessarily that they can be loaded (they could depend on
3696 unavailable dynamic libraries, for example).
3698 To know which image types are really available, use
3699 @code{image-type-available-p}.
3702 @defvar image-library-alist
3703 This in an alist of image types vs external libraries needed to
3706 Each element is a list @code{(@var{image-type} @var{library}...)},
3707 where the car is a supported image format from @code{image-types}, and
3708 the rest are strings giving alternate filenames for the corresponding
3709 external libraries to load.
3711 Emacs tries to load the libraries in the order they appear on the
3712 list; if none is loaded, the running session of Emacs won't support
3713 the image type. @code{pbm} and @code{xbm} don't need to be listed;
3714 they're always supported.
3716 This variable is ignored if the image libraries are statically linked
3720 @defun image-type-available-p type
3721 This function returns non-@code{nil} if image type @var{type} is
3722 available, i.e., if images of this type can be loaded and displayed in
3723 Emacs. @var{type} should be one of the types contained in
3726 For image types whose support libraries are statically linked, this
3727 function always returns @code{t}; for other image types, it returns
3728 @code{t} if the dynamic library could be loaded, @code{nil} otherwise.
3731 @node Image Descriptors
3732 @subsection Image Descriptors
3733 @cindex image descriptor
3735 An image description is a list of the form @code{(image . @var{props})},
3736 where @var{props} is a property list containing alternating keyword
3737 symbols (symbols whose names start with a colon) and their values.
3738 You can use any Lisp object as a property, but the only properties
3739 that have any special meaning are certain symbols, all of them keywords.
3741 Every image descriptor must contain the property @code{:type
3742 @var{type}} to specify the format of the image. The value of @var{type}
3743 should be an image type symbol; for example, @code{xpm} for an image in
3746 Here is a list of other properties that are meaningful for all image
3750 @item :file @var{file}
3751 The @code{:file} property says to load the image from file
3752 @var{file}. If @var{file} is not an absolute file name, it is expanded
3753 in @code{data-directory}.
3755 @item :data @var{data}
3756 The @code{:data} property says the actual contents of the image.
3757 Each image must use either @code{:data} or @code{:file}, but not both.
3758 For most image types, the value of the @code{:data} property should be a
3759 string containing the image data; we recommend using a unibyte string.
3761 Before using @code{:data}, look for further information in the section
3762 below describing the specific image format. For some image types,
3763 @code{:data} may not be supported; for some, it allows other data types;
3764 for some, @code{:data} alone is not enough, so you need to use other
3765 image properties along with @code{:data}.
3767 @item :margin @var{margin}
3768 The @code{:margin} property specifies how many pixels to add as an
3769 extra margin around the image. The value, @var{margin}, must be a
3770 non-negative number, or a pair @code{(@var{x} . @var{y})} of such
3771 numbers. If it is a pair, @var{x} specifies how many pixels to add
3772 horizontally, and @var{y} specifies how many pixels to add vertically.
3773 If @code{:margin} is not specified, the default is zero.
3775 @item :ascent @var{ascent}
3776 The @code{:ascent} property specifies the amount of the image's
3777 height to use for its ascent---that is, the part above the baseline.
3778 The value, @var{ascent}, must be a number in the range 0 to 100, or
3779 the symbol @code{center}.
3781 If @var{ascent} is a number, that percentage of the image's height is
3782 used for its ascent.
3784 If @var{ascent} is @code{center}, the image is vertically centered
3785 around a centerline which would be the vertical centerline of text drawn
3786 at the position of the image, in the manner specified by the text
3787 properties and overlays that apply to the image.
3789 If this property is omitted, it defaults to 50.
3791 @item :relief @var{relief}
3792 The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle
3793 around the image. The value, @var{relief}, specifies the width of the
3794 shadow lines, in pixels. If @var{relief} is negative, shadows are drawn
3795 so that the image appears as a pressed button; otherwise, it appears as
3796 an unpressed button.
3798 @item :conversion @var{algorithm}
3799 The @code{:conversion} property, if non-@code{nil}, specifies a
3800 conversion algorithm that should be applied to the image before it is
3801 displayed; the value, @var{algorithm}, specifies which algorithm.
3806 Specifies the Laplace edge detection algorithm, which blurs out small
3807 differences in color while highlighting larger differences. People
3808 sometimes consider this useful for displaying the image for a
3809 ``disabled'' button.
3811 @item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
3812 Specifies a general edge-detection algorithm. @var{matrix} must be
3813 either a nine-element list or a nine-element vector of numbers. A pixel
3814 at position @math{x/y} in the transformed image is computed from
3815 original pixels around that position. @var{matrix} specifies, for each
3816 pixel in the neighborhood of @math{x/y}, a factor with which that pixel
3817 will influence the transformed pixel; element @math{0} specifies the
3818 factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for
3819 the pixel at @math{x/y-1} etc., as shown below:
3822 $$\pmatrix{x-1/y-1 & x/y-1 & x+1/y-1 \cr
3823 x-1/y & x/y & x+1/y \cr
3824 x-1/y+1& x/y+1 & x+1/y+1 \cr}$$
3829 (x-1/y-1 x/y-1 x+1/y-1
3831 x-1/y+1 x/y+1 x+1/y+1)
3835 The resulting pixel is computed from the color intensity of the color
3836 resulting from summing up the RGB values of surrounding pixels,
3837 multiplied by the specified factors, and dividing that sum by the sum
3838 of the factors' absolute values.
3840 Laplace edge-detection currently uses a matrix of
3843 $$\pmatrix{1 & 0 & 0 \cr
3856 Emboss edge-detection uses a matrix of
3859 $$\pmatrix{ 2 & -1 & 0 \cr
3873 Specifies transforming the image so that it looks ``disabled.''
3876 @item :mask @var{mask}
3877 If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build
3878 a clipping mask for the image, so that the background of a frame is
3879 visible behind the image. If @var{bg} is not specified, or if @var{bg}
3880 is @code{t}, determine the background color of the image by looking at
3881 the four corners of the image, assuming the most frequently occurring
3882 color from the corners is the background color of the image. Otherwise,
3883 @var{bg} must be a list @code{(@var{red} @var{green} @var{blue})}
3884 specifying the color to assume for the background of the image.
3886 If @var{mask} is @code{nil}, remove a mask from the image, if it has
3887 one. Images in some formats include a mask which can be removed by
3888 specifying @code{:mask nil}.
3890 @item :pointer @var{shape}
3891 This specifies the pointer shape when the mouse pointer is over this
3892 image. @xref{Pointer Shape}, for available pointer shapes.
3894 @item :map @var{map}
3895 This associates an image map of @dfn{hot spots} with this image.
3897 An image map is an alist where each element has the format
3898 @code{(@var{area} @var{id} @var{plist})}. An @var{area} is specified
3899 as either a rectangle, a circle, or a polygon.
3901 A rectangle is a cons
3902 @code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))}
3903 which specifies the pixel coordinates of the upper left and bottom right
3904 corners of the rectangle area.
3907 @code{(circle . ((@var{x0} . @var{y0}) . @var{r}))}
3908 which specifies the center and the radius of the circle; @var{r} may
3909 be a float or integer.
3912 @code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])}
3913 where each pair in the vector describes one corner in the polygon.
3915 When the mouse pointer lies on a hot-spot area of an image, the
3916 @var{plist} of that hot-spot is consulted; if it contains a @code{help-echo}
3917 property, that defines a tool-tip for the hot-spot, and if it contains
3918 a @code{pointer} property, that defines the shape of the mouse cursor when
3919 it is on the hot-spot.
3920 @xref{Pointer Shape}, for available pointer shapes.
3922 When you click the mouse when the mouse pointer is over a hot-spot, an
3923 event is composed by combining the @var{id} of the hot-spot with the
3924 mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's
3925 @var{id} is @code{area4}.
3928 @defun image-mask-p spec &optional frame
3929 This function returns @code{t} if image @var{spec} has a mask bitmap.
3930 @var{frame} is the frame on which the image will be displayed.
3931 @var{frame} @code{nil} or omitted means to use the selected frame
3932 (@pxref{Input Focus}).
3936 @subsection XBM Images
3939 To use XBM format, specify @code{xbm} as the image type. This image
3940 format doesn't require an external library, so images of this type are
3943 Additional image properties supported for the @code{xbm} image type are:
3946 @item :foreground @var{foreground}
3947 The value, @var{foreground}, should be a string specifying the image
3948 foreground color, or @code{nil} for the default color. This color is
3949 used for each pixel in the XBM that is 1. The default is the frame's
3952 @item :background @var{background}
3953 The value, @var{background}, should be a string specifying the image
3954 background color, or @code{nil} for the default color. This color is
3955 used for each pixel in the XBM that is 0. The default is the frame's
3959 If you specify an XBM image using data within Emacs instead of an
3960 external file, use the following three properties:
3963 @item :data @var{data}
3964 The value, @var{data}, specifies the contents of the image.
3965 There are three formats you can use for @var{data}:
3969 A vector of strings or bool-vectors, each specifying one line of the
3970 image. Do specify @code{:height} and @code{:width}.
3973 A string containing the same byte sequence as an XBM file would contain.
3974 You must not specify @code{:height} and @code{:width} in this case,
3975 because omitting them is what indicates the data has the format of an
3976 XBM file. The file contents specify the height and width of the image.
3979 A string or a bool-vector containing the bits of the image (plus perhaps
3980 some extra bits at the end that will not be used). It should contain at
3981 least @var{width} * @code{height} bits. In this case, you must specify
3982 @code{:height} and @code{:width}, both to indicate that the string
3983 contains just the bits rather than a whole XBM file, and to specify the
3987 @item :width @var{width}
3988 The value, @var{width}, specifies the width of the image, in pixels.
3990 @item :height @var{height}
3991 The value, @var{height}, specifies the height of the image, in pixels.
3995 @subsection XPM Images
3998 To use XPM format, specify @code{xpm} as the image type. The
3999 additional image property @code{:color-symbols} is also meaningful with
4000 the @code{xpm} image type:
4003 @item :color-symbols @var{symbols}
4004 The value, @var{symbols}, should be an alist whose elements have the
4005 form @code{(@var{name} . @var{color})}. In each element, @var{name} is
4006 the name of a color as it appears in the image file, and @var{color}
4007 specifies the actual color to use for displaying that name.
4011 @subsection GIF Images
4014 For GIF images, specify image type @code{gif}.
4017 @item :index @var{index}
4018 You can use @code{:index} to specify one image from a GIF file that
4019 contains more than one image. This property specifies use of image
4020 number @var{index} from the file. If the GIF file doesn't contain an
4021 image with index @var{index}, the image displays as a hollow box.
4025 This could be used to implement limited support for animated GIFs.
4026 For example, the following function displays a multi-image GIF file
4027 at point-min in the current buffer, switching between sub-images
4030 (defun show-anim (file max)
4031 "Display multi-image GIF file FILE which contains MAX subimages."
4032 (display-anim (current-buffer) file 0 max t))
4034 (defun display-anim (buffer file idx max first-time)
4037 (let ((img (create-image file nil :image idx)))
4040 (goto-char (point-min))
4041 (unless first-time (delete-char 1))
4043 (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
4046 @node PostScript Images
4047 @subsection PostScript Images
4048 @cindex postscript images
4050 To use PostScript for an image, specify image type @code{postscript}.
4051 This works only if you have Ghostscript installed. You must always use
4052 these three properties:
4055 @item :pt-width @var{width}
4056 The value, @var{width}, specifies the width of the image measured in
4057 points (1/72 inch). @var{width} must be an integer.
4059 @item :pt-height @var{height}
4060 The value, @var{height}, specifies the height of the image in points
4061 (1/72 inch). @var{height} must be an integer.
4063 @item :bounding-box @var{box}
4064 The value, @var{box}, must be a list or vector of four integers, which
4065 specifying the bounding box of the PostScript image, analogous to the
4066 @samp{BoundingBox} comment found in PostScript files.
4069 %%BoundingBox: 22 171 567 738
4073 Displaying PostScript images from Lisp data is not currently
4074 implemented, but it may be implemented by the time you read this.
4075 See the @file{etc/NEWS} file to make sure.
4077 @node Other Image Types
4078 @subsection Other Image Types
4081 For PBM images, specify image type @code{pbm}. Color, gray-scale and
4082 monochromatic images are supported. For mono PBM images, two additional
4083 image properties are supported.
4086 @item :foreground @var{foreground}
4087 The value, @var{foreground}, should be a string specifying the image
4088 foreground color, or @code{nil} for the default color. This color is
4089 used for each pixel in the XBM that is 1. The default is the frame's
4092 @item :background @var{background}
4093 The value, @var{background}, should be a string specifying the image
4094 background color, or @code{nil} for the default color. This color is
4095 used for each pixel in the XBM that is 0. The default is the frame's
4099 For JPEG images, specify image type @code{jpeg}.
4101 For TIFF images, specify image type @code{tiff}.
4103 For PNG images, specify image type @code{png}.
4105 For SVG images, specify image type @code{svg}.
4107 @node Defining Images
4108 @subsection Defining Images
4110 The functions @code{create-image}, @code{defimage} and
4111 @code{find-image} provide convenient ways to create image descriptors.
4113 @defun create-image file-or-data &optional type data-p &rest props
4114 This function creates and returns an image descriptor which uses the
4115 data in @var{file-or-data}. @var{file-or-data} can be a file name or
4116 a string containing the image data; @var{data-p} should be @code{nil}
4117 for the former case, non-@code{nil} for the latter case.
4119 The optional argument @var{type} is a symbol specifying the image type.
4120 If @var{type} is omitted or @code{nil}, @code{create-image} tries to
4121 determine the image type from the file's first few bytes, or else
4122 from the file's name.
4124 The remaining arguments, @var{props}, specify additional image
4125 properties---for example,
4128 (create-image "foo.xpm" 'xpm nil :heuristic-mask t)
4131 The function returns @code{nil} if images of this type are not
4132 supported. Otherwise it returns an image descriptor.
4135 @defmac defimage symbol specs &optional doc
4136 This macro defines @var{symbol} as an image name. The arguments
4137 @var{specs} is a list which specifies how to display the image.
4138 The third argument, @var{doc}, is an optional documentation string.
4140 Each argument in @var{specs} has the form of a property list, and each
4141 one should specify at least the @code{:type} property and either the
4142 @code{:file} or the @code{:data} property. The value of @code{:type}
4143 should be a symbol specifying the image type, the value of
4144 @code{:file} is the file to load the image from, and the value of
4145 @code{:data} is a string containing the actual image data. Here is an
4149 (defimage test-image
4150 ((:type xpm :file "~/test1.xpm")
4151 (:type xbm :file "~/test1.xbm")))
4154 @code{defimage} tests each argument, one by one, to see if it is
4155 usable---that is, if the type is supported and the file exists. The
4156 first usable argument is used to make an image descriptor which is
4157 stored in @var{symbol}.
4159 If none of the alternatives will work, then @var{symbol} is defined
4163 @defun find-image specs
4164 This function provides a convenient way to find an image satisfying one
4165 of a list of image specifications @var{specs}.
4167 Each specification in @var{specs} is a property list with contents
4168 depending on image type. All specifications must at least contain the
4169 properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
4170 or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
4171 the image type, e.g.@: @code{xbm}, @var{file} is the file to load the
4172 image from, and @var{data} is a string containing the actual image data.
4173 The first specification in the list whose @var{type} is supported, and
4174 @var{file} exists, is used to construct the image specification to be
4175 returned. If no specification is satisfied, @code{nil} is returned.
4177 The image is looked for in @code{image-load-path}.
4180 @defvar image-load-path
4181 This variable's value is a list of locations in which to search for
4182 image files. If an element is a string or a variable symbol whose
4183 value is a string, the string is taken to be the name of a directory
4184 to search. If an element is a variable symbol whose value is a list,
4185 that is taken to be a list of directory names to search.
4187 The default is to search in the @file{images} subdirectory of the
4188 directory specified by @code{data-directory}, then the directory
4189 specified by @code{data-directory}, and finally in the directories in
4190 @code{load-path}. Subdirectories are not automatically included in
4191 the search, so if you put an image file in a subdirectory, you have to
4192 supply the subdirectory name explicitly. For example, to find the
4193 image @file{images/foo/bar.xpm} within @code{data-directory}, you
4194 should specify the image as follows:
4197 (defimage foo-image '((:type xpm :file "foo/bar.xpm")))
4201 @defun image-load-path-for-library library image &optional path no-error
4202 This function returns a suitable search path for images used by the
4203 Lisp package @var{library}.
4205 The function searches for @var{image} first using @code{image-load-path},
4206 excluding @file{@code{data-directory}/images}, and then in
4207 @code{load-path}, followed by a path suitable for @var{library}, which
4208 includes @file{../../etc/images} and @file{../etc/images} relative to
4209 the library file itself, and finally in
4210 @file{@code{data-directory}/images}.
4212 Then this function returns a list of directories which contains first
4213 the directory in which @var{image} was found, followed by the value of
4214 @code{load-path}. If @var{path} is given, it is used instead of
4217 If @var{no-error} is non-@code{nil} and a suitable path can't be
4218 found, don't signal an error. Instead, return a list of directories as
4219 before, except that @code{nil} appears in place of the image directory.
4221 Here is an example that uses a common idiom to provide compatibility
4222 with versions of Emacs that lack the variable @code{image-load-path}:
4225 (defvar image-load-path) ; shush compiler
4226 (let* ((load-path (image-load-path-for-library
4227 "mh-e" "mh-logo.xpm"))
4228 (image-load-path (cons (car load-path)
4229 (when (boundp 'image-load-path)
4231 (mh-tool-bar-folder-buttons-init))
4235 @node Showing Images
4236 @subsection Showing Images
4238 You can use an image descriptor by setting up the @code{display}
4239 property yourself, but it is easier to use the functions in this
4242 @defun insert-image image &optional string area slice
4243 This function inserts @var{image} in the current buffer at point. The
4244 value @var{image} should be an image descriptor; it could be a value
4245 returned by @code{create-image}, or the value of a symbol defined with
4246 @code{defimage}. The argument @var{string} specifies the text to put
4247 in the buffer to hold the image. If it is omitted or @code{nil},
4248 @code{insert-image} uses @code{" "} by default.
4250 The argument @var{area} specifies whether to put the image in a margin.
4251 If it is @code{left-margin}, the image appears in the left margin;
4252 @code{right-margin} specifies the right margin. If @var{area} is
4253 @code{nil} or omitted, the image is displayed at point within the
4256 The argument @var{slice} specifies a slice of the image to insert. If
4257 @var{slice} is @code{nil} or omitted the whole image is inserted.
4258 Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width}
4259 @var{height})} which specifies the @var{x} and @var{y} positions and
4260 @var{width} and @var{height} of the image area to insert. Integer
4261 values are in units of pixels. A floating point number in the range
4262 0.0--1.0 stands for that fraction of the width or height of the entire
4265 Internally, this function inserts @var{string} in the buffer, and gives
4266 it a @code{display} property which specifies @var{image}. @xref{Display
4270 @defun insert-sliced-image image &optional string area rows cols
4271 This function inserts @var{image} in the current buffer at point, like
4272 @code{insert-image}, but splits the image into @var{rows}x@var{cols}
4273 equally sized slices.
4276 @defun put-image image pos &optional string area
4277 This function puts image @var{image} in front of @var{pos} in the
4278 current buffer. The argument @var{pos} should be an integer or a
4279 marker. It specifies the buffer position where the image should appear.
4280 The argument @var{string} specifies the text that should hold the image
4281 as an alternative to the default.
4283 The argument @var{image} must be an image descriptor, perhaps returned
4284 by @code{create-image} or stored by @code{defimage}.
4286 The argument @var{area} specifies whether to put the image in a margin.
4287 If it is @code{left-margin}, the image appears in the left margin;
4288 @code{right-margin} specifies the right margin. If @var{area} is
4289 @code{nil} or omitted, the image is displayed at point within the
4292 Internally, this function creates an overlay, and gives it a
4293 @code{before-string} property containing text that has a @code{display}
4294 property whose value is the image. (Whew!)
4297 @defun remove-images start end &optional buffer
4298 This function removes images in @var{buffer} between positions
4299 @var{start} and @var{end}. If @var{buffer} is omitted or @code{nil},
4300 images are removed from the current buffer.
4302 This removes only images that were put into @var{buffer} the way
4303 @code{put-image} does it, not images that were inserted with
4304 @code{insert-image} or in other ways.
4307 @defun image-size spec &optional pixels frame
4308 This function returns the size of an image as a pair
4309 @w{@code{(@var{width} . @var{height})}}. @var{spec} is an image
4310 specification. @var{pixels} non-@code{nil} means return sizes
4311 measured in pixels, otherwise return sizes measured in canonical
4312 character units (fractions of the width/height of the frame's default
4313 font). @var{frame} is the frame on which the image will be displayed.
4314 @var{frame} null or omitted means use the selected frame (@pxref{Input
4318 @defvar max-image-size
4319 This variable is used to define the maximum size of image that Emacs
4320 will load. Emacs will refuse to load (and display) any image that is
4321 larger than this limit.
4323 If the value is an integer, it directly specifies the maximum
4324 image height and width, measured in pixels. If it is a floating
4325 point number, it specifies the maximum image height and width
4326 as a ratio to the frame height and width. If the value is
4327 non-numeric, there is no explicit limit on the size of images.
4329 The purpose of this variable is to prevent unreasonably large images
4330 from accidentally being loaded into Emacs. It only takes effect the
4331 first time an image is loaded. Once an image is placed in the image
4332 cache, it can always be displayed, even if the value of
4333 @var{max-image-size} is subsequently changed (@pxref{Image Cache}).
4337 @subsection Image Cache
4340 Emacs stores images in an image cache so that it can display them
4341 again more efficiently. When Emacs displays an image, it searches the
4342 image cache for an existing image specification @code{equal} to the
4343 desired specification. If a match is found, the image is displayed
4344 from the cache; otherwise, Emacs loads the image normally.
4346 Occasionally, you may need to tell Emacs to refresh the images
4347 associated with a given image specification. For example, suppose you
4348 display an image using a specification that contains a @code{:file}
4349 property. The image is loaded from the given file and stored in the
4350 image cache. If you later display the image again, using the same
4351 image specification, the image is displayed from the image cache.
4352 Normally, this is not a problem. However, if the image file has
4353 changed in the meantime, Emacs would be displaying the old version of
4354 the image. In such a situation, it is necessary to ``refresh'' the
4355 image using @code{image-refresh}.
4357 @defun image-refresh spec &optional frame
4358 This function refreshes any images having image specifications
4359 @code{equal} to @var{spec} on frame @var{frame}. If @var{frame} is
4360 @code{nil}, the selected frame is used. If @var{frame} is @code{t},
4361 the refresh is applied to all existing frames.
4363 This works by removing all image with image specifications matching
4364 @var{spec} from the image cache. Thus, the next time the image is
4365 displayed, Emacs will load the image again.
4368 @defun clear-image-cache &optional frame
4369 This function clears the entire image cache. If @var{frame} is
4370 non-@code{nil}, only the cache for that frame is cleared. Otherwise,
4371 all frames' caches are cleared.
4374 If an image in the image cache has not been displayed for a specified
4375 period of time, Emacs removes it from the cache and frees the
4378 @defvar image-cache-eviction-delay
4379 This variable specifies the number of seconds an image can remain in the
4380 cache without being displayed. When an image is not displayed for this
4381 length of time, Emacs removes it from the image cache.
4383 If the value is @code{nil}, Emacs does not remove images from the cache
4384 except when you explicitly clear it. This mode can be useful for
4390 @cindex buttons in buffers
4391 @cindex clickable buttons in buffers
4393 The @emph{button} package defines functions for inserting and
4394 manipulating clickable (with the mouse, or via keyboard commands)
4395 buttons in Emacs buffers, such as might be used for help hyper-links,
4396 etc. Emacs uses buttons for the hyper-links in help text and the like.
4398 A button is essentially a set of properties attached (via text
4399 properties or overlays) to a region of text in an Emacs buffer. These
4400 properties are called @dfn{button properties}.
4402 One of these properties (@code{action}) is a function, which will
4403 be called when the user invokes it using the keyboard or the mouse.
4404 The invoked function may then examine the button and use its other
4405 properties as desired.
4407 In some ways the Emacs button package duplicates functionality offered
4408 by the widget package (@pxref{Top, , Introduction, widget, The Emacs
4409 Widget Library}), but the button package has the advantage that it is
4410 much faster, much smaller, and much simpler to use (for elisp
4411 programmers---for users, the result is about the same). The extra
4412 speed and space savings are useful mainly if you need to create many
4413 buttons in a buffer (for instance an @code{*Apropos*} buffer uses
4414 buttons to make entries clickable, and may contain many thousands of
4418 * Button Properties:: Button properties with special meanings.
4419 * Button Types:: Defining common properties for classes of buttons.
4420 * Making Buttons:: Adding buttons to Emacs buffers.
4421 * Manipulating Buttons:: Getting and setting properties of buttons.
4422 * Button Buffer Commands:: Buffer-wide commands and bindings for buttons.
4425 @node Button Properties
4426 @subsection Button Properties
4427 @cindex button properties
4429 Buttons have an associated list of properties defining their
4430 appearance and behavior, and other arbitrary properties may be used
4431 for application specific purposes. Some properties that have special
4432 meaning to the button package include:
4436 @kindex action @r{(button property)}
4437 The function to call when the user invokes the button, which is passed
4438 the single argument @var{button}. By default this is @code{ignore},
4442 @kindex mouse-action @r{(button property)}
4443 This is similar to @code{action}, and when present, will be used
4444 instead of @code{action} for button invocations resulting from
4445 mouse-clicks (instead of the user hitting @key{RET}). If not
4446 present, mouse-clicks use @code{action} instead.
4449 @kindex face @r{(button property)}
4450 This is an Emacs face controlling how buttons of this type are
4451 displayed; by default this is the @code{button} face.
4454 @kindex mouse-face @r{(button property)}
4455 This is an additional face which controls appearance during
4456 mouse-overs (merged with the usual button face); by default this is
4457 the usual Emacs @code{highlight} face.
4460 @kindex keymap @r{(button property)}
4461 The button's keymap, defining bindings active within the button
4462 region. By default this is the usual button region keymap, stored
4463 in the variable @code{button-map}, which defines @key{RET} and
4464 @key{mouse-2} to invoke the button.
4467 @kindex type @r{(button property)}
4468 The button-type of the button. When creating a button, this is
4469 usually specified using the @code{:type} keyword argument.
4470 @xref{Button Types}.
4473 @kindex help-index @r{(button property)}
4474 A string displayed by the Emacs tool-tip help system; by default,
4475 @code{"mouse-2, RET: Push this button"}.
4478 @kindex follow-link @r{(button property)}
4479 The follow-link property, defining how a @key{Mouse-1} click behaves
4480 on this button, @xref{Links and Mouse-1}.
4483 @kindex button @r{(button property)}
4484 All buttons have a non-@code{nil} @code{button} property, which may be useful
4485 in finding regions of text that comprise buttons (which is what the
4486 standard button functions do).
4489 There are other properties defined for the regions of text in a
4490 button, but these are not generally interesting for typical uses.
4493 @subsection Button Types
4494 @cindex button types
4496 Every button has a button @emph{type}, which defines default values
4497 for the button's properties. Button types are arranged in a
4498 hierarchy, with specialized types inheriting from more general types,
4499 so that it's easy to define special-purpose types of buttons for
4502 @defun define-button-type name &rest properties
4503 Define a `button type' called @var{name}. The remaining arguments
4504 form a sequence of @var{property value} pairs, specifying default
4505 property values for buttons with this type (a button's type may be set
4506 by giving it a @code{type} property when creating the button, using
4507 the @code{:type} keyword argument).
4509 In addition, the keyword argument @code{:supertype} may be used to
4510 specify a button-type from which @var{name} inherits its default
4511 property values. Note that this inheritance happens only when
4512 @var{name} is defined; subsequent changes to a supertype are not
4513 reflected in its subtypes.
4516 Using @code{define-button-type} to define default properties for
4517 buttons is not necessary---buttons without any specified type use the
4518 built-in button-type @code{button}---but it is encouraged, since
4519 doing so usually makes the resulting code clearer and more efficient.
4521 @node Making Buttons
4522 @subsection Making Buttons
4523 @cindex making buttons
4525 Buttons are associated with a region of text, using an overlay or
4526 text properties to hold button-specific information, all of which are
4527 initialized from the button's type (which defaults to the built-in
4528 button type @code{button}). Like all Emacs text, the appearance of
4529 the button is governed by the @code{face} property; by default (via
4530 the @code{face} property inherited from the @code{button} button-type)
4531 this is a simple underline, like a typical web-page link.
4533 For convenience, there are two sorts of button-creation functions,
4534 those that add button properties to an existing region of a buffer,
4535 called @code{make-...button}, and those that also insert the button
4536 text, called @code{insert-...button}.
4538 The button-creation functions all take the @code{&rest} argument
4539 @var{properties}, which should be a sequence of @var{property value}
4540 pairs, specifying properties to add to the button; see @ref{Button
4541 Properties}. In addition, the keyword argument @code{:type} may be
4542 used to specify a button-type from which to inherit other properties;
4543 see @ref{Button Types}. Any properties not explicitly specified
4544 during creation will be inherited from the button's type (if the type
4545 defines such a property).
4547 The following functions add a button using an overlay
4548 (@pxref{Overlays}) to hold the button properties:
4550 @defun make-button beg end &rest properties
4551 This makes a button from @var{beg} to @var{end} in the
4552 current buffer, and returns it.
4555 @defun insert-button label &rest properties
4556 This insert a button with the label @var{label} at point,
4560 The following functions are similar, but use Emacs text properties
4561 (@pxref{Text Properties}) to hold the button properties, making the
4562 button actually part of the text instead of being a property of the
4563 buffer. Buttons using text properties do not create markers into the
4564 buffer, which is important for speed when you use extremely large
4565 numbers of buttons. Both functions return the position of the start
4568 @defun make-text-button beg end &rest properties
4569 This makes a button from @var{beg} to @var{end} in the current buffer, using
4573 @defun insert-text-button label &rest properties
4574 This inserts a button with the label @var{label} at point, using text
4578 @node Manipulating Buttons
4579 @subsection Manipulating Buttons
4580 @cindex manipulating buttons
4582 These are functions for getting and setting properties of buttons.
4583 Often these are used by a button's invocation function to determine
4586 Where a @var{button} parameter is specified, it means an object
4587 referring to a specific button, either an overlay (for overlay
4588 buttons), or a buffer-position or marker (for text property buttons).
4589 Such an object is passed as the first argument to a button's
4590 invocation function when it is invoked.
4592 @defun button-start button
4593 Return the position at which @var{button} starts.
4596 @defun button-end button
4597 Return the position at which @var{button} ends.
4600 @defun button-get button prop
4601 Get the property of button @var{button} named @var{prop}.
4604 @defun button-put button prop val
4605 Set @var{button}'s @var{prop} property to @var{val}.
4608 @defun button-activate button &optional use-mouse-action
4609 Call @var{button}'s @code{action} property (i.e., invoke it). If
4610 @var{use-mouse-action} is non-@code{nil}, try to invoke the button's
4611 @code{mouse-action} property instead of @code{action}; if the button
4612 has no @code{mouse-action} property, use @code{action} as normal.
4615 @defun button-label button
4616 Return @var{button}'s text label.
4619 @defun button-type button
4620 Return @var{button}'s button-type.
4623 @defun button-has-type-p button type
4624 Return @code{t} if @var{button} has button-type @var{type}, or one of
4625 @var{type}'s subtypes.
4628 @defun button-at pos
4629 Return the button at position @var{pos} in the current buffer, or @code{nil}.
4632 @defun button-type-put type prop val
4633 Set the button-type @var{type}'s @var{prop} property to @var{val}.
4636 @defun button-type-get type prop
4637 Get the property of button-type @var{type} named @var{prop}.
4640 @defun button-type-subtype-p type supertype
4641 Return @code{t} if button-type @var{type} is a subtype of @var{supertype}.
4644 @node Button Buffer Commands
4645 @subsection Button Buffer Commands
4646 @cindex button buffer commands
4648 These are commands and functions for locating and operating on
4649 buttons in an Emacs buffer.
4651 @code{push-button} is the command that a user uses to actually `push'
4652 a button, and is bound by default in the button itself to @key{RET}
4653 and to @key{mouse-2} using a region-specific keymap. Commands
4654 that are useful outside the buttons itself, such as
4655 @code{forward-button} and @code{backward-button} are additionally
4656 available in the keymap stored in @code{button-buffer-map}; a mode
4657 which uses buttons may want to use @code{button-buffer-map} as a
4658 parent keymap for its keymap.
4660 If the button has a non-@code{nil} @code{follow-link} property, and
4661 @var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click
4662 will also activate the @code{push-button} command.
4663 @xref{Links and Mouse-1}.
4665 @deffn Command push-button &optional pos use-mouse-action
4666 Perform the action specified by a button at location @var{pos}.
4667 @var{pos} may be either a buffer position or a mouse-event. If
4668 @var{use-mouse-action} is non-@code{nil}, or @var{pos} is a
4669 mouse-event (@pxref{Mouse Events}), try to invoke the button's
4670 @code{mouse-action} property instead of @code{action}; if the button
4671 has no @code{mouse-action} property, use @code{action} as normal.
4672 @var{pos} defaults to point, except when @code{push-button} is invoked
4673 interactively as the result of a mouse-event, in which case, the mouse
4674 event's position is used. If there's no button at @var{pos}, do
4675 nothing and return @code{nil}, otherwise return @code{t}.
4678 @deffn Command forward-button n &optional wrap display-message
4679 Move to the @var{n}th next button, or @var{n}th previous button if
4680 @var{n} is negative. If @var{n} is zero, move to the start of any
4681 button at point. If @var{wrap} is non-@code{nil}, moving past either
4682 end of the buffer continues from the other end. If
4683 @var{display-message} is non-@code{nil}, the button's help-echo string
4684 is displayed. Any button with a non-@code{nil} @code{skip} property
4685 is skipped over. Returns the button found.
4688 @deffn Command backward-button n &optional wrap display-message
4689 Move to the @var{n}th previous button, or @var{n}th next button if
4690 @var{n} is negative. If @var{n} is zero, move to the start of any
4691 button at point. If @var{wrap} is non-@code{nil}, moving past either
4692 end of the buffer continues from the other end. If
4693 @var{display-message} is non-@code{nil}, the button's help-echo string
4694 is displayed. Any button with a non-@code{nil} @code{skip} property
4695 is skipped over. Returns the button found.
4698 @defun next-button pos &optional count-current
4699 @defunx previous-button pos &optional count-current
4700 Return the next button after (for @code{next-button} or before (for
4701 @code{previous-button}) position @var{pos} in the current buffer. If
4702 @var{count-current} is non-@code{nil}, count any button at @var{pos}
4703 in the search, instead of starting at the next button.
4706 @node Abstract Display
4707 @section Abstract Display
4709 @cindex display, abstract
4710 @cindex display, arbitrary objects
4711 @cindex model/view/controller
4712 @cindex view part, model/view/controller
4714 The Ewoc package constructs buffer text that represents a structure
4715 of Lisp objects, and updates the text to follow changes in that
4716 structure. This is like the ``view'' component in the
4717 ``model/view/controller'' design paradigm.
4719 An @dfn{ewoc} is a structure that organizes information required to
4720 construct buffer text that represents certain Lisp data. The buffer
4721 text of the ewoc has three parts, in order: first, fixed @dfn{header}
4722 text; next, textual descriptions of a series of data elements (Lisp
4723 objects that you specify); and last, fixed @dfn{footer} text.
4724 Specifically, an ewoc contains information on:
4728 The buffer which its text is generated in.
4731 The text's start position in the buffer.
4734 The header and footer strings.
4737 A doubly-linked chain of @dfn{nodes}, each of which contains:
4741 A @dfn{data element}, a single Lisp object.
4744 Links to the preceding and following nodes in the chain.
4748 A @dfn{pretty-printer} function which is responsible for
4749 inserting the textual representation of a data
4750 element value into the current buffer.
4753 Typically, you define an ewoc with @code{ewoc-create}, and then pass
4754 the resulting ewoc structure to other functions in the Ewoc package to
4755 build nodes within it, and display it in the buffer. Once it is
4756 displayed in the buffer, other functions determine the correspondance
4757 between buffer positions and nodes, move point from one node's textual
4758 representation to another, and so forth. @xref{Abstract Display
4761 A node @dfn{encapsulates} a data element much the way a variable
4762 holds a value. Normally, encapsulation occurs as a part of adding a
4763 node to the ewoc. You can retrieve the data element value and place a
4764 new value in its place, like so:
4767 (ewoc-data @var{node})
4770 (ewoc-set-data @var{node} @var{new-value})
4771 @result{} @var{new-value}
4775 You can also use, as the data element value, a Lisp object (list or
4776 vector) that is a container for the ``real'' value, or an index into
4777 some other structure. The example (@pxref{Abstract Display Example})
4778 uses the latter approach.
4780 When the data changes, you will want to update the text in the
4781 buffer. You can update all nodes by calling @code{ewoc-refresh}, or
4782 just specific nodes using @code{ewoc-invalidate}, or all nodes
4783 satisfying a predicate using @code{ewoc-map}. Alternatively, you can
4784 delete invalid nodes using @code{ewoc-delete} or @code{ewoc-filter},
4785 and add new nodes in their place. Deleting a node from an ewoc deletes
4786 its associated textual description from buffer, as well.
4789 * Abstract Display Functions::
4790 * Abstract Display Example::
4793 @node Abstract Display Functions
4794 @subsection Abstract Display Functions
4796 In this subsection, @var{ewoc} and @var{node} stand for the
4797 structures described above (@pxref{Abstract Display}), while
4798 @var{data} stands for an arbitrary Lisp object used as a data element.
4800 @defun ewoc-create pretty-printer &optional header footer nosep
4801 This constructs and returns a new ewoc, with no nodes (and thus no data
4802 elements). @var{pretty-printer} should be a function that takes one
4803 argument, a data element of the sort you plan to use in this ewoc, and
4804 inserts its textual description at point using @code{insert} (and never
4805 @code{insert-before-markers}, because that would interfere with the
4806 Ewoc package's internal mechanisms).
4808 Normally, a newline is automatically inserted after the header,
4809 the footer and every node's textual description. If @var{nosep}
4810 is non-@code{nil}, no newline is inserted. This may be useful for
4811 displaying an entire ewoc on a single line, for example, or for
4812 making nodes ``invisible'' by arranging for @var{pretty-printer}
4813 to do nothing for those nodes.
4815 An ewoc maintains its text in the buffer that is current when
4816 you create it, so switch to the intended buffer before calling
4820 @defun ewoc-buffer ewoc
4821 This returns the buffer where @var{ewoc} maintains its text.
4824 @defun ewoc-get-hf ewoc
4825 This returns a cons cell @code{(@var{header} . @var{footer})}
4826 made from @var{ewoc}'s header and footer.
4829 @defun ewoc-set-hf ewoc header footer
4830 This sets the header and footer of @var{ewoc} to the strings
4831 @var{header} and @var{footer}, respectively.
4834 @defun ewoc-enter-first ewoc data
4835 @defunx ewoc-enter-last ewoc data
4836 These add a new node encapsulating @var{data}, putting it, respectively,
4837 at the beginning or end of @var{ewoc}'s chain of nodes.
4840 @defun ewoc-enter-before ewoc node data
4841 @defunx ewoc-enter-after ewoc node data
4842 These add a new node encapsulating @var{data}, adding it to
4843 @var{ewoc} before or after @var{node}, respectively.
4846 @defun ewoc-prev ewoc node
4847 @defunx ewoc-next ewoc node
4848 These return, respectively, the previous node and the next node of @var{node}
4852 @defun ewoc-nth ewoc n
4853 This returns the node in @var{ewoc} found at zero-based index @var{n}.
4854 A negative @var{n} means count from the end. @code{ewoc-nth} returns
4855 @code{nil} if @var{n} is out of range.
4858 @defun ewoc-data node
4859 This extracts the data encapsulated by @var{node} and returns it.
4862 @defun ewoc-set-data node data
4863 This sets the data encapsulated by @var{node} to @var{data}.
4866 @defun ewoc-locate ewoc &optional pos guess
4867 This determines the node in @var{ewoc} which contains point (or
4868 @var{pos} if specified), and returns that node. If @var{ewoc} has no
4869 nodes, it returns @code{nil}. If @var{pos} is before the first node,
4870 it returns the first node; if @var{pos} is after the last node, it returns
4871 the last node. The optional third arg @var{guess}
4872 should be a node that is likely to be near @var{pos}; this doesn't
4873 alter the result, but makes the function run faster.
4876 @defun ewoc-location node
4877 This returns the start position of @var{node}.
4880 @defun ewoc-goto-prev ewoc arg
4881 @defunx ewoc-goto-next ewoc arg
4882 These move point to the previous or next, respectively, @var{arg}th node
4883 in @var{ewoc}. @code{ewoc-goto-prev} does not move if it is already at
4884 the first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next}
4885 moves past the last node, returning @code{nil}. Excepting this special
4886 case, these functions return the node moved to.
4889 @defun ewoc-goto-node ewoc node
4890 This moves point to the start of @var{node} in @var{ewoc}.
4893 @defun ewoc-refresh ewoc
4894 This function regenerates the text of @var{ewoc}. It works by
4895 deleting the text between the header and the footer, i.e., all the
4896 data elements' representations, and then calling the pretty-printer
4897 function for each node, one by one, in order.
4900 @defun ewoc-invalidate ewoc &rest nodes
4901 This is similar to @code{ewoc-refresh}, except that only @var{nodes} in
4902 @var{ewoc} are updated instead of the entire set.
4905 @defun ewoc-delete ewoc &rest nodes
4906 This deletes each node in @var{nodes} from @var{ewoc}.
4909 @defun ewoc-filter ewoc predicate &rest args
4910 This calls @var{predicate} for each data element in @var{ewoc} and
4911 deletes those nodes for which @var{predicate} returns @code{nil}.
4912 Any @var{args} are passed to @var{predicate}.
4915 @defun ewoc-collect ewoc predicate &rest args
4916 This calls @var{predicate} for each data element in @var{ewoc}
4917 and returns a list of those elements for which @var{predicate}
4918 returns non-@code{nil}. The elements in the list are ordered
4919 as in the buffer. Any @var{args} are passed to @var{predicate}.
4922 @defun ewoc-map map-function ewoc &rest args
4923 This calls @var{map-function} for each data element in @var{ewoc} and
4924 updates those nodes for which @var{map-function} returns non-@code{nil}.
4925 Any @var{args} are passed to @var{map-function}.
4928 @node Abstract Display Example
4929 @subsection Abstract Display Example
4931 Here is a simple example using functions of the ewoc package to
4932 implement a ``color components display,'' an area in a buffer that
4933 represents a vector of three integers (itself representing a 24-bit RGB
4934 value) in various ways.
4937 (setq colorcomp-ewoc nil
4939 colorcomp-mode-map nil
4940 colorcomp-labels ["Red" "Green" "Blue"])
4942 (defun colorcomp-pp (data)
4944 (let ((comp (aref colorcomp-data data)))
4945 (insert (aref colorcomp-labels data) "\t: #x"
4946 (format "%02X" comp) " "
4947 (make-string (ash comp -2) ?#) "\n"))
4948 (let ((cstr (format "#%02X%02X%02X"
4949 (aref colorcomp-data 0)
4950 (aref colorcomp-data 1)
4951 (aref colorcomp-data 2)))
4952 (samp " (sample text) "))
4954 (propertize samp 'face `(foreground-color . ,cstr))
4955 (propertize samp 'face `(background-color . ,cstr))
4958 (defun colorcomp (color)
4959 "Allow fiddling with COLOR in a new buffer.
4960 The buffer is in Color Components mode."
4961 (interactive "sColor (name or #RGB or #RRGGBB): ")
4962 (when (string= "" color)
4963 (setq color "green"))
4964 (unless (color-values color)
4965 (error "No such color: %S" color))
4967 (generate-new-buffer (format "originally: %s" color)))
4968 (kill-all-local-variables)
4969 (setq major-mode 'colorcomp-mode
4970 mode-name "Color Components")
4971 (use-local-map colorcomp-mode-map)
4973 (buffer-disable-undo)
4974 (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8))
4975 (color-values color))))
4976 (ewoc (ewoc-create 'colorcomp-pp
4977 "\nColor Components\n\n"
4978 (substitute-command-keys
4979 "\n\\@{colorcomp-mode-map@}"))))
4980 (set (make-local-variable 'colorcomp-data) data)
4981 (set (make-local-variable 'colorcomp-ewoc) ewoc)
4982 (ewoc-enter-last ewoc 0)
4983 (ewoc-enter-last ewoc 1)
4984 (ewoc-enter-last ewoc 2)
4985 (ewoc-enter-last ewoc nil)))
4988 @cindex controller part, model/view/controller
4989 This example can be extended to be a ``color selection widget'' (in
4990 other words, the controller part of the ``model/view/controller''
4991 design paradigm) by defining commands to modify @code{colorcomp-data}
4992 and to ``finish'' the selection process, and a keymap to tie it all
4993 together conveniently.
4996 (defun colorcomp-mod (index limit delta)
4997 (let ((cur (aref colorcomp-data index)))
4998 (unless (= limit cur)
4999 (aset colorcomp-data index (+ cur delta)))
5002 (ewoc-nth colorcomp-ewoc index)
5003 (ewoc-nth colorcomp-ewoc -1))))
5005 (defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1))
5006 (defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1))
5007 (defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1))
5008 (defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1))
5009 (defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1))
5010 (defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1))
5012 (defun colorcomp-copy-as-kill-and-exit ()
5013 "Copy the color components into the kill ring and kill the buffer.
5014 The string is formatted #RRGGBB (hash followed by six hex digits)."
5016 (kill-new (format "#%02X%02X%02X"
5017 (aref colorcomp-data 0)
5018 (aref colorcomp-data 1)
5019 (aref colorcomp-data 2)))
5022 (setq colorcomp-mode-map
5023 (let ((m (make-sparse-keymap)))
5025 (define-key m "i" 'colorcomp-R-less)
5026 (define-key m "o" 'colorcomp-R-more)
5027 (define-key m "k" 'colorcomp-G-less)
5028 (define-key m "l" 'colorcomp-G-more)
5029 (define-key m "," 'colorcomp-B-less)
5030 (define-key m "." 'colorcomp-B-more)
5031 (define-key m " " 'colorcomp-copy-as-kill-and-exit)
5035 Note that we never modify the data in each node, which is fixed when the
5036 ewoc is created to be either @code{nil} or an index into the vector
5037 @code{colorcomp-data}, the actual color components.
5040 @section Blinking Parentheses
5041 @cindex parenthesis matching
5042 @cindex blinking parentheses
5043 @cindex balancing parentheses
5045 This section describes the mechanism by which Emacs shows a matching
5046 open parenthesis when the user inserts a close parenthesis.
5048 @defvar blink-paren-function
5049 The value of this variable should be a function (of no arguments) to
5050 be called whenever a character with close parenthesis syntax is inserted.
5051 The value of @code{blink-paren-function} may be @code{nil}, in which
5052 case nothing is done.
5055 @defopt blink-matching-paren
5056 If this variable is @code{nil}, then @code{blink-matching-open} does
5060 @defopt blink-matching-paren-distance
5061 This variable specifies the maximum distance to scan for a matching
5062 parenthesis before giving up.
5065 @defopt blink-matching-delay
5066 This variable specifies the number of seconds for the cursor to remain
5067 at the matching parenthesis. A fraction of a second often gives
5068 good results, but the default is 1, which works on all systems.
5071 @deffn Command blink-matching-open
5072 This function is the default value of @code{blink-paren-function}. It
5073 assumes that point follows a character with close parenthesis syntax and
5074 moves the cursor momentarily to the matching opening character. If that
5075 character is not already on the screen, it displays the character's
5076 context in the echo area. To avoid long delays, this function does not
5077 search farther than @code{blink-matching-paren-distance} characters.
5079 Here is an example of calling this function explicitly.
5083 (defun interactive-blink-matching-open ()
5084 @c Do not break this line! -- rms.
5085 @c The first line of a doc string
5086 @c must stand alone.
5087 "Indicate momentarily the start of sexp before point."
5091 (let ((blink-matching-paren-distance
5093 (blink-matching-paren t))
5094 (blink-matching-open)))
5100 @section Usual Display Conventions
5102 The usual display conventions define how to display each character
5103 code. You can override these conventions by setting up a display table
5104 (@pxref{Display Tables}). Here are the usual display conventions:
5108 Character codes 32 through 126 map to glyph codes 32 through 126.
5109 Normally this means they display as themselves.
5112 Character code 9 is a horizontal tab. It displays as whitespace
5113 up to a position determined by @code{tab-width}.
5116 Character code 10 is a newline.
5119 All other codes in the range 0 through 31, and code 127, display in one
5120 of two ways according to the value of @code{ctl-arrow}. If it is
5121 non-@code{nil}, these codes map to sequences of two glyphs, where the
5122 first glyph is the @acronym{ASCII} code for @samp{^}. (A display table can
5123 specify a glyph to use instead of @samp{^}.) Otherwise, these codes map
5124 just like the codes in the range 128 to 255.
5126 On MS-DOS terminals, Emacs arranges by default for the character code
5127 127 to be mapped to the glyph code 127, which normally displays as an
5128 empty polygon. This glyph is used to display non-@acronym{ASCII} characters
5129 that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,,
5130 emacs, The GNU Emacs Manual}.
5133 Character codes 128 through 255 map to sequences of four glyphs, where
5134 the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are
5135 digit characters representing the character code in octal. (A display
5136 table can specify a glyph to use instead of @samp{\}.)
5139 Multibyte character codes above 256 are displayed as themselves, or as a
5140 question mark or empty box if the terminal cannot display that
5144 The usual display conventions apply even when there is a display
5145 table, for any character whose entry in the active display table is
5146 @code{nil}. Thus, when you set up a display table, you need only
5147 specify the characters for which you want special behavior.
5149 These display rules apply to carriage return (character code 13), when
5150 it appears in the buffer. But that character may not appear in the
5151 buffer where you expect it, if it was eliminated as part of end-of-line
5152 conversion (@pxref{Coding System Basics}).
5154 These variables affect the way certain characters are displayed on the
5155 screen. Since they change the number of columns the characters occupy,
5156 they also affect the indentation functions. These variables also affect
5157 how the mode line is displayed; if you want to force redisplay of the
5158 mode line using the new values, call the function
5159 @code{force-mode-line-update} (@pxref{Mode Line Format}).
5162 @cindex control characters in display
5163 This buffer-local variable controls how control characters are
5164 displayed. If it is non-@code{nil}, they are displayed as a caret
5165 followed by the character: @samp{^A}. If it is @code{nil}, they are
5166 displayed as a backslash followed by three octal digits: @samp{\001}.
5169 @c Following may have overfull hbox.
5170 @defvar default-ctl-arrow
5171 The value of this variable is the default value for @code{ctl-arrow} in
5172 buffers that do not override it. @xref{Default Value}.
5176 The value of this buffer-local variable is the spacing between tab
5177 stops used for displaying tab characters in Emacs buffers. The value
5178 is in units of columns, and the default is 8. Note that this feature
5179 is completely independent of the user-settable tab stops used by the
5180 command @code{tab-to-tab-stop}. @xref{Indent Tabs}.
5183 @node Display Tables
5184 @section Display Tables
5186 @cindex display table
5187 You can use the @dfn{display table} feature to control how all possible
5188 character codes display on the screen. This is useful for displaying
5189 European languages that have letters not in the @acronym{ASCII} character
5192 The display table maps each character code into a sequence of
5193 @dfn{glyphs}, each glyph being a graphic that takes up one character
5194 position on the screen. You can also define how to display each glyph
5195 on your terminal, using the @dfn{glyph table}.
5197 Display tables affect how the mode line is displayed; if you want to
5198 force redisplay of the mode line using a new display table, call
5199 @code{force-mode-line-update} (@pxref{Mode Line Format}).
5202 * Display Table Format:: What a display table consists of.
5203 * Active Display Table:: How Emacs selects a display table to use.
5204 * Glyphs:: How to define a glyph, and what glyphs mean.
5207 @node Display Table Format
5208 @subsection Display Table Format
5210 A display table is actually a char-table (@pxref{Char-Tables}) with
5211 @code{display-table} as its subtype.
5213 @defun make-display-table
5214 This creates and returns a display table. The table initially has
5215 @code{nil} in all elements.
5218 The ordinary elements of the display table are indexed by character
5219 codes; the element at index @var{c} says how to display the character
5220 code @var{c}. The value should be @code{nil} or a vector of the
5221 glyphs to be output (@pxref{Glyphs}). @code{nil} says to display the
5222 character @var{c} according to the usual display conventions
5223 (@pxref{Usual Display}).
5225 @strong{Warning:} if you use the display table to change the display
5226 of newline characters, the whole buffer will be displayed as one long
5229 The display table also has six ``extra slots'' which serve special
5230 purposes. Here is a table of their meanings; @code{nil} in any slot
5231 means to use the default for that slot, as stated below.
5235 The glyph for the end of a truncated screen line (the default for this
5236 is @samp{$}). @xref{Glyphs}. On graphical terminals, Emacs uses
5237 arrows in the fringes to indicate truncation, so the display table has
5241 The glyph for the end of a continued line (the default is @samp{\}).
5242 On graphical terminals, Emacs uses curved arrows in the fringes to
5243 indicate continuation, so the display table has no effect.
5246 The glyph for indicating a character displayed as an octal character
5247 code (the default is @samp{\}).
5250 The glyph for indicating a control character (the default is @samp{^}).
5253 A vector of glyphs for indicating the presence of invisible lines (the
5254 default is @samp{...}). @xref{Selective Display}.
5257 The glyph used to draw the border between side-by-side windows (the
5258 default is @samp{|}). @xref{Splitting Windows}. This takes effect only
5259 when there are no scroll bars; if scroll bars are supported and in use,
5260 a scroll bar separates the two windows.
5263 For example, here is how to construct a display table that mimics the
5264 effect of setting @code{ctl-arrow} to a non-@code{nil} value:
5267 (setq disptab (make-display-table))
5270 (or (= i ?\t) (= i ?\n)
5271 (aset disptab i (vector ?^ (+ i 64))))
5273 (aset disptab 127 (vector ?^ ??)))
5276 @defun display-table-slot display-table slot
5277 This function returns the value of the extra slot @var{slot} of
5278 @var{display-table}. The argument @var{slot} may be a number from 0 to
5279 5 inclusive, or a slot name (symbol). Valid symbols are
5280 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
5281 @code{selective-display}, and @code{vertical-border}.
5284 @defun set-display-table-slot display-table slot value
5285 This function stores @var{value} in the extra slot @var{slot} of
5286 @var{display-table}. The argument @var{slot} may be a number from 0 to
5287 5 inclusive, or a slot name (symbol). Valid symbols are
5288 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
5289 @code{selective-display}, and @code{vertical-border}.
5292 @defun describe-display-table display-table
5293 This function displays a description of the display table
5294 @var{display-table} in a help buffer.
5297 @deffn Command describe-current-display-table
5298 This command displays a description of the current display table in a
5302 @node Active Display Table
5303 @subsection Active Display Table
5304 @cindex active display table
5306 Each window can specify a display table, and so can each buffer. When
5307 a buffer @var{b} is displayed in window @var{w}, display uses the
5308 display table for window @var{w} if it has one; otherwise, the display
5309 table for buffer @var{b} if it has one; otherwise, the standard display
5310 table if any. The display table chosen is called the @dfn{active}
5313 @defun window-display-table &optional window
5314 This function returns @var{window}'s display table, or @code{nil}
5315 if @var{window} does not have an assigned display table. The default
5316 for @var{window} is the selected window.
5319 @defun set-window-display-table window table
5320 This function sets the display table of @var{window} to @var{table}.
5321 The argument @var{table} should be either a display table or
5325 @defvar buffer-display-table
5326 This variable is automatically buffer-local in all buffers; its value in
5327 a particular buffer specifies the display table for that buffer. If it
5328 is @code{nil}, that means the buffer does not have an assigned display
5332 @defvar standard-display-table
5333 This variable's value is the default display table, used whenever a
5334 window has no display table and neither does the buffer displayed in
5335 that window. This variable is @code{nil} by default.
5338 If there is no display table to use for a particular window---that is,
5339 if the window specifies none, its buffer specifies none, and
5340 @code{standard-display-table} is @code{nil}---then Emacs uses the usual
5341 display conventions for all character codes in that window. @xref{Usual
5344 A number of functions for changing the standard display table
5345 are defined in the library @file{disp-table}.
5351 A @dfn{glyph} is a generalization of a character; it stands for an
5352 image that takes up a single character position on the screen. Normally
5353 glyphs come from vectors in the display table (@pxref{Display Tables}).
5355 A glyph is represented in Lisp as a @dfn{glyph code}. A glyph code
5356 can be @dfn{simple} or it can be defined by the @dfn{glyph table}. A
5357 simple glyph code is just a way of specifying a character and a face
5358 to output it in. @xref{Faces}.
5360 The following functions are used to manipulate simple glyph codes:
5362 @defun make-glyph-code char &optional face
5363 This function returns a simple glyph code representing char @var{char}
5364 with face @var{face}.
5367 @defun glyph-char glyph
5368 This function returns the character of simple glyph code @var{glyph}.
5371 @defun glyph-face glyph
5372 This function returns face of simple glyph code @var{glyph}, or
5373 @code{nil} if @var{glyph} has the default face (face-id 0).
5376 On character terminals, you can set up a @dfn{glyph table} to define
5377 the meaning of glyph codes (represented as small integers).
5380 The value of this variable is the current glyph table. It should be
5381 @code{nil} or a vector whose @var{g}th element defines glyph code
5384 If a glyph code is greater than or equal to the length of the glyph
5385 table, that code is automatically simple. If @code{glyph-table} is
5386 @code{nil} then all glyph codes are simple.
5388 The glyph table is used only on character terminals. On graphical
5389 displays, all glyph codes are simple.
5392 Here are the meaningful types of elements in the glyph table:
5396 Send the characters in @var{string} to the terminal to output
5400 Define this glyph code as an alias for glyph code @var{code} created
5401 by @code{make-glyph-code}. You can use such an alias to define a
5402 small-numbered glyph code which specifies a character with a face.
5405 This glyph code is simple.
5408 @defun create-glyph string
5409 This function returns a newly-allocated glyph code which is set up to
5410 display by sending @var{string} to the terminal.
5415 @c @cindex beeping "beep" is adjacent
5418 This section describes how to make Emacs ring the bell (or blink the
5419 screen) to attract the user's attention. Be conservative about how
5420 often you do this; frequent bells can become irritating. Also be
5421 careful not to use just beeping when signaling an error is more
5422 appropriate. (@xref{Errors}.)
5424 @defun ding &optional do-not-terminate
5425 @cindex keyboard macro termination
5426 This function beeps, or flashes the screen (see @code{visible-bell} below).
5427 It also terminates any keyboard macro currently executing unless
5428 @var{do-not-terminate} is non-@code{nil}.
5431 @defun beep &optional do-not-terminate
5432 This is a synonym for @code{ding}.
5435 @defopt visible-bell
5436 This variable determines whether Emacs should flash the screen to
5437 represent a bell. Non-@code{nil} means yes, @code{nil} means no. This
5438 is effective on graphical displays, and on text-only terminals
5439 provided the terminal's Termcap entry defines the visible bell
5440 capability (@samp{vb}).
5443 @defvar ring-bell-function
5444 If this is non-@code{nil}, it specifies how Emacs should ``ring the
5445 bell.'' Its value should be a function of no arguments. If this is
5446 non-@code{nil}, it takes precedence over the @code{visible-bell}
5450 @node Window Systems
5451 @section Window Systems
5453 Emacs works with several window systems, most notably the X Window
5454 System. Both Emacs and X use the term ``window,'' but use it
5455 differently. An Emacs frame is a single window as far as X is
5456 concerned; the individual Emacs windows are not known to X at all.
5458 @defvar window-system
5459 This variable tells Lisp programs what window system Emacs is running
5460 under. The possible values are
5464 @cindex X Window System
5465 Emacs is displaying using X.
5467 Emacs is displaying using MS-DOS.
5469 Emacs is displaying using Windows.
5471 Emacs is displaying using a Macintosh.
5473 Emacs is using a character-based terminal.
5477 @defvar window-setup-hook
5478 This variable is a normal hook which Emacs runs after handling the
5479 initialization files. Emacs runs this hook after it has completed
5480 loading your init file, the default initialization file (if
5481 any), and the terminal-specific Lisp code, and running the hook
5482 @code{term-setup-hook}.
5484 This hook is used for internal purposes: setting up communication with
5485 the window system, and creating the initial window. Users should not
5490 arch-tag: ffdf5714-7ecf-415b-9023-fbc6b409c2c6