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 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 This function calls for redisplay of certain windows, the next time
59 redisplay is done, but does not clear them first.
61 @defun force-window-update &optional object
62 This function forces some or all windows to be updated on next redisplay.
63 If @var{object} is a window, it forces redisplay of that window. If
64 @var{object} is a buffer or buffer name, it forces redisplay of all
65 windows displaying that buffer. If @var{object} is @code{nil} (or
66 omitted), it forces redisplay of all windows.
69 Processing user input takes absolute priority over redisplay. If you
70 call these functions when input is available, they do nothing
71 immediately, but a full redisplay does happen eventually---after all the
72 input has been processed.
74 Normally, suspending and resuming Emacs also refreshes the screen.
75 Some terminal emulators record separate contents for display-oriented
76 programs such as Emacs and for ordinary sequential display. If you are
77 using such a terminal, you might want to inhibit the redisplay on
80 @defvar no-redraw-on-reenter
81 @cindex suspend (cf. @code{no-redraw-on-reenter})
82 @cindex resume (cf. @code{no-redraw-on-reenter})
83 This variable controls whether Emacs redraws the entire screen after it
84 has been suspended and resumed. Non-@code{nil} means there is no need
85 to redraw, @code{nil} means redrawing is needed. The default is @code{nil}.
88 @node Forcing Redisplay
89 @section Forcing Redisplay
90 @cindex forcing redisplay
92 Emacs redisplay normally stops if input arrives, and does not happen
93 at all if input is available before it starts. Most of the time, this
94 is exactly what you want. However, you can prevent preemption by
95 binding @code{redisplay-dont-pause} to a non-@code{nil} value.
97 @defvar redisplay-preemption-period
98 This variable specifies how many seconds Emacs waits between checks
99 for new input during redisplay. (The default is 0.1 seconds.) If
100 input has arrived when Emacs checks, it pre-empts redisplay and
101 processes the available input before trying again to redisplay.
103 If this variable is @code{nil}, Emacs does not check for input during
104 redisplay, and redisplay cannot be preempted by input.
106 @emph{Note} that this variable is only available if Emacs is built
107 with support for sub-second timers.
110 @defvar redisplay-dont-pause
111 If this variable is non-@code{nil}, pending input does not
112 prevent or halt redisplay; redisplay occurs, and finishes,
113 regardless of whether input is available.
116 @defun redisplay &optional force
117 This function performs an immediate redisplay provided there are no
118 pending input events. This is equivalent to @code{(sit-for 0)}.
120 If the optional argument @var{force} is non-@code{nil}, it forces an
121 immediate and complete redisplay even if input is available.
126 @cindex line wrapping
127 @cindex continuation lines
128 @cindex @samp{$} in display
129 @cindex @samp{\} in display
131 When a line of text extends beyond the right edge of a window, Emacs
132 can @dfn{continue} the line (make it ``wrap'' to the next screen
133 line), or @dfn{truncate} the line (limit it to one screen line). The
134 additional screen lines used to display a long text line are called
135 @dfn{continuation} lines. Continuation is not the same as filling;
136 continuation happens on the screen only, not in the buffer contents,
137 and it breaks a line precisely at the right margin, not at a word
138 boundary. @xref{Filling}.
140 On a graphical display, tiny arrow images in the window fringes
141 indicate truncated and continued lines (@pxref{Fringes}). On a text
142 terminal, a @samp{$} in the rightmost column of the window indicates
143 truncation; a @samp{\} on the rightmost column indicates a line that
144 ``wraps''. (The display table can specify alternate characters to use
145 for this; @pxref{Display Tables}).
147 @defopt truncate-lines
148 This buffer-local variable controls how Emacs displays lines that extend
149 beyond the right edge of the window. The default is @code{nil}, which
150 specifies continuation. If the value is non-@code{nil}, then these
153 If the variable @code{truncate-partial-width-windows} is non-@code{nil},
154 then truncation is always used for side-by-side windows (within one
155 frame) regardless of the value of @code{truncate-lines}.
158 @defopt default-truncate-lines
159 This variable is the default value for @code{truncate-lines}, for
160 buffers that do not have buffer-local values for it.
163 @defopt truncate-partial-width-windows
164 This variable controls display of lines that extend beyond the right
165 edge of the window, in side-by-side windows (@pxref{Splitting Windows}).
166 If it is non-@code{nil}, these lines are truncated; otherwise,
167 @code{truncate-lines} says what to do with them.
170 When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
171 a window, that forces truncation.
173 If your buffer contains @emph{very} long lines, and you use
174 continuation to display them, just thinking about them can make Emacs
175 redisplay slow. The column computation and indentation functions also
176 become slow. Then you might find it advisable to set
177 @code{cache-long-line-scans} to @code{t}.
179 @defvar cache-long-line-scans
180 If this variable is non-@code{nil}, various indentation and motion
181 functions, and Emacs redisplay, cache the results of scanning the
182 buffer, and consult the cache to avoid rescanning regions of the buffer
183 unless they are modified.
185 Turning on the cache slows down processing of short lines somewhat.
187 This variable is automatically buffer-local in every buffer.
191 @section The Echo Area
192 @cindex error display
195 The @dfn{echo area} is used for displaying error messages
196 (@pxref{Errors}), for messages made with the @code{message} primitive,
197 and for echoing keystrokes. It is not the same as the minibuffer,
198 despite the fact that the minibuffer appears (when active) in the same
199 place on the screen as the echo area. The @cite{GNU Emacs Manual}
200 specifies the rules for resolving conflicts between the echo area and
201 the minibuffer for use of that screen space (@pxref{Minibuffer,, The
202 Minibuffer, emacs, The GNU Emacs Manual}).
204 You can write output in the echo area by using the Lisp printing
205 functions with @code{t} as the stream (@pxref{Output Functions}), or
209 * Displaying Messages:: Explicitly displaying text in the echo area.
210 * Progress:: Informing user about progress of a long operation.
211 * Logging Messages:: Echo area messages are logged for the user.
212 * Echo Area Customization:: Controlling the echo area.
215 @node Displaying Messages
216 @subsection Displaying Messages in the Echo Area
218 This section describes the functions for explicitly producing echo
219 area messages. Many other Emacs features display messages there, too.
221 @defun message format-string &rest arguments
222 This function displays a message in the echo area. The argument
223 @var{format-string} is similar to a C language @code{printf} format
224 string. See @code{format} in @ref{Formatting Strings}, for the details
225 on the conversion specifications. @code{message} returns the
228 In batch mode, @code{message} prints the message text on the standard
229 error stream, followed by a newline.
231 If @var{format-string}, or strings among the @var{arguments}, have
232 @code{face} text properties, these affect the way the message is displayed.
235 If @var{format-string} is @code{nil} or the empty string,
236 @code{message} clears the echo area; if the echo area has been
237 expanded automatically, this brings it back to its normal size.
238 If the minibuffer is active, this brings the minibuffer contents back
239 onto the screen immediately.
243 (message "Minibuffer depth is %d."
245 @print{} Minibuffer depth is 0.
246 @result{} "Minibuffer depth is 0."
250 ---------- Echo Area ----------
251 Minibuffer depth is 0.
252 ---------- Echo Area ----------
256 To automatically display a message in the echo area or in a pop-buffer,
257 depending on its size, use @code{display-message-or-buffer} (see below).
260 @defmac with-temp-message message &rest body
261 This construct displays a message in the echo area temporarily, during
262 the execution of @var{body}. It displays @var{message}, executes
263 @var{body}, then returns the value of the last body form while restoring
264 the previous echo area contents.
267 @defun message-or-box format-string &rest arguments
268 This function displays a message like @code{message}, but may display it
269 in a dialog box instead of the echo area. If this function is called in
270 a command that was invoked using the mouse---more precisely, if
271 @code{last-nonmenu-event} (@pxref{Command Loop Info}) is either
272 @code{nil} or a list---then it uses a dialog box or pop-up menu to
273 display the message. Otherwise, it uses the echo area. (This is the
274 same criterion that @code{y-or-n-p} uses to make a similar decision; see
275 @ref{Yes-or-No Queries}.)
277 You can force use of the mouse or of the echo area by binding
278 @code{last-nonmenu-event} to a suitable value around the call.
281 @defun message-box format-string &rest arguments
282 This function displays a message like @code{message}, but uses a dialog
283 box (or a pop-up menu) whenever that is possible. If it is impossible
284 to use a dialog box or pop-up menu, because the terminal does not
285 support them, then @code{message-box} uses the echo area, like
289 @defun display-message-or-buffer message &optional buffer-name not-this-window frame
290 This function displays the message @var{message}, which may be either a
291 string or a buffer. If it is shorter than the maximum height of the
292 echo area, as defined by @code{max-mini-window-height}, it is displayed
293 in the echo area, using @code{message}. Otherwise,
294 @code{display-buffer} is used to show it in a pop-up buffer.
296 Returns either the string shown in the echo area, or when a pop-up
297 buffer is used, the window used to display it.
299 If @var{message} is a string, then the optional argument
300 @var{buffer-name} is the name of the buffer used to display it when a
301 pop-up buffer is used, defaulting to @samp{*Message*}. In the case
302 where @var{message} is a string and displayed in the echo area, it is
303 not specified whether the contents are inserted into the buffer anyway.
305 The optional arguments @var{not-this-window} and @var{frame} are as for
306 @code{display-buffer}, and only used if a buffer is displayed.
309 @defun current-message
310 This function returns the message currently being displayed in the
311 echo area, or @code{nil} if there is none.
315 @subsection Reporting Operation Progress
316 @cindex progress reporting
318 When an operation can take a while to finish, you should inform the
319 user about the progress it makes. This way the user can estimate
320 remaining time and clearly see that Emacs is busy working, not hung.
322 Functions listed in this section provide simple and efficient way of
323 reporting operation progress. Here is a working example that does
327 (let ((progress-reporter
328 (make-progress-reporter "Collecting mana for Emacs..."
332 (progress-reporter-update progress-reporter k))
333 (progress-reporter-done progress-reporter))
336 @defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
337 This function creates and returns a @dfn{progress reporter}---an
338 object you will use as an argument for all other functions listed
339 here. The idea is to precompute as much data as possible to make
340 progress reporting very fast.
342 When this progress reporter is subsequently used, it will display
343 @var{message} in the echo area, followed by progress percentage.
344 @var{message} is treated as a simple string. If you need it to depend
345 on a filename, for instance, use @code{format} before calling this
348 @var{min-value} and @var{max-value} arguments stand for starting and
349 final states of your operation. For instance, if you scan a buffer,
350 they should be the results of @code{point-min} and @code{point-max}
351 correspondingly. It is required that @var{max-value} is greater than
352 @var{min-value}. If you create progress reporter when some part of
353 the operation has already been completed, then specify
354 @var{current-value} argument. But normally you should omit it or set
355 it to @code{nil}---it will default to @var{min-value} then.
357 Remaining arguments control the rate of echo area updates. Progress
358 reporter will wait for at least @var{min-change} more percents of the
359 operation to be completed before printing next message.
360 @var{min-time} specifies the minimum time in seconds to pass between
361 successive prints. It can be fractional. Depending on Emacs and
362 system capabilities, progress reporter may or may not respect this
363 last argument or do it with varying precision. Default value for
364 @var{min-change} is 1 (one percent), for @var{min-time}---0.2
367 This function calls @code{progress-reporter-update}, so the first
368 message is printed immediately.
371 @defun progress-reporter-update reporter value
372 This function does the main work of reporting progress of your
373 operation. It displays the message of @var{reporter}, followed by
374 progress percentage determined by @var{value}. If percentage is zero,
375 or close enough according to the @var{min-change} and @var{min-time}
376 arguments, then it is omitted from the output.
378 @var{reporter} must be the result of a call to
379 @code{make-progress-reporter}. @var{value} specifies the current
380 state of your operation and must be between @var{min-value} and
381 @var{max-value} (inclusive) as passed to
382 @code{make-progress-reporter}. For instance, if you scan a buffer,
383 then @var{value} should be the result of a call to @code{point}.
385 This function respects @var{min-change} and @var{min-time} as passed
386 to @code{make-progress-reporter} and so does not output new messages
387 on every invocation. It is thus very fast and normally you should not
388 try to reduce the number of calls to it: resulting overhead will most
389 likely negate your effort.
392 @defun progress-reporter-force-update reporter value &optional new-message
393 This function is similar to @code{progress-reporter-update} except
394 that it prints a message in the echo area unconditionally.
396 The first two arguments have the same meaning as for
397 @code{progress-reporter-update}. Optional @var{new-message} allows
398 you to change the message of the @var{reporter}. Since this functions
399 always updates the echo area, such a change will be immediately
400 presented to the user.
403 @defun progress-reporter-done reporter
404 This function should be called when the operation is finished. It
405 prints the message of @var{reporter} followed by word ``done'' in the
408 You should always call this function and not hope for
409 @code{progress-reporter-update} to print ``100%.'' Firstly, it may
410 never print it, there are many good reasons for this not to happen.
411 Secondly, ``done'' is more explicit.
414 @defmac dotimes-with-progress-reporter (var count [result]) message body@dots{}
415 This is a convenience macro that works the same way as @code{dotimes}
416 does, but also reports loop progress using the functions described
417 above. It allows you to save some typing.
419 You can rewrite the example in the beginning of this node using
423 (dotimes-with-progress-reporter
425 "Collecting some mana for Emacs..."
430 @node Logging Messages
431 @subsection Logging Messages in @samp{*Messages*}
432 @cindex logging echo-area messages
434 Almost all the messages displayed in the echo area are also recorded
435 in the @samp{*Messages*} buffer so that the user can refer back to
436 them. This includes all the messages that are output with
439 @defopt message-log-max
440 This variable specifies how many lines to keep in the @samp{*Messages*}
441 buffer. The value @code{t} means there is no limit on how many lines to
442 keep. The value @code{nil} disables message logging entirely. Here's
443 how to display a message and prevent it from being logged:
446 (let (message-log-max)
451 To make @samp{*Messages*} more convenient for the user, the logging
452 facility combines successive identical messages. It also combines
453 successive related messages for the sake of two cases: question
454 followed by answer, and a series of progress messages.
456 A ``question followed by an answer'' means two messages like the
457 ones produced by @code{y-or-n-p}: the first is @samp{@var{question}},
458 and the second is @samp{@var{question}...@var{answer}}. The first
459 message conveys no additional information beyond what's in the second,
460 so logging the second message discards the first from the log.
462 A ``series of progress messages'' means successive messages like
463 those produced by @code{make-progress-reporter}. They have the form
464 @samp{@var{base}...@var{how-far}}, where @var{base} is the same each
465 time, while @var{how-far} varies. Logging each message in the series
466 discards the previous one, provided they are consecutive.
468 The functions @code{make-progress-reporter} and @code{y-or-n-p}
469 don't have to do anything special to activate the message log
470 combination feature. It operates whenever two consecutive messages
471 are logged that share a common prefix ending in @samp{...}.
473 @node Echo Area Customization
474 @subsection Echo Area Customization
476 These variables control details of how the echo area works.
478 @defvar cursor-in-echo-area
479 This variable controls where the cursor appears when a message is
480 displayed in the echo area. If it is non-@code{nil}, then the cursor
481 appears at the end of the message. Otherwise, the cursor appears at
482 point---not in the echo area at all.
484 The value is normally @code{nil}; Lisp programs bind it to @code{t}
485 for brief periods of time.
488 @defvar echo-area-clear-hook
489 This normal hook is run whenever the echo area is cleared---either by
490 @code{(message nil)} or for any other reason.
493 @defvar echo-keystrokes
494 This variable determines how much time should elapse before command
495 characters echo. Its value must be an integer or floating point number,
497 number of seconds to wait before echoing. If the user types a prefix
498 key (such as @kbd{C-x}) and then delays this many seconds before
499 continuing, the prefix key is echoed in the echo area. (Once echoing
500 begins in a key sequence, all subsequent characters in the same key
501 sequence are echoed immediately.)
503 If the value is zero, then command input is not echoed.
506 @defvar message-truncate-lines
507 Normally, displaying a long message resizes the echo area to display
508 the entire message. But if the variable @code{message-truncate-lines}
509 is non-@code{nil}, the echo area does not resize, and the message is
510 truncated to fit it, as in Emacs 20 and before.
513 The variable @code{max-mini-window-height}, which specifies the
514 maximum height for resizing minibuffer windows, also applies to the
515 echo area (which is really a special use of the minibuffer window.
516 @xref{Minibuffer Misc}.
519 @section Reporting Warnings
522 @dfn{Warnings} are a facility for a program to inform the user of a
523 possible problem, but continue running.
526 * Warning Basics:: Warnings concepts and functions to report them.
527 * Warning Variables:: Variables programs bind to customize their warnings.
528 * Warning Options:: Variables users set to control display of warnings.
532 @subsection Warning Basics
533 @cindex severity level
535 Every warning has a textual message, which explains the problem for
536 the user, and a @dfn{severity level} which is a symbol. Here are the
537 possible severity levels, in order of decreasing severity, and their
542 A problem that will seriously impair Emacs operation soon
543 if you do not attend to it promptly.
545 A report of data or circumstances that are inherently wrong.
547 A report of data or circumstances that are not inherently wrong, but
548 raise suspicion of a possible problem.
550 A report of information that may be useful if you are debugging.
553 When your program encounters invalid input data, it can either
554 signal a Lisp error by calling @code{error} or @code{signal} or report
555 a warning with severity @code{:error}. Signaling a Lisp error is the
556 easiest thing to do, but it means the program cannot continue
557 processing. If you want to take the trouble to implement a way to
558 continue processing despite the bad data, then reporting a warning of
559 severity @code{:error} is the right way to inform the user of the
560 problem. For instance, the Emacs Lisp byte compiler can report an
561 error that way and continue compiling other functions. (If the
562 program signals a Lisp error and then handles it with
563 @code{condition-case}, the user won't see the error message; it could
564 show the message to the user by reporting it as a warning.)
567 Each warning has a @dfn{warning type} to classify it. The type is a
568 list of symbols. The first symbol should be the custom group that you
569 use for the program's user options. For example, byte compiler
570 warnings use the warning type @code{(bytecomp)}. You can also
571 subcategorize the warnings, if you wish, by using more symbols in the
574 @defun display-warning type message &optional level buffer-name
575 This function reports a warning, using @var{message} as the message
576 and @var{type} as the warning type. @var{level} should be the
577 severity level, with @code{:warning} being the default.
579 @var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
580 for logging the warning. By default, it is @samp{*Warnings*}.
583 @defun lwarn type level message &rest args
584 This function reports a warning using the value of @code{(format
585 @var{message} @var{args}...)} as the message. In other respects it is
586 equivalent to @code{display-warning}.
589 @defun warn message &rest args
590 This function reports a warning using the value of @code{(format
591 @var{message} @var{args}...)} as the message, @code{(emacs)} as the
592 type, and @code{:warning} as the severity level. It exists for
593 compatibility only; we recommend not using it, because you should
594 specify a specific warning type.
597 @node Warning Variables
598 @subsection Warning Variables
600 Programs can customize how their warnings appear by binding
601 the variables described in this section.
603 @defvar warning-levels
604 This list defines the meaning and severity order of the warning
605 severity levels. Each element defines one severity level,
606 and they are arranged in order of decreasing severity.
608 Each element has the form @code{(@var{level} @var{string}
609 @var{function})}, where @var{level} is the severity level it defines.
610 @var{string} specifies the textual description of this level.
611 @var{string} should use @samp{%s} to specify where to put the warning
612 type information, or it can omit the @samp{%s} so as not to include
615 The optional @var{function}, if non-@code{nil}, is a function to call
616 with no arguments, to get the user's attention.
618 Normally you should not change the value of this variable.
621 @defvar warning-prefix-function
622 If non-@code{nil}, the value is a function to generate prefix text for
623 warnings. Programs can bind the variable to a suitable function.
624 @code{display-warning} calls this function with the warnings buffer
625 current, and the function can insert text in it. That text becomes
626 the beginning of the warning message.
628 The function is called with two arguments, the severity level and its
629 entry in @code{warning-levels}. It should return a list to use as the
630 entry (this value need not be an actual member of
631 @code{warning-levels}). By constructing this value, the function can
632 change the severity of the warning, or specify different handling for
633 a given severity level.
635 If the variable's value is @code{nil} then there is no function
639 @defvar warning-series
640 Programs can bind this variable to @code{t} to say that the next
641 warning should begin a series. When several warnings form a series,
642 that means to leave point on the first warning of the series, rather
643 than keep moving it for each warning so that it appears on the last one.
644 The series ends when the local binding is unbound and
645 @code{warning-series} becomes @code{nil} again.
647 The value can also be a symbol with a function definition. That is
648 equivalent to @code{t}, except that the next warning will also call
649 the function with no arguments with the warnings buffer current. The
650 function can insert text which will serve as a header for the series
653 Once a series has begun, the value is a marker which points to the
654 buffer position in the warnings buffer of the start of the series.
656 The variable's normal value is @code{nil}, which means to handle
657 each warning separately.
660 @defvar warning-fill-prefix
661 When this variable is non-@code{nil}, it specifies a fill prefix to
662 use for filling each warning's text.
665 @defvar warning-type-format
666 This variable specifies the format for displaying the warning type
667 in the warning message. The result of formatting the type this way
668 gets included in the message under the control of the string in the
669 entry in @code{warning-levels}. The default value is @code{" (%s)"}.
670 If you bind it to @code{""} then the warning type won't appear at
674 @node Warning Options
675 @subsection Warning Options
677 These variables are used by users to control what happens
678 when a Lisp program reports a warning.
680 @defopt warning-minimum-level
681 This user option specifies the minimum severity level that should be
682 shown immediately to the user. The default is @code{:warning}, which
683 means to immediately display all warnings except @code{:debug}
687 @defopt warning-minimum-log-level
688 This user option specifies the minimum severity level that should be
689 logged in the warnings buffer. The default is @code{:warning}, which
690 means to log all warnings except @code{:debug} warnings.
693 @defopt warning-suppress-types
694 This list specifies which warning types should not be displayed
695 immediately for the user. Each element of the list should be a list
696 of symbols. If its elements match the first elements in a warning
697 type, then that warning is not displayed immediately.
700 @defopt warning-suppress-log-types
701 This list specifies which warning types should not be logged in the
702 warnings buffer. Each element of the list should be a list of
703 symbols. If it matches the first few elements in a warning type, then
704 that warning is not logged.
708 @section Invisible Text
710 @cindex invisible text
711 You can make characters @dfn{invisible}, so that they do not appear on
712 the screen, with the @code{invisible} property. This can be either a
713 text property (@pxref{Text Properties}) or a property of an overlay
714 (@pxref{Overlays}). Cursor motion also partly ignores these
715 characters; if the command loop finds point within them, it moves
716 point to the other side of them.
718 In the simplest case, any non-@code{nil} @code{invisible} property makes
719 a character invisible. This is the default case---if you don't alter
720 the default value of @code{buffer-invisibility-spec}, this is how the
721 @code{invisible} property works. You should normally use @code{t}
722 as the value of the @code{invisible} property if you don't plan
723 to set @code{buffer-invisibility-spec} yourself.
725 More generally, you can use the variable @code{buffer-invisibility-spec}
726 to control which values of the @code{invisible} property make text
727 invisible. This permits you to classify the text into different subsets
728 in advance, by giving them different @code{invisible} values, and
729 subsequently make various subsets visible or invisible by changing the
730 value of @code{buffer-invisibility-spec}.
732 Controlling visibility with @code{buffer-invisibility-spec} is
733 especially useful in a program to display the list of entries in a
734 database. It permits the implementation of convenient filtering
735 commands to view just a part of the entries in the database. Setting
736 this variable is very fast, much faster than scanning all the text in
737 the buffer looking for properties to change.
739 @defvar buffer-invisibility-spec
740 This variable specifies which kinds of @code{invisible} properties
741 actually make a character invisible. Setting this variable makes it
746 A character is invisible if its @code{invisible} property is
747 non-@code{nil}. This is the default.
750 Each element of the list specifies a criterion for invisibility; if a
751 character's @code{invisible} property fits any one of these criteria,
752 the character is invisible. The list can have two kinds of elements:
756 A character is invisible if its @code{invisible} property value
757 is @var{atom} or if it is a list with @var{atom} as a member.
759 @item (@var{atom} . t)
760 A character is invisible if its @code{invisible} property value
761 is @var{atom} or if it is a list with @var{atom} as a member.
762 Moreover, if this character is at the end of a line and is followed
763 by a visible newline, it displays an ellipsis.
768 Two functions are specifically provided for adding elements to
769 @code{buffer-invisibility-spec} and removing elements from it.
771 @defun add-to-invisibility-spec element
772 This function adds the element @var{element} to
773 @code{buffer-invisibility-spec}. If @code{buffer-invisibility-spec}
774 was @code{t}, it changes to a list, @code{(t)}, so that text whose
775 @code{invisible} property is @code{t} remains invisible.
778 @defun remove-from-invisibility-spec element
779 This removes the element @var{element} from
780 @code{buffer-invisibility-spec}. This does nothing if @var{element}
784 A convention for use of @code{buffer-invisibility-spec} is that a
785 major mode should use the mode's own name as an element of
786 @code{buffer-invisibility-spec} and as the value of the
787 @code{invisible} property:
790 ;; @r{If you want to display an ellipsis:}
791 (add-to-invisibility-spec '(my-symbol . t))
792 ;; @r{If you don't want ellipsis:}
793 (add-to-invisibility-spec 'my-symbol)
795 (overlay-put (make-overlay beginning end)
796 'invisible 'my-symbol)
798 ;; @r{When done with the overlays:}
799 (remove-from-invisibility-spec '(my-symbol . t))
800 ;; @r{Or respectively:}
801 (remove-from-invisibility-spec 'my-symbol)
804 @vindex line-move-ignore-invisible
805 Ordinarily, functions that operate on text or move point do not care
806 whether the text is invisible. The user-level line motion commands
807 explicitly ignore invisible newlines if
808 @code{line-move-ignore-invisible} is non-@code{nil} (the default), but
809 only because they are explicitly programmed to do so.
811 However, if a command ends with point inside or immediately before
812 invisible text, the main editing loop moves point further forward or
813 further backward (in the same direction that the command already moved
814 it) until that condition is no longer true. Thus, if the command
815 moved point back into an invisible range, Emacs moves point back to
816 the beginning of that range, and then back one more character. If the
817 command moved point forward into an invisible range, Emacs moves point
818 forward up to the first visible character that follows the invisible
821 Incremental search can make invisible overlays visible temporarily
822 and/or permanently when a match includes invisible text. To enable
823 this, the overlay should have a non-@code{nil}
824 @code{isearch-open-invisible} property. The property value should be a
825 function to be called with the overlay as an argument. This function
826 should make the overlay visible permanently; it is used when the match
827 overlaps the overlay on exit from the search.
829 During the search, such overlays are made temporarily visible by
830 temporarily modifying their invisible and intangible properties. If you
831 want this to be done differently for a certain overlay, give it an
832 @code{isearch-open-invisible-temporary} property which is a function.
833 The function is called with two arguments: the first is the overlay, and
834 the second is @code{nil} to make the overlay visible, or @code{t} to
835 make it invisible again.
837 @node Selective Display
838 @section Selective Display
839 @cindex selective display
841 @dfn{Selective display} refers to a pair of related features for
842 hiding certain lines on the screen.
844 The first variant, explicit selective display, is designed for use
845 in a Lisp program: it controls which lines are hidden by altering the
846 text. This kind of hiding in some ways resembles the effect of the
847 @code{invisible} property (@pxref{Invisible Text}), but the two
848 features are different and do not work the same way.
850 In the second variant, the choice of lines to hide is made
851 automatically based on indentation. This variant is designed to be a
854 The way you control explicit selective display is by replacing a
855 newline (control-j) with a carriage return (control-m). The text that
856 was formerly a line following that newline is now hidden. Strictly
857 speaking, it is temporarily no longer a line at all, since only
858 newlines can separate lines; it is now part of the previous line.
860 Selective display does not directly affect editing commands. For
861 example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly
862 into hidden text. However, the replacement of newline characters with
863 carriage return characters affects some editing commands. For
864 example, @code{next-line} skips hidden lines, since it searches only
865 for newlines. Modes that use selective display can also define
866 commands that take account of the newlines, or that control which
867 parts of the text are hidden.
869 When you write a selectively displayed buffer into a file, all the
870 control-m's are output as newlines. This means that when you next read
871 in the file, it looks OK, with nothing hidden. The selective display
872 effect is seen only within Emacs.
874 @defvar selective-display
875 This buffer-local variable enables selective display. This means that
876 lines, or portions of lines, may be made hidden.
880 If the value of @code{selective-display} is @code{t}, then the character
881 control-m marks the start of hidden text; the control-m, and the rest
882 of the line following it, are not displayed. This is explicit selective
886 If the value of @code{selective-display} is a positive integer, then
887 lines that start with more than that many columns of indentation are not
891 When some portion of a buffer is hidden, the vertical movement
892 commands operate as if that portion did not exist, allowing a single
893 @code{next-line} command to skip any number of hidden lines.
894 However, character movement commands (such as @code{forward-char}) do
895 not skip the hidden portion, and it is possible (if tricky) to insert
896 or delete text in an hidden portion.
898 In the examples below, we show the @emph{display appearance} of the
899 buffer @code{foo}, which changes with the value of
900 @code{selective-display}. The @emph{contents} of the buffer do not
905 (setq selective-display nil)
908 ---------- Buffer: foo ----------
915 ---------- Buffer: foo ----------
919 (setq selective-display 2)
922 ---------- Buffer: foo ----------
927 ---------- Buffer: foo ----------
932 @defvar selective-display-ellipses
933 If this buffer-local variable is non-@code{nil}, then Emacs displays
934 @samp{@dots{}} at the end of a line that is followed by hidden text.
935 This example is a continuation of the previous one.
939 (setq selective-display-ellipses t)
942 ---------- Buffer: foo ----------
947 ---------- Buffer: foo ----------
951 You can use a display table to substitute other text for the ellipsis
952 (@samp{@dots{}}). @xref{Display Tables}.
955 @node Temporary Displays
956 @section Temporary Displays
958 Temporary displays are used by Lisp programs to put output into a
959 buffer and then present it to the user for perusal rather than for
960 editing. Many help commands use this feature.
962 @defspec with-output-to-temp-buffer buffer-name forms@dots{}
963 This function executes @var{forms} while arranging to insert any output
964 they print into the buffer named @var{buffer-name}, which is first
965 created if necessary, and put into Help mode. Finally, the buffer is
966 displayed in some window, but not selected.
968 If the @var{forms} do not change the major mode in the output buffer,
969 so that it is still Help mode at the end of their execution, then
970 @code{with-output-to-temp-buffer} makes this buffer read-only at the
971 end, and also scans it for function and variable names to make them
972 into clickable cross-references. @xref{Docstring hyperlinks, , Tips
973 for Documentation Strings}, in particular the item on hyperlinks in
974 documentation strings, for more details.
976 The string @var{buffer-name} specifies the temporary buffer, which
977 need not already exist. The argument must be a string, not a buffer.
978 The buffer is erased initially (with no questions asked), and it is
979 marked as unmodified after @code{with-output-to-temp-buffer} exits.
981 @code{with-output-to-temp-buffer} binds @code{standard-output} to the
982 temporary buffer, then it evaluates the forms in @var{forms}. Output
983 using the Lisp output functions within @var{forms} goes by default to
984 that buffer (but screen display and messages in the echo area, although
985 they are ``output'' in the general sense of the word, are not affected).
986 @xref{Output Functions}.
988 Several hooks are available for customizing the behavior
989 of this construct; they are listed below.
991 The value of the last form in @var{forms} is returned.
995 ---------- Buffer: foo ----------
996 This is the contents of foo.
997 ---------- Buffer: foo ----------
1001 (with-output-to-temp-buffer "foo"
1003 (print standard-output))
1004 @result{} #<buffer foo>
1006 ---------- Buffer: foo ----------
1011 ---------- Buffer: foo ----------
1016 @defvar temp-buffer-show-function
1017 If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
1018 calls it as a function to do the job of displaying a help buffer. The
1019 function gets one argument, which is the buffer it should display.
1021 It is a good idea for this function to run @code{temp-buffer-show-hook}
1022 just as @code{with-output-to-temp-buffer} normally would, inside of
1023 @code{save-selected-window} and with the chosen window and buffer
1027 @defvar temp-buffer-setup-hook
1028 This normal hook is run by @code{with-output-to-temp-buffer} before
1029 evaluating @var{body}. When the hook runs, the temporary buffer is
1030 current. This hook is normally set up with a function to put the
1031 buffer in Help mode.
1034 @defvar temp-buffer-show-hook
1035 This normal hook is run by @code{with-output-to-temp-buffer} after
1036 displaying the temporary buffer. When the hook runs, the temporary buffer
1037 is current, and the window it was displayed in is selected. This hook
1038 is normally set up with a function to make the buffer read only, and
1039 find function names and variable names in it, provided the major mode
1043 @defun momentary-string-display string position &optional char message
1044 This function momentarily displays @var{string} in the current buffer at
1045 @var{position}. It has no effect on the undo list or on the buffer's
1046 modification status.
1048 The momentary display remains until the next input event. If the next
1049 input event is @var{char}, @code{momentary-string-display} ignores it
1050 and returns. Otherwise, that event remains buffered for subsequent use
1051 as input. Thus, typing @var{char} will simply remove the string from
1052 the display, while typing (say) @kbd{C-f} will remove the string from
1053 the display and later (presumably) move point forward. The argument
1054 @var{char} is a space by default.
1056 The return value of @code{momentary-string-display} is not meaningful.
1058 If the string @var{string} does not contain control characters, you can
1059 do the same job in a more general way by creating (and then subsequently
1060 deleting) an overlay with a @code{before-string} property.
1061 @xref{Overlay Properties}.
1063 If @var{message} is non-@code{nil}, it is displayed in the echo area
1064 while @var{string} is displayed in the buffer. If it is @code{nil}, a
1065 default message says to type @var{char} to continue.
1067 In this example, point is initially located at the beginning of the
1072 ---------- Buffer: foo ----------
1073 This is the contents of foo.
1074 @point{}Second line.
1075 ---------- Buffer: foo ----------
1079 (momentary-string-display
1080 "**** Important Message! ****"
1082 "Type RET when done reading")
1087 ---------- Buffer: foo ----------
1088 This is the contents of foo.
1089 **** Important Message! ****Second line.
1090 ---------- Buffer: foo ----------
1092 ---------- Echo Area ----------
1093 Type RET when done reading
1094 ---------- Echo Area ----------
1103 You can use @dfn{overlays} to alter the appearance of a buffer's text on
1104 the screen, for the sake of presentation features. An overlay is an
1105 object that belongs to a particular buffer, and has a specified
1106 beginning and end. It also has properties that you can examine and set;
1107 these affect the display of the text within the overlay.
1109 An overlay uses markers to record its beginning and end; thus,
1110 editing the text of the buffer adjusts the beginning and end of each
1111 overlay so that it stays with the text. When you create the overlay,
1112 you can specify whether text inserted at the beginning should be
1113 inside the overlay or outside, and likewise for the end of the overlay.
1116 * Managing Overlays:: Creating and moving overlays.
1117 * Overlay Properties:: How to read and set properties.
1118 What properties do to the screen display.
1119 * Finding Overlays:: Searching for overlays.
1122 @node Managing Overlays
1123 @subsection Managing Overlays
1125 This section describes the functions to create, delete and move
1126 overlays, and to examine their contents. Overlay changes are not
1127 recorded in the buffer's undo list, since the overlays are not
1128 part of the buffer's contents.
1130 @defun overlayp object
1131 This function returns @code{t} if @var{object} is an overlay.
1134 @defun make-overlay start end &optional buffer front-advance rear-advance
1135 This function creates and returns an overlay that belongs to
1136 @var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
1137 and @var{end} must specify buffer positions; they may be integers or
1138 markers. If @var{buffer} is omitted, the overlay is created in the
1141 The arguments @var{front-advance} and @var{rear-advance} specify the
1142 marker insertion type for the start of the overlay and for the end of
1143 the overlay, respectively. @xref{Marker Insertion Types}. If they
1144 are both @code{nil}, the default, then the overlay extends to include
1145 any text inserted at the beginning, but not text inserted at the end.
1146 If @var{front-advance} is non-@code{nil}, text inserted at the
1147 beginning of the overlay is excluded from the overlay. If
1148 @var{rear-advance} is non-@code{nil}, text inserted at the end of the
1149 overlay is included in the overlay.
1152 @defun overlay-start overlay
1153 This function returns the position at which @var{overlay} starts,
1157 @defun overlay-end overlay
1158 This function returns the position at which @var{overlay} ends,
1162 @defun overlay-buffer overlay
1163 This function returns the buffer that @var{overlay} belongs to. It
1164 returns @code{nil} if @var{overlay} has been deleted.
1167 @defun delete-overlay overlay
1168 This function deletes @var{overlay}. The overlay continues to exist as
1169 a Lisp object, and its property list is unchanged, but it ceases to be
1170 attached to the buffer it belonged to, and ceases to have any effect on
1173 A deleted overlay is not permanently disconnected. You can give it a
1174 position in a buffer again by calling @code{move-overlay}.
1177 @defun move-overlay overlay start end &optional buffer
1178 This function moves @var{overlay} to @var{buffer}, and places its bounds
1179 at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
1180 must specify buffer positions; they may be integers or markers.
1182 If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
1183 was already associated with; if @var{overlay} was deleted, it goes into
1186 The return value is @var{overlay}.
1188 This is the only valid way to change the endpoints of an overlay. Do
1189 not try modifying the markers in the overlay by hand, as that fails to
1190 update other vital data structures and can cause some overlays to be
1194 @defun remove-overlays &optional start end name value
1195 This function removes all the overlays between @var{start} and
1196 @var{end} whose property @var{name} has the value @var{value}. It can
1197 move the endpoints of the overlays in the region, or split them.
1199 If @var{name} is omitted or @code{nil}, it means to delete all overlays in
1200 the specified region. If @var{start} and/or @var{end} are omitted or
1201 @code{nil}, that means the beginning and end of the buffer respectively.
1202 Therefore, @code{(remove-overlays)} removes all the overlays in the
1206 Here are some examples:
1209 ;; @r{Create an overlay.}
1210 (setq foo (make-overlay 1 10))
1211 @result{} #<overlay from 1 to 10 in display.texi>
1216 (overlay-buffer foo)
1217 @result{} #<buffer display.texi>
1218 ;; @r{Give it a property we can check later.}
1219 (overlay-put foo 'happy t)
1221 ;; @r{Verify the property is present.}
1222 (overlay-get foo 'happy)
1224 ;; @r{Move the overlay.}
1225 (move-overlay foo 5 20)
1226 @result{} #<overlay from 5 to 20 in display.texi>
1231 ;; @r{Delete the overlay.}
1232 (delete-overlay foo)
1234 ;; @r{Verify it is deleted.}
1236 @result{} #<overlay in no buffer>
1237 ;; @r{A deleted overlay has no position.}
1242 (overlay-buffer foo)
1244 ;; @r{Undelete the overlay.}
1245 (move-overlay foo 1 20)
1246 @result{} #<overlay from 1 to 20 in display.texi>
1247 ;; @r{Verify the results.}
1252 (overlay-buffer foo)
1253 @result{} #<buffer display.texi>
1254 ;; @r{Moving and deleting the overlay does not change its properties.}
1255 (overlay-get foo 'happy)
1259 @node Overlay Properties
1260 @subsection Overlay Properties
1262 Overlay properties are like text properties in that the properties that
1263 alter how a character is displayed can come from either source. But in
1264 most respects they are different. @xref{Text Properties}, for comparison.
1266 Text properties are considered a part of the text; overlays and
1267 their properties are specifically considered not to be part of the
1268 text. Thus, copying text between various buffers and strings
1269 preserves text properties, but does not try to preserve overlays.
1270 Changing a buffer's text properties marks the buffer as modified,
1271 while moving an overlay or changing its properties does not. Unlike
1272 text property changes, overlay property changes are not recorded in
1273 the buffer's undo list.
1275 These functions read and set the properties of an overlay:
1277 @defun overlay-get overlay prop
1278 This function returns the value of property @var{prop} recorded in
1279 @var{overlay}, if any. If @var{overlay} does not record any value for
1280 that property, but it does have a @code{category} property which is a
1281 symbol, that symbol's @var{prop} property is used. Otherwise, the value
1285 @defun overlay-put overlay prop value
1286 This function sets the value of property @var{prop} recorded in
1287 @var{overlay} to @var{value}. It returns @var{value}.
1290 @defun overlay-properties overlay
1291 This returns a copy of the property list of @var{overlay}.
1294 See also the function @code{get-char-property} which checks both
1295 overlay properties and text properties for a given character.
1296 @xref{Examining Properties}.
1298 Many overlay properties have special meanings; here is a table
1303 @kindex priority @r{(overlay property)}
1304 This property's value (which should be a nonnegative integer number)
1305 determines the priority of the overlay. The priority matters when two
1306 or more overlays cover the same character and both specify the same
1307 property; the one whose @code{priority} value is larger takes priority
1308 over the other. For the @code{face} property, the higher priority
1309 value does not completely replace the other; instead, its face
1310 attributes override the face attributes of the lower priority
1311 @code{face} property.
1313 Currently, all overlays take priority over text properties. Please
1314 avoid using negative priority values, as we have not yet decided just
1315 what they should mean.
1318 @kindex window @r{(overlay property)}
1319 If the @code{window} property is non-@code{nil}, then the overlay
1320 applies only on that window.
1323 @kindex category @r{(overlay property)}
1324 If an overlay has a @code{category} property, we call it the
1325 @dfn{category} of the overlay. It should be a symbol. The properties
1326 of the symbol serve as defaults for the properties of the overlay.
1329 @kindex face @r{(overlay property)}
1330 This property controls the way text is displayed---for example, which
1331 font and which colors. @xref{Faces}, for more information.
1333 In the simplest case, the value is a face name. It can also be a list;
1334 then each element can be any of these possibilities:
1338 A face name (a symbol or string).
1341 A property list of face attributes. This has the form (@var{keyword}
1342 @var{value} @dots{}), where each @var{keyword} is a face attribute
1343 name and @var{value} is a meaningful value for that attribute. With
1344 this feature, you do not need to create a face each time you want to
1345 specify a particular attribute for certain text. @xref{Face
1349 A cons cell of the form @code{(foreground-color . @var{color-name})} or
1350 @code{(background-color . @var{color-name})}. These elements specify
1351 just the foreground color or just the background color.
1353 @code{(foreground-color . @var{color-name})} has the same effect as
1354 @code{(:foreground @var{color-name})}; likewise for the background.
1358 @kindex mouse-face @r{(overlay property)}
1359 This property is used instead of @code{face} when the mouse is within
1360 the range of the overlay.
1363 @kindex display @r{(overlay property)}
1364 This property activates various features that change the
1365 way text is displayed. For example, it can make text appear taller
1366 or shorter, higher or lower, wider or narrower, or replaced with an image.
1367 @xref{Display Property}.
1370 @kindex help-echo @r{(overlay property)}
1371 If an overlay has a @code{help-echo} property, then when you move the
1372 mouse onto the text in the overlay, Emacs displays a help string in the
1373 echo area, or in the tooltip window. For details see @ref{Text
1376 @item modification-hooks
1377 @kindex modification-hooks @r{(overlay property)}
1378 This property's value is a list of functions to be called if any
1379 character within the overlay is changed or if text is inserted strictly
1382 The hook functions are called both before and after each change.
1383 If the functions save the information they receive, and compare notes
1384 between calls, they can determine exactly what change has been made
1387 When called before a change, each function receives four arguments: the
1388 overlay, @code{nil}, and the beginning and end of the text range to be
1391 When called after a change, each function receives five arguments: the
1392 overlay, @code{t}, the beginning and end of the text range just
1393 modified, and the length of the pre-change text replaced by that range.
1394 (For an insertion, the pre-change length is zero; for a deletion, that
1395 length is the number of characters deleted, and the post-change
1396 beginning and end are equal.)
1398 If these functions modify the buffer, they should bind
1399 @code{inhibit-modification-hooks} to @code{t} around doing so, to
1400 avoid confusing the internal mechanism that calls these hooks.
1402 @item insert-in-front-hooks
1403 @kindex insert-in-front-hooks @r{(overlay property)}
1404 This property's value is a list of functions to be called before and
1405 after inserting text right at the beginning of the overlay. The calling
1406 conventions are the same as for the @code{modification-hooks} functions.
1408 @item insert-behind-hooks
1409 @kindex insert-behind-hooks @r{(overlay property)}
1410 This property's value is a list of functions to be called before and
1411 after inserting text right at the end of the overlay. The calling
1412 conventions are the same as for the @code{modification-hooks} functions.
1415 @kindex invisible @r{(overlay property)}
1416 The @code{invisible} property can make the text in the overlay
1417 invisible, which means that it does not appear on the screen.
1418 @xref{Invisible Text}, for details.
1421 @kindex intangible @r{(overlay property)}
1422 The @code{intangible} property on an overlay works just like the
1423 @code{intangible} text property. @xref{Special Properties}, for details.
1425 @item isearch-open-invisible
1426 This property tells incremental search how to make an invisible overlay
1427 visible, permanently, if the final match overlaps it. @xref{Invisible
1430 @item isearch-open-invisible-temporary
1431 This property tells incremental search how to make an invisible overlay
1432 visible, temporarily, during the search. @xref{Invisible Text}.
1435 @kindex before-string @r{(overlay property)}
1436 This property's value is a string to add to the display at the beginning
1437 of the overlay. The string does not appear in the buffer in any
1438 sense---only on the screen.
1441 @kindex after-string @r{(overlay property)}
1442 This property's value is a string to add to the display at the end of
1443 the overlay. The string does not appear in the buffer in any
1444 sense---only on the screen.
1447 @kindex evaporate @r{(overlay property)}
1448 If this property is non-@code{nil}, the overlay is deleted automatically
1449 if it becomes empty (i.e., if its length becomes zero). If you give
1450 an empty overlay a non-@code{nil} @code{evaporate} property, that deletes
1454 @cindex keymap of character (and overlays)
1455 @kindex local-map @r{(overlay property)}
1456 If this property is non-@code{nil}, it specifies a keymap for a portion
1457 of the text. The property's value replaces the buffer's local map, when
1458 the character after point is within the overlay. @xref{Active Keymaps}.
1461 @kindex keymap @r{(overlay property)}
1462 The @code{keymap} property is similar to @code{local-map} but overrides the
1463 buffer's local map (and the map specified by the @code{local-map}
1464 property) rather than replacing it.
1467 @node Finding Overlays
1468 @subsection Searching for Overlays
1470 @defun overlays-at pos
1471 This function returns a list of all the overlays that cover the
1472 character at position @var{pos} in the current buffer. The list is in
1473 no particular order. An overlay contains position @var{pos} if it
1474 begins at or before @var{pos}, and ends after @var{pos}.
1476 To illustrate usage, here is a Lisp function that returns a list of the
1477 overlays that specify property @var{prop} for the character at point:
1480 (defun find-overlays-specifying (prop)
1481 (let ((overlays (overlays-at (point)))
1484 (let ((overlay (car overlays)))
1485 (if (overlay-get overlay prop)
1486 (setq found (cons overlay found))))
1487 (setq overlays (cdr overlays)))
1492 @defun overlays-in beg end
1493 This function returns a list of the overlays that overlap the region
1494 @var{beg} through @var{end}. ``Overlap'' means that at least one
1495 character is contained within the overlay and also contained within the
1496 specified region; however, empty overlays are included in the result if
1497 they are located at @var{beg}, or strictly between @var{beg} and @var{end}.
1500 @defun next-overlay-change pos
1501 This function returns the buffer position of the next beginning or end
1502 of an overlay, after @var{pos}. If there is none, it returns
1506 @defun previous-overlay-change pos
1507 This function returns the buffer position of the previous beginning or
1508 end of an overlay, before @var{pos}. If there is none, it returns
1512 Here's a function which uses @code{next-overlay-change} to search
1513 for the next character which gets a given property @code{prop} from
1514 either its overlays or its text properties (@pxref{Property Search}):
1517 (defun find-overlay-prop (prop)
1519 (while (and (not (eobp))
1520 (not (get-char-property (point) prop)))
1521 (goto-char (min (next-overlay-change (point))
1522 (next-single-property-change (point) prop))))
1526 Now you can search for a @code{happy} property like this:
1529 (find-overlay-prop 'happy)
1535 Since not all characters have the same width, these functions let you
1536 check the width of a character. @xref{Primitive Indent}, and
1537 @ref{Screen Lines}, for related functions.
1539 @defun char-width char
1540 This function returns the width in columns of the character @var{char},
1541 if it were displayed in the current buffer and the selected window.
1544 @defun string-width string
1545 This function returns the width in columns of the string @var{string},
1546 if it were displayed in the current buffer and the selected window.
1549 @defun truncate-string-to-width string width &optional start-column padding ellipsis
1550 This function returns the part of @var{string} that fits within
1551 @var{width} columns, as a new string.
1553 If @var{string} does not reach @var{width}, then the result ends where
1554 @var{string} ends. If one multi-column character in @var{string}
1555 extends across the column @var{width}, that character is not included in
1556 the result. Thus, the result can fall short of @var{width} but cannot
1559 The optional argument @var{start-column} specifies the starting column.
1560 If this is non-@code{nil}, then the first @var{start-column} columns of
1561 the string are omitted from the value. If one multi-column character in
1562 @var{string} extends across the column @var{start-column}, that
1563 character is not included.
1565 The optional argument @var{padding}, if non-@code{nil}, is a padding
1566 character added at the beginning and end of the result string, to extend
1567 it to exactly @var{width} columns. The padding character is used at the
1568 end of the result if it falls short of @var{width}. It is also used at
1569 the beginning of the result if one multi-column character in
1570 @var{string} extends across the column @var{start-column}.
1572 If @var{ellipsis} is non-@code{nil}, it should be a string which will
1573 replace the end of @var{str} (including any padding) if it extends
1574 beyond @var{end-column}, unless the display width of @var{str} is
1575 equal to or less than the display width of @var{ellipsis}. If
1576 @var{ellipsis} is non-@code{nil} and not a string, it stands for
1580 (truncate-string-to-width "\tab\t" 12 4)
1582 (truncate-string-to-width "\tab\t" 12 4 ?\s)
1588 @section Line Height
1591 The total height of each display line consists of the height of the
1592 contents of the line, plus optional additional vertical line spacing
1593 above or below the display line.
1595 The height of the line contents is the maximum height of any
1596 character or image on that display line, including the final newline
1597 if there is one. (A display line that is continued doesn't include a
1598 final newline.) That is the default line height, if you do nothing to
1599 specify a greater height. (In the most common case, this equals the
1600 height of the default frame font.)
1602 There are several ways to explicitly specify a larger line height,
1603 either by specifying an absolute height for the display line, or by
1604 specifying vertical space. However, no matter what you specify, the
1605 actual line height can never be less than the default.
1607 @kindex line-height @r{(text property)}
1608 A newline can have a @code{line-height} text or overlay property
1609 that controls the total height of the display line ending in that
1612 If the property value is @code{t}, the newline character has no
1613 effect on the displayed height of the line---the visible contents
1614 alone determine the height. This is useful for tiling small images
1615 (or image slices) without adding blank areas between the images.
1617 If the property value is a list of the form @code{(@var{height}
1618 @var{total})}, that adds extra space @emph{below} the display line.
1619 First Emacs uses @var{height} as a height spec to control extra space
1620 @emph{above} the line; then it adds enough space @emph{below} the line
1621 to bring the total line height up to @var{total}. In this case, the
1622 other ways to specify the line spacing are ignored.
1624 Any other kind of property value is a height spec, which translates
1625 into a number---the specified line height. There are several ways to
1626 write a height spec; here's how each of them translates into a number:
1630 If the height spec is a positive integer, the height value is that integer.
1632 If the height spec is a float, @var{float}, the numeric height value
1633 is @var{float} times the frame's default line height.
1634 @item (@var{face} . @var{ratio})
1635 If the height spec is a cons of the format shown, the numeric height
1636 is @var{ratio} times the height of face @var{face}. @var{ratio} can
1637 be any type of number, or @code{nil} which means a ratio of 1.
1638 If @var{face} is @code{t}, it refers to the current face.
1639 @item (nil . @var{ratio})
1640 If the height spec is a cons of the format shown, the numeric height
1641 is @var{ratio} times the height of the contents of the line.
1644 Thus, any valid height spec determines the height in pixels, one way
1645 or another. If the line contents' height is less than that, Emacs
1646 adds extra vertical space above the line to achieve the specified
1649 If you don't specify the @code{line-height} property, the line's
1650 height consists of the contents' height plus the line spacing.
1651 There are several ways to specify the line spacing for different
1652 parts of Emacs text.
1654 @vindex default-line-spacing
1655 You can specify the line spacing for all lines in a frame with the
1656 @code{line-spacing} frame parameter (@pxref{Layout Parameters}).
1657 However, if the variable @code{default-line-spacing} is
1658 non-@code{nil}, it overrides the frame's @code{line-spacing}
1659 parameter. An integer value specifies the number of pixels put below
1660 lines on graphical displays. A floating point number specifies the
1661 spacing relative to the frame's default line height.
1663 @vindex line-spacing
1664 You can specify the line spacing for all lines in a buffer via the
1665 buffer-local @code{line-spacing} variable. An integer value specifies
1666 the number of pixels put below lines on graphical displays. A floating
1667 point number specifies the spacing relative to the default frame line
1668 height. This overrides line spacings specified for the frame.
1670 @kindex line-spacing @r{(text property)}
1671 Finally, a newline can have a @code{line-spacing} text or overlay
1672 property that overrides the default frame line spacing and the buffer
1673 local @code{line-spacing} variable, for the display line ending in
1676 One way or another, these mechanisms specify a Lisp value for the
1677 spacing of each line. The value is a height spec, and it translates
1678 into a Lisp value as described above. However, in this case the
1679 numeric height value specifies the line spacing, rather than the line
1686 A @dfn{face} is a named collection of graphical attributes: font
1687 family, foreground color, background color, optional underlining, and
1688 many others. Faces are used in Emacs to control the style of display of
1689 particular parts of the text or the frame. @xref{Standard Faces,,,
1690 emacs, The GNU Emacs Manual}, for the list of faces Emacs normally
1694 Each face has its own @dfn{face number}, which distinguishes faces at
1695 low levels within Emacs. However, for most purposes, you refer to
1696 faces in Lisp programs by the symbols that name them.
1699 This function returns @code{t} if @var{object} is a face name string
1700 or symbol (or if it is a vector of the kind used internally to record
1701 face data). It returns @code{nil} otherwise.
1704 Each face name is meaningful for all frames, and by default it has the
1705 same meaning in all frames. But you can arrange to give a particular
1706 face name a special meaning in one frame if you wish.
1709 * Defining Faces:: How to define a face with @code{defface}.
1710 * Face Attributes:: What is in a face?
1711 * Attribute Functions:: Functions to examine and set face attributes.
1712 * Displaying Faces:: How Emacs combines the faces specified for a character.
1713 * Font Selection:: Finding the best available font for a face.
1714 * Face Functions:: How to define and examine faces.
1715 * Auto Faces:: Hook for automatic face assignment.
1716 * Font Lookup:: Looking up the names of available fonts
1717 and information about them.
1718 * Fontsets:: A fontset is a collection of fonts
1719 that handle a range of character sets.
1722 @node Defining Faces
1723 @subsection Defining Faces
1725 The way to define a new face is with @code{defface}. This creates a
1726 kind of customization item (@pxref{Customization}) which the user can
1727 customize using the Customization buffer (@pxref{Easy Customization,,,
1728 emacs, The GNU Emacs Manual}).
1730 @defmac defface face spec doc [keyword value]@dots{}
1731 This declares @var{face} as a customizable face that defaults
1732 according to @var{spec}. You should not quote the symbol @var{face},
1733 and it should not end in @samp{-face} (that would be redundant). The
1734 argument @var{doc} specifies the face documentation. The keywords you
1735 can use in @code{defface} are the same as in @code{defgroup} and
1736 @code{defcustom} (@pxref{Common Keywords}).
1738 When @code{defface} executes, it defines the face according to
1739 @var{spec}, then uses any customizations that were read from the
1740 init file (@pxref{Init File}) to override that specification.
1742 The purpose of @var{spec} is to specify how the face should appear on
1743 different kinds of terminals. It should be an alist whose elements
1744 have the form @code{(@var{display} @var{atts})}. Each element's
1745 @sc{car}, @var{display}, specifies a class of terminals. (The first
1746 element, if its @sc{car} is @code{default}, is special---it specifies
1747 defaults for the remaining elements). The element's @sc{cadr},
1748 @var{atts}, is a list of face attributes and their values; it
1749 specifies what the face should look like on that kind of terminal.
1750 The possible attributes are defined in the value of
1751 @code{custom-face-attributes}.
1753 The @var{display} part of an element of @var{spec} determines which
1754 frames the element matches. If more than one element of @var{spec}
1755 matches a given frame, the first element that matches is the one used
1756 for that frame. There are three possibilities for @var{display}:
1759 @item @code{default}
1760 This element of @var{spec} doesn't match any frames; instead, it
1761 specifies defaults that apply to all frames. This kind of element, if
1762 used, must be the first element of @var{spec}. Each of the following
1763 elements can override any or all of these defaults.
1766 This element of @var{spec} matches all frames. Therefore, any
1767 subsequent elements of @var{spec} are never used. Normally
1768 @code{t} is used in the last (or only) element of @var{spec}.
1771 If @var{display} is a list, each element should have the form
1772 @code{(@var{characteristic} @var{value}@dots{})}. Here
1773 @var{characteristic} specifies a way of classifying frames, and the
1774 @var{value}s are possible classifications which @var{display} should
1775 apply to. Here are the possible values of @var{characteristic}:
1779 The kind of window system the frame uses---either @code{graphic} (any
1780 graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console),
1781 @code{w32} (for MS Windows 9X/NT/2K/XP), @code{mac} (for the Macintosh
1782 display), or @code{tty} (a non-graphics-capable display).
1783 @xref{Window Systems, window-system}.
1786 What kinds of colors the frame supports---either @code{color},
1787 @code{grayscale}, or @code{mono}.
1790 The kind of background---either @code{light} or @code{dark}.
1793 An integer that represents the minimum number of colors the frame
1794 should support. This matches a frame if its
1795 @code{display-color-cells} value is at least the specified integer.
1798 Whether or not the frame can display the face attributes given in
1799 @var{value}@dots{} (@pxref{Face Attributes}). See the documentation
1800 for the function @code{display-supports-face-attributes-p} for more
1801 information on exactly how this testing is done. @xref{Display Face
1805 If an element of @var{display} specifies more than one @var{value} for a
1806 given @var{characteristic}, any of those values is acceptable. If
1807 @var{display} has more than one element, each element should specify a
1808 different @var{characteristic}; then @emph{each} characteristic of the
1809 frame must match one of the @var{value}s specified for it in
1814 Here's how the standard face @code{region} is defined:
1818 '((((class color) (min-colors 88) (background dark))
1819 :background "blue3")
1821 (((class color) (min-colors 88) (background light))
1822 :background "lightgoldenrod2")
1823 (((class color) (min-colors 16) (background dark))
1824 :background "blue3")
1825 (((class color) (min-colors 16) (background light))
1826 :background "lightgoldenrod2")
1827 (((class color) (min-colors 8))
1828 :background "blue" :foreground "white")
1829 (((type tty) (class mono))
1831 (t :background "gray"))
1833 "Basic face for highlighting the region."
1834 :group 'basic-faces)
1838 Internally, @code{defface} uses the symbol property
1839 @code{face-defface-spec} to record the face attributes specified in
1840 @code{defface}, @code{saved-face} for the attributes saved by the user
1841 with the customization buffer, @code{customized-face} for the
1842 attributes customized by the user for the current session, but not
1843 saved, and @code{face-documentation} for the documentation string.
1845 @defopt frame-background-mode
1846 This option, if non-@code{nil}, specifies the background type to use for
1847 interpreting face definitions. If it is @code{dark}, then Emacs treats
1848 all frames as if they had a dark background, regardless of their actual
1849 background colors. If it is @code{light}, then Emacs treats all frames
1850 as if they had a light background.
1853 @node Face Attributes
1854 @subsection Face Attributes
1855 @cindex face attributes
1857 The effect of using a face is determined by a fixed set of @dfn{face
1858 attributes}. This table lists all the face attributes, and what they
1859 mean. Note that in general, more than one face can be specified for a
1860 given piece of text; when that happens, the attributes of all the faces
1861 are merged to specify how to display the text. @xref{Displaying Faces}.
1863 Any attribute in a face can have the value @code{unspecified}. This
1864 means the face doesn't specify that attribute. In face merging, when
1865 the first face fails to specify a particular attribute, that means the
1866 next face gets a chance. However, the @code{default} face must
1867 specify all attributes.
1869 Some of these font attributes are meaningful only on certain kinds of
1870 displays---if your display cannot handle a certain attribute, the
1871 attribute is ignored. (The attributes @code{:family}, @code{:width},
1872 @code{:height}, @code{:weight}, and @code{:slant} correspond to parts of
1873 an X Logical Font Descriptor.)
1877 Font family name, or fontset name (@pxref{Fontsets}). If you specify a
1878 font family name, the wild-card characters @samp{*} and @samp{?} are
1882 Relative proportionate width, also known as the character set width or
1883 set width. This should be one of the symbols @code{ultra-condensed},
1884 @code{extra-condensed}, @code{condensed}, @code{semi-condensed},
1885 @code{normal}, @code{semi-expanded}, @code{expanded},
1886 @code{extra-expanded}, or @code{ultra-expanded}.
1889 Either the font height, an integer in units of 1/10 point, a floating
1890 point number specifying the amount by which to scale the height of any
1891 underlying face, or a function, which is called with the old height
1892 (from the underlying face), and should return the new height.
1895 Font weight---a symbol from this series (from most dense to most faint):
1896 @code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
1897 @code{normal}, @code{semi-light}, @code{light}, @code{extra-light},
1898 or @code{ultra-light}.
1900 On a text-only terminal, any weight greater than normal is displayed as
1901 extra bright, and any weight less than normal is displayed as
1902 half-bright (provided the terminal supports the feature).
1905 Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal},
1906 @code{reverse-italic}, or @code{reverse-oblique}.
1908 On a text-only terminal, slanted text is displayed as half-bright, if
1909 the terminal supports the feature.
1912 Foreground color, a string. The value can be a system-defined color
1913 name, or a hexadecimal color specification of the form
1914 @samp{#@var{rr}@var{gg}@var{bb}}. (@samp{#000000} is black,
1915 @samp{#ff0000} is red, @samp{#00ff00} is green, @samp{#0000ff} is
1916 blue, and @samp{#ffffff} is white.)
1919 Background color, a string, like the foreground color.
1921 @item :inverse-video
1922 Whether or not characters should be displayed in inverse video. The
1923 value should be @code{t} (yes) or @code{nil} (no).
1926 The background stipple, a bitmap.
1928 The value can be a string; that should be the name of a file containing
1929 external-format X bitmap data. The file is found in the directories
1930 listed in the variable @code{x-bitmap-file-path}.
1932 Alternatively, the value can specify the bitmap directly, with a list
1933 of the form @code{(@var{width} @var{height} @var{data})}. Here,
1934 @var{width} and @var{height} specify the size in pixels, and
1935 @var{data} is a string containing the raw bits of the bitmap, row by
1936 row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes
1937 in the string (which should be a unibyte string for best results).
1938 This means that each row always occupies at least one whole byte.
1940 If the value is @code{nil}, that means use no stipple pattern.
1942 Normally you do not need to set the stipple attribute, because it is
1943 used automatically to handle certain shades of gray.
1946 Whether or not characters should be underlined, and in what color. If
1947 the value is @code{t}, underlining uses the foreground color of the
1948 face. If the value is a string, underlining uses that color. The
1949 value @code{nil} means do not underline.
1952 Whether or not characters should be overlined, and in what color.
1953 The value is used like that of @code{:underline}.
1955 @item :strike-through
1956 Whether or not characters should be strike-through, and in what
1957 color. The value is used like that of @code{:underline}.
1960 The name of a face from which to inherit attributes, or a list of face
1961 names. Attributes from inherited faces are merged into the face like an
1962 underlying face would be, with higher priority than underlying faces.
1963 If a list of faces is used, attributes from faces earlier in the list
1964 override those from later faces.
1967 Whether or not a box should be drawn around characters, its color, the
1968 width of the box lines, and 3D appearance.
1971 Here are the possible values of the @code{:box} attribute, and what
1979 Draw a box with lines of width 1, in the foreground color.
1982 Draw a box with lines of width 1, in color @var{color}.
1984 @item @code{(:line-width @var{width} :color @var{color} :style @var{style})}
1985 This way you can explicitly specify all aspects of the box. The value
1986 @var{width} specifies the width of the lines to draw; it defaults to 1.
1988 The value @var{color} specifies the color to draw with. The default is
1989 the foreground color of the face for simple boxes, and the background
1990 color of the face for 3D boxes.
1992 The value @var{style} specifies whether to draw a 3D box. If it is
1993 @code{released-button}, the box looks like a 3D button that is not being
1994 pressed. If it is @code{pressed-button}, the box looks like a 3D button
1995 that is being pressed. If it is @code{nil} or omitted, a plain 2D box
1999 In older versions of Emacs, before @code{:family}, @code{:height},
2000 @code{:width}, @code{:weight}, and @code{:slant} existed, these
2001 attributes were used to specify the type face. They are now
2002 semi-obsolete, but they still work:
2006 This attribute specifies the font name.
2009 A non-@code{nil} value specifies a bold font.
2012 A non-@code{nil} value specifies an italic font.
2015 For compatibility, you can still set these ``attributes'', even
2016 though they are not real face attributes. Here is what that does:
2020 You can specify an X font name as the ``value'' of this ``attribute'';
2021 that sets the @code{:family}, @code{:width}, @code{:height},
2022 @code{:weight}, and @code{:slant} attributes according to the font name.
2024 If the value is a pattern with wildcards, the first font that matches
2025 the pattern is used to set these attributes.
2028 A non-@code{nil} makes the face bold; @code{nil} makes it normal.
2029 This actually works by setting the @code{:weight} attribute.
2032 A non-@code{nil} makes the face italic; @code{nil} makes it normal.
2033 This actually works by setting the @code{:slant} attribute.
2036 @defvar x-bitmap-file-path
2037 This variable specifies a list of directories for searching
2038 for bitmap files, for the @code{:stipple} attribute.
2041 @defun bitmap-spec-p object
2042 This returns @code{t} if @var{object} is a valid bitmap specification,
2043 suitable for use with @code{:stipple} (see above). It returns
2044 @code{nil} otherwise.
2047 @node Attribute Functions
2048 @subsection Face Attribute Functions
2050 You can modify the attributes of an existing face with the following
2051 functions. If you specify @var{frame}, they affect just that frame;
2052 otherwise, they affect all frames as well as the defaults that apply to
2055 @defun set-face-attribute face frame &rest arguments
2056 This function sets one or more attributes of face @var{face}
2057 for frame @var{frame}. If @var{frame} is @code{nil}, it sets
2058 the attribute for all frames, and the defaults for new frames.
2060 The extra arguments @var{arguments} specify the attributes to set, and
2061 the values for them. They should consist of alternating attribute names
2062 (such as @code{:family} or @code{:underline}) and corresponding values.
2066 (set-face-attribute 'foo nil
2073 sets the attributes @code{:width}, @code{:weight} and @code{:underline}
2074 to the corresponding values.
2077 @defun face-attribute face attribute &optional frame inherit
2078 This returns the value of the @var{attribute} attribute of face
2079 @var{face} on @var{frame}. If @var{frame} is @code{nil},
2080 that means the selected frame (@pxref{Input Focus}).
2082 If @var{frame} is @code{t}, the value is the default for
2083 @var{face} for new frames.
2085 If @var{inherit} is @code{nil}, only attributes directly defined by
2086 @var{face} are considered, so the return value may be
2087 @code{unspecified}, or a relative value. If @var{inherit} is
2088 non-@code{nil}, @var{face}'s definition of @var{attribute} is merged
2089 with the faces specified by its @code{:inherit} attribute; however the
2090 return value may still be @code{unspecified} or relative. If
2091 @var{inherit} is a face or a list of faces, then the result is further
2092 merged with that face (or faces), until it becomes specified and
2095 To ensure that the return value is always specified and absolute, use
2096 a value of @code{default} for @var{inherit}; this will resolve any
2097 unspecified or relative values by merging with the @code{default} face
2098 (which is always completely specified).
2103 (face-attribute 'bold :weight)
2108 @defun face-attribute-relative-p attribute value
2109 This function returns non-@code{nil} if @var{value}, when used as the
2110 value of the face attribute @var{attribute}, is relative. This means
2111 it would modify, rather than completely override, any value that comes
2112 from a subsequent face in the face list or that is inherited from
2115 @code{unspecified} is a relative value for all attributes.
2116 For @code{:height}, floating point values are also relative.
2121 (read-face-name "Describe face" "= `default' face" t)
2124 prompts with @samp{Describe face (default = `default' face): }.
2127 @defun merge-face-attribute attribute value1 value2
2128 If @var{value1} is a relative value for the face attribute
2129 @var{attribute}, returns it merged with the underlying value
2130 @var{value2}; otherwise, if @var{value1} is an absolute value for the
2131 face attribute @var{attribute}, returns @var{value1} unchanged.
2134 The functions above did not exist before Emacs 21. For compatibility
2135 with older Emacs versions, you can use the following functions to set
2136 and examine the face attributes which existed in those versions.
2138 @defun set-face-foreground face color &optional frame
2139 @defunx set-face-background face color &optional frame
2140 These functions set the foreground (or background, respectively) color
2141 of face @var{face} to @var{color}. The argument @var{color} should be a
2142 string, the name of a color.
2144 Certain shades of gray are implemented by stipple patterns on
2145 black-and-white screens.
2148 @defun set-face-stipple face pattern &optional frame
2149 This function sets the background stipple pattern of face @var{face}
2150 to @var{pattern}. The argument @var{pattern} should be the name of a
2151 stipple pattern defined by the X server, or actual bitmap data
2152 (@pxref{Face Attributes}), or @code{nil} meaning don't use stipple.
2154 Normally there is no need to pay attention to stipple patterns, because
2155 they are used automatically to handle certain shades of gray.
2158 @defun set-face-font face font &optional frame
2159 This function sets the font of face @var{face}. This actually sets
2160 the attributes @code{:family}, @code{:width}, @code{:height},
2161 @code{:weight}, and @code{:slant} according to the font name
2165 @defun set-face-bold-p face bold-p &optional frame
2166 This function specifies whether @var{face} should be bold. If
2167 @var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no.
2168 This actually sets the @code{:weight} attribute.
2171 @defun set-face-italic-p face italic-p &optional frame
2172 This function specifies whether @var{face} should be italic. If
2173 @var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no.
2174 This actually sets the @code{:slant} attribute.
2177 @defun set-face-underline-p face underline-p &optional frame
2178 This function sets the underline attribute of face @var{face}.
2179 Non-@code{nil} means do underline; @code{nil} means don't.
2182 @defun set-face-inverse-video-p face inverse-video-p &optional frame
2183 This function sets the @code{:inverse-video} attribute of face
2187 @defun invert-face face &optional frame
2188 This function swaps the foreground and background colors of face
2192 These functions examine the attributes of a face. If you don't
2193 specify @var{frame}, they refer to the default data for new frames.
2194 They return the symbol @code{unspecified} if the face doesn't define any
2195 value for that attribute.
2197 @defun face-foreground face &optional frame inherit
2198 @defunx face-background face &optional frame inherit
2199 These functions return the foreground color (or background color,
2200 respectively) of face @var{face}, as a string.
2202 If @var{inherit} is @code{nil}, only a color directly defined by the face is
2203 returned. If @var{inherit} is non-@code{nil}, any faces specified by its
2204 @code{:inherit} attribute are considered as well, and if @var{inherit}
2205 is a face or a list of faces, then they are also considered, until a
2206 specified color is found. To ensure that the return value is always
2207 specified, use a value of @code{default} for @var{inherit}.
2210 @defun face-stipple face &optional frame inherit
2211 This function returns the name of the background stipple pattern of face
2212 @var{face}, or @code{nil} if it doesn't have one.
2214 If @var{inherit} is @code{nil}, only a stipple directly defined by the
2215 face is returned. If @var{inherit} is non-@code{nil}, any faces
2216 specified by its @code{:inherit} attribute are considered as well, and
2217 if @var{inherit} is a face or a list of faces, then they are also
2218 considered, until a specified stipple is found. To ensure that the
2219 return value is always specified, use a value of @code{default} for
2223 @defun face-font face &optional frame
2224 This function returns the name of the font of face @var{face}.
2227 @defun face-bold-p face &optional frame
2228 This function returns @code{t} if @var{face} is bold---that is, if it is
2229 bolder than normal. It returns @code{nil} otherwise.
2232 @defun face-italic-p face &optional frame
2233 This function returns @code{t} if @var{face} is italic or oblique,
2234 @code{nil} otherwise.
2237 @defun face-underline-p face &optional frame
2238 This function returns the @code{:underline} attribute of face @var{face}.
2241 @defun face-inverse-video-p face &optional frame
2242 This function returns the @code{:inverse-video} attribute of face @var{face}.
2245 @node Displaying Faces
2246 @subsection Displaying Faces
2248 Here are the ways to specify which faces to use for display of text:
2252 With defaults. The @code{default} face is used as the ultimate
2253 default for all text. (In Emacs 19 and 20, the @code{default}
2254 face is used only when no other face is specified.)
2257 For a mode line or header line, the face @code{mode-line} or
2258 @code{mode-line-inactive}, or @code{header-line}, is merged in just
2259 before @code{default}.
2262 With text properties. A character can have a @code{face} property; if
2263 so, the faces and face attributes specified there apply. @xref{Special
2266 If the character has a @code{mouse-face} property, that is used instead
2267 of the @code{face} property when the mouse is ``near enough'' to the
2271 With overlays. An overlay can have @code{face} and @code{mouse-face}
2272 properties too; they apply to all the text covered by the overlay.
2275 With a region that is active. In Transient Mark mode, the region is
2276 highlighted with the face @code{region} (@pxref{Standard Faces,,,
2277 emacs, The GNU Emacs Manual}).
2280 With special glyphs. Each glyph can specify a particular face
2281 number. @xref{Glyphs}.
2284 If these various sources together specify more than one face for a
2285 particular character, Emacs merges the attributes of the various faces
2286 specified. For each attribute, Emacs tries first the face of any
2287 special glyph; then the face for region highlighting, if appropriate;
2288 then the faces specified by overlays, followed by those specified by
2289 text properties, then the @code{mode-line} or
2290 @code{mode-line-inactive} or @code{header-line} face (if in a mode
2291 line or a header line), and last the @code{default} face.
2293 When multiple overlays cover one character, an overlay with higher
2294 priority overrides those with lower priority. @xref{Overlays}.
2296 @node Font Selection
2297 @subsection Font Selection
2299 @dfn{Selecting a font} means mapping the specified face attributes for
2300 a character to a font that is available on a particular display. The
2301 face attributes, as determined by face merging, specify most of the
2302 font choice, but not all. Part of the choice depends on what character
2305 If the face specifies a fontset name, that fontset determines a
2306 pattern for fonts of the given charset. If the face specifies a font
2307 family, a font pattern is constructed.
2309 Emacs tries to find an available font for the given face attributes
2310 and character's registry and encoding. If there is a font that matches
2311 exactly, it is used, of course. The hard case is when no available font
2312 exactly fits the specification. Then Emacs looks for one that is
2313 ``close''---one attribute at a time. You can specify the order to
2314 consider the attributes. In the case where a specified font family is
2315 not available, you can specify a set of mappings for alternatives to
2318 @defvar face-font-selection-order
2319 This variable specifies the order of importance of the face attributes
2320 @code{:width}, @code{:height}, @code{:weight}, and @code{:slant}. The
2321 value should be a list containing those four symbols, in order of
2322 decreasing importance.
2324 Font selection first finds the best available matches for the first
2325 attribute listed; then, among the fonts which are best in that way, it
2326 searches for the best matches in the second attribute, and so on.
2328 The attributes @code{:weight} and @code{:width} have symbolic values in
2329 a range centered around @code{normal}. Matches that are more extreme
2330 (farther from @code{normal}) are somewhat preferred to matches that are
2331 less extreme (closer to @code{normal}); this is designed to ensure that
2332 non-normal faces contrast with normal ones, whenever possible.
2334 The default is @code{(:width :height :weight :slant)}, which means first
2335 find the fonts closest to the specified @code{:width}, then---among the
2336 fonts with that width---find a best match for the specified font height,
2339 One example of a case where this variable makes a difference is when the
2340 default font has no italic equivalent. With the default ordering, the
2341 @code{italic} face will use a non-italic font that is similar to the
2342 default one. But if you put @code{:slant} before @code{:height}, the
2343 @code{italic} face will use an italic font, even if its height is not
2347 @defvar face-font-family-alternatives
2348 This variable lets you specify alternative font families to try, if a
2349 given family is specified and doesn't exist. Each element should have
2353 (@var{family} @var{alternate-families}@dots{})
2356 If @var{family} is specified but not available, Emacs will try the other
2357 families given in @var{alternate-families}, one by one, until it finds a
2358 family that does exist.
2361 @defvar face-font-registry-alternatives
2362 This variable lets you specify alternative font registries to try, if a
2363 given registry is specified and doesn't exist. Each element should have
2367 (@var{registry} @var{alternate-registries}@dots{})
2370 If @var{registry} is specified but not available, Emacs will try the
2371 other registries given in @var{alternate-registries}, one by one,
2372 until it finds a registry that does exist.
2375 Emacs can make use of scalable fonts, but by default it does not use
2376 them, since the use of too many or too big scalable fonts can crash
2379 @defvar scalable-fonts-allowed
2380 This variable controls which scalable fonts to use. A value of
2381 @code{nil}, the default, means do not use scalable fonts. @code{t}
2382 means to use any scalable font that seems appropriate for the text.
2384 Otherwise, the value must be a list of regular expressions. Then a
2385 scalable font is enabled for use if its name matches any regular
2386 expression in the list. For example,
2389 (setq scalable-fonts-allowed '("muleindian-2$"))
2393 allows the use of scalable fonts with registry @code{muleindian-2}.
2396 @defvar face-font-rescale-alist
2397 This variable specifies scaling for certain faces. Its value should
2398 be a list of elements of the form
2401 (@var{fontname-regexp} . @var{scale-factor})
2404 If @var{fontname-regexp} matches the font name that is about to be
2405 used, this says to choose a larger similar font according to the
2406 factor @var{scale-factor}. You would use this feature to normalize
2407 the font size if certain fonts are bigger or smaller than their
2408 nominal heights and widths would suggest.
2411 @node Face Functions
2412 @subsection Functions for Working with Faces
2414 Here are additional functions for creating and working with faces.
2416 @defun make-face name
2417 This function defines a new face named @var{name}, initially with all
2418 attributes @code{nil}. It does nothing if there is already a face named
2423 This function returns a list of all defined face names.
2426 @defun copy-face old-face new-name &optional frame new-frame
2427 This function defines a face named @var{new-name} as a copy of the existing
2428 face named @var{old-face}. It creates the face @var{new-name} if that
2429 doesn't already exist.
2431 If the optional argument @var{frame} is given, this function applies
2432 only to that frame. Otherwise it applies to each frame individually,
2433 copying attributes from @var{old-face} in each frame to @var{new-face}
2436 If the optional argument @var{new-frame} is given, then @code{copy-face}
2437 copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
2442 This function returns the face number of face @var{face}.
2445 @defun face-documentation face
2446 This function returns the documentation string of face @var{face}, or
2447 @code{nil} if none was specified for it.
2450 @defun face-equal face1 face2 &optional frame
2451 This returns @code{t} if the faces @var{face1} and @var{face2} have the
2452 same attributes for display.
2455 @defun face-differs-from-default-p face &optional frame
2456 This returns non-@code{nil} if the face @var{face} displays
2457 differently from the default face.
2461 A @dfn{face alias} provides an equivalent name for a face. You can
2462 define a face alias by giving the alias symbol the @code{face-alias}
2463 property, with a value of the target face name. The following example
2464 makes @code{modeline} an alias for the @code{mode-line} face.
2467 (put 'modeline 'face-alias 'mode-line)
2472 @subsection Automatic Face Assignment
2473 @cindex automatic face assignment
2474 @cindex faces, automatic choice
2476 @cindex Font-Lock mode
2477 This hook is used for automatically assigning faces to text in the
2478 buffer. It is part of the implementation of Font-Lock mode.
2480 @defvar fontification-functions
2481 This variable holds a list of functions that are called by Emacs
2482 redisplay as needed to assign faces automatically to text in the buffer.
2484 The functions are called in the order listed, with one argument, a
2485 buffer position @var{pos}. Each function should attempt to assign faces
2486 to the text in the current buffer starting at @var{pos}.
2488 Each function should record the faces they assign by setting the
2489 @code{face} property. It should also add a non-@code{nil}
2490 @code{fontified} property for all the text it has assigned faces to.
2491 That property tells redisplay that faces have been assigned to that text
2494 It is probably a good idea for each function to do nothing if the
2495 character after @var{pos} already has a non-@code{nil} @code{fontified}
2496 property, but this is not required. If one function overrides the
2497 assignments made by a previous one, the properties as they are
2498 after the last function finishes are the ones that really matter.
2500 For efficiency, we recommend writing these functions so that they
2501 usually assign faces to around 400 to 600 characters at each call.
2505 @subsection Looking Up Fonts
2507 @defun x-list-fonts pattern &optional face frame maximum
2508 This function returns a list of available font names that match
2509 @var{pattern}. If the optional arguments @var{face} and @var{frame} are
2510 specified, then the list is limited to fonts that are the same size as
2511 @var{face} currently is on @var{frame}.
2513 The argument @var{pattern} should be a string, perhaps with wildcard
2514 characters: the @samp{*} character matches any substring, and the
2515 @samp{?} character matches any single character. Pattern matching
2516 of font names ignores case.
2518 If you specify @var{face} and @var{frame}, @var{face} should be a face name
2519 (a symbol) and @var{frame} should be a frame.
2521 The optional argument @var{maximum} sets a limit on how many fonts to
2522 return. If this is non-@code{nil}, then the return value is truncated
2523 after the first @var{maximum} matching fonts. Specifying a small value
2524 for @var{maximum} can make this function much faster, in cases where
2525 many fonts match the pattern.
2528 @defun x-family-fonts &optional family frame
2529 This function returns a list describing the available fonts for family
2530 @var{family} on @var{frame}. If @var{family} is omitted or @code{nil},
2531 this list applies to all families, and therefore, it contains all
2532 available fonts. Otherwise, @var{family} must be a string; it may
2533 contain the wildcards @samp{?} and @samp{*}.
2535 The list describes the display that @var{frame} is on; if @var{frame} is
2536 omitted or @code{nil}, it applies to the selected frame's display
2537 (@pxref{Input Focus}).
2539 The list contains a vector of the following form for each font:
2542 [@var{family} @var{width} @var{point-size} @var{weight} @var{slant}
2543 @var{fixed-p} @var{full} @var{registry-and-encoding}]
2546 The first five elements correspond to face attributes; if you
2547 specify these attributes for a face, it will use this font.
2549 The last three elements give additional information about the font.
2550 @var{fixed-p} is non-@code{nil} if the font is fixed-pitch.
2551 @var{full} is the full name of the font, and
2552 @var{registry-and-encoding} is a string giving the registry and
2553 encoding of the font.
2555 The result list is sorted according to the current face font sort order.
2558 @defun x-font-family-list &optional frame
2559 This function returns a list of the font families available for
2560 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, it
2561 describes the selected frame's display (@pxref{Input Focus}).
2563 The value is a list of elements of this form:
2566 (@var{family} . @var{fixed-p})
2570 Here @var{family} is a font family, and @var{fixed-p} is
2571 non-@code{nil} if fonts of that family are fixed-pitch.
2574 @defvar font-list-limit
2575 This variable specifies maximum number of fonts to consider in font
2576 matching. The function @code{x-family-fonts} will not return more than
2577 that many fonts, and font selection will consider only that many fonts
2578 when searching a matching font for face attributes. The default is
2583 @subsection Fontsets
2585 A @dfn{fontset} is a list of fonts, each assigned to a range of
2586 character codes. An individual font cannot display the whole range of
2587 characters that Emacs supports, but a fontset can. Fontsets have names,
2588 just as fonts do, and you can use a fontset name in place of a font name
2589 when you specify the ``font'' for a frame or a face. Here is
2590 information about defining a fontset under Lisp program control.
2592 @defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
2593 This function defines a new fontset according to the specification
2594 string @var{fontset-spec}. The string should have this format:
2597 @var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
2601 Whitespace characters before and after the commas are ignored.
2603 The first part of the string, @var{fontpattern}, should have the form of
2604 a standard X font name, except that the last two fields should be
2605 @samp{fontset-@var{alias}}.
2607 The new fontset has two names, one long and one short. The long name is
2608 @var{fontpattern} in its entirety. The short name is
2609 @samp{fontset-@var{alias}}. You can refer to the fontset by either
2610 name. If a fontset with the same name already exists, an error is
2611 signaled, unless @var{noerror} is non-@code{nil}, in which case this
2612 function does nothing.
2614 If optional argument @var{style-variant-p} is non-@code{nil}, that says
2615 to create bold, italic and bold-italic variants of the fontset as well.
2616 These variant fontsets do not have a short name, only a long one, which
2617 is made by altering @var{fontpattern} to indicate the bold or italic
2620 The specification string also says which fonts to use in the fontset.
2621 See below for the details.
2624 The construct @samp{@var{charset}:@var{font}} specifies which font to
2625 use (in this fontset) for one particular character set. Here,
2626 @var{charset} is the name of a character set, and @var{font} is the font
2627 to use for that character set. You can use this construct any number of
2628 times in the specification string.
2630 For the remaining character sets, those that you don't specify
2631 explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
2632 @samp{fontset-@var{alias}} with a value that names one character set.
2633 For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced
2634 with @samp{ISO8859-1}.
2636 In addition, when several consecutive fields are wildcards, Emacs
2637 collapses them into a single wildcard. This is to prevent use of
2638 auto-scaled fonts. Fonts made by scaling larger fonts are not usable
2639 for editing, and scaling a smaller font is not useful because it is
2640 better to use the smaller font in its own size, which Emacs does.
2642 Thus if @var{fontpattern} is this,
2645 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
2649 the font specification for @acronym{ASCII} characters would be this:
2652 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
2656 and the font specification for Chinese GB2312 characters would be this:
2659 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
2662 You may not have any Chinese font matching the above font
2663 specification. Most X distributions include only Chinese fonts that
2664 have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
2665 such a case, @samp{Fontset-@var{n}} can be specified as below:
2668 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
2669 chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
2673 Then, the font specifications for all but Chinese GB2312 characters have
2674 @samp{fixed} in the @var{family} field, and the font specification for
2675 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
2678 @defun set-fontset-font name character fontname &optional frame
2679 This function modifies the existing fontset @var{name} to
2680 use the font name @var{fontname} for the character @var{character}.
2682 If @var{name} is @code{nil}, this function modifies the default
2683 fontset, whose short name is @samp{fontset-default}.
2685 @var{character} may be a cons; @code{(@var{from} . @var{to})}, where
2686 @var{from} and @var{to} are non-generic characters. In that case, use
2687 @var{fontname} for all characters in the range @var{from} and @var{to}
2690 @var{character} may be a charset. In that case, use
2691 @var{fontname} for all character in the charsets.
2693 @var{fontname} may be a cons; @code{(@var{family} . @var{registry})},
2694 where @var{family} is a family name of a font (possibly including a
2695 foundry name at the head), @var{registry} is a registry name of a font
2696 (possibly including an encoding name at the tail).
2698 For instance, this changes the default fontset to use a font of which
2699 registry name is @samp{JISX0208.1983} for all characters belonging to
2700 the charset @code{japanese-jisx0208}.
2703 (set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
2707 @defun char-displayable-p char
2708 This function returns @code{t} if Emacs ought to be able to display
2709 @var{char}. More precisely, if the selected frame's fontset has a
2710 font to display the character set that @var{char} belongs to.
2712 Fontsets can specify a font on a per-character basis; when the fontset
2713 does that, this function's value may not be accurate.
2720 The @dfn{fringes} of a window are thin vertical strips down the
2721 sides that are used for displaying bitmaps that indicate truncation,
2722 continuation, horizontal scrolling, and the overlay arrow.
2725 * Fringe Size/Pos:: Specifying where to put the window fringes.
2726 * Fringe Indicators:: Displaying indicator icons in the window fringes.
2727 * Fringe Cursors:: Displaying cursors in the right fringe.
2728 * Fringe Bitmaps:: Specifying bitmaps for fringe indicators.
2729 * Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes.
2730 * Overlay Arrow:: Display of an arrow to indicate position.
2733 @node Fringe Size/Pos
2734 @subsection Fringe Size and Position
2736 The following buffer-local variables control the position and width
2737 of the window fringes.
2739 @defvar fringes-outside-margins
2740 The fringes normally appear between the display margins and the window
2741 text. If the value is non-@code{nil}, they appear outside the display
2742 margins. @xref{Display Margins}.
2745 @defvar left-fringe-width
2746 This variable, if non-@code{nil}, specifies the width of the left
2747 fringe in pixels. A value of @code{nil} means to use the left fringe
2748 width from the window's frame.
2751 @defvar right-fringe-width
2752 This variable, if non-@code{nil}, specifies the width of the right
2753 fringe in pixels. A value of @code{nil} means to use the right fringe
2754 width from the window's frame.
2757 The values of these variables take effect when you display the
2758 buffer in a window. If you change them while the buffer is visible,
2759 you can call @code{set-window-buffer} to display it once again in the
2760 same window, to make the changes take effect.
2762 @defun set-window-fringes window left &optional right outside-margins
2763 This function sets the fringe widths of window @var{window}.
2764 If @var{window} is @code{nil}, the selected window is used.
2766 The argument @var{left} specifies the width in pixels of the left
2767 fringe, and likewise @var{right} for the right fringe. A value of
2768 @code{nil} for either one stands for the default width. If
2769 @var{outside-margins} is non-@code{nil}, that specifies that fringes
2770 should appear outside of the display margins.
2773 @defun window-fringes &optional window
2774 This function returns information about the fringes of a window
2775 @var{window}. If @var{window} is omitted or @code{nil}, the selected
2776 window is used. The value has the form @code{(@var{left-width}
2777 @var{right-width} @var{outside-margins})}.
2781 @node Fringe Indicators
2782 @subsection Fringe Indicators
2783 @cindex fringe indicators
2784 @cindex indicators, fringe
2786 The @dfn{fringe indicators} are tiny icons Emacs displays in the
2787 window fringe (on a graphic display) to indicate truncated or
2788 continued lines, buffer boundaries, overlay arrow, etc.
2790 @defopt indicate-empty-lines
2791 @cindex fringes, and empty line indication
2792 When this is non-@code{nil}, Emacs displays a special glyph in the
2793 fringe of each empty line at the end of the buffer, on graphical
2794 displays. @xref{Fringes}. This variable is automatically
2795 buffer-local in every buffer.
2798 @defvar indicate-buffer-boundaries
2799 This buffer-local variable controls how the buffer boundaries and
2800 window scrolling are indicated in the window fringes.
2802 Emacs can indicate the buffer boundaries---that is, the first and last
2803 line in the buffer---with angle icons when they appear on the screen.
2804 In addition, Emacs can display an up-arrow in the fringe to show
2805 that there is text above the screen, and a down-arrow to show
2806 there is text below the screen.
2808 There are four kinds of basic values:
2812 Don't display the icons.
2814 Display them in the left fringe.
2816 Display them in the right fringe.
2817 @item @var{anything-else}
2818 Display the icon at the top of the window top in the left fringe, and other
2819 in the right fringe.
2822 If value is a cons @code{(@var{angles} . @var{arrows})}, @var{angles}
2823 controls the angle icons, and @var{arrows} controls the arrows. Both
2824 @var{angles} and @var{arrows} work according to the table above.
2825 Thus, @code{(t . right)} places the top angle icon in the left
2826 fringe, the bottom angle icon in the right fringe, and both arrows in
2830 @defvar default-indicate-buffer-boundaries
2831 The value of this variable is the default value for
2832 @code{indicate-buffer-boundaries} in buffers that do not override it.
2835 @defvar fringe-indicator-alist
2836 This buffer-local variable specifies the mapping from logical fringe
2837 indicators to the actual bitmaps displayed in the window fringes.
2839 These symbols identify the logical fringe indicators:
2842 @item Truncation and continuation line indicators:
2843 @code{truncation}, @code{continuation}.
2845 @item Buffer position indicators:
2846 @code{up}, @code{down},
2847 @code{top}, @code{bottom},
2850 @item Empty line indicator:
2853 @item Overlay arrow indicator:
2854 @code{overlay-arrow}.
2856 @item Unknown bitmap indicator:
2860 The value is an alist where each element @code{(@var{indicator} . @var{bitmaps})}
2861 specifies the fringe bitmaps used to display a specific logical
2864 Here, @var{indicator} specifies the logical indicator type, and
2865 @var{bitmaps} is list of symbols @code{(@var{left} @var{right}
2866 [@var{left1} @var{right1}])} which specifies the actual bitmap shown
2867 in the left or right fringe for the logical indicator.
2869 The @var{left} and @var{right} symbols specify the bitmaps shown in
2870 the left and/or right fringe for the specific indicator. The
2871 @var{left1} or @var{right1} bitmaps are used only for the `bottom' and
2872 `top-bottom indicators when the last (only) line in has no final
2873 newline. Alternatively, @var{bitmaps} may be a single symbol which is
2874 used in both left and right fringes.
2876 When @code{fringe-indicator-alist} has a buffer-local value, and there
2877 is no bitmap defined for a logical indicator, or the bitmap is
2878 @code{t}, the corresponding value from the (non-local)
2879 @code{default-fringe-indicator-alist} is used.
2881 To completely hide a specific indicator, set the bitmap to @code{nil}.
2884 @defvar default-fringe-indicator-alist
2885 The value of this variable is the default value for
2886 @code{fringe-indicator-alist} in buffers that do not override it.
2889 Standard fringe bitmaps for indicators:
2891 left-arrow right-arrow up-arrow down-arrow
2892 left-curly-arrow right-curly-arrow
2893 left-triangle right-triangle
2894 top-left-angle top-right-angle
2895 bottom-left-angle bottom-right-angle
2896 left-bracket right-bracket
2897 filled-rectangle hollow-rectangle
2898 filled-square hollow-square
2899 vertical-bar horizontal-bar
2900 empty-line question-mark
2903 @node Fringe Cursors
2904 @subsection Fringe Cursors
2905 @cindex fringe cursors
2906 @cindex cursor, fringe
2908 When a line is exactly as wide as the window, Emacs displays the
2909 cursor in the right fringe instead of using two lines. Different
2910 bitmaps are used to represent the cursor in the fringe depending on
2911 the current buffer's cursor type.
2914 @item Logical cursor types:
2915 @code{box} , @code{hollow}, @code{bar},
2916 @code{hbar}, @code{hollow-small}.
2919 The @code{hollow-small} type is used instead of @code{hollow} when the
2920 normal @code{hollow-rectangle} bitmap is too tall to fit on a specific
2923 @defvar overflow-newline-into-fringe
2924 If this is non-@code{nil}, lines exactly as wide as the window (not
2925 counting the final newline character) are not continued. Instead,
2926 when point is at the end of the line, the cursor appears in the right
2930 @defvar fringe-cursor-alist
2931 This variable specifies the mapping from logical cursor type to the
2932 actual fringe bitmaps displayed in the right fringe. The value is an
2933 alist where each element @code{(@var{cursor} . @var{bitmap})} specifies
2934 the fringe bitmaps used to display a specific logical cursor type in
2935 the fringe. Here, @var{cursor} specifies the logical cursor type and
2936 @var{bitmap} is a symbol specifying the fringe bitmap to be displayed
2937 for that logical cursor type.
2939 When @code{fringe-cursor-alist} has a buffer-local value, and there is
2940 no bitmap defined for a cursor type, the corresponding value from the
2941 (non-local) @code{default-fringes-indicator-alist} is used.
2944 @defvar default-fringes-cursor-alist
2945 The value of this variable is the default value for
2946 @code{fringe-cursor-alist} in buffers that do not override it.
2949 Standard bitmaps for displaying the cursor in right fringe:
2951 filled-rectangle hollow-rectangle filled-square hollow-square
2952 vertical-bar horizontal-bar
2956 @node Fringe Bitmaps
2957 @subsection Fringe Bitmaps
2958 @cindex fringe bitmaps
2959 @cindex bitmaps, fringe
2961 The @dfn{fringe bitmaps} are the actual bitmaps which represent the
2962 logical fringe indicators for truncated or continued lines, buffer
2963 boundaries, overlay arrow, etc. Fringe bitmap symbols have their own
2964 name space. The fringe bitmaps are shared by all frames and windows.
2965 You can redefine the built-in fringe bitmaps, and you can define new
2968 The way to display a bitmap in the left or right fringes for a given
2969 line in a window is by specifying the @code{display} property for one
2970 of the characters that appears in it. Use a display specification of
2971 the form @code{(left-fringe @var{bitmap} [@var{face}])} or
2972 @code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display
2973 Property}). Here, @var{bitmap} is a symbol identifying the bitmap you
2974 want, and @var{face} (which is optional) is the name of the face whose
2975 colors should be used for displaying the bitmap, instead of the
2976 default @code{fringe} face. @var{face} is automatically merged with
2977 the @code{fringe} face, so normally @var{face} need only specify the
2978 foreground color for the bitmap.
2980 @defun fringe-bitmaps-at-pos &optional pos window
2981 This function returns the fringe bitmaps of the display line
2982 containing position @var{pos} in window @var{window}. The return
2983 value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left}
2984 is the symbol for the fringe bitmap in the left fringe (or @code{nil}
2985 if no bitmap), @var{right} is similar for the right fringe, and @var{ov}
2986 is non-@code{nil} if there is an overlay arrow in the left fringe.
2988 The value is @code{nil} if @var{pos} is not visible in @var{window}.
2989 If @var{window} is @code{nil}, that stands for the selected window.
2990 If @var{pos} is @code{nil}, that stands for the value of point in
2994 @node Customizing Bitmaps
2995 @subsection Customizing Fringe Bitmaps
2997 @defun define-fringe-bitmap bitmap bits &optional height width align
2998 This function defines the symbol @var{bitmap} as a new fringe bitmap,
2999 or replaces an existing bitmap with that name.
3001 The argument @var{bits} specifies the image to use. It should be
3002 either a string or a vector of integers, where each element (an
3003 integer) corresponds to one row of the bitmap. Each bit of an integer
3004 corresponds to one pixel of the bitmap, where the low bit corresponds
3005 to the rightmost pixel of the bitmap.
3007 The height is normally the length of @var{bits}. However, you
3008 can specify a different height with non-@code{nil} @var{height}. The width
3009 is normally 8, but you can specify a different width with non-@code{nil}
3010 @var{width}. The width must be an integer between 1 and 16.
3012 The argument @var{align} specifies the positioning of the bitmap
3013 relative to the range of rows where it is used; the default is to
3014 center the bitmap. The allowed values are @code{top}, @code{center},
3017 The @var{align} argument may also be a list @code{(@var{align}
3018 @var{periodic})} where @var{align} is interpreted as described above.
3019 If @var{periodic} is non-@code{nil}, it specifies that the rows in
3020 @code{bits} should be repeated enough times to reach the specified
3024 @defun destroy-fringe-bitmap bitmap
3025 This function destroy the fringe bitmap identified by @var{bitmap}.
3026 If @var{bitmap} identifies a standard fringe bitmap, it actually
3027 restores the standard definition of that bitmap, instead of
3028 eliminating it entirely.
3031 @defun set-fringe-bitmap-face bitmap &optional face
3032 This sets the face for the fringe bitmap @var{bitmap} to @var{face}.
3033 If @var{face} is @code{nil}, it selects the @code{fringe} face. The
3034 bitmap's face controls the color to draw it in.
3036 @var{face} is merged with the @code{fringe} face, so normally
3037 @var{face} should specify only the foreground color.
3041 @subsection The Overlay Arrow
3042 @cindex overlay arrow
3044 The @dfn{overlay arrow} is useful for directing the user's attention
3045 to a particular line in a buffer. For example, in the modes used for
3046 interface to debuggers, the overlay arrow indicates the line of code
3047 about to be executed. This feature has nothing to do with
3048 @dfn{overlays} (@pxref{Overlays}).
3050 @defvar overlay-arrow-string
3051 This variable holds the string to display to call attention to a
3052 particular line, or @code{nil} if the arrow feature is not in use.
3053 On a graphical display the contents of the string are ignored; instead a
3054 glyph is displayed in the fringe area to the left of the display area.
3057 @defvar overlay-arrow-position
3058 This variable holds a marker that indicates where to display the overlay
3059 arrow. It should point at the beginning of a line. On a non-graphical
3060 display the arrow text
3061 appears at the beginning of that line, overlaying any text that would
3062 otherwise appear. Since the arrow is usually short, and the line
3063 usually begins with indentation, normally nothing significant is
3066 The overlay-arrow string is displayed in any given buffer if the value
3067 of @code{overlay-arrow-position} in that buffer points into that
3068 buffer. Thus, it works to can display multiple overlay arrow strings
3069 by creating buffer-local bindings of @code{overlay-arrow-position}.
3070 However, it is usually cleaner to use
3071 @code{overlay-arrow-variable-list} to achieve this result.
3072 @c !!! overlay-arrow-position: but the overlay string may remain in the display
3073 @c of some other buffer until an update is required. This should be fixed
3077 You can do a similar job by creating an overlay with a
3078 @code{before-string} property. @xref{Overlay Properties}.
3080 You can define multiple overlay arrows via the variable
3081 @code{overlay-arrow-variable-list}.
3083 @defvar overlay-arrow-variable-list
3084 This variable's value is a list of variables, each of which specifies
3085 the position of an overlay arrow. The variable
3086 @code{overlay-arrow-position} has its normal meaning because it is on
3090 Each variable on this list can have properties
3091 @code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that
3092 specify an overlay arrow string (for text-only terminals) or fringe
3093 bitmap (for graphical terminals) to display at the corresponding
3094 overlay arrow position. If either property is not set, the default
3095 @code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator
3099 @section Scroll Bars
3101 Normally the frame parameter @code{vertical-scroll-bars} controls
3102 whether the windows in the frame have vertical scroll bars, and
3103 whether they are on the left or right. The frame parameter
3104 @code{scroll-bar-width} specifies how wide they are (@code{nil}
3105 meaning the default). @xref{Layout Parameters}.
3107 @defun frame-current-scroll-bars &optional frame
3108 This function reports the scroll bar type settings for frame
3109 @var{frame}. The value is a cons cell
3110 @code{(@var{vertical-type} .@: @var{horizontal-type})}, where
3111 @var{vertical-type} is either @code{left}, @code{right}, or @code{nil}
3112 (which means no scroll bar.) @var{horizontal-type} is meant to
3113 specify the horizontal scroll bar type, but since they are not
3114 implemented, it is always @code{nil}.
3117 @vindex vertical-scroll-bar
3118 You can enable or disable scroll bars for a particular buffer,
3119 by setting the variable @code{vertical-scroll-bar}. This variable
3120 automatically becomes buffer-local when set. The possible values are
3121 @code{left}, @code{right}, @code{t}, which means to use the
3122 frame's default, and @code{nil} for no scroll bar.
3124 You can also control this for individual windows. Call the function
3125 @code{set-window-scroll-bars} to specify what to do for a specific window:
3127 @defun set-window-scroll-bars window width &optional vertical-type horizontal-type
3128 This function sets the width and type of scroll bars for window
3131 @var{width} specifies the scroll bar width in pixels (@code{nil} means
3132 use the width specified for the frame). @var{vertical-type} specifies
3133 whether to have a vertical scroll bar and, if so, where. The possible
3134 values are @code{left}, @code{right} and @code{nil}, just like the
3135 values of the @code{vertical-scroll-bars} frame parameter.
3137 The argument @var{horizontal-type} is meant to specify whether and
3138 where to have horizontal scroll bars, but since they are not
3139 implemented, it has no effect. If @var{window} is @code{nil}, the
3140 selected window is used.
3143 @defun window-scroll-bars &optional window
3144 Report the width and type of scroll bars specified for @var{window}.
3145 If @var{window} is omitted or @code{nil}, the selected window is used.
3146 The value is a list of the form @code{(@var{width}
3147 @var{cols} @var{vertical-type} @var{horizontal-type})}. The value
3148 @var{width} is the value that was specified for the width (which may
3149 be @code{nil}); @var{cols} is the number of columns that the scroll
3150 bar actually occupies.
3152 @var{horizontal-type} is not actually meaningful.
3155 If you don't specify these values for a window with
3156 @code{set-window-scroll-bars}, the buffer-local variables
3157 @code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being
3158 displayed control the window's vertical scroll bars. The function
3159 @code{set-window-buffer} examines these variables. If you change them
3160 in a buffer that is already visible in a window, you can make the
3161 window take note of the new values by calling @code{set-window-buffer}
3162 specifying the same buffer that is already displayed.
3164 @defvar scroll-bar-mode
3165 This variable, always local in all buffers, controls whether and where
3166 to put scroll bars in windows displaying the buffer. The possible values
3167 are @code{nil} for no scroll bar, @code{left} to put a scroll bar on
3168 the left, and @code{right} to put a scroll bar on the right.
3171 @defun window-current-scroll-bars &optional window
3172 This function reports the scroll bar type for window @var{window}.
3173 If @var{window} is omitted or @code{nil}, the selected window is used.
3174 The value is a cons cell
3175 @code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike
3176 @code{window-scroll-bars}, this reports the scroll bar type actually
3177 used, once frame defaults and @code{scroll-bar-mode} are taken into
3181 @defvar scroll-bar-width
3182 This variable, always local in all buffers, specifies the width of the
3183 buffer's scroll bars, measured in pixels. A value of @code{nil} means
3184 to use the value specified by the frame.
3187 @node Display Property
3188 @section The @code{display} Property
3189 @cindex display specification
3190 @kindex display @r{(text property)}
3192 The @code{display} text property (or overlay property) is used to
3193 insert images into text, and also control other aspects of how text
3194 displays. The value of the @code{display} property should be a
3195 display specification, or a list or vector containing several display
3198 Some kinds of @code{display} properties specify something to display
3199 instead of the text that has the property. In this case, ``the text''
3200 means all the consecutive characters that have the same Lisp object as
3201 their @code{display} property; these characters are replaced as a
3202 single unit. By contrast, characters that have similar but distinct
3203 Lisp objects as their @code{display} properties are handled
3204 separately. Here's a function that illustrates this point:
3208 (goto-char (point-min))
3210 (let ((string (concat "A")))
3211 (put-text-property (point) (1+ (point)) 'display string)
3213 (put-text-property (point) (1+ (point)) 'display string)
3218 It gives each of the first ten characters in the buffer string
3219 @code{"A"} as the @code{display} property, but they don't all get the
3220 same string. The first two characters get the same string, so they
3221 together are replaced with one @samp{A}. The next two characters get
3222 a second string, so they together are replaced with one @samp{A}.
3223 Likewise for each following pair of characters. Thus, the ten
3224 characters appear as five A's. This function would have the same
3229 (goto-char (point-min))
3231 (let ((string (concat "A")))
3232 (put-text-property (point) (2+ (point)) 'display string)
3233 (put-text-property (point) (1+ (point)) 'display string)
3238 This illustrates that what matters is the property value for
3239 each character. If two consecutive characters have the same
3240 object as the @code{display} property value, it's irrelevant
3241 whether they got this property from a single call to
3242 @code{put-text-property} or from two different calls.
3244 The rest of this section describes several kinds of
3245 display specifications and what they mean.
3248 * Specified Space:: Displaying one space with a specified width.
3249 * Pixel Specification:: Specifying space width or height in pixels.
3250 * Other Display Specs:: Displaying an image; magnifying text; moving it
3251 up or down on the page; adjusting the width
3252 of spaces within text.
3253 * Display Margins:: Displaying text or images to the side of the main text.
3256 @node Specified Space
3257 @subsection Specified Spaces
3258 @cindex spaces, specified height or width
3259 @cindex specified spaces
3260 @cindex variable-width spaces
3262 To display a space of specified width and/or height, use a display
3263 specification of the form @code{(space . @var{props})}, where
3264 @var{props} is a property list (a list of alternating properties and
3265 values). You can put this property on one or more consecutive
3266 characters; a space of the specified height and width is displayed in
3267 place of @emph{all} of those characters. These are the properties you
3268 can use in @var{props} to specify the weight of the space:
3271 @item :width @var{width}
3272 If @var{width} is an integer or floating point number, it specifies
3273 that the space width should be @var{width} times the normal character
3274 width. @var{width} can also be a @dfn{pixel width} specification
3275 (@pxref{Pixel Specification}).
3277 @item :relative-width @var{factor}
3278 Specifies that the width of the stretch should be computed from the
3279 first character in the group of consecutive characters that have the
3280 same @code{display} property. The space width is the width of that
3281 character, multiplied by @var{factor}.
3283 @item :align-to @var{hpos}
3284 Specifies that the space should be wide enough to reach @var{hpos}.
3285 If @var{hpos} is a number, it is measured in units of the normal
3286 character width. @var{hpos} can also be a @dfn{pixel width}
3287 specification (@pxref{Pixel Specification}).
3290 You should use one and only one of the above properties. You can
3291 also specify the height of the space, with these properties:
3294 @item :height @var{height}
3295 Specifies the height of the space.
3296 If @var{height} is an integer or floating point number, it specifies
3297 that the space height should be @var{height} times the normal character
3298 height. The @var{height} may also be a @dfn{pixel height} specification
3299 (@pxref{Pixel Specification}).
3301 @item :relative-height @var{factor}
3302 Specifies the height of the space, multiplying the ordinary height
3303 of the text having this display specification by @var{factor}.
3305 @item :ascent @var{ascent}
3306 If the value of @var{ascent} is a non-negative number no greater than
3307 100, it specifies that @var{ascent} percent of the height of the space
3308 should be considered as the ascent of the space---that is, the part
3309 above the baseline. The ascent may also be specified in pixel units
3310 with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}).
3314 Don't use both @code{:height} and @code{:relative-height} together.
3316 The @code{:width} and @code{:align-to} properties are supported on
3317 non-graphic terminals, but the other space properties in this section
3320 @node Pixel Specification
3321 @subsection Pixel Specification for Spaces
3322 @cindex spaces, pixel specification
3324 The value of the @code{:width}, @code{:align-to}, @code{:height},
3325 and @code{:ascent} properties can be a special kind of expression that
3326 is evaluated during redisplay. The result of the evaluation is used
3327 as an absolute number of pixels.
3329 The following expressions are supported:
3333 @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form}
3334 @var{num} ::= @var{integer} | @var{float} | @var{symbol}
3335 @var{unit} ::= in | mm | cm | width | height
3338 @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin
3340 @var{pos} ::= left | center | right
3341 @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...)
3346 The form @var{num} specifies a fraction of the default frame font
3347 height or width. The form @code{(@var{num})} specifies an absolute
3348 number of pixels. If @var{num} is a symbol, @var{symbol}, its
3349 buffer-local variable binding is used.
3351 The @code{in}, @code{mm}, and @code{cm} units specify the number of
3352 pixels per inch, millimeter, and centimeter, respectively. The
3353 @code{width} and @code{height} units correspond to the default width
3354 and height of the current face. An image specification @code{image}
3355 corresponds to the width or height of the image.
3357 The @code{left-fringe}, @code{right-fringe}, @code{left-margin},
3358 @code{right-margin}, @code{scroll-bar}, and @code{text} elements
3359 specify to the width of the corresponding area of the window.
3361 The @code{left}, @code{center}, and @code{right} positions can be
3362 used with @code{:align-to} to specify a position relative to the left
3363 edge, center, or right edge of the text area.
3365 Any of the above window elements (except @code{text}) can also be
3366 used with @code{:align-to} to specify that the position is relative to
3367 the left edge of the given area. Once the base offset for a relative
3368 position has been set (by the first occurrence of one of these
3369 symbols), further occurrences of these symbols are interpreted as the
3370 width of the specified area. For example, to align to the center of
3371 the left-margin, use
3374 :align-to (+ left-margin (0.5 . left-margin))
3377 If no specific base offset is set for alignment, it is always relative
3378 to the left edge of the text area. For example, @samp{:align-to 0} in a
3379 header-line aligns with the first text column in the text area.
3381 A value of the form @code{(@var{num} . @var{expr})} stands for the
3382 product of the values of @var{num} and @var{expr}. For example,
3383 @code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 .
3384 @var{image})} specifies half the width (or height) of the specified
3387 The form @code{(+ @var{expr} ...)} adds up the value of the
3388 expressions. The form @code{(- @var{expr} ...)} negates or subtracts
3389 the value of the expressions.
3391 @node Other Display Specs
3392 @subsection Other Display Specifications
3394 Here are the other sorts of display specifications that you can use
3395 in the @code{display} text property.
3399 Display @var{string} instead of the text that has this property.
3401 Recursive display specifications are not supported---@var{string}'s
3402 @code{display} properties, if any, are not used.
3404 @item (image . @var{image-props})
3405 This kind of display specification is an image descriptor (@pxref{Images}).
3406 When used as a display specification, it means to display the image
3407 instead of the text that has the display specification.
3409 @item (slice @var{x} @var{y} @var{width} @var{height})
3410 This specification together with @code{image} specifies a @dfn{slice}
3411 (a partial area) of the image to display. The elements @var{y} and
3412 @var{x} specify the top left corner of the slice, within the image;
3413 @var{width} and @var{height} specify the width and height of the
3414 slice. Integer values are numbers of pixels. A floating point number
3415 in the range 0.0--1.0 stands for that fraction of the width or height
3416 of the entire image.
3418 @item ((margin nil) @var{string})
3419 A display specification of this form means to display @var{string}
3420 instead of the text that has the display specification, at the same
3421 position as that text. It is equivalent to using just @var{string},
3422 but it is done as a special case of marginal display (@pxref{Display
3425 @item (space-width @var{factor})
3426 This display specification affects all the space characters within the
3427 text that has the specification. It displays all of these spaces
3428 @var{factor} times as wide as normal. The element @var{factor} should
3429 be an integer or float. Characters other than spaces are not affected
3430 at all; in particular, this has no effect on tab characters.
3432 @item (height @var{height})
3433 This display specification makes the text taller or shorter.
3434 Here are the possibilities for @var{height}:
3437 @item @code{(+ @var{n})}
3438 This means to use a font that is @var{n} steps larger. A ``step'' is
3439 defined by the set of available fonts---specifically, those that match
3440 what was otherwise specified for this text, in all attributes except
3441 height. Each size for which a suitable font is available counts as
3442 another step. @var{n} should be an integer.
3444 @item @code{(- @var{n})}
3445 This means to use a font that is @var{n} steps smaller.
3447 @item a number, @var{factor}
3448 A number, @var{factor}, means to use a font that is @var{factor} times
3449 as tall as the default font.
3451 @item a symbol, @var{function}
3452 A symbol is a function to compute the height. It is called with the
3453 current height as argument, and should return the new height to use.
3455 @item anything else, @var{form}
3456 If the @var{height} value doesn't fit the previous possibilities, it is
3457 a form. Emacs evaluates it to get the new height, with the symbol
3458 @code{height} bound to the current specified font height.
3461 @item (raise @var{factor})
3462 This kind of display specification raises or lowers the text
3463 it applies to, relative to the baseline of the line.
3465 @var{factor} must be a number, which is interpreted as a multiple of the
3466 height of the affected text. If it is positive, that means to display
3467 the characters raised. If it is negative, that means to display them
3470 If the text also has a @code{height} display specification, that does
3471 not affect the amount of raising or lowering, which is based on the
3472 faces used for the text.
3475 @c We put all the `@code{(when ...)}' on one line to encourage
3476 @c makeinfo's end-of-sentence heuristics to DTRT. Previously, the dot
3477 @c was at eol; the info file ended up w/ two spaces rendered after it.
3478 You can make any display specification conditional. To do that,
3479 package it in another list of the form
3480 @code{(when @var{condition} . @var{spec})}.
3481 Then the specification @var{spec} applies only when
3482 @var{condition} evaluates to a non-@code{nil} value. During the
3483 evaluation, @code{object} is bound to the string or buffer having the
3484 conditional @code{display} property. @code{position} and
3485 @code{buffer-position} are bound to the position within @code{object}
3486 and the buffer position where the @code{display} property was found,
3487 respectively. Both positions can be different when @code{object} is a
3490 @node Display Margins
3491 @subsection Displaying in the Margins
3492 @cindex display margins
3493 @cindex margins, display
3495 A buffer can have blank areas called @dfn{display margins} on the left
3496 and on the right. Ordinary text never appears in these areas, but you
3497 can put things into the display margins using the @code{display}
3500 To put text in the left or right display margin of the window, use a
3501 display specification of the form @code{(margin right-margin)} or
3502 @code{(margin left-margin)} on it. To put an image in a display margin,
3503 use that display specification along with the display specification for
3504 the image. Unfortunately, there is currently no way to make
3505 text or images in the margin mouse-sensitive.
3507 If you put such a display specification directly on text in the
3508 buffer, the specified margin display appears @emph{instead of} that
3509 buffer text itself. To put something in the margin @emph{in
3510 association with} certain buffer text without preventing or altering
3511 the display of that text, put a @code{before-string} property on the
3512 text and put the display specification on the contents of the
3515 Before the display margins can display anything, you must give
3516 them a nonzero width. The usual way to do that is to set these
3519 @defvar left-margin-width
3520 This variable specifies the width of the left margin.
3521 It is buffer-local in all buffers.
3524 @defvar right-margin-width
3525 This variable specifies the width of the right margin.
3526 It is buffer-local in all buffers.
3529 Setting these variables does not immediately affect the window. These
3530 variables are checked when a new buffer is displayed in the window.
3531 Thus, you can make changes take effect by calling
3532 @code{set-window-buffer}.
3534 You can also set the margin widths immediately.
3536 @defun set-window-margins window left &optional right
3537 This function specifies the margin widths for window @var{window}.
3538 The argument @var{left} controls the left margin and
3539 @var{right} controls the right margin (default @code{0}).
3542 @defun window-margins &optional window
3543 This function returns the left and right margins of @var{window}
3544 as a cons cell of the form @code{(@var{left} . @var{right})}.
3545 If @var{window} is @code{nil}, the selected window is used.
3550 @cindex images in buffers
3552 To display an image in an Emacs buffer, you must first create an image
3553 descriptor, then use it as a display specifier in the @code{display}
3554 property of text that is displayed (@pxref{Display Property}).
3556 Emacs can display a number of different image formats; some of them
3557 are supported only if particular support libraries are installed on
3558 your machine. In some environments, Emacs can load image
3559 libraries on demand; if so, the variable @code{image-library-alist}
3560 can be used to modify the set of known names for these dynamic
3561 libraries (though it is not possible to add new image formats).
3563 The supported image formats include XBM, XPM (this requires the
3564 libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring
3565 @code{libungif} 4.1.0), Postscript, PBM, JPEG (requiring the
3566 @code{libjpeg} library version v6a), TIFF (requiring @code{libtiff}
3567 v3.4), and PNG (requiring @code{libpng} 1.0.2).
3569 You specify one of these formats with an image type symbol. The image
3570 type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
3571 @code{pbm}, @code{jpeg}, @code{tiff}, and @code{png}.
3574 This variable contains a list of those image type symbols that are
3575 potentially supported in the current configuration.
3576 @emph{Potentially} here means that Emacs knows about the image types,
3577 not necessarily that they can be loaded (they could depend on
3578 unavailable dynamic libraries, for example).
3580 To know which image types are really available, use
3581 @code{image-type-available-p}.
3584 @defvar image-library-alist
3585 This in an alist of image types vs external libraries needed to
3588 Each element is a list @code{(@var{image-type} @var{library}...)},
3589 where the car is a supported image format from @code{image-types}, and
3590 the rest are strings giving alternate filenames for the corresponding
3591 external libraries to load.
3593 Emacs tries to load the libraries in the order they appear on the
3594 list; if none is loaded, the running session of Emacs won't support
3595 the image type. @code{pbm} and @code{xbm} don't need to be listed;
3596 they're always supported.
3598 This variable is ignored if the image libraries are statically linked
3602 @defun image-type-available-p type
3603 @findex image-type-available-p
3605 This function returns non-@code{nil} if image type @var{type} is
3606 available, i.e., if images of this type can be loaded and displayed in
3607 Emacs. @var{type} should be one of the types contained in
3610 For image types whose support libraries are statically linked, this
3611 function always returns @code{t}; for other image types, it returns
3612 @code{t} if the dynamic library could be loaded, @code{nil} otherwise.
3616 * Image Descriptors:: How to specify an image for use in @code{:display}.
3617 * XBM Images:: Special features for XBM format.
3618 * XPM Images:: Special features for XPM format.
3619 * GIF Images:: Special features for GIF format.
3620 * Postscript Images:: Special features for Postscript format.
3621 * Other Image Types:: Various other formats are supported.
3622 * Defining Images:: Convenient ways to define an image for later use.
3623 * Showing Images:: Convenient ways to display an image once it is defined.
3624 * Image Cache:: Internal mechanisms of image display.
3627 @node Image Descriptors
3628 @subsection Image Descriptors
3629 @cindex image descriptor
3631 An image description is a list of the form @code{(image . @var{props})},
3632 where @var{props} is a property list containing alternating keyword
3633 symbols (symbols whose names start with a colon) and their values.
3634 You can use any Lisp object as a property, but the only properties
3635 that have any special meaning are certain symbols, all of them keywords.
3637 Every image descriptor must contain the property @code{:type
3638 @var{type}} to specify the format of the image. The value of @var{type}
3639 should be an image type symbol; for example, @code{xpm} for an image in
3642 Here is a list of other properties that are meaningful for all image
3646 @item :file @var{file}
3647 The @code{:file} property says to load the image from file
3648 @var{file}. If @var{file} is not an absolute file name, it is expanded
3649 in @code{data-directory}.
3651 @item :data @var{data}
3652 The @code{:data} property says the actual contents of the image.
3653 Each image must use either @code{:data} or @code{:file}, but not both.
3654 For most image types, the value of the @code{:data} property should be a
3655 string containing the image data; we recommend using a unibyte string.
3657 Before using @code{:data}, look for further information in the section
3658 below describing the specific image format. For some image types,
3659 @code{:data} may not be supported; for some, it allows other data types;
3660 for some, @code{:data} alone is not enough, so you need to use other
3661 image properties along with @code{:data}.
3663 @item :margin @var{margin}
3664 The @code{:margin} property specifies how many pixels to add as an
3665 extra margin around the image. The value, @var{margin}, must be a
3666 non-negative number, or a pair @code{(@var{x} . @var{y})} of such
3667 numbers. If it is a pair, @var{x} specifies how many pixels to add
3668 horizontally, and @var{y} specifies how many pixels to add vertically.
3669 If @code{:margin} is not specified, the default is zero.
3671 @item :ascent @var{ascent}
3672 The @code{:ascent} property specifies the amount of the image's
3673 height to use for its ascent---that is, the part above the baseline.
3674 The value, @var{ascent}, must be a number in the range 0 to 100, or
3675 the symbol @code{center}.
3677 If @var{ascent} is a number, that percentage of the image's height is
3678 used for its ascent.
3680 If @var{ascent} is @code{center}, the image is vertically centered
3681 around a centerline which would be the vertical centerline of text drawn
3682 at the position of the image, in the manner specified by the text
3683 properties and overlays that apply to the image.
3685 If this property is omitted, it defaults to 50.
3687 @item :relief @var{relief}
3688 The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle
3689 around the image. The value, @var{relief}, specifies the width of the
3690 shadow lines, in pixels. If @var{relief} is negative, shadows are drawn
3691 so that the image appears as a pressed button; otherwise, it appears as
3692 an unpressed button.
3694 @item :conversion @var{algorithm}
3695 The @code{:conversion} property, if non-@code{nil}, specifies a
3696 conversion algorithm that should be applied to the image before it is
3697 displayed; the value, @var{algorithm}, specifies which algorithm.
3702 Specifies the Laplace edge detection algorithm, which blurs out small
3703 differences in color while highlighting larger differences. People
3704 sometimes consider this useful for displaying the image for a
3705 ``disabled'' button.
3707 @item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
3708 Specifies a general edge-detection algorithm. @var{matrix} must be
3709 either a nine-element list or a nine-element vector of numbers. A pixel
3710 at position @math{x/y} in the transformed image is computed from
3711 original pixels around that position. @var{matrix} specifies, for each
3712 pixel in the neighborhood of @math{x/y}, a factor with which that pixel
3713 will influence the transformed pixel; element @math{0} specifies the
3714 factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for
3715 the pixel at @math{x/y-1} etc., as shown below:
3718 $$\pmatrix{x-1/y-1 & x/y-1 & x+1/y-1 \cr
3719 x-1/y & x/y & x+1/y \cr
3720 x-1/y+1& x/y+1 & x+1/y+1 \cr}$$
3725 (x-1/y-1 x/y-1 x+1/y-1
3727 x-1/y+1 x/y+1 x+1/y+1)
3731 The resulting pixel is computed from the color intensity of the color
3732 resulting from summing up the RGB values of surrounding pixels,
3733 multiplied by the specified factors, and dividing that sum by the sum
3734 of the factors' absolute values.
3736 Laplace edge-detection currently uses a matrix of
3739 $$\pmatrix{1 & 0 & 0 \cr
3752 Emboss edge-detection uses a matrix of
3755 $$\pmatrix{ 2 & -1 & 0 \cr
3769 Specifies transforming the image so that it looks ``disabled''.
3772 @item :mask @var{mask}
3773 If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build
3774 a clipping mask for the image, so that the background of a frame is
3775 visible behind the image. If @var{bg} is not specified, or if @var{bg}
3776 is @code{t}, determine the background color of the image by looking at
3777 the four corners of the image, assuming the most frequently occurring
3778 color from the corners is the background color of the image. Otherwise,
3779 @var{bg} must be a list @code{(@var{red} @var{green} @var{blue})}
3780 specifying the color to assume for the background of the image.
3782 If @var{mask} is @code{nil}, remove a mask from the image, if it has
3783 one. Images in some formats include a mask which can be removed by
3784 specifying @code{:mask nil}.
3786 @item :pointer @var{shape}
3787 This specifies the pointer shape when the mouse pointer is over this
3788 image. @xref{Pointer Shape}, for available pointer shapes.
3790 @item :map @var{map}
3791 This associates an image map of @dfn{hot spots} with this image.
3793 An image map is an alist where each element has the format
3794 @code{(@var{area} @var{id} @var{plist})}. An @var{area} is specified
3795 as either a rectangle, a circle, or a polygon.
3797 A rectangle is a cons
3798 @code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))}
3799 which specifies the pixel coordinates of the upper left and bottom right
3800 corners of the rectangle area.
3803 @code{(circle . ((@var{x0} . @var{y0}) . @var{r}))}
3804 which specifies the center and the radius of the circle; @var{r} may
3805 be a float or integer.
3808 @code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])}
3809 where each pair in the vector describes one corner in the polygon.
3811 When the mouse pointer lies on a hot-spot area of an image, the
3812 @var{plist} of that hot-spot is consulted; if it contains a @code{help-echo}
3813 property, that defines a tool-tip for the hot-spot, and if it contains
3814 a @code{pointer} property, that defines the shape of the mouse cursor when
3815 it is on the hot-spot.
3816 @xref{Pointer Shape}, for available pointer shapes.
3818 When you click the mouse when the mouse pointer is over a hot-spot, an
3819 event is composed by combining the @var{id} of the hot-spot with the
3820 mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's
3821 @var{id} is @code{area4}.
3824 @defun image-mask-p spec &optional frame
3825 This function returns @code{t} if image @var{spec} has a mask bitmap.
3826 @var{frame} is the frame on which the image will be displayed.
3827 @var{frame} @code{nil} or omitted means to use the selected frame
3828 (@pxref{Input Focus}).
3832 @subsection XBM Images
3835 To use XBM format, specify @code{xbm} as the image type. This image
3836 format doesn't require an external library, so images of this type are
3839 Additional image properties supported for the @code{xbm} image type are:
3842 @item :foreground @var{foreground}
3843 The value, @var{foreground}, should be a string specifying the image
3844 foreground color, or @code{nil} for the default color. This color is
3845 used for each pixel in the XBM that is 1. The default is the frame's
3848 @item :background @var{background}
3849 The value, @var{background}, should be a string specifying the image
3850 background color, or @code{nil} for the default color. This color is
3851 used for each pixel in the XBM that is 0. The default is the frame's
3855 If you specify an XBM image using data within Emacs instead of an
3856 external file, use the following three properties:
3859 @item :data @var{data}
3860 The value, @var{data}, specifies the contents of the image.
3861 There are three formats you can use for @var{data}:
3865 A vector of strings or bool-vectors, each specifying one line of the
3866 image. Do specify @code{:height} and @code{:width}.
3869 A string containing the same byte sequence as an XBM file would contain.
3870 You must not specify @code{:height} and @code{:width} in this case,
3871 because omitting them is what indicates the data has the format of an
3872 XBM file. The file contents specify the height and width of the image.
3875 A string or a bool-vector containing the bits of the image (plus perhaps
3876 some extra bits at the end that will not be used). It should contain at
3877 least @var{width} * @code{height} bits. In this case, you must specify
3878 @code{:height} and @code{:width}, both to indicate that the string
3879 contains just the bits rather than a whole XBM file, and to specify the
3883 @item :width @var{width}
3884 The value, @var{width}, specifies the width of the image, in pixels.
3886 @item :height @var{height}
3887 The value, @var{height}, specifies the height of the image, in pixels.
3891 @subsection XPM Images
3894 To use XPM format, specify @code{xpm} as the image type. The
3895 additional image property @code{:color-symbols} is also meaningful with
3896 the @code{xpm} image type:
3899 @item :color-symbols @var{symbols}
3900 The value, @var{symbols}, should be an alist whose elements have the
3901 form @code{(@var{name} . @var{color})}. In each element, @var{name} is
3902 the name of a color as it appears in the image file, and @var{color}
3903 specifies the actual color to use for displaying that name.
3907 @subsection GIF Images
3910 For GIF images, specify image type @code{gif}.
3913 @item :index @var{index}
3914 You can use @code{:index} to specify one image from a GIF file that
3915 contains more than one image. This property specifies use of image
3916 number @var{index} from the file. If the GIF file doesn't contain an
3917 image with index @var{index}, the image displays as a hollow box.
3921 This could be used to implement limited support for animated GIFs.
3922 For example, the following function displays a multi-image GIF file
3923 at point-min in the current buffer, switching between sub-images
3926 (defun show-anim (file max)
3927 "Display multi-image GIF file FILE which contains MAX subimages."
3928 (display-anim (current-buffer) file 0 max t))
3930 (defun display-anim (buffer file idx max first-time)
3933 (let ((img (create-image file nil :image idx)))
3936 (goto-char (point-min))
3937 (unless first-time (delete-char 1))
3939 (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
3942 @node Postscript Images
3943 @subsection Postscript Images
3944 @cindex Postscript images
3946 To use Postscript for an image, specify image type @code{postscript}.
3947 This works only if you have Ghostscript installed. You must always use
3948 these three properties:
3951 @item :pt-width @var{width}
3952 The value, @var{width}, specifies the width of the image measured in
3953 points (1/72 inch). @var{width} must be an integer.
3955 @item :pt-height @var{height}
3956 The value, @var{height}, specifies the height of the image in points
3957 (1/72 inch). @var{height} must be an integer.
3959 @item :bounding-box @var{box}
3960 The value, @var{box}, must be a list or vector of four integers, which
3961 specifying the bounding box of the Postscript image, analogous to the
3962 @samp{BoundingBox} comment found in Postscript files.
3965 %%BoundingBox: 22 171 567 738
3969 Displaying Postscript images from Lisp data is not currently
3970 implemented, but it may be implemented by the time you read this.
3971 See the @file{etc/NEWS} file to make sure.
3973 @node Other Image Types
3974 @subsection Other Image Types
3977 For PBM images, specify image type @code{pbm}. Color, gray-scale and
3978 monochromatic images are supported. For mono PBM images, two additional
3979 image properties are supported.
3982 @item :foreground @var{foreground}
3983 The value, @var{foreground}, should be a string specifying the image
3984 foreground color, or @code{nil} for the default color. This color is
3985 used for each pixel in the XBM that is 1. The default is the frame's
3988 @item :background @var{background}
3989 The value, @var{background}, should be a string specifying the image
3990 background color, or @code{nil} for the default color. This color is
3991 used for each pixel in the XBM that is 0. The default is the frame's
3995 For JPEG images, specify image type @code{jpeg}.
3997 For TIFF images, specify image type @code{tiff}.
3999 For PNG images, specify image type @code{png}.
4001 @node Defining Images
4002 @subsection Defining Images
4004 The functions @code{create-image}, @code{defimage} and
4005 @code{find-image} provide convenient ways to create image descriptors.
4007 @defun create-image file-or-data &optional type data-p &rest props
4008 This function creates and returns an image descriptor which uses the
4009 data in @var{file-or-data}. @var{file-or-data} can be a file name or
4010 a string containing the image data; @var{data-p} should be @code{nil}
4011 for the former case, non-@code{nil} for the latter case.
4013 The optional argument @var{type} is a symbol specifying the image type.
4014 If @var{type} is omitted or @code{nil}, @code{create-image} tries to
4015 determine the image type from the file's first few bytes, or else
4016 from the file's name.
4018 The remaining arguments, @var{props}, specify additional image
4019 properties---for example,
4022 (create-image "foo.xpm" 'xpm nil :heuristic-mask t)
4025 The function returns @code{nil} if images of this type are not
4026 supported. Otherwise it returns an image descriptor.
4029 @defmac defimage symbol specs &optional doc
4030 This macro defines @var{symbol} as an image name. The arguments
4031 @var{specs} is a list which specifies how to display the image.
4032 The third argument, @var{doc}, is an optional documentation string.
4034 Each argument in @var{specs} has the form of a property list, and each
4035 one should specify at least the @code{:type} property and either the
4036 @code{:file} or the @code{:data} property. The value of @code{:type}
4037 should be a symbol specifying the image type, the value of
4038 @code{:file} is the file to load the image from, and the value of
4039 @code{:data} is a string containing the actual image data. Here is an
4043 (defimage test-image
4044 ((:type xpm :file "~/test1.xpm")
4045 (:type xbm :file "~/test1.xbm")))
4048 @code{defimage} tests each argument, one by one, to see if it is
4049 usable---that is, if the type is supported and the file exists. The
4050 first usable argument is used to make an image descriptor which is
4051 stored in @var{symbol}.
4053 If none of the alternatives will work, then @var{symbol} is defined
4057 @defun find-image specs
4058 This function provides a convenient way to find an image satisfying one
4059 of a list of image specifications @var{specs}.
4061 Each specification in @var{specs} is a property list with contents
4062 depending on image type. All specifications must at least contain the
4063 properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
4064 or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
4065 the image type, e.g.@: @code{xbm}, @var{file} is the file to load the
4066 image from, and @var{data} is a string containing the actual image data.
4067 The first specification in the list whose @var{type} is supported, and
4068 @var{file} exists, is used to construct the image specification to be
4069 returned. If no specification is satisfied, @code{nil} is returned.
4071 The image is looked for in @code{image-load-path}.
4074 @defvar image-load-path
4075 This variable's value is a list of locations in which to search for
4076 image files. If an element is a string or a variable symbol whose
4077 value is a string, the string is taken to be the name of a directory
4078 to search. If an element is a variable symbol whose value is a list,
4079 that is taken to be a list of directory names to search.
4081 The default is to search in the @file{images} subdirectory of the
4082 directory specified by @code{data-directory}, then the directory
4083 specified by @code{data-directory}, and finally in the directories in
4084 @code{load-path}. Subdirectories are not automatically included in
4085 the search, so if you put an image file in a subdirectory, you have to
4086 supply the subdirectory name explicitly. For example, to find the
4087 image @file{images/foo/bar.xpm} within @code{data-directory}, you
4088 should specify the image as follows:
4091 (defimage foo-image '((:type xpm :file "foo/bar.xpm")))
4095 @defun image-load-path-for-library library image &optional path no-error
4096 This function returns a suitable search path for images used by the
4097 Lisp package @var{library}.
4099 The function searches for @var{image} first in @code{image-load-path}
4100 (excluding @file{@code{data-directory}/images}) and then in
4101 @code{load-path}, followed by a path suitable for @var{library}, which
4102 includes @file{../../etc/images} and @file{../etc/images} relative to
4103 the library file itself, and finally in
4104 @file{@code{data-directory}/images}.
4106 Then this function returns a list of directories which contains first
4107 the directory in which @var{image} was found, followed by the value of
4108 @code{load-path}. If @var{path} is given, it is used instead of
4111 If @var{no-error} is non-@code{nil} and a suitable path can't be
4112 found, don't signal an error. Instead, return a list of directories as
4113 before, except that @code{nil} appears in place of the image directory.
4115 Here is an example that uses a common idiom to provide compatibility
4116 with versions of Emacs that lack the variable @code{image-load-path}:
4119 (defvar image-load-path) ; shush compiler
4120 (let* ((load-path (image-load-path-for-library
4121 "mh-e" "mh-logo.xpm"))
4122 (image-load-path (cons (car load-path)
4123 (when (boundp 'image-load-path)
4125 (mh-tool-bar-folder-buttons-init))
4129 @node Showing Images
4130 @subsection Showing Images
4132 You can use an image descriptor by setting up the @code{display}
4133 property yourself, but it is easier to use the functions in this
4136 @defun insert-image image &optional string area slice
4137 This function inserts @var{image} in the current buffer at point. The
4138 value @var{image} should be an image descriptor; it could be a value
4139 returned by @code{create-image}, or the value of a symbol defined with
4140 @code{defimage}. The argument @var{string} specifies the text to put
4141 in the buffer to hold the image. If it is omitted or @code{nil},
4142 @code{insert-image} uses @code{" "} by default.
4144 The argument @var{area} specifies whether to put the image in a margin.
4145 If it is @code{left-margin}, the image appears in the left margin;
4146 @code{right-margin} specifies the right margin. If @var{area} is
4147 @code{nil} or omitted, the image is displayed at point within the
4150 The argument @var{slice} specifies a slice of the image to insert. If
4151 @var{slice} is @code{nil} or omitted the whole image is inserted.
4152 Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width}
4153 @var{height})} which specifies the @var{x} and @var{y} positions and
4154 @var{width} and @var{height} of the image area to insert. Integer
4155 values are in units of pixels. A floating point number in the range
4156 0.0--1.0 stands for that fraction of the width or height of the entire
4159 Internally, this function inserts @var{string} in the buffer, and gives
4160 it a @code{display} property which specifies @var{image}. @xref{Display
4164 @defun insert-sliced-image image &optional string area rows cols
4165 This function inserts @var{image} in the current buffer at point, like
4166 @code{insert-image}, but splits the image into @var{rows}x@var{cols}
4167 equally sized slices.
4170 @defun put-image image pos &optional string area
4171 This function puts image @var{image} in front of @var{pos} in the
4172 current buffer. The argument @var{pos} should be an integer or a
4173 marker. It specifies the buffer position where the image should appear.
4174 The argument @var{string} specifies the text that should hold the image
4175 as an alternative to the default.
4177 The argument @var{image} must be an image descriptor, perhaps returned
4178 by @code{create-image} or stored by @code{defimage}.
4180 The argument @var{area} specifies whether to put the image in a margin.
4181 If it is @code{left-margin}, the image appears in the left margin;
4182 @code{right-margin} specifies the right margin. If @var{area} is
4183 @code{nil} or omitted, the image is displayed at point within the
4186 Internally, this function creates an overlay, and gives it a
4187 @code{before-string} property containing text that has a @code{display}
4188 property whose value is the image. (Whew!)
4191 @defun remove-images start end &optional buffer
4192 This function removes images in @var{buffer} between positions
4193 @var{start} and @var{end}. If @var{buffer} is omitted or @code{nil},
4194 images are removed from the current buffer.
4196 This removes only images that were put into @var{buffer} the way
4197 @code{put-image} does it, not images that were inserted with
4198 @code{insert-image} or in other ways.
4201 @defun image-size spec &optional pixels frame
4202 This function returns the size of an image as a pair
4203 @w{@code{(@var{width} . @var{height})}}. @var{spec} is an image
4204 specification. @var{pixels} non-@code{nil} means return sizes
4205 measured in pixels, otherwise return sizes measured in canonical
4206 character units (fractions of the width/height of the frame's default
4207 font). @var{frame} is the frame on which the image will be displayed.
4208 @var{frame} null or omitted means use the selected frame (@pxref{Input
4212 @defvar max-image-size
4213 This variable is used to define the maximum size of image that Emacs
4214 will load. Emacs will refuse to load (and display) any image that is
4215 larger than this limit.
4217 If the value is an integer, it directly specifies the maximum
4218 image height and width, measured in pixels. If it is a floating
4219 point number, it specifies the maximum image height and width
4220 as a ratio to the frame height and width. If the value is
4221 non-numeric, there is no explicit limit on the size of images.
4223 The purpose of this variable is to prevent unreasonably large images
4224 from accidentally being loaded into Emacs. It only takes effect the
4225 first time an image is loaded. Once an image is placed in the image
4226 cache, it can always be displayed, even if the value of
4227 @var{max-image-size} is subsequently changed (@pxref{Image Cache}).
4231 @subsection Image Cache
4233 Emacs stores images in an image cache when it displays them, so it can
4234 display them again more efficiently. It removes an image from the cache
4235 when it hasn't been displayed for a specified period of time.
4237 When an image is looked up in the cache, its specification is compared
4238 with cached image specifications using @code{equal}. This means that
4239 all images with equal specifications share the same image in the cache.
4241 @defvar image-cache-eviction-delay
4242 This variable specifies the number of seconds an image can remain in the
4243 cache without being displayed. When an image is not displayed for this
4244 length of time, Emacs removes it from the image cache.
4246 If the value is @code{nil}, Emacs does not remove images from the cache
4247 except when you explicitly clear it. This mode can be useful for
4251 @defun clear-image-cache &optional frame
4252 This function clears the image cache. If @var{frame} is non-@code{nil},
4253 only the cache for that frame is cleared. Otherwise all frames' caches
4260 @cindex buttons in buffers
4261 @cindex clickable buttons in buffers
4263 The @emph{button} package defines functions for inserting and
4264 manipulating clickable (with the mouse, or via keyboard commands)
4265 buttons in Emacs buffers, such as might be used for help hyper-links,
4266 etc. Emacs uses buttons for the hyper-links in help text and the like.
4268 A button is essentially a set of properties attached (via text
4269 properties or overlays) to a region of text in an Emacs buffer. These
4270 properties are called @dfn{button properties}.
4272 One of these properties (@code{action}) is a function, which will
4273 be called when the user invokes it using the keyboard or the mouse.
4274 The invoked function may then examine the button and use its other
4275 properties as desired.
4277 In some ways the Emacs button package duplicates functionality offered
4278 by the widget package (@pxref{Top, , Introduction, widget, The Emacs
4279 Widget Library}), but the button package has the advantage that it is
4280 much faster, much smaller, and much simpler to use (for elisp
4281 programmers---for users, the result is about the same). The extra
4282 speed and space savings are useful mainly if you need to create many
4283 buttons in a buffer (for instance an @code{*Apropos*} buffer uses
4284 buttons to make entries clickable, and may contain many thousands of
4288 * Button Properties:: Button properties with special meanings.
4289 * Button Types:: Defining common properties for classes of buttons.
4290 * Making Buttons:: Adding buttons to Emacs buffers.
4291 * Manipulating Buttons:: Getting and setting properties of buttons.
4292 * Button Buffer Commands:: Buffer-wide commands and bindings for buttons.
4295 @node Button Properties
4296 @subsection Button Properties
4297 @cindex button properties
4299 Buttons have an associated list of properties defining their
4300 appearance and behavior, and other arbitrary properties may be used
4301 for application specific purposes. Some properties that have special
4302 meaning to the button package include:
4306 @kindex action @r{(button property)}
4307 The function to call when the user invokes the button, which is passed
4308 the single argument @var{button}. By default this is @code{ignore},
4312 @kindex mouse-action @r{(button property)}
4313 This is similar to @code{action}, and when present, will be used
4314 instead of @code{action} for button invocations resulting from
4315 mouse-clicks (instead of the user hitting @key{RET}). If not
4316 present, mouse-clicks use @code{action} instead.
4319 @kindex face @r{(button property)}
4320 This is an Emacs face controlling how buttons of this type are
4321 displayed; by default this is the @code{button} face.
4324 @kindex mouse-face @r{(button property)}
4325 This is an additional face which controls appearance during
4326 mouse-overs (merged with the usual button face); by default this is
4327 the usual Emacs @code{highlight} face.
4330 @kindex keymap @r{(button property)}
4331 The button's keymap, defining bindings active within the button
4332 region. By default this is the usual button region keymap, stored
4333 in the variable @code{button-map}, which defines @key{RET} and
4334 @key{mouse-2} to invoke the button.
4337 @kindex type @r{(button property)}
4338 The button-type of the button. When creating a button, this is
4339 usually specified using the @code{:type} keyword argument.
4340 @xref{Button Types}.
4343 @kindex help-index @r{(button property)}
4344 A string displayed by the Emacs tool-tip help system; by default,
4345 @code{"mouse-2, RET: Push this button"}.
4348 @kindex follow-link @r{(button property)}
4349 The follow-link property, defining how a @key{Mouse-1} click behaves
4350 on this button, @xref{Links and Mouse-1}.
4353 @kindex button @r{(button property)}
4354 All buttons have a non-@code{nil} @code{button} property, which may be useful
4355 in finding regions of text that comprise buttons (which is what the
4356 standard button functions do).
4359 There are other properties defined for the regions of text in a
4360 button, but these are not generally interesting for typical uses.
4363 @subsection Button Types
4364 @cindex button types
4366 Every button has a button @emph{type}, which defines default values
4367 for the button's properties. Button types are arranged in a
4368 hierarchy, with specialized types inheriting from more general types,
4369 so that it's easy to define special-purpose types of buttons for
4372 @defun define-button-type name &rest properties
4373 Define a `button type' called @var{name}. The remaining arguments
4374 form a sequence of @var{property value} pairs, specifying default
4375 property values for buttons with this type (a button's type may be set
4376 by giving it a @code{type} property when creating the button, using
4377 the @code{:type} keyword argument).
4379 In addition, the keyword argument @code{:supertype} may be used to
4380 specify a button-type from which @var{name} inherits its default
4381 property values. Note that this inheritance happens only when
4382 @var{name} is defined; subsequent changes to a supertype are not
4383 reflected in its subtypes.
4386 Using @code{define-button-type} to define default properties for
4387 buttons is not necessary---buttons without any specified type use the
4388 built-in button-type @code{button}---but it is encouraged, since
4389 doing so usually makes the resulting code clearer and more efficient.
4391 @node Making Buttons
4392 @subsection Making Buttons
4393 @cindex making buttons
4395 Buttons are associated with a region of text, using an overlay or
4396 text properties to hold button-specific information, all of which are
4397 initialized from the button's type (which defaults to the built-in
4398 button type @code{button}). Like all Emacs text, the appearance of
4399 the button is governed by the @code{face} property; by default (via
4400 the @code{face} property inherited from the @code{button} button-type)
4401 this is a simple underline, like a typical web-page link.
4403 For convenience, there are two sorts of button-creation functions,
4404 those that add button properties to an existing region of a buffer,
4405 called @code{make-...button}, and those that also insert the button
4406 text, called @code{insert-...button}.
4408 The button-creation functions all take the @code{&rest} argument
4409 @var{properties}, which should be a sequence of @var{property value}
4410 pairs, specifying properties to add to the button; see @ref{Button
4411 Properties}. In addition, the keyword argument @code{:type} may be
4412 used to specify a button-type from which to inherit other properties;
4413 see @ref{Button Types}. Any properties not explicitly specified
4414 during creation will be inherited from the button's type (if the type
4415 defines such a property).
4417 The following functions add a button using an overlay
4418 (@pxref{Overlays}) to hold the button properties:
4420 @defun make-button beg end &rest properties
4421 This makes a button from @var{beg} to @var{end} in the
4422 current buffer, and returns it.
4425 @defun insert-button label &rest properties
4426 This insert a button with the label @var{label} at point,
4430 The following functions are similar, but use Emacs text properties
4431 (@pxref{Text Properties}) to hold the button properties, making the
4432 button actually part of the text instead of being a property of the
4433 buffer. Buttons using text properties do not create markers into the
4434 buffer, which is important for speed when you use extremely large
4435 numbers of buttons. Both functions return the position of the start
4438 @defun make-text-button beg end &rest properties
4439 This makes a button from @var{beg} to @var{end} in the current buffer, using
4443 @defun insert-text-button label &rest properties
4444 This inserts a button with the label @var{label} at point, using text
4448 @node Manipulating Buttons
4449 @subsection Manipulating Buttons
4450 @cindex manipulating buttons
4452 These are functions for getting and setting properties of buttons.
4453 Often these are used by a button's invocation function to determine
4456 Where a @var{button} parameter is specified, it means an object
4457 referring to a specific button, either an overlay (for overlay
4458 buttons), or a buffer-position or marker (for text property buttons).
4459 Such an object is passed as the first argument to a button's
4460 invocation function when it is invoked.
4462 @defun button-start button
4463 Return the position at which @var{button} starts.
4466 @defun button-end button
4467 Return the position at which @var{button} ends.
4470 @defun button-get button prop
4471 Get the property of button @var{button} named @var{prop}.
4474 @defun button-put button prop val
4475 Set @var{button}'s @var{prop} property to @var{val}.
4478 @defun button-activate button &optional use-mouse-action
4479 Call @var{button}'s @code{action} property (i.e., invoke it). If
4480 @var{use-mouse-action} is non-@code{nil}, try to invoke the button's
4481 @code{mouse-action} property instead of @code{action}; if the button
4482 has no @code{mouse-action} property, use @code{action} as normal.
4485 @defun button-label button
4486 Return @var{button}'s text label.
4489 @defun button-type button
4490 Return @var{button}'s button-type.
4493 @defun button-has-type-p button type
4494 Return @code{t} if @var{button} has button-type @var{type}, or one of
4495 @var{type}'s subtypes.
4498 @defun button-at pos
4499 Return the button at position @var{pos} in the current buffer, or @code{nil}.
4502 @defun button-type-put type prop val
4503 Set the button-type @var{type}'s @var{prop} property to @var{val}.
4506 @defun button-type-get type prop
4507 Get the property of button-type @var{type} named @var{prop}.
4510 @defun button-type-subtype-p type supertype
4511 Return @code{t} if button-type @var{type} is a subtype of @var{supertype}.
4514 @node Button Buffer Commands
4515 @subsection Button Buffer Commands
4516 @cindex button buffer commands
4518 These are commands and functions for locating and operating on
4519 buttons in an Emacs buffer.
4521 @code{push-button} is the command that a user uses to actually `push'
4522 a button, and is bound by default in the button itself to @key{RET}
4523 and to @key{mouse-2} using a region-specific keymap. Commands
4524 that are useful outside the buttons itself, such as
4525 @code{forward-button} and @code{backward-button} are additionally
4526 available in the keymap stored in @code{button-buffer-map}; a mode
4527 which uses buttons may want to use @code{button-buffer-map} as a
4528 parent keymap for its keymap.
4530 If the button has a non-@code{nil} @code{follow-link} property, and
4531 @var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click
4532 will also activate the @code{push-button} command.
4533 @xref{Links and Mouse-1}.
4535 @deffn Command push-button &optional pos use-mouse-action
4536 Perform the action specified by a button at location @var{pos}.
4537 @var{pos} may be either a buffer position or a mouse-event. If
4538 @var{use-mouse-action} is non-@code{nil}, or @var{pos} is a
4539 mouse-event (@pxref{Mouse Events}), try to invoke the button's
4540 @code{mouse-action} property instead of @code{action}; if the button
4541 has no @code{mouse-action} property, use @code{action} as normal.
4542 @var{pos} defaults to point, except when @code{push-button} is invoked
4543 interactively as the result of a mouse-event, in which case, the mouse
4544 event's position is used. If there's no button at @var{pos}, do
4545 nothing and return @code{nil}, otherwise return @code{t}.
4548 @deffn Command forward-button n &optional wrap display-message
4549 Move to the @var{n}th next button, or @var{n}th previous button if
4550 @var{n} is negative. If @var{n} is zero, move to the start of any
4551 button at point. If @var{wrap} is non-@code{nil}, moving past either
4552 end of the buffer continues from the other end. If
4553 @var{display-message} is non-@code{nil}, the button's help-echo string
4554 is displayed. Any button with a non-@code{nil} @code{skip} property
4555 is skipped over. Returns the button found.
4558 @deffn Command backward-button n &optional wrap display-message
4559 Move to the @var{n}th previous button, or @var{n}th next button if
4560 @var{n} is negative. If @var{n} is zero, move to the start of any
4561 button at point. If @var{wrap} is non-@code{nil}, moving past either
4562 end of the buffer continues from the other end. If
4563 @var{display-message} is non-@code{nil}, the button's help-echo string
4564 is displayed. Any button with a non-@code{nil} @code{skip} property
4565 is skipped over. Returns the button found.
4568 @defun next-button pos &optional count-current
4569 Return the next button after position @var{pos} in the current buffer.
4570 If @var{count-current} is non-@code{nil}, count any button at
4571 @var{pos} in the search, instead of starting at the next button.
4574 @defun previous-button pos &optional count-current
4575 Return the @var{n}th button before position @var{pos} in the current
4576 buffer. If @var{count-current} is non-@code{nil}, count any button at
4577 @var{pos} in the search, instead of starting at the next button.
4580 @node Abstract Display
4581 @section Abstract Display
4583 @cindex display, abstract
4584 @cindex display, arbitrary objects
4585 @cindex model/view/controller
4586 @cindex view part, model/view/controller
4588 The Ewoc package constructs buffer text that represents a structure
4589 of Lisp objects, and updates the text to follow changes in that
4590 structure. This is like the ``view'' component in the
4591 ``model/view/controller'' design paradigm.
4593 An @dfn{ewoc} is a structure that organizes information required to
4594 construct buffer text that represents certain Lisp data. The buffer
4595 text of the ewoc has three parts, in order: first, fixed @dfn{header}
4596 text; next, textual descriptions of a series of data elements (Lisp
4597 objects that you specify); and last, fixed @dfn{footer} text.
4598 Specifically, an ewoc contains information on:
4602 The buffer which its text is generated in.
4605 The text's start position in the buffer.
4608 The header and footer strings.
4611 A doubly-linked chain of @dfn{nodes}, each of which contains:
4615 A @dfn{data element}, a single Lisp object.
4618 Links to the preceding and following nodes in the chain.
4622 A @dfn{pretty-printer} function which is responsible for
4623 inserting the textual representation of a data
4624 element value into the current buffer.
4627 Typically, you define an ewoc with @code{ewoc-create}, and then pass
4628 the resulting ewoc structure to other functions in the Ewoc package to
4629 build nodes within it, and display it in the buffer. Once it is
4630 displayed in the buffer, other functions determine the correspondance
4631 between buffer positions and nodes, move point from one node's textual
4632 representation to another, and so forth. @xref{Abstract Display
4635 A node @dfn{encapsulates} a data element much the way a variable
4636 holds a value. Normally, encapsulation occurs as a part of adding a
4637 node to the ewoc. You can retrieve the data element value and place a
4638 new value in its place, like so:
4641 (ewoc-data @var{node})
4644 (ewoc-set-data @var{node} @var{new-value})
4645 @result{} @var{new-value}
4649 You can also use, as the data element value, a Lisp object (list or
4650 vector) that is a container for the ``real'' value, or an index into
4651 some other structure. The example (@pxref{Abstract Display Example})
4652 uses the latter approach.
4654 When the data changes, you will want to update the text in the
4655 buffer. You can update all nodes by calling @code{ewoc-refresh}, or
4656 just specific nodes using @code{ewoc-invalidate}, or all nodes
4657 satisfying a predicate using @code{ewoc-map}. Alternatively, you can
4658 delete invalid nodes using @code{ewoc-delete} or @code{ewoc-filter},
4659 and add new nodes in their place. Deleting a node from an ewoc deletes
4660 its associated textual description from buffer, as well.
4663 * Abstract Display Functions::
4664 * Abstract Display Example::
4667 @node Abstract Display Functions
4668 @subsection Abstract Display Functions
4670 In this subsection, @var{ewoc} and @var{node} stand for the
4671 structures described above (@pxref{Abstract Display}), while
4672 @var{data} stands for an arbitrary Lisp object used as a data element.
4674 @defun ewoc-create pretty-printer &optional header footer nosep
4675 This constructs and returns a new ewoc, with no nodes (and thus no data
4676 elements). @var{pretty-printer} should be a function that takes one
4677 argument, a data element of the sort you plan to use in this ewoc, and
4678 inserts its textual description at point using @code{insert} (and never
4679 @code{insert-before-markers}, because that would interfere with the
4680 Ewoc package's internal mechanisms).
4682 Normally, a newline is automatically inserted after the header,
4683 the footer and every node's textual description. If @var{nosep}
4684 is non-@code{nil}, no newline is inserted. This may be useful for
4685 displaying an entire ewoc on a single line, for example, or for
4686 making nodes ``invisible'' by arranging for @var{pretty-printer}
4687 to do nothing for those nodes.
4689 An ewoc maintains its text in the buffer that is current when
4690 you create it, so switch to the intended buffer before calling
4694 @defun ewoc-buffer ewoc
4695 This returns the buffer where @var{ewoc} maintains its text.
4698 @defun ewoc-get-hf ewoc
4699 This returns a cons cell @code{(@var{header} . @var{footer})}
4700 made from @var{ewoc}'s header and footer.
4703 @defun ewoc-set-hf ewoc header footer
4704 This sets the header and footer of @var{ewoc} to the strings
4705 @var{header} and @var{footer}, respectively.
4708 @defun ewoc-enter-first ewoc data
4709 @defunx ewoc-enter-last ewoc data
4710 These add a new node encapsulating @var{data}, putting it, respectively,
4711 at the beginning or end of @var{ewoc}'s chain of nodes.
4714 @defun ewoc-enter-before ewoc node data
4715 @defunx ewoc-enter-after ewoc node data
4716 These add a new node encapsulating @var{data}, adding it to
4717 @var{ewoc} before or after @var{node}, respectively.
4720 @defun ewoc-prev ewoc node
4721 @defunx ewoc-next ewoc node
4722 These return, respectively, the previous node and the next node of @var{node}
4726 @defun ewoc-nth ewoc n
4727 This returns the node in @var{ewoc} found at zero-based index @var{n}.
4728 A negative @var{n} means count from the end. @code{ewoc-nth} returns
4729 @code{nil} if @var{n} is out of range.
4732 @defun ewoc-data node
4733 This extracts the data encapsulated by @var{node} and returns it.
4736 @defun ewoc-set-data node data
4737 This sets the data encapsulated by @var{node} to @var{data}.
4740 @defun ewoc-locate ewoc &optional pos guess
4741 This determines the node in @var{ewoc} which contains point (or
4742 @var{pos} if specified), and returns that node. If @var{ewoc} has no
4743 nodes, it returns @code{nil}. If @var{pos} is before the first node,
4744 it returns the first node; if @var{pos} is after the last node, it returns
4745 the last node. The optional third arg @var{guess}
4746 should be a node that is likely to be near @var{pos}; this doesn't
4747 alter the result, but makes the function run faster.
4750 @defun ewoc-location node
4751 This returns the start position of @var{node}.
4754 @defun ewoc-goto-prev ewoc arg
4755 @defunx ewoc-goto-next ewoc arg
4756 These move point to the previous or next, respectively, @var{arg}th node
4757 in @var{ewoc}. @code{ewoc-goto-prev} does not move if it is already at
4758 the first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next}
4759 moves past the last node, returning @code{nil}. Excepting this special
4760 case, these functions return the node moved to.
4763 @defun ewoc-goto-node ewoc node
4764 This moves point to the start of @var{node} in @var{ewoc}.
4767 @defun ewoc-refresh ewoc
4768 This function regenerates the text of @var{ewoc}. It works by
4769 deleting the text between the header and the footer, i.e., all the
4770 data elements' representations, and then calling the pretty-printer
4771 function for each node, one by one, in order.
4774 @defun ewoc-invalidate ewoc &rest nodes
4775 This is similar to @code{ewoc-refresh}, except that only @var{nodes} in
4776 @var{ewoc} are updated instead of the entire set.
4779 @defun ewoc-delete ewoc &rest nodes
4780 This deletes each node in @var{nodes} from @var{ewoc}.
4783 @defun ewoc-filter ewoc predicate &rest args
4784 This calls @var{predicate} for each data element in @var{ewoc} and
4785 deletes those nodes for which @var{predicate} returns @code{nil}.
4786 Any @var{args} are passed to @var{predicate}.
4789 @defun ewoc-collect ewoc predicate &rest args
4790 This calls @var{predicate} for each data element in @var{ewoc}
4791 and returns a list of those elements for which @var{predicate}
4792 returns non-@code{nil}. The elements in the list are ordered
4793 as in the buffer. Any @var{args} are passed to @var{predicate}.
4796 @defun ewoc-map map-function ewoc &rest args
4797 This calls @var{map-function} for each data element in @var{ewoc} and
4798 updates those nodes for which @var{map-function} returns non-@code{nil}.
4799 Any @var{args} are passed to @var{map-function}.
4802 @node Abstract Display Example
4803 @subsection Abstract Display Example
4805 Here is a simple example using functions of the ewoc package to
4806 implement a ``color components display'', an area in a buffer that
4807 represents a vector of three integers (itself representing a 24-bit RGB
4808 value) in various ways.
4811 (setq colorcomp-ewoc nil
4813 colorcomp-mode-map nil
4814 colorcomp-labels ["Red" "Green" "Blue"])
4816 (defun colorcomp-pp (data)
4818 (let ((comp (aref colorcomp-data data)))
4819 (insert (aref colorcomp-labels data) "\t: #x"
4820 (format "%02X" comp) " "
4821 (make-string (ash comp -2) ?#) "\n"))
4822 (let ((cstr (format "#%02X%02X%02X"
4823 (aref colorcomp-data 0)
4824 (aref colorcomp-data 1)
4825 (aref colorcomp-data 2)))
4826 (samp " (sample text) "))
4828 (propertize samp 'face `(foreground-color . ,cstr))
4829 (propertize samp 'face `(background-color . ,cstr))
4832 (defun colorcomp (color)
4833 "Allow fiddling with COLOR in a new buffer.
4834 The buffer is in Color Components mode."
4835 (interactive "sColor (name or #RGB or #RRGGBB): ")
4836 (when (string= "" color)
4837 (setq color "green"))
4838 (unless (color-values color)
4839 (error "No such color: %S" color))
4841 (generate-new-buffer (format "originally: %s" color)))
4842 (kill-all-local-variables)
4843 (setq major-mode 'colorcomp-mode
4844 mode-name "Color Components")
4845 (use-local-map colorcomp-mode-map)
4847 (buffer-disable-undo)
4848 (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8))
4849 (color-values color))))
4850 (ewoc (ewoc-create 'colorcomp-pp
4851 "\nColor Components\n\n"
4852 (substitute-command-keys
4853 "\n\\@{colorcomp-mode-map@}"))))
4854 (set (make-local-variable 'colorcomp-data) data)
4855 (set (make-local-variable 'colorcomp-ewoc) ewoc)
4856 (ewoc-enter-last ewoc 0)
4857 (ewoc-enter-last ewoc 1)
4858 (ewoc-enter-last ewoc 2)
4859 (ewoc-enter-last ewoc nil)))
4862 @cindex controller part, model/view/controller
4863 This example can be extended to be a ``color selection widget'' (in
4864 other words, the controller part of the ``model/view/controller''
4865 design paradigm) by defining commands to modify @code{colorcomp-data}
4866 and to ``finish'' the selection process, and a keymap to tie it all
4867 together conveniently.
4870 (defun colorcomp-mod (index limit delta)
4871 (let ((cur (aref colorcomp-data index)))
4872 (unless (= limit cur)
4873 (aset colorcomp-data index (+ cur delta)))
4876 (ewoc-nth colorcomp-ewoc index)
4877 (ewoc-nth colorcomp-ewoc -1))))
4879 (defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1))
4880 (defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1))
4881 (defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1))
4882 (defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1))
4883 (defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1))
4884 (defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1))
4886 (defun colorcomp-copy-as-kill-and-exit ()
4887 "Copy the color components into the kill ring and kill the buffer.
4888 The string is formatted #RRGGBB (hash followed by six hex digits)."
4890 (kill-new (format "#%02X%02X%02X"
4891 (aref colorcomp-data 0)
4892 (aref colorcomp-data 1)
4893 (aref colorcomp-data 2)))
4896 (setq colorcomp-mode-map
4897 (let ((m (make-sparse-keymap)))
4899 (define-key m "i" 'colorcomp-R-less)
4900 (define-key m "o" 'colorcomp-R-more)
4901 (define-key m "k" 'colorcomp-G-less)
4902 (define-key m "l" 'colorcomp-G-more)
4903 (define-key m "," 'colorcomp-B-less)
4904 (define-key m "." 'colorcomp-B-more)
4905 (define-key m " " 'colorcomp-copy-as-kill-and-exit)
4909 Note that we never modify the data in each node, which is fixed when the
4910 ewoc is created to be either @code{nil} or an index into the vector
4911 @code{colorcomp-data}, the actual color components.
4914 @section Blinking Parentheses
4915 @cindex parenthesis matching
4917 @cindex balancing parentheses
4918 @cindex close parenthesis
4920 This section describes the mechanism by which Emacs shows a matching
4921 open parenthesis when the user inserts a close parenthesis.
4923 @defvar blink-paren-function
4924 The value of this variable should be a function (of no arguments) to
4925 be called whenever a character with close parenthesis syntax is inserted.
4926 The value of @code{blink-paren-function} may be @code{nil}, in which
4927 case nothing is done.
4930 @defopt blink-matching-paren
4931 If this variable is @code{nil}, then @code{blink-matching-open} does
4935 @defopt blink-matching-paren-distance
4936 This variable specifies the maximum distance to scan for a matching
4937 parenthesis before giving up.
4940 @defopt blink-matching-delay
4941 This variable specifies the number of seconds for the cursor to remain
4942 at the matching parenthesis. A fraction of a second often gives
4943 good results, but the default is 1, which works on all systems.
4946 @deffn Command blink-matching-open
4947 This function is the default value of @code{blink-paren-function}. It
4948 assumes that point follows a character with close parenthesis syntax and
4949 moves the cursor momentarily to the matching opening character. If that
4950 character is not already on the screen, it displays the character's
4951 context in the echo area. To avoid long delays, this function does not
4952 search farther than @code{blink-matching-paren-distance} characters.
4954 Here is an example of calling this function explicitly.
4958 (defun interactive-blink-matching-open ()
4959 @c Do not break this line! -- rms.
4960 @c The first line of a doc string
4961 @c must stand alone.
4962 "Indicate momentarily the start of sexp before point."
4966 (let ((blink-matching-paren-distance
4968 (blink-matching-paren t))
4969 (blink-matching-open)))
4975 @section Usual Display Conventions
4977 The usual display conventions define how to display each character
4978 code. You can override these conventions by setting up a display table
4979 (@pxref{Display Tables}). Here are the usual display conventions:
4983 Character codes 32 through 126 map to glyph codes 32 through 126.
4984 Normally this means they display as themselves.
4987 Character code 9 is a horizontal tab. It displays as whitespace
4988 up to a position determined by @code{tab-width}.
4991 Character code 10 is a newline.
4994 All other codes in the range 0 through 31, and code 127, display in one
4995 of two ways according to the value of @code{ctl-arrow}. If it is
4996 non-@code{nil}, these codes map to sequences of two glyphs, where the
4997 first glyph is the @acronym{ASCII} code for @samp{^}. (A display table can
4998 specify a glyph to use instead of @samp{^}.) Otherwise, these codes map
4999 just like the codes in the range 128 to 255.
5001 On MS-DOS terminals, Emacs arranges by default for the character code
5002 127 to be mapped to the glyph code 127, which normally displays as an
5003 empty polygon. This glyph is used to display non-@acronym{ASCII} characters
5004 that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,,
5005 emacs, The GNU Emacs Manual}.
5008 Character codes 128 through 255 map to sequences of four glyphs, where
5009 the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are
5010 digit characters representing the character code in octal. (A display
5011 table can specify a glyph to use instead of @samp{\}.)
5014 Multibyte character codes above 256 are displayed as themselves, or as a
5015 question mark or empty box if the terminal cannot display that
5019 The usual display conventions apply even when there is a display
5020 table, for any character whose entry in the active display table is
5021 @code{nil}. Thus, when you set up a display table, you need only
5022 specify the characters for which you want special behavior.
5024 These display rules apply to carriage return (character code 13), when
5025 it appears in the buffer. But that character may not appear in the
5026 buffer where you expect it, if it was eliminated as part of end-of-line
5027 conversion (@pxref{Coding System Basics}).
5029 These variables affect the way certain characters are displayed on the
5030 screen. Since they change the number of columns the characters occupy,
5031 they also affect the indentation functions. These variables also affect
5032 how the mode line is displayed; if you want to force redisplay of the
5033 mode line using the new values, call the function
5034 @code{force-mode-line-update} (@pxref{Mode Line Format}).
5037 @cindex control characters in display
5038 This buffer-local variable controls how control characters are
5039 displayed. If it is non-@code{nil}, they are displayed as a caret
5040 followed by the character: @samp{^A}. If it is @code{nil}, they are
5041 displayed as a backslash followed by three octal digits: @samp{\001}.
5044 @c Following may have overfull hbox.
5045 @defvar default-ctl-arrow
5046 The value of this variable is the default value for @code{ctl-arrow} in
5047 buffers that do not override it. @xref{Default Value}.
5051 The value of this buffer-local variable is the spacing between tab
5052 stops used for displaying tab characters in Emacs buffers. The value
5053 is in units of columns, and the default is 8. Note that this feature
5054 is completely independent of the user-settable tab stops used by the
5055 command @code{tab-to-tab-stop}. @xref{Indent Tabs}.
5058 @node Display Tables
5059 @section Display Tables
5061 @cindex display table
5062 You can use the @dfn{display table} feature to control how all possible
5063 character codes display on the screen. This is useful for displaying
5064 European languages that have letters not in the @acronym{ASCII} character
5067 The display table maps each character code into a sequence of
5068 @dfn{glyphs}, each glyph being a graphic that takes up one character
5069 position on the screen. You can also define how to display each glyph
5070 on your terminal, using the @dfn{glyph table}.
5072 Display tables affect how the mode line is displayed; if you want to
5073 force redisplay of the mode line using a new display table, call
5074 @code{force-mode-line-update} (@pxref{Mode Line Format}).
5077 * Display Table Format:: What a display table consists of.
5078 * Active Display Table:: How Emacs selects a display table to use.
5079 * Glyphs:: How to define a glyph, and what glyphs mean.
5082 @node Display Table Format
5083 @subsection Display Table Format
5085 A display table is actually a char-table (@pxref{Char-Tables}) with
5086 @code{display-table} as its subtype.
5088 @defun make-display-table
5089 This creates and returns a display table. The table initially has
5090 @code{nil} in all elements.
5093 The ordinary elements of the display table are indexed by character
5094 codes; the element at index @var{c} says how to display the character
5095 code @var{c}. The value should be @code{nil} or a vector of glyph
5096 values (@pxref{Glyphs}). If an element is @code{nil}, it says to
5097 display that character according to the usual display conventions
5098 (@pxref{Usual Display}).
5100 If you use the display table to change the display of newline
5101 characters, the whole buffer will be displayed as one long ``line.''
5103 The display table also has six ``extra slots'' which serve special
5104 purposes. Here is a table of their meanings; @code{nil} in any slot
5105 means to use the default for that slot, as stated below.
5109 The glyph for the end of a truncated screen line (the default for this
5110 is @samp{$}). @xref{Glyphs}. On graphical terminals, Emacs uses
5111 arrows in the fringes to indicate truncation, so the display table has
5115 The glyph for the end of a continued line (the default is @samp{\}).
5116 On graphical terminals, Emacs uses curved arrows in the fringes to
5117 indicate continuation, so the display table has no effect.
5120 The glyph for indicating a character displayed as an octal character
5121 code (the default is @samp{\}).
5124 The glyph for indicating a control character (the default is @samp{^}).
5127 A vector of glyphs for indicating the presence of invisible lines (the
5128 default is @samp{...}). @xref{Selective Display}.
5131 The glyph used to draw the border between side-by-side windows (the
5132 default is @samp{|}). @xref{Splitting Windows}. This takes effect only
5133 when there are no scroll bars; if scroll bars are supported and in use,
5134 a scroll bar separates the two windows.
5137 For example, here is how to construct a display table that mimics the
5138 effect of setting @code{ctl-arrow} to a non-@code{nil} value:
5141 (setq disptab (make-display-table))
5144 (or (= i ?\t) (= i ?\n)
5145 (aset disptab i (vector ?^ (+ i 64))))
5147 (aset disptab 127 (vector ?^ ??)))
5150 @defun display-table-slot display-table slot
5151 This function returns the value of the extra slot @var{slot} of
5152 @var{display-table}. The argument @var{slot} may be a number from 0 to
5153 5 inclusive, or a slot name (symbol). Valid symbols are
5154 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
5155 @code{selective-display}, and @code{vertical-border}.
5158 @defun set-display-table-slot display-table slot value
5159 This function stores @var{value} in the extra slot @var{slot} of
5160 @var{display-table}. The argument @var{slot} may be a number from 0 to
5161 5 inclusive, or a slot name (symbol). Valid symbols are
5162 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
5163 @code{selective-display}, and @code{vertical-border}.
5166 @defun describe-display-table display-table
5167 This function displays a description of the display table
5168 @var{display-table} in a help buffer.
5171 @deffn Command describe-current-display-table
5172 This command displays a description of the current display table in a
5176 @node Active Display Table
5177 @subsection Active Display Table
5178 @cindex active display table
5180 Each window can specify a display table, and so can each buffer. When
5181 a buffer @var{b} is displayed in window @var{w}, display uses the
5182 display table for window @var{w} if it has one; otherwise, the display
5183 table for buffer @var{b} if it has one; otherwise, the standard display
5184 table if any. The display table chosen is called the @dfn{active}
5187 @defun window-display-table &optional window
5188 This function returns @var{window}'s display table, or @code{nil}
5189 if @var{window} does not have an assigned display table. The default
5190 for @var{window} is the selected window.
5193 @defun set-window-display-table window table
5194 This function sets the display table of @var{window} to @var{table}.
5195 The argument @var{table} should be either a display table or
5199 @defvar buffer-display-table
5200 This variable is automatically buffer-local in all buffers; its value in
5201 a particular buffer specifies the display table for that buffer. If it
5202 is @code{nil}, that means the buffer does not have an assigned display
5206 @defvar standard-display-table
5207 This variable's value is the default display table, used whenever a
5208 window has no display table and neither does the buffer displayed in
5209 that window. This variable is @code{nil} by default.
5212 If there is no display table to use for a particular window---that is,
5213 if the window specifies none, its buffer specifies none, and
5214 @code{standard-display-table} is @code{nil}---then Emacs uses the usual
5215 display conventions for all character codes in that window. @xref{Usual
5218 A number of functions for changing the standard display table
5219 are defined in the library @file{disp-table}.
5225 A @dfn{glyph} is a generalization of a character; it stands for an
5226 image that takes up a single character position on the screen. Glyphs
5227 are represented in Lisp as integers, just as characters are. Normally
5228 Emacs finds glyphs in the display table (@pxref{Display Tables}).
5230 A glyph can be @dfn{simple} or it can be defined by the @dfn{glyph
5231 table}. A simple glyph is just a way of specifying a character and a
5232 face to output it in. The glyph code for a simple glyph, mod 524288,
5233 is the character to output, and the glyph code divided by 524288
5234 specifies the face number (@pxref{Face Functions}) to use while
5235 outputting it. (524288 is
5244 On character terminals, you can set up a @dfn{glyph table} to define
5245 the meaning of glyph codes. The glyph codes is the value of the
5246 variable @code{glyph-table}.
5249 The value of this variable is the current glyph table. It should be a
5250 vector; the @var{g}th element defines glyph code @var{g}.
5252 If a glyph code is greater than or equal to the length of the glyph
5253 table, that code is automatically simple. If the value of
5254 @code{glyph-table} is @code{nil} instead of a vector, then all glyphs
5255 are simple. The glyph table is not used on graphical displays, only
5256 on character terminals. On graphical displays, all glyphs are simple.
5259 Here are the possible types of elements in the glyph table:
5263 Send the characters in @var{string} to the terminal to output
5264 this glyph. This alternative is available on character terminals,
5265 but not on graphical displays.
5268 Define this glyph code as an alias for glyph code @var{integer}. You
5269 can use an alias to specify a face code for the glyph and use a small
5273 This glyph is simple.
5276 @defun create-glyph string
5277 This function returns a newly-allocated glyph code which is set up to
5278 display by sending @var{string} to the terminal.
5286 This section describes how to make Emacs ring the bell (or blink the
5287 screen) to attract the user's attention. Be conservative about how
5288 often you do this; frequent bells can become irritating. Also be
5289 careful not to use just beeping when signaling an error is more
5290 appropriate. (@xref{Errors}.)
5292 @defun ding &optional do-not-terminate
5293 @cindex keyboard macro termination
5294 This function beeps, or flashes the screen (see @code{visible-bell} below).
5295 It also terminates any keyboard macro currently executing unless
5296 @var{do-not-terminate} is non-@code{nil}.
5299 @defun beep &optional do-not-terminate
5300 This is a synonym for @code{ding}.
5303 @defopt visible-bell
5304 This variable determines whether Emacs should flash the screen to
5305 represent a bell. Non-@code{nil} means yes, @code{nil} means no. This
5306 is effective on graphical displays, and on text-only terminals
5307 provided the terminal's Termcap entry defines the visible bell
5308 capability (@samp{vb}).
5311 @defvar ring-bell-function
5312 If this is non-@code{nil}, it specifies how Emacs should ``ring the
5313 bell.'' Its value should be a function of no arguments. If this is
5314 non-@code{nil}, it takes precedence over the @code{visible-bell}
5318 @node Window Systems
5319 @section Window Systems
5321 Emacs works with several window systems, most notably the X Window
5322 System. Both Emacs and X use the term ``window'', but use it
5323 differently. An Emacs frame is a single window as far as X is
5324 concerned; the individual Emacs windows are not known to X at all.
5326 @defvar window-system
5327 This variable tells Lisp programs what window system Emacs is running
5328 under. The possible values are
5332 @cindex X Window System
5333 Emacs is displaying using X.
5335 Emacs is displaying using MS-DOS.
5337 Emacs is displaying using Windows.
5339 Emacs is displaying using a Macintosh.
5341 Emacs is using a character-based terminal.
5345 @defvar window-setup-hook
5346 This variable is a normal hook which Emacs runs after handling the
5347 initialization files. Emacs runs this hook after it has completed
5348 loading your init file, the default initialization file (if
5349 any), and the terminal-specific Lisp code, and running the hook
5350 @code{term-setup-hook}.
5352 This hook is used for internal purposes: setting up communication with
5353 the window system, and creating the initial window. Users should not
5358 arch-tag: ffdf5714-7ecf-415b-9023-fbc6b409c2c6