2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, 2002
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/display
7 @node Display, Calendar, Processes, Top
10 This chapter describes a number of features related to the display
11 that Emacs presents to the user.
14 * Refresh Screen:: Clearing the screen and redrawing everything on it.
15 * Forcing Redisplay:: Forcing redisplay.
16 * Truncation:: Folding or wrapping long text lines.
17 * The Echo Area:: Where messages are displayed.
18 * Warnings:: Displaying warning messages for the user.
19 * Invisible Text:: Hiding part of the buffer text.
20 * Selective Display:: Hiding part of the buffer text (the old way).
21 * Overlay Arrow:: Display of an arrow to indicate position.
22 * Temporary Displays:: Displays that go away automatically.
23 * Overlays:: Use overlays to highlight parts of the buffer.
24 * Width:: How wide a character or string is on the screen.
25 * Faces:: A face defines a graphics style for text characters:
27 * Fringes:: Controlling window fringes.
28 * Scroll Bars:: Controlling vertical scroll bars.
29 * Display Property:: Enabling special display features.
30 * Images:: Displaying images in Emacs buffers.
31 * Buttons:: Adding clickable buttons to Emacs buffers.
32 * Blinking:: How Emacs shows the matching open parenthesis.
33 * Inverse Video:: Specifying how the screen looks.
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} redisplays the entire contents of a
44 given frame (@pxref{Frames}).
47 @defun redraw-frame frame
48 This function clears and redisplays frame @var{frame}.
51 Even more powerful is @code{redraw-display}:
53 @deffn Command redraw-display
54 This function clears and redisplays all visible frames.
57 This function forces certain windows to be redisplayed
58 but does not clear them.
60 @defun force-window-update object
61 This function forces redisplay of some or all windows. If
62 @var{object} is a window, it forces redisplay of that window. If
63 @var{object} is a buffer or buffer name, it forces redisplay of all
64 windows displaying that buffer. If @var{object} is @code{nil}, it
65 forces redisplay of all windows.
68 Processing user input takes absolute priority over redisplay. If you
69 call these functions when input is available, they do nothing
70 immediately, but a full redisplay does happen eventually---after all the
71 input has been processed.
73 Normally, suspending and resuming Emacs also refreshes the screen.
74 Some terminal emulators record separate contents for display-oriented
75 programs such as Emacs and for ordinary sequential display. If you are
76 using such a terminal, you might want to inhibit the redisplay on
79 @defvar no-redraw-on-reenter
80 @cindex suspend (cf. @code{no-redraw-on-reenter})
81 @cindex resume (cf. @code{no-redraw-on-reenter})
82 This variable controls whether Emacs redraws the entire screen after it
83 has been suspended and resumed. Non-@code{nil} means there is no need
84 to redraw, @code{nil} means redrawing is needed. The default is @code{nil}.
87 @node Forcing Redisplay
88 @section Forcing Redisplay
89 @cindex forcing redisplay
91 Emacs redisplay normally stops if input arrives, and does not happen
92 at all if input is available before it starts. Most of the time, this
93 is exactly what you want. However, you can prevent preemption by
94 binding @code{redisplay-dont-pause} to a non-@code{nil} value.
96 @tindex redisplay-dont-pause
97 @defvar redisplay-dont-pause
98 If this variable is non-@code{nil}, pending input does not
99 prevent or halt redisplay; redisplay occurs, and finishes,
100 regardless of whether input is available. This feature 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 windowed display, the @samp{$} and @samp{\} indicators are
130 replaced with graphics bitmaps 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 You can override the glyphs that indicate continuation or truncation
164 using the display table; see @ref{Display Tables}.
166 If your buffer contains @emph{very} long lines, and you use
167 continuation to display them, just thinking about them can make Emacs
168 redisplay slow. The column computation and indentation functions also
169 become slow. Then you might find it advisable to set
170 @code{cache-long-line-scans} to @code{t}.
172 @defvar cache-long-line-scans
173 If this variable is non-@code{nil}, various indentation and motion
174 functions, and Emacs redisplay, cache the results of scanning the
175 buffer, and consult the cache to avoid rescanning regions of the buffer
176 unless they are modified.
178 Turning on the cache slows down processing of short lines somewhat.
180 This variable is automatically buffer-local in every buffer.
184 @section The Echo Area
185 @cindex error display
188 The @dfn{echo area} is used for displaying messages made with the
189 @code{message} primitive, and for echoing keystrokes. It is not the
190 same as the minibuffer, despite the fact that the minibuffer appears
191 (when active) in the same place on the screen as the echo area. The
192 @cite{GNU Emacs Manual} specifies the rules for resolving conflicts
193 between the echo area and the minibuffer for use of that screen space
194 (@pxref{Minibuffer,, The Minibuffer, emacs, The GNU Emacs Manual}).
195 Error messages appear in the echo area; see @ref{Errors}.
197 You can write output in the echo area by using the Lisp printing
198 functions with @code{t} as the stream (@pxref{Output Functions}), or as
201 @defun message string &rest arguments
202 This function displays a message in the echo area. The
203 argument @var{string} is similar to a C language @code{printf} control
204 string. See @code{format} in @ref{String Conversion}, for the details
205 on the conversion specifications. @code{message} returns the
208 In batch mode, @code{message} prints the message text on the standard
209 error stream, followed by a newline.
211 If @var{string}, or strings among the @var{arguments}, have @code{face}
212 text properties, these affect the way the message is displayed.
215 If @var{string} is @code{nil}, @code{message} clears the echo area; if
216 the echo area has been expanded automatically, this brings it back to
217 its normal size. If the minibuffer is active, this brings the
218 minibuffer contents back onto the screen immediately.
220 @vindex message-truncate-lines
221 Normally, displaying a long message resizes the echo area to display
222 the entire message. But if the variable @code{message-truncate-lines}
223 is non-@code{nil}, the echo area does not resize, and the message is
224 truncated to fit it, as in Emacs 20 and before.
228 (message "Minibuffer depth is %d."
230 @print{} Minibuffer depth is 0.
231 @result{} "Minibuffer depth is 0."
235 ---------- Echo Area ----------
236 Minibuffer depth is 0.
237 ---------- Echo Area ----------
241 To automatically display a message in the echo area or in a pop-buffer,
242 depending on its size, use @code{display-message-or-buffer}.
245 @tindex with-temp-message
246 @defmac with-temp-message message &rest body
247 This construct displays a message in the echo area temporarily, during
248 the execution of @var{body}. It displays @var{message}, executes
249 @var{body}, then returns the value of the last body form while restoring
250 the previous echo area contents.
253 @defun message-or-box string &rest arguments
254 This function displays a message like @code{message}, but may display it
255 in a dialog box instead of the echo area. If this function is called in
256 a command that was invoked using the mouse---more precisely, if
257 @code{last-nonmenu-event} (@pxref{Command Loop Info}) is either
258 @code{nil} or a list---then it uses a dialog box or pop-up menu to
259 display the message. Otherwise, it uses the echo area. (This is the
260 same criterion that @code{y-or-n-p} uses to make a similar decision; see
261 @ref{Yes-or-No Queries}.)
263 You can force use of the mouse or of the echo area by binding
264 @code{last-nonmenu-event} to a suitable value around the call.
267 @defun message-box string &rest arguments
268 This function displays a message like @code{message}, but uses a dialog
269 box (or a pop-up menu) whenever that is possible. If it is impossible
270 to use a dialog box or pop-up menu, because the terminal does not
271 support them, then @code{message-box} uses the echo area, like
275 @defun display-message-or-buffer message &optional buffer-name not-this-window frame
276 @tindex display-message-or-buffer
277 This function displays the message @var{message}, which may be either a
278 string or a buffer. If it is shorter than the maximum height of the
279 echo area, as defined by @code{max-mini-window-height}, it is displayed
280 in the echo area, using @code{message}. Otherwise,
281 @code{display-buffer} is used to show it in a pop-up buffer.
283 Returns either the string shown in the echo area, or when a pop-up
284 buffer is used, the window used to display it.
286 If @var{message} is a string, then the optional argument
287 @var{buffer-name} is the name of the buffer used to display it when a
288 pop-up buffer is used, defaulting to @samp{*Message*}. In the case
289 where @var{message} is a string and displayed in the echo area, it is
290 not specified whether the contents are inserted into the buffer anyway.
292 The optional arguments @var{not-this-window} and @var{frame} are as for
293 @code{display-buffer}, and only used if a buffer is displayed.
296 @defun current-message
297 This function returns the message currently being displayed in the
298 echo area, or @code{nil} if there is none.
301 @defvar cursor-in-echo-area
302 This variable controls where the cursor appears when a message is
303 displayed in the echo area. If it is non-@code{nil}, then the cursor
304 appears at the end of the message. Otherwise, the cursor appears at
305 point---not in the echo area at all.
307 The value is normally @code{nil}; Lisp programs bind it to @code{t}
308 for brief periods of time.
311 @defvar echo-area-clear-hook
312 This normal hook is run whenever the echo area is cleared---either by
313 @code{(message nil)} or for any other reason.
316 Almost all the messages displayed in the echo area are also recorded
317 in the @samp{*Messages*} buffer.
319 @defopt message-log-max
320 This variable specifies how many lines to keep in the @samp{*Messages*}
321 buffer. The value @code{t} means there is no limit on how many lines to
322 keep. The value @code{nil} disables message logging entirely. Here's
323 how to display a message and prevent it from being logged:
326 (let (message-log-max)
331 @defvar echo-keystrokes
332 This variable determines how much time should elapse before command
333 characters echo. Its value must be an integer or floating point number,
335 number of seconds to wait before echoing. If the user types a prefix
336 key (such as @kbd{C-x}) and then delays this many seconds before
337 continuing, the prefix key is echoed in the echo area. (Once echoing
338 begins in a key sequence, all subsequent characters in the same key
339 sequence are echoed immediately.)
341 If the value is zero, then command input is not echoed.
345 @section Reporting Warnings
348 @dfn{Warnings} are a facility for a program to inform the user of a
349 possible problem, but continue running.
352 * Warning Basics:: Warnings concepts and functions to report them.
353 * Warning Variables:: Variables programs bind to customize their warnings.
354 * Warning Options:: Variables users set to control display of warnings.
358 @subsection Warning Basics
359 @cindex severity level
361 Every warning has a textual message, which explains the problem for
362 the user, and a @dfn{severity level} which is a symbol. Here are the
363 possible severity levels, in order of decreasing severity, and their
368 A problem that will seriously impair Emacs operation soon
369 if you do not attend to it promptly.
371 A report of data or circumstances that are inherently wrong.
373 A report of data or circumstances that are not inherently wrong, but
374 raise suspicion of a possible problem.
376 A report of information that may be useful if you are debugging.
379 When your program encounters invalid input data, it can either
380 signal a Lisp error by calling @code{error} or @code{signal} or report
381 a warning with severity @code{:error}. Signaling a Lisp error is the
382 easiest thing to do, but it means the program cannot continue
383 processing. If you want to take the trouble to implement a way to
384 continue processing despite the bad data, then reporting a warning of
385 severity @code{:error} is the right way to inform the user of the
386 problem. For instance, the Emacs Lisp byte compiler can report an
387 error that way and continue compiling other functions. (If the
388 program signals a Lisp error and then handles it with
389 @code{condition-case}, the user won't see the error message; it could
390 show the message to the user by reporting it as a warning.)
393 Each warning has a @dfn{warning type} to classify it. The type is a
394 list of symbols. The first symbol should be the custom group that you
395 use for the program's user options. For example, byte compiler
396 warnings use the warning type @code{(bytecomp)}. You can also
397 subcategorize the warnings, if you wish, by using more symbols in the
400 @defun display-warning type message &optional level buffer-name
401 This function reports a warning, using @var{message} as the message
402 and @var{type} as the warning type. @var{level} should be the
403 severity level, with @code{:warning} being the default.
405 @var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
406 for logging the warning. By default, it is @samp{*Warnings*}.
409 @defun lwarn type level message &rest args
410 This function reports a warning using the value of @code{(format
411 @var{message} @var{args}...)} as the message. In other respects it is
412 equivalent to @code{display-warning}.
415 @defun warn message &rest args
416 This function reports a warning using the value of @code{(format
417 @var{message} @var{args}...)} as the message, @code{(emacs)} as the
418 type, and @code{:warning} as the severity level. It exists for
419 compatibility only; we recommend not using it, because you should
420 specify a specific warning type.
423 @node Warning Variables
424 @subsection Warning Variables
426 Programs can customize how their warnings appear by binding
427 the variables described in this section.
429 @defvar warning-levels
430 This list defines the meaning and severity order of the warning
431 severity levels. Each element defines one severity level,
432 and they are arranged in order of decreasing severity.
434 Each element has the form @code{(@var{level} @var{string}
435 @var{function})}, where @var{level} is the severity level it defines.
436 @var{string} specifies the textual description of this level.
437 @var{string} should use @samp{%s} to specify where to put the warning
438 type information, or it can omit the @samp{%s} so as not to include
441 The optional @var{function}, if non-@code{nil}, is a function to call
442 with no arguments, to get the user's attention.
444 Normally you should not change the value of this variable.
447 @defvar warning-prefix-function
448 If non-@code{nil}, the value is a function to generate prefix text for
449 warnings. Programs can bind the variable to a suitable function.
450 @code{display-warning} calls this function with the warnings buffer
451 current, and the function can insert text in it. That text becomes
452 the beginning of the warning message.
454 The function is called with two arguments, the severity level and its
455 entry in @code{warning-levels}. It should return a list to use as the
456 entry (this value need not be an actual member of
457 @code{warning-levels}). By constructing this value, the function can
458 change the severity of the warning, or specify different handling for
459 a given severity level.
461 If the variable's value is @code{nil} then there is no function
465 @defvar warning-series
466 Programs can bind this variable to @code{t} to say that the next
467 warning should begin a series. When several warnings form a series,
468 that means to leave point on the first warning of the series, rather
469 than keep moving it for each warning so that it appears on the last one.
470 The series ends when the local binding is unbound and
471 @code{warning-series} becomes @code{nil} again.
473 The value can also be a symbol with a function definition. That is
474 equivalent to @code{t}, except that the next warning will also call
475 the function with no arguments with the warnings buffer current. The
476 function can insert text which will serve as a header for the series
479 Once a series has begun, the value is a marker which points to the
480 buffer position in the warnings buffer of the start of the series.
482 The variable's normal value is @code{nil}, which means to handle
483 each warning separately.
486 @defvar warning-fill-prefix
487 When this variable is non-@code{nil}, it specifies a fill prefix to
488 use for filling each warning's text.
491 @defvar warning-type-format
492 This variable specifies the format for displaying the warning type
493 in the warning message. The result of formatting the type this way
494 gets included in the message under the control of the string in the
495 entry in @code{warning-levels}. The default value is @code{" (%s)"}.
496 If you bind it to @code{""} then the warning type won't appear at
500 @node Warning Options
501 @subsection Warning Options
503 These variables are used by users to control what happens
504 when a Lisp program reports a warning.
506 @defopt warning-minimum-level
507 This user option specifies the minimum severity level that should be
508 shown immediately to the user. The default is @code{:warning}, which
509 means to immediately display all warnings except @code{:debug}
513 @defopt warning-minimum-log-level
514 This user option specifies the minimum severity level that should be
515 logged in the warnings buffer. The default is @code{:warning}, which
516 means to log all warnings except @code{:debug} warnings.
519 @defopt warning-suppress-types
520 This list specifies which warning types should not be displayed
521 immediately for the user. Each element of the list should be a list
522 of symbols. If its elements match the first elements in a warning
523 type, then that warning is not displayed immediately.
526 @defopt warning-suppress-log-types
527 This list specifies which warning types should not be logged in the
528 warnings buffer. Each element of the list should be a list of
529 symbols. If it matches the first few elements in a warning type, then
530 that warning is not logged.
534 @section Invisible Text
536 @cindex invisible text
537 You can make characters @dfn{invisible}, so that they do not appear on
538 the screen, with the @code{invisible} property. This can be either a
539 text property (@pxref{Text Properties}) or a property of an overlay
542 In the simplest case, any non-@code{nil} @code{invisible} property makes
543 a character invisible. This is the default case---if you don't alter
544 the default value of @code{buffer-invisibility-spec}, this is how the
545 @code{invisible} property works. You should normally use @code{t}
546 as the value of the @code{invisible} property if you don't plan
547 to set @code{buffer-invisibility-spec} yourself.
549 More generally, you can use the variable @code{buffer-invisibility-spec}
550 to control which values of the @code{invisible} property make text
551 invisible. This permits you to classify the text into different subsets
552 in advance, by giving them different @code{invisible} values, and
553 subsequently make various subsets visible or invisible by changing the
554 value of @code{buffer-invisibility-spec}.
556 Controlling visibility with @code{buffer-invisibility-spec} is
557 especially useful in a program to display the list of entries in a
558 database. It permits the implementation of convenient filtering
559 commands to view just a part of the entries in the database. Setting
560 this variable is very fast, much faster than scanning all the text in
561 the buffer looking for properties to change.
563 @defvar buffer-invisibility-spec
564 This variable specifies which kinds of @code{invisible} properties
565 actually make a character invisible.
569 A character is invisible if its @code{invisible} property is
570 non-@code{nil}. This is the default.
573 Each element of the list specifies a criterion for invisibility; if a
574 character's @code{invisible} property fits any one of these criteria,
575 the character is invisible. The list can have two kinds of elements:
579 A character is invisible if its @code{invisible} property value
580 is @var{atom} or if it is a list with @var{atom} as a member.
582 @item (@var{atom} . t)
583 A character is invisible if its @code{invisible} property value
584 is @var{atom} or if it is a list with @var{atom} as a member.
585 Moreover, if this character is at the end of a line and is followed
586 by a visible newline, it displays an ellipsis.
591 Two functions are specifically provided for adding elements to
592 @code{buffer-invisibility-spec} and removing elements from it.
594 @defun add-to-invisibility-spec element
595 This function adds the element @var{element} to
596 @code{buffer-invisibility-spec} (if it is not already present in that
597 list). If @code{buffer-invisibility-spec} was @code{t}, it changes to
598 a list, @code{(t)}, so that text whose @code{invisible} property
599 is @code{t} remains invisible.
602 @defun remove-from-invisibility-spec element
603 This removes the element @var{element} from
604 @code{buffer-invisibility-spec}. This does nothing if @var{element}
608 A convention for use of @code{buffer-invisibility-spec} is that a
609 major mode should use the mode's own name as an element of
610 @code{buffer-invisibility-spec} and as the value of the
611 @code{invisible} property:
614 ;; @r{If you want to display an ellipsis:}
615 (add-to-invisibility-spec '(my-symbol . t))
616 ;; @r{If you don't want ellipsis:}
617 (add-to-invisibility-spec 'my-symbol)
619 (overlay-put (make-overlay beginning end)
620 'invisible 'my-symbol)
622 ;; @r{When done with the overlays:}
623 (remove-from-invisibility-spec '(my-symbol . t))
624 ;; @r{Or respectively:}
625 (remove-from-invisibility-spec 'my-symbol)
628 @vindex line-move-ignore-invisible
629 Ordinarily, functions that operate on text or move point do not care
630 whether the text is invisible. The user-level line motion commands
631 explicitly ignore invisible newlines if
632 @code{line-move-ignore-invisible} is non-@code{nil}, but only because
633 they are explicitly programmed to do so.
635 However, if a command ends with point inside or immediately after
636 invisible text, the main editing loop moves point further forward or
637 further backward (in the same direction that the command already moved
638 it) until that condition is no longer true. Thus, if the command
639 moved point back into an invisible range, Emacs moves point back to
640 the beginning of that range, following the previous visible character.
641 If the command moved point forward into an invisible range, Emacs
642 moves point forward past the first visible character that follows the
645 Incremental search can make invisible overlays visible temporarily
646 and/or permanently when a match includes invisible text. To enable
647 this, the overlay should have a non-@code{nil}
648 @code{isearch-open-invisible} property. The property value should be a
649 function to be called with the overlay as an argument. This function
650 should make the overlay visible permanently; it is used when the match
651 overlaps the overlay on exit from the search.
653 During the search, such overlays are made temporarily visible by
654 temporarily modifying their invisible and intangible properties. If you
655 want this to be done differently for a certain overlay, give it an
656 @code{isearch-open-invisible-temporary} property which is a function.
657 The function is called with two arguments: the first is the overlay, and
658 the second is @code{nil} to make the overlay visible, or @code{t} to
659 make it invisible again.
661 @node Selective Display
662 @section Selective Display
663 @cindex selective display
665 @dfn{Selective display} refers to a pair of related features for
666 hiding certain lines on the screen.
668 The first variant, explicit selective display, is designed for use in
669 a Lisp program: it controls which lines are hidden by altering the text.
670 The invisible text feature (@pxref{Invisible Text}) has partially
671 replaced this feature.
673 In the second variant, the choice of lines to hide is made
674 automatically based on indentation. This variant is designed to be a
677 The way you control explicit selective display is by replacing a
678 newline (control-j) with a carriage return (control-m). The text that
679 was formerly a line following that newline is now invisible. Strictly
680 speaking, it is temporarily no longer a line at all, since only newlines
681 can separate lines; it is now part of the previous line.
683 Selective display does not directly affect editing commands. For
684 example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly into
685 invisible text. However, the replacement of newline characters with
686 carriage return characters affects some editing commands. For example,
687 @code{next-line} skips invisible lines, since it searches only for
688 newlines. Modes that use selective display can also define commands
689 that take account of the newlines, or that make parts of the text
690 visible or invisible.
692 When you write a selectively displayed buffer into a file, all the
693 control-m's are output as newlines. This means that when you next read
694 in the file, it looks OK, with nothing invisible. The selective display
695 effect is seen only within Emacs.
697 @defvar selective-display
698 This buffer-local variable enables selective display. This means that
699 lines, or portions of lines, may be made invisible.
703 If the value of @code{selective-display} is @code{t}, then the character
704 control-m marks the start of invisible text; the control-m, and the rest
705 of the line following it, are not displayed. This is explicit selective
709 If the value of @code{selective-display} is a positive integer, then
710 lines that start with more than that many columns of indentation are not
714 When some portion of a buffer is invisible, the vertical movement
715 commands operate as if that portion did not exist, allowing a single
716 @code{next-line} command to skip any number of invisible lines.
717 However, character movement commands (such as @code{forward-char}) do
718 not skip the invisible portion, and it is possible (if tricky) to insert
719 or delete text in an invisible portion.
721 In the examples below, we show the @emph{display appearance} of the
722 buffer @code{foo}, which changes with the value of
723 @code{selective-display}. The @emph{contents} of the buffer do not
728 (setq selective-display nil)
731 ---------- Buffer: foo ----------
738 ---------- Buffer: foo ----------
742 (setq selective-display 2)
745 ---------- Buffer: foo ----------
750 ---------- Buffer: foo ----------
755 @defvar selective-display-ellipses
756 If this buffer-local variable is non-@code{nil}, then Emacs displays
757 @samp{@dots{}} at the end of a line that is followed by invisible text.
758 This example is a continuation of the previous one.
762 (setq selective-display-ellipses t)
765 ---------- Buffer: foo ----------
770 ---------- Buffer: foo ----------
774 You can use a display table to substitute other text for the ellipsis
775 (@samp{@dots{}}). @xref{Display Tables}.
779 @section The Overlay Arrow
780 @cindex overlay arrow
782 The @dfn{overlay arrow} is useful for directing the user's attention
783 to a particular line in a buffer. For example, in the modes used for
784 interface to debuggers, the overlay arrow indicates the line of code
785 about to be executed.
787 @defvar overlay-arrow-string
788 This variable holds the string to display to call attention to a
789 particular line, or @code{nil} if the arrow feature is not in use.
790 On a graphical display the contents of the string are ignored; instead a
791 glyph is displayed in the fringe area to the left of the display area.
794 @defvar overlay-arrow-position
795 This variable holds a marker that indicates where to display the overlay
796 arrow. It should point at the beginning of a line. On a non-graphical
797 display the arrow text
798 appears at the beginning of that line, overlaying any text that would
799 otherwise appear. Since the arrow is usually short, and the line
800 usually begins with indentation, normally nothing significant is
803 The overlay string is displayed only in the buffer that this marker
804 points into. Thus, only one buffer can have an overlay arrow at any
806 @c !!! overlay-arrow-position: but the overlay string may remain in the display
807 @c of some other buffer until an update is required. This should be fixed
811 You can do a similar job by creating an overlay with a
812 @code{before-string} property. @xref{Overlay Properties}.
814 @node Temporary Displays
815 @section Temporary Displays
817 Temporary displays are used by Lisp programs to put output into a
818 buffer and then present it to the user for perusal rather than for
819 editing. Many help commands use this feature.
821 @defspec with-output-to-temp-buffer buffer-name forms@dots{}
822 This function executes @var{forms} while arranging to insert any output
823 they print into the buffer named @var{buffer-name}, which is first
824 created if necessary, and put into Help mode. Finally, the buffer is
825 displayed in some window, but not selected.
827 If the @var{forms} do not change the major mode in the output buffer,
828 so that it is still Help mode at the end of their execution, then
829 @code{with-output-to-temp-buffer} makes this buffer read-only at the
830 end, and also scans it for function and variable names to make them
831 into clickable cross-references. @xref{Docstring hyperlinks, , Tips
832 for Documentation Strings}, in particular the item on hyperlinks in
833 documentation strings, for more details.
835 The string @var{buffer-name} specifies the temporary buffer, which
836 need not already exist. The argument must be a string, not a buffer.
837 The buffer is erased initially (with no questions asked), and it is
838 marked as unmodified after @code{with-output-to-temp-buffer} exits.
840 @code{with-output-to-temp-buffer} binds @code{standard-output} to the
841 temporary buffer, then it evaluates the forms in @var{forms}. Output
842 using the Lisp output functions within @var{forms} goes by default to
843 that buffer (but screen display and messages in the echo area, although
844 they are ``output'' in the general sense of the word, are not affected).
845 @xref{Output Functions}.
847 Several hooks are available for customizing the behavior
848 of this construct; they are listed below.
850 The value of the last form in @var{forms} is returned.
854 ---------- Buffer: foo ----------
855 This is the contents of foo.
856 ---------- Buffer: foo ----------
860 (with-output-to-temp-buffer "foo"
862 (print standard-output))
863 @result{} #<buffer foo>
865 ---------- Buffer: foo ----------
870 ---------- Buffer: foo ----------
875 @defvar temp-buffer-show-function
876 If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
877 calls it as a function to do the job of displaying a help buffer. The
878 function gets one argument, which is the buffer it should display.
880 It is a good idea for this function to run @code{temp-buffer-show-hook}
881 just as @code{with-output-to-temp-buffer} normally would, inside of
882 @code{save-selected-window} and with the chosen window and buffer
886 @defvar temp-buffer-setup-hook
887 @tindex temp-buffer-setup-hook
888 This normal hook is run by @code{with-output-to-temp-buffer} before
889 evaluating @var{body}. When the hook runs, the temporary buffer is
890 current. This hook is normally set up with a function to put the
894 @defvar temp-buffer-show-hook
895 This normal hook is run by @code{with-output-to-temp-buffer} after
896 displaying the temporary buffer. When the hook runs, the temporary buffer
897 is current, and the window it was displayed in is selected. This hook
898 is normally set up with a function to make the buffer read only, and
899 find function names and variable names in it, provided the major mode
903 @defun momentary-string-display string position &optional char message
904 This function momentarily displays @var{string} in the current buffer at
905 @var{position}. It has no effect on the undo list or on the buffer's
908 The momentary display remains until the next input event. If the next
909 input event is @var{char}, @code{momentary-string-display} ignores it
910 and returns. Otherwise, that event remains buffered for subsequent use
911 as input. Thus, typing @var{char} will simply remove the string from
912 the display, while typing (say) @kbd{C-f} will remove the string from
913 the display and later (presumably) move point forward. The argument
914 @var{char} is a space by default.
916 The return value of @code{momentary-string-display} is not meaningful.
918 If the string @var{string} does not contain control characters, you can
919 do the same job in a more general way by creating (and then subsequently
920 deleting) an overlay with a @code{before-string} property.
921 @xref{Overlay Properties}.
923 If @var{message} is non-@code{nil}, it is displayed in the echo area
924 while @var{string} is displayed in the buffer. If it is @code{nil}, a
925 default message says to type @var{char} to continue.
927 In this example, point is initially located at the beginning of the
932 ---------- Buffer: foo ----------
933 This is the contents of foo.
935 ---------- Buffer: foo ----------
939 (momentary-string-display
940 "**** Important Message! ****"
942 "Type RET when done reading")
947 ---------- Buffer: foo ----------
948 This is the contents of foo.
949 **** Important Message! ****Second line.
950 ---------- Buffer: foo ----------
952 ---------- Echo Area ----------
953 Type RET when done reading
954 ---------- Echo Area ----------
963 You can use @dfn{overlays} to alter the appearance of a buffer's text on
964 the screen, for the sake of presentation features. An overlay is an
965 object that belongs to a particular buffer, and has a specified
966 beginning and end. It also has properties that you can examine and set;
967 these affect the display of the text within the overlay.
969 An overlays uses markers to record its beginning and end; thus,
970 editing the text of the buffer adjusts the beginning and end of each
971 overlay so that it stays with the text. When you create the overlay,
972 you can specify whether text inserted at the beginning should be
973 inside the overlay or outside, and likewise for the end of the overlay.
976 * Overlay Properties:: How to read and set properties.
977 What properties do to the screen display.
978 * Managing Overlays:: Creating and moving overlays.
979 * Finding Overlays:: Searching for overlays.
982 @node Overlay Properties
983 @subsection Overlay Properties
985 Overlay properties are like text properties in that the properties that
986 alter how a character is displayed can come from either source. But in
987 most respects they are different. Text properties are considered a part
988 of the text; overlays are specifically considered not to be part of the
989 text. Thus, copying text between various buffers and strings preserves
990 text properties, but does not try to preserve overlays. Changing a
991 buffer's text properties marks the buffer as modified, while moving an
992 overlay or changing its properties does not. Unlike text property
993 changes, overlay changes are not recorded in the buffer's undo list.
994 @xref{Text Properties}, for comparison.
996 These functions are used for reading and writing the properties of an
999 @defun overlay-get overlay prop
1000 This function returns the value of property @var{prop} recorded in
1001 @var{overlay}, if any. If @var{overlay} does not record any value for
1002 that property, but it does have a @code{category} property which is a
1003 symbol, that symbol's @var{prop} property is used. Otherwise, the value
1007 @defun overlay-put overlay prop value
1008 This function sets the value of property @var{prop} recorded in
1009 @var{overlay} to @var{value}. It returns @var{value}.
1012 @defun overlay-properties overlay
1013 This returns a copy of the property list of @var{overlay}.
1016 See also the function @code{get-char-property} which checks both
1017 overlay properties and text properties for a given character.
1018 @xref{Examining Properties}.
1020 Many overlay properties have special meanings; here is a table
1025 @kindex priority @r{(overlay property)}
1026 This property's value (which should be a nonnegative integer number)
1027 determines the priority of the overlay. The priority matters when two
1028 or more overlays cover the same character and both specify the same
1029 property; the one whose @code{priority} value is larger takes priority
1030 over the other. For the @code{face} property, the higher priority
1031 value does not completely replace the other; instead, its face
1032 attributes override the face attributes of the lower priority
1033 @code{face} property.
1035 Currently, all overlays take priority over text properties. Please
1036 avoid using negative priority values, as we have not yet decided just
1037 what they should mean.
1040 @kindex window @r{(overlay property)}
1041 If the @code{window} property is non-@code{nil}, then the overlay
1042 applies only on that window.
1045 @kindex category @r{(overlay property)}
1046 If an overlay has a @code{category} property, we call it the
1047 @dfn{category} of the overlay. It should be a symbol. The properties
1048 of the symbol serve as defaults for the properties of the overlay.
1051 @kindex face @r{(overlay property)}
1052 This property controls the way text is displayed---for example, which
1053 font and which colors. @xref{Faces}, for more information.
1055 In the simplest case, the value is a face name. It can also be a list;
1056 then each element can be any of these possibilities:
1060 A face name (a symbol or string).
1063 Starting in Emacs 21, a property list of face attributes. This has the
1064 form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
1065 face attribute name and @var{value} is a meaningful value for that
1066 attribute. With this feature, you do not need to create a face each
1067 time you want to specify a particular attribute for certain text.
1068 @xref{Face Attributes}.
1071 A cons cell of the form @code{(foreground-color . @var{color-name})} or
1072 @code{(background-color . @var{color-name})}. These elements specify
1073 just the foreground color or just the background color.
1075 @code{(foreground-color . @var{color-name})} is equivalent to
1076 @code{(:foreground @var{color-name})}, and likewise for the background.
1080 @kindex mouse-face @r{(overlay property)}
1081 This property is used instead of @code{face} when the mouse is within
1082 the range of the overlay.
1085 @kindex display @r{(overlay property)}
1086 This property activates various features that change the
1087 way text is displayed. For example, it can make text appear taller
1088 or shorter, higher or lower, wider or narrower, or replaced with an image.
1089 @xref{Display Property}.
1092 @kindex help-echo @r{(text property)}
1093 If an overlay has a @code{help-echo} property, then when you move the
1094 mouse onto the text in the overlay, Emacs displays a help string in the
1095 echo area, or in the tooltip window. For details see @ref{Text
1098 @item modification-hooks
1099 @kindex modification-hooks @r{(overlay property)}
1100 This property's value is a list of functions to be called if any
1101 character within the overlay is changed or if text is inserted strictly
1104 The hook functions are called both before and after each change.
1105 If the functions save the information they receive, and compare notes
1106 between calls, they can determine exactly what change has been made
1109 When called before a change, each function receives four arguments: the
1110 overlay, @code{nil}, and the beginning and end of the text range to be
1113 When called after a change, each function receives five arguments: the
1114 overlay, @code{t}, the beginning and end of the text range just
1115 modified, and the length of the pre-change text replaced by that range.
1116 (For an insertion, the pre-change length is zero; for a deletion, that
1117 length is the number of characters deleted, and the post-change
1118 beginning and end are equal.)
1120 @item insert-in-front-hooks
1121 @kindex insert-in-front-hooks @r{(overlay property)}
1122 This property's value is a list of functions to be called before and
1123 after inserting text right at the beginning of the overlay. The calling
1124 conventions are the same as for the @code{modification-hooks} functions.
1126 @item insert-behind-hooks
1127 @kindex insert-behind-hooks @r{(overlay property)}
1128 This property's value is a list of functions to be called before and
1129 after inserting text right at the end of the overlay. The calling
1130 conventions are the same as for the @code{modification-hooks} functions.
1133 @kindex invisible @r{(overlay property)}
1134 The @code{invisible} property can make the text in the overlay
1135 invisible, which means that it does not appear on the screen.
1136 @xref{Invisible Text}, for details.
1139 @kindex intangible @r{(overlay property)}
1140 The @code{intangible} property on an overlay works just like the
1141 @code{intangible} text property. @xref{Special Properties}, for details.
1143 @item isearch-open-invisible
1144 This property tells incremental search how to make an invisible overlay
1145 visible, permanently, if the final match overlaps it. @xref{Invisible
1148 @item isearch-open-invisible-temporary
1149 This property tells incremental search how to make an invisible overlay
1150 visible, temporarily, during the search. @xref{Invisible Text}.
1153 @kindex before-string @r{(overlay property)}
1154 This property's value is a string to add to the display at the beginning
1155 of the overlay. The string does not appear in the buffer in any
1156 sense---only on the screen.
1159 @kindex after-string @r{(overlay property)}
1160 This property's value is a string to add to the display at the end of
1161 the overlay. The string does not appear in the buffer in any
1162 sense---only on the screen.
1165 @kindex evaporate @r{(overlay property)}
1166 If this property is non-@code{nil}, the overlay is deleted automatically
1167 if it becomes empty (i.e., if its length becomes zero). However,
1168 if the overlay is @emph{already} empty, @code{evaporate} does not
1172 @cindex keymap of character (and overlays)
1173 @kindex local-map @r{(overlay property)}
1174 If this property is non-@code{nil}, it specifies a keymap for a portion
1175 of the text. The property's value replaces the buffer's local map, when
1176 the character after point is within the overlay. @xref{Active Keymaps}.
1179 @kindex keymap @r{(overlay property)}
1180 The @code{keymap} property is similar to @code{local-map} but overrides the
1181 buffer's local map (and the map specified by the @code{local-map}
1182 property) rather than replacing it.
1185 @node Managing Overlays
1186 @subsection Managing Overlays
1188 This section describes the functions to create, delete and move
1189 overlays, and to examine their contents.
1191 @defun overlayp object
1192 This function returns @code{t} if @var{object} is an overlay.
1195 @defun make-overlay start end &optional buffer front-advance rear-advance
1196 This function creates and returns an overlay that belongs to
1197 @var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
1198 and @var{end} must specify buffer positions; they may be integers or
1199 markers. If @var{buffer} is omitted, the overlay is created in the
1202 The arguments @var{front-advance} and @var{rear-advance} specify the
1203 insertion type for the start of the overlay and for the end of the
1204 overlay, respectively. @xref{Marker Insertion Types}. If
1205 @var{front-advance} is non-@code{nil}, text inserted at the beginning
1206 of the overlay is excluded from the overlay. If @var{read-advance} is
1207 non-@code{nil}, text inserted at the beginning of the overlay is
1208 included in the overlay.
1211 @defun overlay-start overlay
1212 This function returns the position at which @var{overlay} starts,
1216 @defun overlay-end overlay
1217 This function returns the position at which @var{overlay} ends,
1221 @defun overlay-buffer overlay
1222 This function returns the buffer that @var{overlay} belongs to.
1225 @defun delete-overlay overlay
1226 This function deletes @var{overlay}. The overlay continues to exist as
1227 a Lisp object, and its property list is unchanged, but it ceases to be
1228 attached to the buffer it belonged to, and ceases to have any effect on
1231 A deleted overlay is not permanently disconnected. You can give it a
1232 position in a buffer again by calling @code{move-overlay}.
1235 @defun move-overlay overlay start end &optional buffer
1236 This function moves @var{overlay} to @var{buffer}, and places its bounds
1237 at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
1238 must specify buffer positions; they may be integers or markers.
1240 If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
1241 was already associated with; if @var{overlay} was deleted, it goes into
1244 The return value is @var{overlay}.
1246 This is the only valid way to change the endpoints of an overlay. Do
1247 not try modifying the markers in the overlay by hand, as that fails to
1248 update other vital data structures and can cause some overlays to be
1252 Here are some examples:
1255 ;; @r{Create an overlay.}
1256 (setq foo (make-overlay 1 10))
1257 @result{} #<overlay from 1 to 10 in display.texi>
1262 (overlay-buffer foo)
1263 @result{} #<buffer display.texi>
1264 ;; @r{Give it a property we can check later.}
1265 (overlay-put foo 'happy t)
1267 ;; @r{Verify the property is present.}
1268 (overlay-get foo 'happy)
1270 ;; @r{Move the overlay.}
1271 (move-overlay foo 5 20)
1272 @result{} #<overlay from 5 to 20 in display.texi>
1277 ;; @r{Delete the overlay.}
1278 (delete-overlay foo)
1280 ;; @r{Verify it is deleted.}
1282 @result{} #<overlay in no buffer>
1283 ;; @r{A deleted overlay has no position.}
1288 (overlay-buffer foo)
1290 ;; @r{Undelete the overlay.}
1291 (move-overlay foo 1 20)
1292 @result{} #<overlay from 1 to 20 in display.texi>
1293 ;; @r{Verify the results.}
1298 (overlay-buffer foo)
1299 @result{} #<buffer display.texi>
1300 ;; @r{Moving and deleting the overlay does not change its properties.}
1301 (overlay-get foo 'happy)
1305 @node Finding Overlays
1306 @subsection Searching for Overlays
1308 @defun overlays-at pos
1309 This function returns a list of all the overlays that cover the
1310 character at position @var{pos} in the current buffer. The list is in
1311 no particular order. An overlay contains position @var{pos} if it
1312 begins at or before @var{pos}, and ends after @var{pos}.
1314 To illustrate usage, here is a Lisp function that returns a list of the
1315 overlays that specify property @var{prop} for the character at point:
1318 (defun find-overlays-specifying (prop)
1319 (let ((overlays (overlays-at (point)))
1322 (let ((overlay (car overlays)))
1323 (if (overlay-get overlay prop)
1324 (setq found (cons overlay found))))
1325 (setq overlays (cdr overlays)))
1330 @defun overlays-in beg end
1331 This function returns a list of the overlays that overlap the region
1332 @var{beg} through @var{end}. ``Overlap'' means that at least one
1333 character is contained within the overlay and also contained within the
1334 specified region; however, empty overlays are included in the result if
1335 they are located at @var{beg}, or strictly between @var{beg} and @var{end}.
1338 @defun next-overlay-change pos
1339 This function returns the buffer position of the next beginning or end
1340 of an overlay, after @var{pos}.
1343 @defun previous-overlay-change pos
1344 This function returns the buffer position of the previous beginning or
1345 end of an overlay, before @var{pos}.
1348 Here's an easy way to use @code{next-overlay-change} to search for the
1349 next character which gets a non-@code{nil} @code{happy} property from
1350 either its overlays or its text properties (@pxref{Property Search}):
1353 (defun find-overlay-prop (prop)
1355 (while (and (not (eobp))
1356 (not (get-char-property (point) 'happy)))
1357 (goto-char (min (next-overlay-change (point))
1358 (next-single-property-change (point) 'happy))))
1365 Since not all characters have the same width, these functions let you
1366 check the width of a character. @xref{Primitive Indent}, and
1367 @ref{Screen Lines}, for related functions.
1369 @defun char-width char
1370 This function returns the width in columns of the character @var{char},
1371 if it were displayed in the current buffer and the selected window.
1374 @defun string-width string
1375 This function returns the width in columns of the string @var{string},
1376 if it were displayed in the current buffer and the selected window.
1379 @defun truncate-string-to-width string width &optional start-column padding
1380 This function returns the part of @var{string} that fits within
1381 @var{width} columns, as a new string.
1383 If @var{string} does not reach @var{width}, then the result ends where
1384 @var{string} ends. If one multi-column character in @var{string}
1385 extends across the column @var{width}, that character is not included in
1386 the result. Thus, the result can fall short of @var{width} but cannot
1389 The optional argument @var{start-column} specifies the starting column.
1390 If this is non-@code{nil}, then the first @var{start-column} columns of
1391 the string are omitted from the value. If one multi-column character in
1392 @var{string} extends across the column @var{start-column}, that
1393 character is not included.
1395 The optional argument @var{padding}, if non-@code{nil}, is a padding
1396 character added at the beginning and end of the result string, to extend
1397 it to exactly @var{width} columns. The padding character is used at the
1398 end of the result if it falls short of @var{width}. It is also used at
1399 the beginning of the result if one multi-column character in
1400 @var{string} extends across the column @var{start-column}.
1403 (truncate-string-to-width "\tab\t" 12 4)
1405 (truncate-string-to-width "\tab\t" 12 4 ?\s)
1414 A @dfn{face} is a named collection of graphical attributes: font
1415 family, foreground color, background color, optional underlining, and
1416 many others. Faces are used in Emacs to control the style of display of
1417 particular parts of the text or the frame.
1420 Each face has its own @dfn{face number}, which distinguishes faces at
1421 low levels within Emacs. However, for most purposes, you refer to
1422 faces in Lisp programs by their names.
1425 This function returns @code{t} if @var{object} is a face name symbol (or
1426 if it is a vector of the kind used internally to record face data). It
1427 returns @code{nil} otherwise.
1430 Each face name is meaningful for all frames, and by default it has the
1431 same meaning in all frames. But you can arrange to give a particular
1432 face name a special meaning in one frame if you wish.
1435 * Standard Faces:: The faces Emacs normally comes with.
1436 * Defining Faces:: How to define a face with @code{defface}.
1437 * Face Attributes:: What is in a face?
1438 * Attribute Functions:: Functions to examine and set face attributes.
1439 * Merging Faces:: How Emacs combines the faces specified for a character.
1440 * Font Selection:: Finding the best available font for a face.
1441 * Face Functions:: How to define and examine faces.
1442 * Auto Faces:: Hook for automatic face assignment.
1443 * Font Lookup:: Looking up the names of available fonts
1444 and information about them.
1445 * Fontsets:: A fontset is a collection of fonts
1446 that handle a range of character sets.
1449 @node Standard Faces
1450 @subsection Standard Faces
1452 This table lists all the standard faces and their uses. Most of them
1453 are used for displaying certain parts of the frames or certain kinds of
1454 text; you can control how those places look by customizing these faces.
1458 @kindex default @r{(face name)}
1459 This face is used for ordinary text.
1462 @kindex mode-line @r{(face name)}
1463 This face is used for the mode line of the selected window, and for
1464 menu bars when toolkit menus are not used---but only if
1465 @code{mode-line-inverse-video} is non-@code{nil}.
1468 @kindex modeline @r{(face name)}
1469 This is an alias for the @code{mode-line} face, for compatibility with
1472 @item mode-line-inactive
1473 @kindex mode-line-inactive @r{(face name)}
1474 This face is used for mode lines of non-selected windows.
1475 This face inherits from @code{mode-line}, so changes
1476 in that face affect all windows.
1479 @kindex header-line @r{(face name)}
1480 This face is used for the header lines of windows that have them.
1483 This face controls the display of menus, both their colors and their
1484 font. (This works only on certain systems.)
1487 @kindex fringe @r{(face name)}
1488 This face controls the colors of window fringes, the thin areas on
1489 either side that are used to display continuation and truncation glyphs.
1491 @item minibuffer-prompt
1492 @kindex minibuffer-prompt @r{(face name)}
1493 @vindex minibuffer-prompt-properties
1494 This face is used for the text of minibuffer prompts. By default,
1495 Emacs automatically adds this face to the value of
1496 @code{minibuffer-prompt-properties}, which is a list of text
1497 properties used to display the prompt text.
1500 @kindex scroll-bar @r{(face name)}
1501 This face controls the colors for display of scroll bars.
1504 @kindex tool-bar @r{(face name)}
1505 This face is used for display of the tool bar, if any.
1508 @kindex region @r{(face name)}
1509 This face is used for highlighting the region in Transient Mark mode.
1511 @item secondary-selection
1512 @kindex secondary-selection @r{(face name)}
1513 This face is used to show any secondary selection you have made.
1516 @kindex highlight @r{(face name)}
1517 This face is meant to be used for highlighting for various purposes.
1519 @item trailing-whitespace
1520 @kindex trailing-whitespace @r{(face name)}
1521 This face is used to display excess whitespace at the end of a line,
1522 if @code{show-trailing-whitespace} is non-@code{nil}.
1525 In contrast, these faces are provided to change the appearance of text
1526 in specific ways. You can use them on specific text, when you want
1527 the effects they produce.
1531 @kindex bold @r{(face name)}
1532 This face uses a bold font, if possible. It uses the bold variant of
1533 the frame's font, if it has one. It's up to you to choose a default
1534 font that has a bold variant, if you want to use one.
1537 @kindex italic @r{(face name)}
1538 This face uses the italic variant of the frame's font, if it has one.
1541 @kindex bold-italic @r{(face name)}
1542 This face uses the bold italic variant of the frame's font, if it has
1546 @kindex underline @r{(face name)}
1547 This face underlines text.
1550 @kindex fixed-pitch @r{(face name)}
1551 This face forces use of a particular fixed-width font.
1553 @item variable-pitch
1554 @kindex variable-pitch @r{(face name)}
1555 This face forces use of a particular variable-width font. It's
1556 reasonable to customize this to use a different variable-width font, if
1557 you like, but you should not make it a fixed-width font.
1560 @defvar show-trailing-whitespace
1561 @tindex show-trailing-whitespace
1562 If this variable is non-@code{nil}, Emacs uses the
1563 @code{trailing-whitespace} face to display any spaces and tabs at the
1567 @node Defining Faces
1568 @subsection Defining Faces
1570 The way to define a new face is with @code{defface}. This creates a
1571 kind of customization item (@pxref{Customization}) which the user can
1572 customize using the Customization buffer (@pxref{Easy Customization,,,
1573 emacs, The GNU Emacs Manual}).
1575 @defmac defface face spec doc [keyword value]...
1576 This declares @var{face} as a customizable face that defaults according
1577 to @var{spec}. You should not quote the symbol @var{face}. The
1578 argument @var{doc} specifies the face documentation. The keywords you
1579 can use in @code{defface} are the same ones that are meaningful in both
1580 @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
1582 When @code{defface} executes, it defines the face according to
1583 @var{spec}, then uses any customizations that were read from the
1584 init file (@pxref{Init File}) to override that specification.
1586 The purpose of @var{spec} is to specify how the face should appear on
1587 different kinds of terminals. It should be an alist whose elements have
1588 the form @code{(@var{display} @var{atts})}. Each element's @sc{car},
1589 @var{display}, specifies a class of terminals. The element's second element,
1590 @var{atts}, is a list of face attributes and their values; it specifies
1591 what the face should look like on that kind of terminal. The possible
1592 attributes are defined in the value of @code{custom-face-attributes}.
1594 The @var{display} part of an element of @var{spec} determines which
1595 frames the element applies to. If more than one element of @var{spec}
1596 matches a given frame, the first matching element is the only one used
1597 for that frame. There are two possibilities for @var{display}:
1601 This element of @var{spec} matches all frames. Therefore, any
1602 subsequent elements of @var{spec} are never used. Normally
1603 @code{t} is used in the last (or only) element of @var{spec}.
1606 If @var{display} is a list, each element should have the form
1607 @code{(@var{characteristic} @var{value}@dots{})}. Here
1608 @var{characteristic} specifies a way of classifying frames, and the
1609 @var{value}s are possible classifications which @var{display} should
1610 apply to. Here are the possible values of @var{characteristic}:
1614 The kind of window system the frame uses---either @code{graphic} (any
1615 graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console),
1616 @code{w32} (for MS Windows 9X/NT), or @code{tty} (a non-graphics-capable
1620 What kinds of colors the frame supports---either @code{color},
1621 @code{grayscale}, or @code{mono}.
1624 The kind of background---either @code{light} or @code{dark}.
1627 Whether or not the frame can display the face attributes given in
1628 @var{value}@dots{} (@pxref{Face Attributes}). See the documentation
1629 for the function @code{display-supports-face-attributes-p} for more
1630 information on exactly how this testing is done. @xref{Display Face
1634 If an element of @var{display} specifies more than one @var{value} for a
1635 given @var{characteristic}, any of those values is acceptable. If
1636 @var{display} has more than one element, each element should specify a
1637 different @var{characteristic}; then @emph{each} characteristic of the
1638 frame must match one of the @var{value}s specified for it in
1643 Here's how the standard face @code{region} is defined:
1648 `((((type tty) (class color))
1649 (:background "blue" :foreground "white"))
1651 (((type tty) (class mono))
1653 (((class color) (background dark))
1654 (:background "blue"))
1655 (((class color) (background light))
1656 (:background "lightblue"))
1657 (t (:background "gray")))
1659 "Basic face for highlighting the region."
1660 :group 'basic-faces)
1664 Internally, @code{defface} uses the symbol property
1665 @code{face-defface-spec} to record the face attributes specified in
1666 @code{defface}, @code{saved-face} for the attributes saved by the user
1667 with the customization buffer, and @code{face-documentation} for the
1668 documentation string.
1670 @defopt frame-background-mode
1671 This option, if non-@code{nil}, specifies the background type to use for
1672 interpreting face definitions. If it is @code{dark}, then Emacs treats
1673 all frames as if they had a dark background, regardless of their actual
1674 background colors. If it is @code{light}, then Emacs treats all frames
1675 as if they had a light background.
1678 @node Face Attributes
1679 @subsection Face Attributes
1680 @cindex face attributes
1682 The effect of using a face is determined by a fixed set of @dfn{face
1683 attributes}. This table lists all the face attributes, and what they
1684 mean. Note that in general, more than one face can be specified for a
1685 given piece of text; when that happens, the attributes of all the faces
1686 are merged to specify how to display the text. @xref{Merging Faces}.
1688 In Emacs 21, any attribute in a face can have the value
1689 @code{unspecified}. This means the face doesn't specify that attribute.
1690 In face merging, when the first face fails to specify a particular
1691 attribute, that means the next face gets a chance. However, the
1692 @code{default} face must specify all attributes.
1694 Some of these font attributes are meaningful only on certain kinds of
1695 displays---if your display cannot handle a certain attribute, the
1696 attribute is ignored. (The attributes @code{:family}, @code{:width},
1697 @code{:height}, @code{:weight}, and @code{:slant} correspond to parts of
1698 an X Logical Font Descriptor.)
1702 Font family name, or fontset name (@pxref{Fontsets}). If you specify a
1703 font family name, the wild-card characters @samp{*} and @samp{?} are
1707 Relative proportionate width, also known as the character set width or
1708 set width. This should be one of the symbols @code{ultra-condensed},
1709 @code{extra-condensed}, @code{condensed}, @code{semi-condensed},
1710 @code{normal}, @code{semi-expanded}, @code{expanded},
1711 @code{extra-expanded}, or @code{ultra-expanded}.
1714 Either the font height, an integer in units of 1/10 point, a floating
1715 point number specifying the amount by which to scale the height of any
1716 underlying face, or a function, which is called with the old height
1717 (from the underlying face), and should return the new height.
1720 Font weight---a symbol from this series (from most dense to most faint):
1721 @code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
1722 @code{normal}, @code{semi-light}, @code{light}, @code{extra-light},
1723 or @code{ultra-light}.
1725 On a text-only terminal, any weight greater than normal is displayed as
1726 extra bright, and any weight less than normal is displayed as
1727 half-bright (provided the terminal supports the feature).
1730 Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal},
1731 @code{reverse-italic}, or @code{reverse-oblique}.
1733 On a text-only terminal, slanted text is displayed as half-bright, if
1734 the terminal supports the feature.
1737 Foreground color, a string.
1740 Background color, a string.
1742 @item :inverse-video
1743 Whether or not characters should be displayed in inverse video. The
1744 value should be @code{t} (yes) or @code{nil} (no).
1747 The background stipple, a bitmap.
1749 The value can be a string; that should be the name of a file containing
1750 external-format X bitmap data. The file is found in the directories
1751 listed in the variable @code{x-bitmap-file-path}.
1753 Alternatively, the value can specify the bitmap directly, with a list
1754 of the form @code{(@var{width} @var{height} @var{data})}. Here,
1755 @var{width} and @var{height} specify the size in pixels, and
1756 @var{data} is a string containing the raw bits of the bitmap, row by
1757 row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes
1758 in the string (which should be a unibyte string for best results).
1759 This means that each row always occupies at least one whole byte.
1761 If the value is @code{nil}, that means use no stipple pattern.
1763 Normally you do not need to set the stipple attribute, because it is
1764 used automatically to handle certain shades of gray.
1767 Whether or not characters should be underlined, and in what color. If
1768 the value is @code{t}, underlining uses the foreground color of the
1769 face. If the value is a string, underlining uses that color. The
1770 value @code{nil} means do not underline.
1773 Whether or not characters should be overlined, and in what color.
1774 The value is used like that of @code{:underline}.
1776 @item :strike-through
1777 Whether or not characters should be strike-through, and in what
1778 color. The value is used like that of @code{:underline}.
1781 The name of a face from which to inherit attributes, or a list of face
1782 names. Attributes from inherited faces are merged into the face like an
1783 underlying face would be, with higher priority than underlying faces.
1786 Whether or not a box should be drawn around characters, its color, the
1787 width of the box lines, and 3D appearance.
1790 Here are the possible values of the @code{:box} attribute, and what
1798 Draw a box with lines of width 1, in the foreground color.
1801 Draw a box with lines of width 1, in color @var{color}.
1803 @item @code{(:line-width @var{width} :color @var{color} :style @var{style})}
1804 This way you can explicitly specify all aspects of the box. The value
1805 @var{width} specifies the width of the lines to draw; it defaults to 1.
1807 The value @var{color} specifies the color to draw with. The default is
1808 the foreground color of the face for simple boxes, and the background
1809 color of the face for 3D boxes.
1811 The value @var{style} specifies whether to draw a 3D box. If it is
1812 @code{released-button}, the box looks like a 3D button that is not being
1813 pressed. If it is @code{pressed-button}, the box looks like a 3D button
1814 that is being pressed. If it is @code{nil} or omitted, a plain 2D box
1818 The attributes @code{:overline}, @code{:strike-through} and
1819 @code{:box} are new in Emacs 21. The attributes @code{:family},
1820 @code{:height}, @code{:width}, @code{:weight}, @code{:slant} are also
1821 new; previous versions used the following attributes, now semi-obsolete,
1822 to specify some of the same information:
1826 This attribute specifies the font name.
1829 A non-@code{nil} value specifies a bold font.
1832 A non-@code{nil} value specifies an italic font.
1835 For compatibility, you can still set these ``attributes'' in Emacs 21,
1836 even though they are not real face attributes. Here is what that does:
1840 You can specify an X font name as the ``value'' of this ``attribute'';
1841 that sets the @code{:family}, @code{:width}, @code{:height},
1842 @code{:weight}, and @code{:slant} attributes according to the font name.
1844 If the value is a pattern with wildcards, the first font that matches
1845 the pattern is used to set these attributes.
1848 A non-@code{nil} makes the face bold; @code{nil} makes it normal.
1849 This actually works by setting the @code{:weight} attribute.
1852 A non-@code{nil} makes the face italic; @code{nil} makes it normal.
1853 This actually works by setting the @code{:slant} attribute.
1856 @defvar x-bitmap-file-path
1857 This variable specifies a list of directories for searching
1858 for bitmap files, for the @code{:stipple} attribute.
1861 @defun bitmap-spec-p object
1862 This returns @code{t} if @var{object} is a valid bitmap specification,
1863 suitable for use with @code{:stipple} (see above). It returns
1864 @code{nil} otherwise.
1867 @node Attribute Functions
1868 @subsection Face Attribute Functions
1870 You can modify the attributes of an existing face with the following
1871 functions. If you specify @var{frame}, they affect just that frame;
1872 otherwise, they affect all frames as well as the defaults that apply to
1875 @tindex set-face-attribute
1876 @defun set-face-attribute face frame &rest arguments
1877 This function sets one or more attributes of face @var{face}
1878 for frame @var{frame}. If @var{frame} is @code{nil}, it sets
1879 the attribute for all frames, and the defaults for new frames.
1881 The extra arguments @var{arguments} specify the attributes to set, and
1882 the values for them. They should consist of alternating attribute names
1883 (such as @code{:family} or @code{:underline}) and corresponding values.
1887 (set-face-attribute 'foo nil
1894 sets the attributes @code{:width}, @code{:weight} and @code{:underline}
1895 to the corresponding values.
1898 @tindex face-attribute
1899 @defun face-attribute face attribute &optional frame inherit
1900 This returns the value of the @var{attribute} attribute of face
1901 @var{face} on @var{frame}. If @var{frame} is @code{nil},
1902 that means the selected frame (@pxref{Input Focus}).
1904 If @var{frame} is @code{t}, the value is the default for
1905 @var{face} for new frames.
1907 If @var{inherit} is @code{nil}, only attributes directly defined by
1908 @var{face} are considered, so the return value may be
1909 @code{unspecified}, or a relative value. If @var{inherit} is
1910 non-@code{nil}, @var{face}'s definition of @var{attribute} is merged
1911 with the faces specified by its @code{:inherit} attribute; however the
1912 return value may still be @code{unspecified} or relative. If
1913 @var{inherit} is a face or a list of faces, then the result is further
1914 merged with that face (or faces), until it becomes specified and
1917 To ensure that the return value is always specified and absolute, use
1918 a value of @code{default} for @var{inherit}; this will resolve any
1919 unspecified or relative values by merging with the @code{default} face
1920 (which is always completely specified).
1925 (face-attribute 'bold :weight)
1930 The functions above did not exist before Emacs 21. For compatibility
1931 with older Emacs versions, you can use the following functions to set
1932 and examine the face attributes which existed in those versions.
1934 @tindex face-attribute-relative-p
1935 @defun face-attribute-relative-p attribute value
1936 This function returns non-@code{nil} if @var{value}, when used as
1937 the value of the face attribute @var{attribute}, is relative (that is,
1938 if it modifies an underlying or inherited value of @var{attribute}).
1941 @tindex merge-face-attribute
1942 @defun merge-face-attribute attribute value1 value2
1943 If @var{value1} is a relative value for the face attribute
1944 @var{attribute}, returns it merged with the underlying value
1945 @var{value2}; otherwise, if @var{value1} is an absolute value for the
1946 face attribute @var{attribute}, returns @var{value1} unchanged.
1949 @defun set-face-foreground face color &optional frame
1950 @defunx set-face-background face color &optional frame
1951 These functions set the foreground (or background, respectively) color
1952 of face @var{face} to @var{color}. The argument @var{color} should be a
1953 string, the name of a color.
1955 Certain shades of gray are implemented by stipple patterns on
1956 black-and-white screens.
1959 @defun set-face-stipple face pattern &optional frame
1960 This function sets the background stipple pattern of face @var{face}
1961 to @var{pattern}. The argument @var{pattern} should be the name of a
1962 stipple pattern defined by the X server, or actual bitmap data
1963 (@pxref{Face Attributes}), or @code{nil} meaning don't use stipple.
1965 Normally there is no need to pay attention to stipple patterns, because
1966 they are used automatically to handle certain shades of gray.
1969 @defun set-face-font face font &optional frame
1970 This function sets the font of face @var{face}.
1972 In Emacs 21, this actually sets the attributes @code{:family},
1973 @code{:width}, @code{:height}, @code{:weight}, and @code{:slant}
1974 according to the font name @var{font}.
1976 In Emacs 20, this sets the font attribute. Once you set the font
1977 explicitly, the bold and italic attributes cease to have any effect,
1978 because the precise font that you specified is used.
1981 @defun set-face-bold-p face bold-p &optional frame
1982 This function specifies whether @var{face} should be bold. If
1983 @var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no.
1985 In Emacs 21, this sets the @code{:weight} attribute.
1986 In Emacs 20, it sets the @code{:bold} attribute.
1989 @defun set-face-italic-p face italic-p &optional frame
1990 This function specifies whether @var{face} should be italic. If
1991 @var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no.
1993 In Emacs 21, this sets the @code{:slant} attribute.
1994 In Emacs 20, it sets the @code{:italic} attribute.
1997 @defun set-face-underline-p face underline-p &optional frame
1998 This function sets the underline attribute of face @var{face}.
1999 Non-@code{nil} means do underline; @code{nil} means don't.
2002 @defun invert-face face &optional frame
2003 This function inverts the @code{:inverse-video} attribute of face
2004 @var{face}. If the attribute is @code{nil}, this function sets it to
2005 @code{t}, and vice versa.
2008 These functions examine the attributes of a face. If you don't
2009 specify @var{frame}, they refer to the default data for new frames.
2010 They return the symbol @code{unspecified} if the face doesn't define any
2011 value for that attribute.
2013 @defun face-foreground face &optional frame inherit
2014 @defunx face-background face &optional frame
2015 These functions return the foreground color (or background color,
2016 respectively) of face @var{face}, as a string.
2018 If @var{inherit} is nil, only a color directly defined by the face is
2019 returned. If @var{inherit} is non-nil, any faces specified by its
2020 @code{:inherit} attribute are considered as well, and if @var{inherit}
2021 is a face or a list of faces, then they are also considered, until a
2022 specified color is found. To ensure that the return value is always
2023 specified, use a value of @code{default} for @var{inherit}.
2026 @defun face-stipple face &optional frame inherit
2027 This function returns the name of the background stipple pattern of face
2028 @var{face}, or @code{nil} if it doesn't have one.
2030 If @var{inherit} is @code{nil}, only a stipple directly defined by the
2031 face is returned. If @var{inherit} is non-@code{nil}, any faces
2032 specified by its @code{:inherit} attribute are considered as well, and
2033 if @var{inherit} is a face or a list of faces, then they are also
2034 considered, until a specified stipple is found. To ensure that the
2035 return value is always specified, use a value of @code{default} for
2039 @defun face-font face &optional frame
2040 This function returns the name of the font of face @var{face}.
2043 @defun face-bold-p face &optional frame
2044 This function returns @code{t} if @var{face} is bold---that is, if it is
2045 bolder than normal. It returns @code{nil} otherwise.
2048 @defun face-italic-p face &optional frame
2049 This function returns @code{t} if @var{face} is italic or oblique,
2050 @code{nil} otherwise.
2053 @defun face-underline-p face &optional frame
2054 This function returns the @code{:underline} attribute of face @var{face}.
2057 @defun face-inverse-video-p face &optional frame
2058 This function returns the @code{:inverse-video} attribute of face @var{face}.
2062 @subsection Merging Faces for Display
2064 Here are the ways to specify which faces to use for display of text:
2068 With defaults. The @code{default} face is used as the ultimate
2069 default for all text. (In Emacs 19 and 20, the @code{default}
2070 face is used only when no other face is specified.)
2072 For a mode line or header line, the face @code{modeline} or
2073 @code{header-line} is used just before @code{default}.
2076 With text properties. A character can have a @code{face} property; if
2077 so, the faces and face attributes specified there apply. @xref{Special
2080 If the character has a @code{mouse-face} property, that is used instead
2081 of the @code{face} property when the mouse is ``near enough'' to the
2085 With overlays. An overlay can have @code{face} and @code{mouse-face}
2086 properties too; they apply to all the text covered by the overlay.
2089 With a region that is active. In Transient Mark mode, the region is
2090 highlighted with the face @code{region} (@pxref{Standard Faces}).
2093 With special glyphs. Each glyph can specify a particular face
2094 number. @xref{Glyphs}.
2097 If these various sources together specify more than one face for a
2098 particular character, Emacs merges the attributes of the various faces
2099 specified. The attributes of the faces of special glyphs come first;
2100 then comes the face for region highlighting, if appropriate;
2101 then come attributes of faces from overlays, followed by those from text
2102 properties, and last the default face.
2104 When multiple overlays cover one character, an overlay with higher
2105 priority overrides those with lower priority. @xref{Overlays}.
2107 In Emacs 20, if an attribute such as the font or a color is not
2108 specified in any of the above ways, the frame's own font or color is
2109 used. In newer Emacs versions, this cannot happen, because the
2110 @code{default} face specifies all attributes---in fact, the frame's own
2111 font and colors are synonymous with those of the default face.
2113 @node Font Selection
2114 @subsection Font Selection
2116 @dfn{Selecting a font} means mapping the specified face attributes for
2117 a character to a font that is available on a particular display. The
2118 face attributes, as determined by face merging, specify most of the
2119 font choice, but not all. Part of the choice depends on what character
2122 If the face specifies a fontset name, that fontset determines a
2123 pattern for fonts of the given charset. If the face specifies a font
2124 family, a font pattern is constructed.
2126 Emacs tries to find an available font for the given face attributes
2127 and character's registry and encoding. If there is a font that matches
2128 exactly, it is used, of course. The hard case is when no available font
2129 exactly fits the specification. Then Emacs looks for one that is
2130 ``close''---one attribute at a time. You can specify the order to
2131 consider the attributes. In the case where a specified font family is
2132 not available, you can specify a set of mappings for alternatives to
2135 @defvar face-font-selection-order
2136 @tindex face-font-selection-order
2137 This variable specifies the order of importance of the face attributes
2138 @code{:width}, @code{:height}, @code{:weight}, and @code{:slant}. The
2139 value should be a list containing those four symbols, in order of
2140 decreasing importance.
2142 Font selection first finds the best available matches for the first
2143 attribute listed; then, among the fonts which are best in that way, it
2144 searches for the best matches in the second attribute, and so on.
2146 The attributes @code{:weight} and @code{:width} have symbolic values in
2147 a range centered around @code{normal}. Matches that are more extreme
2148 (farther from @code{normal}) are somewhat preferred to matches that are
2149 less extreme (closer to @code{normal}); this is designed to ensure that
2150 non-normal faces contrast with normal ones, whenever possible.
2152 The default is @code{(:width :height :weight :slant)}, which means first
2153 find the fonts closest to the specified @code{:width}, then---among the
2154 fonts with that width---find a best match for the specified font height,
2157 One example of a case where this variable makes a difference is when the
2158 default font has no italic equivalent. With the default ordering, the
2159 @code{italic} face will use a non-italic font that is similar to the
2160 default one. But if you put @code{:slant} before @code{:height}, the
2161 @code{italic} face will use an italic font, even if its height is not
2165 @defvar face-font-family-alternatives
2166 @tindex face-font-family-alternatives
2167 This variable lets you specify alternative font families to try, if a
2168 given family is specified and doesn't exist. Each element should have
2172 (@var{family} @var{alternate-families}@dots{})
2175 If @var{family} is specified but not available, Emacs will try the other
2176 families given in @var{alternate-families}, one by one, until it finds a
2177 family that does exist.
2180 @defvar face-font-registry-alternatives
2181 @tindex face-font-registry-alternatives
2182 This variable lets you specify alternative font registries to try, if a
2183 given registry is specified and doesn't exist. Each element should have
2187 (@var{registry} @var{alternate-registries}@dots{})
2190 If @var{registry} is specified but not available, Emacs will try the
2191 other registries given in @var{alternate-registries}, one by one,
2192 until it finds a registry that does exist.
2195 Emacs can make use of scalable fonts, but by default it does not use
2196 them, since the use of too many or too big scalable fonts can crash
2199 @defvar scalable-fonts-allowed
2200 @tindex scalable-fonts-allowed
2201 This variable controls which scalable fonts to use. A value of
2202 @code{nil}, the default, means do not use scalable fonts. @code{t}
2203 means to use any scalable font that seems appropriate for the text.
2205 Otherwise, the value must be a list of regular expressions. Then a
2206 scalable font is enabled for use if its name matches any regular
2207 expression in the list. For example,
2210 (setq scalable-fonts-allowed '("muleindian-2$"))
2214 allows the use of scalable fonts with registry @code{muleindian-2}.
2217 @defun clear-face-cache &optional unload-p
2218 @tindex clear-face-cache
2219 This function clears the face cache for all frames.
2220 If @var{unload-p} is non-@code{nil}, that means to unload
2221 all unused fonts as well.
2224 @defvar face-font-rescale-alist
2225 This variable specifies scaling for certain faces. Its value should
2226 be a list of elements of the form
2229 (@var{fontname-regexp} . @var{scale-factor})
2232 If @var{fontname-regexp} matches the font name that is about to be
2233 used, this says to choose a larger similar font according to the
2234 factor @var{scale-factor}. You would use this feature to normalize
2235 the font size if certain fonts are bigger or smaller than their
2236 nominal heights and widths would suggest.
2239 @node Face Functions
2240 @subsection Functions for Working with Faces
2242 Here are additional functions for creating and working with faces.
2244 @defun make-face name
2245 This function defines a new face named @var{name}, initially with all
2246 attributes @code{nil}. It does nothing if there is already a face named
2251 This function returns a list of all defined face names.
2254 @defun copy-face old-face new-name &optional frame new-frame
2255 This function defines the face @var{new-name} as a copy of the existing
2256 face named @var{old-face}. It creates the face @var{new-name} if that
2257 doesn't already exist.
2259 If the optional argument @var{frame} is given, this function applies
2260 only to that frame. Otherwise it applies to each frame individually,
2261 copying attributes from @var{old-face} in each frame to @var{new-face}
2264 If the optional argument @var{new-frame} is given, then @code{copy-face}
2265 copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
2270 This function returns the face number of face @var{face}.
2273 @defun face-documentation face
2274 This function returns the documentation string of face @var{face}, or
2275 @code{nil} if none was specified for it.
2278 @defun face-equal face1 face2 &optional frame
2279 This returns @code{t} if the faces @var{face1} and @var{face2} have the
2280 same attributes for display.
2283 @defun face-differs-from-default-p face &optional frame
2284 This returns @code{t} if the face @var{face} displays differently from
2285 the default face. A face is considered to be ``the same'' as the
2286 default face if each attribute is either the same as that of the default
2287 face, or unspecified (meaning to inherit from the default).
2291 @subsection Automatic Face Assignment
2292 @cindex automatic face assignment
2293 @cindex faces, automatic choice
2295 @cindex Font-Lock mode
2296 Starting with Emacs 21, a hook is available for automatically
2297 assigning faces to text in the buffer. This hook is used for part of
2298 the implementation of Font-Lock mode.
2300 @tindex fontification-functions
2301 @defvar fontification-functions
2302 This variable holds a list of functions that are called by Emacs
2303 redisplay as needed to assign faces automatically to text in the buffer.
2305 The functions are called in the order listed, with one argument, a
2306 buffer position @var{pos}. Each function should attempt to assign faces
2307 to the text in the current buffer starting at @var{pos}.
2309 Each function should record the faces they assign by setting the
2310 @code{face} property. It should also add a non-@code{nil}
2311 @code{fontified} property for all the text it has assigned faces to.
2312 That property tells redisplay that faces have been assigned to that text
2315 It is probably a good idea for each function to do nothing if the
2316 character after @var{pos} already has a non-@code{nil} @code{fontified}
2317 property, but this is not required. If one function overrides the
2318 assignments made by a previous one, the properties as they are
2319 after the last function finishes are the ones that really matter.
2321 For efficiency, we recommend writing these functions so that they
2322 usually assign faces to around 400 to 600 characters at each call.
2326 @subsection Looking Up Fonts
2328 @defun x-list-fonts pattern &optional face frame maximum
2329 This function returns a list of available font names that match
2330 @var{pattern}. If the optional arguments @var{face} and @var{frame} are
2331 specified, then the list is limited to fonts that are the same size as
2332 @var{face} currently is on @var{frame}.
2334 The argument @var{pattern} should be a string, perhaps with wildcard
2335 characters: the @samp{*} character matches any substring, and the
2336 @samp{?} character matches any single character. Pattern matching
2337 of font names ignores case.
2339 If you specify @var{face} and @var{frame}, @var{face} should be a face name
2340 (a symbol) and @var{frame} should be a frame.
2342 The optional argument @var{maximum} sets a limit on how many fonts to
2343 return. If this is non-@code{nil}, then the return value is truncated
2344 after the first @var{maximum} matching fonts. Specifying a small value
2345 for @var{maximum} can make this function much faster, in cases where
2346 many fonts match the pattern.
2349 These additional functions are available starting in Emacs 21.
2351 @defun x-family-fonts &optional family frame
2352 @tindex x-family-fonts
2353 This function returns a list describing the available fonts for family
2354 @var{family} on @var{frame}. If @var{family} is omitted or @code{nil},
2355 this list applies to all families, and therefore, it contains all
2356 available fonts. Otherwise, @var{family} must be a string; it may
2357 contain the wildcards @samp{?} and @samp{*}.
2359 The list describes the display that @var{frame} is on; if @var{frame} is
2360 omitted or @code{nil}, it applies to the selected frame's display
2361 (@pxref{Input Focus}).
2363 The list contains a vector of the following form for each font:
2366 [@var{family} @var{width} @var{point-size} @var{weight} @var{slant}
2367 @var{fixed-p} @var{full} @var{registry-and-encoding}]
2370 The first five elements correspond to face attributes; if you
2371 specify these attributes for a face, it will use this font.
2373 The last three elements give additional information about the font.
2374 @var{fixed-p} is non-@code{nil} if the font is fixed-pitch.
2375 @var{full} is the full name of the font, and
2376 @var{registry-and-encoding} is a string giving the registry and
2377 encoding of the font.
2379 The result list is sorted according to the current face font sort order.
2382 @defun x-font-family-list &optional frame
2383 @tindex x-font-family-list
2384 This function returns a list of the font families available for
2385 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, it
2386 describes the selected frame's display (@pxref{Input Focus}).
2388 The value is a list of elements of this form:
2391 (@var{family} . @var{fixed-p})
2395 Here @var{family} is a font family, and @var{fixed-p} is
2396 non-@code{nil} if fonts of that family are fixed-pitch.
2399 @defvar font-list-limit
2400 @tindex font-list-limit
2401 This variable specifies maximum number of fonts to consider in font
2402 matching. The function @code{x-family-fonts} will not return more than
2403 that many fonts, and font selection will consider only that many fonts
2404 when searching a matching font for face attributes. The default is
2409 @subsection Fontsets
2411 A @dfn{fontset} is a list of fonts, each assigned to a range of
2412 character codes. An individual font cannot display the whole range of
2413 characters that Emacs supports, but a fontset can. Fontsets have names,
2414 just as fonts do, and you can use a fontset name in place of a font name
2415 when you specify the ``font'' for a frame or a face. Here is
2416 information about defining a fontset under Lisp program control.
2418 @defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
2419 This function defines a new fontset according to the specification
2420 string @var{fontset-spec}. The string should have this format:
2423 @var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
2427 Whitespace characters before and after the commas are ignored.
2429 The first part of the string, @var{fontpattern}, should have the form of
2430 a standard X font name, except that the last two fields should be
2431 @samp{fontset-@var{alias}}.
2433 The new fontset has two names, one long and one short. The long name is
2434 @var{fontpattern} in its entirety. The short name is
2435 @samp{fontset-@var{alias}}. You can refer to the fontset by either
2436 name. If a fontset with the same name already exists, an error is
2437 signaled, unless @var{noerror} is non-@code{nil}, in which case this
2438 function does nothing.
2440 If optional argument @var{style-variant-p} is non-@code{nil}, that says
2441 to create bold, italic and bold-italic variants of the fontset as well.
2442 These variant fontsets do not have a short name, only a long one, which
2443 is made by altering @var{fontpattern} to indicate the bold or italic
2446 The specification string also says which fonts to use in the fontset.
2447 See below for the details.
2450 The construct @samp{@var{charset}:@var{font}} specifies which font to
2451 use (in this fontset) for one particular character set. Here,
2452 @var{charset} is the name of a character set, and @var{font} is the font
2453 to use for that character set. You can use this construct any number of
2454 times in the specification string.
2456 For the remaining character sets, those that you don't specify
2457 explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
2458 @samp{fontset-@var{alias}} with a value that names one character set.
2459 For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced
2460 with @samp{ISO8859-1}.
2462 In addition, when several consecutive fields are wildcards, Emacs
2463 collapses them into a single wildcard. This is to prevent use of
2464 auto-scaled fonts. Fonts made by scaling larger fonts are not usable
2465 for editing, and scaling a smaller font is not useful because it is
2466 better to use the smaller font in its own size, which Emacs does.
2468 Thus if @var{fontpattern} is this,
2471 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
2475 the font specification for @acronym{ASCII} characters would be this:
2478 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
2482 and the font specification for Chinese GB2312 characters would be this:
2485 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
2488 You may not have any Chinese font matching the above font
2489 specification. Most X distributions include only Chinese fonts that
2490 have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
2491 such a case, @samp{Fontset-@var{n}} can be specified as below:
2494 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
2495 chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
2499 Then, the font specifications for all but Chinese GB2312 characters have
2500 @samp{fixed} in the @var{family} field, and the font specification for
2501 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
2504 @defun set-fontset-font name character fontname &optional frame
2505 This function modifies the existing fontset @var{name} to
2506 use the font name @var{fontname} for the character @var{character}.
2508 If @var{name} is @code{nil}, this function modifies the default
2509 fontset, whose short name is @samp{fontset-default}.
2511 @var{character} may be a cons; @code{(@var{from} . @var{to})}, where
2512 @var{from} and @var{to} are non-generic characters. In that case, use
2513 @var{fontname} for all characters in the range @var{from} and @var{to}
2516 @var{character} may be a charset. In that case, use
2517 @var{fontname} for all character in the charsets.
2519 @var{fontname} may be a cons; @code{(@var{family} . @var{registry})},
2520 where @var{family} is a family name of a font (possibly including a
2521 foundry name at the head), @var{registry} is a registry name of a font
2522 (possibly including an encoding name at the tail).
2524 For instance, this changes the default fontset to use a font of which
2525 registry name is @samp{JISX0208.1983} for all characters belonging to
2526 the charset @code{japanese-jisx0208}.
2529 (set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
2534 @defun char-displayable-p char
2535 This function returns @code{t} if Emacs ought to be able to display
2536 @var{char}. More precisely, if the selected frame's fontset has a
2537 font to display the character set that @var{char} belongs to.
2539 Fontsets can specify a font on a per-character basis; when the fontset
2540 does that, this function's value may not be accurate.
2547 The @dfn{fringes} of a window are thin vertical strips down the
2548 sides that are used for displaying bitmaps that indicate truncation,
2549 continuation, horizontal scrolling, and the overlay arrow. The
2550 fringes normally appear between the display margins and the window
2551 text, but you can put them outside the display margins for a specific
2552 buffer by setting @code{fringes-outside-margins} buffer-locally to a
2553 non-@code{nil} value.
2555 @defvar fringes-outside-margins
2556 If the value is non-@code{nil}, the frames appear outside
2557 the display margins.
2560 @defvar left-fringe-width
2561 This variable, if non-@code{nil}, specifies the width of the left
2565 @defvar right-fringe-width
2566 This variable, if non-@code{nil}, specifies the width of the right
2570 The values of these variables take effect when you display the
2571 buffer in a window. If you change them while the buffer is visible,
2572 you can call @code{set-window-buffer} to display it once again in the
2573 same window, to make the changes take effect.
2575 @defun set-window-fringes window left &optional right outside-margins
2576 This function sets the fringe widths of window @var{window}.
2577 If @var{window} is @code{nil}, the selected window is used.
2579 The argument @var{left} specifies the width in pixels of the left
2580 fringe, and likewise @var{right} for the right fringe. A value of
2581 @code{nil} for either one stands for the default width. If
2582 @var{outside-margins} is non-@code{nil}, that specifies that fringes
2583 should appear outside of the display margins.
2586 @defun window-fringes &optional window
2587 This function returns information about the fringes of a window
2588 @var{window}. If @var{window} is omitted or @code{nil}, the selected
2589 window is used. The value has the form @code{(@var{left-width}
2590 @var{right-width} @var{frames-outside-margins})}.
2594 @section Scroll Bars
2596 Normally the frame parameter @code{vertical-scroll-bars} controls
2597 whether the windows in the frame have vertical scroll bars. A
2598 non-@code{nil} parameter value means they do. The frame parameter
2599 @code{scroll-bar-width} specifies how wide they are (@code{nil}
2600 meaning the default). @xref{Window Frame Parameters}.
2602 You can also control this for individual windows. Call the function
2603 @code{set-window-scroll-bars} to specify what to do for a specific window:
2605 @defun set-window-scroll-bars window width &optional vertical-type horizontal-type
2606 Set width and type of scroll bars of window @var{window}.
2607 If @var{window} is @code{nil}, the selected window is used.
2608 @var{width} specifies the scroll bar width in pixels (@code{nil} means
2609 use whatever is specified for width for the frame).
2610 @var{vertical-type} specifies whether to have a vertical scroll bar
2611 and, if so, where. The possible values are @code{left}, @code{right}
2612 and @code{nil}, just like the values of the
2613 @code{vertical-scroll-bars} frame parameter.
2615 The argument @var{horizontal-type} is meant to specify whether and
2616 where to have horizontal scroll bars, but since they are not
2617 implemented, it has no effect.
2620 @defun window-scroll-bars &optional window
2621 Report the width and type of scroll bars specified for @var{window}.
2622 If @var{window} is omitted or @code{nil}, the selected window is used.
2623 The value is a list of the form @code{(@var{width}
2624 @var{cols} @var{vertical-type} @var{horizontal-type})}. The value
2625 @var{width} is the value that was specified for the width (which may
2626 be @code{nil}); @var{cols} is the number of columns that the scroll
2627 bar actually occupies.
2629 @var{horizontal-type} is not actually meaningful.
2632 If you don't specify these values for a window with
2633 @code{set-window-scroll-bars}, the buffer-local variables
2634 @code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being
2635 displayed control the window's vertical scroll bars. The function
2636 @code{set-window-buffer} examines these variables. If you change them
2637 in a buffer that is already visible in a window, you can make the
2638 window take note of the new values by calling @code{set-window-buffer}
2639 specifying the same buffer that is already displayed.
2641 @node Display Property
2642 @section The @code{display} Property
2643 @cindex display specification
2644 @kindex display @r{(text property)}
2646 The @code{display} text property (or overlay property) is used to
2647 insert images into text, and also control other aspects of how text
2648 displays. These features are available starting in Emacs 21. The value
2649 of the @code{display} property should be a display specification, or a
2650 list or vector containing several display specifications. The rest of
2651 this section describes several kinds of display specifications and what
2655 * Specified Space:: Displaying one space with a specified width.
2656 * Other Display Specs:: Displaying an image; magnifying text; moving it
2657 up or down on the page; adjusting the width
2658 of spaces within text.
2659 * Display Margins:: Displaying text or images to the side of the main text.
2660 * Conditional Display:: Making any of the above features conditional
2661 depending on some Lisp expression.
2664 @node Specified Space
2665 @subsection Specified Spaces
2666 @cindex spaces, specified height or width
2667 @cindex specified spaces
2668 @cindex variable-width spaces
2670 To display a space of specified width and/or height, use a display
2671 specification of the form @code{(space . @var{props})}, where
2672 @var{props} is a property list (a list of alternating properties and
2673 values). You can put this property on one or more consecutive
2674 characters; a space of the specified height and width is displayed in
2675 place of @emph{all} of those characters. These are the properties you
2676 can use in @var{props} to specify the weight of the space:
2679 @item :width @var{width}
2680 Specifies that the space width should be @var{width} times the normal
2681 character width. @var{width} can be an integer or floating point
2684 @item :relative-width @var{factor}
2685 Specifies that the width of the stretch should be computed from the
2686 first character in the group of consecutive characters that have the
2687 same @code{display} property. The space width is the width of that
2688 character, multiplied by @var{factor}.
2690 @item :align-to @var{hpos}
2691 Specifies that the space should be wide enough to reach @var{hpos}. The
2692 value @var{hpos} is measured in units of the normal character width. It
2693 may be an integer or a floating point number.
2696 You should use one and only one of the above properties. You can
2697 also specify the height of the space, with other properties:
2700 @item :height @var{height}
2701 Specifies the height of the space, as @var{height},
2702 measured in terms of the normal line height.
2704 @item :relative-height @var{factor}
2705 Specifies the height of the space, multiplying the ordinary height
2706 of the text having this display specification by @var{factor}.
2708 @item :ascent @var{ascent}
2709 Specifies that @var{ascent} percent of the height of the space should be
2710 considered as the ascent of the space---that is, the part above the
2711 baseline. The value of @var{ascent} must be a non-negative number no
2715 Don't use both @code{:height} and @code{:relative-height} together.
2717 @node Other Display Specs
2718 @subsection Other Display Specifications
2721 @item (image . @var{image-props})
2722 This is in fact an image descriptor (@pxref{Images}). When used as a
2723 display specification, it means to display the image instead of the text
2724 that has the display specification.
2726 @item ((margin nil) @var{string})
2728 A display specification of this form means to display @var{string}
2729 instead of the text that has the display specification, at the same
2730 position as that text. This is a special case of marginal display
2731 (@pxref{Display Margins}).
2733 Recursive display specifications are not supported---string display
2734 specifications must not have @code{display} properties themselves.
2736 @item (space-width @var{factor})
2737 This display specification affects all the space characters within the
2738 text that has the specification. It displays all of these spaces
2739 @var{factor} times as wide as normal. The element @var{factor} should
2740 be an integer or float. Characters other than spaces are not affected
2741 at all; in particular, this has no effect on tab characters.
2743 @item (height @var{height})
2744 This display specification makes the text taller or shorter.
2745 Here are the possibilities for @var{height}:
2748 @item @code{(+ @var{n})}
2749 This means to use a font that is @var{n} steps larger. A ``step'' is
2750 defined by the set of available fonts---specifically, those that match
2751 what was otherwise specified for this text, in all attributes except
2752 height. Each size for which a suitable font is available counts as
2753 another step. @var{n} should be an integer.
2755 @item @code{(- @var{n})}
2756 This means to use a font that is @var{n} steps smaller.
2758 @item a number, @var{factor}
2759 A number, @var{factor}, means to use a font that is @var{factor} times
2760 as tall as the default font.
2762 @item a symbol, @var{function}
2763 A symbol is a function to compute the height. It is called with the
2764 current height as argument, and should return the new height to use.
2766 @item anything else, @var{form}
2767 If the @var{height} value doesn't fit the previous possibilities, it is
2768 a form. Emacs evaluates it to get the new height, with the symbol
2769 @code{height} bound to the current specified font height.
2772 @item (raise @var{factor})
2773 This kind of display specification raises or lowers the text
2774 it applies to, relative to the baseline of the line.
2776 @var{factor} must be a number, which is interpreted as a multiple of the
2777 height of the affected text. If it is positive, that means to display
2778 the characters raised. If it is negative, that means to display them
2781 If the text also has a @code{height} display specification, that does
2782 not affect the amount of raising or lowering, which is based on the
2783 faces used for the text.
2786 @node Display Margins
2787 @subsection Displaying in the Margins
2788 @cindex display margins
2789 @cindex margins, display
2791 A buffer can have blank areas called @dfn{display margins} on the left
2792 and on the right. Ordinary text never appears in these areas, but you
2793 can put things into the display margins using the @code{display}
2796 To put text in the left or right display margin of the window, use a
2797 display specification of the form @code{(margin right-margin)} or
2798 @code{(margin left-margin)} on it. To put an image in a display margin,
2799 use that display specification along with the display specification for
2800 the image. Unfortunately, there is currently no way to make
2801 text or images in the margin mouse-sensitive.
2803 If you put such a display specification directly on text in the
2804 buffer, the specified margin display appears @emph{instead of} that
2805 buffer text itself. To put something in the margin @emph{in
2806 association with} certain buffer text without preventing or altering
2807 the display of that text, put a @code{before-string} property on the
2808 text and put the display specification on the contents of the
2811 Before the display margins can display anything, you must give
2812 them a nonzero width. The usual way to do that is to set these
2815 @defvar left-margin-width
2816 @tindex left-margin-width
2817 This variable specifies the width of the left margin.
2818 It is buffer-local in all buffers.
2821 @defvar right-margin-width
2822 @tindex right-margin-width
2823 This variable specifies the width of the right margin.
2824 It is buffer-local in all buffers.
2827 Setting these variables does not immediately affect the window. These
2828 variables are checked when a new buffer is displayed in the window.
2829 Thus, you can make changes take effect by calling
2830 @code{set-window-buffer}.
2832 You can also set the margin widths immediately.
2834 @defun set-window-margins window left &optional right
2835 @tindex set-window-margins
2836 This function specifies the margin widths for window @var{window}.
2837 The argument @var{left} controls the left margin and
2838 @var{right} controls the right margin (default @code{0}).
2841 @defun window-margins &optional window
2842 @tindex window-margins
2843 This function returns the left and right margins of @var{window}
2844 as a cons cell of the form @code{(@var{left} . @var{right})}.
2845 If @var{window} is @code{nil}, the selected window is used.
2848 @node Conditional Display
2849 @subsection Conditional Display Specifications
2850 @cindex conditional display specifications
2852 You can make any display specification conditional. To do that,
2853 package it in another list of the form @code{(when @var{condition} .
2854 @var{spec})}. Then the specification @var{spec} applies only when
2855 @var{condition} evaluates to a non-@code{nil} value. During the
2856 evaluation, @code{object} is bound to the string or buffer having the
2857 conditional @code{display} property. @code{position} and
2858 @code{buffer-position} are bound to the position within @code{object}
2859 and the buffer position where the @code{display} property was found,
2860 respectively. Both positions can be different when @code{object} is a
2865 @cindex images in buffers
2867 To display an image in an Emacs buffer, you must first create an image
2868 descriptor, then use it as a display specifier in the @code{display}
2869 property of text that is displayed (@pxref{Display Property}). Like the
2870 @code{display} property, this feature is available starting in Emacs 21.
2872 Emacs can display a number of different image formats; some of them
2873 are supported only if particular support libraries are installed on your
2874 machine. The supported image formats include XBM, XPM (needing the
2875 libraries @code{libXpm} version 3.4k and @code{libz}), GIF (needing
2876 @code{libungif} 4.1.0), Postscript, PBM, JPEG (needing the
2877 @code{libjpeg} library version v6a), TIFF (needing @code{libtiff} v3.4),
2878 and PNG (needing @code{libpng} 1.0.2).
2880 You specify one of these formats with an image type symbol. The image
2881 type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
2882 @code{pbm}, @code{jpeg}, @code{tiff}, and @code{png}.
2885 This variable contains a list of those image type symbols that are
2886 supported in the current configuration.
2890 * Image Descriptors:: How to specify an image for use in @code{:display}.
2891 * XBM Images:: Special features for XBM format.
2892 * XPM Images:: Special features for XPM format.
2893 * GIF Images:: Special features for GIF format.
2894 * Postscript Images:: Special features for Postscript format.
2895 * Other Image Types:: Various other formats are supported.
2896 * Defining Images:: Convenient ways to define an image for later use.
2897 * Showing Images:: Convenient ways to display an image once it is defined.
2898 * Image Cache:: Internal mechanisms of image display.
2901 @node Image Descriptors
2902 @subsection Image Descriptors
2903 @cindex image descriptor
2905 An image description is a list of the form @code{(image
2906 . @var{props})}, where @var{props} is a property list containing
2907 alternating keyword symbols (symbols whose names start with a colon) and
2908 their values. You can use any Lisp object as a property, but the only
2909 properties that have any special meaning are certain symbols, all of
2912 Every image descriptor must contain the property @code{:type
2913 @var{type}} to specify the format of the image. The value of @var{type}
2914 should be an image type symbol; for example, @code{xpm} for an image in
2917 Here is a list of other properties that are meaningful for all image
2921 @item :file @var{file}
2922 The @code{:file} property specifies to load the image from file
2923 @var{file}. If @var{file} is not an absolute file name, it is expanded
2924 in @code{data-directory}.
2926 @item :data @var{data}
2927 The @code{:data} property specifies the actual contents of the image.
2928 Each image must use either @code{:data} or @code{:file}, but not both.
2929 For most image types, the value of the @code{:data} property should be a
2930 string containing the image data; we recommend using a unibyte string.
2932 Before using @code{:data}, look for further information in the section
2933 below describing the specific image format. For some image types,
2934 @code{:data} may not be supported; for some, it allows other data types;
2935 for some, @code{:data} alone is not enough, so you need to use other
2936 image properties along with @code{:data}.
2938 @item :margin @var{margin}
2939 The @code{:margin} property specifies how many pixels to add as an
2940 extra margin around the image. The value, @var{margin}, must be a
2941 non-negative number, or a pair @code{(@var{x} . @var{y})} of such
2942 numbers. If it is a pair, @var{x} specifies how many pixels to add
2943 horizontally, and @var{y} specifies how many pixels to add vertically.
2944 If @code{:margin} is not specified, the default is zero.
2946 @item :ascent @var{ascent}
2947 The @code{:ascent} property specifies the amount of the image's
2948 height to use for its ascent---that is, the part above the baseline.
2949 The value, @var{ascent}, must be a number in the range 0 to 100, or
2950 the symbol @code{center}.
2952 If @var{ascent} is a number, that percentage of the image's height is
2953 used for its ascent.
2955 If @var{ascent} is @code{center}, the image is vertically centered
2956 around a centerline which would be the vertical centerline of text drawn
2957 at the position of the image, in the manner specified by the text
2958 properties and overlays that apply to the image.
2960 If this property is omitted, it defaults to 50.
2962 @item :relief @var{relief}
2963 The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle
2964 around the image. The value, @var{relief}, specifies the width of the
2965 shadow lines, in pixels. If @var{relief} is negative, shadows are drawn
2966 so that the image appears as a pressed button; otherwise, it appears as
2967 an unpressed button.
2969 @item :conversion @var{algorithm}
2970 The @code{:conversion} property, if non-@code{nil}, specifies a
2971 conversion algorithm that should be applied to the image before it is
2972 displayed; the value, @var{algorithm}, specifies which algorithm.
2977 Specifies the Laplace edge detection algorithm, which blurs out small
2978 differences in color while highlighting larger differences. People
2979 sometimes consider this useful for displaying the image for a
2980 ``disabled'' button.
2982 @item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
2983 Specifies a general edge-detection algorithm. @var{matrix} must be
2984 either a nine-element list or a nine-element vector of numbers. A pixel
2985 at position @math{x/y} in the transformed image is computed from
2986 original pixels around that position. @var{matrix} specifies, for each
2987 pixel in the neighborhood of @math{x/y}, a factor with which that pixel
2988 will influence the transformed pixel; element @math{0} specifies the
2989 factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for
2990 the pixel at @math{x/y-1} etc., as shown below:
2993 $$\pmatrix{x-1/y-1 & x/y-1 & x+1/y-1 \cr
2994 x-1/y & x/y & x+1/y \cr
2995 x-1/y+1& x/y+1 & x+1/y+1 \cr}$$
3000 (x-1/y-1 x/y-1 x+1/y-1
3002 x-1/y+1 x/y+1 x+1/y+1)
3006 The resulting pixel is computed from the color intensity of the color
3007 resulting from summing up the RGB values of surrounding pixels,
3008 multiplied by the specified factors, and dividing that sum by the sum
3009 of the factors' absolute values.
3011 Laplace edge-detection currently uses a matrix of
3014 $$\pmatrix{1 & 0 & 0 \cr
3027 Emboss edge-detection uses a matrix of
3030 $$\pmatrix{ 2 & -1 & 0 \cr
3044 Specifies transforming the image so that it looks ``disabled''.
3047 @item :mask @var{mask}
3048 If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build
3049 a clipping mask for the image, so that the background of a frame is
3050 visible behind the image. If @var{bg} is not specified, or if @var{bg}
3051 is @code{t}, determine the background color of the image by looking at
3052 the four corners of the image, assuming the most frequently occurring
3053 color from the corners is the background color of the image. Otherwise,
3054 @var{bg} must be a list @code{(@var{red} @var{green} @var{blue})}
3055 specifying the color to assume for the background of the image.
3057 If @var{mask} is @code{nil}, remove a mask from the image, if it has
3058 one. Images in some formats include a mask which can be removed by
3059 specifying @code{:mask nil}.
3062 @defun image-mask-p spec &optional frame
3063 @tindex image-mask-p
3064 This function returns @code{t} if image @var{spec} has a mask bitmap.
3065 @var{frame} is the frame on which the image will be displayed.
3066 @var{frame} @code{nil} or omitted means to use the selected frame
3067 (@pxref{Input Focus}).
3071 @subsection XBM Images
3074 To use XBM format, specify @code{xbm} as the image type. This image
3075 format doesn't require an external library, so images of this type are
3078 Additional image properties supported for the @code{xbm} image type are:
3081 @item :foreground @var{foreground}
3082 The value, @var{foreground}, should be a string specifying the image
3083 foreground color, or @code{nil} for the default color. This color is
3084 used for each pixel in the XBM that is 1. The default is the frame's
3087 @item :background @var{background}
3088 The value, @var{background}, should be a string specifying the image
3089 background color, or @code{nil} for the default color. This color is
3090 used for each pixel in the XBM that is 0. The default is the frame's
3094 If you specify an XBM image using data within Emacs instead of an
3095 external file, use the following three properties:
3098 @item :data @var{data}
3099 The value, @var{data}, specifies the contents of the image.
3100 There are three formats you can use for @var{data}:
3104 A vector of strings or bool-vectors, each specifying one line of the
3105 image. Do specify @code{:height} and @code{:width}.
3108 A string containing the same byte sequence as an XBM file would contain.
3109 You must not specify @code{:height} and @code{:width} in this case,
3110 because omitting them is what indicates the data has the format of an
3111 XBM file. The file contents specify the height and width of the image.
3114 A string or a bool-vector containing the bits of the image (plus perhaps
3115 some extra bits at the end that will not be used). It should contain at
3116 least @var{width} * @code{height} bits. In this case, you must specify
3117 @code{:height} and @code{:width}, both to indicate that the string
3118 contains just the bits rather than a whole XBM file, and to specify the
3122 @item :width @var{width}
3123 The value, @var{width}, specifies the width of the image, in pixels.
3125 @item :height @var{height}
3126 The value, @var{height}, specifies the height of the image, in pixels.
3130 @subsection XPM Images
3133 To use XPM format, specify @code{xpm} as the image type. The
3134 additional image property @code{:color-symbols} is also meaningful with
3135 the @code{xpm} image type:
3138 @item :color-symbols @var{symbols}
3139 The value, @var{symbols}, should be an alist whose elements have the
3140 form @code{(@var{name} . @var{color})}. In each element, @var{name} is
3141 the name of a color as it appears in the image file, and @var{color}
3142 specifies the actual color to use for displaying that name.
3146 @subsection GIF Images
3149 For GIF images, specify image type @code{gif}. Because of the patents
3150 in the US covering the LZW algorithm, the continued use of GIF format is
3151 a problem for the whole Internet; to end this problem, it is a good idea
3152 for everyone, even outside the US, to stop using GIFS right away
3153 (@uref{http://www.burnallgifs.org/}). But if you still want to use
3154 them, Emacs can display them.
3157 @item :index @var{index}
3158 You can use @code{:index} to specify one image from a GIF file that
3159 contains more than one image. This property specifies use of image
3160 number @var{index} from the file. If the GIF file doesn't contain an
3161 image with index @var{index}, the image displays as a hollow box.
3165 This could be used to implement limited support for animated GIFs.
3166 For example, the following function displays a multi-image GIF file
3167 at point-min in the current buffer, switching between sub-images
3170 (defun show-anim (file max)
3171 "Display multi-image GIF file FILE which contains MAX subimages."
3172 (display-anim (current-buffer) file 0 max t))
3174 (defun display-anim (buffer file idx max first-time)
3177 (let ((img (create-image file nil :image idx)))
3180 (goto-char (point-min))
3181 (unless first-time (delete-char 1))
3183 (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
3186 @node Postscript Images
3187 @subsection Postscript Images
3188 @cindex Postscript images
3190 To use Postscript for an image, specify image type @code{postscript}.
3191 This works only if you have Ghostscript installed. You must always use
3192 these three properties:
3195 @item :pt-width @var{width}
3196 The value, @var{width}, specifies the width of the image measured in
3197 points (1/72 inch). @var{width} must be an integer.
3199 @item :pt-height @var{height}
3200 The value, @var{height}, specifies the height of the image in points
3201 (1/72 inch). @var{height} must be an integer.
3203 @item :bounding-box @var{box}
3204 The value, @var{box}, must be a list or vector of four integers, which
3205 specifying the bounding box of the Postscript image, analogous to the
3206 @samp{BoundingBox} comment found in Postscript files.
3209 %%BoundingBox: 22 171 567 738
3213 Displaying Postscript images from Lisp data is not currently
3214 implemented, but it may be implemented by the time you read this.
3215 See the @file{etc/NEWS} file to make sure.
3217 @node Other Image Types
3218 @subsection Other Image Types
3221 For PBM images, specify image type @code{pbm}. Color, gray-scale and
3222 monochromatic images are supported. For mono PBM images, two additional
3223 image properties are supported.
3226 @item :foreground @var{foreground}
3227 The value, @var{foreground}, should be a string specifying the image
3228 foreground color, or @code{nil} for the default color. This color is
3229 used for each pixel in the XBM that is 1. The default is the frame's
3232 @item :background @var{background}
3233 The value, @var{background}, should be a string specifying the image
3234 background color, or @code{nil} for the default color. This color is
3235 used for each pixel in the XBM that is 0. The default is the frame's
3239 For JPEG images, specify image type @code{jpeg}.
3241 For TIFF images, specify image type @code{tiff}.
3243 For PNG images, specify image type @code{png}.
3245 @node Defining Images
3246 @subsection Defining Images
3248 The functions @code{create-image}, @code{defimage} and
3249 @code{find-image} provide convenient ways to create image descriptors.
3251 @defun create-image file &optional type &rest props
3252 @tindex create-image
3253 This function creates and returns an image descriptor which uses the
3256 The optional argument @var{type} is a symbol specifying the image type.
3257 If @var{type} is omitted or @code{nil}, @code{create-image} tries to
3258 determine the image type from the file's first few bytes, or else
3259 from the file's name.
3261 The remaining arguments, @var{props}, specify additional image
3262 properties---for example,
3265 (create-image "foo.xpm" 'xpm :heuristic-mask t)
3268 The function returns @code{nil} if images of this type are not
3269 supported. Otherwise it returns an image descriptor.
3272 @defmac defimage symbol specs &optional doc
3274 This macro defines @var{symbol} as an image name. The arguments
3275 @var{specs} is a list which specifies how to display the image.
3276 The third argument, @var{doc}, is an optional documentation string.
3278 Each argument in @var{specs} has the form of a property list, and each
3279 one should specify at least the @code{:type} property and either the
3280 @code{:file} or the @code{:data} property. The value of @code{:type}
3281 should be a symbol specifying the image type, the value of
3282 @code{:file} is the file to load the image from, and the value of
3283 @code{:data} is a string containing the actual image data. Here is an
3287 (defimage test-image
3288 ((:type xpm :file "~/test1.xpm")
3289 (:type xbm :file "~/test1.xbm")))
3292 @code{defimage} tests each argument, one by one, to see if it is
3293 usable---that is, if the type is supported and the file exists. The
3294 first usable argument is used to make an image descriptor which is
3295 stored in @var{symbol}.
3297 If none of the alternatives will work, then @var{symbol} is defined
3301 @defun find-image specs
3303 This function provides a convenient way to find an image satisfying one
3304 of a list of image specifications @var{specs}.
3306 Each specification in @var{specs} is a property list with contents
3307 depending on image type. All specifications must at least contain the
3308 properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
3309 or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
3310 the image type, e.g.@: @code{xbm}, @var{file} is the file to load the
3311 image from, and @var{data} is a string containing the actual image data.
3312 The first specification in the list whose @var{type} is supported, and
3313 @var{file} exists, is used to construct the image specification to be
3314 returned. If no specification is satisfied, @code{nil} is returned.
3316 The image is looked for first on @code{load-path} and then in
3317 @code{data-directory}.
3320 @node Showing Images
3321 @subsection Showing Images
3323 You can use an image descriptor by setting up the @code{display}
3324 property yourself, but it is easier to use the functions in this
3327 @defun insert-image image &optional string area
3328 This function inserts @var{image} in the current buffer at point. The
3329 value @var{image} should be an image descriptor; it could be a value
3330 returned by @code{create-image}, or the value of a symbol defined with
3331 @code{defimage}. The argument @var{string} specifies the text to put in
3332 the buffer to hold the image.
3334 The argument @var{area} specifies whether to put the image in a margin.
3335 If it is @code{left-margin}, the image appears in the left margin;
3336 @code{right-margin} specifies the right margin. If @var{area} is
3337 @code{nil} or omitted, the image is displayed at point within the
3340 Internally, this function inserts @var{string} in the buffer, and gives
3341 it a @code{display} property which specifies @var{image}. @xref{Display
3345 @defun put-image image pos &optional string area
3346 This function puts image @var{image} in front of @var{pos} in the
3347 current buffer. The argument @var{pos} should be an integer or a
3348 marker. It specifies the buffer position where the image should appear.
3349 The argument @var{string} specifies the text that should hold the image
3350 as an alternative to the default.
3352 The argument @var{image} must be an image descriptor, perhaps returned
3353 by @code{create-image} or stored by @code{defimage}.
3355 The argument @var{area} specifies whether to put the image in a margin.
3356 If it is @code{left-margin}, the image appears in the left margin;
3357 @code{right-margin} specifies the right margin. If @var{area} is
3358 @code{nil} or omitted, the image is displayed at point within the
3361 Internally, this function creates an overlay, and gives it a
3362 @code{before-string} property containing text that has a @code{display}
3363 property whose value is the image. (Whew!)
3366 @defun remove-images start end &optional buffer
3367 This function removes images in @var{buffer} between positions
3368 @var{start} and @var{end}. If @var{buffer} is omitted or @code{nil},
3369 images are removed from the current buffer.
3371 This removes only images that were put into @var{buffer} the way
3372 @code{put-image} does it, not images that were inserted with
3373 @code{insert-image} or in other ways.
3376 @defun image-size spec &optional pixels frame
3378 This function returns the size of an image as a pair
3379 @w{@code{(@var{width} . @var{height})}}. @var{spec} is an image
3380 specification. @var{pixels} non-@code{nil} means return sizes
3381 measured in pixels, otherwise return sizes measured in canonical
3382 character units (fractions of the width/height of the frame's default
3383 font). @var{frame} is the frame on which the image will be displayed.
3384 @var{frame} null or omitted means use the selected frame (@pxref{Input
3389 @subsection Image Cache
3391 Emacs stores images in an image cache when it displays them, so it can
3392 display them again more efficiently. It removes an image from the cache
3393 when it hasn't been displayed for a specified period of time.
3395 When an image is looked up in the cache, its specification is compared
3396 with cached image specifications using @code{equal}. This means that
3397 all images with equal specifications share the same image in the cache.
3399 @defvar image-cache-eviction-delay
3400 @tindex image-cache-eviction-delay
3401 This variable specifies the number of seconds an image can remain in the
3402 cache without being displayed. When an image is not displayed for this
3403 length of time, Emacs removes it from the image cache.
3405 If the value is @code{nil}, Emacs does not remove images from the cache
3406 except when you explicitly clear it. This mode can be useful for
3410 @defun clear-image-cache &optional frame
3411 @tindex clear-image-cache
3412 This function clears the image cache. If @var{frame} is non-@code{nil},
3413 only the cache for that frame is cleared. Otherwise all frames' caches
3420 @cindex buttons in buffers
3421 @cindex clickable buttons in buffers
3423 The @emph{button} package defines functions for inserting and
3424 manipulating clickable (with the mouse, or via keyboard commands)
3425 buttons in Emacs buffers, such as might be used for help hyper-links,
3426 etc. Emacs uses buttons for the hyper-links in help text and the like.
3428 A button is essentially a set of properties attached (via text
3429 properties or overlays) to a region of text in an emacs buffer, which
3430 are called its button properties. @xref{Button Properties}.
3432 One of the these properties (@code{action}) is a function, which will
3433 be called when the user invokes it using the keyboard or the mouse.
3434 The invoked function may then examine the button and use its other
3435 properties as desired.
3437 In some ways the emacs button package duplicates functionality offered
3438 by the widget package (@pxref{Top, , Introduction, widget, The Emacs
3439 Widget Library}), but the button package has the advantage that it is
3440 much faster, much smaller, and much simpler to use (for elisp
3441 programmers---for users, the result is about the same). The extra
3442 speed and space savings are useful mainly if you need to create many
3443 buttons in a buffer (for instance an @code{*Apropos*} buffer uses
3444 buttons to make entries clickable, and may contain many thousands of
3448 * Button Properties:: Button properties with special meanings.
3449 * Button Types:: Defining common properties for classes of buttons.
3450 * Making Buttons:: Adding buttons to emacs buffers.
3451 * Manipulating Buttons:: Getting and setting properties of buttons.
3452 * Button Buffer Commands:: Buffer-wide commands and bindings for buttons.
3453 * Manipulating Button Types::
3456 @node Button Properties
3457 @subsection Button Properties
3458 @cindex button properties
3460 Buttons have an associated list of properties defining their
3461 appearance and behavior, and other arbitrary properties may be used
3462 for application specific purposes.
3464 Some properties that have special meaning to the button package
3470 @kindex action @r{(button property)}
3471 The function to call when the user invokes the button, which is passed
3472 the single argument @var{button}. By default this is @code{ignore},
3476 @kindex mouse-action @r{(button property)}
3477 This is similar to @code{action}, and when present, will be used
3478 instead of @code{action} for button invocations resulting from
3479 mouse-clicks (instead of the user hitting @key{RET}). If not
3480 present, mouse-clicks use @code{action} instead.
3483 @kindex face @r{(button property)}
3484 This is an emacs face controlling how buttons of this type are
3485 displayed; by default this is the @code{button} face.
3488 @kindex mouse-face @r{(button property)}
3489 This is an additional face which controls appearance during
3490 mouse-overs (merged with the usual button face); by default this is
3491 the usual emacs @code{highlight} face.
3494 @kindex keymap @r{(button property)}
3495 The button's keymap, defining bindings active within the button
3496 region. By default this is the usual button region keymap, stored
3497 in the variable @code{button-map}, which defines @key{RET} and
3498 @key{mouse-2} to invoke the button.
3501 @kindex type @r{(button property)}
3502 The button-type of the button. When creating a button, this is
3503 usually specified using the @code{:type} keyword argument.
3504 @xref{Button Types}.
3507 @kindex help-index @r{(button property)}
3508 A string displayed by the emacs tool-tip help system; by default,
3509 @code{"mouse-2, RET: Push this button"}.
3512 @kindex button @r{(button property)}
3513 All buttons have a non-@code{nil} @code{button} property, which may be useful
3514 in finding regions of text that comprise buttons (which is what the
3515 standard button functions do).
3518 There are other properties defined for the regions of text in a
3519 button, but these are not generally interesting for typical uses.
3522 @subsection Button Types
3523 @cindex button types
3525 Every button has a button @emph{type}, which defines default values
3526 for the button's properties. Button types are arranged in a
3527 hierarchy, with specialized types inheriting from more general types,
3528 so that it's easy to define special-purpose types of buttons for
3531 @defun define-button-type name &rest properties
3532 @tindex define-button-type
3533 Define a `button type' called @var{name}. The remaining arguments
3534 form a sequence of @var{property value} pairs, specifying default
3535 property values for buttons with this type (a button's type may be set
3536 by giving it a @code{type} property when creating the button, using
3537 the @code{:type} keyword argument).
3539 In addition, the keyword argument @code{:supertype} may be used to
3540 specify a button-type from which @var{name} inherits its default
3541 property values. Note that this inheritance happens only when
3542 @var{name} is defined; subsequent changes to a supertype are not
3543 reflected in its subtypes.
3546 Using @code{define-button-type} to define default properties for
3547 buttons is not necessary---buttons without any specified type use the
3548 built-in button-type @code{button}---but it is is encouraged, since
3549 doing so usually makes the resulting code clearer and more efficient.
3551 @node Making Buttons
3552 @subsection Making Buttons
3553 @cindex making buttons
3555 Buttons are associated with a region of text, using an overlay or
3556 text-properties to hold button-specific information, all of which are
3557 initialized from the button's type (which defaults to the built-in
3558 button type @code{button}). Like all emacs text, the appearance of
3559 the button is governed by the @code{face} property; by default (via
3560 the @code{face} property inherited from the @code{button} button-type)
3561 this is a simple underline, like a typical web-page link.
3563 For convenience, there are two sorts of button-creation functions,
3564 those that add button properties to an existing region of a buffer,
3565 called @code{make-...button}, and those also insert the button text,
3566 called @code{insert-...button}.
3568 The button-creation functions all take the @code{&rest} argument
3569 @var{properties}, which should be a sequence of @var{property value}
3570 pairs, specifying properties to add to the button; see @ref{Button
3571 Properties}. In addition, the keyword argument @code{:type} may be
3572 used to specify a button-type from which to inherit other properties;
3573 see @ref{Button Types}. Any properties not explicitly specified
3574 during creation will be inherited from the button's type (if the type
3575 defines such a property).
3577 The following functions add a button using an overlay
3578 (@pxref{Overlays}) to hold the button properties:
3580 @defun make-button beg end &rest properties
3582 Make a button from @var{beg} to @var{end} in the current buffer.
3585 @defun insert-button label &rest properties
3586 @tindex insert-button
3587 Insert a button with the label @var{label}.
3590 The following functions are similar, but use emacs text-properties
3591 (@pxref{Text Properties}) to hold the button properties, making the
3592 button actually part of the text instead of being a property of the
3593 buffer (using text-properties is usually faster than using overlays,
3594 so this may be preferable when creating large numbers of buttons):
3596 @defun make-text-button beg end &rest properties
3597 @tindex make-text-button
3598 Make a button from @var{beg} to @var{end} in the current buffer, using
3602 @defun insert-text-button label &rest properties
3603 @tindex insert-text-button
3604 Insert a button with the label @var{label}, using text-properties.
3607 Buttons using text-properties retain no markers into the buffer are
3608 retained, which is important for speed in cases where there are
3609 extremely large numbers of buttons.
3611 @node Manipulating Buttons
3612 @subsection Manipulating Buttons
3613 @cindex manipulating buttons
3615 These are functions for getting and setting properties of buttons.
3616 Often these are used by a button's invocation function to determine
3619 Where a @var{button} parameter is specified, it means an object
3620 referring to a specific button, either an overlay (for overlay
3621 buttons), or a buffer-position or marker (for text property buttons).
3622 Such an object is passed as the first argument to a button's
3623 invocation function when it is invoked.
3625 @defun button-start button
3626 @tindex button-start
3627 Return the position at which @var{button} starts.
3630 @defun button-end button
3632 Return the position at which @var{button} ends.
3635 @defun button-get button prop
3637 Get the property of button @var{button} named @var{prop}.
3640 @defun button-put button prop val
3642 Set @var{button}'s @var{prop} property to @var{val}.
3645 @defun button-activate button &optional use-mouse-action
3646 @tindex button-activate
3647 Call @var{button}'s @code{action} property (i.e., invoke it). If
3648 @var{use-mouse-action} is non-@code{nil}, try to invoke the button's
3649 @code{mouse-action} property instead of @code{action}; if the button
3650 has no @code{mouse-action} property, use @code{action} as normal.
3653 @defun button-label button
3654 @tindex button-label
3655 Return @var{button}'s text label.
3658 @defun button-type button
3660 Return @var{button}'s button-type.
3663 @defun button-has-type-p button type
3664 @tindex button-has-type-p
3665 Return @code{t} if @var{button} has button-type @var{type}, or one of
3666 @var{type}'s subtypes.
3669 @defun button-at pos
3671 Return the button at position @var{pos} in the current buffer, or @code{nil}.
3674 @node Button Buffer Commands
3675 @subsection Button Buffer Commands
3676 @cindex button buffer commands
3678 These are commands and functions for locating and operating on
3679 buttons in an emacs buffer.
3681 @code{push-button} is the command that a user uses to actually `push'
3682 a button, and is bound by default in the button itself to @key{RET}
3683 and to @key{mouse-2} using a region-specific keymap. Commands
3684 that are useful outside the buttons itself, such as
3685 @code{forward-button} and @code{backward-button} are additionally
3686 available in the keymap stored in @code{button-buffer-map}; a mode
3687 which uses buttons may want to use @code{button-buffer-map} as a
3688 parent keymap for its keymap.
3690 @deffn Command push-button &optional pos use-mouse-action
3692 Perform the action specified by a button at location @var{pos}.
3693 @var{pos} may be either a buffer position or a mouse-event. If
3694 @var{use-mouse-action} is non-@code{nil}, or @var{pos} is a
3695 mouse-event (@pxref{Mouse Events}), try to invoke the button's
3696 @code{mouse-action} property instead of @code{action}; if the button
3697 has no @code{mouse-action} property, use @code{action} as normal.
3698 @var{pos} defaults to point, except when @code{push-button} is invoked
3699 interactively as the result of a mouse-event, in which case, the mouse
3700 event's position is used. If there's no button at @var{pos}, do
3701 nothing and return @code{nil}, otherwise return @code{t}.
3704 @deffn Command forward-button n &optional wrap display-message
3705 @tindex forward-button
3706 Move to the @var{n}th next button, or @var{n}th previous button if
3707 @var{n} is negative. If @var{n} is zero, move to the start of any
3708 button at point. If @var{wrap} is non-@code{nil}, moving past either
3709 end of the buffer continues from the other end. If
3710 @var{display-message} is non-@code{nil}, the button's help-echo string
3711 is displayed. Any button with a non-@code{nil} @code{skip} property
3712 is skipped over. Returns the button found.
3715 @deffn Command backward-button n &optional wrap display-message
3716 @tindex backward-button
3717 Move to the @var{n}th previous button, or @var{n}th next button if
3718 @var{n} is negative. If @var{n} is zero, move to the start of any
3719 button at point. If @var{wrap} is non-@code{nil}, moving past either
3720 end of the buffer continues from the other end. If
3721 @var{display-message} is non-@code{nil}, the button's help-echo string
3722 is displayed. Any button with a non-@code{nil} @code{skip} property
3723 is skipped over. Returns the button found.
3726 @defun next-button pos &optional count-current
3728 Return the next button after position @var{pos} in the current buffer.
3729 If @var{count-current} is non-@code{nil}, count any button at
3730 @var{pos} in the search, instead of starting at the next button.
3733 @defun previous-button pos &optional count-current
3734 @tindex previous-button
3735 Return the @var{n}th button before position @var{pos} in the current
3736 buffer. If @var{count-current} is non-@code{nil}, count any button at
3737 @var{pos} in the search, instead of starting at the next button.
3740 @node Manipulating Button Types
3741 @subsection Manipulating Button Types
3742 @cindex manipulating button types
3744 @defun button-type-put type prop val
3745 @tindex button-type-put
3746 Set the button-type @var{type}'s @var{prop} property to @var{val}.
3749 @defun button-type-get type prop
3750 @tindex button-type-get
3751 Get the property of button-type @var{type} named @var{prop}.
3754 @defun button-type-subtype-p type supertype
3755 @tindex button-type-subtype-p
3756 Return @code{t} if button-type @var{type} is a subtype of @var{supertype}.
3760 @section Blinking Parentheses
3761 @cindex parenthesis matching
3763 @cindex balancing parentheses
3764 @cindex close parenthesis
3766 This section describes the mechanism by which Emacs shows a matching
3767 open parenthesis when the user inserts a close parenthesis.
3769 @defvar blink-paren-function
3770 The value of this variable should be a function (of no arguments) to
3771 be called whenever a character with close parenthesis syntax is inserted.
3772 The value of @code{blink-paren-function} may be @code{nil}, in which
3773 case nothing is done.
3776 @defopt blink-matching-paren
3777 If this variable is @code{nil}, then @code{blink-matching-open} does
3781 @defopt blink-matching-paren-distance
3782 This variable specifies the maximum distance to scan for a matching
3783 parenthesis before giving up.
3786 @defopt blink-matching-delay
3787 This variable specifies the number of seconds for the cursor to remain
3788 at the matching parenthesis. A fraction of a second often gives
3789 good results, but the default is 1, which works on all systems.
3792 @deffn Command blink-matching-open
3793 This function is the default value of @code{blink-paren-function}. It
3794 assumes that point follows a character with close parenthesis syntax and
3795 moves the cursor momentarily to the matching opening character. If that
3796 character is not already on the screen, it displays the character's
3797 context in the echo area. To avoid long delays, this function does not
3798 search farther than @code{blink-matching-paren-distance} characters.
3800 Here is an example of calling this function explicitly.
3804 (defun interactive-blink-matching-open ()
3805 @c Do not break this line! -- rms.
3806 @c The first line of a doc string
3807 @c must stand alone.
3808 "Indicate momentarily the start of sexp before point."
3812 (let ((blink-matching-paren-distance
3814 (blink-matching-paren t))
3815 (blink-matching-open)))
3821 @section Inverse Video
3822 @cindex Inverse Video
3824 @defopt inverse-video
3825 @cindex highlighting
3826 This variable controls whether Emacs uses inverse video for all text
3827 on the screen. Non-@code{nil} means yes, @code{nil} means no. The
3828 default is @code{nil}.
3831 @defopt mode-line-inverse-video
3832 This variable controls the use of inverse video for mode lines and menu
3833 bars. If it is non-@code{nil}, then these lines are displayed in
3834 inverse video. Otherwise, these lines are displayed normally, just like
3835 other text. The default is @code{t}.
3837 For window frames, this feature actually applies the face named
3838 @code{mode-line}; that face is normally set up as the inverse of the
3839 default face, unless you change it.
3843 @section Usual Display Conventions
3845 The usual display conventions define how to display each character
3846 code. You can override these conventions by setting up a display table
3847 (@pxref{Display Tables}). Here are the usual display conventions:
3851 Character codes 32 through 126 map to glyph codes 32 through 126.
3852 Normally this means they display as themselves.
3855 Character code 9 is a horizontal tab. It displays as whitespace
3856 up to a position determined by @code{tab-width}.
3859 Character code 10 is a newline.
3862 All other codes in the range 0 through 31, and code 127, display in one
3863 of two ways according to the value of @code{ctl-arrow}. If it is
3864 non-@code{nil}, these codes map to sequences of two glyphs, where the
3865 first glyph is the @acronym{ASCII} code for @samp{^}. (A display table can
3866 specify a glyph to use instead of @samp{^}.) Otherwise, these codes map
3867 just like the codes in the range 128 to 255.
3869 On MS-DOS terminals, Emacs arranges by default for the character code
3870 127 to be mapped to the glyph code 127, which normally displays as an
3871 empty polygon. This glyph is used to display non-@acronym{ASCII} characters
3872 that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,,
3873 emacs, The GNU Emacs Manual}.
3876 Character codes 128 through 255 map to sequences of four glyphs, where
3877 the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are
3878 digit characters representing the character code in octal. (A display
3879 table can specify a glyph to use instead of @samp{\}.)
3882 Multibyte character codes above 256 are displayed as themselves, or as a
3883 question mark or empty box if the terminal cannot display that
3887 The usual display conventions apply even when there is a display
3888 table, for any character whose entry in the active display table is
3889 @code{nil}. Thus, when you set up a display table, you need only
3890 specify the characters for which you want special behavior.
3892 These display rules apply to carriage return (character code 13), when
3893 it appears in the buffer. But that character may not appear in the
3894 buffer where you expect it, if it was eliminated as part of end-of-line
3895 conversion (@pxref{Coding System Basics}).
3897 These variables affect the way certain characters are displayed on the
3898 screen. Since they change the number of columns the characters occupy,
3899 they also affect the indentation functions. These variables also affect
3900 how the mode line is displayed; if you want to force redisplay of the
3901 mode line using the new values, call the function
3902 @code{force-mode-line-update} (@pxref{Mode Line Format}).
3905 @cindex control characters in display
3906 This buffer-local variable controls how control characters are
3907 displayed. If it is non-@code{nil}, they are displayed as a caret
3908 followed by the character: @samp{^A}. If it is @code{nil}, they are
3909 displayed as a backslash followed by three octal digits: @samp{\001}.
3912 @c Following may have overfull hbox.
3913 @defvar default-ctl-arrow
3914 The value of this variable is the default value for @code{ctl-arrow} in
3915 buffers that do not override it. @xref{Default Value}.
3918 @defopt indicate-empty-lines
3919 @tindex indicate-empty-lines
3920 @cindex fringes, and empty line indication
3921 When this is non-@code{nil}, Emacs displays a special glyph in the
3922 fringe of each empty line at the end of the buffer, on terminals that
3923 support it (window systems). @xref{Fringes}.
3927 The value of this variable is the spacing between tab stops used for
3928 displaying tab characters in Emacs buffers. The value is in units of
3929 columns, and the default is 8. Note that this feature is completely
3930 independent of the user-settable tab stops used by the command
3931 @code{tab-to-tab-stop}. @xref{Indent Tabs}.
3934 @node Display Tables
3935 @section Display Tables
3937 @cindex display table
3938 You can use the @dfn{display table} feature to control how all possible
3939 character codes display on the screen. This is useful for displaying
3940 European languages that have letters not in the @acronym{ASCII} character
3943 The display table maps each character code into a sequence of
3944 @dfn{glyphs}, each glyph being a graphic that takes up one character
3945 position on the screen. You can also define how to display each glyph
3946 on your terminal, using the @dfn{glyph table}.
3948 Display tables affect how the mode line is displayed; if you want to
3949 force redisplay of the mode line using a new display table, call
3950 @code{force-mode-line-update} (@pxref{Mode Line Format}).
3953 * Display Table Format:: What a display table consists of.
3954 * Active Display Table:: How Emacs selects a display table to use.
3955 * Glyphs:: How to define a glyph, and what glyphs mean.
3958 @node Display Table Format
3959 @subsection Display Table Format
3961 A display table is actually a char-table (@pxref{Char-Tables}) with
3962 @code{display-table} as its subtype.
3964 @defun make-display-table
3965 This creates and returns a display table. The table initially has
3966 @code{nil} in all elements.
3969 The ordinary elements of the display table are indexed by character
3970 codes; the element at index @var{c} says how to display the character
3971 code @var{c}. The value should be @code{nil} or a vector of glyph
3972 values (@pxref{Glyphs}). If an element is @code{nil}, it says to
3973 display that character according to the usual display conventions
3974 (@pxref{Usual Display}).
3976 If you use the display table to change the display of newline
3977 characters, the whole buffer will be displayed as one long ``line.''
3979 The display table also has six ``extra slots'' which serve special
3980 purposes. Here is a table of their meanings; @code{nil} in any slot
3981 means to use the default for that slot, as stated below.
3985 The glyph for the end of a truncated screen line (the default for this
3986 is @samp{$}). @xref{Glyphs}. Newer Emacs versions, on some platforms,
3987 display arrows to indicate truncation---the display table has no effect
3988 in these situations.
3990 The glyph for the end of a continued line (the default is @samp{\}).
3991 Newer Emacs versions, on some platforms, display curved arrows to
3992 indicate truncation---the display table has no effect in these
3995 The glyph for indicating a character displayed as an octal character
3996 code (the default is @samp{\}).
3998 The glyph for indicating a control character (the default is @samp{^}).
4000 A vector of glyphs for indicating the presence of invisible lines (the
4001 default is @samp{...}). @xref{Selective Display}.
4003 The glyph used to draw the border between side-by-side windows (the
4004 default is @samp{|}). @xref{Splitting Windows}. This takes effect only
4005 when there are no scroll bars; if scroll bars are supported and in use,
4006 a scroll bar separates the two windows.
4009 For example, here is how to construct a display table that mimics the
4010 effect of setting @code{ctl-arrow} to a non-@code{nil} value:
4013 (setq disptab (make-display-table))
4016 (or (= i ?\t) (= i ?\n)
4017 (aset disptab i (vector ?^ (+ i 64))))
4019 (aset disptab 127 (vector ?^ ??)))
4022 @defun display-table-slot display-table slot
4023 This function returns the value of the extra slot @var{slot} of
4024 @var{display-table}. The argument @var{slot} may be a number from 0 to
4025 5 inclusive, or a slot name (symbol). Valid symbols are
4026 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
4027 @code{selective-display}, and @code{vertical-border}.
4030 @defun set-display-table-slot display-table slot value
4031 This function stores @var{value} in the extra slot @var{slot} of
4032 @var{display-table}. The argument @var{slot} may be a number from 0 to
4033 5 inclusive, or a slot name (symbol). Valid symbols are
4034 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
4035 @code{selective-display}, and @code{vertical-border}.
4038 @defun describe-display-table display-table
4039 @tindex describe-display-table
4040 This function displays a description of the display table
4041 @var{display-table} in a help buffer.
4044 @deffn Command describe-current-display-table
4045 @tindex describe-current-display-table
4046 This command displays a description of the current display table in a
4050 @node Active Display Table
4051 @subsection Active Display Table
4052 @cindex active display table
4054 Each window can specify a display table, and so can each buffer. When
4055 a buffer @var{b} is displayed in window @var{w}, display uses the
4056 display table for window @var{w} if it has one; otherwise, the display
4057 table for buffer @var{b} if it has one; otherwise, the standard display
4058 table if any. The display table chosen is called the @dfn{active}
4061 @defun window-display-table window
4062 This function returns @var{window}'s display table, or @code{nil}
4063 if @var{window} does not have an assigned display table.
4066 @defun set-window-display-table window table
4067 This function sets the display table of @var{window} to @var{table}.
4068 The argument @var{table} should be either a display table or
4072 @defvar buffer-display-table
4073 This variable is automatically buffer-local in all buffers; its value in
4074 a particular buffer specifies the display table for that buffer. If it
4075 is @code{nil}, that means the buffer does not have an assigned display
4079 @defvar standard-display-table
4080 This variable's value is the default display table, used whenever a
4081 window has no display table and neither does the buffer displayed in
4082 that window. This variable is @code{nil} by default.
4085 If there is no display table to use for a particular window---that is,
4086 if the window specifies none, its buffer specifies none, and
4087 @code{standard-display-table} is @code{nil}---then Emacs uses the usual
4088 display conventions for all character codes in that window. @xref{Usual
4091 A number of functions for changing the standard display table
4092 are defined in the library @file{disp-table}.
4098 A @dfn{glyph} is a generalization of a character; it stands for an
4099 image that takes up a single character position on the screen. Glyphs
4100 are represented in Lisp as integers, just as characters are. Normally
4101 Emacs finds glyphs in the display table (@pxref{Display Tables}).
4103 A glyph can be @dfn{simple} or it can be defined by the @dfn{glyph
4104 table}. A simple glyph is just a way of specifying a character and a
4105 face to output it in. The glyph code for a simple glyph, mod 524288,
4106 is the character to output, and the glyph code divided by 524288
4107 specifies the face number (@pxref{Face Functions}) to use while
4108 outputting it. (524288 is
4117 On character terminals, you can set up a @dfn{glyph table} to define
4118 the meaning of glyph codes. The glyph codes is the value of the
4119 variable @code{glyph-table}.
4122 The value of this variable is the current glyph table. It should be a
4123 vector; the @var{g}th element defines glyph code @var{g}.
4125 If a glyph code is greater than or equal to the length of the glyph
4126 table, that code is automatically simple. If the value of
4127 @code{glyph-table} is @code{nil} instead of a vector, then all glyphs
4128 are simple. The glyph table is not used on graphical displays, only
4129 on character terminals. On graphical displays, all glyphs are simple.
4132 Here are the possible types of elements in the glyph table:
4136 Send the characters in @var{string} to the terminal to output
4137 this glyph. This alternative is available on character terminals,
4138 but not under a window system.
4141 Define this glyph code as an alias for glyph code @var{integer}. You
4142 can use an alias to specify a face code for the glyph and use a small
4146 This glyph is simple.
4149 @defun create-glyph string
4150 @tindex create-glyph
4151 This function returns a newly-allocated glyph code which is set up to
4152 display by sending @var{string} to the terminal.
4160 This section describes how to make Emacs ring the bell (or blink the
4161 screen) to attract the user's attention. Be conservative about how
4162 often you do this; frequent bells can become irritating. Also be
4163 careful not to use just beeping when signaling an error is more
4164 appropriate. (@xref{Errors}.)
4166 @defun ding &optional do-not-terminate
4167 @cindex keyboard macro termination
4168 This function beeps, or flashes the screen (see @code{visible-bell} below).
4169 It also terminates any keyboard macro currently executing unless
4170 @var{do-not-terminate} is non-@code{nil}.
4173 @defun beep &optional do-not-terminate
4174 This is a synonym for @code{ding}.
4177 @defopt visible-bell
4178 This variable determines whether Emacs should flash the screen to
4179 represent a bell. Non-@code{nil} means yes, @code{nil} means no. This
4180 is effective on a window system, and on a character-only terminal
4181 provided the terminal's Termcap entry defines the visible bell
4182 capability (@samp{vb}).
4185 @defvar ring-bell-function
4186 If this is non-@code{nil}, it specifies how Emacs should ``ring the
4187 bell.'' Its value should be a function of no arguments. If this is
4188 non-@code{nil}, it takes precedence over the @code{visible-bell}
4192 @node Window Systems
4193 @section Window Systems
4195 Emacs works with several window systems, most notably the X Window
4196 System. Both Emacs and X use the term ``window'', but use it
4197 differently. An Emacs frame is a single window as far as X is
4198 concerned; the individual Emacs windows are not known to X at all.
4200 @defvar window-system
4201 This variable tells Lisp programs what window system Emacs is running
4202 under. The possible values are
4206 @cindex X Window System
4207 Emacs is displaying using X.
4209 Emacs is displaying using MS-DOS.
4211 Emacs is displaying using Windows.
4213 Emacs is displaying using a Macintosh.
4215 Emacs is using a character-based terminal.
4219 @defvar window-setup-hook
4220 This variable is a normal hook which Emacs runs after handling the
4221 initialization files. Emacs runs this hook after it has completed
4222 loading your init file, the default initialization file (if
4223 any), and the terminal-specific Lisp code, and running the hook
4224 @code{term-setup-hook}.
4226 This hook is used for internal purposes: setting up communication with
4227 the window system, and creating the initial window. Users should not
4232 arch-tag: ffdf5714-7ecf-415b-9023-fbc6b409c2c6