2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
4 @c 2002, 2005 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 * Progress:: Informing user about progress of a long operation.
20 * Invisible Text:: Hiding part of the buffer text.
21 * Selective Display:: Hiding part of the buffer text (the old way).
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 * Line Height:: Controlling the height of lines.
26 * Faces:: A face defines a graphics style for text characters:
28 * Fringes:: Controlling window fringes.
29 * Scroll Bars:: Controlling vertical scroll bars.
30 * Pointer Shape:: Controlling the mouse pointer shape.
31 * Display Property:: Enabling special display features.
32 * Images:: Displaying images in Emacs buffers.
33 * Buttons:: Adding clickable buttons to Emacs buffers.
34 * Blinking:: How Emacs shows the matching open parenthesis.
35 * Inverse Video:: Specifying how the screen looks.
36 * Usual Display:: The usual conventions for displaying nonprinting chars.
37 * Display Tables:: How to specify other conventions.
38 * Beeping:: Audible signal to the user.
39 * Window Systems:: Which window system is being used.
43 @section Refreshing the Screen
45 The function @code{redraw-frame} clears and redisplays the entire
46 contents of a given frame (@pxref{Frames}). This is useful if the
50 @defun redraw-frame frame
51 This function clears and redisplays frame @var{frame}.
54 Even more powerful is @code{redraw-display}:
56 @deffn Command redraw-display
57 This function clears and redisplays all visible frames.
60 This function calls for redisplay of certain windows, the next time
61 redisplay is done, but does not clear them first.
63 @defun force-window-update &optional object
64 This function forces redisplay of some or all windows. If
65 @var{object} is a window, it forces redisplay of that window. If
66 @var{object} is a buffer or buffer name, it forces redisplay of all
67 windows displaying that buffer. If @var{object} is @code{nil} (or
68 omitted), it forces redisplay of all windows.
71 Processing user input takes absolute priority over redisplay. If you
72 call these functions when input is available, they do nothing
73 immediately, but a full redisplay does happen eventually---after all the
74 input has been processed.
76 Normally, suspending and resuming Emacs also refreshes the screen.
77 Some terminal emulators record separate contents for display-oriented
78 programs such as Emacs and for ordinary sequential display. If you are
79 using such a terminal, you might want to inhibit the redisplay on
82 @defvar no-redraw-on-reenter
83 @cindex suspend (cf. @code{no-redraw-on-reenter})
84 @cindex resume (cf. @code{no-redraw-on-reenter})
85 This variable controls whether Emacs redraws the entire screen after it
86 has been suspended and resumed. Non-@code{nil} means there is no need
87 to redraw, @code{nil} means redrawing is needed. The default is @code{nil}.
90 @node Forcing Redisplay
91 @section Forcing Redisplay
92 @cindex forcing redisplay
94 Emacs redisplay normally stops if input arrives, and does not happen
95 at all if input is available before it starts. Most of the time, this
96 is exactly what you want. However, you can prevent preemption by
97 binding @code{redisplay-dont-pause} to a non-@code{nil} value.
99 @tindex redisplay-dont-pause
100 @defvar redisplay-dont-pause
101 If this variable is non-@code{nil}, pending input does not
102 prevent or halt redisplay; redisplay occurs, and finishes,
103 regardless of whether input is available.
106 You can request a display update, but only if no input is pending,
107 with @code{(sit-for 0)}. To force a display update even when input is
111 (let ((redisplay-dont-pause t))
117 @cindex line wrapping
118 @cindex continuation lines
119 @cindex @samp{$} in display
120 @cindex @samp{\} in display
122 When a line of text extends beyond the right edge of a window, the
123 line can either be continued on the next screen line, or truncated to
124 one screen line. The additional screen lines used to display a long
125 text line are called @dfn{continuation} lines. Normally, a @samp{$} in
126 the rightmost column of the window indicates truncation; a @samp{\} on
127 the rightmost column indicates a line that ``wraps'' onto the next line,
128 which is also called @dfn{continuing} the line. (The display table can
129 specify alternative indicators; see @ref{Display Tables}.)
131 On a window system display, the @samp{$} and @samp{\} indicators are
132 replaced with arrow images displayed in the window fringes
135 Note that continuation is different from filling; continuation happens
136 on the screen only, not in the buffer contents, and it breaks a line
137 precisely at the right margin, not at a word boundary. @xref{Filling}.
139 @defopt truncate-lines
140 This buffer-local variable controls how Emacs displays lines that extend
141 beyond the right edge of the window. The default is @code{nil}, which
142 specifies continuation. If the value is non-@code{nil}, then these
145 If the variable @code{truncate-partial-width-windows} is non-@code{nil},
146 then truncation is always used for side-by-side windows (within one
147 frame) regardless of the value of @code{truncate-lines}.
150 @defopt default-truncate-lines
151 This variable is the default value for @code{truncate-lines}, for
152 buffers that do not have buffer-local values for it.
155 @defopt truncate-partial-width-windows
156 This variable controls display of lines that extend beyond the right
157 edge of the window, in side-by-side windows (@pxref{Splitting Windows}).
158 If it is non-@code{nil}, these lines are truncated; otherwise,
159 @code{truncate-lines} says what to do with them.
162 When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
163 a window, that forces truncation.
165 If your buffer contains @emph{very} long lines, and you use
166 continuation to display them, just thinking about them can make Emacs
167 redisplay slow. The column computation and indentation functions also
168 become slow. Then you might find it advisable to set
169 @code{cache-long-line-scans} to @code{t}.
171 @defvar cache-long-line-scans
172 If this variable is non-@code{nil}, various indentation and motion
173 functions, and Emacs redisplay, cache the results of scanning the
174 buffer, and consult the cache to avoid rescanning regions of the buffer
175 unless they are modified.
177 Turning on the cache slows down processing of short lines somewhat.
179 This variable is automatically buffer-local in every buffer.
183 @section The Echo Area
184 @cindex error display
187 The @dfn{echo area} is used for displaying error messages
188 (@pxref{Errors}), for messages made with the @code{message} primitive,
189 and for echoing keystrokes. It is not the same as the minibuffer,
190 despite the fact that the minibuffer appears (when active) in the same
191 place on the screen as the echo area. The @cite{GNU Emacs Manual}
192 specifies the rules for resolving conflicts between the echo area and
193 the minibuffer for use of that screen space (@pxref{Minibuffer,, The
194 Minibuffer, emacs, The GNU Emacs Manual}).
196 You can write output in the echo area by using the Lisp printing
197 functions with @code{t} as the stream (@pxref{Output Functions}), or as
200 @defun message string &rest arguments
201 This function displays a message in the echo area. The
202 argument @var{string} is similar to a C language @code{printf} control
203 string. See @code{format} in @ref{String Conversion}, for the details
204 on the conversion specifications. @code{message} returns the
207 In batch mode, @code{message} prints the message text on the standard
208 error stream, followed by a newline.
210 If @var{string}, or strings among the @var{arguments}, have @code{face}
211 text properties, these affect the way the message is displayed.
214 If @var{string} is @code{nil}, @code{message} clears the echo area; if
215 the echo area has been expanded automatically, this brings it back to
216 its normal size. If the minibuffer is active, this brings the
217 minibuffer contents back onto the screen immediately.
219 @vindex message-truncate-lines
220 Normally, displaying a long message resizes the echo area to display
221 the entire message. But if the variable @code{message-truncate-lines}
222 is non-@code{nil}, the echo area does not resize, and the message is
223 truncated to fit it, as in Emacs 20 and before.
227 (message "Minibuffer depth is %d."
229 @print{} Minibuffer depth is 0.
230 @result{} "Minibuffer depth is 0."
234 ---------- Echo Area ----------
235 Minibuffer depth is 0.
236 ---------- Echo Area ----------
240 To automatically display a message in the echo area or in a pop-buffer,
241 depending on its size, use @code{display-message-or-buffer} (see below).
244 @defopt max-mini-window-height
245 This variable specifies the maximum height for resizing minibuffer
246 windows. If a float, it specifies a fraction of the height of the
247 frame. If an integer, it specifies a number of lines.
250 @tindex with-temp-message
251 @defmac with-temp-message message &rest body
252 This construct displays a message in the echo area temporarily, during
253 the execution of @var{body}. It displays @var{message}, executes
254 @var{body}, then returns the value of the last body form while restoring
255 the previous echo area contents.
258 @defun message-or-box string &rest arguments
259 This function displays a message like @code{message}, but may display it
260 in a dialog box instead of the echo area. If this function is called in
261 a command that was invoked using the mouse---more precisely, if
262 @code{last-nonmenu-event} (@pxref{Command Loop Info}) is either
263 @code{nil} or a list---then it uses a dialog box or pop-up menu to
264 display the message. Otherwise, it uses the echo area. (This is the
265 same criterion that @code{y-or-n-p} uses to make a similar decision; see
266 @ref{Yes-or-No Queries}.)
268 You can force use of the mouse or of the echo area by binding
269 @code{last-nonmenu-event} to a suitable value around the call.
272 @defun message-box string &rest arguments
273 This function displays a message like @code{message}, but uses a dialog
274 box (or a pop-up menu) whenever that is possible. If it is impossible
275 to use a dialog box or pop-up menu, because the terminal does not
276 support them, then @code{message-box} uses the echo area, like
280 @defun display-message-or-buffer message &optional buffer-name not-this-window frame
281 @tindex display-message-or-buffer
282 This function displays the message @var{message}, which may be either a
283 string or a buffer. If it is shorter than the maximum height of the
284 echo area, as defined by @code{max-mini-window-height}, it is displayed
285 in the echo area, using @code{message}. Otherwise,
286 @code{display-buffer} is used to show it in a pop-up buffer.
288 Returns either the string shown in the echo area, or when a pop-up
289 buffer is used, the window used to display it.
291 If @var{message} is a string, then the optional argument
292 @var{buffer-name} is the name of the buffer used to display it when a
293 pop-up buffer is used, defaulting to @samp{*Message*}. In the case
294 where @var{message} is a string and displayed in the echo area, it is
295 not specified whether the contents are inserted into the buffer anyway.
297 The optional arguments @var{not-this-window} and @var{frame} are as for
298 @code{display-buffer}, and only used if a buffer is displayed.
301 @defun current-message
302 This function returns the message currently being displayed in the
303 echo area, or @code{nil} if there is none.
306 @defvar cursor-in-echo-area
307 This variable controls where the cursor appears when a message is
308 displayed in the echo area. If it is non-@code{nil}, then the cursor
309 appears at the end of the message. Otherwise, the cursor appears at
310 point---not in the echo area at all.
312 The value is normally @code{nil}; Lisp programs bind it to @code{t}
313 for brief periods of time.
316 @defvar echo-area-clear-hook
317 This normal hook is run whenever the echo area is cleared---either by
318 @code{(message nil)} or for any other reason.
321 Almost all the messages displayed in the echo area are also recorded
322 in the @samp{*Messages*} buffer.
324 @defopt message-log-max
325 This variable specifies how many lines to keep in the @samp{*Messages*}
326 buffer. The value @code{t} means there is no limit on how many lines to
327 keep. The value @code{nil} disables message logging entirely. Here's
328 how to display a message and prevent it from being logged:
331 (let (message-log-max)
336 @defvar echo-keystrokes
337 This variable determines how much time should elapse before command
338 characters echo. Its value must be an integer or floating point number,
340 number of seconds to wait before echoing. If the user types a prefix
341 key (such as @kbd{C-x}) and then delays this many seconds before
342 continuing, the prefix key is echoed in the echo area. (Once echoing
343 begins in a key sequence, all subsequent characters in the same key
344 sequence are echoed immediately.)
346 If the value is zero, then command input is not echoed.
350 @section Reporting Warnings
353 @dfn{Warnings} are a facility for a program to inform the user of a
354 possible problem, but continue running.
357 * Warning Basics:: Warnings concepts and functions to report them.
358 * Warning Variables:: Variables programs bind to customize their warnings.
359 * Warning Options:: Variables users set to control display of warnings.
363 @subsection Warning Basics
364 @cindex severity level
366 Every warning has a textual message, which explains the problem for
367 the user, and a @dfn{severity level} which is a symbol. Here are the
368 possible severity levels, in order of decreasing severity, and their
373 A problem that will seriously impair Emacs operation soon
374 if you do not attend to it promptly.
376 A report of data or circumstances that are inherently wrong.
378 A report of data or circumstances that are not inherently wrong, but
379 raise suspicion of a possible problem.
381 A report of information that may be useful if you are debugging.
384 When your program encounters invalid input data, it can either
385 signal a Lisp error by calling @code{error} or @code{signal} or report
386 a warning with severity @code{:error}. Signaling a Lisp error is the
387 easiest thing to do, but it means the program cannot continue
388 processing. If you want to take the trouble to implement a way to
389 continue processing despite the bad data, then reporting a warning of
390 severity @code{:error} is the right way to inform the user of the
391 problem. For instance, the Emacs Lisp byte compiler can report an
392 error that way and continue compiling other functions. (If the
393 program signals a Lisp error and then handles it with
394 @code{condition-case}, the user won't see the error message; it could
395 show the message to the user by reporting it as a warning.)
398 Each warning has a @dfn{warning type} to classify it. The type is a
399 list of symbols. The first symbol should be the custom group that you
400 use for the program's user options. For example, byte compiler
401 warnings use the warning type @code{(bytecomp)}. You can also
402 subcategorize the warnings, if you wish, by using more symbols in the
405 @defun display-warning type message &optional level buffer-name
406 This function reports a warning, using @var{message} as the message
407 and @var{type} as the warning type. @var{level} should be the
408 severity level, with @code{:warning} being the default.
410 @var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
411 for logging the warning. By default, it is @samp{*Warnings*}.
414 @defun lwarn type level message &rest args
415 This function reports a warning using the value of @code{(format
416 @var{message} @var{args}...)} as the message. In other respects it is
417 equivalent to @code{display-warning}.
420 @defun warn message &rest args
421 This function reports a warning using the value of @code{(format
422 @var{message} @var{args}...)} as the message, @code{(emacs)} as the
423 type, and @code{:warning} as the severity level. It exists for
424 compatibility only; we recommend not using it, because you should
425 specify a specific warning type.
428 @node Warning Variables
429 @subsection Warning Variables
431 Programs can customize how their warnings appear by binding
432 the variables described in this section.
434 @defvar warning-levels
435 This list defines the meaning and severity order of the warning
436 severity levels. Each element defines one severity level,
437 and they are arranged in order of decreasing severity.
439 Each element has the form @code{(@var{level} @var{string}
440 @var{function})}, where @var{level} is the severity level it defines.
441 @var{string} specifies the textual description of this level.
442 @var{string} should use @samp{%s} to specify where to put the warning
443 type information, or it can omit the @samp{%s} so as not to include
446 The optional @var{function}, if non-@code{nil}, is a function to call
447 with no arguments, to get the user's attention.
449 Normally you should not change the value of this variable.
452 @defvar warning-prefix-function
453 If non-@code{nil}, the value is a function to generate prefix text for
454 warnings. Programs can bind the variable to a suitable function.
455 @code{display-warning} calls this function with the warnings buffer
456 current, and the function can insert text in it. That text becomes
457 the beginning of the warning message.
459 The function is called with two arguments, the severity level and its
460 entry in @code{warning-levels}. It should return a list to use as the
461 entry (this value need not be an actual member of
462 @code{warning-levels}). By constructing this value, the function can
463 change the severity of the warning, or specify different handling for
464 a given severity level.
466 If the variable's value is @code{nil} then there is no function
470 @defvar warning-series
471 Programs can bind this variable to @code{t} to say that the next
472 warning should begin a series. When several warnings form a series,
473 that means to leave point on the first warning of the series, rather
474 than keep moving it for each warning so that it appears on the last one.
475 The series ends when the local binding is unbound and
476 @code{warning-series} becomes @code{nil} again.
478 The value can also be a symbol with a function definition. That is
479 equivalent to @code{t}, except that the next warning will also call
480 the function with no arguments with the warnings buffer current. The
481 function can insert text which will serve as a header for the series
484 Once a series has begun, the value is a marker which points to the
485 buffer position in the warnings buffer of the start of the series.
487 The variable's normal value is @code{nil}, which means to handle
488 each warning separately.
491 @defvar warning-fill-prefix
492 When this variable is non-@code{nil}, it specifies a fill prefix to
493 use for filling each warning's text.
496 @defvar warning-type-format
497 This variable specifies the format for displaying the warning type
498 in the warning message. The result of formatting the type this way
499 gets included in the message under the control of the string in the
500 entry in @code{warning-levels}. The default value is @code{" (%s)"}.
501 If you bind it to @code{""} then the warning type won't appear at
505 @node Warning Options
506 @subsection Warning Options
508 These variables are used by users to control what happens
509 when a Lisp program reports a warning.
511 @defopt warning-minimum-level
512 This user option specifies the minimum severity level that should be
513 shown immediately to the user. The default is @code{:warning}, which
514 means to immediately display all warnings except @code{:debug}
518 @defopt warning-minimum-log-level
519 This user option specifies the minimum severity level that should be
520 logged in the warnings buffer. The default is @code{:warning}, which
521 means to log all warnings except @code{:debug} warnings.
524 @defopt warning-suppress-types
525 This list specifies which warning types should not be displayed
526 immediately for the user. Each element of the list should be a list
527 of symbols. If its elements match the first elements in a warning
528 type, then that warning is not displayed immediately.
531 @defopt warning-suppress-log-types
532 This list specifies which warning types should not be logged in the
533 warnings buffer. Each element of the list should be a list of
534 symbols. If it matches the first few elements in a warning type, then
535 that warning is not logged.
539 @section Reporting Operation Progress
540 @cindex progress reporting
542 When an operation can take a while to finish, you should inform the
543 user about the progress it makes. This way the user can estimate
544 remaining time and clearly see that Emacs is busy working, not hung.
546 Functions listed in this section provide simple and efficient way of
547 reporting operation progress. Here is a working example that does
551 (let ((progress-reporter
552 (make-progress-reporter "Collecting some mana for Emacs..."
556 (progress-reporter-update progress-reporter k))
557 (progress-reporter-done progress-reporter))
560 @defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
561 This function creates and returns a @dfn{progress reporter}---an
562 object you will use as an argument for all other functions listed
563 here. The idea is to precompute as much data as possible to make
564 progress reporting very fast.
566 When this progress reporter is subsequently used, it will display
567 @var{message} in the echo area, followed by progress percentage.
568 @var{message} is treated as a simple string. If you need it to depend
569 on a filename, for instance, use @code{format} before calling this
572 @var{min-value} and @var{max-value} arguments stand for starting and
573 final states of your operation. For instance, if you scan a buffer,
574 they should be the results of @code{point-min} and @code{point-max}
575 correspondingly. It is required that @var{max-value} is greater than
576 @var{min-value}. If you create progress reporter when some part of
577 the operation has already been completed, then specify
578 @var{current-value} argument. But normally you should omit it or set
579 it to @code{nil}---it will default to @var{min-value} then.
581 Remaining arguments control the rate of echo area updates. Progress
582 reporter will wait for at least @var{min-change} more percents of the
583 operation to be completed before printing next message.
584 @var{min-time} specifies the minimum time in seconds to pass between
585 successive prints. It can be fractional. Depending on Emacs and
586 system capabilities, progress reporter may or may not respect this
587 last argument or do it with varying precision. Default value for
588 @var{min-change} is 1 (one percent), for @var{min-time}---0.2
591 This function calls @code{progress-reporter-update}, so the first
592 message is printed immediately.
595 @defun progress-reporter-update reporter value
596 This function does the main work of reporting progress of your
597 operation. It displays the message of @var{reporter}, followed by
598 progress percentage determined by @var{value}. If percentage is zero,
599 or close enough according to the @var{min-change} and @var{min-time}
600 arguments, then it is omitted from the output.
602 @var{reporter} must be the result of a call to
603 @code{make-progress-reporter}. @var{value} specifies the current
604 state of your operation and must be between @var{min-value} and
605 @var{max-value} (inclusive) as passed to
606 @code{make-progress-reporter}. For instance, if you scan a buffer,
607 then @var{value} should be the result of a call to @code{point}.
609 This function respects @var{min-change} and @var{min-time} as passed
610 to @code{make-progress-reporter} and so does not output new messages
611 on every invocation. It is thus very fast and normally you should not
612 try to reduce the number of calls to it: resulting overhead will most
613 likely negate your effort.
616 @defun progress-reporter-force-update reporter value &optional new-message
617 This function is similar to @code{progress-reporter-update} except
618 that it prints a message in the echo area unconditionally.
620 The first two arguments have the same meaning as for
621 @code{progress-reporter-update}. Optional @var{new-message} allows
622 you to change the message of the @var{reporter}. Since this functions
623 always updates the echo area, such a change will be immediately
624 presented to the user.
627 @defun progress-reporter-done reporter
628 This function should be called when the operation is finished. It
629 prints the message of @var{reporter} followed by word ``done'' in the
632 You should always call this function and not hope for
633 @code{progress-reporter-update} to print ``100%.'' Firstly, it may
634 never print it, there are many good reasons for this not to happen.
635 Secondly, ``done'' is more explicit.
638 @defmac dotimes-with-progress-reporter (var count [result]) message body...
639 This is a convenience macro that works the same way as @code{dotimes}
640 does, but also reports loop progress using the functions described
641 above. It allows you to save some typing.
643 You can rewrite the example in the beginning of this node using
647 (dotimes-with-progress-reporter
649 "Collecting some mana for Emacs..."
655 @section Invisible Text
657 @cindex invisible text
658 You can make characters @dfn{invisible}, so that they do not appear on
659 the screen, with the @code{invisible} property. This can be either a
660 text property (@pxref{Text Properties}) or a property of an overlay
661 (@pxref{Overlays}). Cursor motion also partly ignores these
662 characters; if the command loop finds point within them, it moves
663 point to the other side of them.
665 In the simplest case, any non-@code{nil} @code{invisible} property makes
666 a character invisible. This is the default case---if you don't alter
667 the default value of @code{buffer-invisibility-spec}, this is how the
668 @code{invisible} property works. You should normally use @code{t}
669 as the value of the @code{invisible} property if you don't plan
670 to set @code{buffer-invisibility-spec} yourself.
672 More generally, you can use the variable @code{buffer-invisibility-spec}
673 to control which values of the @code{invisible} property make text
674 invisible. This permits you to classify the text into different subsets
675 in advance, by giving them different @code{invisible} values, and
676 subsequently make various subsets visible or invisible by changing the
677 value of @code{buffer-invisibility-spec}.
679 Controlling visibility with @code{buffer-invisibility-spec} is
680 especially useful in a program to display the list of entries in a
681 database. It permits the implementation of convenient filtering
682 commands to view just a part of the entries in the database. Setting
683 this variable is very fast, much faster than scanning all the text in
684 the buffer looking for properties to change.
686 @defvar buffer-invisibility-spec
687 This variable specifies which kinds of @code{invisible} properties
688 actually make a character invisible. Setting this variable makes it
693 A character is invisible if its @code{invisible} property is
694 non-@code{nil}. This is the default.
697 Each element of the list specifies a criterion for invisibility; if a
698 character's @code{invisible} property fits any one of these criteria,
699 the character is invisible. The list can have two kinds of elements:
703 A character is invisible if its @code{invisible} property value
704 is @var{atom} or if it is a list with @var{atom} as a member.
706 @item (@var{atom} . t)
707 A character is invisible if its @code{invisible} property value
708 is @var{atom} or if it is a list with @var{atom} as a member.
709 Moreover, if this character is at the end of a line and is followed
710 by a visible newline, it displays an ellipsis.
715 Two functions are specifically provided for adding elements to
716 @code{buffer-invisibility-spec} and removing elements from it.
718 @defun add-to-invisibility-spec element
719 This function adds the element @var{element} to
720 @code{buffer-invisibility-spec} (if it is not already present in that
721 list). If @code{buffer-invisibility-spec} was @code{t}, it changes to
722 a list, @code{(t)}, so that text whose @code{invisible} property
723 is @code{t} remains invisible.
726 @defun remove-from-invisibility-spec element
727 This removes the element @var{element} from
728 @code{buffer-invisibility-spec}. This does nothing if @var{element}
732 A convention for use of @code{buffer-invisibility-spec} is that a
733 major mode should use the mode's own name as an element of
734 @code{buffer-invisibility-spec} and as the value of the
735 @code{invisible} property:
738 ;; @r{If you want to display an ellipsis:}
739 (add-to-invisibility-spec '(my-symbol . t))
740 ;; @r{If you don't want ellipsis:}
741 (add-to-invisibility-spec 'my-symbol)
743 (overlay-put (make-overlay beginning end)
744 'invisible 'my-symbol)
746 ;; @r{When done with the overlays:}
747 (remove-from-invisibility-spec '(my-symbol . t))
748 ;; @r{Or respectively:}
749 (remove-from-invisibility-spec 'my-symbol)
752 @vindex line-move-ignore-invisible
753 Ordinarily, functions that operate on text or move point do not care
754 whether the text is invisible. The user-level line motion commands
755 explicitly ignore invisible newlines if
756 @code{line-move-ignore-invisible} is non-@code{nil} (the default), but
757 only because they are explicitly programmed to do so.
759 However, if a command ends with point inside or immediately after
760 invisible text, the main editing loop moves point further forward or
761 further backward (in the same direction that the command already moved
762 it) until that condition is no longer true. Thus, if the command
763 moved point back into an invisible range, Emacs moves point back to
764 the beginning of that range, following the previous visible character.
765 If the command moved point forward into an invisible range, Emacs
766 moves point forward past the first visible character that follows the
769 Incremental search can make invisible overlays visible temporarily
770 and/or permanently when a match includes invisible text. To enable
771 this, the overlay should have a non-@code{nil}
772 @code{isearch-open-invisible} property. The property value should be a
773 function to be called with the overlay as an argument. This function
774 should make the overlay visible permanently; it is used when the match
775 overlaps the overlay on exit from the search.
777 During the search, such overlays are made temporarily visible by
778 temporarily modifying their invisible and intangible properties. If you
779 want this to be done differently for a certain overlay, give it an
780 @code{isearch-open-invisible-temporary} property which is a function.
781 The function is called with two arguments: the first is the overlay, and
782 the second is @code{nil} to make the overlay visible, or @code{t} to
783 make it invisible again.
785 @node Selective Display
786 @section Selective Display
787 @cindex selective display
789 @dfn{Selective display} refers to a pair of related features for
790 hiding certain lines on the screen.
792 The first variant, explicit selective display, is designed for use
793 in a Lisp program: it controls which lines are hidden by altering the
794 text. This kind of hiding in some ways resembles the effect of the
795 @code{invisible} property (@pxref{Invisible Text}), but the two
796 features are different and do not work the same way.
798 In the second variant, the choice of lines to hide is made
799 automatically based on indentation. This variant is designed to be a
802 The way you control explicit selective display is by replacing a
803 newline (control-j) with a carriage return (control-m). The text that
804 was formerly a line following that newline is now hidden. Strictly
805 speaking, it is temporarily no longer a line at all, since only
806 newlines can separate lines; it is now part of the previous line.
808 Selective display does not directly affect editing commands. For
809 example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly
810 into hidden text. However, the replacement of newline characters with
811 carriage return characters affects some editing commands. For
812 example, @code{next-line} skips hidden lines, since it searches only
813 for newlines. Modes that use selective display can also define
814 commands that take account of the newlines, or that control which
815 parts of the text are hidden.
817 When you write a selectively displayed buffer into a file, all the
818 control-m's are output as newlines. This means that when you next read
819 in the file, it looks OK, with nothing hidden. The selective display
820 effect is seen only within Emacs.
822 @defvar selective-display
823 This buffer-local variable enables selective display. This means that
824 lines, or portions of lines, may be made hidden.
828 If the value of @code{selective-display} is @code{t}, then the character
829 control-m marks the start of hidden text; the control-m, and the rest
830 of the line following it, are not displayed. This is explicit selective
834 If the value of @code{selective-display} is a positive integer, then
835 lines that start with more than that many columns of indentation are not
839 When some portion of a buffer is hidden, the vertical movement
840 commands operate as if that portion did not exist, allowing a single
841 @code{next-line} command to skip any number of hidden lines.
842 However, character movement commands (such as @code{forward-char}) do
843 not skip the hidden portion, and it is possible (if tricky) to insert
844 or delete text in an hidden portion.
846 In the examples below, we show the @emph{display appearance} of the
847 buffer @code{foo}, which changes with the value of
848 @code{selective-display}. The @emph{contents} of the buffer do not
853 (setq selective-display nil)
856 ---------- Buffer: foo ----------
863 ---------- Buffer: foo ----------
867 (setq selective-display 2)
870 ---------- Buffer: foo ----------
875 ---------- Buffer: foo ----------
880 @defvar selective-display-ellipses
881 If this buffer-local variable is non-@code{nil}, then Emacs displays
882 @samp{@dots{}} at the end of a line that is followed by hidden text.
883 This example is a continuation of the previous one.
887 (setq selective-display-ellipses t)
890 ---------- Buffer: foo ----------
895 ---------- Buffer: foo ----------
899 You can use a display table to substitute other text for the ellipsis
900 (@samp{@dots{}}). @xref{Display Tables}.
903 @node Temporary Displays
904 @section Temporary Displays
906 Temporary displays are used by Lisp programs to put output into a
907 buffer and then present it to the user for perusal rather than for
908 editing. Many help commands use this feature.
910 @defspec with-output-to-temp-buffer buffer-name forms@dots{}
911 This function executes @var{forms} while arranging to insert any output
912 they print into the buffer named @var{buffer-name}, which is first
913 created if necessary, and put into Help mode. Finally, the buffer is
914 displayed in some window, but not selected.
916 If the @var{forms} do not change the major mode in the output buffer,
917 so that it is still Help mode at the end of their execution, then
918 @code{with-output-to-temp-buffer} makes this buffer read-only at the
919 end, and also scans it for function and variable names to make them
920 into clickable cross-references. @xref{Docstring hyperlinks, , Tips
921 for Documentation Strings}, in particular the item on hyperlinks in
922 documentation strings, for more details.
924 The string @var{buffer-name} specifies the temporary buffer, which
925 need not already exist. The argument must be a string, not a buffer.
926 The buffer is erased initially (with no questions asked), and it is
927 marked as unmodified after @code{with-output-to-temp-buffer} exits.
929 @code{with-output-to-temp-buffer} binds @code{standard-output} to the
930 temporary buffer, then it evaluates the forms in @var{forms}. Output
931 using the Lisp output functions within @var{forms} goes by default to
932 that buffer (but screen display and messages in the echo area, although
933 they are ``output'' in the general sense of the word, are not affected).
934 @xref{Output Functions}.
936 Several hooks are available for customizing the behavior
937 of this construct; they are listed below.
939 The value of the last form in @var{forms} is returned.
943 ---------- Buffer: foo ----------
944 This is the contents of foo.
945 ---------- Buffer: foo ----------
949 (with-output-to-temp-buffer "foo"
951 (print standard-output))
952 @result{} #<buffer foo>
954 ---------- Buffer: foo ----------
959 ---------- Buffer: foo ----------
964 @defvar temp-buffer-show-function
965 If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
966 calls it as a function to do the job of displaying a help buffer. The
967 function gets one argument, which is the buffer it should display.
969 It is a good idea for this function to run @code{temp-buffer-show-hook}
970 just as @code{with-output-to-temp-buffer} normally would, inside of
971 @code{save-selected-window} and with the chosen window and buffer
975 @defvar temp-buffer-setup-hook
976 @tindex temp-buffer-setup-hook
977 This normal hook is run by @code{with-output-to-temp-buffer} before
978 evaluating @var{body}. When the hook runs, the temporary buffer is
979 current. This hook is normally set up with a function to put the
983 @defvar temp-buffer-show-hook
984 This normal hook is run by @code{with-output-to-temp-buffer} after
985 displaying the temporary buffer. When the hook runs, the temporary buffer
986 is current, and the window it was displayed in is selected. This hook
987 is normally set up with a function to make the buffer read only, and
988 find function names and variable names in it, provided the major mode
992 @defun momentary-string-display string position &optional char message
993 This function momentarily displays @var{string} in the current buffer at
994 @var{position}. It has no effect on the undo list or on the buffer's
997 The momentary display remains until the next input event. If the next
998 input event is @var{char}, @code{momentary-string-display} ignores it
999 and returns. Otherwise, that event remains buffered for subsequent use
1000 as input. Thus, typing @var{char} will simply remove the string from
1001 the display, while typing (say) @kbd{C-f} will remove the string from
1002 the display and later (presumably) move point forward. The argument
1003 @var{char} is a space by default.
1005 The return value of @code{momentary-string-display} is not meaningful.
1007 If the string @var{string} does not contain control characters, you can
1008 do the same job in a more general way by creating (and then subsequently
1009 deleting) an overlay with a @code{before-string} property.
1010 @xref{Overlay Properties}.
1012 If @var{message} is non-@code{nil}, it is displayed in the echo area
1013 while @var{string} is displayed in the buffer. If it is @code{nil}, a
1014 default message says to type @var{char} to continue.
1016 In this example, point is initially located at the beginning of the
1021 ---------- Buffer: foo ----------
1022 This is the contents of foo.
1023 @point{}Second line.
1024 ---------- Buffer: foo ----------
1028 (momentary-string-display
1029 "**** Important Message! ****"
1031 "Type RET when done reading")
1036 ---------- Buffer: foo ----------
1037 This is the contents of foo.
1038 **** Important Message! ****Second line.
1039 ---------- Buffer: foo ----------
1041 ---------- Echo Area ----------
1042 Type RET when done reading
1043 ---------- Echo Area ----------
1052 You can use @dfn{overlays} to alter the appearance of a buffer's text on
1053 the screen, for the sake of presentation features. An overlay is an
1054 object that belongs to a particular buffer, and has a specified
1055 beginning and end. It also has properties that you can examine and set;
1056 these affect the display of the text within the overlay.
1058 An overlays uses markers to record its beginning and end; thus,
1059 editing the text of the buffer adjusts the beginning and end of each
1060 overlay so that it stays with the text. When you create the overlay,
1061 you can specify whether text inserted at the beginning should be
1062 inside the overlay or outside, and likewise for the end of the overlay.
1065 * Managing Overlays:: Creating and moving overlays.
1066 * Overlay Properties:: How to read and set properties.
1067 What properties do to the screen display.
1068 * Finding Overlays:: Searching for overlays.
1071 @node Managing Overlays
1072 @subsection Managing Overlays
1074 This section describes the functions to create, delete and move
1075 overlays, and to examine their contents. Overlay changes are not
1076 recorded in the buffer's undo list, since the overlays are not
1077 part of the buffer's contents.
1079 @defun overlayp object
1080 This function returns @code{t} if @var{object} is an overlay.
1083 @defun make-overlay start end &optional buffer front-advance rear-advance
1084 This function creates and returns an overlay that belongs to
1085 @var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
1086 and @var{end} must specify buffer positions; they may be integers or
1087 markers. If @var{buffer} is omitted, the overlay is created in the
1090 The arguments @var{front-advance} and @var{rear-advance} specify the
1091 insertion type for the start of the overlay and for the end of the
1092 overlay, respectively. @xref{Marker Insertion Types}. If
1093 @var{front-advance} is non-@code{nil}, text inserted at the beginning
1094 of the overlay is excluded from the overlay. If @var{read-advance} is
1095 non-@code{nil}, text inserted at the beginning of the overlay is
1096 included in the overlay.
1099 @defun overlay-start overlay
1100 This function returns the position at which @var{overlay} starts,
1104 @defun overlay-end overlay
1105 This function returns the position at which @var{overlay} ends,
1109 @defun overlay-buffer overlay
1110 This function returns the buffer that @var{overlay} belongs to. It
1111 returns @code{nil} if @var{overlay} has been deleted.
1114 @defun delete-overlay overlay
1115 This function deletes @var{overlay}. The overlay continues to exist as
1116 a Lisp object, and its property list is unchanged, but it ceases to be
1117 attached to the buffer it belonged to, and ceases to have any effect on
1120 A deleted overlay is not permanently disconnected. You can give it a
1121 position in a buffer again by calling @code{move-overlay}.
1124 @defun move-overlay overlay start end &optional buffer
1125 This function moves @var{overlay} to @var{buffer}, and places its bounds
1126 at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
1127 must specify buffer positions; they may be integers or markers.
1129 If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
1130 was already associated with; if @var{overlay} was deleted, it goes into
1133 The return value is @var{overlay}.
1135 This is the only valid way to change the endpoints of an overlay. Do
1136 not try modifying the markers in the overlay by hand, as that fails to
1137 update other vital data structures and can cause some overlays to be
1141 @defun remove-overlays &optional start end name value
1142 This function removes all the overlays between @var{start} and
1143 @var{end} whose property @var{name} has the value @var{value}. It can
1144 move the endpoints of the overlays in the region, or split them.
1146 If @var{name} is omitted or nil, it means to delete all overlays in
1147 the specified region. If @var{start} and/or @var{end} are omitted or
1148 nil, that means the beginning and end of the buffer respectively.
1149 Therefore, @code{(remove-overlays)} removes all the overlays in the
1153 Here are some examples:
1156 ;; @r{Create an overlay.}
1157 (setq foo (make-overlay 1 10))
1158 @result{} #<overlay from 1 to 10 in display.texi>
1163 (overlay-buffer foo)
1164 @result{} #<buffer display.texi>
1165 ;; @r{Give it a property we can check later.}
1166 (overlay-put foo 'happy t)
1168 ;; @r{Verify the property is present.}
1169 (overlay-get foo 'happy)
1171 ;; @r{Move the overlay.}
1172 (move-overlay foo 5 20)
1173 @result{} #<overlay from 5 to 20 in display.texi>
1178 ;; @r{Delete the overlay.}
1179 (delete-overlay foo)
1181 ;; @r{Verify it is deleted.}
1183 @result{} #<overlay in no buffer>
1184 ;; @r{A deleted overlay has no position.}
1189 (overlay-buffer foo)
1191 ;; @r{Undelete the overlay.}
1192 (move-overlay foo 1 20)
1193 @result{} #<overlay from 1 to 20 in display.texi>
1194 ;; @r{Verify the results.}
1199 (overlay-buffer foo)
1200 @result{} #<buffer display.texi>
1201 ;; @r{Moving and deleting the overlay does not change its properties.}
1202 (overlay-get foo 'happy)
1206 @node Overlay Properties
1207 @subsection Overlay Properties
1209 Overlay properties are like text properties in that the properties that
1210 alter how a character is displayed can come from either source. But in
1211 most respects they are different. @xref{Text Properties}, for comparison.
1213 Text properties are considered a part of the text; overlays and
1214 their properties are specifically considered not to be part of the
1215 text. Thus, copying text between various buffers and strings
1216 preserves text properties, but does not try to preserve overlays.
1217 Changing a buffer's text properties marks the buffer as modified,
1218 while moving an overlay or changing its properties does not. Unlike
1219 text property changes, overlay property changes are not recorded in
1220 the buffer's undo list.
1222 These functions read and set the properties of an overlay:
1224 @defun overlay-get overlay prop
1225 This function returns the value of property @var{prop} recorded in
1226 @var{overlay}, if any. If @var{overlay} does not record any value for
1227 that property, but it does have a @code{category} property which is a
1228 symbol, that symbol's @var{prop} property is used. Otherwise, the value
1232 @defun overlay-put overlay prop value
1233 This function sets the value of property @var{prop} recorded in
1234 @var{overlay} to @var{value}. It returns @var{value}.
1237 @defun overlay-properties overlay
1238 This returns a copy of the property list of @var{overlay}.
1241 See also the function @code{get-char-property} which checks both
1242 overlay properties and text properties for a given character.
1243 @xref{Examining Properties}.
1245 Many overlay properties have special meanings; here is a table
1250 @kindex priority @r{(overlay property)}
1251 This property's value (which should be a nonnegative integer number)
1252 determines the priority of the overlay. The priority matters when two
1253 or more overlays cover the same character and both specify the same
1254 property; the one whose @code{priority} value is larger takes priority
1255 over the other. For the @code{face} property, the higher priority
1256 value does not completely replace the other; instead, its face
1257 attributes override the face attributes of the lower priority
1258 @code{face} property.
1260 Currently, all overlays take priority over text properties. Please
1261 avoid using negative priority values, as we have not yet decided just
1262 what they should mean.
1265 @kindex window @r{(overlay property)}
1266 If the @code{window} property is non-@code{nil}, then the overlay
1267 applies only on that window.
1270 @kindex category @r{(overlay property)}
1271 If an overlay has a @code{category} property, we call it the
1272 @dfn{category} of the overlay. It should be a symbol. The properties
1273 of the symbol serve as defaults for the properties of the overlay.
1276 @kindex face @r{(overlay property)}
1277 This property controls the way text is displayed---for example, which
1278 font and which colors. @xref{Faces}, for more information.
1280 In the simplest case, the value is a face name. It can also be a list;
1281 then each element can be any of these possibilities:
1285 A face name (a symbol or string).
1288 A property list of face attributes. This has the form (@var{keyword}
1289 @var{value} @dots{}), where each @var{keyword} is a face attribute
1290 name and @var{value} is a meaningful value for that attribute. With
1291 this feature, you do not need to create a face each time you want to
1292 specify a particular attribute for certain text. @xref{Face
1296 A cons cell of the form @code{(foreground-color . @var{color-name})} or
1297 @code{(background-color . @var{color-name})}. These elements specify
1298 just the foreground color or just the background color.
1300 @code{(foreground-color . @var{color-name})} is equivalent to
1301 @code{(:foreground @var{color-name})}, and likewise for the background.
1305 @kindex mouse-face @r{(overlay property)}
1306 This property is used instead of @code{face} when the mouse is within
1307 the range of the overlay.
1310 @kindex display @r{(overlay property)}
1311 This property activates various features that change the
1312 way text is displayed. For example, it can make text appear taller
1313 or shorter, higher or lower, wider or narrower, or replaced with an image.
1314 @xref{Display Property}.
1317 @kindex help-echo @r{(overlay property)}
1318 If an overlay has a @code{help-echo} property, then when you move the
1319 mouse onto the text in the overlay, Emacs displays a help string in the
1320 echo area, or in the tooltip window. For details see @ref{Text
1323 @item modification-hooks
1324 @kindex modification-hooks @r{(overlay property)}
1325 This property's value is a list of functions to be called if any
1326 character within the overlay is changed or if text is inserted strictly
1329 The hook functions are called both before and after each change.
1330 If the functions save the information they receive, and compare notes
1331 between calls, they can determine exactly what change has been made
1334 When called before a change, each function receives four arguments: the
1335 overlay, @code{nil}, and the beginning and end of the text range to be
1338 When called after a change, each function receives five arguments: the
1339 overlay, @code{t}, the beginning and end of the text range just
1340 modified, and the length of the pre-change text replaced by that range.
1341 (For an insertion, the pre-change length is zero; for a deletion, that
1342 length is the number of characters deleted, and the post-change
1343 beginning and end are equal.)
1345 @item insert-in-front-hooks
1346 @kindex insert-in-front-hooks @r{(overlay property)}
1347 This property's value is a list of functions to be called before and
1348 after inserting text right at the beginning of the overlay. The calling
1349 conventions are the same as for the @code{modification-hooks} functions.
1351 @item insert-behind-hooks
1352 @kindex insert-behind-hooks @r{(overlay property)}
1353 This property's value is a list of functions to be called before and
1354 after inserting text right at the end of the overlay. The calling
1355 conventions are the same as for the @code{modification-hooks} functions.
1358 @kindex invisible @r{(overlay property)}
1359 The @code{invisible} property can make the text in the overlay
1360 invisible, which means that it does not appear on the screen.
1361 @xref{Invisible Text}, for details.
1364 @kindex intangible @r{(overlay property)}
1365 The @code{intangible} property on an overlay works just like the
1366 @code{intangible} text property. @xref{Special Properties}, for details.
1368 @item isearch-open-invisible
1369 This property tells incremental search how to make an invisible overlay
1370 visible, permanently, if the final match overlaps it. @xref{Invisible
1373 @item isearch-open-invisible-temporary
1374 This property tells incremental search how to make an invisible overlay
1375 visible, temporarily, during the search. @xref{Invisible Text}.
1378 @kindex before-string @r{(overlay property)}
1379 This property's value is a string to add to the display at the beginning
1380 of the overlay. The string does not appear in the buffer in any
1381 sense---only on the screen.
1384 @kindex after-string @r{(overlay property)}
1385 This property's value is a string to add to the display at the end of
1386 the overlay. The string does not appear in the buffer in any
1387 sense---only on the screen.
1390 @kindex evaporate @r{(overlay property)}
1391 If this property is non-@code{nil}, the overlay is deleted automatically
1392 if it becomes empty (i.e., if its length becomes zero). If you give
1393 an empty overlay a non-@code{nil} @code{evaporate} property, that deletes
1397 @cindex keymap of character (and overlays)
1398 @kindex local-map @r{(overlay property)}
1399 If this property is non-@code{nil}, it specifies a keymap for a portion
1400 of the text. The property's value replaces the buffer's local map, when
1401 the character after point is within the overlay. @xref{Active Keymaps}.
1404 @kindex keymap @r{(overlay property)}
1405 The @code{keymap} property is similar to @code{local-map} but overrides the
1406 buffer's local map (and the map specified by the @code{local-map}
1407 property) rather than replacing it.
1410 @node Finding Overlays
1411 @subsection Searching for Overlays
1413 @defun overlays-at pos
1414 This function returns a list of all the overlays that cover the
1415 character at position @var{pos} in the current buffer. The list is in
1416 no particular order. An overlay contains position @var{pos} if it
1417 begins at or before @var{pos}, and ends after @var{pos}.
1419 To illustrate usage, here is a Lisp function that returns a list of the
1420 overlays that specify property @var{prop} for the character at point:
1423 (defun find-overlays-specifying (prop)
1424 (let ((overlays (overlays-at (point)))
1427 (let ((overlay (car overlays)))
1428 (if (overlay-get overlay prop)
1429 (setq found (cons overlay found))))
1430 (setq overlays (cdr overlays)))
1435 @defun overlays-in beg end
1436 This function returns a list of the overlays that overlap the region
1437 @var{beg} through @var{end}. ``Overlap'' means that at least one
1438 character is contained within the overlay and also contained within the
1439 specified region; however, empty overlays are included in the result if
1440 they are located at @var{beg}, or strictly between @var{beg} and @var{end}.
1443 @defun next-overlay-change pos
1444 This function returns the buffer position of the next beginning or end
1445 of an overlay, after @var{pos}. If there is none, it returns
1449 @defun previous-overlay-change pos
1450 This function returns the buffer position of the previous beginning or
1451 end of an overlay, before @var{pos}. If there is none, it returns
1455 Here's an easy way to use @code{next-overlay-change} to search for the
1456 next character which gets a non-@code{nil} @code{happy} property from
1457 either its overlays or its text properties (@pxref{Property Search}):
1460 (defun find-overlay-prop (prop)
1462 (while (and (not (eobp))
1463 (not (get-char-property (point) 'happy)))
1464 (goto-char (min (next-overlay-change (point))
1465 (next-single-property-change (point) 'happy))))
1472 Since not all characters have the same width, these functions let you
1473 check the width of a character. @xref{Primitive Indent}, and
1474 @ref{Screen Lines}, for related functions.
1476 @defun char-width char
1477 This function returns the width in columns of the character @var{char},
1478 if it were displayed in the current buffer and the selected window.
1481 @defun string-width string
1482 This function returns the width in columns of the string @var{string},
1483 if it were displayed in the current buffer and the selected window.
1486 @defun truncate-string-to-width string width &optional start-column padding ellipsis
1487 This function returns the part of @var{string} that fits within
1488 @var{width} columns, as a new string.
1490 If @var{string} does not reach @var{width}, then the result ends where
1491 @var{string} ends. If one multi-column character in @var{string}
1492 extends across the column @var{width}, that character is not included in
1493 the result. Thus, the result can fall short of @var{width} but cannot
1496 The optional argument @var{start-column} specifies the starting column.
1497 If this is non-@code{nil}, then the first @var{start-column} columns of
1498 the string are omitted from the value. If one multi-column character in
1499 @var{string} extends across the column @var{start-column}, that
1500 character is not included.
1502 The optional argument @var{padding}, if non-@code{nil}, is a padding
1503 character added at the beginning and end of the result string, to extend
1504 it to exactly @var{width} columns. The padding character is used at the
1505 end of the result if it falls short of @var{width}. It is also used at
1506 the beginning of the result if one multi-column character in
1507 @var{string} extends across the column @var{start-column}.
1509 If @var{ellipsis} is non-@code{nil}, it should be a string which will
1510 replace the end of @var{str} (including any padding) if it extends
1511 beyond @var{end-column}, unless the display width of @var{str} is
1512 equal to or less than the display width of @var{ellipsis}. If
1513 @var{ellipsis} is non-@code{nil} and not a string, it stands for
1517 (truncate-string-to-width "\tab\t" 12 4)
1519 (truncate-string-to-width "\tab\t" 12 4 ?\s)
1525 @section Line Height
1528 The total height of each display line consists of the height of the
1529 contents of the line, and additional vertical line spacing below the
1532 The height of the line contents is normally determined from the
1533 maximum height of any character or image on that display line,
1534 including the final newline if there is one. (A line that is
1535 continued doesn't include a final newline.) In the most common case,
1536 the line height equals the height of the default frame font.
1538 There are several ways to explicitly control or change the line
1539 height, either by specifying an absolute height for the display line,
1540 or by adding additional vertical space below one or all lines.
1542 @kindex line-height @r{(text property)}
1543 A newline can have a @code{line-height} text or overlay property
1544 that controls the total height of the display line ending in that
1547 If the property value is a list @code{(@var{height} @var{total})},
1548 then @var{height} is used as the actual property value for the
1549 @code{line-height}, and @var{total} specifies the total displayed
1550 height of the line, so the line spacing added below the line equals
1551 the @var{total} height minus the actual line height. In this case,
1552 the other ways to specify the line spacing are ignored.
1554 If the property value is @code{t}, the displayed height of the
1555 line is exactly what its contents demand; no line-spacing is added.
1556 This case is useful for tiling small images or image slices without
1557 adding blank areas between the images.
1559 If the property value is not @code{t}, it is a height spec. A height
1560 spec stands for a numeric height value; this heigh spec specifies the
1561 actual line height, @var{line-height}. There are several ways to
1562 write a height spec; here's how each of them translates into a numeric
1567 If the height spec is a positive integer, the height value is that integer.
1569 If the height spec is a float, @var{float}, the numeric height value
1570 is @var{float} times the frame's default line height.
1571 @item (@var{face} . @var{ratio})
1572 If the height spec is a cons of the format shown, the numeric height
1573 is @var{ratio} times the height of face @var{face}. @var{ratio} can
1574 be any type of number, or @code{nil} which means a ratio of 1.
1575 If @var{face} is @code{t}, it refers to the current face.
1576 @item (@code{nil} . @var{ratio})
1577 If the height spec is a cons of the format shown, the numeric height
1578 is @var{ratio} times the height of the contents of the line.
1581 Thus, any valid non-@code{t} property value specifies a height in pixels,
1582 @var{line-height}, one way or another. If the line contents' height
1583 is less than @var{line-height}, Emacs adds extra vertical space above
1584 the line to achieve the total height @var{line-height}. Otherwise,
1585 @var{line-height} has no effect.
1587 If you don't specify the @code{line-height} propery, the line's
1588 height consists of the contents' height plus the line spacing.
1589 There are several ways to specify the line spacing for different
1590 parts of Emacs text.
1592 @vindex default-line-spacing
1593 You can specify the line spacing for all lines in a frame with the
1594 @code{line-spacing} frame parameter, @xref{Window Frame Parameters}.
1595 However, if the variable @code{default-line-spacing} is
1596 non-@code{nil}, it overrides the frame's @code{line-spacing}
1597 parameter. An integer value specifies the number of pixels put below
1598 lines on window systems. A floating point number specifies the
1599 spacing relative to the frame's default line height.
1601 @vindex line-spacing
1602 You can specify the line spacing for all lines in a buffer via the
1603 buffer-local @code{line-spacing} variable. An integer value specifies
1604 the number of pixels put below lines on window systems. A floating
1605 point number specifies the spacing relative to the default frame line
1606 height. This overrides line spacings specified for the frame.
1608 @kindex line-spacing @r{(text property)}
1609 Finally, a newline can have a @code{line-spacing} text or overlay
1610 property that controls the height of the display line ending with that
1611 newline. The property value overrides the default frame line spacing
1612 and the buffer local @code{line-spacing} variable.
1614 One way or another, these mechanisms specify a Lisp value for the
1615 spacing of each line. The value is a height spec, and it translates
1616 into a Lisp value as described above. However, in this case the
1617 numeric height value specifies the line spacing, rather than the line
1624 A @dfn{face} is a named collection of graphical attributes: font
1625 family, foreground color, background color, optional underlining, and
1626 many others. Faces are used in Emacs to control the style of display of
1627 particular parts of the text or the frame.
1630 Each face has its own @dfn{face number}, which distinguishes faces at
1631 low levels within Emacs. However, for most purposes, you refer to
1632 faces in Lisp programs by their names.
1635 This function returns @code{t} if @var{object} is a face name symbol (or
1636 if it is a vector of the kind used internally to record face data). It
1637 returns @code{nil} otherwise.
1640 Each face name is meaningful for all frames, and by default it has the
1641 same meaning in all frames. But you can arrange to give a particular
1642 face name a special meaning in one frame if you wish.
1645 * Standard Faces:: The faces Emacs normally comes with.
1646 * Defining Faces:: How to define a face with @code{defface}.
1647 * Face Attributes:: What is in a face?
1648 * Attribute Functions:: Functions to examine and set face attributes.
1649 * Displaying Faces:: How Emacs combines the faces specified for a character.
1650 * Font Selection:: Finding the best available font for a face.
1651 * Face Functions:: How to define and examine faces.
1652 * Auto Faces:: Hook for automatic face assignment.
1653 * Font Lookup:: Looking up the names of available fonts
1654 and information about them.
1655 * Fontsets:: A fontset is a collection of fonts
1656 that handle a range of character sets.
1659 @node Standard Faces
1660 @subsection Standard Faces
1662 This table lists all the standard faces and their uses. Most of them
1663 are used for displaying certain parts of the frames or certain kinds of
1664 text; you can control how those places look by customizing these faces.
1668 @kindex default @r{(face name)}
1669 This face is used for ordinary text.
1672 @kindex mode-line @r{(face name)}
1673 This face is used for the mode line of the selected window, and for
1674 menu bars when toolkit menus are not used---but only if
1675 @code{mode-line-inverse-video} is non-@code{nil}.
1678 @kindex modeline @r{(face name)}
1679 This is an alias for the @code{mode-line} face, for compatibility with
1682 @item mode-line-inactive
1683 @kindex mode-line-inactive @r{(face name)}
1684 This face is used for mode lines of non-selected windows.
1685 This face inherits from @code{mode-line}, so changes
1686 in that face affect all windows.
1689 @kindex header-line @r{(face name)}
1690 This face is used for the header lines of windows that have them.
1693 This face controls the display of menus, both their colors and their
1694 font. (This works only on certain systems.)
1697 @kindex fringe @r{(face name)}
1698 This face controls the default colors of window fringes, the thin areas on
1699 either side that are used to display continuation and truncation glyphs.
1701 @item minibuffer-prompt
1702 @kindex minibuffer-prompt @r{(face name)}
1703 @vindex minibuffer-prompt-properties
1704 This face is used for the text of minibuffer prompts. By default,
1705 Emacs automatically adds this face to the value of
1706 @code{minibuffer-prompt-properties}, which is a list of text
1707 properties used to display the prompt text.
1710 @kindex scroll-bar @r{(face name)}
1711 This face controls the colors for display of scroll bars.
1714 @kindex tool-bar @r{(face name)}
1715 This face is used for display of the tool bar, if any.
1718 @kindex region @r{(face name)}
1719 This face is used for highlighting the region in Transient Mark mode.
1721 @item secondary-selection
1722 @kindex secondary-selection @r{(face name)}
1723 This face is used to show any secondary selection you have made.
1726 @kindex highlight @r{(face name)}
1727 This face is meant to be used for highlighting for various purposes.
1729 @item trailing-whitespace
1730 @kindex trailing-whitespace @r{(face name)}
1731 This face is used to display excess whitespace at the end of a line,
1732 if @code{show-trailing-whitespace} is non-@code{nil}.
1735 @kindex escape-glyph @r{(face name)}
1736 This face is used to display control characters and escape glyphs.
1739 In contrast, these faces are provided to change the appearance of text
1740 in specific ways. You can use them on specific text, when you want
1741 the effects they produce.
1745 @kindex bold @r{(face name)}
1746 This face uses a bold font, if possible. It uses the bold variant of
1747 the frame's font, if it has one. It's up to you to choose a default
1748 font that has a bold variant, if you want to use one.
1751 @kindex italic @r{(face name)}
1752 This face uses the italic variant of the frame's font, if it has one.
1755 @kindex bold-italic @r{(face name)}
1756 This face uses the bold italic variant of the frame's font, if it has
1760 @kindex underline @r{(face name)}
1761 This face underlines text.
1764 @kindex fixed-pitch @r{(face name)}
1765 This face forces use of a particular fixed-width font.
1767 @item variable-pitch
1768 @kindex variable-pitch @r{(face name)}
1769 This face forces use of a particular variable-width font. It's
1770 reasonable to customize this to use a different variable-width font, if
1771 you like, but you should not make it a fixed-width font.
1774 @defvar show-trailing-whitespace
1775 @tindex show-trailing-whitespace
1776 If this variable is non-@code{nil}, Emacs uses the
1777 @code{trailing-whitespace} face to display any spaces and tabs at the
1781 @node Defining Faces
1782 @subsection Defining Faces
1784 The way to define a new face is with @code{defface}. This creates a
1785 kind of customization item (@pxref{Customization}) which the user can
1786 customize using the Customization buffer (@pxref{Easy Customization,,,
1787 emacs, The GNU Emacs Manual}).
1789 @defmac defface face spec doc [keyword value]...
1790 This declares @var{face} as a customizable face that defaults according
1791 to @var{spec}. You should not quote the symbol @var{face}. The
1792 argument @var{doc} specifies the face documentation. The keywords you
1793 can use in @code{defface} are the same ones that are meaningful in both
1794 @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
1796 When @code{defface} executes, it defines the face according to
1797 @var{spec}, then uses any customizations that were read from the
1798 init file (@pxref{Init File}) to override that specification.
1800 The purpose of @var{spec} is to specify how the face should appear on
1801 different kinds of terminals. It should be an alist whose elements have
1802 the form @code{(@var{display} @var{atts})}. Each element's @sc{car},
1803 @var{display}, specifies a class of terminals. The element's second element,
1804 @var{atts}, is a list of face attributes and their values; it specifies
1805 what the face should look like on that kind of terminal. The possible
1806 attributes are defined in the value of @code{custom-face-attributes}.
1808 The @var{display} part of an element of @var{spec} determines which
1809 frames the element applies to. If more than one element of @var{spec}
1810 matches a given frame, the first matching element is the only one used
1811 for that frame. There are two possibilities for @var{display}:
1815 This element of @var{spec} matches all frames. Therefore, any
1816 subsequent elements of @var{spec} are never used. Normally
1817 @code{t} is used in the last (or only) element of @var{spec}.
1820 If @var{display} is a list, each element should have the form
1821 @code{(@var{characteristic} @var{value}@dots{})}. Here
1822 @var{characteristic} specifies a way of classifying frames, and the
1823 @var{value}s are possible classifications which @var{display} should
1824 apply to. Here are the possible values of @var{characteristic}:
1828 The kind of window system the frame uses---either @code{graphic} (any
1829 graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console),
1830 @code{w32} (for MS Windows 9X/NT), or @code{tty} (a non-graphics-capable
1834 What kinds of colors the frame supports---either @code{color},
1835 @code{grayscale}, or @code{mono}.
1838 The kind of background---either @code{light} or @code{dark}.
1841 An integer that represents the minimum number of colors the frame should
1842 support, it is compared with the result of @code{display-color-cells}.
1845 Whether or not the frame can display the face attributes given in
1846 @var{value}@dots{} (@pxref{Face Attributes}). See the documentation
1847 for the function @code{display-supports-face-attributes-p} for more
1848 information on exactly how this testing is done. @xref{Display Face
1852 If an element of @var{display} specifies more than one @var{value} for a
1853 given @var{characteristic}, any of those values is acceptable. If
1854 @var{display} has more than one element, each element should specify a
1855 different @var{characteristic}; then @emph{each} characteristic of the
1856 frame must match one of the @var{value}s specified for it in
1861 Here's how the standard face @code{region} is defined:
1865 '((((class color) (min-colors 88) (background dark))
1866 :background "blue3")
1868 (((class color) (min-colors 88) (background light))
1869 :background "lightgoldenrod2")
1870 (((class color) (min-colors 16) (background dark))
1871 :background "blue3")
1872 (((class color) (min-colors 16) (background light))
1873 :background "lightgoldenrod2")
1874 (((class color) (min-colors 8))
1875 :background "blue" :foreground "white")
1876 (((type tty) (class mono))
1878 (t :background "gray"))
1880 "Basic face for highlighting the region."
1881 :group 'basic-faces)
1885 Internally, @code{defface} uses the symbol property
1886 @code{face-defface-spec} to record the face attributes specified in
1887 @code{defface}, @code{saved-face} for the attributes saved by the user
1888 with the customization buffer, and @code{face-documentation} for the
1889 documentation string.
1891 @defopt frame-background-mode
1892 This option, if non-@code{nil}, specifies the background type to use for
1893 interpreting face definitions. If it is @code{dark}, then Emacs treats
1894 all frames as if they had a dark background, regardless of their actual
1895 background colors. If it is @code{light}, then Emacs treats all frames
1896 as if they had a light background.
1899 @node Face Attributes
1900 @subsection Face Attributes
1901 @cindex face attributes
1903 The effect of using a face is determined by a fixed set of @dfn{face
1904 attributes}. This table lists all the face attributes, and what they
1905 mean. Note that in general, more than one face can be specified for a
1906 given piece of text; when that happens, the attributes of all the faces
1907 are merged to specify how to display the text. @xref{Displaying Faces}.
1909 Any attribute in a face can have the value @code{unspecified}. This
1910 means the face doesn't specify that attribute. In face merging, when
1911 the first face fails to specify a particular attribute, that means the
1912 next face gets a chance. However, the @code{default} face must
1913 specify all attributes.
1915 Some of these font attributes are meaningful only on certain kinds of
1916 displays---if your display cannot handle a certain attribute, the
1917 attribute is ignored. (The attributes @code{:family}, @code{:width},
1918 @code{:height}, @code{:weight}, and @code{:slant} correspond to parts of
1919 an X Logical Font Descriptor.)
1923 Font family name, or fontset name (@pxref{Fontsets}). If you specify a
1924 font family name, the wild-card characters @samp{*} and @samp{?} are
1928 Relative proportionate width, also known as the character set width or
1929 set width. This should be one of the symbols @code{ultra-condensed},
1930 @code{extra-condensed}, @code{condensed}, @code{semi-condensed},
1931 @code{normal}, @code{semi-expanded}, @code{expanded},
1932 @code{extra-expanded}, or @code{ultra-expanded}.
1935 Either the font height, an integer in units of 1/10 point, a floating
1936 point number specifying the amount by which to scale the height of any
1937 underlying face, or a function, which is called with the old height
1938 (from the underlying face), and should return the new height.
1941 Font weight---a symbol from this series (from most dense to most faint):
1942 @code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
1943 @code{normal}, @code{semi-light}, @code{light}, @code{extra-light},
1944 or @code{ultra-light}.
1946 On a text-only terminal, any weight greater than normal is displayed as
1947 extra bright, and any weight less than normal is displayed as
1948 half-bright (provided the terminal supports the feature).
1951 Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal},
1952 @code{reverse-italic}, or @code{reverse-oblique}.
1954 On a text-only terminal, slanted text is displayed as half-bright, if
1955 the terminal supports the feature.
1958 Foreground color, a string. The value can be a system-defined color
1959 name, or a hexadecimal color specification of the form
1960 @samp{#@var{rr}@var{gg}@var{bb}}. (@samp{#000000} is black,
1961 @samp{#ff0000} is red, @samp{#00ff00} is green, @samp{#0000ff} is
1962 blue, and @samp{#ffffff} is white.)
1965 Background color, a string, like the foreground color.
1967 @item :inverse-video
1968 Whether or not characters should be displayed in inverse video. The
1969 value should be @code{t} (yes) or @code{nil} (no).
1972 The background stipple, a bitmap.
1974 The value can be a string; that should be the name of a file containing
1975 external-format X bitmap data. The file is found in the directories
1976 listed in the variable @code{x-bitmap-file-path}.
1978 Alternatively, the value can specify the bitmap directly, with a list
1979 of the form @code{(@var{width} @var{height} @var{data})}. Here,
1980 @var{width} and @var{height} specify the size in pixels, and
1981 @var{data} is a string containing the raw bits of the bitmap, row by
1982 row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes
1983 in the string (which should be a unibyte string for best results).
1984 This means that each row always occupies at least one whole byte.
1986 If the value is @code{nil}, that means use no stipple pattern.
1988 Normally you do not need to set the stipple attribute, because it is
1989 used automatically to handle certain shades of gray.
1992 Whether or not characters should be underlined, and in what color. If
1993 the value is @code{t}, underlining uses the foreground color of the
1994 face. If the value is a string, underlining uses that color. The
1995 value @code{nil} means do not underline.
1998 Whether or not characters should be overlined, and in what color.
1999 The value is used like that of @code{:underline}.
2001 @item :strike-through
2002 Whether or not characters should be strike-through, and in what
2003 color. The value is used like that of @code{:underline}.
2006 The name of a face from which to inherit attributes, or a list of face
2007 names. Attributes from inherited faces are merged into the face like an
2008 underlying face would be, with higher priority than underlying faces.
2011 Whether or not a box should be drawn around characters, its color, the
2012 width of the box lines, and 3D appearance.
2015 Here are the possible values of the @code{:box} attribute, and what
2023 Draw a box with lines of width 1, in the foreground color.
2026 Draw a box with lines of width 1, in color @var{color}.
2028 @item @code{(:line-width @var{width} :color @var{color} :style @var{style})}
2029 This way you can explicitly specify all aspects of the box. The value
2030 @var{width} specifies the width of the lines to draw; it defaults to 1.
2032 The value @var{color} specifies the color to draw with. The default is
2033 the foreground color of the face for simple boxes, and the background
2034 color of the face for 3D boxes.
2036 The value @var{style} specifies whether to draw a 3D box. If it is
2037 @code{released-button}, the box looks like a 3D button that is not being
2038 pressed. If it is @code{pressed-button}, the box looks like a 3D button
2039 that is being pressed. If it is @code{nil} or omitted, a plain 2D box
2043 In older versions of Emacs, before @code{:family}, @code{:height},
2044 @code{:width}, @code{:weight}, and @code{:slant} existed, these
2045 attributes were used to specify the type face. They are now
2046 semi-obsolete, but they still work:
2050 This attribute specifies the font name.
2053 A non-@code{nil} value specifies a bold font.
2056 A non-@code{nil} value specifies an italic font.
2059 For compatibility, you can still set these ``attributes'', even
2060 though they are not real face attributes. Here is what that does:
2064 You can specify an X font name as the ``value'' of this ``attribute'';
2065 that sets the @code{:family}, @code{:width}, @code{:height},
2066 @code{:weight}, and @code{:slant} attributes according to the font name.
2068 If the value is a pattern with wildcards, the first font that matches
2069 the pattern is used to set these attributes.
2072 A non-@code{nil} makes the face bold; @code{nil} makes it normal.
2073 This actually works by setting the @code{:weight} attribute.
2076 A non-@code{nil} makes the face italic; @code{nil} makes it normal.
2077 This actually works by setting the @code{:slant} attribute.
2080 @defvar x-bitmap-file-path
2081 This variable specifies a list of directories for searching
2082 for bitmap files, for the @code{:stipple} attribute.
2085 @defun bitmap-spec-p object
2086 This returns @code{t} if @var{object} is a valid bitmap specification,
2087 suitable for use with @code{:stipple} (see above). It returns
2088 @code{nil} otherwise.
2091 @node Attribute Functions
2092 @subsection Face Attribute Functions
2094 You can modify the attributes of an existing face with the following
2095 functions. If you specify @var{frame}, they affect just that frame;
2096 otherwise, they affect all frames as well as the defaults that apply to
2099 @tindex set-face-attribute
2100 @defun set-face-attribute face frame &rest arguments
2101 This function sets one or more attributes of face @var{face}
2102 for frame @var{frame}. If @var{frame} is @code{nil}, it sets
2103 the attribute for all frames, and the defaults for new frames.
2105 The extra arguments @var{arguments} specify the attributes to set, and
2106 the values for them. They should consist of alternating attribute names
2107 (such as @code{:family} or @code{:underline}) and corresponding values.
2111 (set-face-attribute 'foo nil
2118 sets the attributes @code{:width}, @code{:weight} and @code{:underline}
2119 to the corresponding values.
2122 @tindex face-attribute
2123 @defun face-attribute face attribute &optional frame inherit
2124 This returns the value of the @var{attribute} attribute of face
2125 @var{face} on @var{frame}. If @var{frame} is @code{nil},
2126 that means the selected frame (@pxref{Input Focus}).
2128 If @var{frame} is @code{t}, the value is the default for
2129 @var{face} for new frames.
2131 If @var{inherit} is @code{nil}, only attributes directly defined by
2132 @var{face} are considered, so the return value may be
2133 @code{unspecified}, or a relative value. If @var{inherit} is
2134 non-@code{nil}, @var{face}'s definition of @var{attribute} is merged
2135 with the faces specified by its @code{:inherit} attribute; however the
2136 return value may still be @code{unspecified} or relative. If
2137 @var{inherit} is a face or a list of faces, then the result is further
2138 merged with that face (or faces), until it becomes specified and
2141 To ensure that the return value is always specified and absolute, use
2142 a value of @code{default} for @var{inherit}; this will resolve any
2143 unspecified or relative values by merging with the @code{default} face
2144 (which is always completely specified).
2149 (face-attribute 'bold :weight)
2154 The functions above did not exist before Emacs 21. For compatibility
2155 with older Emacs versions, you can use the following functions to set
2156 and examine the face attributes which existed in those versions.
2158 @tindex face-attribute-relative-p
2159 @defun face-attribute-relative-p attribute value
2160 This function returns non-@code{nil} if @var{value}, when used as
2161 the value of the face attribute @var{attribute}, is relative (that is,
2162 if it modifies an underlying or inherited value of @var{attribute}).
2165 @tindex merge-face-attribute
2166 @defun merge-face-attribute attribute value1 value2
2167 If @var{value1} is a relative value for the face attribute
2168 @var{attribute}, returns it merged with the underlying value
2169 @var{value2}; otherwise, if @var{value1} is an absolute value for the
2170 face attribute @var{attribute}, returns @var{value1} unchanged.
2173 @defun set-face-foreground face color &optional frame
2174 @defunx set-face-background face color &optional frame
2175 These functions set the foreground (or background, respectively) color
2176 of face @var{face} to @var{color}. The argument @var{color} should be a
2177 string, the name of a color.
2179 Certain shades of gray are implemented by stipple patterns on
2180 black-and-white screens.
2183 @defun set-face-stipple face pattern &optional frame
2184 This function sets the background stipple pattern of face @var{face}
2185 to @var{pattern}. The argument @var{pattern} should be the name of a
2186 stipple pattern defined by the X server, or actual bitmap data
2187 (@pxref{Face Attributes}), or @code{nil} meaning don't use stipple.
2189 Normally there is no need to pay attention to stipple patterns, because
2190 they are used automatically to handle certain shades of gray.
2193 @defun set-face-font face font &optional frame
2194 This function sets the font of face @var{face}. This actually sets
2195 the attributes @code{:family}, @code{:width}, @code{:height},
2196 @code{:weight}, and @code{:slant} according to the font name
2200 @defun set-face-bold-p face bold-p &optional frame
2201 This function specifies whether @var{face} should be bold. If
2202 @var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no.
2203 This actually sets the @code{:weight} attribute.
2206 @defun set-face-italic-p face italic-p &optional frame
2207 This function specifies whether @var{face} should be italic. If
2208 @var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no.
2209 This actually sets the @code{:slant} attribute.
2212 @defun set-face-underline-p face underline-p &optional frame
2213 This function sets the underline attribute of face @var{face}.
2214 Non-@code{nil} means do underline; @code{nil} means don't.
2217 @defun invert-face face &optional frame
2218 This function inverts the @code{:inverse-video} attribute of face
2219 @var{face}. If the attribute is @code{nil}, this function sets it to
2220 @code{t}, and vice versa.
2223 These functions examine the attributes of a face. If you don't
2224 specify @var{frame}, they refer to the default data for new frames.
2225 They return the symbol @code{unspecified} if the face doesn't define any
2226 value for that attribute.
2228 @defun face-foreground face &optional frame inherit
2229 @defunx face-background face &optional frame
2230 These functions return the foreground color (or background color,
2231 respectively) of face @var{face}, as a string.
2233 If @var{inherit} is @code{nil}, only a color directly defined by the face is
2234 returned. If @var{inherit} is non-@code{nil}, any faces specified by its
2235 @code{:inherit} attribute are considered as well, and if @var{inherit}
2236 is a face or a list of faces, then they are also considered, until a
2237 specified color is found. To ensure that the return value is always
2238 specified, use a value of @code{default} for @var{inherit}.
2241 @defun face-stipple face &optional frame inherit
2242 This function returns the name of the background stipple pattern of face
2243 @var{face}, or @code{nil} if it doesn't have one.
2245 If @var{inherit} is @code{nil}, only a stipple directly defined by the
2246 face is returned. If @var{inherit} is non-@code{nil}, any faces
2247 specified by its @code{:inherit} attribute are considered as well, and
2248 if @var{inherit} is a face or a list of faces, then they are also
2249 considered, until a specified stipple is found. To ensure that the
2250 return value is always specified, use a value of @code{default} for
2254 @defun face-font face &optional frame
2255 This function returns the name of the font of face @var{face}.
2258 @defun face-bold-p face &optional frame
2259 This function returns @code{t} if @var{face} is bold---that is, if it is
2260 bolder than normal. It returns @code{nil} otherwise.
2263 @defun face-italic-p face &optional frame
2264 This function returns @code{t} if @var{face} is italic or oblique,
2265 @code{nil} otherwise.
2268 @defun face-underline-p face &optional frame
2269 This function returns the @code{:underline} attribute of face @var{face}.
2272 @defun face-inverse-video-p face &optional frame
2273 This function returns the @code{:inverse-video} attribute of face @var{face}.
2276 @node Displaying Faces
2277 @subsection Displaying Faces
2279 Here are the ways to specify which faces to use for display of text:
2283 With defaults. The @code{default} face is used as the ultimate
2284 default for all text. (In Emacs 19 and 20, the @code{default}
2285 face is used only when no other face is specified.)
2288 For a mode line or header line, the face @code{mode-line} or
2289 @code{mode-line-inactive}, or @code{header-line}, is merged in just
2290 before @code{default}.
2293 With text properties. A character can have a @code{face} property; if
2294 so, the faces and face attributes specified there apply. @xref{Special
2297 If the character has a @code{mouse-face} property, that is used instead
2298 of the @code{face} property when the mouse is ``near enough'' to the
2302 With overlays. An overlay can have @code{face} and @code{mouse-face}
2303 properties too; they apply to all the text covered by the overlay.
2306 With a region that is active. In Transient Mark mode, the region is
2307 highlighted with the face @code{region} (@pxref{Standard Faces}).
2310 With special glyphs. Each glyph can specify a particular face
2311 number. @xref{Glyphs}.
2314 If these various sources together specify more than one face for a
2315 particular character, Emacs merges the attributes of the various faces
2316 specified. For each attribute, Emacs tries first the face of any
2317 special glyph; then the face for region highlighting, if appropriate;
2318 then the faces specified by overlays, followed by those specified by
2319 text properties, then the @code{mode-line} or
2320 @code{mode-line-inactive} or @code{header-line} face (if in a mode
2321 line or a header line), and last the @code{default} face.
2323 When multiple overlays cover one character, an overlay with higher
2324 priority overrides those with lower priority. @xref{Overlays}.
2326 @node Font Selection
2327 @subsection Font Selection
2329 @dfn{Selecting a font} means mapping the specified face attributes for
2330 a character to a font that is available on a particular display. The
2331 face attributes, as determined by face merging, specify most of the
2332 font choice, but not all. Part of the choice depends on what character
2335 If the face specifies a fontset name, that fontset determines a
2336 pattern for fonts of the given charset. If the face specifies a font
2337 family, a font pattern is constructed.
2339 Emacs tries to find an available font for the given face attributes
2340 and character's registry and encoding. If there is a font that matches
2341 exactly, it is used, of course. The hard case is when no available font
2342 exactly fits the specification. Then Emacs looks for one that is
2343 ``close''---one attribute at a time. You can specify the order to
2344 consider the attributes. In the case where a specified font family is
2345 not available, you can specify a set of mappings for alternatives to
2348 @defvar face-font-selection-order
2349 @tindex face-font-selection-order
2350 This variable specifies the order of importance of the face attributes
2351 @code{:width}, @code{:height}, @code{:weight}, and @code{:slant}. The
2352 value should be a list containing those four symbols, in order of
2353 decreasing importance.
2355 Font selection first finds the best available matches for the first
2356 attribute listed; then, among the fonts which are best in that way, it
2357 searches for the best matches in the second attribute, and so on.
2359 The attributes @code{:weight} and @code{:width} have symbolic values in
2360 a range centered around @code{normal}. Matches that are more extreme
2361 (farther from @code{normal}) are somewhat preferred to matches that are
2362 less extreme (closer to @code{normal}); this is designed to ensure that
2363 non-normal faces contrast with normal ones, whenever possible.
2365 The default is @code{(:width :height :weight :slant)}, which means first
2366 find the fonts closest to the specified @code{:width}, then---among the
2367 fonts with that width---find a best match for the specified font height,
2370 One example of a case where this variable makes a difference is when the
2371 default font has no italic equivalent. With the default ordering, the
2372 @code{italic} face will use a non-italic font that is similar to the
2373 default one. But if you put @code{:slant} before @code{:height}, the
2374 @code{italic} face will use an italic font, even if its height is not
2378 @defvar face-font-family-alternatives
2379 @tindex face-font-family-alternatives
2380 This variable lets you specify alternative font families to try, if a
2381 given family is specified and doesn't exist. Each element should have
2385 (@var{family} @var{alternate-families}@dots{})
2388 If @var{family} is specified but not available, Emacs will try the other
2389 families given in @var{alternate-families}, one by one, until it finds a
2390 family that does exist.
2393 @defvar face-font-registry-alternatives
2394 @tindex face-font-registry-alternatives
2395 This variable lets you specify alternative font registries to try, if a
2396 given registry is specified and doesn't exist. Each element should have
2400 (@var{registry} @var{alternate-registries}@dots{})
2403 If @var{registry} is specified but not available, Emacs will try the
2404 other registries given in @var{alternate-registries}, one by one,
2405 until it finds a registry that does exist.
2408 Emacs can make use of scalable fonts, but by default it does not use
2409 them, since the use of too many or too big scalable fonts can crash
2412 @defvar scalable-fonts-allowed
2413 @tindex scalable-fonts-allowed
2414 This variable controls which scalable fonts to use. A value of
2415 @code{nil}, the default, means do not use scalable fonts. @code{t}
2416 means to use any scalable font that seems appropriate for the text.
2418 Otherwise, the value must be a list of regular expressions. Then a
2419 scalable font is enabled for use if its name matches any regular
2420 expression in the list. For example,
2423 (setq scalable-fonts-allowed '("muleindian-2$"))
2427 allows the use of scalable fonts with registry @code{muleindian-2}.
2430 @defun clear-face-cache &optional unload-p
2431 @tindex clear-face-cache
2432 This function clears the face cache for all frames.
2433 If @var{unload-p} is non-@code{nil}, that means to unload
2434 all unused fonts as well.
2437 @defvar face-font-rescale-alist
2438 This variable specifies scaling for certain faces. Its value should
2439 be a list of elements of the form
2442 (@var{fontname-regexp} . @var{scale-factor})
2445 If @var{fontname-regexp} matches the font name that is about to be
2446 used, this says to choose a larger similar font according to the
2447 factor @var{scale-factor}. You would use this feature to normalize
2448 the font size if certain fonts are bigger or smaller than their
2449 nominal heights and widths would suggest.
2452 @node Face Functions
2453 @subsection Functions for Working with Faces
2455 Here are additional functions for creating and working with faces.
2457 @defun make-face name
2458 This function defines a new face named @var{name}, initially with all
2459 attributes @code{nil}. It does nothing if there is already a face named
2464 This function returns a list of all defined face names.
2467 @defun copy-face old-face new-name &optional frame new-frame
2468 This function defines a face named @var{new-name} as a copy of the existing
2469 face named @var{old-face}. It creates the face @var{new-name} if that
2470 doesn't already exist.
2472 If the optional argument @var{frame} is given, this function applies
2473 only to that frame. Otherwise it applies to each frame individually,
2474 copying attributes from @var{old-face} in each frame to @var{new-face}
2477 If the optional argument @var{new-frame} is given, then @code{copy-face}
2478 copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
2483 This function returns the face number of face @var{face}.
2486 @defun face-documentation face
2487 This function returns the documentation string of face @var{face}, or
2488 @code{nil} if none was specified for it.
2491 @defun face-equal face1 face2 &optional frame
2492 This returns @code{t} if the faces @var{face1} and @var{face2} have the
2493 same attributes for display.
2496 @defun face-differs-from-default-p face &optional frame
2497 This returns non-@code{nil} if the face @var{face} displays
2498 differently from the default face.
2502 @subsection Automatic Face Assignment
2503 @cindex automatic face assignment
2504 @cindex faces, automatic choice
2506 @cindex Font-Lock mode
2507 This hook is used for automatically assigning faces to text in the
2508 buffer. It is part of the implementation of Font-Lock mode.
2510 @tindex fontification-functions
2511 @defvar fontification-functions
2512 This variable holds a list of functions that are called by Emacs
2513 redisplay as needed to assign faces automatically to text in the buffer.
2515 The functions are called in the order listed, with one argument, a
2516 buffer position @var{pos}. Each function should attempt to assign faces
2517 to the text in the current buffer starting at @var{pos}.
2519 Each function should record the faces they assign by setting the
2520 @code{face} property. It should also add a non-@code{nil}
2521 @code{fontified} property for all the text it has assigned faces to.
2522 That property tells redisplay that faces have been assigned to that text
2525 It is probably a good idea for each function to do nothing if the
2526 character after @var{pos} already has a non-@code{nil} @code{fontified}
2527 property, but this is not required. If one function overrides the
2528 assignments made by a previous one, the properties as they are
2529 after the last function finishes are the ones that really matter.
2531 For efficiency, we recommend writing these functions so that they
2532 usually assign faces to around 400 to 600 characters at each call.
2536 @subsection Looking Up Fonts
2538 @defun x-list-fonts pattern &optional face frame maximum
2539 This function returns a list of available font names that match
2540 @var{pattern}. If the optional arguments @var{face} and @var{frame} are
2541 specified, then the list is limited to fonts that are the same size as
2542 @var{face} currently is on @var{frame}.
2544 The argument @var{pattern} should be a string, perhaps with wildcard
2545 characters: the @samp{*} character matches any substring, and the
2546 @samp{?} character matches any single character. Pattern matching
2547 of font names ignores case.
2549 If you specify @var{face} and @var{frame}, @var{face} should be a face name
2550 (a symbol) and @var{frame} should be a frame.
2552 The optional argument @var{maximum} sets a limit on how many fonts to
2553 return. If this is non-@code{nil}, then the return value is truncated
2554 after the first @var{maximum} matching fonts. Specifying a small value
2555 for @var{maximum} can make this function much faster, in cases where
2556 many fonts match the pattern.
2559 @defun x-family-fonts &optional family frame
2560 @tindex x-family-fonts
2561 This function returns a list describing the available fonts for family
2562 @var{family} on @var{frame}. If @var{family} is omitted or @code{nil},
2563 this list applies to all families, and therefore, it contains all
2564 available fonts. Otherwise, @var{family} must be a string; it may
2565 contain the wildcards @samp{?} and @samp{*}.
2567 The list describes the display that @var{frame} is on; if @var{frame} is
2568 omitted or @code{nil}, it applies to the selected frame's display
2569 (@pxref{Input Focus}).
2571 The list contains a vector of the following form for each font:
2574 [@var{family} @var{width} @var{point-size} @var{weight} @var{slant}
2575 @var{fixed-p} @var{full} @var{registry-and-encoding}]
2578 The first five elements correspond to face attributes; if you
2579 specify these attributes for a face, it will use this font.
2581 The last three elements give additional information about the font.
2582 @var{fixed-p} is non-@code{nil} if the font is fixed-pitch.
2583 @var{full} is the full name of the font, and
2584 @var{registry-and-encoding} is a string giving the registry and
2585 encoding of the font.
2587 The result list is sorted according to the current face font sort order.
2590 @defun x-font-family-list &optional frame
2591 @tindex x-font-family-list
2592 This function returns a list of the font families available for
2593 @var{frame}'s display. If @var{frame} is omitted or @code{nil}, it
2594 describes the selected frame's display (@pxref{Input Focus}).
2596 The value is a list of elements of this form:
2599 (@var{family} . @var{fixed-p})
2603 Here @var{family} is a font family, and @var{fixed-p} is
2604 non-@code{nil} if fonts of that family are fixed-pitch.
2607 @defvar font-list-limit
2608 @tindex font-list-limit
2609 This variable specifies maximum number of fonts to consider in font
2610 matching. The function @code{x-family-fonts} will not return more than
2611 that many fonts, and font selection will consider only that many fonts
2612 when searching a matching font for face attributes. The default is
2617 @subsection Fontsets
2619 A @dfn{fontset} is a list of fonts, each assigned to a range of
2620 character codes. An individual font cannot display the whole range of
2621 characters that Emacs supports, but a fontset can. Fontsets have names,
2622 just as fonts do, and you can use a fontset name in place of a font name
2623 when you specify the ``font'' for a frame or a face. Here is
2624 information about defining a fontset under Lisp program control.
2626 @defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
2627 This function defines a new fontset according to the specification
2628 string @var{fontset-spec}. The string should have this format:
2631 @var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
2635 Whitespace characters before and after the commas are ignored.
2637 The first part of the string, @var{fontpattern}, should have the form of
2638 a standard X font name, except that the last two fields should be
2639 @samp{fontset-@var{alias}}.
2641 The new fontset has two names, one long and one short. The long name is
2642 @var{fontpattern} in its entirety. The short name is
2643 @samp{fontset-@var{alias}}. You can refer to the fontset by either
2644 name. If a fontset with the same name already exists, an error is
2645 signaled, unless @var{noerror} is non-@code{nil}, in which case this
2646 function does nothing.
2648 If optional argument @var{style-variant-p} is non-@code{nil}, that says
2649 to create bold, italic and bold-italic variants of the fontset as well.
2650 These variant fontsets do not have a short name, only a long one, which
2651 is made by altering @var{fontpattern} to indicate the bold or italic
2654 The specification string also says which fonts to use in the fontset.
2655 See below for the details.
2658 The construct @samp{@var{charset}:@var{font}} specifies which font to
2659 use (in this fontset) for one particular character set. Here,
2660 @var{charset} is the name of a character set, and @var{font} is the font
2661 to use for that character set. You can use this construct any number of
2662 times in the specification string.
2664 For the remaining character sets, those that you don't specify
2665 explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
2666 @samp{fontset-@var{alias}} with a value that names one character set.
2667 For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced
2668 with @samp{ISO8859-1}.
2670 In addition, when several consecutive fields are wildcards, Emacs
2671 collapses them into a single wildcard. This is to prevent use of
2672 auto-scaled fonts. Fonts made by scaling larger fonts are not usable
2673 for editing, and scaling a smaller font is not useful because it is
2674 better to use the smaller font in its own size, which Emacs does.
2676 Thus if @var{fontpattern} is this,
2679 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
2683 the font specification for @acronym{ASCII} characters would be this:
2686 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
2690 and the font specification for Chinese GB2312 characters would be this:
2693 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
2696 You may not have any Chinese font matching the above font
2697 specification. Most X distributions include only Chinese fonts that
2698 have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
2699 such a case, @samp{Fontset-@var{n}} can be specified as below:
2702 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
2703 chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
2707 Then, the font specifications for all but Chinese GB2312 characters have
2708 @samp{fixed} in the @var{family} field, and the font specification for
2709 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
2712 @defun set-fontset-font name character fontname &optional frame
2713 This function modifies the existing fontset @var{name} to
2714 use the font name @var{fontname} for the character @var{character}.
2716 If @var{name} is @code{nil}, this function modifies the default
2717 fontset, whose short name is @samp{fontset-default}.
2719 @var{character} may be a cons; @code{(@var{from} . @var{to})}, where
2720 @var{from} and @var{to} are non-generic characters. In that case, use
2721 @var{fontname} for all characters in the range @var{from} and @var{to}
2724 @var{character} may be a charset. In that case, use
2725 @var{fontname} for all character in the charsets.
2727 @var{fontname} may be a cons; @code{(@var{family} . @var{registry})},
2728 where @var{family} is a family name of a font (possibly including a
2729 foundry name at the head), @var{registry} is a registry name of a font
2730 (possibly including an encoding name at the tail).
2732 For instance, this changes the default fontset to use a font of which
2733 registry name is @samp{JISX0208.1983} for all characters belonging to
2734 the charset @code{japanese-jisx0208}.
2737 (set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
2742 @defun char-displayable-p char
2743 This function returns @code{t} if Emacs ought to be able to display
2744 @var{char}. More precisely, if the selected frame's fontset has a
2745 font to display the character set that @var{char} belongs to.
2747 Fontsets can specify a font on a per-character basis; when the fontset
2748 does that, this function's value may not be accurate.
2755 The @dfn{fringes} of a window are thin vertical strips down the
2756 sides that are used for displaying bitmaps that indicate truncation,
2757 continuation, horizontal scrolling, and the overlay arrow.
2760 * Fringe Size/Pos:: Specifying where to put the window fringes.
2761 * Fringe Bitmaps:: Displaying bitmaps in the window fringes.
2762 * Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes.
2763 * Overlay Arrow:: Display of an arrow to indicate position.
2766 @node Fringe Size/Pos
2767 @subsection Fringe Size and Position
2769 Here's how to control the position and width of the window fringes.
2771 @defvar fringes-outside-margins
2772 If the value is non-@code{nil}, the frames appear outside the display
2773 margins. The fringes normally appear between the display margins and
2774 the window text. It works to set @code{fringes-outside-margins}
2775 buffer-locally. @xref{Display Margins}.
2778 @defvar left-fringe-width
2779 This variable, if non-@code{nil}, specifies the width of the left
2783 @defvar right-fringe-width
2784 This variable, if non-@code{nil}, specifies the width of the right
2788 The values of these variables take effect when you display the
2789 buffer in a window. If you change them while the buffer is visible,
2790 you can call @code{set-window-buffer} to display it once again in the
2791 same window, to make the changes take effect.
2793 @defun set-window-fringes window left &optional right outside-margins
2794 This function sets the fringe widths of window @var{window}.
2795 If @var{window} is @code{nil}, the selected window is used.
2797 The argument @var{left} specifies the width in pixels of the left
2798 fringe, and likewise @var{right} for the right fringe. A value of
2799 @code{nil} for either one stands for the default width. If
2800 @var{outside-margins} is non-@code{nil}, that specifies that fringes
2801 should appear outside of the display margins.
2804 @defun window-fringes &optional window
2805 This function returns information about the fringes of a window
2806 @var{window}. If @var{window} is omitted or @code{nil}, the selected
2807 window is used. The value has the form @code{(@var{left-width}
2808 @var{right-width} @var{outside-margins})}.
2811 @defvar overflow-newline-into-fringe
2812 If this is non-@code{nil}, lines exactly as wide as the window (not
2813 counting the final newline character) are not continued. Instead,
2814 when point is at the end of the line, the cursor appears in the right
2818 @node Fringe Bitmaps
2819 @subsection Fringe Bitmaps
2820 @cindex fringe bitmaps
2821 @cindex bitmaps, fringe
2823 The @dfn{fringe bitmaps} are tiny icons Emacs displays in the window
2824 fringe (on a graphic display) to indicate truncated or continued
2825 lines, buffer boundaries, overlay arrow, etc. The fringe bitmaps are
2826 shared by all frames and windows. You can redefine the built-in
2827 fringe bitmaps, and you can define new fringe bitmaps.
2829 The way to display a bitmap in the left or right fringes for a given
2830 line in a window is by specifying the @code{display} property for one
2831 of the characters that appears in it. Use a display specification of
2832 the form @code{(left-fringe @var{bitmap} [@var{face}])} or
2833 @code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display
2834 Property}). Here, @var{bitmap} is a symbol identifying the bitmap
2835 you want, and @var{face} (which is optional) is the name of the face
2836 whose colors should be used for displaying the bitmap.
2838 These are the symbols identify the standard fringe bitmaps.
2839 Evaluate @code{(require 'fringe)} to define them. Fringe bitmap
2840 symbols have their own name space.
2843 @item Truncation and continuation line bitmaps:
2844 @code{left-truncation}, @code{right-truncation},
2845 @code{continued-line}, @code{continuation-line}.
2847 @item Buffer indication bitmaps:
2848 @code{up-arrow}, @code{down-arrow},
2849 @code{top-left-angle}, @code{top-right-angle},
2850 @code{bottom-left-angle}, @code{bottom-right-angle},
2851 @code{left-bracket}, @code{right-bracket}.
2853 @item Empty line indication bitmap:
2856 @item Overlay arrow bitmap:
2857 @code{overlay-arrow}.
2859 @item Bitmaps for displaying the cursor in right fringe:
2860 @code{filled-box-cursor}, @code{hollow-box-cursor}, @code{hollow-square},
2861 @code{bar-cursor}, @code{hbar-cursor}.
2864 @defun fringe-bitmaps-at-pos &optional pos window
2865 This function returns the fringe bitmaps of the display line
2866 containing position @var{pos} in window @var{window}. The return
2867 value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left}
2868 is the symbol for the fringe bitmap in the left fringe (or @code{nil}
2869 if no bitmap), @var{right} is similar for the right fringe, and @var{ov}
2870 is non-@code{nil} if there is an overlay arrow in the left fringe.
2872 The value is @code{nil} if @var{pos} is not visible in @var{window}.
2873 If @var{window} is @code{nil}, that stands for the selected window.
2874 If @var{pos} is @code{nil}, that stands for the value of point in
2878 @node Customizing Bitmaps
2879 @subsection Customizing Fringe Bitmaps
2881 @defun define-fringe-bitmap bitmap bits &optional height width align
2882 This function defines the symbol @var{bitmap} as a new fringe bitmap,
2883 or replaces an existing bitmap with that name.
2885 The argument @var{bits} specifies the image to use. It should be
2886 either a string or a vector of integers, where each element (an
2887 integer) corresponds to one row of the bitmap. Each bit of an integer
2888 corresponds to one pixel of the bitmap, where the low bit corresponds
2889 to the rightmost pixel of the bitmap.
2891 The height is normally the length of @var{bits}. However, you
2892 can specify a different height with non-@code{nil} @var{height}. The width
2893 is normally 8, but you can specify a different width with non-@code{nil}
2894 @var{width}. The width must be an integer between 1 and 16.
2896 The argument @var{align} specifies the positioning of the bitmap
2897 relative to the range of rows where it is used; the default is to
2898 center the bitmap. The allowed values are @code{top}, @code{center},
2901 The @var{align} argument may also be a list @code{(@var{align}
2902 @var{periodic})} where @var{align} is interpreted as described above.
2903 If @var{periodic} is non-@code{nil}, it specifies that the rows in
2904 @code{bits} should be repeated enough times to reach the specified
2907 The return value on success is an integer identifying the new bitmap.
2908 You should save that integer in a variable so it can be used to select
2911 This function signals an error if there are no more free bitmap slots.
2914 @defun destroy-fringe-bitmap bitmap
2915 This function destroy the fringe bitmap identified by @var{bitmap}.
2916 If @var{bitmap} identifies a standard fringe bitmap, it actually
2917 restores the standard definition of that bitmap, instead of
2918 eliminating it entirely.
2921 @defun set-fringe-bitmap-face bitmap &optional face
2922 This sets the face for the fringe bitmap @var{bitmap} to @var{face}.
2923 If @var{face} is @code{nil}, it selects the @code{fringe} face. The
2924 bitmap's face controls the color to draw it in.
2926 The face you use here should be derived from @code{fringe}, and should
2927 specify only the foreground color.
2931 @subsection The Overlay Arrow
2932 @cindex overlay arrow
2934 The @dfn{overlay arrow} is useful for directing the user's attention
2935 to a particular line in a buffer. For example, in the modes used for
2936 interface to debuggers, the overlay arrow indicates the line of code
2937 about to be executed. This feature has nothing to do with
2938 @dfn{overlays} (@pxref{Overlays}).
2940 @defvar overlay-arrow-string
2941 This variable holds the string to display to call attention to a
2942 particular line, or @code{nil} if the arrow feature is not in use.
2943 On a graphical display the contents of the string are ignored; instead a
2944 glyph is displayed in the fringe area to the left of the display area.
2947 @defvar overlay-arrow-position
2948 This variable holds a marker that indicates where to display the overlay
2949 arrow. It should point at the beginning of a line. On a non-graphical
2950 display the arrow text
2951 appears at the beginning of that line, overlaying any text that would
2952 otherwise appear. Since the arrow is usually short, and the line
2953 usually begins with indentation, normally nothing significant is
2956 The overlay string is displayed only in the buffer that this marker
2957 points into. Thus, only one buffer can have an overlay arrow at any
2959 @c !!! overlay-arrow-position: but the overlay string may remain in the display
2960 @c of some other buffer until an update is required. This should be fixed
2964 You can do a similar job by creating an overlay with a
2965 @code{before-string} property. @xref{Overlay Properties}.
2967 You can define multiple overlay arrows via the variable
2968 @code{overlay-arrow-variable-list}.
2970 @defvar overlay-arrow-variable-list
2971 This variable's value is a list of varibles, each of which specifies
2972 the position of an overlay arrow. The variable
2973 @code{overlay-arrow-position} has its normal meaning because it is on
2977 Each variable on this list can have properties
2978 @code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that
2979 specify an overlay arrow string (for text-only terminals) or fringe
2980 bitmap (for graphical terminals) to display at the corresponding
2981 overlay arrow position. If either property is not set, the default
2982 (@code{overlay-arrow-string} or @code{overlay-arrow-fringe-bitmap}) is
2986 @section Scroll Bars
2988 Normally the frame parameter @code{vertical-scroll-bars} controls
2989 whether the windows in the frame have vertical scroll bars. A
2990 non-@code{nil} parameter value means they do. The frame parameter
2991 @code{scroll-bar-width} specifies how wide they are (@code{nil}
2992 meaning the default). @xref{Window Frame Parameters}.
2994 @vindex vertical-scroll-bar
2995 You can enable or disable scroll bars for a particular buffer,
2996 by setting the variable @code{vertical-scroll-bar}. This variable
2997 automatically becomes buffer-local when set. The possible values are
2998 @code{left}, @code{right}, @code{t}, which means to use the
2999 frame's default, and @code{nil} for no scroll bar.
3001 You can also control this for individual windows. Call the function
3002 @code{set-window-scroll-bars} to specify what to do for a specific window:
3004 @defun set-window-scroll-bars window width &optional vertical-type horizontal-type
3005 This function sets the width and type of scroll bars for window
3008 @var{width} specifies the scroll bar width in pixels (@code{nil} means
3009 use the width specified for the frame). @var{vertical-type} specifies
3010 whether to have a vertical scroll bar and, if so, where. The possible
3011 values are @code{left}, @code{right} and @code{nil}, just like the
3012 values of the @code{vertical-scroll-bars} frame parameter.
3014 The argument @var{horizontal-type} is meant to specify whether and
3015 where to have horizontal scroll bars, but since they are not
3016 implemented, it has no effect. If @var{window} is @code{nil}, the
3017 selected window is used.
3020 @defun window-scroll-bars &optional window
3021 Report the width and type of scroll bars specified for @var{window}.
3022 If @var{window} is omitted or @code{nil}, the selected window is used.
3023 The value is a list of the form @code{(@var{width}
3024 @var{cols} @var{vertical-type} @var{horizontal-type})}. The value
3025 @var{width} is the value that was specified for the width (which may
3026 be @code{nil}); @var{cols} is the number of columns that the scroll
3027 bar actually occupies.
3029 @var{horizontal-type} is not actually meaningful.
3032 If you don't specify these values for a window with
3033 @code{set-window-scroll-bars}, the buffer-local variables
3034 @code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being
3035 displayed control the window's vertical scroll bars. The function
3036 @code{set-window-buffer} examines these variables. If you change them
3037 in a buffer that is already visible in a window, you can make the
3038 window take note of the new values by calling @code{set-window-buffer}
3039 specifying the same buffer that is already displayed.
3041 @defvar scroll-bar-mode
3042 This variable, always local in all buffers, controls whether and where
3043 to put scroll bars in windows displaying the buffer. The possible values
3044 are @code{nil} for no scroll bar, @code{left} to put a scroll bar on
3045 the left, and @code{right} to put a scroll bar on the right.
3048 @defvar scroll-bar-width
3049 This variable, always local in all buffers, specifies the width of the
3050 buffer's scroll bars, measured in pixels. A value of @code{nil} means
3051 to use the value specified by the frame.
3055 @section Pointer Shape
3057 Normally, the mouse pointer has the @code{text} shape over text and
3058 the @code{arrow} shape over window areas which do not correspond to
3059 any buffer text. You can specify the mouse pointer shape over text or
3060 images via the @code{pointer} text property, and for images with the
3061 @code{:pointer} and @code{:map} image properties.
3063 The available pointer shapes are: @code{text} (or @code{nil}),
3064 @code{arrow}, @code{hand}, @code{vdrag}, @code{hdrag},
3065 @code{modeline}, and @code{hourglass}.
3067 @defvar void-text-area-pointer
3068 @tindex void-text-area-pointer
3069 This variable specifies the mouse pointer shape in void text areas,
3070 i.e. the areas after the end of a line or below the last line in the
3071 buffer. The default is to use the @code{arrow} (non-text) pointer.
3074 @node Display Property
3075 @section The @code{display} Property
3076 @cindex display specification
3077 @kindex display @r{(text property)}
3079 The @code{display} text property (or overlay property) is used to
3080 insert images into text, and also control other aspects of how text
3081 displays. The value of the @code{display} property should be a
3082 display specification, or a list or vector containing several display
3085 Some kinds of @code{display} properties specify something to display
3086 instead of the text that has the property. In this case, ``the text''
3087 means all the consecutive characters that have the same Lisp object as
3088 their @code{display} property; these characters are replaced as a
3089 single unit. By contrast, characters that have similar but distinct
3090 Lisp objects as their @code{display} properties are handled
3091 separately. Here's a function that illustrates this point:
3095 (goto-char (point-min))
3097 (let ((string (concat "A")))
3098 (put-text-property (point) (1+ (point)) 'display string)
3100 (put-text-property (point) (1+ (point)) 'display string)
3105 It gives each of the first ten characters in the buffer string
3106 @code{"A"} as the @code{display} property, but they don't all get the
3107 same string. The first two characters get the same string, so they
3108 together are replaced with one @samp{A}. The next two characters get
3109 a second string, so they together are replaced with one @samp{A}.
3110 Likewise for each following pair of characters. Thus, the ten
3111 characters appear as five A's. This function would have the same
3116 (goto-char (point-min))
3118 (let ((string (concat "A")))
3119 (put-text-property (point) (2+ (point)) 'display string)
3120 (put-text-property (point) (1+ (point)) 'display string)
3125 This illustrates that what matters is the property value for
3126 each character. If two consecutive characters have the same
3127 object as the @code{display} property value, it's irrelevent
3128 whether they got this property from a single call to
3129 @code{put-text-property} or from two different calls.
3131 The rest of this section describes several kinds of
3132 display specifications and what they mean.
3135 * Specified Space:: Displaying one space with a specified width.
3136 * Pixel Specification:: Specifying space width or height in pixels.
3137 * Other Display Specs:: Displaying an image; magnifying text; moving it
3138 up or down on the page; adjusting the width
3139 of spaces within text.
3140 * Display Margins:: Displaying text or images to the side of the main text.
3143 @node Specified Space
3144 @subsection Specified Spaces
3145 @cindex spaces, specified height or width
3146 @cindex specified spaces
3147 @cindex variable-width spaces
3149 To display a space of specified width and/or height, use a display
3150 specification of the form @code{(space . @var{props})}, where
3151 @var{props} is a property list (a list of alternating properties and
3152 values). You can put this property on one or more consecutive
3153 characters; a space of the specified height and width is displayed in
3154 place of @emph{all} of those characters. These are the properties you
3155 can use in @var{props} to specify the weight of the space:
3158 @item :width @var{width}
3159 If @var{width} is an integer or floating point number, it specifies
3160 that the space width should be @var{width} times the normal character
3161 width. @var{width} can also be a @dfn{pixel width} specification
3162 (@pxref{Pixel Specification}).
3164 @item :relative-width @var{factor}
3165 Specifies that the width of the stretch should be computed from the
3166 first character in the group of consecutive characters that have the
3167 same @code{display} property. The space width is the width of that
3168 character, multiplied by @var{factor}.
3170 @item :align-to @var{hpos}
3171 Specifies that the space should be wide enough to reach @var{hpos}.
3172 If @var{hpos} is a number, it is measured in units of the normal
3173 character width. @var{hpos} can also be a @dfn{pixel width}
3174 specification (@pxref{Pixel Specification}).
3177 You should use one and only one of the above properties. You can
3178 also specify the height of the space, with these properties:
3181 @item :height @var{height}
3182 Specifies the height of the space.
3183 If @var{height} is an integer or floating point number, it specifies
3184 that the space height should be @var{height} times the normal character
3185 height. The @var{height} may also be a @dfn{pixel height} specification
3186 (@pxref{Pixel Specification}).
3188 @item :relative-height @var{factor}
3189 Specifies the height of the space, multiplying the ordinary height
3190 of the text having this display specification by @var{factor}.
3192 @item :ascent @var{ascent}
3193 If the value of @var{ascent} is a non-negative number no greater than
3194 100, it specifies that @var{ascent} percent of the height of the space
3195 should be considered as the ascent of the space---that is, the part
3196 above the baseline. The ascent may also be specified in pixel units
3197 with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}).
3201 Don't use both @code{:height} and @code{:relative-height} together.
3203 The @code{:width} and @code{:align-to} properties are supported on
3204 non-graphic terminals, but the other space properties in this section
3207 @node Pixel Specification
3208 @subsection Pixel Specification for Spaces
3209 @cindex spaces, pixel specification
3211 The value of the @code{:width}, @code{:align-to}, @code{:height},
3212 and @code{:ascent} properties can be a special kind of expression that
3213 is evaluated during redisplay. The result of the evaluation is used
3214 as an absolute number of pixels.
3216 The following expressions are supported:
3220 @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form}
3221 @var{num} ::= @var{integer} | @var{float} | @var{symbol}
3222 @var{unit} ::= in | mm | cm | width | height
3223 @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin
3225 @var{pos} ::= left | center | right
3226 @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...)
3231 The form @var{num} specifies a fraction of the default frame font
3232 height or width. The form @code{(@var{num})} specifies an absolute
3233 number of pixels. If @var{num} is a symbol, @var{symbol}, its
3234 buffer-local variable binding is used.
3236 The @code{in}, @code{mm}, and @code{cm} units specify the number of
3237 pixels per inch, millimeter, and centimeter, respectively. The
3238 @code{width} and @code{height} units correspond to the default width
3239 and height of the current face. An image specification @code{image}
3240 corresponds to the width or height of the image.
3242 The @code{left-fringe}, @code{right-fringe}, @code{left-margin},
3243 @code{right-margin}, @code{scroll-bar}, and @code{text} elements
3244 specify to the width of the corresponding area of the window.
3246 The @code{left}, @code{center}, and @code{right} positions can be
3247 used with @code{:align-to} to specify a position relative to the left
3248 edge, center, or right edge of the text area.
3250 Any of the above window elements (except @code{text}) can also be
3251 used with @code{:align-to} to specify that the position is relative to
3252 the left edge of the given area. Once the base offset for a relative
3253 position has been set (by the first occurrence of one of these
3254 symbols), further occurrences of these symbols are interpreted as the
3255 width of the specified area. For example, to align to the center of
3256 the left-margin, use
3259 :align-to (+ left-margin (0.5 . left-margin))
3262 If no specific base offset is set for alignment, it is always relative
3263 to the left edge of the text area. For example, @samp{:align-to 0} in a
3264 header-line aligns with the first text column in the text area.
3266 A value of the form @code{(@var{num} . @var{expr})} stands for the
3267 product of the values of @var{num} and @var{expr}. For example,
3268 @code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 .
3269 @var{image})} specifies half the width (or height) of the specified
3272 The form @code{(+ @var{expr} ...)} adds up the value of the
3273 expressions. The form @code{(- @var{expr} ...)} negates or subtracts
3274 the value of the expressions.
3276 @node Other Display Specs
3277 @subsection Other Display Specifications
3279 Here are the other sorts of display specifications that you can use
3280 in the @code{display} text property.
3284 Display @var{string} instead of the text that has this property.
3286 @item (image . @var{image-props})
3287 This display specification is an image descriptor (@pxref{Images}).
3288 When used as a display specification, it means to display the image
3289 instead of the text that has the display specification.
3291 @item (slice @var{x} @var{y} @var{width} @var{height})
3292 This specification together with @code{image} specifies a @dfn{slice}
3293 (a partial area) of the image to display. The elements @var{y} and
3294 @var{x} specify the top left corner of the slice, within the image;
3295 @var{width} and @var{height} specify the width and height of the
3296 slice. Integer values are numbers of pixels. A floating point number
3297 in the range 0.0--1.0 stands for that fraction of the width or height
3298 of the entire image.
3300 @item ((margin nil) @var{string})
3302 A display specification of this form means to display @var{string}
3303 instead of the text that has the display specification, at the same
3304 position as that text. This is a special case of marginal display
3305 (@pxref{Display Margins}).
3307 Recursive display specifications are not supported---string display
3308 specifications must not have @code{display} properties themselves.
3310 @item (space-width @var{factor})
3311 This display specification affects all the space characters within the
3312 text that has the specification. It displays all of these spaces
3313 @var{factor} times as wide as normal. The element @var{factor} should
3314 be an integer or float. Characters other than spaces are not affected
3315 at all; in particular, this has no effect on tab characters.
3317 @item (height @var{height})
3318 This display specification makes the text taller or shorter.
3319 Here are the possibilities for @var{height}:
3322 @item @code{(+ @var{n})}
3323 This means to use a font that is @var{n} steps larger. A ``step'' is
3324 defined by the set of available fonts---specifically, those that match
3325 what was otherwise specified for this text, in all attributes except
3326 height. Each size for which a suitable font is available counts as
3327 another step. @var{n} should be an integer.
3329 @item @code{(- @var{n})}
3330 This means to use a font that is @var{n} steps smaller.
3332 @item a number, @var{factor}
3333 A number, @var{factor}, means to use a font that is @var{factor} times
3334 as tall as the default font.
3336 @item a symbol, @var{function}
3337 A symbol is a function to compute the height. It is called with the
3338 current height as argument, and should return the new height to use.
3340 @item anything else, @var{form}
3341 If the @var{height} value doesn't fit the previous possibilities, it is
3342 a form. Emacs evaluates it to get the new height, with the symbol
3343 @code{height} bound to the current specified font height.
3346 @item (raise @var{factor})
3347 This kind of display specification raises or lowers the text
3348 it applies to, relative to the baseline of the line.
3350 @var{factor} must be a number, which is interpreted as a multiple of the
3351 height of the affected text. If it is positive, that means to display
3352 the characters raised. If it is negative, that means to display them
3355 If the text also has a @code{height} display specification, that does
3356 not affect the amount of raising or lowering, which is based on the
3357 faces used for the text.
3360 You can make any display specification conditional. To do that,
3361 package it in another list of the form @code{(when @var{condition} .
3362 @var{spec})}. Then the specification @var{spec} applies only when
3363 @var{condition} evaluates to a non-@code{nil} value. During the
3364 evaluation, @code{object} is bound to the string or buffer having the
3365 conditional @code{display} property. @code{position} and
3366 @code{buffer-position} are bound to the position within @code{object}
3367 and the buffer position where the @code{display} property was found,
3368 respectively. Both positions can be different when @code{object} is a
3371 @node Display Margins
3372 @subsection Displaying in the Margins
3373 @cindex display margins
3374 @cindex margins, display
3376 A buffer can have blank areas called @dfn{display margins} on the left
3377 and on the right. Ordinary text never appears in these areas, but you
3378 can put things into the display margins using the @code{display}
3381 To put text in the left or right display margin of the window, use a
3382 display specification of the form @code{(margin right-margin)} or
3383 @code{(margin left-margin)} on it. To put an image in a display margin,
3384 use that display specification along with the display specification for
3385 the image. Unfortunately, there is currently no way to make
3386 text or images in the margin mouse-sensitive.
3388 If you put such a display specification directly on text in the
3389 buffer, the specified margin display appears @emph{instead of} that
3390 buffer text itself. To put something in the margin @emph{in
3391 association with} certain buffer text without preventing or altering
3392 the display of that text, put a @code{before-string} property on the
3393 text and put the display specification on the contents of the
3396 Before the display margins can display anything, you must give
3397 them a nonzero width. The usual way to do that is to set these
3400 @defvar left-margin-width
3401 @tindex left-margin-width
3402 This variable specifies the width of the left margin.
3403 It is buffer-local in all buffers.
3406 @defvar right-margin-width
3407 @tindex right-margin-width
3408 This variable specifies the width of the right margin.
3409 It is buffer-local in all buffers.
3412 Setting these variables does not immediately affect the window. These
3413 variables are checked when a new buffer is displayed in the window.
3414 Thus, you can make changes take effect by calling
3415 @code{set-window-buffer}.
3417 You can also set the margin widths immediately.
3419 @defun set-window-margins window left &optional right
3420 @tindex set-window-margins
3421 This function specifies the margin widths for window @var{window}.
3422 The argument @var{left} controls the left margin and
3423 @var{right} controls the right margin (default @code{0}).
3426 @defun window-margins &optional window
3427 @tindex window-margins
3428 This function returns the left and right margins of @var{window}
3429 as a cons cell of the form @code{(@var{left} . @var{right})}.
3430 If @var{window} is @code{nil}, the selected window is used.
3435 @cindex images in buffers
3437 To display an image in an Emacs buffer, you must first create an image
3438 descriptor, then use it as a display specifier in the @code{display}
3439 property of text that is displayed (@pxref{Display Property}).
3441 Emacs can display a number of different image formats; some of them
3442 are supported only if particular support libraries are installed on
3443 your machine. In some environments, Emacs can load image
3444 libraries on demand; if so, the variable @code{image-library-alist}
3445 can be used to modify the set of known names for these dynamic
3446 libraries (though it is not possible to add new image formats).
3448 The supported image formats include XBM, XPM (this requires the
3449 libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring
3450 @code{libungif} 4.1.0), Postscript, PBM, JPEG (requiring the
3451 @code{libjpeg} library version v6a), TIFF (requiring @code{libtiff}
3452 v3.4), and PNG (requiring @code{libpng} 1.0.2).
3454 You specify one of these formats with an image type symbol. The image
3455 type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
3456 @code{pbm}, @code{jpeg}, @code{tiff}, and @code{png}.
3459 This variable contains a list of those image type symbols that are
3460 potentially supported in the current configuration.
3461 @emph{Potentially} here means that Emacs knows about the image types,
3462 not necessarily that they can be loaded (they could depend on
3463 unavailable dynamic libraries, for example).
3465 To know which image types are really available, use
3466 @code{image-type-available-p}.
3469 @defvar image-library-alist
3470 This in an alist of image types vs external libraries needed to
3473 Each element is a list @code{(@var{image-type} @var{library}...)},
3474 where the car is a supported image format from @code{image-types}, and
3475 the rest are strings giving alternate filenames for the corresponding
3476 external libraries to load.
3478 Emacs tries to load the libraries in the order they appear on the
3479 list; if none is loaded, the running session of Emacs won't support
3480 the image type. @code{pbm} and @code{xbm} don't need to be listed;
3481 they're always supported.
3483 This variable is ignored if the image libraries are statically linked
3487 @defun image-type-available-p type
3488 @findex image-type-available-p
3490 This function returns non-@code{nil} if image type @var{type} is
3491 available, i.e., if images of this type can be loaded and displayed in
3492 Emacs. @var{type} should be one of the types contained in
3495 For image types whose support libraries are statically linked, this
3496 function always returns @code{t}; for other image types, it returns
3497 @code{t} if the dynamic library could be loaded, @code{nil} otherwise.
3501 * Image Descriptors:: How to specify an image for use in @code{:display}.
3502 * XBM Images:: Special features for XBM format.
3503 * XPM Images:: Special features for XPM format.
3504 * GIF Images:: Special features for GIF format.
3505 * Postscript Images:: Special features for Postscript format.
3506 * Other Image Types:: Various other formats are supported.
3507 * Defining Images:: Convenient ways to define an image for later use.
3508 * Showing Images:: Convenient ways to display an image once it is defined.
3509 * Image Cache:: Internal mechanisms of image display.
3512 @node Image Descriptors
3513 @subsection Image Descriptors
3514 @cindex image descriptor
3516 An image description is a list of the form @code{(image
3517 . @var{props})}, where @var{props} is a property list containing
3518 alternating keyword symbols (symbols whose names start with a colon) and
3519 their values. You can use any Lisp object as a property, but the only
3520 properties that have any special meaning are certain symbols, all of
3523 Every image descriptor must contain the property @code{:type
3524 @var{type}} to specify the format of the image. The value of @var{type}
3525 should be an image type symbol; for example, @code{xpm} for an image in
3528 Here is a list of other properties that are meaningful for all image
3532 @item :file @var{file}
3533 The @code{:file} property says to load the image from file
3534 @var{file}. If @var{file} is not an absolute file name, it is expanded
3535 in @code{data-directory}.
3537 @item :data @var{data}
3538 The @code{:data} property says the actual contents of the image.
3539 Each image must use either @code{:data} or @code{:file}, but not both.
3540 For most image types, the value of the @code{:data} property should be a
3541 string containing the image data; we recommend using a unibyte string.
3543 Before using @code{:data}, look for further information in the section
3544 below describing the specific image format. For some image types,
3545 @code{:data} may not be supported; for some, it allows other data types;
3546 for some, @code{:data} alone is not enough, so you need to use other
3547 image properties along with @code{:data}.
3549 @item :margin @var{margin}
3550 The @code{:margin} property specifies how many pixels to add as an
3551 extra margin around the image. The value, @var{margin}, must be a
3552 non-negative number, or a pair @code{(@var{x} . @var{y})} of such
3553 numbers. If it is a pair, @var{x} specifies how many pixels to add
3554 horizontally, and @var{y} specifies how many pixels to add vertically.
3555 If @code{:margin} is not specified, the default is zero.
3557 @item :ascent @var{ascent}
3558 The @code{:ascent} property specifies the amount of the image's
3559 height to use for its ascent---that is, the part above the baseline.
3560 The value, @var{ascent}, must be a number in the range 0 to 100, or
3561 the symbol @code{center}.
3563 If @var{ascent} is a number, that percentage of the image's height is
3564 used for its ascent.
3566 If @var{ascent} is @code{center}, the image is vertically centered
3567 around a centerline which would be the vertical centerline of text drawn
3568 at the position of the image, in the manner specified by the text
3569 properties and overlays that apply to the image.
3571 If this property is omitted, it defaults to 50.
3573 @item :relief @var{relief}
3574 The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle
3575 around the image. The value, @var{relief}, specifies the width of the
3576 shadow lines, in pixels. If @var{relief} is negative, shadows are drawn
3577 so that the image appears as a pressed button; otherwise, it appears as
3578 an unpressed button.
3580 @item :conversion @var{algorithm}
3581 The @code{:conversion} property, if non-@code{nil}, specifies a
3582 conversion algorithm that should be applied to the image before it is
3583 displayed; the value, @var{algorithm}, specifies which algorithm.
3588 Specifies the Laplace edge detection algorithm, which blurs out small
3589 differences in color while highlighting larger differences. People
3590 sometimes consider this useful for displaying the image for a
3591 ``disabled'' button.
3593 @item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
3594 Specifies a general edge-detection algorithm. @var{matrix} must be
3595 either a nine-element list or a nine-element vector of numbers. A pixel
3596 at position @math{x/y} in the transformed image is computed from
3597 original pixels around that position. @var{matrix} specifies, for each
3598 pixel in the neighborhood of @math{x/y}, a factor with which that pixel
3599 will influence the transformed pixel; element @math{0} specifies the
3600 factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for
3601 the pixel at @math{x/y-1} etc., as shown below:
3604 $$\pmatrix{x-1/y-1 & x/y-1 & x+1/y-1 \cr
3605 x-1/y & x/y & x+1/y \cr
3606 x-1/y+1& x/y+1 & x+1/y+1 \cr}$$
3611 (x-1/y-1 x/y-1 x+1/y-1
3613 x-1/y+1 x/y+1 x+1/y+1)
3617 The resulting pixel is computed from the color intensity of the color
3618 resulting from summing up the RGB values of surrounding pixels,
3619 multiplied by the specified factors, and dividing that sum by the sum
3620 of the factors' absolute values.
3622 Laplace edge-detection currently uses a matrix of
3625 $$\pmatrix{1 & 0 & 0 \cr
3638 Emboss edge-detection uses a matrix of
3641 $$\pmatrix{ 2 & -1 & 0 \cr
3655 Specifies transforming the image so that it looks ``disabled''.
3658 @item :mask @var{mask}
3659 If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build
3660 a clipping mask for the image, so that the background of a frame is
3661 visible behind the image. If @var{bg} is not specified, or if @var{bg}
3662 is @code{t}, determine the background color of the image by looking at
3663 the four corners of the image, assuming the most frequently occurring
3664 color from the corners is the background color of the image. Otherwise,
3665 @var{bg} must be a list @code{(@var{red} @var{green} @var{blue})}
3666 specifying the color to assume for the background of the image.
3668 If @var{mask} is @code{nil}, remove a mask from the image, if it has
3669 one. Images in some formats include a mask which can be removed by
3670 specifying @code{:mask nil}.
3672 @item :pointer @var{shape}
3673 This specifies the pointer shape when the mouse pointer is over this
3674 image. @xref{Pointer Shape}, for available pointer shapes.
3676 @item :map @var{map}
3677 This associates an image map of @dfn{hot spots} with this image.
3679 An image map is an alist where each element has the format
3680 @code{(@var{area} @var{id} @var{plist})}. An @var{area} is specified
3681 as either a rectangle, a circle, or a polygon.
3683 A rectangle is a cons
3684 @code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))}
3685 which specifies the pixel coordinates of the upper left and bottom right
3686 corners of the rectangle area.
3689 @code{(circle . ((@var{x0} . @var{y0}) . @var{r}))}
3690 which specifies the center and the radius of the circle; @var{r} may
3691 be a float or integer.
3694 @code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])}
3695 where each pair in the vector describes one corner in the polygon.
3697 When the mouse pointer is above a hot-spot area of an image, the
3698 @var{plist} of that hot-spot is consulted; if it contains a @code{help-echo}
3699 property it defines a tool-tip for the hot-spot, and if it contains
3700 a @code{pointer} property, it defines the shape of the mouse cursor when
3701 it is over the hot-spot.
3702 @xref{Pointer Shape}, for available pointer shapes.
3704 When you click the mouse when the mouse pointer is over a hot-spot, an
3705 event is composed by combining the @var{id} of the hot-spot with the
3706 mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's
3707 @var{id} is @code{area4}.
3710 @defun image-mask-p spec &optional frame
3711 @tindex image-mask-p
3712 This function returns @code{t} if image @var{spec} has a mask bitmap.
3713 @var{frame} is the frame on which the image will be displayed.
3714 @var{frame} @code{nil} or omitted means to use the selected frame
3715 (@pxref{Input Focus}).
3719 @subsection XBM Images
3722 To use XBM format, specify @code{xbm} as the image type. This image
3723 format doesn't require an external library, so images of this type are
3726 Additional image properties supported for the @code{xbm} image type are:
3729 @item :foreground @var{foreground}
3730 The value, @var{foreground}, should be a string specifying the image
3731 foreground color, or @code{nil} for the default color. This color is
3732 used for each pixel in the XBM that is 1. The default is the frame's
3735 @item :background @var{background}
3736 The value, @var{background}, should be a string specifying the image
3737 background color, or @code{nil} for the default color. This color is
3738 used for each pixel in the XBM that is 0. The default is the frame's
3742 If you specify an XBM image using data within Emacs instead of an
3743 external file, use the following three properties:
3746 @item :data @var{data}
3747 The value, @var{data}, specifies the contents of the image.
3748 There are three formats you can use for @var{data}:
3752 A vector of strings or bool-vectors, each specifying one line of the
3753 image. Do specify @code{:height} and @code{:width}.
3756 A string containing the same byte sequence as an XBM file would contain.
3757 You must not specify @code{:height} and @code{:width} in this case,
3758 because omitting them is what indicates the data has the format of an
3759 XBM file. The file contents specify the height and width of the image.
3762 A string or a bool-vector containing the bits of the image (plus perhaps
3763 some extra bits at the end that will not be used). It should contain at
3764 least @var{width} * @code{height} bits. In this case, you must specify
3765 @code{:height} and @code{:width}, both to indicate that the string
3766 contains just the bits rather than a whole XBM file, and to specify the
3770 @item :width @var{width}
3771 The value, @var{width}, specifies the width of the image, in pixels.
3773 @item :height @var{height}
3774 The value, @var{height}, specifies the height of the image, in pixels.
3778 @subsection XPM Images
3781 To use XPM format, specify @code{xpm} as the image type. The
3782 additional image property @code{:color-symbols} is also meaningful with
3783 the @code{xpm} image type:
3786 @item :color-symbols @var{symbols}
3787 The value, @var{symbols}, should be an alist whose elements have the
3788 form @code{(@var{name} . @var{color})}. In each element, @var{name} is
3789 the name of a color as it appears in the image file, and @var{color}
3790 specifies the actual color to use for displaying that name.
3794 @subsection GIF Images
3797 For GIF images, specify image type @code{gif}.
3800 @item :index @var{index}
3801 You can use @code{:index} to specify one image from a GIF file that
3802 contains more than one image. This property specifies use of image
3803 number @var{index} from the file. If the GIF file doesn't contain an
3804 image with index @var{index}, the image displays as a hollow box.
3808 This could be used to implement limited support for animated GIFs.
3809 For example, the following function displays a multi-image GIF file
3810 at point-min in the current buffer, switching between sub-images
3813 (defun show-anim (file max)
3814 "Display multi-image GIF file FILE which contains MAX subimages."
3815 (display-anim (current-buffer) file 0 max t))
3817 (defun display-anim (buffer file idx max first-time)
3820 (let ((img (create-image file nil :image idx)))
3823 (goto-char (point-min))
3824 (unless first-time (delete-char 1))
3826 (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
3829 @node Postscript Images
3830 @subsection Postscript Images
3831 @cindex Postscript images
3833 To use Postscript for an image, specify image type @code{postscript}.
3834 This works only if you have Ghostscript installed. You must always use
3835 these three properties:
3838 @item :pt-width @var{width}
3839 The value, @var{width}, specifies the width of the image measured in
3840 points (1/72 inch). @var{width} must be an integer.
3842 @item :pt-height @var{height}
3843 The value, @var{height}, specifies the height of the image in points
3844 (1/72 inch). @var{height} must be an integer.
3846 @item :bounding-box @var{box}
3847 The value, @var{box}, must be a list or vector of four integers, which
3848 specifying the bounding box of the Postscript image, analogous to the
3849 @samp{BoundingBox} comment found in Postscript files.
3852 %%BoundingBox: 22 171 567 738
3856 Displaying Postscript images from Lisp data is not currently
3857 implemented, but it may be implemented by the time you read this.
3858 See the @file{etc/NEWS} file to make sure.
3860 @node Other Image Types
3861 @subsection Other Image Types
3864 For PBM images, specify image type @code{pbm}. Color, gray-scale and
3865 monochromatic images are supported. For mono PBM images, two additional
3866 image properties are supported.
3869 @item :foreground @var{foreground}
3870 The value, @var{foreground}, should be a string specifying the image
3871 foreground color, or @code{nil} for the default color. This color is
3872 used for each pixel in the XBM that is 1. The default is the frame's
3875 @item :background @var{background}
3876 The value, @var{background}, should be a string specifying the image
3877 background color, or @code{nil} for the default color. This color is
3878 used for each pixel in the XBM that is 0. The default is the frame's
3882 For JPEG images, specify image type @code{jpeg}.
3884 For TIFF images, specify image type @code{tiff}.
3886 For PNG images, specify image type @code{png}.
3888 @node Defining Images
3889 @subsection Defining Images
3891 The functions @code{create-image}, @code{defimage} and
3892 @code{find-image} provide convenient ways to create image descriptors.
3894 @defun create-image file-or-data &optional type data-p &rest props
3895 @tindex create-image
3896 This function creates and returns an image descriptor which uses the
3897 data in @var{file-or-data}. @var{file-or-data} can be a file name or
3898 a string containing the image data; @var{data-p} should be @code{nil}
3899 for the former case, non-@code{nil} for the latter case.
3901 The optional argument @var{type} is a symbol specifying the image type.
3902 If @var{type} is omitted or @code{nil}, @code{create-image} tries to
3903 determine the image type from the file's first few bytes, or else
3904 from the file's name.
3906 The remaining arguments, @var{props}, specify additional image
3907 properties---for example,
3910 (create-image "foo.xpm" 'xpm nil :heuristic-mask t)
3913 The function returns @code{nil} if images of this type are not
3914 supported. Otherwise it returns an image descriptor.
3917 @defmac defimage symbol specs &optional doc
3919 This macro defines @var{symbol} as an image name. The arguments
3920 @var{specs} is a list which specifies how to display the image.
3921 The third argument, @var{doc}, is an optional documentation string.
3923 Each argument in @var{specs} has the form of a property list, and each
3924 one should specify at least the @code{:type} property and either the
3925 @code{:file} or the @code{:data} property. The value of @code{:type}
3926 should be a symbol specifying the image type, the value of
3927 @code{:file} is the file to load the image from, and the value of
3928 @code{:data} is a string containing the actual image data. Here is an
3932 (defimage test-image
3933 ((:type xpm :file "~/test1.xpm")
3934 (:type xbm :file "~/test1.xbm")))
3937 @code{defimage} tests each argument, one by one, to see if it is
3938 usable---that is, if the type is supported and the file exists. The
3939 first usable argument is used to make an image descriptor which is
3940 stored in @var{symbol}.
3942 If none of the alternatives will work, then @var{symbol} is defined
3946 @defun find-image specs
3948 This function provides a convenient way to find an image satisfying one
3949 of a list of image specifications @var{specs}.
3951 Each specification in @var{specs} is a property list with contents
3952 depending on image type. All specifications must at least contain the
3953 properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
3954 or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
3955 the image type, e.g.@: @code{xbm}, @var{file} is the file to load the
3956 image from, and @var{data} is a string containing the actual image data.
3957 The first specification in the list whose @var{type} is supported, and
3958 @var{file} exists, is used to construct the image specification to be
3959 returned. If no specification is satisfied, @code{nil} is returned.
3961 The image is looked for first on @code{load-path} and then in
3962 @code{data-directory}.
3965 @node Showing Images
3966 @subsection Showing Images
3968 You can use an image descriptor by setting up the @code{display}
3969 property yourself, but it is easier to use the functions in this
3972 @defun insert-image image &optional string area slice
3973 This function inserts @var{image} in the current buffer at point. The
3974 value @var{image} should be an image descriptor; it could be a value
3975 returned by @code{create-image}, or the value of a symbol defined with
3976 @code{defimage}. The argument @var{string} specifies the text to put
3977 in the buffer to hold the image. If it is omitted or @code{nil},
3978 @code{insert-image} uses @code{" "} by default.
3980 The argument @var{area} specifies whether to put the image in a margin.
3981 If it is @code{left-margin}, the image appears in the left margin;
3982 @code{right-margin} specifies the right margin. If @var{area} is
3983 @code{nil} or omitted, the image is displayed at point within the
3986 The argument @var{slice} specifies a slice of the image to insert. If
3987 @var{slice} is @code{nil} or omitted the whole image is inserted.
3988 Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width}
3989 @var{height})} which specifies the @var{x} and @var{y} positions and
3990 @var{width} and @var{height} of the image area to insert. Integer
3991 values are in units of pixels. A floating point number in the range
3992 0.0--1.0 stands for that fraction of the width or height of the entire
3995 Internally, this function inserts @var{string} in the buffer, and gives
3996 it a @code{display} property which specifies @var{image}. @xref{Display
4000 @defun insert-sliced-image image &optional string area rows cols
4001 This function inserts @var{image} in the current buffer at point, like
4002 @code{insert-image}, but splits the image into @var{rows}x@var{cols}
4003 equally sized slices.
4006 @defun put-image image pos &optional string area
4007 This function puts image @var{image} in front of @var{pos} in the
4008 current buffer. The argument @var{pos} should be an integer or a
4009 marker. It specifies the buffer position where the image should appear.
4010 The argument @var{string} specifies the text that should hold the image
4011 as an alternative to the default.
4013 The argument @var{image} must be an image descriptor, perhaps returned
4014 by @code{create-image} or stored by @code{defimage}.
4016 The argument @var{area} specifies whether to put the image in a margin.
4017 If it is @code{left-margin}, the image appears in the left margin;
4018 @code{right-margin} specifies the right margin. If @var{area} is
4019 @code{nil} or omitted, the image is displayed at point within the
4022 Internally, this function creates an overlay, and gives it a
4023 @code{before-string} property containing text that has a @code{display}
4024 property whose value is the image. (Whew!)
4027 @defun remove-images start end &optional buffer
4028 This function removes images in @var{buffer} between positions
4029 @var{start} and @var{end}. If @var{buffer} is omitted or @code{nil},
4030 images are removed from the current buffer.
4032 This removes only images that were put into @var{buffer} the way
4033 @code{put-image} does it, not images that were inserted with
4034 @code{insert-image} or in other ways.
4037 @defun image-size spec &optional pixels frame
4039 This function returns the size of an image as a pair
4040 @w{@code{(@var{width} . @var{height})}}. @var{spec} is an image
4041 specification. @var{pixels} non-@code{nil} means return sizes
4042 measured in pixels, otherwise return sizes measured in canonical
4043 character units (fractions of the width/height of the frame's default
4044 font). @var{frame} is the frame on which the image will be displayed.
4045 @var{frame} null or omitted means use the selected frame (@pxref{Input
4050 @subsection Image Cache
4052 Emacs stores images in an image cache when it displays them, so it can
4053 display them again more efficiently. It removes an image from the cache
4054 when it hasn't been displayed for a specified period of time.
4056 When an image is looked up in the cache, its specification is compared
4057 with cached image specifications using @code{equal}. This means that
4058 all images with equal specifications share the same image in the cache.
4060 @defvar image-cache-eviction-delay
4061 @tindex image-cache-eviction-delay
4062 This variable specifies the number of seconds an image can remain in the
4063 cache without being displayed. When an image is not displayed for this
4064 length of time, Emacs removes it from the image cache.
4066 If the value is @code{nil}, Emacs does not remove images from the cache
4067 except when you explicitly clear it. This mode can be useful for
4071 @defun clear-image-cache &optional frame
4072 @tindex clear-image-cache
4073 This function clears the image cache. If @var{frame} is non-@code{nil},
4074 only the cache for that frame is cleared. Otherwise all frames' caches
4081 @cindex buttons in buffers
4082 @cindex clickable buttons in buffers
4084 The @emph{button} package defines functions for inserting and
4085 manipulating clickable (with the mouse, or via keyboard commands)
4086 buttons in Emacs buffers, such as might be used for help hyper-links,
4087 etc. Emacs uses buttons for the hyper-links in help text and the like.
4089 A button is essentially a set of properties attached (via text
4090 properties or overlays) to a region of text in an Emacs buffer. These
4091 properties are called @dfn{button properties}.
4093 One of the these properties (@code{action}) is a function, which will
4094 be called when the user invokes it using the keyboard or the mouse.
4095 The invoked function may then examine the button and use its other
4096 properties as desired.
4098 In some ways the Emacs button package duplicates functionality offered
4099 by the widget package (@pxref{Top, , Introduction, widget, The Emacs
4100 Widget Library}), but the button package has the advantage that it is
4101 much faster, much smaller, and much simpler to use (for elisp
4102 programmers---for users, the result is about the same). The extra
4103 speed and space savings are useful mainly if you need to create many
4104 buttons in a buffer (for instance an @code{*Apropos*} buffer uses
4105 buttons to make entries clickable, and may contain many thousands of
4109 * Button Properties:: Button properties with special meanings.
4110 * Button Types:: Defining common properties for classes of buttons.
4111 * Making Buttons:: Adding buttons to Emacs buffers.
4112 * Manipulating Buttons:: Getting and setting properties of buttons.
4113 * Button Buffer Commands:: Buffer-wide commands and bindings for buttons.
4116 @node Button Properties
4117 @subsection Button Properties
4118 @cindex button properties
4120 Buttons have an associated list of properties defining their
4121 appearance and behavior, and other arbitrary properties may be used
4122 for application specific purposes. Some properties that have special
4123 meaning to the button package include:
4127 @kindex action @r{(button property)}
4128 The function to call when the user invokes the button, which is passed
4129 the single argument @var{button}. By default this is @code{ignore},
4133 @kindex mouse-action @r{(button property)}
4134 This is similar to @code{action}, and when present, will be used
4135 instead of @code{action} for button invocations resulting from
4136 mouse-clicks (instead of the user hitting @key{RET}). If not
4137 present, mouse-clicks use @code{action} instead.
4140 @kindex face @r{(button property)}
4141 This is an Emacs face controlling how buttons of this type are
4142 displayed; by default this is the @code{button} face.
4145 @kindex mouse-face @r{(button property)}
4146 This is an additional face which controls appearance during
4147 mouse-overs (merged with the usual button face); by default this is
4148 the usual Emacs @code{highlight} face.
4151 @kindex keymap @r{(button property)}
4152 The button's keymap, defining bindings active within the button
4153 region. By default this is the usual button region keymap, stored
4154 in the variable @code{button-map}, which defines @key{RET} and
4155 @key{mouse-2} to invoke the button.
4158 @kindex type @r{(button property)}
4159 The button-type of the button. When creating a button, this is
4160 usually specified using the @code{:type} keyword argument.
4161 @xref{Button Types}.
4164 @kindex help-index @r{(button property)}
4165 A string displayed by the Emacs tool-tip help system; by default,
4166 @code{"mouse-2, RET: Push this button"}.
4169 @kindex follow-link @r{(button property)}
4170 The follow-link property, defining how a @key{Mouse-1} click behaves
4171 on this button, @xref{Links and Mouse-1}.
4174 @kindex button @r{(button property)}
4175 All buttons have a non-@code{nil} @code{button} property, which may be useful
4176 in finding regions of text that comprise buttons (which is what the
4177 standard button functions do).
4180 There are other properties defined for the regions of text in a
4181 button, but these are not generally interesting for typical uses.
4184 @subsection Button Types
4185 @cindex button types
4187 Every button has a button @emph{type}, which defines default values
4188 for the button's properties. Button types are arranged in a
4189 hierarchy, with specialized types inheriting from more general types,
4190 so that it's easy to define special-purpose types of buttons for
4193 @defun define-button-type name &rest properties
4194 @tindex define-button-type
4195 Define a `button type' called @var{name}. The remaining arguments
4196 form a sequence of @var{property value} pairs, specifying default
4197 property values for buttons with this type (a button's type may be set
4198 by giving it a @code{type} property when creating the button, using
4199 the @code{:type} keyword argument).
4201 In addition, the keyword argument @code{:supertype} may be used to
4202 specify a button-type from which @var{name} inherits its default
4203 property values. Note that this inheritance happens only when
4204 @var{name} is defined; subsequent changes to a supertype are not
4205 reflected in its subtypes.
4208 Using @code{define-button-type} to define default properties for
4209 buttons is not necessary---buttons without any specified type use the
4210 built-in button-type @code{button}---but it is encouraged, since
4211 doing so usually makes the resulting code clearer and more efficient.
4213 @node Making Buttons
4214 @subsection Making Buttons
4215 @cindex making buttons
4217 Buttons are associated with a region of text, using an overlay or
4218 text properties to hold button-specific information, all of which are
4219 initialized from the button's type (which defaults to the built-in
4220 button type @code{button}). Like all Emacs text, the appearance of
4221 the button is governed by the @code{face} property; by default (via
4222 the @code{face} property inherited from the @code{button} button-type)
4223 this is a simple underline, like a typical web-page link.
4225 For convenience, there are two sorts of button-creation functions,
4226 those that add button properties to an existing region of a buffer,
4227 called @code{make-...button}, and those also insert the button text,
4228 called @code{insert-...button}.
4230 The button-creation functions all take the @code{&rest} argument
4231 @var{properties}, which should be a sequence of @var{property value}
4232 pairs, specifying properties to add to the button; see @ref{Button
4233 Properties}. In addition, the keyword argument @code{:type} may be
4234 used to specify a button-type from which to inherit other properties;
4235 see @ref{Button Types}. Any properties not explicitly specified
4236 during creation will be inherited from the button's type (if the type
4237 defines such a property).
4239 The following functions add a button using an overlay
4240 (@pxref{Overlays}) to hold the button properties:
4242 @defun make-button beg end &rest properties
4244 This makes a button from @var{beg} to @var{end} in the
4245 current buffer, and returns it.
4248 @defun insert-button label &rest properties
4249 @tindex insert-button
4250 This insert a button with the label @var{label} at point,
4254 The following functions are similar, but use Emacs text properties
4255 (@pxref{Text Properties}) to hold the button properties, making the
4256 button actually part of the text instead of being a property of the
4257 buffer. Buttons using text properties do not create markers into the
4258 buffer, which is important for speed when you use extremely large
4259 numbers of buttons. Both functions return the position of the start
4262 @defun make-text-button beg end &rest properties
4263 @tindex make-text-button
4264 This makes a button from @var{beg} to @var{end} in the current buffer, using
4268 @defun insert-text-button label &rest properties
4269 @tindex insert-text-button
4270 This inserts a button with the label @var{label} at point, using text
4274 @node Manipulating Buttons
4275 @subsection Manipulating Buttons
4276 @cindex manipulating buttons
4278 These are functions for getting and setting properties of buttons.
4279 Often these are used by a button's invocation function to determine
4282 Where a @var{button} parameter is specified, it means an object
4283 referring to a specific button, either an overlay (for overlay
4284 buttons), or a buffer-position or marker (for text property buttons).
4285 Such an object is passed as the first argument to a button's
4286 invocation function when it is invoked.
4288 @defun button-start button
4289 @tindex button-start
4290 Return the position at which @var{button} starts.
4293 @defun button-end button
4295 Return the position at which @var{button} ends.
4298 @defun button-get button prop
4300 Get the property of button @var{button} named @var{prop}.
4303 @defun button-put button prop val
4305 Set @var{button}'s @var{prop} property to @var{val}.
4308 @defun button-activate button &optional use-mouse-action
4309 @tindex button-activate
4310 Call @var{button}'s @code{action} property (i.e., invoke it). If
4311 @var{use-mouse-action} is non-@code{nil}, try to invoke the button's
4312 @code{mouse-action} property instead of @code{action}; if the button
4313 has no @code{mouse-action} property, use @code{action} as normal.
4316 @defun button-label button
4317 @tindex button-label
4318 Return @var{button}'s text label.
4321 @defun button-type button
4323 Return @var{button}'s button-type.
4326 @defun button-has-type-p button type
4327 @tindex button-has-type-p
4328 Return @code{t} if @var{button} has button-type @var{type}, or one of
4329 @var{type}'s subtypes.
4332 @defun button-at pos
4334 Return the button at position @var{pos} in the current buffer, or @code{nil}.
4337 @defun button-type-put type prop val
4338 @tindex button-type-put
4339 Set the button-type @var{type}'s @var{prop} property to @var{val}.
4342 @defun button-type-get type prop
4343 @tindex button-type-get
4344 Get the property of button-type @var{type} named @var{prop}.
4347 @defun button-type-subtype-p type supertype
4348 @tindex button-type-subtype-p
4349 Return @code{t} if button-type @var{type} is a subtype of @var{supertype}.
4352 @node Button Buffer Commands
4353 @subsection Button Buffer Commands
4354 @cindex button buffer commands
4356 These are commands and functions for locating and operating on
4357 buttons in an Emacs buffer.
4359 @code{push-button} is the command that a user uses to actually `push'
4360 a button, and is bound by default in the button itself to @key{RET}
4361 and to @key{mouse-2} using a region-specific keymap. Commands
4362 that are useful outside the buttons itself, such as
4363 @code{forward-button} and @code{backward-button} are additionally
4364 available in the keymap stored in @code{button-buffer-map}; a mode
4365 which uses buttons may want to use @code{button-buffer-map} as a
4366 parent keymap for its keymap.
4368 If the button has a non-@code{nil} @code{follow-link} property, and
4369 @var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click
4370 will also activate the @code{push-button} command.
4371 @xref{Links and Mouse-1}.
4373 @deffn Command push-button &optional pos use-mouse-action
4375 Perform the action specified by a button at location @var{pos}.
4376 @var{pos} may be either a buffer position or a mouse-event. If
4377 @var{use-mouse-action} is non-@code{nil}, or @var{pos} is a
4378 mouse-event (@pxref{Mouse Events}), try to invoke the button's
4379 @code{mouse-action} property instead of @code{action}; if the button
4380 has no @code{mouse-action} property, use @code{action} as normal.
4381 @var{pos} defaults to point, except when @code{push-button} is invoked
4382 interactively as the result of a mouse-event, in which case, the mouse
4383 event's position is used. If there's no button at @var{pos}, do
4384 nothing and return @code{nil}, otherwise return @code{t}.
4387 @deffn Command forward-button n &optional wrap display-message
4388 @tindex forward-button
4389 Move to the @var{n}th next button, or @var{n}th previous button if
4390 @var{n} is negative. If @var{n} is zero, move to the start of any
4391 button at point. If @var{wrap} is non-@code{nil}, moving past either
4392 end of the buffer continues from the other end. If
4393 @var{display-message} is non-@code{nil}, the button's help-echo string
4394 is displayed. Any button with a non-@code{nil} @code{skip} property
4395 is skipped over. Returns the button found.
4398 @deffn Command backward-button n &optional wrap display-message
4399 @tindex backward-button
4400 Move to the @var{n}th previous button, or @var{n}th next button if
4401 @var{n} is negative. If @var{n} is zero, move to the start of any
4402 button at point. If @var{wrap} is non-@code{nil}, moving past either
4403 end of the buffer continues from the other end. If
4404 @var{display-message} is non-@code{nil}, the button's help-echo string
4405 is displayed. Any button with a non-@code{nil} @code{skip} property
4406 is skipped over. Returns the button found.
4409 @defun next-button pos &optional count-current
4411 Return the next button after position @var{pos} in the current buffer.
4412 If @var{count-current} is non-@code{nil}, count any button at
4413 @var{pos} in the search, instead of starting at the next button.
4416 @defun previous-button pos &optional count-current
4417 @tindex previous-button
4418 Return the @var{n}th button before position @var{pos} in the current
4419 buffer. If @var{count-current} is non-@code{nil}, count any button at
4420 @var{pos} in the search, instead of starting at the next button.
4424 @section Blinking Parentheses
4425 @cindex parenthesis matching
4427 @cindex balancing parentheses
4428 @cindex close parenthesis
4430 This section describes the mechanism by which Emacs shows a matching
4431 open parenthesis when the user inserts a close parenthesis.
4433 @defvar blink-paren-function
4434 The value of this variable should be a function (of no arguments) to
4435 be called whenever a character with close parenthesis syntax is inserted.
4436 The value of @code{blink-paren-function} may be @code{nil}, in which
4437 case nothing is done.
4440 @defopt blink-matching-paren
4441 If this variable is @code{nil}, then @code{blink-matching-open} does
4445 @defopt blink-matching-paren-distance
4446 This variable specifies the maximum distance to scan for a matching
4447 parenthesis before giving up.
4450 @defopt blink-matching-delay
4451 This variable specifies the number of seconds for the cursor to remain
4452 at the matching parenthesis. A fraction of a second often gives
4453 good results, but the default is 1, which works on all systems.
4456 @deffn Command blink-matching-open
4457 This function is the default value of @code{blink-paren-function}. It
4458 assumes that point follows a character with close parenthesis syntax and
4459 moves the cursor momentarily to the matching opening character. If that
4460 character is not already on the screen, it displays the character's
4461 context in the echo area. To avoid long delays, this function does not
4462 search farther than @code{blink-matching-paren-distance} characters.
4464 Here is an example of calling this function explicitly.
4468 (defun interactive-blink-matching-open ()
4469 @c Do not break this line! -- rms.
4470 @c The first line of a doc string
4471 @c must stand alone.
4472 "Indicate momentarily the start of sexp before point."
4476 (let ((blink-matching-paren-distance
4478 (blink-matching-paren t))
4479 (blink-matching-open)))
4485 @section Inverse Video
4486 @cindex Inverse Video
4488 @defopt inverse-video
4489 @cindex highlighting
4490 This variable controls whether Emacs uses inverse video for all text
4491 on the screen. Non-@code{nil} means yes, @code{nil} means no. The
4492 default is @code{nil}.
4495 @defopt mode-line-inverse-video
4496 This variable controls the use of inverse video for mode lines and
4497 menu bars. If it is non-@code{nil}, then these lines are displayed in
4498 the face @code{mode-line}. Otherwise, these lines are displayed
4499 normally, just like other text. The default is @code{t}.
4503 @section Usual Display Conventions
4505 The usual display conventions define how to display each character
4506 code. You can override these conventions by setting up a display table
4507 (@pxref{Display Tables}). Here are the usual display conventions:
4511 Character codes 32 through 126 map to glyph codes 32 through 126.
4512 Normally this means they display as themselves.
4515 Character code 9 is a horizontal tab. It displays as whitespace
4516 up to a position determined by @code{tab-width}.
4519 Character code 10 is a newline.
4522 All other codes in the range 0 through 31, and code 127, display in one
4523 of two ways according to the value of @code{ctl-arrow}. If it is
4524 non-@code{nil}, these codes map to sequences of two glyphs, where the
4525 first glyph is the @acronym{ASCII} code for @samp{^}. (A display table can
4526 specify a glyph to use instead of @samp{^}.) Otherwise, these codes map
4527 just like the codes in the range 128 to 255.
4529 On MS-DOS terminals, Emacs arranges by default for the character code
4530 127 to be mapped to the glyph code 127, which normally displays as an
4531 empty polygon. This glyph is used to display non-@acronym{ASCII} characters
4532 that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,,
4533 emacs, The GNU Emacs Manual}.
4536 Character codes 128 through 255 map to sequences of four glyphs, where
4537 the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are
4538 digit characters representing the character code in octal. (A display
4539 table can specify a glyph to use instead of @samp{\}.)
4542 Multibyte character codes above 256 are displayed as themselves, or as a
4543 question mark or empty box if the terminal cannot display that
4547 The usual display conventions apply even when there is a display
4548 table, for any character whose entry in the active display table is
4549 @code{nil}. Thus, when you set up a display table, you need only
4550 specify the characters for which you want special behavior.
4552 These display rules apply to carriage return (character code 13), when
4553 it appears in the buffer. But that character may not appear in the
4554 buffer where you expect it, if it was eliminated as part of end-of-line
4555 conversion (@pxref{Coding System Basics}).
4557 These variables affect the way certain characters are displayed on the
4558 screen. Since they change the number of columns the characters occupy,
4559 they also affect the indentation functions. These variables also affect
4560 how the mode line is displayed; if you want to force redisplay of the
4561 mode line using the new values, call the function
4562 @code{force-mode-line-update} (@pxref{Mode Line Format}).
4565 @cindex control characters in display
4566 This buffer-local variable controls how control characters are
4567 displayed. If it is non-@code{nil}, they are displayed as a caret
4568 followed by the character: @samp{^A}. If it is @code{nil}, they are
4569 displayed as a backslash followed by three octal digits: @samp{\001}.
4572 @c Following may have overfull hbox.
4573 @defvar default-ctl-arrow
4574 The value of this variable is the default value for @code{ctl-arrow} in
4575 buffers that do not override it. @xref{Default Value}.
4579 The value of this variable is the spacing between tab stops used for
4580 displaying tab characters in Emacs buffers. The value is in units of
4581 columns, and the default is 8. Note that this feature is completely
4582 independent of the user-settable tab stops used by the command
4583 @code{tab-to-tab-stop}. @xref{Indent Tabs}.
4586 @defopt indicate-empty-lines
4587 @tindex indicate-empty-lines
4588 @cindex fringes, and empty line indication
4589 When this is non-@code{nil}, Emacs displays a special glyph in the
4590 fringe of each empty line at the end of the buffer, on terminals that
4591 support it (window systems). @xref{Fringes}.
4594 @defvar indicate-buffer-boundaries
4595 This buffer-local variable controls how the buffer boundaries and
4596 window scrolling are indicated in the window fringes.
4598 Emacs can indicate the buffer boundaries---that is, the first and last
4599 line in the buffer---with angle icons when they appear on the screen.
4600 In addition, Emacs can display an up-arrow in the fringe to show
4601 that there is text above the screen, and a down-arrow to show
4602 there is text below the screen.
4604 There are four kinds of basic values:
4608 Don't display the icons.
4610 Display them in the left fringe.
4612 Display them in the right fringe.
4613 @item @var{anything-else}
4614 Display the icon at the top of the window top in the left fringe, and other
4615 in the right fringe.
4618 If value is a cons @code{(@var{angles} . @var{arrows})}, @var{angles}
4619 controls the angle icons, and @var{arrows} controls the arrows. Both
4620 @var{angles} and @var{arrows} work according to the table above.
4621 Thus, @code{(t . right)} places the top angle icon in the left
4622 fringe, the bottom angle icon in the right fringe, and both arrows in
4626 @defvar default-indicate-buffer-boundaries
4627 The value of this variable is the default value for
4628 @code{indicate-buffer-boundaries} in buffers that do not override it.
4631 @node Display Tables
4632 @section Display Tables
4634 @cindex display table
4635 You can use the @dfn{display table} feature to control how all possible
4636 character codes display on the screen. This is useful for displaying
4637 European languages that have letters not in the @acronym{ASCII} character
4640 The display table maps each character code into a sequence of
4641 @dfn{glyphs}, each glyph being a graphic that takes up one character
4642 position on the screen. You can also define how to display each glyph
4643 on your terminal, using the @dfn{glyph table}.
4645 Display tables affect how the mode line is displayed; if you want to
4646 force redisplay of the mode line using a new display table, call
4647 @code{force-mode-line-update} (@pxref{Mode Line Format}).
4650 * Display Table Format:: What a display table consists of.
4651 * Active Display Table:: How Emacs selects a display table to use.
4652 * Glyphs:: How to define a glyph, and what glyphs mean.
4655 @node Display Table Format
4656 @subsection Display Table Format
4658 A display table is actually a char-table (@pxref{Char-Tables}) with
4659 @code{display-table} as its subtype.
4661 @defun make-display-table
4662 This creates and returns a display table. The table initially has
4663 @code{nil} in all elements.
4666 The ordinary elements of the display table are indexed by character
4667 codes; the element at index @var{c} says how to display the character
4668 code @var{c}. The value should be @code{nil} or a vector of glyph
4669 values (@pxref{Glyphs}). If an element is @code{nil}, it says to
4670 display that character according to the usual display conventions
4671 (@pxref{Usual Display}).
4673 If you use the display table to change the display of newline
4674 characters, the whole buffer will be displayed as one long ``line.''
4676 The display table also has six ``extra slots'' which serve special
4677 purposes. Here is a table of their meanings; @code{nil} in any slot
4678 means to use the default for that slot, as stated below.
4682 The glyph for the end of a truncated screen line (the default for this
4683 is @samp{$}). @xref{Glyphs}. On graphical terminals, Emacs uses
4684 arrows in the fringes to indicate truncation, so the display table has
4688 The glyph for the end of a continued line (the default is @samp{\}).
4689 On graphical terminals, Emacs uses curved arrows in the fringes to
4690 indicate continuation, so the display table has no effect.
4693 The glyph for indicating a character displayed as an octal character
4694 code (the default is @samp{\}).
4697 The glyph for indicating a control character (the default is @samp{^}).
4700 A vector of glyphs for indicating the presence of invisible lines (the
4701 default is @samp{...}). @xref{Selective Display}.
4704 The glyph used to draw the border between side-by-side windows (the
4705 default is @samp{|}). @xref{Splitting Windows}. This takes effect only
4706 when there are no scroll bars; if scroll bars are supported and in use,
4707 a scroll bar separates the two windows.
4710 For example, here is how to construct a display table that mimics the
4711 effect of setting @code{ctl-arrow} to a non-@code{nil} value:
4714 (setq disptab (make-display-table))
4717 (or (= i ?\t) (= i ?\n)
4718 (aset disptab i (vector ?^ (+ i 64))))
4720 (aset disptab 127 (vector ?^ ??)))
4723 @defun display-table-slot display-table slot
4724 This function returns the value of the extra slot @var{slot} of
4725 @var{display-table}. The argument @var{slot} may be a number from 0 to
4726 5 inclusive, or a slot name (symbol). Valid symbols are
4727 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
4728 @code{selective-display}, and @code{vertical-border}.
4731 @defun set-display-table-slot display-table slot value
4732 This function stores @var{value} in the extra slot @var{slot} of
4733 @var{display-table}. The argument @var{slot} may be a number from 0 to
4734 5 inclusive, or a slot name (symbol). Valid symbols are
4735 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
4736 @code{selective-display}, and @code{vertical-border}.
4739 @defun describe-display-table display-table
4740 @tindex describe-display-table
4741 This function displays a description of the display table
4742 @var{display-table} in a help buffer.
4745 @deffn Command describe-current-display-table
4746 @tindex describe-current-display-table
4747 This command displays a description of the current display table in a
4751 @node Active Display Table
4752 @subsection Active Display Table
4753 @cindex active display table
4755 Each window can specify a display table, and so can each buffer. When
4756 a buffer @var{b} is displayed in window @var{w}, display uses the
4757 display table for window @var{w} if it has one; otherwise, the display
4758 table for buffer @var{b} if it has one; otherwise, the standard display
4759 table if any. The display table chosen is called the @dfn{active}
4762 @defun window-display-table &optional window
4763 This function returns @var{window}'s display table, or @code{nil}
4764 if @var{window} does not have an assigned display table. The default
4765 for @var{window} is the selected window.
4768 @defun set-window-display-table window table
4769 This function sets the display table of @var{window} to @var{table}.
4770 The argument @var{table} should be either a display table or
4774 @defvar buffer-display-table
4775 This variable is automatically buffer-local in all buffers; its value in
4776 a particular buffer specifies the display table for that buffer. If it
4777 is @code{nil}, that means the buffer does not have an assigned display
4781 @defvar standard-display-table
4782 This variable's value is the default display table, used whenever a
4783 window has no display table and neither does the buffer displayed in
4784 that window. This variable is @code{nil} by default.
4787 If there is no display table to use for a particular window---that is,
4788 if the window specifies none, its buffer specifies none, and
4789 @code{standard-display-table} is @code{nil}---then Emacs uses the usual
4790 display conventions for all character codes in that window. @xref{Usual
4793 A number of functions for changing the standard display table
4794 are defined in the library @file{disp-table}.
4800 A @dfn{glyph} is a generalization of a character; it stands for an
4801 image that takes up a single character position on the screen. Glyphs
4802 are represented in Lisp as integers, just as characters are. Normally
4803 Emacs finds glyphs in the display table (@pxref{Display Tables}).
4805 A glyph can be @dfn{simple} or it can be defined by the @dfn{glyph
4806 table}. A simple glyph is just a way of specifying a character and a
4807 face to output it in. The glyph code for a simple glyph, mod 524288,
4808 is the character to output, and the glyph code divided by 524288
4809 specifies the face number (@pxref{Face Functions}) to use while
4810 outputting it. (524288 is
4819 On character terminals, you can set up a @dfn{glyph table} to define
4820 the meaning of glyph codes. The glyph codes is the value of the
4821 variable @code{glyph-table}.
4824 The value of this variable is the current glyph table. It should be a
4825 vector; the @var{g}th element defines glyph code @var{g}.
4827 If a glyph code is greater than or equal to the length of the glyph
4828 table, that code is automatically simple. If the value of
4829 @code{glyph-table} is @code{nil} instead of a vector, then all glyphs
4830 are simple. The glyph table is not used on graphical displays, only
4831 on character terminals. On graphical displays, all glyphs are simple.
4834 Here are the possible types of elements in the glyph table:
4838 Send the characters in @var{string} to the terminal to output
4839 this glyph. This alternative is available on character terminals,
4840 but not under a window system.
4843 Define this glyph code as an alias for glyph code @var{integer}. You
4844 can use an alias to specify a face code for the glyph and use a small
4848 This glyph is simple.
4851 @defun create-glyph string
4852 @tindex create-glyph
4853 This function returns a newly-allocated glyph code which is set up to
4854 display by sending @var{string} to the terminal.
4862 This section describes how to make Emacs ring the bell (or blink the
4863 screen) to attract the user's attention. Be conservative about how
4864 often you do this; frequent bells can become irritating. Also be
4865 careful not to use just beeping when signaling an error is more
4866 appropriate. (@xref{Errors}.)
4868 @defun ding &optional do-not-terminate
4869 @cindex keyboard macro termination
4870 This function beeps, or flashes the screen (see @code{visible-bell} below).
4871 It also terminates any keyboard macro currently executing unless
4872 @var{do-not-terminate} is non-@code{nil}.
4875 @defun beep &optional do-not-terminate
4876 This is a synonym for @code{ding}.
4879 @defopt visible-bell
4880 This variable determines whether Emacs should flash the screen to
4881 represent a bell. Non-@code{nil} means yes, @code{nil} means no. This
4882 is effective on a window system, and on a character-only terminal
4883 provided the terminal's Termcap entry defines the visible bell
4884 capability (@samp{vb}).
4887 @defvar ring-bell-function
4888 If this is non-@code{nil}, it specifies how Emacs should ``ring the
4889 bell.'' Its value should be a function of no arguments. If this is
4890 non-@code{nil}, it takes precedence over the @code{visible-bell}
4894 @node Window Systems
4895 @section Window Systems
4897 Emacs works with several window systems, most notably the X Window
4898 System. Both Emacs and X use the term ``window'', but use it
4899 differently. An Emacs frame is a single window as far as X is
4900 concerned; the individual Emacs windows are not known to X at all.
4902 @defvar window-system
4903 This variable tells Lisp programs what window system Emacs is running
4904 under. The possible values are
4908 @cindex X Window System
4909 Emacs is displaying using X.
4911 Emacs is displaying using MS-DOS.
4913 Emacs is displaying using Windows.
4915 Emacs is displaying using a Macintosh.
4917 Emacs is using a character-based terminal.
4921 @defvar window-setup-hook
4922 This variable is a normal hook which Emacs runs after handling the
4923 initialization files. Emacs runs this hook after it has completed
4924 loading your init file, the default initialization file (if
4925 any), and the terminal-specific Lisp code, and running the hook
4926 @code{term-setup-hook}.
4928 This hook is used for internal purposes: setting up communication with
4929 the window system, and creating the initial window. Users should not
4934 arch-tag: ffdf5714-7ecf-415b-9023-fbc6b409c2c6