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 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 * Pointer Shape:: Controlling the mouse pointer shape.
30 * Display Property:: Enabling special display features.
31 * Images:: Displaying images in Emacs buffers.
32 * Buttons:: Adding clickable buttons to Emacs buffers.
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 redisplay of some or all windows. If
63 @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 @tindex redisplay-dont-pause
98 @defvar redisplay-dont-pause
99 If this variable is non-@code{nil}, pending input does not
100 prevent or halt redisplay; redisplay occurs, and finishes,
101 regardless of whether input is available.
104 You can request a display update, but only if no input is pending,
105 with @code{(sit-for 0)}. To force a display update even when input is
109 (let ((redisplay-dont-pause t))
115 @cindex line wrapping
116 @cindex continuation lines
117 @cindex @samp{$} in display
118 @cindex @samp{\} in display
120 When a line of text extends beyond the right edge of a window, the
121 line can either be continued on the next screen line, or truncated to
122 one screen line. The additional screen lines used to display a long
123 text line are called @dfn{continuation} lines. Normally, a @samp{$} in
124 the rightmost column of the window indicates truncation; a @samp{\} on
125 the rightmost column indicates a line that ``wraps'' onto the next line,
126 which is also called @dfn{continuing} the line. (The display table can
127 specify alternative indicators; see @ref{Display Tables}.)
129 On a window system display, the @samp{$} and @samp{\} indicators are
130 replaced with arrow images displayed in the window fringes
133 Note that continuation is different from filling; continuation happens
134 on the screen only, not in the buffer contents, and it breaks a line
135 precisely at the right margin, not at a word boundary. @xref{Filling}.
137 @defopt truncate-lines
138 This buffer-local variable controls how Emacs displays lines that extend
139 beyond the right edge of the window. The default is @code{nil}, which
140 specifies continuation. If the value is non-@code{nil}, then these
143 If the variable @code{truncate-partial-width-windows} is non-@code{nil},
144 then truncation is always used for side-by-side windows (within one
145 frame) regardless of the value of @code{truncate-lines}.
148 @defopt default-truncate-lines
149 This variable is the default value for @code{truncate-lines}, for
150 buffers that do not have buffer-local values for it.
153 @defopt truncate-partial-width-windows
154 This variable controls display of lines that extend beyond the right
155 edge of the window, in side-by-side windows (@pxref{Splitting Windows}).
156 If it is non-@code{nil}, these lines are truncated; otherwise,
157 @code{truncate-lines} says what to do with them.
160 When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
161 a window, that forces truncation.
163 If your buffer contains @emph{very} long lines, and you use
164 continuation to display them, just thinking about them can make Emacs
165 redisplay slow. The column computation and indentation functions also
166 become slow. Then you might find it advisable to set
167 @code{cache-long-line-scans} to @code{t}.
169 @defvar cache-long-line-scans
170 If this variable is non-@code{nil}, various indentation and motion
171 functions, and Emacs redisplay, cache the results of scanning the
172 buffer, and consult the cache to avoid rescanning regions of the buffer
173 unless they are modified.
175 Turning on the cache slows down processing of short lines somewhat.
177 This variable is automatically buffer-local in every buffer.
181 @section The Echo Area
182 @cindex error display
185 The @dfn{echo area} is used for displaying error messages
186 (@pxref{Errors}), for messages made with the @code{message} primitive,
187 and for echoing keystrokes. It is not the same as the minibuffer,
188 despite the fact that the minibuffer appears (when active) in the same
189 place on the screen as the echo area. The @cite{GNU Emacs Manual}
190 specifies the rules for resolving conflicts between the echo area and
191 the minibuffer for use of that screen space (@pxref{Minibuffer,, The
192 Minibuffer, emacs, The GNU Emacs Manual}).
194 You can write output in the echo area by using the Lisp printing
195 functions with @code{t} as the stream (@pxref{Output Functions}), or
199 * Displaying Messages:: Explicitly displaying text in the echo area.
200 * Progress:: Informing user about progress of a long operation.
201 * Logging Messages:: Echo area messages are logged for the user.
202 * Echo Area Customization:: Controlling the echo area.
205 @node Displaying Messages
206 @subsection Displaying Messages in the Echo Area
208 This section describes the functions for explicitly producing echo
209 area messages. Many other Emacs features display messages there, too.
211 @defun message string &rest arguments
212 This function displays a message in the echo area. The
213 argument @var{string} is similar to a C language @code{printf} control
214 string. See @code{format} in @ref{Formatting Strings}, for the details
215 on the conversion specifications. @code{message} returns the
218 In batch mode, @code{message} prints the message text on the standard
219 error stream, followed by a newline.
221 If @var{string}, or strings among the @var{arguments}, have @code{face}
222 text properties, these affect the way the message is displayed.
225 If @var{string} is @code{nil}, @code{message} clears the echo area; if
226 the echo area has been expanded automatically, this brings it back to
227 its normal size. If the minibuffer is active, this brings the
228 minibuffer contents back onto the screen immediately.
232 (message "Minibuffer depth is %d."
234 @print{} Minibuffer depth is 0.
235 @result{} "Minibuffer depth is 0."
239 ---------- Echo Area ----------
240 Minibuffer depth is 0.
241 ---------- Echo Area ----------
245 To automatically display a message in the echo area or in a pop-buffer,
246 depending on its size, use @code{display-message-or-buffer} (see below).
249 @tindex with-temp-message
250 @defmac with-temp-message message &rest body
251 This construct displays a message in the echo area temporarily, during
252 the execution of @var{body}. It displays @var{message}, executes
253 @var{body}, then returns the value of the last body form while restoring
254 the previous echo area contents.
257 @defun message-or-box string &rest arguments
258 This function displays a message like @code{message}, but may display it
259 in a dialog box instead of the echo area. If this function is called in
260 a command that was invoked using the mouse---more precisely, if
261 @code{last-nonmenu-event} (@pxref{Command Loop Info}) is either
262 @code{nil} or a list---then it uses a dialog box or pop-up menu to
263 display the message. Otherwise, it uses the echo area. (This is the
264 same criterion that @code{y-or-n-p} uses to make a similar decision; see
265 @ref{Yes-or-No Queries}.)
267 You can force use of the mouse or of the echo area by binding
268 @code{last-nonmenu-event} to a suitable value around the call.
271 @defun message-box string &rest arguments
272 This function displays a message like @code{message}, but uses a dialog
273 box (or a pop-up menu) whenever that is possible. If it is impossible
274 to use a dialog box or pop-up menu, because the terminal does not
275 support them, then @code{message-box} uses the echo area, like
279 @defun display-message-or-buffer message &optional buffer-name not-this-window frame
280 @tindex display-message-or-buffer
281 This function displays the message @var{message}, which may be either a
282 string or a buffer. If it is shorter than the maximum height of the
283 echo area, as defined by @code{max-mini-window-height}, it is displayed
284 in the echo area, using @code{message}. Otherwise,
285 @code{display-buffer} is used to show it in a pop-up buffer.
287 Returns either the string shown in the echo area, or when a pop-up
288 buffer is used, the window used to display it.
290 If @var{message} is a string, then the optional argument
291 @var{buffer-name} is the name of the buffer used to display it when a
292 pop-up buffer is used, defaulting to @samp{*Message*}. In the case
293 where @var{message} is a string and displayed in the echo area, it is
294 not specified whether the contents are inserted into the buffer anyway.
296 The optional arguments @var{not-this-window} and @var{frame} are as for
297 @code{display-buffer}, and only used if a buffer is displayed.
300 @defun current-message
301 This function returns the message currently being displayed in the
302 echo area, or @code{nil} if there is none.
306 @subsection Reporting Operation Progress
307 @cindex progress reporting
309 When an operation can take a while to finish, you should inform the
310 user about the progress it makes. This way the user can estimate
311 remaining time and clearly see that Emacs is busy working, not hung.
313 Functions listed in this section provide simple and efficient way of
314 reporting operation progress. Here is a working example that does
318 (let ((progress-reporter
319 (make-progress-reporter "Collecting mana for Emacs..."
323 (progress-reporter-update progress-reporter k))
324 (progress-reporter-done progress-reporter))
327 @defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
328 This function creates and returns a @dfn{progress reporter}---an
329 object you will use as an argument for all other functions listed
330 here. The idea is to precompute as much data as possible to make
331 progress reporting very fast.
333 When this progress reporter is subsequently used, it will display
334 @var{message} in the echo area, followed by progress percentage.
335 @var{message} is treated as a simple string. If you need it to depend
336 on a filename, for instance, use @code{format} before calling this
339 @var{min-value} and @var{max-value} arguments stand for starting and
340 final states of your operation. For instance, if you scan a buffer,
341 they should be the results of @code{point-min} and @code{point-max}
342 correspondingly. It is required that @var{max-value} is greater than
343 @var{min-value}. If you create progress reporter when some part of
344 the operation has already been completed, then specify
345 @var{current-value} argument. But normally you should omit it or set
346 it to @code{nil}---it will default to @var{min-value} then.
348 Remaining arguments control the rate of echo area updates. Progress
349 reporter will wait for at least @var{min-change} more percents of the
350 operation to be completed before printing next message.
351 @var{min-time} specifies the minimum time in seconds to pass between
352 successive prints. It can be fractional. Depending on Emacs and
353 system capabilities, progress reporter may or may not respect this
354 last argument or do it with varying precision. Default value for
355 @var{min-change} is 1 (one percent), for @var{min-time}---0.2
358 This function calls @code{progress-reporter-update}, so the first
359 message is printed immediately.
362 @defun progress-reporter-update reporter value
363 This function does the main work of reporting progress of your
364 operation. It displays the message of @var{reporter}, followed by
365 progress percentage determined by @var{value}. If percentage is zero,
366 or close enough according to the @var{min-change} and @var{min-time}
367 arguments, then it is omitted from the output.
369 @var{reporter} must be the result of a call to
370 @code{make-progress-reporter}. @var{value} specifies the current
371 state of your operation and must be between @var{min-value} and
372 @var{max-value} (inclusive) as passed to
373 @code{make-progress-reporter}. For instance, if you scan a buffer,
374 then @var{value} should be the result of a call to @code{point}.
376 This function respects @var{min-change} and @var{min-time} as passed
377 to @code{make-progress-reporter} and so does not output new messages
378 on every invocation. It is thus very fast and normally you should not
379 try to reduce the number of calls to it: resulting overhead will most
380 likely negate your effort.
383 @defun progress-reporter-force-update reporter value &optional new-message
384 This function is similar to @code{progress-reporter-update} except
385 that it prints a message in the echo area unconditionally.
387 The first two arguments have the same meaning as for
388 @code{progress-reporter-update}. Optional @var{new-message} allows
389 you to change the message of the @var{reporter}. Since this functions
390 always updates the echo area, such a change will be immediately
391 presented to the user.
394 @defun progress-reporter-done reporter
395 This function should be called when the operation is finished. It
396 prints the message of @var{reporter} followed by word ``done'' in the
399 You should always call this function and not hope for
400 @code{progress-reporter-update} to print ``100%.'' Firstly, it may
401 never print it, there are many good reasons for this not to happen.
402 Secondly, ``done'' is more explicit.
405 @defmac dotimes-with-progress-reporter (var count [result]) message body...
406 This is a convenience macro that works the same way as @code{dotimes}
407 does, but also reports loop progress using the functions described
408 above. It allows you to save some typing.
410 You can rewrite the example in the beginning of this node using
414 (dotimes-with-progress-reporter
416 "Collecting some mana for Emacs..."
421 @node Logging Messages
422 @subsection Logging Messages in @samp{*Messages*}
423 @cindex logging echo-area messages
425 Almost all the messages displayed in the echo area are also recorded
426 in the @samp{*Messages*} buffer so that the user can refer back to
427 them. This includes all the messages that are output with
430 @defopt message-log-max
431 This variable specifies how many lines to keep in the @samp{*Messages*}
432 buffer. The value @code{t} means there is no limit on how many lines to
433 keep. The value @code{nil} disables message logging entirely. Here's
434 how to display a message and prevent it from being logged:
437 (let (message-log-max)
442 To make @samp{*Messages*} more convenient for the user, the logging
443 facility combines successive identical messages. It also combines
444 successive related messages for the sake of two cases: question
445 followed by answer, and a series of progress messages.
447 A ``question followed by an answer'' means two messages like the
448 ones produced by @code{y-or-n-p}: the first is @samp{@var{question}},
449 and the second is @samp{@var{question}...@var{answer}}. The first
450 message conveys no additional information beyond what's in the second,
451 so logging the second message discards the first from the log.
453 A ``series of progress messages'' means successive messages like
454 those produced by @code{make-progress-reporter}. They have the form
455 @samp{@var{base}...@var{how-far}}, where @var{base} is the same each
456 time, while @var{how-far} varies. Logging each message in the series
457 discards the previous one, provided they are consecutive.
459 The functions @code{make-progress-reporter} and @code{y-or-n-p}
460 don't have to do anything special to activate the message log
461 combination feature. It operates whenever two consecutive messages
462 are logged that share a common prefix ending in @samp{...}.
464 @node Echo Area Customization
465 @subsection Echo Area Customization
467 These variables control details of how the echo area works.
469 @defvar cursor-in-echo-area
470 This variable controls where the cursor appears when a message is
471 displayed in the echo area. If it is non-@code{nil}, then the cursor
472 appears at the end of the message. Otherwise, the cursor appears at
473 point---not in the echo area at all.
475 The value is normally @code{nil}; Lisp programs bind it to @code{t}
476 for brief periods of time.
479 @defvar echo-area-clear-hook
480 This normal hook is run whenever the echo area is cleared---either by
481 @code{(message nil)} or for any other reason.
484 @defvar echo-keystrokes
485 This variable determines how much time should elapse before command
486 characters echo. Its value must be an integer or floating point number,
488 number of seconds to wait before echoing. If the user types a prefix
489 key (such as @kbd{C-x}) and then delays this many seconds before
490 continuing, the prefix key is echoed in the echo area. (Once echoing
491 begins in a key sequence, all subsequent characters in the same key
492 sequence are echoed immediately.)
494 If the value is zero, then command input is not echoed.
497 @defvar message-truncate-lines
498 Normally, displaying a long message resizes the echo area to display
499 the entire message. But if the variable @code{message-truncate-lines}
500 is non-@code{nil}, the echo area does not resize, and the message is
501 truncated to fit it, as in Emacs 20 and before.
504 The variable @code{max-mini-window-height}, which specifies the
505 maximum height for resizing minibuffer windows, also applies to the
506 echo area (which is really a special use of the minibuffer window.
507 @xref{Minibuffer Misc}.
510 @section Reporting Warnings
513 @dfn{Warnings} are a facility for a program to inform the user of a
514 possible problem, but continue running.
517 * Warning Basics:: Warnings concepts and functions to report them.
518 * Warning Variables:: Variables programs bind to customize their warnings.
519 * Warning Options:: Variables users set to control display of warnings.
523 @subsection Warning Basics
524 @cindex severity level
526 Every warning has a textual message, which explains the problem for
527 the user, and a @dfn{severity level} which is a symbol. Here are the
528 possible severity levels, in order of decreasing severity, and their
533 A problem that will seriously impair Emacs operation soon
534 if you do not attend to it promptly.
536 A report of data or circumstances that are inherently wrong.
538 A report of data or circumstances that are not inherently wrong, but
539 raise suspicion of a possible problem.
541 A report of information that may be useful if you are debugging.
544 When your program encounters invalid input data, it can either
545 signal a Lisp error by calling @code{error} or @code{signal} or report
546 a warning with severity @code{:error}. Signaling a Lisp error is the
547 easiest thing to do, but it means the program cannot continue
548 processing. If you want to take the trouble to implement a way to
549 continue processing despite the bad data, then reporting a warning of
550 severity @code{:error} is the right way to inform the user of the
551 problem. For instance, the Emacs Lisp byte compiler can report an
552 error that way and continue compiling other functions. (If the
553 program signals a Lisp error and then handles it with
554 @code{condition-case}, the user won't see the error message; it could
555 show the message to the user by reporting it as a warning.)
558 Each warning has a @dfn{warning type} to classify it. The type is a
559 list of symbols. The first symbol should be the custom group that you
560 use for the program's user options. For example, byte compiler
561 warnings use the warning type @code{(bytecomp)}. You can also
562 subcategorize the warnings, if you wish, by using more symbols in the
565 @defun display-warning type message &optional level buffer-name
566 This function reports a warning, using @var{message} as the message
567 and @var{type} as the warning type. @var{level} should be the
568 severity level, with @code{:warning} being the default.
570 @var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
571 for logging the warning. By default, it is @samp{*Warnings*}.
574 @defun lwarn type level message &rest args
575 This function reports a warning using the value of @code{(format
576 @var{message} @var{args}...)} as the message. In other respects it is
577 equivalent to @code{display-warning}.
580 @defun warn message &rest args
581 This function reports a warning using the value of @code{(format
582 @var{message} @var{args}...)} as the message, @code{(emacs)} as the
583 type, and @code{:warning} as the severity level. It exists for
584 compatibility only; we recommend not using it, because you should
585 specify a specific warning type.
588 @node Warning Variables
589 @subsection Warning Variables
591 Programs can customize how their warnings appear by binding
592 the variables described in this section.
594 @defvar warning-levels
595 This list defines the meaning and severity order of the warning
596 severity levels. Each element defines one severity level,
597 and they are arranged in order of decreasing severity.
599 Each element has the form @code{(@var{level} @var{string}
600 @var{function})}, where @var{level} is the severity level it defines.
601 @var{string} specifies the textual description of this level.
602 @var{string} should use @samp{%s} to specify where to put the warning
603 type information, or it can omit the @samp{%s} so as not to include
606 The optional @var{function}, if non-@code{nil}, is a function to call
607 with no arguments, to get the user's attention.
609 Normally you should not change the value of this variable.
612 @defvar warning-prefix-function
613 If non-@code{nil}, the value is a function to generate prefix text for
614 warnings. Programs can bind the variable to a suitable function.
615 @code{display-warning} calls this function with the warnings buffer
616 current, and the function can insert text in it. That text becomes
617 the beginning of the warning message.
619 The function is called with two arguments, the severity level and its
620 entry in @code{warning-levels}. It should return a list to use as the
621 entry (this value need not be an actual member of
622 @code{warning-levels}). By constructing this value, the function can
623 change the severity of the warning, or specify different handling for
624 a given severity level.
626 If the variable's value is @code{nil} then there is no function
630 @defvar warning-series
631 Programs can bind this variable to @code{t} to say that the next
632 warning should begin a series. When several warnings form a series,
633 that means to leave point on the first warning of the series, rather
634 than keep moving it for each warning so that it appears on the last one.
635 The series ends when the local binding is unbound and
636 @code{warning-series} becomes @code{nil} again.
638 The value can also be a symbol with a function definition. That is
639 equivalent to @code{t}, except that the next warning will also call
640 the function with no arguments with the warnings buffer current. The
641 function can insert text which will serve as a header for the series
644 Once a series has begun, the value is a marker which points to the
645 buffer position in the warnings buffer of the start of the series.
647 The variable's normal value is @code{nil}, which means to handle
648 each warning separately.
651 @defvar warning-fill-prefix
652 When this variable is non-@code{nil}, it specifies a fill prefix to
653 use for filling each warning's text.
656 @defvar warning-type-format
657 This variable specifies the format for displaying the warning type
658 in the warning message. The result of formatting the type this way
659 gets included in the message under the control of the string in the
660 entry in @code{warning-levels}. The default value is @code{" (%s)"}.
661 If you bind it to @code{""} then the warning type won't appear at
665 @node Warning Options
666 @subsection Warning Options
668 These variables are used by users to control what happens
669 when a Lisp program reports a warning.
671 @defopt warning-minimum-level
672 This user option specifies the minimum severity level that should be
673 shown immediately to the user. The default is @code{:warning}, which
674 means to immediately display all warnings except @code{:debug}
678 @defopt warning-minimum-log-level
679 This user option specifies the minimum severity level that should be
680 logged in the warnings buffer. The default is @code{:warning}, which
681 means to log all warnings except @code{:debug} warnings.
684 @defopt warning-suppress-types
685 This list specifies which warning types should not be displayed
686 immediately for the user. Each element of the list should be a list
687 of symbols. If its elements match the first elements in a warning
688 type, then that warning is not displayed immediately.
691 @defopt warning-suppress-log-types
692 This list specifies which warning types should not be logged in the
693 warnings buffer. Each element of the list should be a list of
694 symbols. If it matches the first few elements in a warning type, then
695 that warning is not logged.
699 @section Invisible Text
701 @cindex invisible text
702 You can make characters @dfn{invisible}, so that they do not appear on
703 the screen, with the @code{invisible} property. This can be either a
704 text property (@pxref{Text Properties}) or a property of an overlay
705 (@pxref{Overlays}). Cursor motion also partly ignores these
706 characters; if the command loop finds point within them, it moves
707 point to the other side of them.
709 In the simplest case, any non-@code{nil} @code{invisible} property makes
710 a character invisible. This is the default case---if you don't alter
711 the default value of @code{buffer-invisibility-spec}, this is how the
712 @code{invisible} property works. You should normally use @code{t}
713 as the value of the @code{invisible} property if you don't plan
714 to set @code{buffer-invisibility-spec} yourself.
716 More generally, you can use the variable @code{buffer-invisibility-spec}
717 to control which values of the @code{invisible} property make text
718 invisible. This permits you to classify the text into different subsets
719 in advance, by giving them different @code{invisible} values, and
720 subsequently make various subsets visible or invisible by changing the
721 value of @code{buffer-invisibility-spec}.
723 Controlling visibility with @code{buffer-invisibility-spec} is
724 especially useful in a program to display the list of entries in a
725 database. It permits the implementation of convenient filtering
726 commands to view just a part of the entries in the database. Setting
727 this variable is very fast, much faster than scanning all the text in
728 the buffer looking for properties to change.
730 @defvar buffer-invisibility-spec
731 This variable specifies which kinds of @code{invisible} properties
732 actually make a character invisible. Setting this variable makes it
737 A character is invisible if its @code{invisible} property is
738 non-@code{nil}. This is the default.
741 Each element of the list specifies a criterion for invisibility; if a
742 character's @code{invisible} property fits any one of these criteria,
743 the character is invisible. The list can have two kinds of elements:
747 A character is invisible if its @code{invisible} property value
748 is @var{atom} or if it is a list with @var{atom} as a member.
750 @item (@var{atom} . t)
751 A character is invisible if its @code{invisible} property value
752 is @var{atom} or if it is a list with @var{atom} as a member.
753 Moreover, if this character is at the end of a line and is followed
754 by a visible newline, it displays an ellipsis.
759 Two functions are specifically provided for adding elements to
760 @code{buffer-invisibility-spec} and removing elements from it.
762 @defun add-to-invisibility-spec element
763 This function adds the element @var{element} to
764 @code{buffer-invisibility-spec}. If @code{buffer-invisibility-spec}
765 was @code{t}, it changes to a list, @code{(t)}, so that text whose
766 @code{invisible} property is @code{t} remains invisible.
769 @defun remove-from-invisibility-spec element
770 This removes the element @var{element} from
771 @code{buffer-invisibility-spec}. This does nothing if @var{element}
775 A convention for use of @code{buffer-invisibility-spec} is that a
776 major mode should use the mode's own name as an element of
777 @code{buffer-invisibility-spec} and as the value of the
778 @code{invisible} property:
781 ;; @r{If you want to display an ellipsis:}
782 (add-to-invisibility-spec '(my-symbol . t))
783 ;; @r{If you don't want ellipsis:}
784 (add-to-invisibility-spec 'my-symbol)
786 (overlay-put (make-overlay beginning end)
787 'invisible 'my-symbol)
789 ;; @r{When done with the overlays:}
790 (remove-from-invisibility-spec '(my-symbol . t))
791 ;; @r{Or respectively:}
792 (remove-from-invisibility-spec 'my-symbol)
795 @vindex line-move-ignore-invisible
796 Ordinarily, functions that operate on text or move point do not care
797 whether the text is invisible. The user-level line motion commands
798 explicitly ignore invisible newlines if
799 @code{line-move-ignore-invisible} is non-@code{nil} (the default), but
800 only because they are explicitly programmed to do so.
802 However, if a command ends with point inside or immediately after
803 invisible text, the main editing loop moves point further forward or
804 further backward (in the same direction that the command already moved
805 it) until that condition is no longer true. Thus, if the command
806 moved point back into an invisible range, Emacs moves point back to
807 the beginning of that range, following the previous visible character.
808 If the command moved point forward into an invisible range, Emacs
809 moves point forward past the first visible character that follows the
812 Incremental search can make invisible overlays visible temporarily
813 and/or permanently when a match includes invisible text. To enable
814 this, the overlay should have a non-@code{nil}
815 @code{isearch-open-invisible} property. The property value should be a
816 function to be called with the overlay as an argument. This function
817 should make the overlay visible permanently; it is used when the match
818 overlaps the overlay on exit from the search.
820 During the search, such overlays are made temporarily visible by
821 temporarily modifying their invisible and intangible properties. If you
822 want this to be done differently for a certain overlay, give it an
823 @code{isearch-open-invisible-temporary} property which is a function.
824 The function is called with two arguments: the first is the overlay, and
825 the second is @code{nil} to make the overlay visible, or @code{t} to
826 make it invisible again.
828 @node Selective Display
829 @section Selective Display
830 @cindex selective display
832 @dfn{Selective display} refers to a pair of related features for
833 hiding certain lines on the screen.
835 The first variant, explicit selective display, is designed for use
836 in a Lisp program: it controls which lines are hidden by altering the
837 text. This kind of hiding in some ways resembles the effect of the
838 @code{invisible} property (@pxref{Invisible Text}), but the two
839 features are different and do not work the same way.
841 In the second variant, the choice of lines to hide is made
842 automatically based on indentation. This variant is designed to be a
845 The way you control explicit selective display is by replacing a
846 newline (control-j) with a carriage return (control-m). The text that
847 was formerly a line following that newline is now hidden. Strictly
848 speaking, it is temporarily no longer a line at all, since only
849 newlines can separate lines; it is now part of the previous line.
851 Selective display does not directly affect editing commands. For
852 example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly
853 into hidden text. However, the replacement of newline characters with
854 carriage return characters affects some editing commands. For
855 example, @code{next-line} skips hidden lines, since it searches only
856 for newlines. Modes that use selective display can also define
857 commands that take account of the newlines, or that control which
858 parts of the text are hidden.
860 When you write a selectively displayed buffer into a file, all the
861 control-m's are output as newlines. This means that when you next read
862 in the file, it looks OK, with nothing hidden. The selective display
863 effect is seen only within Emacs.
865 @defvar selective-display
866 This buffer-local variable enables selective display. This means that
867 lines, or portions of lines, may be made hidden.
871 If the value of @code{selective-display} is @code{t}, then the character
872 control-m marks the start of hidden text; the control-m, and the rest
873 of the line following it, are not displayed. This is explicit selective
877 If the value of @code{selective-display} is a positive integer, then
878 lines that start with more than that many columns of indentation are not
882 When some portion of a buffer is hidden, the vertical movement
883 commands operate as if that portion did not exist, allowing a single
884 @code{next-line} command to skip any number of hidden lines.
885 However, character movement commands (such as @code{forward-char}) do
886 not skip the hidden portion, and it is possible (if tricky) to insert
887 or delete text in an hidden portion.
889 In the examples below, we show the @emph{display appearance} of the
890 buffer @code{foo}, which changes with the value of
891 @code{selective-display}. The @emph{contents} of the buffer do not
896 (setq selective-display nil)
899 ---------- Buffer: foo ----------
906 ---------- Buffer: foo ----------
910 (setq selective-display 2)
913 ---------- Buffer: foo ----------
918 ---------- Buffer: foo ----------
923 @defvar selective-display-ellipses
924 If this buffer-local variable is non-@code{nil}, then Emacs displays
925 @samp{@dots{}} at the end of a line that is followed by hidden text.
926 This example is a continuation of the previous one.
930 (setq selective-display-ellipses t)
933 ---------- Buffer: foo ----------
938 ---------- Buffer: foo ----------
942 You can use a display table to substitute other text for the ellipsis
943 (@samp{@dots{}}). @xref{Display Tables}.
946 @node Temporary Displays
947 @section Temporary Displays
949 Temporary displays are used by Lisp programs to put output into a
950 buffer and then present it to the user for perusal rather than for
951 editing. Many help commands use this feature.
953 @defspec with-output-to-temp-buffer buffer-name forms@dots{}
954 This function executes @var{forms} while arranging to insert any output
955 they print into the buffer named @var{buffer-name}, which is first
956 created if necessary, and put into Help mode. Finally, the buffer is
957 displayed in some window, but not selected.
959 If the @var{forms} do not change the major mode in the output buffer,
960 so that it is still Help mode at the end of their execution, then
961 @code{with-output-to-temp-buffer} makes this buffer read-only at the
962 end, and also scans it for function and variable names to make them
963 into clickable cross-references. @xref{Docstring hyperlinks, , Tips
964 for Documentation Strings}, in particular the item on hyperlinks in
965 documentation strings, for more details.
967 The string @var{buffer-name} specifies the temporary buffer, which
968 need not already exist. The argument must be a string, not a buffer.
969 The buffer is erased initially (with no questions asked), and it is
970 marked as unmodified after @code{with-output-to-temp-buffer} exits.
972 @code{with-output-to-temp-buffer} binds @code{standard-output} to the
973 temporary buffer, then it evaluates the forms in @var{forms}. Output
974 using the Lisp output functions within @var{forms} goes by default to
975 that buffer (but screen display and messages in the echo area, although
976 they are ``output'' in the general sense of the word, are not affected).
977 @xref{Output Functions}.
979 Several hooks are available for customizing the behavior
980 of this construct; they are listed below.
982 The value of the last form in @var{forms} is returned.
986 ---------- Buffer: foo ----------
987 This is the contents of foo.
988 ---------- Buffer: foo ----------
992 (with-output-to-temp-buffer "foo"
994 (print standard-output))
995 @result{} #<buffer foo>
997 ---------- Buffer: foo ----------
1002 ---------- Buffer: foo ----------
1007 @defvar temp-buffer-show-function
1008 If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
1009 calls it as a function to do the job of displaying a help buffer. The
1010 function gets one argument, which is the buffer it should display.
1012 It is a good idea for this function to run @code{temp-buffer-show-hook}
1013 just as @code{with-output-to-temp-buffer} normally would, inside of
1014 @code{save-selected-window} and with the chosen window and buffer
1018 @defvar temp-buffer-setup-hook
1019 @tindex temp-buffer-setup-hook
1020 This normal hook is run by @code{with-output-to-temp-buffer} before
1021 evaluating @var{body}. When the hook runs, the temporary buffer is
1022 current. This hook is normally set up with a function to put the
1023 buffer in Help mode.
1026 @defvar temp-buffer-show-hook
1027 This normal hook is run by @code{with-output-to-temp-buffer} after
1028 displaying the temporary buffer. When the hook runs, the temporary buffer
1029 is current, and the window it was displayed in is selected. This hook
1030 is normally set up with a function to make the buffer read only, and
1031 find function names and variable names in it, provided the major mode
1035 @defun momentary-string-display string position &optional char message
1036 This function momentarily displays @var{string} in the current buffer at
1037 @var{position}. It has no effect on the undo list or on the buffer's
1038 modification status.
1040 The momentary display remains until the next input event. If the next
1041 input event is @var{char}, @code{momentary-string-display} ignores it
1042 and returns. Otherwise, that event remains buffered for subsequent use
1043 as input. Thus, typing @var{char} will simply remove the string from
1044 the display, while typing (say) @kbd{C-f} will remove the string from
1045 the display and later (presumably) move point forward. The argument
1046 @var{char} is a space by default.
1048 The return value of @code{momentary-string-display} is not meaningful.
1050 If the string @var{string} does not contain control characters, you can
1051 do the same job in a more general way by creating (and then subsequently
1052 deleting) an overlay with a @code{before-string} property.
1053 @xref{Overlay Properties}.
1055 If @var{message} is non-@code{nil}, it is displayed in the echo area
1056 while @var{string} is displayed in the buffer. If it is @code{nil}, a
1057 default message says to type @var{char} to continue.
1059 In this example, point is initially located at the beginning of the
1064 ---------- Buffer: foo ----------
1065 This is the contents of foo.
1066 @point{}Second line.
1067 ---------- Buffer: foo ----------
1071 (momentary-string-display
1072 "**** Important Message! ****"
1074 "Type RET when done reading")
1079 ---------- Buffer: foo ----------
1080 This is the contents of foo.
1081 **** Important Message! ****Second line.
1082 ---------- Buffer: foo ----------
1084 ---------- Echo Area ----------
1085 Type RET when done reading
1086 ---------- Echo Area ----------
1095 You can use @dfn{overlays} to alter the appearance of a buffer's text on
1096 the screen, for the sake of presentation features. An overlay is an
1097 object that belongs to a particular buffer, and has a specified
1098 beginning and end. It also has properties that you can examine and set;
1099 these affect the display of the text within the overlay.
1101 An overlays uses markers to record its beginning and end; thus,
1102 editing the text of the buffer adjusts the beginning and end of each
1103 overlay so that it stays with the text. When you create the overlay,
1104 you can specify whether text inserted at the beginning should be
1105 inside the overlay or outside, and likewise for the end of the overlay.
1108 * Managing Overlays:: Creating and moving overlays.
1109 * Overlay Properties:: How to read and set properties.
1110 What properties do to the screen display.
1111 * Finding Overlays:: Searching for overlays.
1114 @node Managing Overlays
1115 @subsection Managing Overlays
1117 This section describes the functions to create, delete and move
1118 overlays, and to examine their contents. Overlay changes are not
1119 recorded in the buffer's undo list, since the overlays are not
1120 part of the buffer's contents.
1122 @defun overlayp object
1123 This function returns @code{t} if @var{object} is an overlay.
1126 @defun make-overlay start end &optional buffer front-advance rear-advance
1127 This function creates and returns an overlay that belongs to
1128 @var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
1129 and @var{end} must specify buffer positions; they may be integers or
1130 markers. If @var{buffer} is omitted, the overlay is created in the
1133 The arguments @var{front-advance} and @var{rear-advance} specify the
1134 marker insertion type for the start of the overlay and for the end of
1135 the overlay, respectively. @xref{Marker Insertion Types}. If they
1136 are both @code{nil}, the default, then the overlay extends to include
1137 any text inserted at the beginning, but not text inserted at the end.
1138 If @var{front-advance} is non-@code{nil}, text inserted at the
1139 beginning of the overlay is excluded from the overlay. If
1140 @var{rear-advance} is non-@code{nil}, text inserted at the end of the
1141 overlay is included in the overlay.
1144 @defun overlay-start overlay
1145 This function returns the position at which @var{overlay} starts,
1149 @defun overlay-end overlay
1150 This function returns the position at which @var{overlay} ends,
1154 @defun overlay-buffer overlay
1155 This function returns the buffer that @var{overlay} belongs to. It
1156 returns @code{nil} if @var{overlay} has been deleted.
1159 @defun delete-overlay overlay
1160 This function deletes @var{overlay}. The overlay continues to exist as
1161 a Lisp object, and its property list is unchanged, but it ceases to be
1162 attached to the buffer it belonged to, and ceases to have any effect on
1165 A deleted overlay is not permanently disconnected. You can give it a
1166 position in a buffer again by calling @code{move-overlay}.
1169 @defun move-overlay overlay start end &optional buffer
1170 This function moves @var{overlay} to @var{buffer}, and places its bounds
1171 at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
1172 must specify buffer positions; they may be integers or markers.
1174 If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
1175 was already associated with; if @var{overlay} was deleted, it goes into
1178 The return value is @var{overlay}.
1180 This is the only valid way to change the endpoints of an overlay. Do
1181 not try modifying the markers in the overlay by hand, as that fails to
1182 update other vital data structures and can cause some overlays to be
1186 @defun remove-overlays &optional start end name value
1187 This function removes all the overlays between @var{start} and
1188 @var{end} whose property @var{name} has the value @var{value}. It can
1189 move the endpoints of the overlays in the region, or split them.
1191 If @var{name} is omitted or @code{nil}, it means to delete all overlays in
1192 the specified region. If @var{start} and/or @var{end} are omitted or
1193 @code{nil}, that means the beginning and end of the buffer respectively.
1194 Therefore, @code{(remove-overlays)} removes all the overlays in the
1198 Here are some examples:
1201 ;; @r{Create an overlay.}
1202 (setq foo (make-overlay 1 10))
1203 @result{} #<overlay from 1 to 10 in display.texi>
1208 (overlay-buffer foo)
1209 @result{} #<buffer display.texi>
1210 ;; @r{Give it a property we can check later.}
1211 (overlay-put foo 'happy t)
1213 ;; @r{Verify the property is present.}
1214 (overlay-get foo 'happy)
1216 ;; @r{Move the overlay.}
1217 (move-overlay foo 5 20)
1218 @result{} #<overlay from 5 to 20 in display.texi>
1223 ;; @r{Delete the overlay.}
1224 (delete-overlay foo)
1226 ;; @r{Verify it is deleted.}
1228 @result{} #<overlay in no buffer>
1229 ;; @r{A deleted overlay has no position.}
1234 (overlay-buffer foo)
1236 ;; @r{Undelete the overlay.}
1237 (move-overlay foo 1 20)
1238 @result{} #<overlay from 1 to 20 in display.texi>
1239 ;; @r{Verify the results.}
1244 (overlay-buffer foo)
1245 @result{} #<buffer display.texi>
1246 ;; @r{Moving and deleting the overlay does not change its properties.}
1247 (overlay-get foo 'happy)
1251 @node Overlay Properties
1252 @subsection Overlay Properties
1254 Overlay properties are like text properties in that the properties that
1255 alter how a character is displayed can come from either source. But in
1256 most respects they are different. @xref{Text Properties}, for comparison.
1258 Text properties are considered a part of the text; overlays and
1259 their properties are specifically considered not to be part of the
1260 text. Thus, copying text between various buffers and strings
1261 preserves text properties, but does not try to preserve overlays.
1262 Changing a buffer's text properties marks the buffer as modified,
1263 while moving an overlay or changing its properties does not. Unlike
1264 text property changes, overlay property changes are not recorded in
1265 the buffer's undo list.
1267 These functions read and set the properties of an overlay:
1269 @defun overlay-get overlay prop
1270 This function returns the value of property @var{prop} recorded in
1271 @var{overlay}, if any. If @var{overlay} does not record any value for
1272 that property, but it does have a @code{category} property which is a
1273 symbol, that symbol's @var{prop} property is used. Otherwise, the value
1277 @defun overlay-put overlay prop value
1278 This function sets the value of property @var{prop} recorded in
1279 @var{overlay} to @var{value}. It returns @var{value}.
1282 @defun overlay-properties overlay
1283 This returns a copy of the property list of @var{overlay}.
1286 See also the function @code{get-char-property} which checks both
1287 overlay properties and text properties for a given character.
1288 @xref{Examining Properties}.
1290 Many overlay properties have special meanings; here is a table
1295 @kindex priority @r{(overlay property)}
1296 This property's value (which should be a nonnegative integer number)
1297 determines the priority of the overlay. The priority matters when two
1298 or more overlays cover the same character and both specify the same
1299 property; the one whose @code{priority} value is larger takes priority
1300 over the other. For the @code{face} property, the higher priority
1301 value does not completely replace the other; instead, its face
1302 attributes override the face attributes of the lower priority
1303 @code{face} property.
1305 Currently, all overlays take priority over text properties. Please
1306 avoid using negative priority values, as we have not yet decided just
1307 what they should mean.
1310 @kindex window @r{(overlay property)}
1311 If the @code{window} property is non-@code{nil}, then the overlay
1312 applies only on that window.
1315 @kindex category @r{(overlay property)}
1316 If an overlay has a @code{category} property, we call it the
1317 @dfn{category} of the overlay. It should be a symbol. The properties
1318 of the symbol serve as defaults for the properties of the overlay.
1321 @kindex face @r{(overlay property)}
1322 This property controls the way text is displayed---for example, which
1323 font and which colors. @xref{Faces}, for more information.
1325 In the simplest case, the value is a face name. It can also be a list;
1326 then each element can be any of these possibilities:
1330 A face name (a symbol or string).
1333 A property list of face attributes. This has the form (@var{keyword}
1334 @var{value} @dots{}), where each @var{keyword} is a face attribute
1335 name and @var{value} is a meaningful value for that attribute. With
1336 this feature, you do not need to create a face each time you want to
1337 specify a particular attribute for certain text. @xref{Face
1341 A cons cell of the form @code{(foreground-color . @var{color-name})} or
1342 @code{(background-color . @var{color-name})}. These elements specify
1343 just the foreground color or just the background color.
1345 @code{(foreground-color . @var{color-name})} has the same effect as
1346 @code{(:foreground @var{color-name})}; likewise for the background.
1350 @kindex mouse-face @r{(overlay property)}
1351 This property is used instead of @code{face} when the mouse is within
1352 the range of the overlay.
1355 @kindex display @r{(overlay property)}
1356 This property activates various features that change the
1357 way text is displayed. For example, it can make text appear taller
1358 or shorter, higher or lower, wider or narrower, or replaced with an image.
1359 @xref{Display Property}.
1362 @kindex help-echo @r{(overlay property)}
1363 If an overlay has a @code{help-echo} property, then when you move the
1364 mouse onto the text in the overlay, Emacs displays a help string in the
1365 echo area, or in the tooltip window. For details see @ref{Text
1368 @item modification-hooks
1369 @kindex modification-hooks @r{(overlay property)}
1370 This property's value is a list of functions to be called if any
1371 character within the overlay is changed or if text is inserted strictly
1374 The hook functions are called both before and after each change.
1375 If the functions save the information they receive, and compare notes
1376 between calls, they can determine exactly what change has been made
1379 When called before a change, each function receives four arguments: the
1380 overlay, @code{nil}, and the beginning and end of the text range to be
1383 When called after a change, each function receives five arguments: the
1384 overlay, @code{t}, the beginning and end of the text range just
1385 modified, and the length of the pre-change text replaced by that range.
1386 (For an insertion, the pre-change length is zero; for a deletion, that
1387 length is the number of characters deleted, and the post-change
1388 beginning and end are equal.)
1390 If these functions modify the buffer, they should bind
1391 @code{inhibit-modification-hooks} to @code{t} around doing so, to
1392 avoid confusing the internal mechanism that calls these hooks.
1394 @item insert-in-front-hooks
1395 @kindex insert-in-front-hooks @r{(overlay property)}
1396 This property's value is a list of functions to be called before and
1397 after inserting text right at the beginning of the overlay. The calling
1398 conventions are the same as for the @code{modification-hooks} functions.
1400 @item insert-behind-hooks
1401 @kindex insert-behind-hooks @r{(overlay property)}
1402 This property's value is a list of functions to be called before and
1403 after inserting text right at the end of the overlay. The calling
1404 conventions are the same as for the @code{modification-hooks} functions.
1407 @kindex invisible @r{(overlay property)}
1408 The @code{invisible} property can make the text in the overlay
1409 invisible, which means that it does not appear on the screen.
1410 @xref{Invisible Text}, for details.
1413 @kindex intangible @r{(overlay property)}
1414 The @code{intangible} property on an overlay works just like the
1415 @code{intangible} text property. @xref{Special Properties}, for details.
1417 @item isearch-open-invisible
1418 This property tells incremental search how to make an invisible overlay
1419 visible, permanently, if the final match overlaps it. @xref{Invisible
1422 @item isearch-open-invisible-temporary
1423 This property tells incremental search how to make an invisible overlay
1424 visible, temporarily, during the search. @xref{Invisible Text}.
1427 @kindex before-string @r{(overlay property)}
1428 This property's value is a string to add to the display at the beginning
1429 of the overlay. The string does not appear in the buffer in any
1430 sense---only on the screen.
1433 @kindex after-string @r{(overlay property)}
1434 This property's value is a string to add to the display at the end of
1435 the overlay. The string does not appear in the buffer in any
1436 sense---only on the screen.
1439 @kindex evaporate @r{(overlay property)}
1440 If this property is non-@code{nil}, the overlay is deleted automatically
1441 if it becomes empty (i.e., if its length becomes zero). If you give
1442 an empty overlay a non-@code{nil} @code{evaporate} property, that deletes
1446 @cindex keymap of character (and overlays)
1447 @kindex local-map @r{(overlay property)}
1448 If this property is non-@code{nil}, it specifies a keymap for a portion
1449 of the text. The property's value replaces the buffer's local map, when
1450 the character after point is within the overlay. @xref{Active Keymaps}.
1453 @kindex keymap @r{(overlay property)}
1454 The @code{keymap} property is similar to @code{local-map} but overrides the
1455 buffer's local map (and the map specified by the @code{local-map}
1456 property) rather than replacing it.
1459 @node Finding Overlays
1460 @subsection Searching for Overlays
1462 @defun overlays-at pos
1463 This function returns a list of all the overlays that cover the
1464 character at position @var{pos} in the current buffer. The list is in
1465 no particular order. An overlay contains position @var{pos} if it
1466 begins at or before @var{pos}, and ends after @var{pos}.
1468 To illustrate usage, here is a Lisp function that returns a list of the
1469 overlays that specify property @var{prop} for the character at point:
1472 (defun find-overlays-specifying (prop)
1473 (let ((overlays (overlays-at (point)))
1476 (let ((overlay (car overlays)))
1477 (if (overlay-get overlay prop)
1478 (setq found (cons overlay found))))
1479 (setq overlays (cdr overlays)))
1484 @defun overlays-in beg end
1485 This function returns a list of the overlays that overlap the region
1486 @var{beg} through @var{end}. ``Overlap'' means that at least one
1487 character is contained within the overlay and also contained within the
1488 specified region; however, empty overlays are included in the result if
1489 they are located at @var{beg}, or strictly between @var{beg} and @var{end}.
1492 @defun next-overlay-change pos
1493 This function returns the buffer position of the next beginning or end
1494 of an overlay, after @var{pos}. If there is none, it returns
1498 @defun previous-overlay-change pos
1499 This function returns the buffer position of the previous beginning or
1500 end of an overlay, before @var{pos}. If there is none, it returns
1504 Here's a function which uses @code{next-overlay-change} to search
1505 for the next character which gets a given property @code{prop} from
1506 either its overlays or its text properties (@pxref{Property Search}):
1509 (defun find-overlay-prop (prop)
1511 (while (and (not (eobp))
1512 (not (get-char-property (point) prop)))
1513 (goto-char (min (next-overlay-change (point))
1514 (next-single-property-change (point) prop))))
1518 Now you can search for a @code{happy} property like this:
1521 (find-overlay-prop 'happy)
1527 Since not all characters have the same width, these functions let you
1528 check the width of a character. @xref{Primitive Indent}, and
1529 @ref{Screen Lines}, for related functions.
1531 @defun char-width char
1532 This function returns the width in columns of the character @var{char},
1533 if it were displayed in the current buffer and the selected window.
1536 @defun string-width string
1537 This function returns the width in columns of the string @var{string},
1538 if it were displayed in the current buffer and the selected window.
1541 @defun truncate-string-to-width string width &optional start-column padding ellipsis
1542 This function returns the part of @var{string} that fits within
1543 @var{width} columns, as a new string.
1545 If @var{string} does not reach @var{width}, then the result ends where
1546 @var{string} ends. If one multi-column character in @var{string}
1547 extends across the column @var{width}, that character is not included in
1548 the result. Thus, the result can fall short of @var{width} but cannot
1551 The optional argument @var{start-column} specifies the starting column.
1552 If this is non-@code{nil}, then the first @var{start-column} columns of
1553 the string are omitted from the value. If one multi-column character in
1554 @var{string} extends across the column @var{start-column}, that
1555 character is not included.
1557 The optional argument @var{padding}, if non-@code{nil}, is a padding
1558 character added at the beginning and end of the result string, to extend
1559 it to exactly @var{width} columns. The padding character is used at the
1560 end of the result if it falls short of @var{width}. It is also used at
1561 the beginning of the result if one multi-column character in
1562 @var{string} extends across the column @var{start-column}.
1564 If @var{ellipsis} is non-@code{nil}, it should be a string which will
1565 replace the end of @var{str} (including any padding) if it extends
1566 beyond @var{end-column}, unless the display width of @var{str} is
1567 equal to or less than the display width of @var{ellipsis}. If
1568 @var{ellipsis} is non-@code{nil} and not a string, it stands for
1572 (truncate-string-to-width "\tab\t" 12 4)
1574 (truncate-string-to-width "\tab\t" 12 4 ?\s)
1580 @section Line Height
1583 The total height of each display line consists of the height of the
1584 contents of the line, and additional vertical line spacing below the
1587 The height of the line contents is normally determined from the
1588 maximum height of any character or image on that display line,
1589 including the final newline if there is one. (A line that is
1590 continued doesn't include a final newline.) In the most common case,
1591 the line height equals the height of the default frame font.
1593 There are several ways to explicitly control or change the line
1594 height, either by specifying an absolute height for the display line,
1595 or by adding additional vertical space below one or all lines.
1597 @kindex line-height @r{(text property)}
1598 A newline can have a @code{line-height} text or overlay property
1599 that controls the total height of the display line ending in that
1602 If the property value is a list @code{(@var{height} @var{total})},
1603 then @var{height} is used as the actual property value for the
1604 @code{line-height}, and @var{total} specifies the total displayed
1605 height of the line, so the line spacing added below the line equals
1606 the @var{total} height minus the actual line height. In this case,
1607 the other ways to specify the line spacing are ignored.
1609 If the property value is @code{t}, the displayed height of the
1610 line is exactly what its contents demand; no line-spacing is added.
1611 This case is useful for tiling small images or image slices without
1612 adding blank areas between the images.
1614 If the property value is not @code{t}, it is a height spec. A height
1615 spec stands for a numeric height value; this height spec specifies the
1616 actual line height, @var{line-height}. There are several ways to
1617 write a height spec; here's how each of them translates into a numeric
1622 If the height spec is a positive integer, the height value is that integer.
1624 If the height spec is a float, @var{float}, the numeric height value
1625 is @var{float} times the frame's default line height.
1626 @item (@var{face} . @var{ratio})
1627 If the height spec is a cons of the format shown, the numeric height
1628 is @var{ratio} times the height of face @var{face}. @var{ratio} can
1629 be any type of number, or @code{nil} which means a ratio of 1.
1630 If @var{face} is @code{t}, it refers to the current face.
1631 @item (nil . @var{ratio})
1632 If the height spec is a cons of the format shown, the numeric height
1633 is @var{ratio} times the height of the contents of the line.
1636 Thus, any valid non-@code{t} property value specifies a height in pixels,
1637 @var{line-height}, one way or another. If the line contents' height
1638 is less than @var{line-height}, Emacs adds extra vertical space above
1639 the line to achieve the total height @var{line-height}. Otherwise,
1640 @var{line-height} has no effect.
1642 If you don't specify the @code{line-height} property, the line's
1643 height consists of the contents' height plus the line spacing.
1644 There are several ways to specify the line spacing for different
1645 parts of Emacs text.
1647 @vindex default-line-spacing
1648 You can specify the line spacing for all lines in a frame with the
1649 @code{line-spacing} frame parameter (@pxref{Layout Parameters}).
1650 However, if the variable @code{default-line-spacing} is
1651 non-@code{nil}, it overrides the frame's @code{line-spacing}
1652 parameter. An integer value specifies the number of pixels put below
1653 lines on window systems. A floating point number specifies the
1654 spacing relative to the frame's default line height.
1656 @vindex line-spacing
1657 You can specify the line spacing for all lines in a buffer via the
1658 buffer-local @code{line-spacing} variable. An integer value specifies
1659 the number of pixels put below lines on window systems. A floating
1660 point number specifies the spacing relative to the default frame line
1661 height. This overrides line spacings specified for the frame.
1663 @kindex line-spacing @r{(text property)}
1664 Finally, a newline can have a @code{line-spacing} text or overlay
1665 property that controls the height of the display line ending with that
1666 newline. The property value overrides the default frame line spacing
1667 and the buffer local @code{line-spacing} variable.
1669 One way or another, these mechanisms specify a Lisp value for the
1670 spacing of each line. The value is a height spec, and it translates
1671 into a Lisp value as described above. However, in this case the
1672 numeric height value specifies the line spacing, rather than the line
1679 A @dfn{face} is a named collection of graphical attributes: font
1680 family, foreground color, background color, optional underlining, and
1681 many others. Faces are used in Emacs to control the style of display of
1682 particular parts of the text or the frame. @xref{Standard Faces,,,
1683 emacs, The GNU Emacs Manual}, for the list of faces Emacs normally
1687 Each face has its own @dfn{face number}, which distinguishes faces at
1688 low levels within Emacs. However, for most purposes, you refer to
1689 faces in Lisp programs by the symbols that name them.
1692 This function returns @code{t} if @var{object} is a face name string
1693 or symbol (or if it is a vector of the kind used internally to record
1694 face data). It returns @code{nil} otherwise.
1697 Each face name is meaningful for all frames, and by default it has the
1698 same meaning in all frames. But you can arrange to give a particular
1699 face name a special meaning in one frame if you wish.
1702 * Defining Faces:: How to define a face with @code{defface}.
1703 * Face Attributes:: What is in a face?
1704 * Attribute Functions:: Functions to examine and set face attributes.
1705 * Displaying Faces:: How Emacs combines the faces specified for a character.
1706 * Font Selection:: Finding the best available font for a face.
1707 * Face Functions:: How to define and examine faces.
1708 * Auto Faces:: Hook for automatic face assignment.
1709 * Font Lookup:: Looking up the names of available fonts
1710 and information about them.
1711 * Fontsets:: A fontset is a collection of fonts
1712 that handle a range of character sets.
1715 @node Defining Faces
1716 @subsection Defining Faces
1718 The way to define a new face is with @code{defface}. This creates a
1719 kind of customization item (@pxref{Customization}) which the user can
1720 customize using the Customization buffer (@pxref{Easy Customization,,,
1721 emacs, The GNU Emacs Manual}).
1723 @defmac defface face spec doc [keyword value]...
1724 This declares @var{face} as a customizable face that defaults
1725 according to @var{spec}. You should not quote the symbol @var{face},
1726 and it should not end in @samp{-face} (that would be redundant). The
1727 argument @var{doc} specifies the face documentation. The keywords you
1728 can use in @code{defface} are the same as in @code{defgroup} and
1729 @code{defcustom} (@pxref{Common Keywords}).
1731 When @code{defface} executes, it defines the face according to
1732 @var{spec}, then uses any customizations that were read from the
1733 init file (@pxref{Init File}) to override that specification.
1735 The purpose of @var{spec} is to specify how the face should appear on
1736 different kinds of terminals. It should be an alist whose elements
1737 have the form @code{(@var{display} @var{atts})}. Each element's
1738 @sc{car}, @var{display}, specifies a class of terminals. (The first
1739 element, if it s @sc{car} is @code{default}, is special---it specifies
1740 defaults for the remaining elements). The element's @sc{cadr},
1741 @var{atts}, is a list of face attributes and their values; it
1742 specifies what the face should look like on that kind of terminal.
1743 The possible attributes are defined in the value of
1744 @code{custom-face-attributes}.
1746 The @var{display} part of an element of @var{spec} determines which
1747 frames the element matches. If more than one element of @var{spec}
1748 matches a given frame, the first element that matches is the one used
1749 for that frame. There are three possibilities for @var{display}:
1752 @item @code{default}
1753 This element of @var{spec} doesn't match any frames; instead, it
1754 specifies defaults that apply to all frames. This kind of element, if
1755 used, must be the first element of @var{spec}. Each of the following
1756 elements can override any or all of these defaults.
1759 This element of @var{spec} matches all frames. Therefore, any
1760 subsequent elements of @var{spec} are never used. Normally
1761 @code{t} is used in the last (or only) element of @var{spec}.
1764 If @var{display} is a list, each element should have the form
1765 @code{(@var{characteristic} @var{value}@dots{})}. Here
1766 @var{characteristic} specifies a way of classifying frames, and the
1767 @var{value}s are possible classifications which @var{display} should
1768 apply to. Here are the possible values of @var{characteristic}:
1772 The kind of window system the frame uses---either @code{graphic} (any
1773 graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console),
1774 @code{w32} (for MS Windows 9X/NT), or @code{tty} (a non-graphics-capable
1778 What kinds of colors the frame supports---either @code{color},
1779 @code{grayscale}, or @code{mono}.
1782 The kind of background---either @code{light} or @code{dark}.
1785 An integer that represents the minimum number of colors the frame
1786 should support. This matches a frame if its
1787 @code{display-color-cells} value is at least the specified integer.
1790 Whether or not the frame can display the face attributes given in
1791 @var{value}@dots{} (@pxref{Face Attributes}). See the documentation
1792 for the function @code{display-supports-face-attributes-p} for more
1793 information on exactly how this testing is done. @xref{Display Face
1797 If an element of @var{display} specifies more than one @var{value} for a
1798 given @var{characteristic}, any of those values is acceptable. If
1799 @var{display} has more than one element, each element should specify a
1800 different @var{characteristic}; then @emph{each} characteristic of the
1801 frame must match one of the @var{value}s specified for it in
1806 Here's how the standard face @code{region} is defined:
1810 '((((class color) (min-colors 88) (background dark))
1811 :background "blue3")
1813 (((class color) (min-colors 88) (background light))
1814 :background "lightgoldenrod2")
1815 (((class color) (min-colors 16) (background dark))
1816 :background "blue3")
1817 (((class color) (min-colors 16) (background light))
1818 :background "lightgoldenrod2")
1819 (((class color) (min-colors 8))
1820 :background "blue" :foreground "white")
1821 (((type tty) (class mono))
1823 (t :background "gray"))
1825 "Basic face for highlighting the region."
1826 :group 'basic-faces)
1830 Internally, @code{defface} uses the symbol property
1831 @code{face-defface-spec} to record the face attributes specified in
1832 @code{defface}, @code{saved-face} for the attributes saved by the user
1833 with the customization buffer, @code{customized-face} for the
1834 attributes customized by the user for the current session, but not
1835 saved, and @code{face-documentation} for the documentation string.
1837 @defopt frame-background-mode
1838 This option, if non-@code{nil}, specifies the background type to use for
1839 interpreting face definitions. If it is @code{dark}, then Emacs treats
1840 all frames as if they had a dark background, regardless of their actual
1841 background colors. If it is @code{light}, then Emacs treats all frames
1842 as if they had a light background.
1845 @node Face Attributes
1846 @subsection Face Attributes
1847 @cindex face attributes
1849 The effect of using a face is determined by a fixed set of @dfn{face
1850 attributes}. This table lists all the face attributes, and what they
1851 mean. Note that in general, more than one face can be specified for a
1852 given piece of text; when that happens, the attributes of all the faces
1853 are merged to specify how to display the text. @xref{Displaying Faces}.
1855 Any attribute in a face can have the value @code{unspecified}. This
1856 means the face doesn't specify that attribute. In face merging, when
1857 the first face fails to specify a particular attribute, that means the
1858 next face gets a chance. However, the @code{default} face must
1859 specify all attributes.
1861 Some of these font attributes are meaningful only on certain kinds of
1862 displays---if your display cannot handle a certain attribute, the
1863 attribute is ignored. (The attributes @code{:family}, @code{:width},
1864 @code{:height}, @code{:weight}, and @code{:slant} correspond to parts of
1865 an X Logical Font Descriptor.)
1869 Font family name, or fontset name (@pxref{Fontsets}). If you specify a
1870 font family name, the wild-card characters @samp{*} and @samp{?} are
1874 Relative proportionate width, also known as the character set width or
1875 set width. This should be one of the symbols @code{ultra-condensed},
1876 @code{extra-condensed}, @code{condensed}, @code{semi-condensed},
1877 @code{normal}, @code{semi-expanded}, @code{expanded},
1878 @code{extra-expanded}, or @code{ultra-expanded}.
1881 Either the font height, an integer in units of 1/10 point, a floating
1882 point number specifying the amount by which to scale the height of any
1883 underlying face, or a function, which is called with the old height
1884 (from the underlying face), and should return the new height.
1887 Font weight---a symbol from this series (from most dense to most faint):
1888 @code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
1889 @code{normal}, @code{semi-light}, @code{light}, @code{extra-light},
1890 or @code{ultra-light}.
1892 On a text-only terminal, any weight greater than normal is displayed as
1893 extra bright, and any weight less than normal is displayed as
1894 half-bright (provided the terminal supports the feature).
1897 Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal},
1898 @code{reverse-italic}, or @code{reverse-oblique}.
1900 On a text-only terminal, slanted text is displayed as half-bright, if
1901 the terminal supports the feature.
1904 Foreground color, a string. The value can be a system-defined color
1905 name, or a hexadecimal color specification of the form
1906 @samp{#@var{rr}@var{gg}@var{bb}}. (@samp{#000000} is black,
1907 @samp{#ff0000} is red, @samp{#00ff00} is green, @samp{#0000ff} is
1908 blue, and @samp{#ffffff} is white.)
1911 Background color, a string, like the foreground color.
1913 @item :inverse-video
1914 Whether or not characters should be displayed in inverse video. The
1915 value should be @code{t} (yes) or @code{nil} (no).
1918 The background stipple, a bitmap.
1920 The value can be a string; that should be the name of a file containing
1921 external-format X bitmap data. The file is found in the directories
1922 listed in the variable @code{x-bitmap-file-path}.
1924 Alternatively, the value can specify the bitmap directly, with a list
1925 of the form @code{(@var{width} @var{height} @var{data})}. Here,
1926 @var{width} and @var{height} specify the size in pixels, and
1927 @var{data} is a string containing the raw bits of the bitmap, row by
1928 row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes
1929 in the string (which should be a unibyte string for best results).
1930 This means that each row always occupies at least one whole byte.
1932 If the value is @code{nil}, that means use no stipple pattern.
1934 Normally you do not need to set the stipple attribute, because it is
1935 used automatically to handle certain shades of gray.
1938 Whether or not characters should be underlined, and in what color. If
1939 the value is @code{t}, underlining uses the foreground color of the
1940 face. If the value is a string, underlining uses that color. The
1941 value @code{nil} means do not underline.
1944 Whether or not characters should be overlined, and in what color.
1945 The value is used like that of @code{:underline}.
1947 @item :strike-through
1948 Whether or not characters should be strike-through, and in what
1949 color. The value is used like that of @code{:underline}.
1952 The name of a face from which to inherit attributes, or a list of face
1953 names. Attributes from inherited faces are merged into the face like an
1954 underlying face would be, with higher priority than underlying faces.
1955 If a list of faces is used, attributes from faces earlier in the list
1956 override those from later faces.
1959 Whether or not a box should be drawn around characters, its color, the
1960 width of the box lines, and 3D appearance.
1963 Here are the possible values of the @code{:box} attribute, and what
1971 Draw a box with lines of width 1, in the foreground color.
1974 Draw a box with lines of width 1, in color @var{color}.
1976 @item @code{(:line-width @var{width} :color @var{color} :style @var{style})}
1977 This way you can explicitly specify all aspects of the box. The value
1978 @var{width} specifies the width of the lines to draw; it defaults to 1.
1980 The value @var{color} specifies the color to draw with. The default is
1981 the foreground color of the face for simple boxes, and the background
1982 color of the face for 3D boxes.
1984 The value @var{style} specifies whether to draw a 3D box. If it is
1985 @code{released-button}, the box looks like a 3D button that is not being
1986 pressed. If it is @code{pressed-button}, the box looks like a 3D button
1987 that is being pressed. If it is @code{nil} or omitted, a plain 2D box
1991 In older versions of Emacs, before @code{:family}, @code{:height},
1992 @code{:width}, @code{:weight}, and @code{:slant} existed, these
1993 attributes were used to specify the type face. They are now
1994 semi-obsolete, but they still work:
1998 This attribute specifies the font name.
2001 A non-@code{nil} value specifies a bold font.
2004 A non-@code{nil} value specifies an italic font.
2007 For compatibility, you can still set these ``attributes'', even
2008 though they are not real face attributes. Here is what that does:
2012 You can specify an X font name as the ``value'' of this ``attribute'';
2013 that sets the @code{:family}, @code{:width}, @code{:height},
2014 @code{:weight}, and @code{:slant} attributes according to the font name.
2016 If the value is a pattern with wildcards, the first font that matches
2017 the pattern is used to set these attributes.
2020 A non-@code{nil} makes the face bold; @code{nil} makes it normal.
2021 This actually works by setting the @code{:weight} attribute.
2024 A non-@code{nil} makes the face italic; @code{nil} makes it normal.
2025 This actually works by setting the @code{:slant} attribute.
2028 @defvar x-bitmap-file-path
2029 This variable specifies a list of directories for searching
2030 for bitmap files, for the @code{:stipple} attribute.
2033 @defun bitmap-spec-p object
2034 This returns @code{t} if @var{object} is a valid bitmap specification,
2035 suitable for use with @code{:stipple} (see above). It returns
2036 @code{nil} otherwise.
2039 @node Attribute Functions
2040 @subsection Face Attribute Functions
2042 You can modify the attributes of an existing face with the following
2043 functions. If you specify @var{frame}, they affect just that frame;
2044 otherwise, they affect all frames as well as the defaults that apply to
2047 @tindex set-face-attribute
2048 @defun set-face-attribute face frame &rest arguments
2049 This function sets one or more attributes of face @var{face}
2050 for frame @var{frame}. If @var{frame} is @code{nil}, it sets
2051 the attribute for all frames, and the defaults for new frames.
2053 The extra arguments @var{arguments} specify the attributes to set, and
2054 the values for them. They should consist of alternating attribute names
2055 (such as @code{:family} or @code{:underline}) and corresponding values.
2059 (set-face-attribute 'foo nil
2066 sets the attributes @code{:width}, @code{:weight} and @code{:underline}
2067 to the corresponding values.
2070 @tindex face-attribute
2071 @defun face-attribute face attribute &optional frame inherit
2072 This returns the value of the @var{attribute} attribute of face
2073 @var{face} on @var{frame}. If @var{frame} is @code{nil},
2074 that means the selected frame (@pxref{Input Focus}).
2076 If @var{frame} is @code{t}, the value is the default for
2077 @var{face} for new frames.
2079 If @var{inherit} is @code{nil}, only attributes directly defined by
2080 @var{face} are considered, so the return value may be
2081 @code{unspecified}, or a relative value. If @var{inherit} is
2082 non-@code{nil}, @var{face}'s definition of @var{attribute} is merged
2083 with the faces specified by its @code{:inherit} attribute; however the
2084 return value may still be @code{unspecified} or relative. If
2085 @var{inherit} is a face or a list of faces, then the result is further
2086 merged with that face (or faces), until it becomes specified and
2089 To ensure that the return value is always specified and absolute, use
2090 a value of @code{default} for @var{inherit}; this will resolve any
2091 unspecified or relative values by merging with the @code{default} face
2092 (which is always completely specified).
2097 (face-attribute 'bold :weight)
2102 The functions above did not exist before Emacs 21. For compatibility
2103 with older Emacs versions, you can use the following functions to set
2104 and examine the face attributes which existed in those versions.
2106 @tindex face-attribute-relative-p
2107 @defun face-attribute-relative-p attribute value
2108 This function returns non-@code{nil} if @var{value}, when used as
2109 the value of the face attribute @var{attribute}, is relative (that is,
2110 if it modifies an underlying or inherited value of @var{attribute}).
2113 @tindex merge-face-attribute
2114 @defun merge-face-attribute attribute value1 value2
2115 If @var{value1} is a relative value for the face attribute
2116 @var{attribute}, returns it merged with the underlying value
2117 @var{value2}; otherwise, if @var{value1} is an absolute value for the
2118 face attribute @var{attribute}, returns @var{value1} unchanged.
2121 @defun set-face-foreground face color &optional frame
2122 @defunx set-face-background face color &optional frame
2123 These functions set the foreground (or background, respectively) color
2124 of face @var{face} to @var{color}. The argument @var{color} should be a
2125 string, the name of a color.
2127 Certain shades of gray are implemented by stipple patterns on
2128 black-and-white screens.
2131 @defun set-face-stipple face pattern &optional frame
2132 This function sets the background stipple pattern of face @var{face}
2133 to @var{pattern}. The argument @var{pattern} should be the name of a
2134 stipple pattern defined by the X server, or actual bitmap data
2135 (@pxref{Face Attributes}), or @code{nil} meaning don't use stipple.
2137 Normally there is no need to pay attention to stipple patterns, because
2138 they are used automatically to handle certain shades of gray.
2141 @defun set-face-font face font &optional frame
2142 This function sets the font of face @var{face}. This actually sets
2143 the attributes @code{:family}, @code{:width}, @code{:height},
2144 @code{:weight}, and @code{:slant} according to the font name
2148 @defun set-face-bold-p face bold-p &optional frame
2149 This function specifies whether @var{face} should be bold. If
2150 @var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no.
2151 This actually sets the @code{:weight} attribute.
2154 @defun set-face-italic-p face italic-p &optional frame
2155 This function specifies whether @var{face} should be italic. If
2156 @var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no.
2157 This actually sets the @code{:slant} attribute.
2160 @defun set-face-underline-p face underline-p &optional frame
2161 This function sets the underline attribute of face @var{face}.
2162 Non-@code{nil} means do underline; @code{nil} means don't.
2165 @defun set-face-inverse-video-p face inverse-video-p &optional frame
2166 This function sets the @code{:inverse-video} attribute of face
2170 @defun invert-face face &optional frame
2171 This function swaps the foreground and background colors of face
2175 These functions examine the attributes of a face. If you don't
2176 specify @var{frame}, they refer to the default data for new frames.
2177 They return the symbol @code{unspecified} if the face doesn't define any
2178 value for that attribute.
2180 @defun face-foreground face &optional frame inherit
2181 @defunx face-background face &optional frame inherit
2182 These functions return the foreground color (or background color,
2183 respectively) of face @var{face}, as a string.
2185 If @var{inherit} is @code{nil}, only a color directly defined by the face is
2186 returned. If @var{inherit} is non-@code{nil}, any faces specified by its
2187 @code{:inherit} attribute are considered as well, and if @var{inherit}
2188 is a face or a list of faces, then they are also considered, until a
2189 specified color is found. To ensure that the return value is always
2190 specified, use a value of @code{default} for @var{inherit}.
2193 @defun face-stipple face &optional frame inherit
2194 This function returns the name of the background stipple pattern of face
2195 @var{face}, or @code{nil} if it doesn't have one.
2197 If @var{inherit} is @code{nil}, only a stipple directly defined by the
2198 face is returned. If @var{inherit} is non-@code{nil}, any faces
2199 specified by its @code{:inherit} attribute are considered as well, and
2200 if @var{inherit} is a face or a list of faces, then they are also
2201 considered, until a specified stipple is found. To ensure that the
2202 return value is always specified, use a value of @code{default} for
2206 @defun face-font face &optional frame
2207 This function returns the name of the font of face @var{face}.
2210 @defun face-bold-p face &optional frame
2211 This function returns @code{t} if @var{face} is bold---that is, if it is
2212 bolder than normal. It returns @code{nil} otherwise.
2215 @defun face-italic-p face &optional frame
2216 This function returns @code{t} if @var{face} is italic or oblique,
2217 @code{nil} otherwise.
2220 @defun face-underline-p face &optional frame
2221 This function returns the @code{:underline} attribute of face @var{face}.
2224 @defun face-inverse-video-p face &optional frame
2225 This function returns the @code{:inverse-video} attribute of face @var{face}.
2228 @node Displaying Faces
2229 @subsection Displaying Faces
2231 Here are the ways to specify which faces to use for display of text:
2235 With defaults. The @code{default} face is used as the ultimate
2236 default for all text. (In Emacs 19 and 20, the @code{default}
2237 face is used only when no other face is specified.)
2240 For a mode line or header line, the face @code{mode-line} or
2241 @code{mode-line-inactive}, or @code{header-line}, is merged in just
2242 before @code{default}.
2245 With text properties. A character can have a @code{face} property; if
2246 so, the faces and face attributes specified there apply. @xref{Special
2249 If the character has a @code{mouse-face} property, that is used instead
2250 of the @code{face} property when the mouse is ``near enough'' to the
2254 With overlays. An overlay can have @code{face} and @code{mouse-face}
2255 properties too; they apply to all the text covered by the overlay.
2258 With a region that is active. In Transient Mark mode, the region is
2259 highlighted with the face @code{region} (@pxref{Standard Faces,,,
2260 emacs, The GNU Emacs Manual}).
2263 With special glyphs. Each glyph can specify a particular face
2264 number. @xref{Glyphs}.
2267 If these various sources together specify more than one face for a
2268 particular character, Emacs merges the attributes of the various faces
2269 specified. For each attribute, Emacs tries first the face of any
2270 special glyph; then the face for region highlighting, if appropriate;
2271 then the faces specified by overlays, followed by those specified by
2272 text properties, then the @code{mode-line} or
2273 @code{mode-line-inactive} or @code{header-line} face (if in a mode
2274 line or a header line), and last the @code{default} face.
2276 When multiple overlays cover one character, an overlay with higher
2277 priority overrides those with lower priority. @xref{Overlays}.
2279 @node Font Selection
2280 @subsection Font Selection
2282 @dfn{Selecting a font} means mapping the specified face attributes for
2283 a character to a font that is available on a particular display. The
2284 face attributes, as determined by face merging, specify most of the
2285 font choice, but not all. Part of the choice depends on what character
2288 If the face specifies a fontset name, that fontset determines a
2289 pattern for fonts of the given charset. If the face specifies a font
2290 family, a font pattern is constructed.
2292 Emacs tries to find an available font for the given face attributes
2293 and character's registry and encoding. If there is a font that matches
2294 exactly, it is used, of course. The hard case is when no available font
2295 exactly fits the specification. Then Emacs looks for one that is
2296 ``close''---one attribute at a time. You can specify the order to
2297 consider the attributes. In the case where a specified font family is
2298 not available, you can specify a set of mappings for alternatives to
2301 @defvar face-font-selection-order
2302 @tindex face-font-selection-order
2303 This variable specifies the order of importance of the face attributes
2304 @code{:width}, @code{:height}, @code{:weight}, and @code{:slant}. The
2305 value should be a list containing those four symbols, in order of
2306 decreasing importance.
2308 Font selection first finds the best available matches for the first
2309 attribute listed; then, among the fonts which are best in that way, it
2310 searches for the best matches in the second attribute, and so on.
2312 The attributes @code{:weight} and @code{:width} have symbolic values in
2313 a range centered around @code{normal}. Matches that are more extreme
2314 (farther from @code{normal}) are somewhat preferred to matches that are
2315 less extreme (closer to @code{normal}); this is designed to ensure that
2316 non-normal faces contrast with normal ones, whenever possible.
2318 The default is @code{(:width :height :weight :slant)}, which means first
2319 find the fonts closest to the specified @code{:width}, then---among the
2320 fonts with that width---find a best match for the specified font height,
2323 One example of a case where this variable makes a difference is when the
2324 default font has no italic equivalent. With the default ordering, the
2325 @code{italic} face will use a non-italic font that is similar to the
2326 default one. But if you put @code{:slant} before @code{:height}, the
2327 @code{italic} face will use an italic font, even if its height is not
2331 @defvar face-font-family-alternatives
2332 @tindex face-font-family-alternatives
2333 This variable lets you specify alternative font families to try, if a
2334 given family is specified and doesn't exist. Each element should have
2338 (@var{family} @var{alternate-families}@dots{})
2341 If @var{family} is specified but not available, Emacs will try the other
2342 families given in @var{alternate-families}, one by one, until it finds a
2343 family that does exist.
2346 @defvar face-font-registry-alternatives
2347 @tindex face-font-registry-alternatives
2348 This variable lets you specify alternative font registries to try, if a
2349 given registry is specified and doesn't exist. Each element should have
2353 (@var{registry} @var{alternate-registries}@dots{})
2356 If @var{registry} is specified but not available, Emacs will try the
2357 other registries given in @var{alternate-registries}, one by one,
2358 until it finds a registry that does exist.
2361 Emacs can make use of scalable fonts, but by default it does not use
2362 them, since the use of too many or too big scalable fonts can crash
2365 @defvar scalable-fonts-allowed
2366 @tindex scalable-fonts-allowed
2367 This variable controls which scalable fonts to use. A value of
2368 @code{nil}, the default, means do not use scalable fonts. @code{t}
2369 means to use any scalable font that seems appropriate for the text.
2371 Otherwise, the value must be a list of regular expressions. Then a
2372 scalable font is enabled for use if its name matches any regular
2373 expression in the list. For example,
2376 (setq scalable-fonts-allowed '("muleindian-2$"))
2380 allows the use of scalable fonts with registry @code{muleindian-2}.
2383 @defun clear-face-cache &optional unload-p
2384 @tindex clear-face-cache
2385 This function clears the face cache for all frames.
2386 If @var{unload-p} is non-@code{nil}, that means to unload
2387 all unused fonts as well.
2390 @defvar face-font-rescale-alist
2391 This variable specifies scaling for certain faces. Its value should
2392 be a list of elements of the form
2395 (@var{fontname-regexp} . @var{scale-factor})
2398 If @var{fontname-regexp} matches the font name that is about to be
2399 used, this says to choose a larger similar font according to the
2400 factor @var{scale-factor}. You would use this feature to normalize
2401 the font size if certain fonts are bigger or smaller than their
2402 nominal heights and widths would suggest.
2405 @node Face Functions
2406 @subsection Functions for Working with Faces
2408 Here are additional functions for creating and working with faces.
2410 @defun make-face name
2411 This function defines a new face named @var{name}, initially with all
2412 attributes @code{nil}. It does nothing if there is already a face named
2417 This function returns a list of all defined face names.
2420 @defun copy-face old-face new-name &optional frame new-frame
2421 This function defines a face named @var{new-name} as a copy of the existing
2422 face named @var{old-face}. It creates the face @var{new-name} if that
2423 doesn't already exist.
2425 If the optional argument @var{frame} is given, this function applies
2426 only to that frame. Otherwise it applies to each frame individually,
2427 copying attributes from @var{old-face} in each frame to @var{new-face}
2430 If the optional argument @var{new-frame} is given, then @code{copy-face}
2431 copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
2436 This function returns the face number of face @var{face}.
2439 @defun face-documentation face
2440 This function returns the documentation string of face @var{face}, or
2441 @code{nil} if none was specified for it.
2444 @defun face-equal face1 face2 &optional frame
2445 This returns @code{t} if the faces @var{face1} and @var{face2} have the
2446 same attributes for display.
2449 @defun face-differs-from-default-p face &optional frame
2450 This returns non-@code{nil} if the face @var{face} displays
2451 differently from the default face.
2455 A @dfn{face alias} provides an equivalent name for a face. You can
2456 define a face alias by giving the alias symbol the @code{face-alias}
2457 property, with a value of the target face name. The following example
2458 makes @code{modeline} an alias for the @code{mode-line} face.
2461 (put 'modeline 'face-alias 'mode-line)
2466 @subsection Automatic Face Assignment
2467 @cindex automatic face assignment
2468 @cindex faces, automatic choice
2470 @cindex Font-Lock mode
2471 This hook is used for automatically assigning faces to text in the
2472 buffer. It is part of the implementation of Font-Lock mode.
2474 @tindex fontification-functions
2475 @defvar fontification-functions
2476 This variable holds a list of functions that are called by Emacs
2477 redisplay as needed to assign faces automatically to text in the buffer.
2479 The functions are called in the order listed, with one argument, a
2480 buffer position @var{pos}. Each function should attempt to assign faces
2481 to the text in the current buffer starting at @var{pos}.
2483 Each function should record the faces they assign by setting the
2484 @code{face} property. It should also add a non-@code{nil}
2485 @code{fontified} property for all the text it has assigned faces to.
2486 That property tells redisplay that faces have been assigned to that text
2489 It is probably a good idea for each function to do nothing if the
2490 character after @var{pos} already has a non-@code{nil} @code{fontified}
2491 property, but this is not required. If one function overrides the
2492 assignments made by a previous one, the properties as they are
2493 after the last function finishes are the ones that really matter.
2495 For efficiency, we recommend writing these functions so that they
2496 usually assign faces to around 400 to 600 characters at each call.
2500 @subsection Looking Up Fonts
2502 @defun x-list-fonts pattern &optional face frame maximum
2503 This function returns a list of available font names that match
2504 @var{pattern}. If the optional arguments @var{face} and @var{frame} are
2505 specified, then the list is limited to fonts that are the same size as
2506 @var{face} currently is on @var{frame}.
2508 The argument @var{pattern} should be a string, perhaps with wildcard
2509 characters: the @samp{*} character matches any substring, and the
2510 @samp{?} character matches any single character. Pattern matching
2511 of font names ignores case.
2513 If you specify @var{face} and @var{frame}, @var{face} should be a face name
2514 (a symbol) and @var{frame} should be a frame.
2516 The optional argument @var{maximum} sets a limit on how many fonts to
2517 return. If this is non-@code{nil}, then the return value is truncated
2518 after the first @var{maximum} matching fonts. Specifying a small value
2519 for @var{maximum} can make this function much faster, in cases where
2520 many fonts match the pattern.
2523 @defun x-family-fonts &optional family frame
2524 @tindex x-family-fonts
2525 This function returns a list describing the available fonts for family
2526 @var{family} on @var{frame}. If @var{family} is omitted or @code{nil},
2527 this list applies to all families, and therefore, it contains all
2528 available fonts. Otherwise, @var{family} must be a string; it may
2529 contain the wildcards @samp{?} and @samp{*}.
2531 The list describes the display that @var{frame} is on; if @var{frame} is
2532 omitted or @code{nil}, it applies to the selected frame's display
2533 (@pxref{Input Focus}).
2535 The list contains a vector of the following form for each font:
2538 [@var{family} @var{width} @var{point-size} @var{weight} @var{slant}
2539 @var{fixed-p} @var{full} @var{registry-and-encoding}]
2542 The first five elements correspond to face attributes; if you
2543 specify these attributes for a face, it will use this font.
2545 The last three elements give additional information about the font.
2546 @var{fixed-p} is non-@code{nil} if the font is fixed-pitch.
2547 @var{full} is the full name of the font, and
2548 @var{registry-and-encoding} is a string giving the registry and
2549 encoding of the font.
2551 The result list is sorted according to the current face font sort order.
2554 @defun x-font-family-list &optional frame
2555 @tindex x-font-family-list
2556 This function returns a list of the font families available for
2557 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, it
2558 describes the selected frame's display (@pxref{Input Focus}).
2560 The value is a list of elements of this form:
2563 (@var{family} . @var{fixed-p})
2567 Here @var{family} is a font family, and @var{fixed-p} is
2568 non-@code{nil} if fonts of that family are fixed-pitch.
2571 @defvar font-list-limit
2572 @tindex font-list-limit
2573 This variable specifies maximum number of fonts to consider in font
2574 matching. The function @code{x-family-fonts} will not return more than
2575 that many fonts, and font selection will consider only that many fonts
2576 when searching a matching font for face attributes. The default is
2581 @subsection Fontsets
2583 A @dfn{fontset} is a list of fonts, each assigned to a range of
2584 character codes. An individual font cannot display the whole range of
2585 characters that Emacs supports, but a fontset can. Fontsets have names,
2586 just as fonts do, and you can use a fontset name in place of a font name
2587 when you specify the ``font'' for a frame or a face. Here is
2588 information about defining a fontset under Lisp program control.
2590 @defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
2591 This function defines a new fontset according to the specification
2592 string @var{fontset-spec}. The string should have this format:
2595 @var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
2599 Whitespace characters before and after the commas are ignored.
2601 The first part of the string, @var{fontpattern}, should have the form of
2602 a standard X font name, except that the last two fields should be
2603 @samp{fontset-@var{alias}}.
2605 The new fontset has two names, one long and one short. The long name is
2606 @var{fontpattern} in its entirety. The short name is
2607 @samp{fontset-@var{alias}}. You can refer to the fontset by either
2608 name. If a fontset with the same name already exists, an error is
2609 signaled, unless @var{noerror} is non-@code{nil}, in which case this
2610 function does nothing.
2612 If optional argument @var{style-variant-p} is non-@code{nil}, that says
2613 to create bold, italic and bold-italic variants of the fontset as well.
2614 These variant fontsets do not have a short name, only a long one, which
2615 is made by altering @var{fontpattern} to indicate the bold or italic
2618 The specification string also says which fonts to use in the fontset.
2619 See below for the details.
2622 The construct @samp{@var{charset}:@var{font}} specifies which font to
2623 use (in this fontset) for one particular character set. Here,
2624 @var{charset} is the name of a character set, and @var{font} is the font
2625 to use for that character set. You can use this construct any number of
2626 times in the specification string.
2628 For the remaining character sets, those that you don't specify
2629 explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
2630 @samp{fontset-@var{alias}} with a value that names one character set.
2631 For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced
2632 with @samp{ISO8859-1}.
2634 In addition, when several consecutive fields are wildcards, Emacs
2635 collapses them into a single wildcard. This is to prevent use of
2636 auto-scaled fonts. Fonts made by scaling larger fonts are not usable
2637 for editing, and scaling a smaller font is not useful because it is
2638 better to use the smaller font in its own size, which Emacs does.
2640 Thus if @var{fontpattern} is this,
2643 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
2647 the font specification for @acronym{ASCII} characters would be this:
2650 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
2654 and the font specification for Chinese GB2312 characters would be this:
2657 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
2660 You may not have any Chinese font matching the above font
2661 specification. Most X distributions include only Chinese fonts that
2662 have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
2663 such a case, @samp{Fontset-@var{n}} can be specified as below:
2666 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
2667 chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
2671 Then, the font specifications for all but Chinese GB2312 characters have
2672 @samp{fixed} in the @var{family} field, and the font specification for
2673 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
2676 @defun set-fontset-font name character fontname &optional frame
2677 This function modifies the existing fontset @var{name} to
2678 use the font name @var{fontname} for the character @var{character}.
2680 If @var{name} is @code{nil}, this function modifies the default
2681 fontset, whose short name is @samp{fontset-default}.
2683 @var{character} may be a cons; @code{(@var{from} . @var{to})}, where
2684 @var{from} and @var{to} are non-generic characters. In that case, use
2685 @var{fontname} for all characters in the range @var{from} and @var{to}
2688 @var{character} may be a charset. In that case, use
2689 @var{fontname} for all character in the charsets.
2691 @var{fontname} may be a cons; @code{(@var{family} . @var{registry})},
2692 where @var{family} is a family name of a font (possibly including a
2693 foundry name at the head), @var{registry} is a registry name of a font
2694 (possibly including an encoding name at the tail).
2696 For instance, this changes the default fontset to use a font of which
2697 registry name is @samp{JISX0208.1983} for all characters belonging to
2698 the charset @code{japanese-jisx0208}.
2701 (set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
2705 @defun char-displayable-p char
2706 This function returns @code{t} if Emacs ought to be able to display
2707 @var{char}. More precisely, if the selected frame's fontset has a
2708 font to display the character set that @var{char} belongs to.
2710 Fontsets can specify a font on a per-character basis; when the fontset
2711 does that, this function's value may not be accurate.
2718 The @dfn{fringes} of a window are thin vertical strips down the
2719 sides that are used for displaying bitmaps that indicate truncation,
2720 continuation, horizontal scrolling, and the overlay arrow.
2723 * Fringe Size/Pos:: Specifying where to put the window fringes.
2724 * Fringe Bitmaps:: Displaying bitmaps in the window fringes.
2725 * Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes.
2726 * Overlay Arrow:: Display of an arrow to indicate position.
2729 @node Fringe Size/Pos
2730 @subsection Fringe Size and Position
2732 Here's how to control the position and width of the window fringes.
2734 @defvar fringes-outside-margins
2735 If the value is non-@code{nil}, the frames appear outside the display
2736 margins. The fringes normally appear between the display margins and
2737 the window text. It works to set @code{fringes-outside-margins}
2738 buffer-locally. @xref{Display Margins}.
2741 @defvar left-fringe-width
2742 This variable, if non-@code{nil}, specifies the width of the left
2746 @defvar right-fringe-width
2747 This variable, if non-@code{nil}, specifies the width of the right
2751 The values of these variables take effect when you display the
2752 buffer in a window. If you change them while the buffer is visible,
2753 you can call @code{set-window-buffer} to display it once again in the
2754 same window, to make the changes take effect.
2756 @defun set-window-fringes window left &optional right outside-margins
2757 This function sets the fringe widths of window @var{window}.
2758 If @var{window} is @code{nil}, the selected window is used.
2760 The argument @var{left} specifies the width in pixels of the left
2761 fringe, and likewise @var{right} for the right fringe. A value of
2762 @code{nil} for either one stands for the default width. If
2763 @var{outside-margins} is non-@code{nil}, that specifies that fringes
2764 should appear outside of the display margins.
2767 @defun window-fringes &optional window
2768 This function returns information about the fringes of a window
2769 @var{window}. If @var{window} is omitted or @code{nil}, the selected
2770 window is used. The value has the form @code{(@var{left-width}
2771 @var{right-width} @var{outside-margins})}.
2774 @defvar overflow-newline-into-fringe
2775 If this is non-@code{nil}, lines exactly as wide as the window (not
2776 counting the final newline character) are not continued. Instead,
2777 when point is at the end of the line, the cursor appears in the right
2781 @node Fringe Bitmaps
2782 @subsection Fringe Bitmaps
2783 @cindex fringe bitmaps
2784 @cindex bitmaps, fringe
2786 The @dfn{fringe bitmaps} are tiny icons Emacs displays in the window
2787 fringe (on a graphic display) to indicate truncated or continued
2788 lines, buffer boundaries, overlay arrow, etc. The fringe bitmaps are
2789 shared by all frames and windows. You can redefine the built-in
2790 fringe bitmaps, and you can define new fringe bitmaps.
2792 The way to display a bitmap in the left or right fringes for a given
2793 line in a window is by specifying the @code{display} property for one
2794 of the characters that appears in it. Use a display specification of
2795 the form @code{(left-fringe @var{bitmap} [@var{face}])} or
2796 @code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display
2797 Property}). Here, @var{bitmap} is a symbol identifying the bitmap you
2798 want, and @var{face} (which is optional) is the name of the face whose
2799 colors should be used for displaying the bitmap, instead of the
2800 default @code{fringe} face. @var{face} is automatically merged with
2801 the @code{fringe} face, so normally @var{face} need only specify the
2802 foreground color for the bitmap.
2804 These symbols identify the standard fringe bitmaps. Evaluate
2805 @code{(require 'fringe)} to define them. Fringe bitmap symbols have
2806 their own name space.
2809 @item Truncation and continuation line bitmaps:
2810 @code{left-truncation}, @code{right-truncation},
2811 @code{continued-line}, @code{continuation-line}.
2813 @item Buffer indication bitmaps:
2814 @code{up-arrow}, @code{down-arrow},
2815 @code{top-left-angle}, @code{top-right-angle},
2816 @code{bottom-left-angle}, @code{bottom-right-angle},
2817 @code{left-bracket}, @code{right-bracket}.
2819 @item Empty line indication bitmap:
2822 @item Overlay arrow bitmap:
2823 @code{overlay-arrow}.
2825 @item Bitmaps for displaying the cursor in right fringe:
2826 @code{filled-box-cursor}, @code{hollow-box-cursor}, @code{hollow-square},
2827 @code{bar-cursor}, @code{hbar-cursor}.
2830 @defun fringe-bitmaps-at-pos &optional pos window
2831 This function returns the fringe bitmaps of the display line
2832 containing position @var{pos} in window @var{window}. The return
2833 value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left}
2834 is the symbol for the fringe bitmap in the left fringe (or @code{nil}
2835 if no bitmap), @var{right} is similar for the right fringe, and @var{ov}
2836 is non-@code{nil} if there is an overlay arrow in the left fringe.
2838 The value is @code{nil} if @var{pos} is not visible in @var{window}.
2839 If @var{window} is @code{nil}, that stands for the selected window.
2840 If @var{pos} is @code{nil}, that stands for the value of point in
2844 @node Customizing Bitmaps
2845 @subsection Customizing Fringe Bitmaps
2847 @defun define-fringe-bitmap bitmap bits &optional height width align
2848 This function defines the symbol @var{bitmap} as a new fringe bitmap,
2849 or replaces an existing bitmap with that name.
2851 The argument @var{bits} specifies the image to use. It should be
2852 either a string or a vector of integers, where each element (an
2853 integer) corresponds to one row of the bitmap. Each bit of an integer
2854 corresponds to one pixel of the bitmap, where the low bit corresponds
2855 to the rightmost pixel of the bitmap.
2857 The height is normally the length of @var{bits}. However, you
2858 can specify a different height with non-@code{nil} @var{height}. The width
2859 is normally 8, but you can specify a different width with non-@code{nil}
2860 @var{width}. The width must be an integer between 1 and 16.
2862 The argument @var{align} specifies the positioning of the bitmap
2863 relative to the range of rows where it is used; the default is to
2864 center the bitmap. The allowed values are @code{top}, @code{center},
2867 The @var{align} argument may also be a list @code{(@var{align}
2868 @var{periodic})} where @var{align} is interpreted as described above.
2869 If @var{periodic} is non-@code{nil}, it specifies that the rows in
2870 @code{bits} should be repeated enough times to reach the specified
2873 The return value on success is an integer identifying the new bitmap.
2874 You should save that integer in a variable so it can be used to select
2877 This function signals an error if there are no more free bitmap slots.
2880 @defun destroy-fringe-bitmap bitmap
2881 This function destroy the fringe bitmap identified by @var{bitmap}.
2882 If @var{bitmap} identifies a standard fringe bitmap, it actually
2883 restores the standard definition of that bitmap, instead of
2884 eliminating it entirely.
2887 @defun set-fringe-bitmap-face bitmap &optional face
2888 This sets the face for the fringe bitmap @var{bitmap} to @var{face}.
2889 If @var{face} is @code{nil}, it selects the @code{fringe} face. The
2890 bitmap's face controls the color to draw it in.
2892 @var{face} is merged with the @code{fringe} face, so normally
2893 @var{face} should specify only the foreground color.
2897 @subsection The Overlay Arrow
2898 @cindex overlay arrow
2900 The @dfn{overlay arrow} is useful for directing the user's attention
2901 to a particular line in a buffer. For example, in the modes used for
2902 interface to debuggers, the overlay arrow indicates the line of code
2903 about to be executed. This feature has nothing to do with
2904 @dfn{overlays} (@pxref{Overlays}).
2906 @defvar overlay-arrow-string
2907 This variable holds the string to display to call attention to a
2908 particular line, or @code{nil} if the arrow feature is not in use.
2909 On a graphical display the contents of the string are ignored; instead a
2910 glyph is displayed in the fringe area to the left of the display area.
2913 @defvar overlay-arrow-position
2914 This variable holds a marker that indicates where to display the overlay
2915 arrow. It should point at the beginning of a line. On a non-graphical
2916 display the arrow text
2917 appears at the beginning of that line, overlaying any text that would
2918 otherwise appear. Since the arrow is usually short, and the line
2919 usually begins with indentation, normally nothing significant is
2922 The overlay string is displayed only in the buffer that this marker
2923 points into. Thus, only one buffer can have an overlay arrow at any
2925 @c !!! overlay-arrow-position: but the overlay string may remain in the display
2926 @c of some other buffer until an update is required. This should be fixed
2930 You can do a similar job by creating an overlay with a
2931 @code{before-string} property. @xref{Overlay Properties}.
2933 You can define multiple overlay arrows via the variable
2934 @code{overlay-arrow-variable-list}.
2936 @defvar overlay-arrow-variable-list
2937 This variable's value is a list of variables, each of which specifies
2938 the position of an overlay arrow. The variable
2939 @code{overlay-arrow-position} has its normal meaning because it is on
2943 Each variable on this list can have properties
2944 @code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that
2945 specify an overlay arrow string (for text-only terminals) or fringe
2946 bitmap (for graphical terminals) to display at the corresponding
2947 overlay arrow position. If either property is not set, the default
2948 (@code{overlay-arrow-string} or @code{overlay-arrow-fringe-bitmap}) is
2952 @section Scroll Bars
2954 Normally the frame parameter @code{vertical-scroll-bars} controls
2955 whether the windows in the frame have vertical scroll bars, and
2956 whether they are on the left or right. The frame parameter
2957 @code{scroll-bar-width} specifies how wide they are (@code{nil}
2958 meaning the default). @xref{Layout Parameters}.
2960 @defun frame-current-scroll-bars &optional frame
2961 This function reports the scroll bar type settings for frame
2962 @var{frame}. The value is a cons cell
2963 @code{(@var{vertical-type} .@: @var{horizontal-type})}, where
2964 @var{vertical-type} is either @code{left}, @code{right}, or @code{nil}
2965 (which means no scroll bar.) @var{horizontal-type} is meant to
2966 specify the horizontal scroll bar type, but since they are not
2967 implemented, it is always @code{nil}.
2970 @vindex vertical-scroll-bar
2971 You can enable or disable scroll bars for a particular buffer,
2972 by setting the variable @code{vertical-scroll-bar}. This variable
2973 automatically becomes buffer-local when set. The possible values are
2974 @code{left}, @code{right}, @code{t}, which means to use the
2975 frame's default, and @code{nil} for no scroll bar.
2977 You can also control this for individual windows. Call the function
2978 @code{set-window-scroll-bars} to specify what to do for a specific window:
2980 @defun set-window-scroll-bars window width &optional vertical-type horizontal-type
2981 This function sets the width and type of scroll bars for window
2984 @var{width} specifies the scroll bar width in pixels (@code{nil} means
2985 use the width specified for the frame). @var{vertical-type} specifies
2986 whether to have a vertical scroll bar and, if so, where. The possible
2987 values are @code{left}, @code{right} and @code{nil}, just like the
2988 values of the @code{vertical-scroll-bars} frame parameter.
2990 The argument @var{horizontal-type} is meant to specify whether and
2991 where to have horizontal scroll bars, but since they are not
2992 implemented, it has no effect. If @var{window} is @code{nil}, the
2993 selected window is used.
2996 @defun window-scroll-bars &optional window
2997 Report the width and type of scroll bars specified for @var{window}.
2998 If @var{window} is omitted or @code{nil}, the selected window is used.
2999 The value is a list of the form @code{(@var{width}
3000 @var{cols} @var{vertical-type} @var{horizontal-type})}. The value
3001 @var{width} is the value that was specified for the width (which may
3002 be @code{nil}); @var{cols} is the number of columns that the scroll
3003 bar actually occupies.
3005 @var{horizontal-type} is not actually meaningful.
3008 If you don't specify these values for a window with
3009 @code{set-window-scroll-bars}, the buffer-local variables
3010 @code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being
3011 displayed control the window's vertical scroll bars. The function
3012 @code{set-window-buffer} examines these variables. If you change them
3013 in a buffer that is already visible in a window, you can make the
3014 window take note of the new values by calling @code{set-window-buffer}
3015 specifying the same buffer that is already displayed.
3017 @defvar scroll-bar-mode
3018 This variable, always local in all buffers, controls whether and where
3019 to put scroll bars in windows displaying the buffer. The possible values
3020 are @code{nil} for no scroll bar, @code{left} to put a scroll bar on
3021 the left, and @code{right} to put a scroll bar on the right.
3024 @defun window-current-scroll-bars &optional window
3025 This function reports the scroll bar type for window @var{window}.
3026 If @var{window} is omitted or @code{nil}, the selected window is used.
3027 The value is a cons cell
3028 @code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike
3029 @code{window-scroll-bars}, this reports the scroll bar type actually
3030 used, once frame defaults and @code{scroll-bar-mode} are taken into
3034 @defvar scroll-bar-width
3035 This variable, always local in all buffers, specifies the width of the
3036 buffer's scroll bars, measured in pixels. A value of @code{nil} means
3037 to use the value specified by the frame.
3041 @section Pointer Shape
3043 Normally, the mouse pointer has the @code{text} shape over text and
3044 the @code{arrow} shape over window areas which do not correspond to
3045 any buffer text. You can specify the mouse pointer shape over text or
3046 images via the @code{pointer} text property, and for images with the
3047 @code{:pointer} and @code{:map} image properties.
3049 The available pointer shapes are: @code{text} (or @code{nil}),
3050 @code{arrow}, @code{hand}, @code{vdrag}, @code{hdrag},
3051 @code{modeline}, and @code{hourglass}.
3053 @defvar void-text-area-pointer
3054 @tindex void-text-area-pointer
3055 This variable specifies the mouse pointer shape in void text areas,
3056 i.e. the areas after the end of a line or below the last line in the
3057 buffer. The default is to use the @code{arrow} (non-text) pointer.
3060 @node Display Property
3061 @section The @code{display} Property
3062 @cindex display specification
3063 @kindex display @r{(text property)}
3065 The @code{display} text property (or overlay property) is used to
3066 insert images into text, and also control other aspects of how text
3067 displays. The value of the @code{display} property should be a
3068 display specification, or a list or vector containing several display
3071 Some kinds of @code{display} properties specify something to display
3072 instead of the text that has the property. In this case, ``the text''
3073 means all the consecutive characters that have the same Lisp object as
3074 their @code{display} property; these characters are replaced as a
3075 single unit. By contrast, characters that have similar but distinct
3076 Lisp objects as their @code{display} properties are handled
3077 separately. Here's a function that illustrates this point:
3081 (goto-char (point-min))
3083 (let ((string (concat "A")))
3084 (put-text-property (point) (1+ (point)) 'display string)
3086 (put-text-property (point) (1+ (point)) 'display string)
3091 It gives each of the first ten characters in the buffer string
3092 @code{"A"} as the @code{display} property, but they don't all get the
3093 same string. The first two characters get the same string, so they
3094 together are replaced with one @samp{A}. The next two characters get
3095 a second string, so they together are replaced with one @samp{A}.
3096 Likewise for each following pair of characters. Thus, the ten
3097 characters appear as five A's. This function would have the same
3102 (goto-char (point-min))
3104 (let ((string (concat "A")))
3105 (put-text-property (point) (2+ (point)) 'display string)
3106 (put-text-property (point) (1+ (point)) 'display string)
3111 This illustrates that what matters is the property value for
3112 each character. If two consecutive characters have the same
3113 object as the @code{display} property value, it's irrelevant
3114 whether they got this property from a single call to
3115 @code{put-text-property} or from two different calls.
3117 The rest of this section describes several kinds of
3118 display specifications and what they mean.
3121 * Specified Space:: Displaying one space with a specified width.
3122 * Pixel Specification:: Specifying space width or height in pixels.
3123 * Other Display Specs:: Displaying an image; magnifying text; moving it
3124 up or down on the page; adjusting the width
3125 of spaces within text.
3126 * Display Margins:: Displaying text or images to the side of the main text.
3129 @node Specified Space
3130 @subsection Specified Spaces
3131 @cindex spaces, specified height or width
3132 @cindex specified spaces
3133 @cindex variable-width spaces
3135 To display a space of specified width and/or height, use a display
3136 specification of the form @code{(space . @var{props})}, where
3137 @var{props} is a property list (a list of alternating properties and
3138 values). You can put this property on one or more consecutive
3139 characters; a space of the specified height and width is displayed in
3140 place of @emph{all} of those characters. These are the properties you
3141 can use in @var{props} to specify the weight of the space:
3144 @item :width @var{width}
3145 If @var{width} is an integer or floating point number, it specifies
3146 that the space width should be @var{width} times the normal character
3147 width. @var{width} can also be a @dfn{pixel width} specification
3148 (@pxref{Pixel Specification}).
3150 @item :relative-width @var{factor}
3151 Specifies that the width of the stretch should be computed from the
3152 first character in the group of consecutive characters that have the
3153 same @code{display} property. The space width is the width of that
3154 character, multiplied by @var{factor}.
3156 @item :align-to @var{hpos}
3157 Specifies that the space should be wide enough to reach @var{hpos}.
3158 If @var{hpos} is a number, it is measured in units of the normal
3159 character width. @var{hpos} can also be a @dfn{pixel width}
3160 specification (@pxref{Pixel Specification}).
3163 You should use one and only one of the above properties. You can
3164 also specify the height of the space, with these properties:
3167 @item :height @var{height}
3168 Specifies the height of the space.
3169 If @var{height} is an integer or floating point number, it specifies
3170 that the space height should be @var{height} times the normal character
3171 height. The @var{height} may also be a @dfn{pixel height} specification
3172 (@pxref{Pixel Specification}).
3174 @item :relative-height @var{factor}
3175 Specifies the height of the space, multiplying the ordinary height
3176 of the text having this display specification by @var{factor}.
3178 @item :ascent @var{ascent}
3179 If the value of @var{ascent} is a non-negative number no greater than
3180 100, it specifies that @var{ascent} percent of the height of the space
3181 should be considered as the ascent of the space---that is, the part
3182 above the baseline. The ascent may also be specified in pixel units
3183 with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}).
3187 Don't use both @code{:height} and @code{:relative-height} together.
3189 The @code{:width} and @code{:align-to} properties are supported on
3190 non-graphic terminals, but the other space properties in this section
3193 @node Pixel Specification
3194 @subsection Pixel Specification for Spaces
3195 @cindex spaces, pixel specification
3197 The value of the @code{:width}, @code{:align-to}, @code{:height},
3198 and @code{:ascent} properties can be a special kind of expression that
3199 is evaluated during redisplay. The result of the evaluation is used
3200 as an absolute number of pixels.
3202 The following expressions are supported:
3206 @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form}
3207 @var{num} ::= @var{integer} | @var{float} | @var{symbol}
3208 @var{unit} ::= in | mm | cm | width | height
3211 @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin
3213 @var{pos} ::= left | center | right
3214 @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...)
3219 The form @var{num} specifies a fraction of the default frame font
3220 height or width. The form @code{(@var{num})} specifies an absolute
3221 number of pixels. If @var{num} is a symbol, @var{symbol}, its
3222 buffer-local variable binding is used.
3224 The @code{in}, @code{mm}, and @code{cm} units specify the number of
3225 pixels per inch, millimeter, and centimeter, respectively. The
3226 @code{width} and @code{height} units correspond to the default width
3227 and height of the current face. An image specification @code{image}
3228 corresponds to the width or height of the image.
3230 The @code{left-fringe}, @code{right-fringe}, @code{left-margin},
3231 @code{right-margin}, @code{scroll-bar}, and @code{text} elements
3232 specify to the width of the corresponding area of the window.
3234 The @code{left}, @code{center}, and @code{right} positions can be
3235 used with @code{:align-to} to specify a position relative to the left
3236 edge, center, or right edge of the text area.
3238 Any of the above window elements (except @code{text}) can also be
3239 used with @code{:align-to} to specify that the position is relative to
3240 the left edge of the given area. Once the base offset for a relative
3241 position has been set (by the first occurrence of one of these
3242 symbols), further occurrences of these symbols are interpreted as the
3243 width of the specified area. For example, to align to the center of
3244 the left-margin, use
3247 :align-to (+ left-margin (0.5 . left-margin))
3250 If no specific base offset is set for alignment, it is always relative
3251 to the left edge of the text area. For example, @samp{:align-to 0} in a
3252 header-line aligns with the first text column in the text area.
3254 A value of the form @code{(@var{num} . @var{expr})} stands for the
3255 product of the values of @var{num} and @var{expr}. For example,
3256 @code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 .
3257 @var{image})} specifies half the width (or height) of the specified
3260 The form @code{(+ @var{expr} ...)} adds up the value of the
3261 expressions. The form @code{(- @var{expr} ...)} negates or subtracts
3262 the value of the expressions.
3264 @node Other Display Specs
3265 @subsection Other Display Specifications
3267 Here are the other sorts of display specifications that you can use
3268 in the @code{display} text property.
3272 Display @var{string} instead of the text that has this property.
3274 @item (image . @var{image-props})
3275 This kind of display specification is an image descriptor (@pxref{Images}).
3276 When used as a display specification, it means to display the image
3277 instead of the text that has the display specification.
3279 @item (slice @var{x} @var{y} @var{width} @var{height})
3280 This specification together with @code{image} specifies a @dfn{slice}
3281 (a partial area) of the image to display. The elements @var{y} and
3282 @var{x} specify the top left corner of the slice, within the image;
3283 @var{width} and @var{height} specify the width and height of the
3284 slice. Integer values are numbers of pixels. A floating point number
3285 in the range 0.0--1.0 stands for that fraction of the width or height
3286 of the entire image.
3288 @item ((margin nil) @var{string})
3290 A display specification of this form means to display @var{string}
3291 instead of the text that has the display specification, at the same
3292 position as that text. This is a special case of marginal display
3293 (@pxref{Display Margins}).
3295 Recursive display specifications are not supported---string display
3296 specifications must not have @code{display} properties themselves.
3298 @item (space-width @var{factor})
3299 This display specification affects all the space characters within the
3300 text that has the specification. It displays all of these spaces
3301 @var{factor} times as wide as normal. The element @var{factor} should
3302 be an integer or float. Characters other than spaces are not affected
3303 at all; in particular, this has no effect on tab characters.
3305 @item (height @var{height})
3306 This display specification makes the text taller or shorter.
3307 Here are the possibilities for @var{height}:
3310 @item @code{(+ @var{n})}
3311 This means to use a font that is @var{n} steps larger. A ``step'' is
3312 defined by the set of available fonts---specifically, those that match
3313 what was otherwise specified for this text, in all attributes except
3314 height. Each size for which a suitable font is available counts as
3315 another step. @var{n} should be an integer.
3317 @item @code{(- @var{n})}
3318 This means to use a font that is @var{n} steps smaller.
3320 @item a number, @var{factor}
3321 A number, @var{factor}, means to use a font that is @var{factor} times
3322 as tall as the default font.
3324 @item a symbol, @var{function}
3325 A symbol is a function to compute the height. It is called with the
3326 current height as argument, and should return the new height to use.
3328 @item anything else, @var{form}
3329 If the @var{height} value doesn't fit the previous possibilities, it is
3330 a form. Emacs evaluates it to get the new height, with the symbol
3331 @code{height} bound to the current specified font height.
3334 @item (raise @var{factor})
3335 This kind of display specification raises or lowers the text
3336 it applies to, relative to the baseline of the line.
3338 @var{factor} must be a number, which is interpreted as a multiple of the
3339 height of the affected text. If it is positive, that means to display
3340 the characters raised. If it is negative, that means to display them
3343 If the text also has a @code{height} display specification, that does
3344 not affect the amount of raising or lowering, which is based on the
3345 faces used for the text.
3348 You can make any display specification conditional. To do that,
3349 package it in another list of the form @code{(when @var{condition} .
3350 @var{spec})}. Then the specification @var{spec} applies only when
3351 @var{condition} evaluates to a non-@code{nil} value. During the
3352 evaluation, @code{object} is bound to the string or buffer having the
3353 conditional @code{display} property. @code{position} and
3354 @code{buffer-position} are bound to the position within @code{object}
3355 and the buffer position where the @code{display} property was found,
3356 respectively. Both positions can be different when @code{object} is a
3359 @node Display Margins
3360 @subsection Displaying in the Margins
3361 @cindex display margins
3362 @cindex margins, display
3364 A buffer can have blank areas called @dfn{display margins} on the left
3365 and on the right. Ordinary text never appears in these areas, but you
3366 can put things into the display margins using the @code{display}
3369 To put text in the left or right display margin of the window, use a
3370 display specification of the form @code{(margin right-margin)} or
3371 @code{(margin left-margin)} on it. To put an image in a display margin,
3372 use that display specification along with the display specification for
3373 the image. Unfortunately, there is currently no way to make
3374 text or images in the margin mouse-sensitive.
3376 If you put such a display specification directly on text in the
3377 buffer, the specified margin display appears @emph{instead of} that
3378 buffer text itself. To put something in the margin @emph{in
3379 association with} certain buffer text without preventing or altering
3380 the display of that text, put a @code{before-string} property on the
3381 text and put the display specification on the contents of the
3384 Before the display margins can display anything, you must give
3385 them a nonzero width. The usual way to do that is to set these
3388 @defvar left-margin-width
3389 @tindex left-margin-width
3390 This variable specifies the width of the left margin.
3391 It is buffer-local in all buffers.
3394 @defvar right-margin-width
3395 @tindex right-margin-width
3396 This variable specifies the width of the right margin.
3397 It is buffer-local in all buffers.
3400 Setting these variables does not immediately affect the window. These
3401 variables are checked when a new buffer is displayed in the window.
3402 Thus, you can make changes take effect by calling
3403 @code{set-window-buffer}.
3405 You can also set the margin widths immediately.
3407 @defun set-window-margins window left &optional right
3408 @tindex set-window-margins
3409 This function specifies the margin widths for window @var{window}.
3410 The argument @var{left} controls the left margin and
3411 @var{right} controls the right margin (default @code{0}).
3414 @defun window-margins &optional window
3415 @tindex window-margins
3416 This function returns the left and right margins of @var{window}
3417 as a cons cell of the form @code{(@var{left} . @var{right})}.
3418 If @var{window} is @code{nil}, the selected window is used.
3423 @cindex images in buffers
3425 To display an image in an Emacs buffer, you must first create an image
3426 descriptor, then use it as a display specifier in the @code{display}
3427 property of text that is displayed (@pxref{Display Property}).
3429 Emacs can display a number of different image formats; some of them
3430 are supported only if particular support libraries are installed on
3431 your machine. In some environments, Emacs can load image
3432 libraries on demand; if so, the variable @code{image-library-alist}
3433 can be used to modify the set of known names for these dynamic
3434 libraries (though it is not possible to add new image formats).
3436 The supported image formats include XBM, XPM (this requires the
3437 libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring
3438 @code{libungif} 4.1.0), Postscript, PBM, JPEG (requiring the
3439 @code{libjpeg} library version v6a), TIFF (requiring @code{libtiff}
3440 v3.4), and PNG (requiring @code{libpng} 1.0.2).
3442 You specify one of these formats with an image type symbol. The image
3443 type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
3444 @code{pbm}, @code{jpeg}, @code{tiff}, and @code{png}.
3447 This variable contains a list of those image type symbols that are
3448 potentially supported in the current configuration.
3449 @emph{Potentially} here means that Emacs knows about the image types,
3450 not necessarily that they can be loaded (they could depend on
3451 unavailable dynamic libraries, for example).
3453 To know which image types are really available, use
3454 @code{image-type-available-p}.
3457 @defvar image-library-alist
3458 This in an alist of image types vs external libraries needed to
3461 Each element is a list @code{(@var{image-type} @var{library}...)},
3462 where the car is a supported image format from @code{image-types}, and
3463 the rest are strings giving alternate filenames for the corresponding
3464 external libraries to load.
3466 Emacs tries to load the libraries in the order they appear on the
3467 list; if none is loaded, the running session of Emacs won't support
3468 the image type. @code{pbm} and @code{xbm} don't need to be listed;
3469 they're always supported.
3471 This variable is ignored if the image libraries are statically linked
3475 @defun image-type-available-p type
3476 @findex image-type-available-p
3478 This function returns non-@code{nil} if image type @var{type} is
3479 available, i.e., if images of this type can be loaded and displayed in
3480 Emacs. @var{type} should be one of the types contained in
3483 For image types whose support libraries are statically linked, this
3484 function always returns @code{t}; for other image types, it returns
3485 @code{t} if the dynamic library could be loaded, @code{nil} otherwise.
3489 * Image Descriptors:: How to specify an image for use in @code{:display}.
3490 * XBM Images:: Special features for XBM format.
3491 * XPM Images:: Special features for XPM format.
3492 * GIF Images:: Special features for GIF format.
3493 * Postscript Images:: Special features for Postscript format.
3494 * Other Image Types:: Various other formats are supported.
3495 * Defining Images:: Convenient ways to define an image for later use.
3496 * Showing Images:: Convenient ways to display an image once it is defined.
3497 * Image Cache:: Internal mechanisms of image display.
3500 @node Image Descriptors
3501 @subsection Image Descriptors
3502 @cindex image descriptor
3504 An image description is a list of the form @code{(image
3505 . @var{props})}, where @var{props} is a property list containing
3506 alternating keyword symbols (symbols whose names start with a colon) and
3507 their values. You can use any Lisp object as a property, but the only
3508 properties that have any special meaning are certain symbols, all of
3511 Every image descriptor must contain the property @code{:type
3512 @var{type}} to specify the format of the image. The value of @var{type}
3513 should be an image type symbol; for example, @code{xpm} for an image in
3516 Here is a list of other properties that are meaningful for all image
3520 @item :file @var{file}
3521 The @code{:file} property says to load the image from file
3522 @var{file}. If @var{file} is not an absolute file name, it is expanded
3523 in @code{data-directory}.
3525 @item :data @var{data}
3526 The @code{:data} property says the actual contents of the image.
3527 Each image must use either @code{:data} or @code{:file}, but not both.
3528 For most image types, the value of the @code{:data} property should be a
3529 string containing the image data; we recommend using a unibyte string.
3531 Before using @code{:data}, look for further information in the section
3532 below describing the specific image format. For some image types,
3533 @code{:data} may not be supported; for some, it allows other data types;
3534 for some, @code{:data} alone is not enough, so you need to use other
3535 image properties along with @code{:data}.
3537 @item :margin @var{margin}
3538 The @code{:margin} property specifies how many pixels to add as an
3539 extra margin around the image. The value, @var{margin}, must be a
3540 non-negative number, or a pair @code{(@var{x} . @var{y})} of such
3541 numbers. If it is a pair, @var{x} specifies how many pixels to add
3542 horizontally, and @var{y} specifies how many pixels to add vertically.
3543 If @code{:margin} is not specified, the default is zero.
3545 @item :ascent @var{ascent}
3546 The @code{:ascent} property specifies the amount of the image's
3547 height to use for its ascent---that is, the part above the baseline.
3548 The value, @var{ascent}, must be a number in the range 0 to 100, or
3549 the symbol @code{center}.
3551 If @var{ascent} is a number, that percentage of the image's height is
3552 used for its ascent.
3554 If @var{ascent} is @code{center}, the image is vertically centered
3555 around a centerline which would be the vertical centerline of text drawn
3556 at the position of the image, in the manner specified by the text
3557 properties and overlays that apply to the image.
3559 If this property is omitted, it defaults to 50.
3561 @item :relief @var{relief}
3562 The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle
3563 around the image. The value, @var{relief}, specifies the width of the
3564 shadow lines, in pixels. If @var{relief} is negative, shadows are drawn
3565 so that the image appears as a pressed button; otherwise, it appears as
3566 an unpressed button.
3568 @item :conversion @var{algorithm}
3569 The @code{:conversion} property, if non-@code{nil}, specifies a
3570 conversion algorithm that should be applied to the image before it is
3571 displayed; the value, @var{algorithm}, specifies which algorithm.
3576 Specifies the Laplace edge detection algorithm, which blurs out small
3577 differences in color while highlighting larger differences. People
3578 sometimes consider this useful for displaying the image for a
3579 ``disabled'' button.
3581 @item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
3582 Specifies a general edge-detection algorithm. @var{matrix} must be
3583 either a nine-element list or a nine-element vector of numbers. A pixel
3584 at position @math{x/y} in the transformed image is computed from
3585 original pixels around that position. @var{matrix} specifies, for each
3586 pixel in the neighborhood of @math{x/y}, a factor with which that pixel
3587 will influence the transformed pixel; element @math{0} specifies the
3588 factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for
3589 the pixel at @math{x/y-1} etc., as shown below:
3592 $$\pmatrix{x-1/y-1 & x/y-1 & x+1/y-1 \cr
3593 x-1/y & x/y & x+1/y \cr
3594 x-1/y+1& x/y+1 & x+1/y+1 \cr}$$
3599 (x-1/y-1 x/y-1 x+1/y-1
3601 x-1/y+1 x/y+1 x+1/y+1)
3605 The resulting pixel is computed from the color intensity of the color
3606 resulting from summing up the RGB values of surrounding pixels,
3607 multiplied by the specified factors, and dividing that sum by the sum
3608 of the factors' absolute values.
3610 Laplace edge-detection currently uses a matrix of
3613 $$\pmatrix{1 & 0 & 0 \cr
3626 Emboss edge-detection uses a matrix of
3629 $$\pmatrix{ 2 & -1 & 0 \cr
3643 Specifies transforming the image so that it looks ``disabled''.
3646 @item :mask @var{mask}
3647 If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build
3648 a clipping mask for the image, so that the background of a frame is
3649 visible behind the image. If @var{bg} is not specified, or if @var{bg}
3650 is @code{t}, determine the background color of the image by looking at
3651 the four corners of the image, assuming the most frequently occurring
3652 color from the corners is the background color of the image. Otherwise,
3653 @var{bg} must be a list @code{(@var{red} @var{green} @var{blue})}
3654 specifying the color to assume for the background of the image.
3656 If @var{mask} is @code{nil}, remove a mask from the image, if it has
3657 one. Images in some formats include a mask which can be removed by
3658 specifying @code{:mask nil}.
3660 @item :pointer @var{shape}
3661 This specifies the pointer shape when the mouse pointer is over this
3662 image. @xref{Pointer Shape}, for available pointer shapes.
3664 @item :map @var{map}
3665 This associates an image map of @dfn{hot spots} with this image.
3667 An image map is an alist where each element has the format
3668 @code{(@var{area} @var{id} @var{plist})}. An @var{area} is specified
3669 as either a rectangle, a circle, or a polygon.
3671 A rectangle is a cons
3672 @code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))}
3673 which specifies the pixel coordinates of the upper left and bottom right
3674 corners of the rectangle area.
3677 @code{(circle . ((@var{x0} . @var{y0}) . @var{r}))}
3678 which specifies the center and the radius of the circle; @var{r} may
3679 be a float or integer.
3682 @code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])}
3683 where each pair in the vector describes one corner in the polygon.
3685 When the mouse pointer is above a hot-spot area of an image, the
3686 @var{plist} of that hot-spot is consulted; if it contains a @code{help-echo}
3687 property it defines a tool-tip for the hot-spot, and if it contains
3688 a @code{pointer} property, it defines the shape of the mouse cursor when
3689 it is over the hot-spot.
3690 @xref{Pointer Shape}, for available pointer shapes.
3692 When you click the mouse when the mouse pointer is over a hot-spot, an
3693 event is composed by combining the @var{id} of the hot-spot with the
3694 mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's
3695 @var{id} is @code{area4}.
3698 @defun image-mask-p spec &optional frame
3699 @tindex image-mask-p
3700 This function returns @code{t} if image @var{spec} has a mask bitmap.
3701 @var{frame} is the frame on which the image will be displayed.
3702 @var{frame} @code{nil} or omitted means to use the selected frame
3703 (@pxref{Input Focus}).
3707 @subsection XBM Images
3710 To use XBM format, specify @code{xbm} as the image type. This image
3711 format doesn't require an external library, so images of this type are
3714 Additional image properties supported for the @code{xbm} image type are:
3717 @item :foreground @var{foreground}
3718 The value, @var{foreground}, should be a string specifying the image
3719 foreground color, or @code{nil} for the default color. This color is
3720 used for each pixel in the XBM that is 1. The default is the frame's
3723 @item :background @var{background}
3724 The value, @var{background}, should be a string specifying the image
3725 background color, or @code{nil} for the default color. This color is
3726 used for each pixel in the XBM that is 0. The default is the frame's
3730 If you specify an XBM image using data within Emacs instead of an
3731 external file, use the following three properties:
3734 @item :data @var{data}
3735 The value, @var{data}, specifies the contents of the image.
3736 There are three formats you can use for @var{data}:
3740 A vector of strings or bool-vectors, each specifying one line of the
3741 image. Do specify @code{:height} and @code{:width}.
3744 A string containing the same byte sequence as an XBM file would contain.
3745 You must not specify @code{:height} and @code{:width} in this case,
3746 because omitting them is what indicates the data has the format of an
3747 XBM file. The file contents specify the height and width of the image.
3750 A string or a bool-vector containing the bits of the image (plus perhaps
3751 some extra bits at the end that will not be used). It should contain at
3752 least @var{width} * @code{height} bits. In this case, you must specify
3753 @code{:height} and @code{:width}, both to indicate that the string
3754 contains just the bits rather than a whole XBM file, and to specify the
3758 @item :width @var{width}
3759 The value, @var{width}, specifies the width of the image, in pixels.
3761 @item :height @var{height}
3762 The value, @var{height}, specifies the height of the image, in pixels.
3766 @subsection XPM Images
3769 To use XPM format, specify @code{xpm} as the image type. The
3770 additional image property @code{:color-symbols} is also meaningful with
3771 the @code{xpm} image type:
3774 @item :color-symbols @var{symbols}
3775 The value, @var{symbols}, should be an alist whose elements have the
3776 form @code{(@var{name} . @var{color})}. In each element, @var{name} is
3777 the name of a color as it appears in the image file, and @var{color}
3778 specifies the actual color to use for displaying that name.
3782 @subsection GIF Images
3785 For GIF images, specify image type @code{gif}.
3788 @item :index @var{index}
3789 You can use @code{:index} to specify one image from a GIF file that
3790 contains more than one image. This property specifies use of image
3791 number @var{index} from the file. If the GIF file doesn't contain an
3792 image with index @var{index}, the image displays as a hollow box.
3796 This could be used to implement limited support for animated GIFs.
3797 For example, the following function displays a multi-image GIF file
3798 at point-min in the current buffer, switching between sub-images
3801 (defun show-anim (file max)
3802 "Display multi-image GIF file FILE which contains MAX subimages."
3803 (display-anim (current-buffer) file 0 max t))
3805 (defun display-anim (buffer file idx max first-time)
3808 (let ((img (create-image file nil :image idx)))
3811 (goto-char (point-min))
3812 (unless first-time (delete-char 1))
3814 (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
3817 @node Postscript Images
3818 @subsection Postscript Images
3819 @cindex Postscript images
3821 To use Postscript for an image, specify image type @code{postscript}.
3822 This works only if you have Ghostscript installed. You must always use
3823 these three properties:
3826 @item :pt-width @var{width}
3827 The value, @var{width}, specifies the width of the image measured in
3828 points (1/72 inch). @var{width} must be an integer.
3830 @item :pt-height @var{height}
3831 The value, @var{height}, specifies the height of the image in points
3832 (1/72 inch). @var{height} must be an integer.
3834 @item :bounding-box @var{box}
3835 The value, @var{box}, must be a list or vector of four integers, which
3836 specifying the bounding box of the Postscript image, analogous to the
3837 @samp{BoundingBox} comment found in Postscript files.
3840 %%BoundingBox: 22 171 567 738
3844 Displaying Postscript images from Lisp data is not currently
3845 implemented, but it may be implemented by the time you read this.
3846 See the @file{etc/NEWS} file to make sure.
3848 @node Other Image Types
3849 @subsection Other Image Types
3852 For PBM images, specify image type @code{pbm}. Color, gray-scale and
3853 monochromatic images are supported. For mono PBM images, two additional
3854 image properties are supported.
3857 @item :foreground @var{foreground}
3858 The value, @var{foreground}, should be a string specifying the image
3859 foreground color, or @code{nil} for the default color. This color is
3860 used for each pixel in the XBM that is 1. The default is the frame's
3863 @item :background @var{background}
3864 The value, @var{background}, should be a string specifying the image
3865 background color, or @code{nil} for the default color. This color is
3866 used for each pixel in the XBM that is 0. The default is the frame's
3870 For JPEG images, specify image type @code{jpeg}.
3872 For TIFF images, specify image type @code{tiff}.
3874 For PNG images, specify image type @code{png}.
3876 @node Defining Images
3877 @subsection Defining Images
3879 The functions @code{create-image}, @code{defimage} and
3880 @code{find-image} provide convenient ways to create image descriptors.
3882 @defun create-image file-or-data &optional type data-p &rest props
3883 @tindex create-image
3884 This function creates and returns an image descriptor which uses the
3885 data in @var{file-or-data}. @var{file-or-data} can be a file name or
3886 a string containing the image data; @var{data-p} should be @code{nil}
3887 for the former case, non-@code{nil} for the latter case.
3889 The optional argument @var{type} is a symbol specifying the image type.
3890 If @var{type} is omitted or @code{nil}, @code{create-image} tries to
3891 determine the image type from the file's first few bytes, or else
3892 from the file's name.
3894 The remaining arguments, @var{props}, specify additional image
3895 properties---for example,
3898 (create-image "foo.xpm" 'xpm nil :heuristic-mask t)
3901 The function returns @code{nil} if images of this type are not
3902 supported. Otherwise it returns an image descriptor.
3905 @defmac defimage symbol specs &optional doc
3907 This macro defines @var{symbol} as an image name. The arguments
3908 @var{specs} is a list which specifies how to display the image.
3909 The third argument, @var{doc}, is an optional documentation string.
3911 Each argument in @var{specs} has the form of a property list, and each
3912 one should specify at least the @code{:type} property and either the
3913 @code{:file} or the @code{:data} property. The value of @code{:type}
3914 should be a symbol specifying the image type, the value of
3915 @code{:file} is the file to load the image from, and the value of
3916 @code{:data} is a string containing the actual image data. Here is an
3920 (defimage test-image
3921 ((:type xpm :file "~/test1.xpm")
3922 (:type xbm :file "~/test1.xbm")))
3925 @code{defimage} tests each argument, one by one, to see if it is
3926 usable---that is, if the type is supported and the file exists. The
3927 first usable argument is used to make an image descriptor which is
3928 stored in @var{symbol}.
3930 If none of the alternatives will work, then @var{symbol} is defined
3934 @defun find-image specs
3936 This function provides a convenient way to find an image satisfying one
3937 of a list of image specifications @var{specs}.
3939 Each specification in @var{specs} is a property list with contents
3940 depending on image type. All specifications must at least contain the
3941 properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
3942 or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
3943 the image type, e.g.@: @code{xbm}, @var{file} is the file to load the
3944 image from, and @var{data} is a string containing the actual image data.
3945 The first specification in the list whose @var{type} is supported, and
3946 @var{file} exists, is used to construct the image specification to be
3947 returned. If no specification is satisfied, @code{nil} is returned.
3949 The image is looked for in @code{image-load-path}.
3952 @defvar image-load-path
3953 @tindex image-load-path
3954 This variable's value is a list of locations in which to search for
3955 image files. If an element is a string, it is taken to be the name of
3956 a directory to search. If an element is a variable symbol, the value
3957 of that variable is used as a list of directories to search.
3959 The default is to search in the @file{images} subdirectory of the
3960 directory specified by @code{data-directory}, then the directory
3961 specified by @code{data-directory}, and finally in the directories in
3962 @code{load-path}. Subdirectories are not automatically included in
3963 the search, so if you put an image file in a subdirectory, you have to
3964 supply the subdirectory name explicitly. For example, to find the
3965 image @file{images/foo/bar.xpm} within @code{data-directory} you
3966 should specify the image as follows:
3969 (defimage foo-image '((:type xpm :file "foo/bar.xpm")))
3973 @node Showing Images
3974 @subsection Showing Images
3976 You can use an image descriptor by setting up the @code{display}
3977 property yourself, but it is easier to use the functions in this
3980 @defun insert-image image &optional string area slice
3981 This function inserts @var{image} in the current buffer at point. The
3982 value @var{image} should be an image descriptor; it could be a value
3983 returned by @code{create-image}, or the value of a symbol defined with
3984 @code{defimage}. The argument @var{string} specifies the text to put
3985 in the buffer to hold the image. If it is omitted or @code{nil},
3986 @code{insert-image} uses @code{" "} by default.
3988 The argument @var{area} specifies whether to put the image in a margin.
3989 If it is @code{left-margin}, the image appears in the left margin;
3990 @code{right-margin} specifies the right margin. If @var{area} is
3991 @code{nil} or omitted, the image is displayed at point within the
3994 The argument @var{slice} specifies a slice of the image to insert. If
3995 @var{slice} is @code{nil} or omitted the whole image is inserted.
3996 Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width}
3997 @var{height})} which specifies the @var{x} and @var{y} positions and
3998 @var{width} and @var{height} of the image area to insert. Integer
3999 values are in units of pixels. A floating point number in the range
4000 0.0--1.0 stands for that fraction of the width or height of the entire
4003 Internally, this function inserts @var{string} in the buffer, and gives
4004 it a @code{display} property which specifies @var{image}. @xref{Display
4008 @defun insert-sliced-image image &optional string area rows cols
4009 This function inserts @var{image} in the current buffer at point, like
4010 @code{insert-image}, but splits the image into @var{rows}x@var{cols}
4011 equally sized slices.
4014 @defun put-image image pos &optional string area
4015 This function puts image @var{image} in front of @var{pos} in the
4016 current buffer. The argument @var{pos} should be an integer or a
4017 marker. It specifies the buffer position where the image should appear.
4018 The argument @var{string} specifies the text that should hold the image
4019 as an alternative to the default.
4021 The argument @var{image} must be an image descriptor, perhaps returned
4022 by @code{create-image} or stored by @code{defimage}.
4024 The argument @var{area} specifies whether to put the image in a margin.
4025 If it is @code{left-margin}, the image appears in the left margin;
4026 @code{right-margin} specifies the right margin. If @var{area} is
4027 @code{nil} or omitted, the image is displayed at point within the
4030 Internally, this function creates an overlay, and gives it a
4031 @code{before-string} property containing text that has a @code{display}
4032 property whose value is the image. (Whew!)
4035 @defun remove-images start end &optional buffer
4036 This function removes images in @var{buffer} between positions
4037 @var{start} and @var{end}. If @var{buffer} is omitted or @code{nil},
4038 images are removed from the current buffer.
4040 This removes only images that were put into @var{buffer} the way
4041 @code{put-image} does it, not images that were inserted with
4042 @code{insert-image} or in other ways.
4045 @defun image-size spec &optional pixels frame
4047 This function returns the size of an image as a pair
4048 @w{@code{(@var{width} . @var{height})}}. @var{spec} is an image
4049 specification. @var{pixels} non-@code{nil} means return sizes
4050 measured in pixels, otherwise return sizes measured in canonical
4051 character units (fractions of the width/height of the frame's default
4052 font). @var{frame} is the frame on which the image will be displayed.
4053 @var{frame} null or omitted means use the selected frame (@pxref{Input
4058 @subsection Image Cache
4060 Emacs stores images in an image cache when it displays them, so it can
4061 display them again more efficiently. It removes an image from the cache
4062 when it hasn't been displayed for a specified period of time.
4064 When an image is looked up in the cache, its specification is compared
4065 with cached image specifications using @code{equal}. This means that
4066 all images with equal specifications share the same image in the cache.
4068 @defvar image-cache-eviction-delay
4069 @tindex image-cache-eviction-delay
4070 This variable specifies the number of seconds an image can remain in the
4071 cache without being displayed. When an image is not displayed for this
4072 length of time, Emacs removes it from the image cache.
4074 If the value is @code{nil}, Emacs does not remove images from the cache
4075 except when you explicitly clear it. This mode can be useful for
4079 @defun clear-image-cache &optional frame
4080 @tindex clear-image-cache
4081 This function clears the image cache. If @var{frame} is non-@code{nil},
4082 only the cache for that frame is cleared. Otherwise all frames' caches
4089 @cindex buttons in buffers
4090 @cindex clickable buttons in buffers
4092 The @emph{button} package defines functions for inserting and
4093 manipulating clickable (with the mouse, or via keyboard commands)
4094 buttons in Emacs buffers, such as might be used for help hyper-links,
4095 etc. Emacs uses buttons for the hyper-links in help text and the like.
4097 A button is essentially a set of properties attached (via text
4098 properties or overlays) to a region of text in an Emacs buffer. These
4099 properties are called @dfn{button properties}.
4101 One of the these properties (@code{action}) is a function, which will
4102 be called when the user invokes it using the keyboard or the mouse.
4103 The invoked function may then examine the button and use its other
4104 properties as desired.
4106 In some ways the Emacs button package duplicates functionality offered
4107 by the widget package (@pxref{Top, , Introduction, widget, The Emacs
4108 Widget Library}), but the button package has the advantage that it is
4109 much faster, much smaller, and much simpler to use (for elisp
4110 programmers---for users, the result is about the same). The extra
4111 speed and space savings are useful mainly if you need to create many
4112 buttons in a buffer (for instance an @code{*Apropos*} buffer uses
4113 buttons to make entries clickable, and may contain many thousands of
4117 * Button Properties:: Button properties with special meanings.
4118 * Button Types:: Defining common properties for classes of buttons.
4119 * Making Buttons:: Adding buttons to Emacs buffers.
4120 * Manipulating Buttons:: Getting and setting properties of buttons.
4121 * Button Buffer Commands:: Buffer-wide commands and bindings for buttons.
4124 @node Button Properties
4125 @subsection Button Properties
4126 @cindex button properties
4128 Buttons have an associated list of properties defining their
4129 appearance and behavior, and other arbitrary properties may be used
4130 for application specific purposes. Some properties that have special
4131 meaning to the button package include:
4135 @kindex action @r{(button property)}
4136 The function to call when the user invokes the button, which is passed
4137 the single argument @var{button}. By default this is @code{ignore},
4141 @kindex mouse-action @r{(button property)}
4142 This is similar to @code{action}, and when present, will be used
4143 instead of @code{action} for button invocations resulting from
4144 mouse-clicks (instead of the user hitting @key{RET}). If not
4145 present, mouse-clicks use @code{action} instead.
4148 @kindex face @r{(button property)}
4149 This is an Emacs face controlling how buttons of this type are
4150 displayed; by default this is the @code{button} face.
4153 @kindex mouse-face @r{(button property)}
4154 This is an additional face which controls appearance during
4155 mouse-overs (merged with the usual button face); by default this is
4156 the usual Emacs @code{highlight} face.
4159 @kindex keymap @r{(button property)}
4160 The button's keymap, defining bindings active within the button
4161 region. By default this is the usual button region keymap, stored
4162 in the variable @code{button-map}, which defines @key{RET} and
4163 @key{mouse-2} to invoke the button.
4166 @kindex type @r{(button property)}
4167 The button-type of the button. When creating a button, this is
4168 usually specified using the @code{:type} keyword argument.
4169 @xref{Button Types}.
4172 @kindex help-index @r{(button property)}
4173 A string displayed by the Emacs tool-tip help system; by default,
4174 @code{"mouse-2, RET: Push this button"}.
4177 @kindex follow-link @r{(button property)}
4178 The follow-link property, defining how a @key{Mouse-1} click behaves
4179 on this button, @xref{Links and Mouse-1}.
4182 @kindex button @r{(button property)}
4183 All buttons have a non-@code{nil} @code{button} property, which may be useful
4184 in finding regions of text that comprise buttons (which is what the
4185 standard button functions do).
4188 There are other properties defined for the regions of text in a
4189 button, but these are not generally interesting for typical uses.
4192 @subsection Button Types
4193 @cindex button types
4195 Every button has a button @emph{type}, which defines default values
4196 for the button's properties. Button types are arranged in a
4197 hierarchy, with specialized types inheriting from more general types,
4198 so that it's easy to define special-purpose types of buttons for
4201 @defun define-button-type name &rest properties
4202 @tindex define-button-type
4203 Define a `button type' called @var{name}. The remaining arguments
4204 form a sequence of @var{property value} pairs, specifying default
4205 property values for buttons with this type (a button's type may be set
4206 by giving it a @code{type} property when creating the button, using
4207 the @code{:type} keyword argument).
4209 In addition, the keyword argument @code{:supertype} may be used to
4210 specify a button-type from which @var{name} inherits its default
4211 property values. Note that this inheritance happens only when
4212 @var{name} is defined; subsequent changes to a supertype are not
4213 reflected in its subtypes.
4216 Using @code{define-button-type} to define default properties for
4217 buttons is not necessary---buttons without any specified type use the
4218 built-in button-type @code{button}---but it is encouraged, since
4219 doing so usually makes the resulting code clearer and more efficient.
4221 @node Making Buttons
4222 @subsection Making Buttons
4223 @cindex making buttons
4225 Buttons are associated with a region of text, using an overlay or
4226 text properties to hold button-specific information, all of which are
4227 initialized from the button's type (which defaults to the built-in
4228 button type @code{button}). Like all Emacs text, the appearance of
4229 the button is governed by the @code{face} property; by default (via
4230 the @code{face} property inherited from the @code{button} button-type)
4231 this is a simple underline, like a typical web-page link.
4233 For convenience, there are two sorts of button-creation functions,
4234 those that add button properties to an existing region of a buffer,
4235 called @code{make-...button}, and those also insert the button text,
4236 called @code{insert-...button}.
4238 The button-creation functions all take the @code{&rest} argument
4239 @var{properties}, which should be a sequence of @var{property value}
4240 pairs, specifying properties to add to the button; see @ref{Button
4241 Properties}. In addition, the keyword argument @code{:type} may be
4242 used to specify a button-type from which to inherit other properties;
4243 see @ref{Button Types}. Any properties not explicitly specified
4244 during creation will be inherited from the button's type (if the type
4245 defines such a property).
4247 The following functions add a button using an overlay
4248 (@pxref{Overlays}) to hold the button properties:
4250 @defun make-button beg end &rest properties
4252 This makes a button from @var{beg} to @var{end} in the
4253 current buffer, and returns it.
4256 @defun insert-button label &rest properties
4257 @tindex insert-button
4258 This insert a button with the label @var{label} at point,
4262 The following functions are similar, but use Emacs text properties
4263 (@pxref{Text Properties}) to hold the button properties, making the
4264 button actually part of the text instead of being a property of the
4265 buffer. Buttons using text properties do not create markers into the
4266 buffer, which is important for speed when you use extremely large
4267 numbers of buttons. Both functions return the position of the start
4270 @defun make-text-button beg end &rest properties
4271 @tindex make-text-button
4272 This makes a button from @var{beg} to @var{end} in the current buffer, using
4276 @defun insert-text-button label &rest properties
4277 @tindex insert-text-button
4278 This inserts a button with the label @var{label} at point, using text
4282 @node Manipulating Buttons
4283 @subsection Manipulating Buttons
4284 @cindex manipulating buttons
4286 These are functions for getting and setting properties of buttons.
4287 Often these are used by a button's invocation function to determine
4290 Where a @var{button} parameter is specified, it means an object
4291 referring to a specific button, either an overlay (for overlay
4292 buttons), or a buffer-position or marker (for text property buttons).
4293 Such an object is passed as the first argument to a button's
4294 invocation function when it is invoked.
4296 @defun button-start button
4297 @tindex button-start
4298 Return the position at which @var{button} starts.
4301 @defun button-end button
4303 Return the position at which @var{button} ends.
4306 @defun button-get button prop
4308 Get the property of button @var{button} named @var{prop}.
4311 @defun button-put button prop val
4313 Set @var{button}'s @var{prop} property to @var{val}.
4316 @defun button-activate button &optional use-mouse-action
4317 @tindex button-activate
4318 Call @var{button}'s @code{action} property (i.e., invoke it). If
4319 @var{use-mouse-action} is non-@code{nil}, try to invoke the button's
4320 @code{mouse-action} property instead of @code{action}; if the button
4321 has no @code{mouse-action} property, use @code{action} as normal.
4324 @defun button-label button
4325 @tindex button-label
4326 Return @var{button}'s text label.
4329 @defun button-type button
4331 Return @var{button}'s button-type.
4334 @defun button-has-type-p button type
4335 @tindex button-has-type-p
4336 Return @code{t} if @var{button} has button-type @var{type}, or one of
4337 @var{type}'s subtypes.
4340 @defun button-at pos
4342 Return the button at position @var{pos} in the current buffer, or @code{nil}.
4345 @defun button-type-put type prop val
4346 @tindex button-type-put
4347 Set the button-type @var{type}'s @var{prop} property to @var{val}.
4350 @defun button-type-get type prop
4351 @tindex button-type-get
4352 Get the property of button-type @var{type} named @var{prop}.
4355 @defun button-type-subtype-p type supertype
4356 @tindex button-type-subtype-p
4357 Return @code{t} if button-type @var{type} is a subtype of @var{supertype}.
4360 @node Button Buffer Commands
4361 @subsection Button Buffer Commands
4362 @cindex button buffer commands
4364 These are commands and functions for locating and operating on
4365 buttons in an Emacs buffer.
4367 @code{push-button} is the command that a user uses to actually `push'
4368 a button, and is bound by default in the button itself to @key{RET}
4369 and to @key{mouse-2} using a region-specific keymap. Commands
4370 that are useful outside the buttons itself, such as
4371 @code{forward-button} and @code{backward-button} are additionally
4372 available in the keymap stored in @code{button-buffer-map}; a mode
4373 which uses buttons may want to use @code{button-buffer-map} as a
4374 parent keymap for its keymap.
4376 If the button has a non-@code{nil} @code{follow-link} property, and
4377 @var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click
4378 will also activate the @code{push-button} command.
4379 @xref{Links and Mouse-1}.
4381 @deffn Command push-button &optional pos use-mouse-action
4383 Perform the action specified by a button at location @var{pos}.
4384 @var{pos} may be either a buffer position or a mouse-event. If
4385 @var{use-mouse-action} is non-@code{nil}, or @var{pos} is a
4386 mouse-event (@pxref{Mouse Events}), try to invoke the button's
4387 @code{mouse-action} property instead of @code{action}; if the button
4388 has no @code{mouse-action} property, use @code{action} as normal.
4389 @var{pos} defaults to point, except when @code{push-button} is invoked
4390 interactively as the result of a mouse-event, in which case, the mouse
4391 event's position is used. If there's no button at @var{pos}, do
4392 nothing and return @code{nil}, otherwise return @code{t}.
4395 @deffn Command forward-button n &optional wrap display-message
4396 @tindex forward-button
4397 Move to the @var{n}th next button, or @var{n}th previous button if
4398 @var{n} is negative. If @var{n} is zero, move to the start of any
4399 button at point. If @var{wrap} is non-@code{nil}, moving past either
4400 end of the buffer continues from the other end. If
4401 @var{display-message} is non-@code{nil}, the button's help-echo string
4402 is displayed. Any button with a non-@code{nil} @code{skip} property
4403 is skipped over. Returns the button found.
4406 @deffn Command backward-button n &optional wrap display-message
4407 @tindex backward-button
4408 Move to the @var{n}th previous button, or @var{n}th next button if
4409 @var{n} is negative. If @var{n} is zero, move to the start of any
4410 button at point. If @var{wrap} is non-@code{nil}, moving past either
4411 end of the buffer continues from the other end. If
4412 @var{display-message} is non-@code{nil}, the button's help-echo string
4413 is displayed. Any button with a non-@code{nil} @code{skip} property
4414 is skipped over. Returns the button found.
4417 @defun next-button pos &optional count-current
4419 Return the next button after position @var{pos} in the current buffer.
4420 If @var{count-current} is non-@code{nil}, count any button at
4421 @var{pos} in the search, instead of starting at the next button.
4424 @defun previous-button pos &optional count-current
4425 @tindex previous-button
4426 Return the @var{n}th button before position @var{pos} in the current
4427 buffer. If @var{count-current} is non-@code{nil}, count any button at
4428 @var{pos} in the search, instead of starting at the next button.
4432 @section Blinking Parentheses
4433 @cindex parenthesis matching
4435 @cindex balancing parentheses
4436 @cindex close parenthesis
4438 This section describes the mechanism by which Emacs shows a matching
4439 open parenthesis when the user inserts a close parenthesis.
4441 @defvar blink-paren-function
4442 The value of this variable should be a function (of no arguments) to
4443 be called whenever a character with close parenthesis syntax is inserted.
4444 The value of @code{blink-paren-function} may be @code{nil}, in which
4445 case nothing is done.
4448 @defopt blink-matching-paren
4449 If this variable is @code{nil}, then @code{blink-matching-open} does
4453 @defopt blink-matching-paren-distance
4454 This variable specifies the maximum distance to scan for a matching
4455 parenthesis before giving up.
4458 @defopt blink-matching-delay
4459 This variable specifies the number of seconds for the cursor to remain
4460 at the matching parenthesis. A fraction of a second often gives
4461 good results, but the default is 1, which works on all systems.
4464 @deffn Command blink-matching-open
4465 This function is the default value of @code{blink-paren-function}. It
4466 assumes that point follows a character with close parenthesis syntax and
4467 moves the cursor momentarily to the matching opening character. If that
4468 character is not already on the screen, it displays the character's
4469 context in the echo area. To avoid long delays, this function does not
4470 search farther than @code{blink-matching-paren-distance} characters.
4472 Here is an example of calling this function explicitly.
4476 (defun interactive-blink-matching-open ()
4477 @c Do not break this line! -- rms.
4478 @c The first line of a doc string
4479 @c must stand alone.
4480 "Indicate momentarily the start of sexp before point."
4484 (let ((blink-matching-paren-distance
4486 (blink-matching-paren t))
4487 (blink-matching-open)))
4493 @section Usual Display Conventions
4495 The usual display conventions define how to display each character
4496 code. You can override these conventions by setting up a display table
4497 (@pxref{Display Tables}). Here are the usual display conventions:
4501 Character codes 32 through 126 map to glyph codes 32 through 126.
4502 Normally this means they display as themselves.
4505 Character code 9 is a horizontal tab. It displays as whitespace
4506 up to a position determined by @code{tab-width}.
4509 Character code 10 is a newline.
4512 All other codes in the range 0 through 31, and code 127, display in one
4513 of two ways according to the value of @code{ctl-arrow}. If it is
4514 non-@code{nil}, these codes map to sequences of two glyphs, where the
4515 first glyph is the @acronym{ASCII} code for @samp{^}. (A display table can
4516 specify a glyph to use instead of @samp{^}.) Otherwise, these codes map
4517 just like the codes in the range 128 to 255.
4519 On MS-DOS terminals, Emacs arranges by default for the character code
4520 127 to be mapped to the glyph code 127, which normally displays as an
4521 empty polygon. This glyph is used to display non-@acronym{ASCII} characters
4522 that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,,
4523 emacs, The GNU Emacs Manual}.
4526 Character codes 128 through 255 map to sequences of four glyphs, where
4527 the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are
4528 digit characters representing the character code in octal. (A display
4529 table can specify a glyph to use instead of @samp{\}.)
4532 Multibyte character codes above 256 are displayed as themselves, or as a
4533 question mark or empty box if the terminal cannot display that
4537 The usual display conventions apply even when there is a display
4538 table, for any character whose entry in the active display table is
4539 @code{nil}. Thus, when you set up a display table, you need only
4540 specify the characters for which you want special behavior.
4542 These display rules apply to carriage return (character code 13), when
4543 it appears in the buffer. But that character may not appear in the
4544 buffer where you expect it, if it was eliminated as part of end-of-line
4545 conversion (@pxref{Coding System Basics}).
4547 These variables affect the way certain characters are displayed on the
4548 screen. Since they change the number of columns the characters occupy,
4549 they also affect the indentation functions. These variables also affect
4550 how the mode line is displayed; if you want to force redisplay of the
4551 mode line using the new values, call the function
4552 @code{force-mode-line-update} (@pxref{Mode Line Format}).
4555 @cindex control characters in display
4556 This buffer-local variable controls how control characters are
4557 displayed. If it is non-@code{nil}, they are displayed as a caret
4558 followed by the character: @samp{^A}. If it is @code{nil}, they are
4559 displayed as a backslash followed by three octal digits: @samp{\001}.
4562 @c Following may have overfull hbox.
4563 @defvar default-ctl-arrow
4564 The value of this variable is the default value for @code{ctl-arrow} in
4565 buffers that do not override it. @xref{Default Value}.
4569 The value of this buffer-local variable is the spacing between tab
4570 stops used for displaying tab characters in Emacs buffers. The value
4571 is in units of columns, and the default is 8. Note that this feature
4572 is completely independent of the user-settable tab stops used by the
4573 command @code{tab-to-tab-stop}. @xref{Indent Tabs}.
4576 @defopt indicate-empty-lines
4577 @tindex indicate-empty-lines
4578 @cindex fringes, and empty line indication
4579 When this is non-@code{nil}, Emacs displays a special glyph in the
4580 fringe of each empty line at the end of the buffer, on terminals that
4581 support it (window systems). @xref{Fringes}.
4582 This variable is automatically buffer-local in every buffer.
4585 @defvar indicate-buffer-boundaries
4586 This buffer-local variable controls how the buffer boundaries and
4587 window scrolling are indicated in the window fringes.
4589 Emacs can indicate the buffer boundaries---that is, the first and last
4590 line in the buffer---with angle icons when they appear on the screen.
4591 In addition, Emacs can display an up-arrow in the fringe to show
4592 that there is text above the screen, and a down-arrow to show
4593 there is text below the screen.
4595 There are four kinds of basic values:
4599 Don't display the icons.
4601 Display them in the left fringe.
4603 Display them in the right fringe.
4604 @item @var{anything-else}
4605 Display the icon at the top of the window top in the left fringe, and other
4606 in the right fringe.
4609 If value is a cons @code{(@var{angles} . @var{arrows})}, @var{angles}
4610 controls the angle icons, and @var{arrows} controls the arrows. Both
4611 @var{angles} and @var{arrows} work according to the table above.
4612 Thus, @code{(t . right)} places the top angle icon in the left
4613 fringe, the bottom angle icon in the right fringe, and both arrows in
4617 @defvar default-indicate-buffer-boundaries
4618 The value of this variable is the default value for
4619 @code{indicate-buffer-boundaries} in buffers that do not override it.
4622 @node Display Tables
4623 @section Display Tables
4625 @cindex display table
4626 You can use the @dfn{display table} feature to control how all possible
4627 character codes display on the screen. This is useful for displaying
4628 European languages that have letters not in the @acronym{ASCII} character
4631 The display table maps each character code into a sequence of
4632 @dfn{glyphs}, each glyph being a graphic that takes up one character
4633 position on the screen. You can also define how to display each glyph
4634 on your terminal, using the @dfn{glyph table}.
4636 Display tables affect how the mode line is displayed; if you want to
4637 force redisplay of the mode line using a new display table, call
4638 @code{force-mode-line-update} (@pxref{Mode Line Format}).
4641 * Display Table Format:: What a display table consists of.
4642 * Active Display Table:: How Emacs selects a display table to use.
4643 * Glyphs:: How to define a glyph, and what glyphs mean.
4646 @node Display Table Format
4647 @subsection Display Table Format
4649 A display table is actually a char-table (@pxref{Char-Tables}) with
4650 @code{display-table} as its subtype.
4652 @defun make-display-table
4653 This creates and returns a display table. The table initially has
4654 @code{nil} in all elements.
4657 The ordinary elements of the display table are indexed by character
4658 codes; the element at index @var{c} says how to display the character
4659 code @var{c}. The value should be @code{nil} or a vector of glyph
4660 values (@pxref{Glyphs}). If an element is @code{nil}, it says to
4661 display that character according to the usual display conventions
4662 (@pxref{Usual Display}).
4664 If you use the display table to change the display of newline
4665 characters, the whole buffer will be displayed as one long ``line.''
4667 The display table also has six ``extra slots'' which serve special
4668 purposes. Here is a table of their meanings; @code{nil} in any slot
4669 means to use the default for that slot, as stated below.
4673 The glyph for the end of a truncated screen line (the default for this
4674 is @samp{$}). @xref{Glyphs}. On graphical terminals, Emacs uses
4675 arrows in the fringes to indicate truncation, so the display table has
4679 The glyph for the end of a continued line (the default is @samp{\}).
4680 On graphical terminals, Emacs uses curved arrows in the fringes to
4681 indicate continuation, so the display table has no effect.
4684 The glyph for indicating a character displayed as an octal character
4685 code (the default is @samp{\}).
4688 The glyph for indicating a control character (the default is @samp{^}).
4691 A vector of glyphs for indicating the presence of invisible lines (the
4692 default is @samp{...}). @xref{Selective Display}.
4695 The glyph used to draw the border between side-by-side windows (the
4696 default is @samp{|}). @xref{Splitting Windows}. This takes effect only
4697 when there are no scroll bars; if scroll bars are supported and in use,
4698 a scroll bar separates the two windows.
4701 For example, here is how to construct a display table that mimics the
4702 effect of setting @code{ctl-arrow} to a non-@code{nil} value:
4705 (setq disptab (make-display-table))
4708 (or (= i ?\t) (= i ?\n)
4709 (aset disptab i (vector ?^ (+ i 64))))
4711 (aset disptab 127 (vector ?^ ??)))
4714 @defun display-table-slot display-table slot
4715 This function returns the value of the extra slot @var{slot} of
4716 @var{display-table}. The argument @var{slot} may be a number from 0 to
4717 5 inclusive, or a slot name (symbol). Valid symbols are
4718 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
4719 @code{selective-display}, and @code{vertical-border}.
4722 @defun set-display-table-slot display-table slot value
4723 This function stores @var{value} in the extra slot @var{slot} of
4724 @var{display-table}. The argument @var{slot} may be a number from 0 to
4725 5 inclusive, or a slot name (symbol). Valid symbols are
4726 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
4727 @code{selective-display}, and @code{vertical-border}.
4730 @defun describe-display-table display-table
4731 @tindex describe-display-table
4732 This function displays a description of the display table
4733 @var{display-table} in a help buffer.
4736 @deffn Command describe-current-display-table
4737 @tindex describe-current-display-table
4738 This command displays a description of the current display table in a
4742 @node Active Display Table
4743 @subsection Active Display Table
4744 @cindex active display table
4746 Each window can specify a display table, and so can each buffer. When
4747 a buffer @var{b} is displayed in window @var{w}, display uses the
4748 display table for window @var{w} if it has one; otherwise, the display
4749 table for buffer @var{b} if it has one; otherwise, the standard display
4750 table if any. The display table chosen is called the @dfn{active}
4753 @defun window-display-table &optional window
4754 This function returns @var{window}'s display table, or @code{nil}
4755 if @var{window} does not have an assigned display table. The default
4756 for @var{window} is the selected window.
4759 @defun set-window-display-table window table
4760 This function sets the display table of @var{window} to @var{table}.
4761 The argument @var{table} should be either a display table or
4765 @defvar buffer-display-table
4766 This variable is automatically buffer-local in all buffers; its value in
4767 a particular buffer specifies the display table for that buffer. If it
4768 is @code{nil}, that means the buffer does not have an assigned display
4772 @defvar standard-display-table
4773 This variable's value is the default display table, used whenever a
4774 window has no display table and neither does the buffer displayed in
4775 that window. This variable is @code{nil} by default.
4778 If there is no display table to use for a particular window---that is,
4779 if the window specifies none, its buffer specifies none, and
4780 @code{standard-display-table} is @code{nil}---then Emacs uses the usual
4781 display conventions for all character codes in that window. @xref{Usual
4784 A number of functions for changing the standard display table
4785 are defined in the library @file{disp-table}.
4791 A @dfn{glyph} is a generalization of a character; it stands for an
4792 image that takes up a single character position on the screen. Glyphs
4793 are represented in Lisp as integers, just as characters are. Normally
4794 Emacs finds glyphs in the display table (@pxref{Display Tables}).
4796 A glyph can be @dfn{simple} or it can be defined by the @dfn{glyph
4797 table}. A simple glyph is just a way of specifying a character and a
4798 face to output it in. The glyph code for a simple glyph, mod 524288,
4799 is the character to output, and the glyph code divided by 524288
4800 specifies the face number (@pxref{Face Functions}) to use while
4801 outputting it. (524288 is
4810 On character terminals, you can set up a @dfn{glyph table} to define
4811 the meaning of glyph codes. The glyph codes is the value of the
4812 variable @code{glyph-table}.
4815 The value of this variable is the current glyph table. It should be a
4816 vector; the @var{g}th element defines glyph code @var{g}.
4818 If a glyph code is greater than or equal to the length of the glyph
4819 table, that code is automatically simple. If the value of
4820 @code{glyph-table} is @code{nil} instead of a vector, then all glyphs
4821 are simple. The glyph table is not used on graphical displays, only
4822 on character terminals. On graphical displays, all glyphs are simple.
4825 Here are the possible types of elements in the glyph table:
4829 Send the characters in @var{string} to the terminal to output
4830 this glyph. This alternative is available on character terminals,
4831 but not under a window system.
4834 Define this glyph code as an alias for glyph code @var{integer}. You
4835 can use an alias to specify a face code for the glyph and use a small
4839 This glyph is simple.
4842 @defun create-glyph string
4843 @tindex create-glyph
4844 This function returns a newly-allocated glyph code which is set up to
4845 display by sending @var{string} to the terminal.
4853 This section describes how to make Emacs ring the bell (or blink the
4854 screen) to attract the user's attention. Be conservative about how
4855 often you do this; frequent bells can become irritating. Also be
4856 careful not to use just beeping when signaling an error is more
4857 appropriate. (@xref{Errors}.)
4859 @defun ding &optional do-not-terminate
4860 @cindex keyboard macro termination
4861 This function beeps, or flashes the screen (see @code{visible-bell} below).
4862 It also terminates any keyboard macro currently executing unless
4863 @var{do-not-terminate} is non-@code{nil}.
4866 @defun beep &optional do-not-terminate
4867 This is a synonym for @code{ding}.
4870 @defopt visible-bell
4871 This variable determines whether Emacs should flash the screen to
4872 represent a bell. Non-@code{nil} means yes, @code{nil} means no. This
4873 is effective on a window system, and on a character-only terminal
4874 provided the terminal's Termcap entry defines the visible bell
4875 capability (@samp{vb}).
4878 @defvar ring-bell-function
4879 If this is non-@code{nil}, it specifies how Emacs should ``ring the
4880 bell.'' Its value should be a function of no arguments. If this is
4881 non-@code{nil}, it takes precedence over the @code{visible-bell}
4885 @node Window Systems
4886 @section Window Systems
4888 Emacs works with several window systems, most notably the X Window
4889 System. Both Emacs and X use the term ``window'', but use it
4890 differently. An Emacs frame is a single window as far as X is
4891 concerned; the individual Emacs windows are not known to X at all.
4893 @defvar window-system
4894 This variable tells Lisp programs what window system Emacs is running
4895 under. The possible values are
4899 @cindex X Window System
4900 Emacs is displaying using X.
4902 Emacs is displaying using MS-DOS.
4904 Emacs is displaying using Windows.
4906 Emacs is displaying using a Macintosh.
4908 Emacs is using a character-based terminal.
4912 @defvar window-setup-hook
4913 This variable is a normal hook which Emacs runs after handling the
4914 initialization files. Emacs runs this hook after it has completed
4915 loading your init file, the default initialization file (if
4916 any), and the terminal-specific Lisp code, and running the hook
4917 @code{term-setup-hook}.
4919 This hook is used for internal purposes: setting up communication with
4920 the window system, and creating the initial window. Users should not
4925 arch-tag: ffdf5714-7ecf-415b-9023-fbc6b409c2c6