Conflate Qnil and Qunbound for `symbol-function'.
[emacs.git] / doc / lispref / display.texi
blob475a9550f991d12308498602e54c82e81abc6149
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @node Display
6 @chapter Emacs Display
8   This chapter describes a number of features related to the display
9 that Emacs presents to the user.
11 @menu
12 * Refresh Screen::      Clearing the screen and redrawing everything on it.
13 * Forcing Redisplay::   Forcing redisplay.
14 * Truncation::          Folding or wrapping long text lines.
15 * The Echo Area::       Displaying messages at the bottom of the screen.
16 * Warnings::            Displaying warning messages for the user.
17 * Invisible Text::      Hiding part of the buffer text.
18 * Selective Display::   Hiding part of the buffer text (the old way).
19 * Temporary Displays::  Displays that go away automatically.
20 * Overlays::            Use overlays to highlight parts of the buffer.
21 * Width::               How wide a character or string is on the screen.
22 * Line Height::         Controlling the height of lines.
23 * Faces::               A face defines a graphics style for text characters:
24                           font, colors, etc.
25 * Fringes::             Controlling window fringes.
26 * Scroll Bars::         Controlling vertical scroll bars.
27 * Display Property::    Enabling special display features.
28 * Images::              Displaying images in Emacs buffers.
29 * Buttons::             Adding clickable buttons to Emacs buffers.
30 * Abstract Display::    Emacs's Widget for Object Collections.
31 * Blinking::            How Emacs shows the matching open parenthesis.
32 * Character Display::   How Emacs displays individual characters.
33 * Beeping::             Audible signal to the user.
34 * Window Systems::      Which window system is being used.
35 * Bidirectional Display:: Display of bidirectional scripts, such as
36                              Arabic and Farsi.
37 @end menu
39 @node Refresh Screen
40 @section Refreshing the Screen
42   The function @code{redraw-frame} clears and redisplays the entire
43 contents of a given frame (@pxref{Frames}).  This is useful if the
44 screen is corrupted.
46 @defun redraw-frame frame
47 This function clears and redisplays frame @var{frame}.
48 @end defun
50   Even more powerful is @code{redraw-display}:
52 @deffn Command redraw-display
53 This function clears and redisplays all visible frames.
54 @end deffn
56   In Emacs, processing user input takes priority over redisplay.  If
57 you call these functions when input is available, they don't redisplay
58 immediately, but the requested redisplay does happen
59 eventually---after all the input has been processed.
61   On text terminals, suspending and resuming Emacs normally also
62 refreshes the screen.  Some terminal emulators record separate
63 contents for display-oriented programs such as Emacs and for ordinary
64 sequential display.  If you are using such a terminal, you might want
65 to inhibit the redisplay on resumption.
67 @defopt no-redraw-on-reenter
68 @cindex suspend (cf. @code{no-redraw-on-reenter})
69 @cindex resume (cf. @code{no-redraw-on-reenter})
70 This variable controls whether Emacs redraws the entire screen after it
71 has been suspended and resumed.  Non-@code{nil} means there is no need
72 to redraw, @code{nil} means redrawing is needed.  The default is @code{nil}.
73 @end defopt
75 @node Forcing Redisplay
76 @section Forcing Redisplay
77 @cindex forcing redisplay
79   Emacs normally tries to redisplay the screen whenever it waits for
80 input.  With the following function, you can request an immediate
81 attempt to redisplay, in the middle of Lisp code, without actually
82 waiting for input.
84 @defun redisplay &optional force
85 This function tries immediately to redisplay.  The optional argument
86 @var{force}, if non-@code{nil}, forces the redisplay to be performed,
87 instead of being preempted, even if input is pending and the variable
88 @code{redisplay-dont-pause} is @code{nil} (see below).  If
89 @code{redisplay-dont-pause} is non-@code{nil} (the default), this
90 function redisplays in any case, i.e.@: @var{force} does nothing.
92 The function returns @code{t} if it actually tried to redisplay, and
93 @code{nil} otherwise.  A value of @code{t} does not mean that
94 redisplay proceeded to completion; it could have been preempted by
95 newly arriving input.
96 @end defun
98 @defvar redisplay-dont-pause
99 If this variable is @code{nil}, arriving input events preempt
100 redisplay; Emacs avoids starting a redisplay, and stops any redisplay
101 that is in progress, until the input has been processed.  In
102 particular, @code{(redisplay)} returns @code{nil} without actually
103 redisplaying, if there is pending input.
105 The default value is @code{t}, which means that pending input does not
106 preempt redisplay.
107 @end defvar
109 @defvar redisplay-preemption-period
110 If @code{redisplay-dont-pause} is @code{nil}, this variable specifies
111 how many seconds Emacs waits between checks for new input during
112 redisplay; if input arrives during this interval, redisplay stops and
113 the input is processed.  The default value is 0.1; if the value is
114 @code{nil}, Emacs does not check for input during redisplay.
116 This variable has no effect when @code{redisplay-dont-pause} is
117 non-@code{nil} (the default).
118 @end defvar
120   Although @code{redisplay} tries immediately to redisplay, it does
121 not change how Emacs decides which parts of its frame(s) to redisplay.
122 By contrast, the following function adds certain windows to the
123 pending redisplay work (as if their contents had completely changed),
124 but does not immediately try to perform redisplay.
126 @defun force-window-update &optional object
127 This function forces some or all windows to be updated the next time
128 Emacs does a redisplay.  If @var{object} is a window, that window is
129 to be updated.  If @var{object} is a buffer or buffer name, all
130 windows displaying that buffer are to be updated.  If @var{object} is
131 @code{nil} (or omitted), all windows are to be updated.
133 This function does not do a redisplay immediately; Emacs does that as
134 it waits for input, or when the function @code{redisplay} is called.
135 @end defun
137 @node Truncation
138 @section Truncation
139 @cindex line wrapping
140 @cindex line truncation
141 @cindex continuation lines
142 @cindex @samp{$} in display
143 @cindex @samp{\} in display
145   When a line of text extends beyond the right edge of a window, Emacs
146 can @dfn{continue} the line (make it ``wrap'' to the next screen
147 line), or @dfn{truncate} the line (limit it to one screen line).  The
148 additional screen lines used to display a long text line are called
149 @dfn{continuation} lines.  Continuation is not the same as filling;
150 continuation happens on the screen only, not in the buffer contents,
151 and it breaks a line precisely at the right margin, not at a word
152 boundary.  @xref{Filling}.
154    On a graphical display, tiny arrow images in the window fringes
155 indicate truncated and continued lines (@pxref{Fringes}).  On a text
156 terminal, a @samp{$} in the rightmost column of the window indicates
157 truncation; a @samp{\} on the rightmost column indicates a line that
158 ``wraps''.  (The display table can specify alternate characters to use
159 for this; @pxref{Display Tables}).
161 @defopt truncate-lines
162 If this buffer-local variable is non-@code{nil}, lines that extend
163 beyond the right edge of the window are truncated; otherwise, they are
164 continued.  As a special exception, the variable
165 @code{truncate-partial-width-windows} takes precedence in
166 @dfn{partial-width} windows (i.e.@: windows that do not occupy the
167 entire frame width).
168 @end defopt
170 @defopt truncate-partial-width-windows
171 This variable controls line truncation in @dfn{partial-width} windows.
172 A partial-width window is one that does not occupy the entire frame
173 width (@pxref{Splitting Windows}).  If the value is @code{nil}, line
174 truncation is determined by the variable @code{truncate-lines} (see
175 above).  If the value is an integer @var{n}, lines are truncated if
176 the partial-width window has fewer than @var{n} columns, regardless of
177 the value of @code{truncate-lines}; if the partial-width window has
178 @var{n} or more columns, line truncation is determined by
179 @code{truncate-lines}.  For any other non-@code{nil} value, lines are
180 truncated in every partial-width window, regardless of the value of
181 @code{truncate-lines}.
182 @end defopt
184   When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
185 a window, that forces truncation.
187 @defvar wrap-prefix
188 If this buffer-local variable is non-@code{nil}, it defines a
189 @dfn{wrap prefix} which Emacs displays at the start of every
190 continuation line.  (If lines are truncated, @code{wrap-prefix} is
191 never used.)  Its value may be a string or an image (@pxref{Other
192 Display Specs}), or a stretch of whitespace such as specified by the
193 @code{:width} or @code{:align-to} display properties (@pxref{Specified
194 Space}).  The value is interpreted in the same way as a @code{display}
195 text property.  @xref{Display Property}.
197 A wrap prefix may also be specified for regions of text, using the
198 @code{wrap-prefix} text or overlay property.  This takes precedence
199 over the @code{wrap-prefix} variable.  @xref{Special Properties}.
200 @end defvar
202 @defvar line-prefix
203 If this buffer-local variable is non-@code{nil}, it defines a
204 @dfn{line prefix} which Emacs displays at the start of every
205 non-continuation line.  Its value may be a string or an image
206 (@pxref{Other Display Specs}), or a stretch of whitespace such as
207 specified by the @code{:width} or @code{:align-to} display properties
208 (@pxref{Specified Space}).  The value is interpreted in the same way
209 as a @code{display} text property.  @xref{Display Property}.
211 A line prefix may also be specified for regions of text using the
212 @code{line-prefix} text or overlay property.  This takes precedence
213 over the @code{line-prefix} variable.  @xref{Special Properties}.
214 @end defvar
216   If your buffer contains @emph{very} long lines, and you use
217 continuation to display them, computing the continuation lines can
218 make redisplay slow.  The column computation and indentation functions
219 also become slow.  Then you might find it advisable to set
220 @code{cache-long-line-scans} to @code{t}.
222 @defvar cache-long-line-scans
223 If this variable is non-@code{nil}, various indentation and motion
224 functions, and Emacs redisplay, cache the results of scanning the
225 buffer, and consult the cache to avoid rescanning regions of the buffer
226 unless they are modified.
228 Turning on the cache slows down processing of short lines somewhat.
230 This variable is automatically buffer-local in every buffer.
231 @end defvar
233 @node The Echo Area
234 @section The Echo Area
235 @cindex error display
236 @cindex echo area
238   The @dfn{echo area} is used for displaying error messages
239 (@pxref{Errors}), for messages made with the @code{message} primitive,
240 and for echoing keystrokes.  It is not the same as the minibuffer,
241 despite the fact that the minibuffer appears (when active) in the same
242 place on the screen as the echo area.  @xref{Minibuffer,, The
243 Minibuffer, emacs, The GNU Emacs Manual}.
245   Apart from the functions documented in this section, you can print
246 Lisp objects to the echo area by specifying @code{t} as the output
247 stream.  @xref{Output Streams}.
249 @menu
250 * Displaying Messages:: Explicitly displaying text in the echo area.
251 * Progress::            Informing user about progress of a long operation.
252 * Logging Messages::    Echo area messages are logged for the user.
253 * Echo Area Customization:: Controlling the echo area.
254 @end menu
256 @node Displaying Messages
257 @subsection Displaying Messages in the Echo Area
258 @cindex display message in echo area
260   This section describes the standard functions for displaying
261 messages in the echo area.
263 @defun message format-string &rest arguments
264 This function displays a message in the echo area.
265 @var{format-string} is a format string, and @var{arguments} are the
266 objects for its format specifications, like in the @code{format}
267 function (@pxref{Formatting Strings}).  The resulting formatted string
268 is displayed in the echo area; if it contains @code{face} text
269 properties, it is displayed with the specified faces (@pxref{Faces}).
270 The string is also added to the @file{*Messages*} buffer, but without
271 text properties (@pxref{Logging Messages}).
273 In batch mode, the message is printed to the standard error stream,
274 followed by a newline.
276 If @var{format-string} is @code{nil} or the empty string,
277 @code{message} clears the echo area; if the echo area has been
278 expanded automatically, this brings it back to its normal size.  If
279 the minibuffer is active, this brings the minibuffer contents back
280 onto the screen immediately.
282 @example
283 @group
284 (message "Minibuffer depth is %d."
285          (minibuffer-depth))
286  @print{} Minibuffer depth is 0.
287 @result{} "Minibuffer depth is 0."
288 @end group
290 @group
291 ---------- Echo Area ----------
292 Minibuffer depth is 0.
293 ---------- Echo Area ----------
294 @end group
295 @end example
297 To automatically display a message in the echo area or in a pop-buffer,
298 depending on its size, use @code{display-message-or-buffer} (see below).
299 @end defun
301 @defmac with-temp-message message &rest body
302 This construct displays a message in the echo area temporarily, during
303 the execution of @var{body}.  It displays @var{message}, executes
304 @var{body}, then returns the value of the last body form while restoring
305 the previous echo area contents.
306 @end defmac
308 @defun message-or-box format-string &rest arguments
309 This function displays a message like @code{message}, but may display it
310 in a dialog box instead of the echo area.  If this function is called in
311 a command that was invoked using the mouse---more precisely, if
312 @code{last-nonmenu-event} (@pxref{Command Loop Info}) is either
313 @code{nil} or a list---then it uses a dialog box or pop-up menu to
314 display the message.  Otherwise, it uses the echo area.  (This is the
315 same criterion that @code{y-or-n-p} uses to make a similar decision; see
316 @ref{Yes-or-No Queries}.)
318 You can force use of the mouse or of the echo area by binding
319 @code{last-nonmenu-event} to a suitable value around the call.
320 @end defun
322 @defun message-box format-string &rest arguments
323 @anchor{message-box}
324 This function displays a message like @code{message}, but uses a dialog
325 box (or a pop-up menu) whenever that is possible.  If it is impossible
326 to use a dialog box or pop-up menu, because the terminal does not
327 support them, then @code{message-box} uses the echo area, like
328 @code{message}.
329 @end defun
331 @defun display-message-or-buffer message &optional buffer-name not-this-window frame
332 This function displays the message @var{message}, which may be either a
333 string or a buffer.  If it is shorter than the maximum height of the
334 echo area, as defined by @code{max-mini-window-height}, it is displayed
335 in the echo area, using @code{message}.  Otherwise,
336 @code{display-buffer} is used to show it in a pop-up buffer.
338 Returns either the string shown in the echo area, or when a pop-up
339 buffer is used, the window used to display it.
341 If @var{message} is a string, then the optional argument
342 @var{buffer-name} is the name of the buffer used to display it when a
343 pop-up buffer is used, defaulting to @file{*Message*}.  In the case
344 where @var{message} is a string and displayed in the echo area, it is
345 not specified whether the contents are inserted into the buffer anyway.
347 The optional arguments @var{not-this-window} and @var{frame} are as for
348 @code{display-buffer}, and only used if a buffer is displayed.
349 @end defun
351 @defun current-message
352 This function returns the message currently being displayed in the
353 echo area, or @code{nil} if there is none.
354 @end defun
356 @node Progress
357 @subsection Reporting Operation Progress
358 @cindex progress reporting
360   When an operation can take a while to finish, you should inform the
361 user about the progress it makes.  This way the user can estimate
362 remaining time and clearly see that Emacs is busy working, not hung.
363 A convenient way to do this is to use a @dfn{progress reporter}.
365   Here is a working example that does nothing useful:
367 @smallexample
368 (let ((progress-reporter
369        (make-progress-reporter "Collecting mana for Emacs..."
370                                0  500)))
371   (dotimes (k 500)
372     (sit-for 0.01)
373     (progress-reporter-update progress-reporter k))
374   (progress-reporter-done progress-reporter))
375 @end smallexample
377 @defun make-progress-reporter message &optional min-value max-value current-value min-change min-time
378 This function creates and returns a progress reporter object, which
379 you will use as an argument for the other functions listed below.  The
380 idea is to precompute as much data as possible to make progress
381 reporting very fast.
383 When this progress reporter is subsequently used, it will display
384 @var{message} in the echo area, followed by progress percentage.
385 @var{message} is treated as a simple string.  If you need it to depend
386 on a filename, for instance, use @code{format} before calling this
387 function.
389 The arguments @var{min-value} and @var{max-value} should be numbers
390 standing for the starting and final states of the operation.  For
391 instance, an operation that ``scans'' a buffer should set these to the
392 results of @code{point-min} and @code{point-max} correspondingly.
393 @var{max-value} should be greater than @var{min-value}.
395 Alternatively, you can set @var{min-value} and @var{max-value} to
396 @code{nil}.  In that case, the progress reporter does not report
397 process percentages; it instead displays a ``spinner'' that rotates a
398 notch each time you update the progress reporter.
400 If @var{min-value} and @var{max-value} are numbers, you can give the
401 argument @var{current-value} a numerical value specifying the initial
402 progress; if omitted, this defaults to @var{min-value}.
404 The remaining arguments control the rate of echo area updates.  The
405 progress reporter will wait for at least @var{min-change} more
406 percents of the operation to be completed before printing next
407 message; the default is one percent.  @var{min-time} specifies the
408 minimum time in seconds to pass between successive prints; the default
409 is 0.2 seconds.  (On some operating systems, the progress reporter may
410 handle fractions of seconds with varying precision).
412 This function calls @code{progress-reporter-update}, so the first
413 message is printed immediately.
414 @end defun
416 @defun progress-reporter-update reporter &optional value
417 This function does the main work of reporting progress of your
418 operation.  It displays the message of @var{reporter}, followed by
419 progress percentage determined by @var{value}.  If percentage is zero,
420 or close enough according to the @var{min-change} and @var{min-time}
421 arguments, then it is omitted from the output.
423 @var{reporter} must be the result of a call to
424 @code{make-progress-reporter}.  @var{value} specifies the current
425 state of your operation and must be between @var{min-value} and
426 @var{max-value} (inclusive) as passed to
427 @code{make-progress-reporter}.  For instance, if you scan a buffer,
428 then @var{value} should be the result of a call to @code{point}.
430 This function respects @var{min-change} and @var{min-time} as passed
431 to @code{make-progress-reporter} and so does not output new messages
432 on every invocation.  It is thus very fast and normally you should not
433 try to reduce the number of calls to it: resulting overhead will most
434 likely negate your effort.
435 @end defun
437 @defun progress-reporter-force-update reporter &optional value new-message
438 This function is similar to @code{progress-reporter-update} except
439 that it prints a message in the echo area unconditionally.
441 The first two arguments have the same meaning as for
442 @code{progress-reporter-update}.  Optional @var{new-message} allows
443 you to change the message of the @var{reporter}.  Since this functions
444 always updates the echo area, such a change will be immediately
445 presented to the user.
446 @end defun
448 @defun progress-reporter-done reporter
449 This function should be called when the operation is finished.  It
450 prints the message of @var{reporter} followed by word ``done'' in the
451 echo area.
453 You should always call this function and not hope for
454 @code{progress-reporter-update} to print ``100%''.  Firstly, it may
455 never print it, there are many good reasons for this not to happen.
456 Secondly, ``done'' is more explicit.
457 @end defun
459 @defmac dotimes-with-progress-reporter (var count [result]) message body@dots{}
460 This is a convenience macro that works the same way as @code{dotimes}
461 does, but also reports loop progress using the functions described
462 above.  It allows you to save some typing.
464 You can rewrite the example in the beginning of this node using
465 this macro this way:
467 @example
468 (dotimes-with-progress-reporter
469     (k 500)
470     "Collecting some mana for Emacs..."
471   (sit-for 0.01))
472 @end example
473 @end defmac
475 @node Logging Messages
476 @subsection Logging Messages in @file{*Messages*}
477 @cindex logging echo-area messages
479   Almost all the messages displayed in the echo area are also recorded
480 in the @file{*Messages*} buffer so that the user can refer back to
481 them.  This includes all the messages that are output with
482 @code{message}.
484 @defopt message-log-max
485 This variable specifies how many lines to keep in the @file{*Messages*}
486 buffer.  The value @code{t} means there is no limit on how many lines to
487 keep.  The value @code{nil} disables message logging entirely.  Here's
488 how to display a message and prevent it from being logged:
490 @example
491 (let (message-log-max)
492   (message @dots{}))
493 @end example
494 @end defopt
496   To make @file{*Messages*} more convenient for the user, the logging
497 facility combines successive identical messages.  It also combines
498 successive related messages for the sake of two cases: question
499 followed by answer, and a series of progress messages.
501   A ``question followed by an answer'' means two messages like the
502 ones produced by @code{y-or-n-p}: the first is @samp{@var{question}},
503 and the second is @samp{@var{question}...@var{answer}}.  The first
504 message conveys no additional information beyond what's in the second,
505 so logging the second message discards the first from the log.
507   A ``series of progress messages'' means successive messages like
508 those produced by @code{make-progress-reporter}.  They have the form
509 @samp{@var{base}...@var{how-far}}, where @var{base} is the same each
510 time, while @var{how-far} varies.  Logging each message in the series
511 discards the previous one, provided they are consecutive.
513   The functions @code{make-progress-reporter} and @code{y-or-n-p}
514 don't have to do anything special to activate the message log
515 combination feature.  It operates whenever two consecutive messages
516 are logged that share a common prefix ending in @samp{...}.
518 @node Echo Area Customization
519 @subsection Echo Area Customization
521   These variables control details of how the echo area works.
523 @defvar cursor-in-echo-area
524 This variable controls where the cursor appears when a message is
525 displayed in the echo area.  If it is non-@code{nil}, then the cursor
526 appears at the end of the message.  Otherwise, the cursor appears at
527 point---not in the echo area at all.
529 The value is normally @code{nil}; Lisp programs bind it to @code{t}
530 for brief periods of time.
531 @end defvar
533 @defvar echo-area-clear-hook
534 This normal hook is run whenever the echo area is cleared---either by
535 @code{(message nil)} or for any other reason.
536 @end defvar
538 @defopt echo-keystrokes
539 This variable determines how much time should elapse before command
540 characters echo.  Its value must be an integer or floating point number,
541 which specifies the
542 number of seconds to wait before echoing.  If the user types a prefix
543 key (such as @kbd{C-x}) and then delays this many seconds before
544 continuing, the prefix key is echoed in the echo area.  (Once echoing
545 begins in a key sequence, all subsequent characters in the same key
546 sequence are echoed immediately.)
548 If the value is zero, then command input is not echoed.
549 @end defopt
551 @defvar message-truncate-lines
552 Normally, displaying a long message resizes the echo area to display
553 the entire message.  But if the variable @code{message-truncate-lines}
554 is non-@code{nil}, the echo area does not resize, and the message is
555 truncated to fit it.
556 @end defvar
558   The variable @code{max-mini-window-height}, which specifies the
559 maximum height for resizing minibuffer windows, also applies to the
560 echo area (which is really a special use of the minibuffer window;
561 @pxref{Minibuffer Misc}).
563 @node Warnings
564 @section Reporting Warnings
565 @cindex warnings
567   @dfn{Warnings} are a facility for a program to inform the user of a
568 possible problem, but continue running.
570 @menu
571 * Warning Basics::      Warnings concepts and functions to report them.
572 * Warning Variables::   Variables programs bind to customize their warnings.
573 * Warning Options::     Variables users set to control display of warnings.
574 * Delayed Warnings::    Deferring a warning until the end of a command.
575 @end menu
577 @node Warning Basics
578 @subsection Warning Basics
579 @cindex severity level
581   Every warning has a textual message, which explains the problem for
582 the user, and a @dfn{severity level} which is a symbol.  Here are the
583 possible severity levels, in order of decreasing severity, and their
584 meanings:
586 @table @code
587 @item :emergency
588 A problem that will seriously impair Emacs operation soon
589 if you do not attend to it promptly.
590 @item :error
591 A report of data or circumstances that are inherently wrong.
592 @item :warning
593 A report of data or circumstances that are not inherently wrong, but
594 raise suspicion of a possible problem.
595 @item :debug
596 A report of information that may be useful if you are debugging.
597 @end table
599   When your program encounters invalid input data, it can either
600 signal a Lisp error by calling @code{error} or @code{signal} or report
601 a warning with severity @code{:error}.  Signaling a Lisp error is the
602 easiest thing to do, but it means the program cannot continue
603 processing.  If you want to take the trouble to implement a way to
604 continue processing despite the bad data, then reporting a warning of
605 severity @code{:error} is the right way to inform the user of the
606 problem.  For instance, the Emacs Lisp byte compiler can report an
607 error that way and continue compiling other functions.  (If the
608 program signals a Lisp error and then handles it with
609 @code{condition-case}, the user won't see the error message; it could
610 show the message to the user by reporting it as a warning.)
612 @cindex warning type
613   Each warning has a @dfn{warning type} to classify it.  The type is a
614 list of symbols.  The first symbol should be the custom group that you
615 use for the program's user options.  For example, byte compiler
616 warnings use the warning type @code{(bytecomp)}.  You can also
617 subcategorize the warnings, if you wish, by using more symbols in the
618 list.
620 @defun display-warning type message &optional level buffer-name
621 This function reports a warning, using @var{message} as the message
622 and @var{type} as the warning type.  @var{level} should be the
623 severity level, with @code{:warning} being the default.
625 @var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
626 for logging the warning.  By default, it is @file{*Warnings*}.
627 @end defun
629 @defun lwarn type level message &rest args
630 This function reports a warning using the value of @code{(format
631 @var{message} @var{args}...)} as the message.  In other respects it is
632 equivalent to @code{display-warning}.
633 @end defun
635 @defun warn message &rest args
636 This function reports a warning using the value of @code{(format
637 @var{message} @var{args}...)} as the message, @code{(emacs)} as the
638 type, and @code{:warning} as the severity level.  It exists for
639 compatibility only; we recommend not using it, because you should
640 specify a specific warning type.
641 @end defun
643 @node Warning Variables
644 @subsection Warning Variables
646   Programs can customize how their warnings appear by binding
647 the variables described in this section.
649 @defvar warning-levels
650 This list defines the meaning and severity order of the warning
651 severity levels.  Each element defines one severity level,
652 and they are arranged in order of decreasing severity.
654 Each element has the form @code{(@var{level} @var{string}
655 @var{function})}, where @var{level} is the severity level it defines.
656 @var{string} specifies the textual description of this level.
657 @var{string} should use @samp{%s} to specify where to put the warning
658 type information, or it can omit the @samp{%s} so as not to include
659 that information.
661 The optional @var{function}, if non-@code{nil}, is a function to call
662 with no arguments, to get the user's attention.
664 Normally you should not change the value of this variable.
665 @end defvar
667 @defvar warning-prefix-function
668 If non-@code{nil}, the value is a function to generate prefix text for
669 warnings.  Programs can bind the variable to a suitable function.
670 @code{display-warning} calls this function with the warnings buffer
671 current, and the function can insert text in it.  That text becomes
672 the beginning of the warning message.
674 The function is called with two arguments, the severity level and its
675 entry in @code{warning-levels}.  It should return a list to use as the
676 entry (this value need not be an actual member of
677 @code{warning-levels}).  By constructing this value, the function can
678 change the severity of the warning, or specify different handling for
679 a given severity level.
681 If the variable's value is @code{nil} then there is no function
682 to call.
683 @end defvar
685 @defvar warning-series
686 Programs can bind this variable to @code{t} to say that the next
687 warning should begin a series.  When several warnings form a series,
688 that means to leave point on the first warning of the series, rather
689 than keep moving it for each warning so that it appears on the last one.
690 The series ends when the local binding is unbound and
691 @code{warning-series} becomes @code{nil} again.
693 The value can also be a symbol with a function definition.  That is
694 equivalent to @code{t}, except that the next warning will also call
695 the function with no arguments with the warnings buffer current.  The
696 function can insert text which will serve as a header for the series
697 of warnings.
699 Once a series has begun, the value is a marker which points to the
700 buffer position in the warnings buffer of the start of the series.
702 The variable's normal value is @code{nil}, which means to handle
703 each warning separately.
704 @end defvar
706 @defvar warning-fill-prefix
707 When this variable is non-@code{nil}, it specifies a fill prefix to
708 use for filling each warning's text.
709 @end defvar
711 @defvar warning-type-format
712 This variable specifies the format for displaying the warning type
713 in the warning message.  The result of formatting the type this way
714 gets included in the message under the control of the string in the
715 entry in @code{warning-levels}.  The default value is @code{" (%s)"}.
716 If you bind it to @code{""} then the warning type won't appear at
717 all.
718 @end defvar
720 @node Warning Options
721 @subsection Warning Options
723   These variables are used by users to control what happens
724 when a Lisp program reports a warning.
726 @defopt warning-minimum-level
727 This user option specifies the minimum severity level that should be
728 shown immediately to the user.  The default is @code{:warning}, which
729 means to immediately display all warnings except @code{:debug}
730 warnings.
731 @end defopt
733 @defopt warning-minimum-log-level
734 This user option specifies the minimum severity level that should be
735 logged in the warnings buffer.  The default is @code{:warning}, which
736 means to log all warnings except @code{:debug} warnings.
737 @end defopt
739 @defopt warning-suppress-types
740 This list specifies which warning types should not be displayed
741 immediately for the user.  Each element of the list should be a list
742 of symbols.  If its elements match the first elements in a warning
743 type, then that warning is not displayed immediately.
744 @end defopt
746 @defopt warning-suppress-log-types
747 This list specifies which warning types should not be logged in the
748 warnings buffer.  Each element of the list should be a list of
749 symbols.  If it matches the first few elements in a warning type, then
750 that warning is not logged.
751 @end defopt
753 @node Delayed Warnings
754 @subsection Delayed Warnings
756 Sometimes, you may wish to avoid showing a warning while a command is
757 running, and only show it only after the end of the command.  You can
758 use the variable @code{delayed-warnings-list} for this.
760 @defvar delayed-warnings-list
761 The value of this variable is a list of warnings to be displayed after
762 the current command has finished.  Each element must be a list
764 @smallexample
765 (@var{type} @var{message} [@var{level} [@var{buffer-name}]])
766 @end smallexample
768 @noindent
769 with the same form, and the same meanings, as the argument list of
770 @code{display-warning} (@pxref{Warning Basics}).  Immediately after
771 running @code{post-command-hook} (@pxref{Command Overview}), the Emacs
772 command loop displays all the warnings specified by this variable,
773 then resets it to @code{nil}.
774 @end defvar
776   Programs which need to further customize the delayed warnings
777 mechanism can change the variable @code{delayed-warnings-hook}:
779 @defvar delayed-warnings-hook
780 This is a normal hook which is run by the Emacs command loop, after
781 @code{post-command-hook}, in order to to process and display delayed
782 warnings.
784 Its default value is a list of two functions:
786 @smallexample
787 (collapse-delayed-warnings display-delayed-warnings)
788 @end smallexample
790 @findex collapse-delayed-warnings
791 @findex display-delayed-warnings
792 @noindent
793 The function @code{collapse-delayed-warnings} removes repeated entries
794 from @code{delayed-warnings-list}.  The function
795 @code{display-delayed-warnings} calls @code{display-warning} on each
796 of the entries in @code{delayed-warnings-list}, in turn, and then sets
797 @code{delayed-warnings-list} to @code{nil}.
798 @end defvar
800 @node Invisible Text
801 @section Invisible Text
803 @cindex invisible text
804 You can make characters @dfn{invisible}, so that they do not appear on
805 the screen, with the @code{invisible} property.  This can be either a
806 text property (@pxref{Text Properties}) or an overlay property
807 (@pxref{Overlays}).  Cursor motion also partly ignores these
808 characters; if the command loop finds that point is inside a range of
809 invisible text after a command, it relocates point to the other side
810 of the text.
812 In the simplest case, any non-@code{nil} @code{invisible} property makes
813 a character invisible.  This is the default case---if you don't alter
814 the default value of @code{buffer-invisibility-spec}, this is how the
815 @code{invisible} property works.  You should normally use @code{t}
816 as the value of the @code{invisible} property if you don't plan
817 to set @code{buffer-invisibility-spec} yourself.
819 More generally, you can use the variable @code{buffer-invisibility-spec}
820 to control which values of the @code{invisible} property make text
821 invisible.  This permits you to classify the text into different subsets
822 in advance, by giving them different @code{invisible} values, and
823 subsequently make various subsets visible or invisible by changing the
824 value of @code{buffer-invisibility-spec}.
826 Controlling visibility with @code{buffer-invisibility-spec} is
827 especially useful in a program to display the list of entries in a
828 database.  It permits the implementation of convenient filtering
829 commands to view just a part of the entries in the database.  Setting
830 this variable is very fast, much faster than scanning all the text in
831 the buffer looking for properties to change.
833 @defvar buffer-invisibility-spec
834 This variable specifies which kinds of @code{invisible} properties
835 actually make a character invisible.  Setting this variable makes it
836 buffer-local.
838 @table @asis
839 @item @code{t}
840 A character is invisible if its @code{invisible} property is
841 non-@code{nil}.  This is the default.
843 @item a list
844 Each element of the list specifies a criterion for invisibility; if a
845 character's @code{invisible} property fits any one of these criteria,
846 the character is invisible.  The list can have two kinds of elements:
848 @table @code
849 @item @var{atom}
850 A character is invisible if its @code{invisible} property value is
851 @var{atom} or if it is a list with @var{atom} as a member; comparison
852 is done with @code{eq}.
854 @item (@var{atom} . t)
855 A character is invisible if its @code{invisible} property value is
856 @var{atom} or if it is a list with @var{atom} as a member; comparison
857 is done with @code{eq}.  Moreover, a sequence of such characters
858 displays as an ellipsis.
859 @end table
860 @end table
861 @end defvar
863   Two functions are specifically provided for adding elements to
864 @code{buffer-invisibility-spec} and removing elements from it.
866 @defun add-to-invisibility-spec element
867 This function adds the element @var{element} to
868 @code{buffer-invisibility-spec}.  If @code{buffer-invisibility-spec}
869 was @code{t}, it changes to a list, @code{(t)}, so that text whose
870 @code{invisible} property is @code{t} remains invisible.
871 @end defun
873 @defun remove-from-invisibility-spec element
874 This removes the element @var{element} from
875 @code{buffer-invisibility-spec}.  This does nothing if @var{element}
876 is not in the list.
877 @end defun
879   A convention for use of @code{buffer-invisibility-spec} is that a
880 major mode should use the mode's own name as an element of
881 @code{buffer-invisibility-spec} and as the value of the
882 @code{invisible} property:
884 @example
885 ;; @r{If you want to display an ellipsis:}
886 (add-to-invisibility-spec '(my-symbol . t))
887 ;; @r{If you don't want ellipsis:}
888 (add-to-invisibility-spec 'my-symbol)
890 (overlay-put (make-overlay beginning end)
891              'invisible 'my-symbol)
893 ;; @r{When done with the invisibility:}
894 (remove-from-invisibility-spec '(my-symbol . t))
895 ;; @r{Or respectively:}
896 (remove-from-invisibility-spec 'my-symbol)
897 @end example
899   You can check for invisibility using the following function:
901 @defun invisible-p pos-or-prop
902 If @var{pos-or-prop} is a marker or number, this function returns a
903 non-@code{nil} value if the text at that position is invisible.
905 If @var{pos-or-prop} is any other kind of Lisp object, that is taken
906 to mean a possible value of the @code{invisible} text or overlay
907 property.  In that case, this function returns a non-@code{nil} value
908 if that value would cause text to become invisible, based on the
909 current value of @code{buffer-invisibility-spec}.
910 @end defun
912 @vindex line-move-ignore-invisible
913   Ordinarily, functions that operate on text or move point do not care
914 whether the text is invisible.  The user-level line motion commands
915 ignore invisible newlines if @code{line-move-ignore-invisible} is
916 non-@code{nil} (the default), but only because they are explicitly
917 programmed to do so.
919   However, if a command ends with point inside or at the boundary of
920 invisible text, the main editing loop relocates point to one of the
921 two ends of the invisible text.  Emacs chooses the direction of
922 relocation so that it is the same as the overall movement direction of
923 the command; if in doubt, it prefers a position where an inserted char
924 would not inherit the @code{invisible} property.  Additionally, if the
925 text is not replaced by an ellipsis and the command only moved within
926 the invisible text, then point is moved one extra character so as to
927 try and reflect the command's movement by a visible movement of the
928 cursor.
930   Thus, if the command moved point back to an invisible range (with the usual
931 stickiness), Emacs moves point back to the beginning of that range.  If the
932 command moved point forward into an invisible range, Emacs moves point forward
933 to the first visible character that follows the invisible text and then forward
934 one more character.
936   Incremental search can make invisible overlays visible temporarily
937 and/or permanently when a match includes invisible text.  To enable
938 this, the overlay should have a non-@code{nil}
939 @code{isearch-open-invisible} property.  The property value should be a
940 function to be called with the overlay as an argument.  This function
941 should make the overlay visible permanently; it is used when the match
942 overlaps the overlay on exit from the search.
944   During the search, such overlays are made temporarily visible by
945 temporarily modifying their invisible and intangible properties.  If you
946 want this to be done differently for a certain overlay, give it an
947 @code{isearch-open-invisible-temporary} property which is a function.
948 The function is called with two arguments: the first is the overlay, and
949 the second is @code{nil} to make the overlay visible, or @code{t} to
950 make it invisible again.
952 @node Selective Display
953 @section Selective Display
954 @c @cindex selective display   Duplicates selective-display
956   @dfn{Selective display} refers to a pair of related features for
957 hiding certain lines on the screen.
959   The first variant, explicit selective display, is designed for use
960 in a Lisp program: it controls which lines are hidden by altering the
961 text.  This kind of hiding in some ways resembles the effect of the
962 @code{invisible} property (@pxref{Invisible Text}), but the two
963 features are different and do not work the same way.
965   In the second variant, the choice of lines to hide is made
966 automatically based on indentation.  This variant is designed to be a
967 user-level feature.
969   The way you control explicit selective display is by replacing a
970 newline (control-j) with a carriage return (control-m).  The text that
971 was formerly a line following that newline is now hidden.  Strictly
972 speaking, it is temporarily no longer a line at all, since only
973 newlines can separate lines; it is now part of the previous line.
975   Selective display does not directly affect editing commands.  For
976 example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly
977 into hidden text.  However, the replacement of newline characters with
978 carriage return characters affects some editing commands.  For
979 example, @code{next-line} skips hidden lines, since it searches only
980 for newlines.  Modes that use selective display can also define
981 commands that take account of the newlines, or that control which
982 parts of the text are hidden.
984   When you write a selectively displayed buffer into a file, all the
985 control-m's are output as newlines.  This means that when you next read
986 in the file, it looks OK, with nothing hidden.  The selective display
987 effect is seen only within Emacs.
989 @defvar selective-display
990 This buffer-local variable enables selective display.  This means that
991 lines, or portions of lines, may be made hidden.
993 @itemize @bullet
994 @item
995 If the value of @code{selective-display} is @code{t}, then the character
996 control-m marks the start of hidden text; the control-m, and the rest
997 of the line following it, are not displayed.  This is explicit selective
998 display.
1000 @item
1001 If the value of @code{selective-display} is a positive integer, then
1002 lines that start with more than that many columns of indentation are not
1003 displayed.
1004 @end itemize
1006 When some portion of a buffer is hidden, the vertical movement
1007 commands operate as if that portion did not exist, allowing a single
1008 @code{next-line} command to skip any number of hidden lines.
1009 However, character movement commands (such as @code{forward-char}) do
1010 not skip the hidden portion, and it is possible (if tricky) to insert
1011 or delete text in an hidden portion.
1013 In the examples below, we show the @emph{display appearance} of the
1014 buffer @code{foo}, which changes with the value of
1015 @code{selective-display}.  The @emph{contents} of the buffer do not
1016 change.
1018 @example
1019 @group
1020 (setq selective-display nil)
1021      @result{} nil
1023 ---------- Buffer: foo ----------
1024 1 on this column
1025  2on this column
1026   3n this column
1027   3n this column
1028  2on this column
1029 1 on this column
1030 ---------- Buffer: foo ----------
1031 @end group
1033 @group
1034 (setq selective-display 2)
1035      @result{} 2
1037 ---------- Buffer: foo ----------
1038 1 on this column
1039  2on this column
1040  2on this column
1041 1 on this column
1042 ---------- Buffer: foo ----------
1043 @end group
1044 @end example
1045 @end defvar
1047 @defopt selective-display-ellipses
1048 If this buffer-local variable is non-@code{nil}, then Emacs displays
1049 @samp{@dots{}} at the end of a line that is followed by hidden text.
1050 This example is a continuation of the previous one.
1052 @example
1053 @group
1054 (setq selective-display-ellipses t)
1055      @result{} t
1057 ---------- Buffer: foo ----------
1058 1 on this column
1059  2on this column ...
1060  2on this column
1061 1 on this column
1062 ---------- Buffer: foo ----------
1063 @end group
1064 @end example
1066 You can use a display table to substitute other text for the ellipsis
1067 (@samp{@dots{}}).  @xref{Display Tables}.
1068 @end defopt
1070 @node Temporary Displays
1071 @section Temporary Displays
1073   Temporary displays are used by Lisp programs to put output into a
1074 buffer and then present it to the user for perusal rather than for
1075 editing.  Many help commands use this feature.
1077 @defmac with-output-to-temp-buffer buffer-name forms@dots{}
1078 This function executes @var{forms} while arranging to insert any output
1079 they print into the buffer named @var{buffer-name}, which is first
1080 created if necessary, and put into Help mode.  Finally, the buffer is
1081 displayed in some window, but not selected.  (See the similar
1082 form @code{with-temp-buffer-window} below.)
1084 If the @var{forms} do not change the major mode in the output buffer,
1085 so that it is still Help mode at the end of their execution, then
1086 @code{with-output-to-temp-buffer} makes this buffer read-only at the
1087 end, and also scans it for function and variable names to make them
1088 into clickable cross-references.  @xref{Docstring hyperlinks, , Tips
1089 for Documentation Strings}, in particular the item on hyperlinks in
1090 documentation strings, for more details.
1092 The string @var{buffer-name} specifies the temporary buffer, which
1093 need not already exist.  The argument must be a string, not a buffer.
1094 The buffer is erased initially (with no questions asked), and it is
1095 marked as unmodified after @code{with-output-to-temp-buffer} exits.
1097 @code{with-output-to-temp-buffer} binds @code{standard-output} to the
1098 temporary buffer, then it evaluates the forms in @var{forms}.  Output
1099 using the Lisp output functions within @var{forms} goes by default to
1100 that buffer (but screen display and messages in the echo area, although
1101 they are ``output'' in the general sense of the word, are not affected).
1102 @xref{Output Functions}.
1104 Several hooks are available for customizing the behavior
1105 of this construct; they are listed below.
1107 The value of the last form in @var{forms} is returned.
1109 @example
1110 @group
1111 ---------- Buffer: foo ----------
1112  This is the contents of foo.
1113 ---------- Buffer: foo ----------
1114 @end group
1116 @group
1117 (with-output-to-temp-buffer "foo"
1118     (print 20)
1119     (print standard-output))
1120 @result{} #<buffer foo>
1122 ---------- Buffer: foo ----------
1125 #<buffer foo>
1127 ---------- Buffer: foo ----------
1128 @end group
1129 @end example
1130 @end defmac
1132 @defopt temp-buffer-show-function
1133 If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
1134 calls it as a function to do the job of displaying a help buffer.  The
1135 function gets one argument, which is the buffer it should display.
1137 It is a good idea for this function to run @code{temp-buffer-show-hook}
1138 just as @code{with-output-to-temp-buffer} normally would, inside of
1139 @code{save-selected-window} and with the chosen window and buffer
1140 selected.
1141 @end defopt
1143 @defvar temp-buffer-setup-hook
1144 This normal hook is run by @code{with-output-to-temp-buffer} before
1145 evaluating @var{body}.  When the hook runs, the temporary buffer is
1146 current.  This hook is normally set up with a function to put the
1147 buffer in Help mode.
1148 @end defvar
1150 @defvar temp-buffer-show-hook
1151 This normal hook is run by @code{with-output-to-temp-buffer} after
1152 displaying the temporary buffer.  When the hook runs, the temporary buffer
1153 is current, and the window it was displayed in is selected.
1154 @end defvar
1156 @defmac with-temp-buffer-window buffer-or-name action quit-function forms@dots{}
1157 This macro is similar to @code{with-output-to-temp-buffer}.
1158 Like that construct, it executes @var{forms} while arranging to insert
1159 any output they print into the buffer named @var{buffer-or-name}.
1160 Finally, the buffer is displayed in some window, but not selected.
1161 Unlike @code{with-output-to-temp-buffer}, this does not switch to Help
1162 mode.
1164 The argument @var{buffer-or-name} specifies the temporary buffer.
1165 It can be either a buffer, which must already exist, or a string,
1166 in which case a buffer of that name is created if necessary.
1167 The buffer is marked as unmodified and read-only when
1168 @code{with-temp-buffer-window} exits.
1170 This macro does not call @code{temp-buffer-show-function}.  Rather, it
1171 passes the @var{action} argument to @code{display-buffer} in order to
1172 display the buffer.
1174 The value of the last form in @var{forms} is returned, unless the
1175 argument @var{quit-function} is specified.  In that case,
1176 it is called with two arguments: the window showing the buffer
1177 and the result of @var{forms}.  The final return value is then
1178 whatever @var{quit-function} returns.
1180 @vindex temp-buffer-window-setup-hook
1181 @vindex temp-buffer-window-show-hook
1182 This macro uses the normal hooks @code{temp-buffer-window-setup-hook}
1183 and @code{temp-buffer-window-show-hook} in place of the analogous hooks
1184 run by @code{with-output-to-temp-buffer}.
1185 @end defmac
1187 @defun momentary-string-display string position &optional char message
1188 This function momentarily displays @var{string} in the current buffer at
1189 @var{position}.  It has no effect on the undo list or on the buffer's
1190 modification status.
1192 The momentary display remains until the next input event.  If the next
1193 input event is @var{char}, @code{momentary-string-display} ignores it
1194 and returns.  Otherwise, that event remains buffered for subsequent use
1195 as input.  Thus, typing @var{char} will simply remove the string from
1196 the display, while typing (say) @kbd{C-f} will remove the string from
1197 the display and later (presumably) move point forward.  The argument
1198 @var{char} is a space by default.
1200 The return value of @code{momentary-string-display} is not meaningful.
1202 If the string @var{string} does not contain control characters, you can
1203 do the same job in a more general way by creating (and then subsequently
1204 deleting) an overlay with a @code{before-string} property.
1205 @xref{Overlay Properties}.
1207 If @var{message} is non-@code{nil}, it is displayed in the echo area
1208 while @var{string} is displayed in the buffer.  If it is @code{nil}, a
1209 default message says to type @var{char} to continue.
1211 In this example, point is initially located at the beginning of the
1212 second line:
1214 @example
1215 @group
1216 ---------- Buffer: foo ----------
1217 This is the contents of foo.
1218 @point{}Second line.
1219 ---------- Buffer: foo ----------
1220 @end group
1222 @group
1223 (momentary-string-display
1224   "**** Important Message! ****"
1225   (point) ?\r
1226   "Type RET when done reading")
1227 @result{} t
1228 @end group
1230 @group
1231 ---------- Buffer: foo ----------
1232 This is the contents of foo.
1233 **** Important Message! ****Second line.
1234 ---------- Buffer: foo ----------
1236 ---------- Echo Area ----------
1237 Type RET when done reading
1238 ---------- Echo Area ----------
1239 @end group
1240 @end example
1241 @end defun
1243 @node Overlays
1244 @section Overlays
1245 @cindex overlays
1247 You can use @dfn{overlays} to alter the appearance of a buffer's text on
1248 the screen, for the sake of presentation features.  An overlay is an
1249 object that belongs to a particular buffer, and has a specified
1250 beginning and end.  It also has properties that you can examine and set;
1251 these affect the display of the text within the overlay.
1253 @cindex scalability of overlays
1254 The visual effect of an overlay is the same as of the corresponding
1255 text property (@pxref{Text Properties}).  However, due to a different
1256 implementation, overlays generally don't scale well (many operations
1257 take a time that is proportional to the number of overlays in the
1258 buffer).  If you need to affect the visual appearance of many portions
1259 in the buffer, we recommend using text properties.
1261 An overlay uses markers to record its beginning and end; thus,
1262 editing the text of the buffer adjusts the beginning and end of each
1263 overlay so that it stays with the text.  When you create the overlay,
1264 you can specify whether text inserted at the beginning should be
1265 inside the overlay or outside, and likewise for the end of the overlay.
1267 @menu
1268 * Managing Overlays::   Creating and moving overlays.
1269 * Overlay Properties::  How to read and set properties.
1270                           What properties do to the screen display.
1271 * Finding Overlays::    Searching for overlays.
1272 @end menu
1274 @node Managing Overlays
1275 @subsection Managing Overlays
1277   This section describes the functions to create, delete and move
1278 overlays, and to examine their contents.  Overlay changes are not
1279 recorded in the buffer's undo list, since the overlays are not
1280 part of the buffer's contents.
1282 @defun overlayp object
1283 This function returns @code{t} if @var{object} is an overlay.
1284 @end defun
1286 @defun make-overlay start end &optional buffer front-advance rear-advance
1287 This function creates and returns an overlay that belongs to
1288 @var{buffer} and ranges from @var{start} to @var{end}.  Both @var{start}
1289 and @var{end} must specify buffer positions; they may be integers or
1290 markers.  If @var{buffer} is omitted, the overlay is created in the
1291 current buffer.
1293 The arguments @var{front-advance} and @var{rear-advance} specify the
1294 marker insertion type for the start of the overlay and for the end of
1295 the overlay, respectively.  @xref{Marker Insertion Types}.  If they
1296 are both @code{nil}, the default, then the overlay extends to include
1297 any text inserted at the beginning, but not text inserted at the end.
1298 If @var{front-advance} is non-@code{nil}, text inserted at the
1299 beginning of the overlay is excluded from the overlay.  If
1300 @var{rear-advance} is non-@code{nil}, text inserted at the end of the
1301 overlay is included in the overlay.
1302 @end defun
1304 @defun overlay-start overlay
1305 This function returns the position at which @var{overlay} starts,
1306 as an integer.
1307 @end defun
1309 @defun overlay-end overlay
1310 This function returns the position at which @var{overlay} ends,
1311 as an integer.
1312 @end defun
1314 @defun overlay-buffer overlay
1315 This function returns the buffer that @var{overlay} belongs to.  It
1316 returns @code{nil} if @var{overlay} has been deleted.
1317 @end defun
1319 @defun delete-overlay overlay
1320 This function deletes @var{overlay}.  The overlay continues to exist as
1321 a Lisp object, and its property list is unchanged, but it ceases to be
1322 attached to the buffer it belonged to, and ceases to have any effect on
1323 display.
1325 A deleted overlay is not permanently disconnected.  You can give it a
1326 position in a buffer again by calling @code{move-overlay}.
1327 @end defun
1329 @defun move-overlay overlay start end &optional buffer
1330 This function moves @var{overlay} to @var{buffer}, and places its bounds
1331 at @var{start} and @var{end}.  Both arguments @var{start} and @var{end}
1332 must specify buffer positions; they may be integers or markers.
1334 If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
1335 was already associated with; if @var{overlay} was deleted, it goes into
1336 the current buffer.
1338 The return value is @var{overlay}.
1340 This is the only valid way to change the endpoints of an overlay.  Do
1341 not try modifying the markers in the overlay by hand, as that fails to
1342 update other vital data structures and can cause some overlays to be
1343 ``lost''.
1344 @end defun
1346 @defun remove-overlays &optional start end name value
1347 This function removes all the overlays between @var{start} and
1348 @var{end} whose property @var{name} has the value @var{value}.  It can
1349 move the endpoints of the overlays in the region, or split them.
1351 If @var{name} is omitted or @code{nil}, it means to delete all overlays in
1352 the specified region.  If @var{start} and/or @var{end} are omitted or
1353 @code{nil}, that means the beginning and end of the buffer respectively.
1354 Therefore, @code{(remove-overlays)} removes all the overlays in the
1355 current buffer.
1356 @end defun
1358 @defun copy-overlay overlay
1359 This function returns a copy of @var{overlay}.  The copy has the same
1360 endpoints and properties as @var{overlay}.  However, the marker
1361 insertion type for the start of the overlay and for the end of the
1362 overlay are set to their default values (@pxref{Marker Insertion
1363 Types}).
1364 @end defun
1366   Here are some examples:
1368 @example
1369 ;; @r{Create an overlay.}
1370 (setq foo (make-overlay 1 10))
1371      @result{} #<overlay from 1 to 10 in display.texi>
1372 (overlay-start foo)
1373      @result{} 1
1374 (overlay-end foo)
1375      @result{} 10
1376 (overlay-buffer foo)
1377      @result{} #<buffer display.texi>
1378 ;; @r{Give it a property we can check later.}
1379 (overlay-put foo 'happy t)
1380      @result{} t
1381 ;; @r{Verify the property is present.}
1382 (overlay-get foo 'happy)
1383      @result{} t
1384 ;; @r{Move the overlay.}
1385 (move-overlay foo 5 20)
1386      @result{} #<overlay from 5 to 20 in display.texi>
1387 (overlay-start foo)
1388      @result{} 5
1389 (overlay-end foo)
1390      @result{} 20
1391 ;; @r{Delete the overlay.}
1392 (delete-overlay foo)
1393      @result{} nil
1394 ;; @r{Verify it is deleted.}
1396      @result{} #<overlay in no buffer>
1397 ;; @r{A deleted overlay has no position.}
1398 (overlay-start foo)
1399      @result{} nil
1400 (overlay-end foo)
1401      @result{} nil
1402 (overlay-buffer foo)
1403      @result{} nil
1404 ;; @r{Undelete the overlay.}
1405 (move-overlay foo 1 20)
1406      @result{} #<overlay from 1 to 20 in display.texi>
1407 ;; @r{Verify the results.}
1408 (overlay-start foo)
1409      @result{} 1
1410 (overlay-end foo)
1411      @result{} 20
1412 (overlay-buffer foo)
1413      @result{} #<buffer display.texi>
1414 ;; @r{Moving and deleting the overlay does not change its properties.}
1415 (overlay-get foo 'happy)
1416      @result{} t
1417 @end example
1419   Emacs stores the overlays of each buffer in two lists, divided
1420 around an arbitrary ``center position''.  One list extends backwards
1421 through the buffer from that center position, and the other extends
1422 forwards from that center position.  The center position can be anywhere
1423 in the buffer.
1425 @defun overlay-recenter pos
1426 This function recenters the overlays of the current buffer around
1427 position @var{pos}.  That makes overlay lookup faster for positions
1428 near @var{pos}, but slower for positions far away from @var{pos}.
1429 @end defun
1431   A loop that scans the buffer forwards, creating overlays, can run
1432 faster if you do @code{(overlay-recenter (point-max))} first.
1434 @node Overlay Properties
1435 @subsection Overlay Properties
1437   Overlay properties are like text properties in that the properties that
1438 alter how a character is displayed can come from either source.  But in
1439 most respects they are different.  @xref{Text Properties}, for comparison.
1441   Text properties are considered a part of the text; overlays and
1442 their properties are specifically considered not to be part of the
1443 text.  Thus, copying text between various buffers and strings
1444 preserves text properties, but does not try to preserve overlays.
1445 Changing a buffer's text properties marks the buffer as modified,
1446 while moving an overlay or changing its properties does not.  Unlike
1447 text property changes, overlay property changes are not recorded in
1448 the buffer's undo list.
1450   Since more than one overlay can specify a property value for the
1451 same character, Emacs lets you specify a priority value of each
1452 overlay.  You should not make assumptions about which overlay will
1453 prevail when there is a conflict and they have the same priority.
1455   These functions read and set the properties of an overlay:
1457 @defun overlay-get overlay prop
1458 This function returns the value of property @var{prop} recorded in
1459 @var{overlay}, if any.  If @var{overlay} does not record any value for
1460 that property, but it does have a @code{category} property which is a
1461 symbol, that symbol's @var{prop} property is used.  Otherwise, the value
1462 is @code{nil}.
1463 @end defun
1465 @defun overlay-put overlay prop value
1466 This function sets the value of property @var{prop} recorded in
1467 @var{overlay} to @var{value}.  It returns @var{value}.
1468 @end defun
1470 @defun overlay-properties overlay
1471 This returns a copy of the property list of @var{overlay}.
1472 @end defun
1474   See also the function @code{get-char-property} which checks both
1475 overlay properties and text properties for a given character.
1476 @xref{Examining Properties}.
1478   Many overlay properties have special meanings; here is a table
1479 of them:
1481 @table @code
1482 @item priority
1483 @kindex priority @r{(overlay property)}
1484 This property's value (which should be a non-negative integer number)
1485 determines the priority of the overlay.  No priority, or @code{nil},
1486 means zero.
1488 The priority matters when two or more overlays cover the same
1489 character and both specify the same property; the one whose
1490 @code{priority} value is larger overrides the other.  For the
1491 @code{face} property, the higher priority overlay's value does not
1492 completely override the other value; instead, its face attributes
1493 override the face attributes of the lower priority @code{face}
1494 property.
1496 Currently, all overlays take priority over text properties.  Please
1497 avoid using negative priority values, as we have not yet decided just
1498 what they should mean.
1500 @item window
1501 @kindex window @r{(overlay property)}
1502 If the @code{window} property is non-@code{nil}, then the overlay
1503 applies only on that window.
1505 @item category
1506 @kindex category @r{(overlay property)}
1507 If an overlay has a @code{category} property, we call it the
1508 @dfn{category} of the overlay.  It should be a symbol.  The properties
1509 of the symbol serve as defaults for the properties of the overlay.
1511 @item face
1512 @kindex face @r{(overlay property)}
1513 This property controls the way text is displayed---for example, which
1514 font and which colors.  @xref{Faces}, for more information.
1516 In the simplest case, the value is a face name.  It can also be a list;
1517 then each element can be any of these possibilities:
1519 @itemize @bullet
1520 @item
1521 A face name (a symbol or string).
1523 @item
1524 A property list of face attributes.  This has the form (@var{keyword}
1525 @var{value} @dots{}), where each @var{keyword} is a face attribute
1526 name and @var{value} is a meaningful value for that attribute.  With
1527 this feature, you do not need to create a face each time you want to
1528 specify a particular attribute for certain text.  @xref{Face
1529 Attributes}.
1531 @item
1532 A cons cell, of the form @code{(foreground-color . @var{color-name})}
1533 or @code{(background-color . @var{color-name})}.  These elements
1534 specify just the foreground color or just the background color.
1536 @code{(foreground-color . @var{color-name})} has the same effect as
1537 @code{(:foreground @var{color-name})}; likewise for the background.
1538 @end itemize
1540 @item mouse-face
1541 @kindex mouse-face @r{(overlay property)}
1542 This property is used instead of @code{face} when the mouse is within
1543 the range of the overlay.  However, Emacs ignores all face attributes
1544 from this property that alter the text size (e.g.  @code{:height},
1545 @code{:weight}, and @code{:slant}).  Those attributes are always the
1546 same as in the unhighlighted text.
1548 @item display
1549 @kindex display @r{(overlay property)}
1550 This property activates various features that change the
1551 way text is displayed.  For example, it can make text appear taller
1552 or shorter, higher or lower, wider or narrower, or replaced with an image.
1553 @xref{Display Property}.
1555 @item help-echo
1556 @kindex help-echo @r{(overlay property)}
1557 If an overlay has a @code{help-echo} property, then when you move the
1558 mouse onto the text in the overlay, Emacs displays a help string in the
1559 echo area, or in the tooltip window.  For details see @ref{Text
1560 help-echo}.
1562 @item modification-hooks
1563 @kindex modification-hooks @r{(overlay property)}
1564 This property's value is a list of functions to be called if any
1565 character within the overlay is changed or if text is inserted strictly
1566 within the overlay.
1568 The hook functions are called both before and after each change.
1569 If the functions save the information they receive, and compare notes
1570 between calls, they can determine exactly what change has been made
1571 in the buffer text.
1573 When called before a change, each function receives four arguments: the
1574 overlay, @code{nil}, and the beginning and end of the text range to be
1575 modified.
1577 When called after a change, each function receives five arguments: the
1578 overlay, @code{t}, the beginning and end of the text range just
1579 modified, and the length of the pre-change text replaced by that range.
1580 (For an insertion, the pre-change length is zero; for a deletion, that
1581 length is the number of characters deleted, and the post-change
1582 beginning and end are equal.)
1584 If these functions modify the buffer, they should bind
1585 @code{inhibit-modification-hooks} to @code{t} around doing so, to
1586 avoid confusing the internal mechanism that calls these hooks.
1588 Text properties also support the @code{modification-hooks} property,
1589 but the details are somewhat different (@pxref{Special Properties}).
1591 @item insert-in-front-hooks
1592 @kindex insert-in-front-hooks @r{(overlay property)}
1593 This property's value is a list of functions to be called before and
1594 after inserting text right at the beginning of the overlay.  The calling
1595 conventions are the same as for the @code{modification-hooks} functions.
1597 @item insert-behind-hooks
1598 @kindex insert-behind-hooks @r{(overlay property)}
1599 This property's value is a list of functions to be called before and
1600 after inserting text right at the end of the overlay.  The calling
1601 conventions are the same as for the @code{modification-hooks} functions.
1603 @item invisible
1604 @kindex invisible @r{(overlay property)}
1605 The @code{invisible} property can make the text in the overlay
1606 invisible, which means that it does not appear on the screen.
1607 @xref{Invisible Text}, for details.
1609 @item intangible
1610 @kindex intangible @r{(overlay property)}
1611 The @code{intangible} property on an overlay works just like the
1612 @code{intangible} text property.  @xref{Special Properties}, for details.
1614 @item isearch-open-invisible
1615 This property tells incremental search how to make an invisible overlay
1616 visible, permanently, if the final match overlaps it.  @xref{Invisible
1617 Text}.
1619 @item isearch-open-invisible-temporary
1620 This property tells incremental search how to make an invisible overlay
1621 visible, temporarily, during the search.  @xref{Invisible Text}.
1623 @item before-string
1624 @kindex before-string @r{(overlay property)}
1625 This property's value is a string to add to the display at the beginning
1626 of the overlay.  The string does not appear in the buffer in any
1627 sense---only on the screen.
1629 @item after-string
1630 @kindex after-string @r{(overlay property)}
1631 This property's value is a string to add to the display at the end of
1632 the overlay.  The string does not appear in the buffer in any
1633 sense---only on the screen.
1635 @item line-prefix
1636 This property specifies a display spec to prepend to each
1637 non-continuation line at display-time.  @xref{Truncation}.
1639 @item wrap-prefix
1640 This property specifies a display spec to prepend to each continuation
1641 line at display-time.  @xref{Truncation}.
1643 @item evaporate
1644 @kindex evaporate @r{(overlay property)}
1645 If this property is non-@code{nil}, the overlay is deleted automatically
1646 if it becomes empty (i.e., if its length becomes zero).  If you give
1647 an empty overlay a non-@code{nil} @code{evaporate} property, that deletes
1648 it immediately.
1650 @item local-map
1651 @cindex keymap of character (and overlays)
1652 @kindex local-map @r{(overlay property)}
1653 If this property is non-@code{nil}, it specifies a keymap for a portion
1654 of the text.  The property's value replaces the buffer's local map, when
1655 the character after point is within the overlay.  @xref{Active Keymaps}.
1657 @item keymap
1658 @kindex keymap @r{(overlay property)}
1659 The @code{keymap} property is similar to @code{local-map} but overrides the
1660 buffer's local map (and the map specified by the @code{local-map}
1661 property) rather than replacing it.
1662 @end table
1664 The @code{local-map} and @code{keymap} properties do not affect a
1665 string displayed by the @code{before-string}, @code{after-string}, or
1666 @code{display} properties.  This is only relevant for mouse clicks and
1667 other mouse events that fall on the string, since point is never on
1668 the string.  To bind special mouse events for the string, assign it a
1669 @code{local-map} or @code{keymap} text property.  @xref{Special
1670 Properties}.
1672 @node Finding Overlays
1673 @subsection Searching for Overlays
1675 @defun overlays-at pos
1676 This function returns a list of all the overlays that cover the
1677 character at position @var{pos} in the current buffer.  The list is in
1678 no particular order.  An overlay contains position @var{pos} if it
1679 begins at or before @var{pos}, and ends after @var{pos}.
1681 To illustrate usage, here is a Lisp function that returns a list of the
1682 overlays that specify property @var{prop} for the character at point:
1684 @smallexample
1685 (defun find-overlays-specifying (prop)
1686   (let ((overlays (overlays-at (point)))
1687         found)
1688     (while overlays
1689       (let ((overlay (car overlays)))
1690         (if (overlay-get overlay prop)
1691             (setq found (cons overlay found))))
1692       (setq overlays (cdr overlays)))
1693     found))
1694 @end smallexample
1695 @end defun
1697 @defun overlays-in beg end
1698 This function returns a list of the overlays that overlap the region
1699 @var{beg} through @var{end}.  ``Overlap'' means that at least one
1700 character is contained within the overlay and also contained within the
1701 specified region; however, empty overlays are included in the result if
1702 they are located at @var{beg}, strictly between @var{beg} and @var{end},
1703 or at @var{end} when @var{end} denotes the position at the end of the
1704 buffer.
1705 @end defun
1707 @defun next-overlay-change pos
1708 This function returns the buffer position of the next beginning or end
1709 of an overlay, after @var{pos}.  If there is none, it returns
1710 @code{(point-max)}.
1711 @end defun
1713 @defun previous-overlay-change pos
1714 This function returns the buffer position of the previous beginning or
1715 end of an overlay, before @var{pos}.  If there is none, it returns
1716 @code{(point-min)}.
1717 @end defun
1719   As an example, here's a simplified (and inefficient) version of the
1720 primitive function @code{next-single-char-property-change}
1721 (@pxref{Property Search}).  It searches forward from position
1722 @var{pos} for the next position where the value of a given property
1723 @code{prop}, as obtained from either overlays or text properties,
1724 changes.
1726 @smallexample
1727 (defun next-single-char-property-change (position prop)
1728   (save-excursion
1729     (goto-char position)
1730     (let ((propval (get-char-property (point) prop)))
1731       (while (and (not (eobp))
1732                   (eq (get-char-property (point) prop) propval))
1733         (goto-char (min (next-overlay-change (point))
1734                         (next-single-property-change (point) prop)))))
1735     (point)))
1736 @end smallexample
1738 @node Width
1739 @section Width
1741 Since not all characters have the same width, these functions let you
1742 check the width of a character.  @xref{Primitive Indent}, and
1743 @ref{Screen Lines}, for related functions.
1745 @defun char-width char
1746 This function returns the width in columns of the character
1747 @var{char}, if it were displayed in the current buffer (i.e.@: taking
1748 into account the buffer's display table, if any; @pxref{Display
1749 Tables}).  The width of a tab character is usually @code{tab-width}
1750 (@pxref{Usual Display}).
1751 @end defun
1753 @defun string-width string
1754 This function returns the width in columns of the string @var{string},
1755 if it were displayed in the current buffer and the selected window.
1756 @end defun
1758 @defun truncate-string-to-width string width &optional start-column padding ellipsis
1759 This function returns the part of @var{string} that fits within
1760 @var{width} columns, as a new string.
1762 If @var{string} does not reach @var{width}, then the result ends where
1763 @var{string} ends.  If one multi-column character in @var{string}
1764 extends across the column @var{width}, that character is not included in
1765 the result.  Thus, the result can fall short of @var{width} but cannot
1766 go beyond it.
1768 The optional argument @var{start-column} specifies the starting column.
1769 If this is non-@code{nil}, then the first @var{start-column} columns of
1770 the string are omitted from the value.  If one multi-column character in
1771 @var{string} extends across the column @var{start-column}, that
1772 character is not included.
1774 The optional argument @var{padding}, if non-@code{nil}, is a padding
1775 character added at the beginning and end of the result string, to extend
1776 it to exactly @var{width} columns.  The padding character is used at the
1777 end of the result if it falls short of @var{width}.  It is also used at
1778 the beginning of the result if one multi-column character in
1779 @var{string} extends across the column @var{start-column}.
1781 If @var{ellipsis} is non-@code{nil}, it should be a string which will
1782 replace the end of @var{str} (including any padding) if it extends
1783 beyond @var{end-column}, unless the display width of @var{str} is
1784 equal to or less than the display width of @var{ellipsis}.  If
1785 @var{ellipsis} is non-@code{nil} and not a string, it stands for
1786 @code{"..."}.
1788 @example
1789 (truncate-string-to-width "\tab\t" 12 4)
1790      @result{} "ab"
1791 (truncate-string-to-width "\tab\t" 12 4 ?\s)
1792      @result{} "    ab  "
1793 @end example
1794 @end defun
1796 @node Line Height
1797 @section Line Height
1798 @cindex line height
1800   The total height of each display line consists of the height of the
1801 contents of the line, plus optional additional vertical line spacing
1802 above or below the display line.
1804   The height of the line contents is the maximum height of any
1805 character or image on that display line, including the final newline
1806 if there is one.  (A display line that is continued doesn't include a
1807 final newline.)  That is the default line height, if you do nothing to
1808 specify a greater height.  (In the most common case, this equals the
1809 height of the default frame font.)
1811   There are several ways to explicitly specify a larger line height,
1812 either by specifying an absolute height for the display line, or by
1813 specifying vertical space.  However, no matter what you specify, the
1814 actual line height can never be less than the default.
1816 @kindex line-height @r{(text property)}
1817   A newline can have a @code{line-height} text or overlay property
1818 that controls the total height of the display line ending in that
1819 newline.
1821   If the property value is @code{t}, the newline character has no
1822 effect on the displayed height of the line---the visible contents
1823 alone determine the height.  This is useful for tiling small images
1824 (or image slices) without adding blank areas between the images.
1826   If the property value is a list of the form @code{(@var{height}
1827 @var{total})}, that adds extra space @emph{below} the display line.
1828 First Emacs uses @var{height} as a height spec to control extra space
1829 @emph{above} the line; then it adds enough space @emph{below} the line
1830 to bring the total line height up to @var{total}.  In this case, the
1831 other ways to specify the line spacing are ignored.
1833   Any other kind of property value is a height spec, which translates
1834 into a number---the specified line height.  There are several ways to
1835 write a height spec; here's how each of them translates into a number:
1837 @table @code
1838 @item @var{integer}
1839 If the height spec is a positive integer, the height value is that integer.
1840 @item @var{float}
1841 If the height spec is a float, @var{float}, the numeric height value
1842 is @var{float} times the frame's default line height.
1843 @item (@var{face} . @var{ratio})
1844 If the height spec is a cons of the format shown, the numeric height
1845 is @var{ratio} times the height of face @var{face}.  @var{ratio} can
1846 be any type of number, or @code{nil} which means a ratio of 1.
1847 If @var{face} is @code{t}, it refers to the current face.
1848 @item (nil . @var{ratio})
1849 If the height spec is a cons of the format shown, the numeric height
1850 is @var{ratio} times the height of the contents of the line.
1851 @end table
1853   Thus, any valid height spec determines the height in pixels, one way
1854 or another.  If the line contents' height is less than that, Emacs
1855 adds extra vertical space above the line to achieve the specified
1856 total height.
1858   If you don't specify the @code{line-height} property, the line's
1859 height consists of the contents' height plus the line spacing.
1860 There are several ways to specify the line spacing for different
1861 parts of Emacs text.
1863   On graphical terminals, you can specify the line spacing for all
1864 lines in a frame, using the @code{line-spacing} frame parameter
1865 (@pxref{Layout Parameters}).  However, if the default value of
1866 @code{line-spacing} is non-@code{nil}, it overrides the
1867 frame's @code{line-spacing} parameter.  An integer value specifies the
1868 number of pixels put below lines.  A floating point number specifies
1869 the spacing relative to the frame's default line height.
1871 @vindex line-spacing
1872   You can specify the line spacing for all lines in a buffer via the
1873 buffer-local @code{line-spacing} variable.  An integer value specifies
1874 the number of pixels put below lines.  A floating point number
1875 specifies the spacing relative to the default frame line height.  This
1876 overrides line spacings specified for the frame.
1878 @kindex line-spacing @r{(text property)}
1879   Finally, a newline can have a @code{line-spacing} text or overlay
1880 property that overrides the default frame line spacing and the buffer
1881 local @code{line-spacing} variable, for the display line ending in
1882 that newline.
1884   One way or another, these mechanisms specify a Lisp value for the
1885 spacing of each line.  The value is a height spec, and it translates
1886 into a Lisp value as described above.  However, in this case the
1887 numeric height value specifies the line spacing, rather than the line
1888 height.
1890   On text terminals, the line spacing cannot be altered.
1892 @node Faces
1893 @section Faces
1894 @cindex faces
1896   A @dfn{face} is a collection of graphical @dfn{attributes} for
1897 displaying text: font, foreground color, background color, optional
1898 underlining, etc.  Faces control how Emacs displays text in buffers,
1899 as well as other parts of the frame such as the mode line.
1901 @cindex anonymous face
1902   One way to represent a face is as a property list of attributes,
1903 like @code{(:foreground "red" :weight bold)}.  For example, you can
1904 assign such an @dfn{anonymous face} as the value of the @code{face}
1905 text property; this causes Emacs to display the underlying text with
1906 the specified attributes.  @xref{Special Properties}.
1908 @cindex face name
1909   More commonly, a face is referred to via a @dfn{face name}: a Lisp
1910 symbol which is associated with a set of face attributes.  Named faces
1911 are defined using the @code{defface} macro (@pxref{Defining Faces}).
1912 Emacs defines several standard named faces; @xref{Standard Faces,,,
1913 emacs, The GNU Emacs Manual}.
1915   Many parts of Emacs require named faces, and do not accept anonymous
1916 faces.  These include the functions documented in @ref{Attribute
1917 Functions}, and the variable @code{font-lock-keywords}
1918 (@pxref{Search-based Fontification}).  Unless otherwise stated, we
1919 will use the term @dfn{face} to refer only to named faces.
1921   For backward compatibility, you can also use a string to specify a
1922 face name; that is equivalent to a Lisp symbol with the same name.
1924 @defun facep object
1925 This function returns a non-@code{nil} value if @var{object} is a
1926 named face: a Lisp symbol or string which serves as a face name.
1927 Otherwise, it returns @code{nil}.
1928 @end defun
1930   By default, each face name corresponds to the same set of attributes
1931 in all frames.  But you can also assign a face name a special set of
1932 attributes in one frame (@pxref{Attribute Functions}).
1934 @menu
1935 * Face Attributes::     What is in a face?
1936 * Defining Faces::      How to define a face.
1937 * Attribute Functions::  Functions to examine and set face attributes.
1938 * Displaying Faces::     How Emacs combines the faces specified for a character.
1939 * Face Remapping::      Remapping faces to alternative definitions.
1940 * Face Functions::      How to define and examine faces.
1941 * Auto Faces::          Hook for automatic face assignment.
1942 * Basic Faces::         Faces that are defined by default.
1943 * Font Selection::      Finding the best available font for a face.
1944 * Font Lookup::         Looking up the names of available fonts
1945                           and information about them.
1946 * Fontsets::            A fontset is a collection of fonts
1947                           that handle a range of character sets.
1948 * Low-Level Font::      Lisp representation for character display fonts.
1949 @end menu
1951 @node Face Attributes
1952 @subsection Face Attributes
1953 @cindex face attributes
1955   @dfn{Face attributes} determine the visual appearance of a face.
1956 The following table lists all the face attributes, their possible
1957 values, and their effects.
1959   Apart from the values given below, each face attribute can have the
1960 value @code{unspecified}.  This special value means that the face
1961 doesn't specify that attribute directly.  An @code{unspecified}
1962 attribute tells Emacs to refer instead to a parent face (see the
1963 description @code{:inherit} attribute below); or, failing that, to an
1964 underlying face (@pxref{Displaying Faces}).  The @code{default} face
1965 must specify all attributes.
1967   Some of these attributes are meaningful only on certain kinds of
1968 displays.  If your display cannot handle a certain attribute, the
1969 attribute is ignored.
1971 @table @code
1972 @item :family
1973 Font family or fontset (a string).  @xref{Fonts,,, emacs, The GNU
1974 Emacs Manual}, for more information about font families.  The function
1975 @code{font-family-list} (see below) returns a list of available family
1976 names.  @xref{Fontsets}, for information about fontsets.
1978 @item :foundry
1979 The name of the @dfn{font foundry} for the font family specified by
1980 the @code{:family} attribute (a string).  @xref{Fonts,,, emacs, The
1981 GNU Emacs Manual}.
1983 @item :width
1984 Relative character width.  This should be one of the symbols
1985 @code{ultra-condensed}, @code{extra-condensed}, @code{condensed},
1986 @code{semi-condensed}, @code{normal}, @code{semi-expanded},
1987 @code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}.
1989 @item :height
1990 The height of the font.  In the simplest case, this is an integer in
1991 units of 1/10 point.
1993 The value can also be a floating point number or a function, which
1994 specifies the height relative to an @dfn{underlying face}
1995 (@pxref{Displaying Faces}).  If the value is a floating point number,
1996 that specifies the amount by which to scale the height of the
1997 underlying face.  If the value is a function, that function is called
1998 with one argument, the height of the underlying face, and returns the
1999 height of the new face.  If the function is passed an integer
2000 argument, it must return an integer.
2002 The height of the default face must be specified using an integer;
2003 floating point and function values are not allowed.
2005 @item :weight
2006 Font weight---one of the symbols (from densest to faintest)
2007 @code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
2008 @code{normal}, @code{semi-light}, @code{light}, @code{extra-light}, or
2009 @code{ultra-light}.  On text terminals which support
2010 variable-brightness text, any weight greater than normal is displayed
2011 as extra bright, and any weight less than normal is displayed as
2012 half-bright.
2014 @cindex italic text
2015 @item :slant
2016 Font slant---one of the symbols @code{italic}, @code{oblique},
2017 @code{normal}, @code{reverse-italic}, or @code{reverse-oblique}.  On
2018 text terminals that support variable-brightness text, slanted text is
2019 displayed as half-bright.
2021 @item :foreground
2022 Foreground color, a string.  The value can be a system-defined color
2023 name, or a hexadecimal color specification.  @xref{Color Names}.  On
2024 black-and-white displays, certain shades of gray are implemented by
2025 stipple patterns.
2027 @item :background
2028 Background color, a string.  The value can be a system-defined color
2029 name, or a hexadecimal color specification.  @xref{Color Names}.
2031 @cindex underlined text
2032 @item :underline
2033 Whether or not characters should be underlined, and in what
2034 way.  The possible values of the @code{:underline} attribute are:
2036 @table @asis
2037 @item @code{nil}
2038 Don't underline.
2040 @item @code{t}
2041 Underline with the foreground color of the face.
2043 @item @var{color}
2044 Underline in color @var{color}, a string specifying a color.
2046 @item @code{(:color @var{color} :style @var{style})}
2047 @var{color} is either a string, or the symbol @code{foreground-color},
2048 meaning the foreground color of the face.  Omitting the attribute
2049 @code{:color} means to use the foreground color of the face.
2050 @var{style} should be a symbol @code{line} or @code{wave}, meaning to
2051 use a straight or wavy line.  Omitting the attribute @code{:style}
2052 means to use a straight line.
2053 @end table
2055 @cindex overlined text
2056 @item :overline
2057 Whether or not characters should be overlined, and in what color.
2058 If the value is @code{t}, overlining uses the foreground color of the
2059 face.  If the value is a string, overlining uses that color.  The
2060 value @code{nil} means do not overline.
2062 @cindex strike-through text
2063 @item :strike-through
2064 Whether or not characters should be strike-through, and in what
2065 color.  The value is used like that of @code{:overline}.
2067 @item :box
2068 Whether or not a box should be drawn around characters, its color, the
2069 width of the box lines, and 3D appearance.  Here are the possible
2070 values of the @code{:box} attribute, and what they mean:
2072 @table @asis
2073 @item @code{nil}
2074 Don't draw a box.
2076 @item @code{t}
2077 Draw a box with lines of width 1, in the foreground color.
2079 @item @var{color}
2080 Draw a box with lines of width 1, in color @var{color}.
2082 @item @code{(:line-width @var{width} :color @var{color} :style @var{style})}
2083 This way you can explicitly specify all aspects of the box.  The value
2084 @var{width} specifies the width of the lines to draw; it defaults to
2085 1.  A negative width @var{-n} means to draw a line of width @var{n}
2086 that occupies the space of the underlying text, thus avoiding any
2087 increase in the character height or width.
2089 The value @var{color} specifies the color to draw with.  The default is
2090 the foreground color of the face for simple boxes, and the background
2091 color of the face for 3D boxes.
2093 The value @var{style} specifies whether to draw a 3D box.  If it is
2094 @code{released-button}, the box looks like a 3D button that is not being
2095 pressed.  If it is @code{pressed-button}, the box looks like a 3D button
2096 that is being pressed.  If it is @code{nil} or omitted, a plain 2D box
2097 is used.
2098 @end table
2100 @item :inverse-video
2101 Whether or not characters should be displayed in inverse video.  The
2102 value should be @code{t} (yes) or @code{nil} (no).
2104 @item :stipple
2105 The background stipple, a bitmap.
2107 The value can be a string; that should be the name of a file containing
2108 external-format X bitmap data.  The file is found in the directories
2109 listed in the variable @code{x-bitmap-file-path}.
2111 Alternatively, the value can specify the bitmap directly, with a list
2112 of the form @code{(@var{width} @var{height} @var{data})}.  Here,
2113 @var{width} and @var{height} specify the size in pixels, and
2114 @var{data} is a string containing the raw bits of the bitmap, row by
2115 row.  Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes
2116 in the string (which should be a unibyte string for best results).
2117 This means that each row always occupies at least one whole byte.
2119 If the value is @code{nil}, that means use no stipple pattern.
2121 Normally you do not need to set the stipple attribute, because it is
2122 used automatically to handle certain shades of gray.
2124 @item :font
2125 The font used to display the face.  Its value should be a font object.
2126 @xref{Font Selection}, for information about font objects.
2128 When specifying this attribute using @code{set-face-attribute}
2129 (@pxref{Attribute Functions}), you may also supply a font spec, a font
2130 entity, or a string.  Emacs converts such values to an appropriate
2131 font object, and stores that font object as the actual attribute
2132 value.  If you specify a string, the contents of the string should be
2133 a font name (@pxref{Fonts,,, emacs, The GNU Emacs Manual}); if the
2134 font name is an XLFD containing wildcards, Emacs chooses the first
2135 font matching those wildcards.  Specifying this attribute also changes
2136 the values of the @code{:family}, @code{:foundry}, @code{:width},
2137 @code{:height}, @code{:weight}, and @code{:slant} attributes.
2139 @item :inherit
2140 The name of a face from which to inherit attributes, or a list of face
2141 names.  Attributes from inherited faces are merged into the face like
2142 an underlying face would be, with higher priority than underlying
2143 faces (@pxref{Displaying Faces}).  If a list of faces is used,
2144 attributes from faces earlier in the list override those from later
2145 faces.
2146 @end table
2148 @defun font-family-list &optional frame
2149 This function returns a list of available font family names.  The
2150 optional argument @var{frame} specifies the frame on which the text is
2151 to be displayed; if it is @code{nil}, the selected frame is used.
2152 @end defun
2154 @defopt underline-minimum-offset
2155 This variable specifies the minimum distance between the baseline and
2156 the underline, in pixels, when displaying underlined text.
2157 @end defopt
2159 @defopt x-bitmap-file-path
2160 This variable specifies a list of directories for searching
2161 for bitmap files, for the @code{:stipple} attribute.
2162 @end defopt
2164 @defun bitmap-spec-p object
2165 This returns @code{t} if @var{object} is a valid bitmap specification,
2166 suitable for use with @code{:stipple} (see above).  It returns
2167 @code{nil} otherwise.
2168 @end defun
2170 @node Defining Faces
2171 @subsection Defining Faces
2173   The usual way to define a face is through the @code{defface} macro.
2174 This macro defines a face name, and associates that name with a set of
2175 face attributes.  It also sets up the face so that the user can
2176 customize it via the Customize interface (@pxref{Customization}).
2178 @defmac defface face spec doc [keyword value]@dots{}
2179 This macro declares @var{face} as a customizable face whose default
2180 attributes are given by @var{spec}.  You should not quote the symbol
2181 @var{face}, and it should not end in @samp{-face} (that would be
2182 redundant).  The argument @var{doc} is a documentation string for the
2183 face.  The additional @var{keyword} arguments have the same meanings
2184 as in @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
2186 When @code{defface} executes, it defines the face according to
2187 @var{spec}, then uses any customizations that were read from the
2188 init file (@pxref{Init File}) to override that specification.
2190 When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs
2191 Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun}
2192 overrides any customizations of the face.  This way, the face reflects
2193 exactly what the @code{defface} says.
2195 @cindex face specification
2196 The @var{spec} argument is a @dfn{face specification}, which states
2197 how the face should appear on different kinds of terminals.  It should
2198 be an alist whose elements each have the form
2200 @example
2201 (@var{display} . @var{plist})
2202 @end example
2204 @noindent
2205 @var{display} specifies a class of terminals (see below).  @var{plist}
2206 is a property list of face attributes and their values, specifying how
2207 the face appears on such terminals.  For backward compatibility, you
2208 can also write an element as @code{(@var{display} @var{plist})}.
2210 The @var{display} part of an element of @var{spec} determines which
2211 terminals the element matches.  If more than one element of @var{spec}
2212 matches a given terminal, the first element that matches is the one
2213 used for that terminal.  There are three possibilities for
2214 @var{display}:
2216 @table @asis
2217 @item @code{default}
2218 This element of @var{spec} doesn't match any terminal; instead, it
2219 specifies defaults that apply to all terminals.  This element, if
2220 used, must be the first element of @var{spec}.  Each of the following
2221 elements can override any or all of these defaults.
2223 @item @code{t}
2224 This element of @var{spec} matches all terminals.  Therefore, any
2225 subsequent elements of @var{spec} are never used.  Normally @code{t}
2226 is used in the last (or only) element of @var{spec}.
2228 @item a list
2229 If @var{display} is a list, each element should have the form
2230 @code{(@var{characteristic} @var{value}@dots{})}.  Here
2231 @var{characteristic} specifies a way of classifying terminals, and the
2232 @var{value}s are possible classifications which @var{display} should
2233 apply to.  Here are the possible values of @var{characteristic}:
2235 @table @code
2236 @item type
2237 The kind of window system the terminal uses---either @code{graphic}
2238 (any graphics-capable display), @code{x}, @code{pc} (for the MS-DOS
2239 console), @code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty} (a
2240 non-graphics-capable display).  @xref{Window Systems, window-system}.
2242 @item class
2243 What kinds of colors the terminal supports---either @code{color},
2244 @code{grayscale}, or @code{mono}.
2246 @item background
2247 The kind of background---either @code{light} or @code{dark}.
2249 @item min-colors
2250 An integer that represents the minimum number of colors the terminal
2251 should support.  This matches a terminal if its
2252 @code{display-color-cells} value is at least the specified integer.
2254 @item supports
2255 Whether or not the terminal can display the face attributes given in
2256 @var{value}@dots{} (@pxref{Face Attributes}).  @xref{Display Face
2257 Attribute Testing}, for more information on exactly how this testing
2258 is done.
2259 @end table
2261 If an element of @var{display} specifies more than one @var{value} for
2262 a given @var{characteristic}, any of those values is acceptable.  If
2263 @var{display} has more than one element, each element should specify a
2264 different @var{characteristic}; then @emph{each} characteristic of the
2265 terminal must match one of the @var{value}s specified for it in
2266 @var{display}.
2267 @end table
2268 @end defmac
2270   Here's how the standard face @code{highlight} is defined:
2272 @example
2273 (defface highlight
2274   '((((class color) (min-colors 88) (background light))
2275      :background "darkseagreen2")
2276     (((class color) (min-colors 88) (background dark))
2277      :background "darkolivegreen")
2278     (((class color) (min-colors 16) (background light))
2279      :background "darkseagreen2")
2280     (((class color) (min-colors 16) (background dark))
2281      :background "darkolivegreen")
2282     (((class color) (min-colors 8))
2283      :background "green" :foreground "black")
2284     (t :inverse-video t))
2285   "Basic face for highlighting."
2286   :group 'basic-faces)
2287 @end example
2289   Internally, Emacs stores the face's default specification in its
2290 @code{face-defface-spec} symbol property (@pxref{Property Lists}).
2291 The @code{saved-face} property stores the face specification saved by
2292 the user, using the customization buffer; the @code{customized-face}
2293 property stores the face specification customized for the current
2294 session, but not saved; and the @code{theme-face} property stores an
2295 alist associating the active customization settings and Custom themes
2296 with their specifications for that face.  The face's documentation
2297 string is stored in the @code{face-documentation} property.  But
2298 normally you should not try to set any of these properties directly.
2299 @xref{Applying Customizations}, for the @code{custom-set-faces}
2300 function, which is used to apply customized face settings.
2302   People are sometimes tempted to create variables whose values
2303 specify a face to use.  In the vast majority of cases, this is not
2304 necessary; it is preferable to simply use faces directly.
2306 @node Attribute Functions
2307 @subsection Face Attribute Functions
2309   This section describes the functions for accessing and modifying the
2310 attributes of an existing named face.
2312 @defun set-face-attribute face frame &rest arguments
2313 This function sets one or more attributes of @var{face} for
2314 @var{frame}.  The attributes you specify this way override whatever
2315 the @code{defface} says.
2317 The extra arguments @var{arguments} specify the attributes to set, and
2318 the values for them.  They should consist of alternating attribute
2319 names (such as @code{:family} or @code{:underline}) and values.  Thus,
2321 @example
2322 (set-face-attribute 'foo nil
2323                     :width 'extended
2324                     :weight 'bold)
2325 @end example
2327 @noindent
2328 sets the attribute @code{:width} to @code{extended} and the attribute
2329 @code{:weight} to @code{bold}.
2331 If @var{frame} is @code{t}, this function sets the default attributes
2332 for new frames.  Default attribute values specified this way override
2333 the @code{defface} for newly created frames.
2335 If @var{frame} is @code{nil}, this function sets the attributes for
2336 all existing frames, and the default for new frames.
2337 @end defun
2339 @defun face-attribute face attribute &optional frame inherit
2340 This returns the value of the @var{attribute} attribute of @var{face}
2341 on @var{frame}.  If @var{frame} is @code{nil}, that means the selected
2342 frame (@pxref{Input Focus}).
2344 If @var{frame} is @code{t}, this returns whatever new-frames default
2345 value you previously specified with @code{set-face-attribute} for the
2346 @var{attribute} attribute of @var{face}.  If you have not specified
2347 one, it returns @code{nil}.
2349 If @var{inherit} is @code{nil}, only attributes directly defined by
2350 @var{face} are considered, so the return value may be
2351 @code{unspecified}, or a relative value.  If @var{inherit} is
2352 non-@code{nil}, @var{face}'s definition of @var{attribute} is merged
2353 with the faces specified by its @code{:inherit} attribute; however the
2354 return value may still be @code{unspecified} or relative.  If
2355 @var{inherit} is a face or a list of faces, then the result is further
2356 merged with that face (or faces), until it becomes specified and
2357 absolute.
2359 To ensure that the return value is always specified and absolute, use
2360 a value of @code{default} for @var{inherit}; this will resolve any
2361 unspecified or relative values by merging with the @code{default} face
2362 (which is always completely specified).
2364 For example,
2366 @example
2367 (face-attribute 'bold :weight)
2368      @result{} bold
2369 @end example
2370 @end defun
2372 @defun face-attribute-relative-p attribute value
2373 This function returns non-@code{nil} if @var{value}, when used as the
2374 value of the face attribute @var{attribute}, is relative.  This means
2375 it would modify, rather than completely override, any value that comes
2376 from a subsequent face in the face list or that is inherited from
2377 another face.
2379 @code{unspecified} is a relative value for all attributes.  For
2380 @code{:height}, floating point and function values are also relative.
2382 For example:
2384 @example
2385 (face-attribute-relative-p :height 2.0)
2386      @result{} t
2387 @end example
2388 @end defun
2390 @defun face-all-attributes face &optional frame
2391 This function returns an alist of attributes of @var{face}.  The
2392 elements of the result are name-value pairs of the form
2393 @w{@code{(@var{attr-name} . @var{attr-value})}}.  Optional argument
2394 @var{frame} specifies the frame whose definition of @var{face} to
2395 return; if omitted or @code{nil}, the returned value describes the
2396 default attributes of @var{face} for newly created frames.
2397 @end defun
2399 @defun merge-face-attribute attribute value1 value2
2400 If @var{value1} is a relative value for the face attribute
2401 @var{attribute}, returns it merged with the underlying value
2402 @var{value2}; otherwise, if @var{value1} is an absolute value for the
2403 face attribute @var{attribute}, returns @var{value1} unchanged.
2404 @end defun
2406   The following commands and functions mostly provide compatibility
2407 with old versions of Emacs.  They work by calling
2408 @code{set-face-attribute}.  Values of @code{t} and @code{nil} for
2409 their @var{frame} argument are handled just like
2410 @code{set-face-attribute} and @code{face-attribute}.  The commands
2411 read their arguments using the minibuffer, if called interactively.
2413 @deffn Command set-face-foreground face color &optional frame
2414 @deffnx Command set-face-background face color &optional frame
2415 These set the @code{:foreground} attribute (or @code{:background}
2416 attribute, respectively) of @var{face} to @var{color}.
2417 @end deffn
2419 @deffn Command set-face-stipple face pattern &optional frame
2420 This sets the @code{:stipple} attribute of @var{face} to
2421 @var{pattern}.
2422 @end deffn
2424 @deffn Command set-face-font face font &optional frame
2425 This sets the @code{:font} attribute of @var{face} to @var{font}.
2426 @end deffn
2428 @defun set-face-bold-p face bold-p &optional frame
2429 This sets the @code{:weight} attribute of @var{face} to @var{normal}
2430 if @var{bold-p} is @code{nil}, and to @var{bold} otherwise.
2431 @end defun
2433 @defun set-face-italic-p face italic-p &optional frame
2434 This sets the @code{:slant} attribute of @var{face} to @var{normal} if
2435 @var{italic-p} is @code{nil}, and to @var{italic} otherwise.
2436 @end defun
2438 @defun set-face-underline face underline &optional frame
2439 This sets the @code{:underline} attribute of @var{face} to
2440 @var{underline}.
2441 @end defun
2443 @defun set-face-inverse-video-p face inverse-video-p &optional frame
2444 This sets the @code{:inverse-video} attribute of @var{face} to
2445 @var{inverse-video-p}.
2446 @end defun
2448 @deffn Command invert-face face &optional frame
2449 This swaps the foreground and background colors of face @var{face}.
2450 @end deffn
2452   The following functions examine the attributes of a face.  If you
2453 don't specify @var{frame}, they refer to the selected frame; @code{t}
2454 refers to the default data for new frames.  They return the symbol
2455 @code{unspecified} if the face doesn't define any value for that
2456 attribute.
2458 @defun face-foreground face &optional frame inherit
2459 @defunx face-background face &optional frame inherit
2460 These functions return the foreground color (or background color,
2461 respectively) of face @var{face}, as a string.
2463 If @var{inherit} is @code{nil}, only a color directly defined by the face is
2464 returned.  If @var{inherit} is non-@code{nil}, any faces specified by its
2465 @code{:inherit} attribute are considered as well, and if @var{inherit}
2466 is a face or a list of faces, then they are also considered, until a
2467 specified color is found.  To ensure that the return value is always
2468 specified, use a value of @code{default} for @var{inherit}.
2469 @end defun
2471 @defun face-stipple face &optional frame inherit
2472 This function returns the name of the background stipple pattern of face
2473 @var{face}, or @code{nil} if it doesn't have one.
2475 If @var{inherit} is @code{nil}, only a stipple directly defined by the
2476 face is returned.  If @var{inherit} is non-@code{nil}, any faces
2477 specified by its @code{:inherit} attribute are considered as well, and
2478 if @var{inherit} is a face or a list of faces, then they are also
2479 considered, until a specified stipple is found.  To ensure that the
2480 return value is always specified, use a value of @code{default} for
2481 @var{inherit}.
2482 @end defun
2484 @defun face-font face &optional frame
2485 This function returns the name of the font of face @var{face}.
2486 @end defun
2488 @defun face-bold-p face &optional frame
2489 This function returns a non-@code{nil} value if the @code{:weight}
2490 attribute of @var{face} is bolder than normal (i.e., one of
2491 @code{semi-bold}, @code{bold}, @code{extra-bold}, or
2492 @code{ultra-bold}).  Otherwise, it returns @code{nil}.
2493 @end defun
2495 @defun face-italic-p face &optional frame
2496 This function returns a non-@code{nil} value if the @code{:slant}
2497 attribute of @var{face} is @code{italic} or @code{oblique}, and
2498 @code{nil} otherwise.
2499 @end defun
2501 @c Note the weasel words.  A face that inherits from an underlined
2502 @c face but does not specify :underline will return nil.
2503 @defun face-underline-p face &optional frame
2504 This function returns non-@code{nil} if face @var{face} specifies
2505 a non-@code{nil} @code{:underline} attribute.
2506 @end defun
2508 @defun face-inverse-video-p face &optional frame
2509 This function returns non-@code{nil} if face @var{face} specifies
2510 a non-@code{nil} @code{:inverse-video} attribute.
2511 @end defun
2513 @node Displaying Faces
2514 @subsection Displaying Faces
2516   When Emacs displays a given piece of text, the visual appearance of
2517 the text may be determined by faces drawn from different sources.  If
2518 these various sources together specify more than one face for a
2519 particular character, Emacs merges the attributes of the various
2520 faces.  Here is the order in which Emacs merges the faces, from
2521 highest to lowest priority:
2523 @itemize @bullet
2524 @item
2525 If the text consists of a special glyph, the glyph can specify a
2526 particular face.  @xref{Glyphs}.
2528 @item
2529 If the text lies within an active region, Emacs highlights it using
2530 the @code{region} face.  @xref{Standard Faces,,, emacs, The GNU Emacs
2531 Manual}.
2533 @item
2534 If the text lies within an overlay with a non-@code{nil} @code{face}
2535 property, Emacs applies the face(s) specified by that property.  If
2536 the overlay has a @code{mouse-face} property and the mouse is ``near
2537 enough'' to the overlay, Emacs applies the face or face attributes
2538 specified by the @code{mouse-face} property instead.  @xref{Overlay
2539 Properties}.
2541 When multiple overlays cover one character, an overlay with higher
2542 priority overrides those with lower priority.  @xref{Overlays}.
2544 @item
2545 If the text contains a @code{face} or @code{mouse-face} property,
2546 Emacs applies the specified faces and face attributes.  @xref{Special
2547 Properties}.  (This is how Font Lock mode faces are applied.
2548 @xref{Font Lock Mode}.)
2550 @item
2551 If the text lies within the mode line of the selected window, Emacs
2552 applies the @code{mode-line} face.  For the mode line of a
2553 non-selected window, Emacs applies the @code{mode-line-inactive} face.
2554 For a header line, Emacs applies the @code{header-line} face.
2556 @item
2557 If any given attribute has not been specified during the preceding
2558 steps, Emacs applies the attribute of the @code{default} face.
2559 @end itemize
2561   At each stage, if a face has a valid @code{:inherit} attribute,
2562 Emacs treats any attribute with an @code{unspecified} value as having
2563 the corresponding value drawn from the parent face(s).  @pxref{Face
2564 Attributes}.  Note that the parent face(s) may also leave the
2565 attribute unspecified; in that case, the attribute remains unspecified
2566 at the next level of face merging.
2568 @node Face Remapping
2569 @subsection Face Remapping
2571   The variable @code{face-remapping-alist} is used for buffer-local or
2572 global changes in the appearance of a face.  For instance, it is used
2573 to implement the @code{text-scale-adjust} command (@pxref{Text
2574 Scale,,, emacs, The GNU Emacs Manual}).
2576 @defvar face-remapping-alist
2577 The value of this variable is an alist whose elements have the form
2578 @code{(@var{face} . @var{remapping})}.  This causes Emacs to display
2579 any text having the face @var{face} with @var{remapping}, rather than
2580 the ordinary definition of @var{face}.
2582 @var{remapping} may be any face specification suitable for a
2583 @code{face} text property: either a face (i.e.@: a face name or a
2584 property list of attribute/value pairs), or a list of faces.  For
2585 details, see the description of the @code{face} text property in
2586 @ref{Special Properties}.  @var{remapping} serves as the complete
2587 specification for the remapped face---it replaces the normal
2588 definition of @var{face}, instead of modifying it.
2590 If @code{face-remapping-alist} is buffer-local, its local value takes
2591 effect only within that buffer.
2593 Note: face remapping is non-recursive.  If @var{remapping} references
2594 the same face name @var{face}, either directly or via the
2595 @code{:inherit} attribute of some other face in @var{remapping}, that
2596 reference uses the normal definition of @var{face}.  For instance, if
2597 the @code{mode-line} face is remapped using this entry in
2598 @code{face-remapping-alist}:
2600 @example
2601 (mode-line italic mode-line)
2602 @end example
2604 @noindent
2605 then the new definition of the @code{mode-line} face inherits from the
2606 @code{italic} face, and the @emph{normal} (non-remapped) definition of
2607 @code{mode-line} face.
2608 @end defvar
2610   The following functions implement a higher-level interface to
2611 @code{face-remapping-alist}.  Most Lisp code should use these
2612 functions instead of setting @code{face-remapping-alist} directly, to
2613 avoid trampling on remappings applied elsewhere.  These functions are
2614 intended for buffer-local remappings, so they all make
2615 @code{face-remapping-alist} buffer-local as a side-effect. They manage
2616 @code{face-remapping-alist} entries of the form
2618 @example
2619   (@var{face} @var{relative-spec-1} @var{relative-spec-2} @var{...} @var{base-spec})
2620 @end example
2622 @noindent
2623 where, as explained above, each of the @var{relative-spec-N} and
2624 @var{base-spec} is either a face name, or a property list of
2625 attribute/value pairs.  Each of the @dfn{relative remapping} entries,
2626 @var{relative-spec-N}, is managed by the
2627 @code{face-remap-add-relative} and @code{face-remap-remove-relative}
2628 functions; these are intended for simple modifications like changing
2629 the text size.  The @dfn{base remapping} entry, @var{base-spec}, has
2630 the lowest priority and is managed by the @code{face-remap-set-base}
2631 and @code{face-remap-reset-base} functions; it is intended for major
2632 modes to remap faces in the buffers they control.
2634 @defun face-remap-add-relative face &rest specs
2635 This functions adds the face specifications in @var{specs} as relative
2636 remappings for face @var{face} in the current buffer.  The remaining
2637 arguments, @var{specs}, should form either a list of face names, or a
2638 property list of attribute/value pairs.
2640 The return value is a Lisp object that serves as a ``cookie''; you can
2641 pass this object as an argument to @code{face-remap-remove-relative}
2642 if you need to remove the remapping later.
2644 @example
2645 ;; Remap the `escape-glyph' face into a combination
2646 ;; of the `highlight' and `italic' faces:
2647 (face-remap-add-relative 'escape-glyph 'highlight 'italic)
2649 ;; Increase the size of the `default' face by 50%:
2650 (face-remap-add-relative 'default :height 1.5)
2651 @end example
2652 @end defun
2654 @defun face-remap-remove-relative cookie
2655 This function removes a relative remapping previously added by
2656 @code{face-remap-add-relative}.  @var{cookie} should be the Lisp
2657 object returned by @code{face-remap-add-relative} when the remapping
2658 was added.
2659 @end defun
2661 @defun face-remap-set-base face &rest specs
2662 This function sets the base remapping of @var{face} in the current
2663 buffer to @var{specs}.  If @var{specs} is empty, the default base
2664 remapping is restored, similar to calling @code{face-remap-reset-base}
2665 (see below); note that this is different from @var{specs} containing a
2666 single value @code{nil}, which has the opposite result (the global
2667 definition of @var{face} is ignored).
2669 This overwrites the default @var{base-spec}, which inherits the global
2670 face definition, so it is up to the caller to add such inheritance if
2671 so desired.
2672 @end defun
2674 @defun face-remap-reset-base face
2675 This function sets the base remapping of @var{face} to its default
2676 value, which inherits from @var{face}'s global definition.
2677 @end defun
2679 @node Face Functions
2680 @subsection Functions for Working with Faces
2682   Here are additional functions for creating and working with faces.
2684 @defun face-list
2685 This function returns a list of all defined face names.
2686 @end defun
2688 @defun face-id face
2689 This function returns the @dfn{face number} of face @var{face}.  This
2690 is a number that uniquely identifies a face at low levels within
2691 Emacs.  It is seldom necessary to refer to a face by its face number.
2692 @end defun
2694 @defun face-documentation face
2695 This function returns the documentation string of face @var{face}, or
2696 @code{nil} if none was specified for it.
2697 @end defun
2699 @defun face-equal face1 face2 &optional frame
2700 This returns @code{t} if the faces @var{face1} and @var{face2} have the
2701 same attributes for display.
2702 @end defun
2704 @defun face-differs-from-default-p face &optional frame
2705 This returns non-@code{nil} if the face @var{face} displays
2706 differently from the default face.
2707 @end defun
2709 @cindex face alias
2710 A @dfn{face alias} provides an equivalent name for a face.  You can
2711 define a face alias by giving the alias symbol the @code{face-alias}
2712 property, with a value of the target face name.  The following example
2713 makes @code{modeline} an alias for the @code{mode-line} face.
2715 @example
2716 (put 'modeline 'face-alias 'mode-line)
2717 @end example
2719 @defmac define-obsolete-face-alias obsolete-face current-face when
2720 This macro defines @code{obsolete-face} as an alias for
2721 @var{current-face}, and also marks it as obsolete, indicating that it
2722 may be removed in future.  @var{when} should be a string indicating
2723 when @code{obsolete-face} was made obsolete (usually a version number
2724 string).
2725 @end defmac
2727 @node Auto Faces
2728 @subsection Automatic Face Assignment
2729 @cindex automatic face assignment
2730 @cindex faces, automatic choice
2732   This hook is used for automatically assigning faces to text in the
2733 buffer.  It is part of the implementation of Jit-Lock mode, used by
2734 Font-Lock.
2736 @defvar fontification-functions
2737 This variable holds a list of functions that are called by Emacs
2738 redisplay as needed, just before doing redisplay.  They are called even
2739 when Font Lock Mode isn't enabled.  When Font Lock Mode is enabled, this
2740 variable usually holds just one function, @code{jit-lock-function}.
2742 The functions are called in the order listed, with one argument, a
2743 buffer position @var{pos}.  Collectively they should attempt to assign
2744 faces to the text in the current buffer starting at @var{pos}.
2746 The functions should record the faces they assign by setting the
2747 @code{face} property.  They should also add a non-@code{nil}
2748 @code{fontified} property to all the text they have assigned faces to.
2749 That property tells redisplay that faces have been assigned to that text
2750 already.
2752 It is probably a good idea for the functions to do nothing if the
2753 character after @var{pos} already has a non-@code{nil} @code{fontified}
2754 property, but this is not required.  If one function overrides the
2755 assignments made by a previous one, the properties after the last
2756 function finishes are the ones that really matter.
2758 For efficiency, we recommend writing these functions so that they
2759 usually assign faces to around 400 to 600 characters at each call.
2760 @end defvar
2762 @node Basic Faces
2763 @subsection Basic Faces
2765 If your Emacs Lisp program needs to assign some faces to text, it is
2766 often a good idea to use certain existing faces or inherit from them,
2767 rather than defining entirely new faces.  This way, if other users
2768 have customized the basic faces to give Emacs a certain look, your
2769 program will ``fit in'' without additional customization.
2771   Some of the basic faces defined in Emacs are listed below.  In
2772 addition to these, you might want to make use of the Font Lock faces
2773 for syntactic highlighting, if highlighting is not already handled by
2774 Font Lock mode, or if some Font Lock faces are not in use.
2775 @xref{Faces for Font Lock}.
2777 @table @code
2778 @item default
2779 The default face, whose attributes are all specified.  All other faces
2780 implicitly inherit from it: any unspecified attribute defaults to the
2781 attribute on this face (@pxref{Face Attributes}).
2783 @item bold
2784 @itemx italic
2785 @itemx bold-italic
2786 @itemx underline
2787 @itemx fixed-pitch
2788 @itemx variable-pitch
2789 These have the attributes indicated by their names (e.g. @code{bold}
2790 has a bold @code{:weight} attribute), with all other attributes
2791 unspecified (and so given by @code{default}).
2793 @item shadow
2794 For ``dimmed out'' text.  For example, it is used for the ignored
2795 part of a filename in the minibuffer (@pxref{Minibuffer File,,
2796 Minibuffers for File Names, emacs, The GNU Emacs Manual}).
2798 @item link
2799 @itemx link-visited
2800 For clickable text buttons that send the user to a different
2801 buffer or ``location''.
2803 @item highlight
2804 For stretches of text that should temporarily stand out.  For example,
2805 it is commonly assigned to the @code{mouse-face} property for cursor
2806 highlighting (@pxref{Special Properties}).
2808 @item match
2809 For text matching a search command.
2811 @item error
2812 @itemx warning
2813 @itemx success
2814 For text concerning errors, warnings, or successes.  For example,
2815 these are used for messages in @file{*Compilation*} buffers.
2816 @end table
2818 @node Font Selection
2819 @subsection Font Selection
2821   Before Emacs can draw a character on a graphical display, it must
2822 select a @dfn{font} for that character@footnote{In this context, the
2823 term @dfn{font} has nothing to do with Font Lock (@pxref{Font Lock
2824 Mode}).}.  @xref{Fonts,,, emacs, The GNU Emacs Manual}.  Normally,
2825 Emacs automatically chooses a font based on the faces assigned to that
2826 character---specifically, the face attributes @code{:family},
2827 @code{:weight}, @code{:slant}, and @code{:width} (@pxref{Face
2828 Attributes}).  The choice of font also depends on the character to be
2829 displayed; some fonts can only display a limited set of characters.
2830 If no available font exactly fits the requirements, Emacs looks for
2831 the @dfn{closest matching font}.  The variables in this section
2832 control how Emacs makes this selection.
2834 @defopt face-font-family-alternatives
2835 If a given family is specified but does not exist, this variable
2836 specifies alternative font families to try.  Each element should have
2837 this form:
2839 @example
2840 (@var{family} @var{alternate-families}@dots{})
2841 @end example
2843 If @var{family} is specified but not available, Emacs will try the other
2844 families given in @var{alternate-families}, one by one, until it finds a
2845 family that does exist.
2846 @end defopt
2848 @defopt face-font-selection-order
2849 If there is no font that exactly matches all desired face attributes
2850 (@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}),
2851 this variable specifies the order in which these attributes should be
2852 considered when selecting the closest matching font.  The value should
2853 be a list containing those four attribute symbols, in order of
2854 decreasing importance.  The default is @code{(:width :height :weight
2855 :slant)}.
2857 Font selection first finds the best available matches for the first
2858 attribute in the list; then, among the fonts which are best in that
2859 way, it searches for the best matches in the second attribute, and so
2862 The attributes @code{:weight} and @code{:width} have symbolic values in
2863 a range centered around @code{normal}.  Matches that are more extreme
2864 (farther from @code{normal}) are somewhat preferred to matches that are
2865 less extreme (closer to @code{normal}); this is designed to ensure that
2866 non-normal faces contrast with normal ones, whenever possible.
2868 One example of a case where this variable makes a difference is when the
2869 default font has no italic equivalent.  With the default ordering, the
2870 @code{italic} face will use a non-italic font that is similar to the
2871 default one.  But if you put @code{:slant} before @code{:height}, the
2872 @code{italic} face will use an italic font, even if its height is not
2873 quite right.
2874 @end defopt
2876 @defopt face-font-registry-alternatives
2877 This variable lets you specify alternative font registries to try, if a
2878 given registry is specified and doesn't exist.  Each element should have
2879 this form:
2881 @example
2882 (@var{registry} @var{alternate-registries}@dots{})
2883 @end example
2885 If @var{registry} is specified but not available, Emacs will try the
2886 other registries given in @var{alternate-registries}, one by one,
2887 until it finds a registry that does exist.
2888 @end defopt
2890   Emacs can make use of scalable fonts, but by default it does not use
2891 them.
2893 @defopt scalable-fonts-allowed
2894 This variable controls which scalable fonts to use.  A value of
2895 @code{nil}, the default, means do not use scalable fonts.  @code{t}
2896 means to use any scalable font that seems appropriate for the text.
2898 Otherwise, the value must be a list of regular expressions.  Then a
2899 scalable font is enabled for use if its name matches any regular
2900 expression in the list.  For example,
2902 @example
2903 (setq scalable-fonts-allowed '("muleindian-2$"))
2904 @end example
2906 @noindent
2907 allows the use of scalable fonts with registry @code{muleindian-2}.
2908 @end defopt
2910 @defvar face-font-rescale-alist
2911 This variable specifies scaling for certain faces.  Its value should
2912 be a list of elements of the form
2914 @example
2915 (@var{fontname-regexp} . @var{scale-factor})
2916 @end example
2918 If @var{fontname-regexp} matches the font name that is about to be
2919 used, this says to choose a larger similar font according to the
2920 factor @var{scale-factor}.  You would use this feature to normalize
2921 the font size if certain fonts are bigger or smaller than their
2922 nominal heights and widths would suggest.
2923 @end defvar
2925 @node Font Lookup
2926 @subsection Looking Up Fonts
2928 @defun x-list-fonts name &optional reference-face frame maximum width
2929 This function returns a list of available font names that match
2930 @var{name}.  @var{name} should be a string containing a font name in
2931 either the Fontconfig, GTK, or XLFD format (@pxref{Fonts,,, emacs, The
2932 GNU Emacs Manual}).  Within an XLFD string, wildcard characters may be
2933 used: the @samp{*} character matches any substring, and the @samp{?}
2934 character matches any single character.  Case is ignored when matching
2935 font names.
2937 If the optional arguments @var{reference-face} and @var{frame} are
2938 specified, the returned list includes only fonts that are the same
2939 size as @var{reference-face} (a face name) currently is on the frame
2940 @var{frame}.
2942 The optional argument @var{maximum} sets a limit on how many fonts to
2943 return.  If it is non-@code{nil}, then the return value is truncated
2944 after the first @var{maximum} matching fonts.  Specifying a small
2945 value for @var{maximum} can make this function much faster, in cases
2946 where many fonts match the pattern.
2948 The optional argument @var{width} specifies a desired font width.  If
2949 it is non-@code{nil}, the function only returns those fonts whose
2950 characters are (on average) @var{width} times as wide as
2951 @var{reference-face}.
2952 @end defun
2954 @defun x-family-fonts &optional family frame
2955 This function returns a list describing the available fonts for family
2956 @var{family} on @var{frame}.  If @var{family} is omitted or @code{nil},
2957 this list applies to all families, and therefore, it contains all
2958 available fonts.  Otherwise, @var{family} must be a string; it may
2959 contain the wildcards @samp{?} and @samp{*}.
2961 The list describes the display that @var{frame} is on; if @var{frame} is
2962 omitted or @code{nil}, it applies to the selected frame's display
2963 (@pxref{Input Focus}).
2965 Each element in the list is a vector of the following form:
2967 @example
2968 [@var{family} @var{width} @var{point-size} @var{weight} @var{slant}
2969  @var{fixed-p} @var{full} @var{registry-and-encoding}]
2970 @end example
2972 The first five elements correspond to face attributes; if you
2973 specify these attributes for a face, it will use this font.
2975 The last three elements give additional information about the font.
2976 @var{fixed-p} is non-@code{nil} if the font is fixed-pitch.
2977 @var{full} is the full name of the font, and
2978 @var{registry-and-encoding} is a string giving the registry and
2979 encoding of the font.
2980 @end defun
2982 @node Fontsets
2983 @subsection Fontsets
2985   A @dfn{fontset} is a list of fonts, each assigned to a range of
2986 character codes.  An individual font cannot display the whole range of
2987 characters that Emacs supports, but a fontset can.  Fontsets have names,
2988 just as fonts do, and you can use a fontset name in place of a font name
2989 when you specify the ``font'' for a frame or a face.  Here is
2990 information about defining a fontset under Lisp program control.
2992 @defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
2993 This function defines a new fontset according to the specification
2994 string @var{fontset-spec}.  The string should have this format:
2996 @smallexample
2997 @var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}}
2998 @end smallexample
3000 @noindent
3001 Whitespace characters before and after the commas are ignored.
3003 The first part of the string, @var{fontpattern}, should have the form of
3004 a standard X font name, except that the last two fields should be
3005 @samp{fontset-@var{alias}}.
3007 The new fontset has two names, one long and one short.  The long name is
3008 @var{fontpattern} in its entirety.  The short name is
3009 @samp{fontset-@var{alias}}.  You can refer to the fontset by either
3010 name.  If a fontset with the same name already exists, an error is
3011 signaled, unless @var{noerror} is non-@code{nil}, in which case this
3012 function does nothing.
3014 If optional argument @var{style-variant-p} is non-@code{nil}, that says
3015 to create bold, italic and bold-italic variants of the fontset as well.
3016 These variant fontsets do not have a short name, only a long one, which
3017 is made by altering @var{fontpattern} to indicate the bold or italic
3018 status.
3020 The specification string also says which fonts to use in the fontset.
3021 See below for the details.
3022 @end defun
3024   The construct @samp{@var{charset}:@var{font}} specifies which font to
3025 use (in this fontset) for one particular character set.  Here,
3026 @var{charset} is the name of a character set, and @var{font} is the font
3027 to use for that character set.  You can use this construct any number of
3028 times in the specification string.
3030   For the remaining character sets, those that you don't specify
3031 explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
3032 @samp{fontset-@var{alias}} with a value that names one character set.
3033 For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced
3034 with @samp{ISO8859-1}.
3036   In addition, when several consecutive fields are wildcards, Emacs
3037 collapses them into a single wildcard.  This is to prevent use of
3038 auto-scaled fonts.  Fonts made by scaling larger fonts are not usable
3039 for editing, and scaling a smaller font is not useful because it is
3040 better to use the smaller font in its own size, which Emacs does.
3042   Thus if @var{fontpattern} is this,
3044 @example
3045 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
3046 @end example
3048 @noindent
3049 the font specification for @acronym{ASCII} characters would be this:
3051 @example
3052 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
3053 @end example
3055 @noindent
3056 and the font specification for Chinese GB2312 characters would be this:
3058 @example
3059 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
3060 @end example
3062   You may not have any Chinese font matching the above font
3063 specification.  Most X distributions include only Chinese fonts that
3064 have @samp{song ti} or @samp{fangsong ti} in the @var{family} field.  In
3065 such a case, @samp{Fontset-@var{n}} can be specified as below:
3067 @smallexample
3068 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
3069         chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
3070 @end smallexample
3072 @noindent
3073 Then, the font specifications for all but Chinese GB2312 characters have
3074 @samp{fixed} in the @var{family} field, and the font specification for
3075 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
3076 field.
3078 @defun set-fontset-font name character font-spec &optional frame add
3079 This function modifies the existing fontset @var{name} to use the font
3080 matching with @var{font-spec} for the character @var{character}.
3082 If @var{name} is @code{nil}, this function modifies the fontset of the
3083 selected frame or that of @var{frame} if @var{frame} is not
3084 @code{nil}.
3086 If @var{name} is @code{t}, this function modifies the default
3087 fontset, whose short name is @samp{fontset-default}.
3089 @var{character} may be a cons; @code{(@var{from} . @var{to})}, where
3090 @var{from} and @var{to} are character codepoints.  In that case, use
3091 @var{font-spec} for all characters in the range @var{from} and @var{to}
3092 (inclusive).
3094 @var{character} may be a charset.  In that case, use
3095 @var{font-spec} for all character in the charsets.
3097 @var{character} may be a script name.  In that case, use
3098 @var{font-spec} for all character in the charsets.
3100 @var{font-spec} may be a cons; @code{(@var{family} . @var{registry})},
3101 where @var{family} is a family name of a font (possibly including a
3102 foundry name at the head), @var{registry} is a registry name of a font
3103 (possibly including an encoding name at the tail).
3105 @var{font-spec} may be a font name string.
3107 The optional argument @var{add}, if non-@code{nil}, specifies how to
3108 add @var{font-spec} to the font specifications previously set.  If it
3109 is @code{prepend}, @var{font-spec} is prepended.  If it is
3110 @code{append}, @var{font-spec} is appended.  By default,
3111 @var{font-spec} overrides the previous settings.
3113 For instance, this changes the default fontset to use a font of which
3114 family name is @samp{Kochi Gothic} for all characters belonging to
3115 the charset @code{japanese-jisx0208}.
3117 @smallexample
3118 (set-fontset-font t 'japanese-jisx0208
3119                   (font-spec :family "Kochi Gothic"))
3120 @end smallexample
3121 @end defun
3123 @defun char-displayable-p char
3124 This function returns @code{t} if Emacs ought to be able to display
3125 @var{char}.  More precisely, if the selected frame's fontset has a
3126 font to display the character set that @var{char} belongs to.
3128 Fontsets can specify a font on a per-character basis; when the fontset
3129 does that, this function's value may not be accurate.
3130 @end defun
3132 @node Low-Level Font
3133 @subsection Low-Level Font Representation
3135   Normally, it is not necessary to manipulate fonts directly.  In case
3136 you need to do so, this section explains how.
3138   In Emacs Lisp, fonts are represented using three different Lisp
3139 object types: @dfn{font objects}, @dfn{font specs}, and @dfn{font
3140 entities}.
3142 @defun fontp object &optional type
3143 Return @code{t} if @var{object} is a font object, font spec, or font
3144 entity.  Otherwise, return @code{nil}.
3146 The optional argument @var{type}, if non-@code{nil}, determines the
3147 exact type of Lisp object to check for.  In that case, @var{type}
3148 should be one of @code{font-object}, @code{font-spec}, or
3149 @code{font-entity}.
3150 @end defun
3152   A font object is a Lisp object that represents a font that Emacs has
3153 @dfn{opened}.  Font objects cannot be modified in Lisp, but they can
3154 be inspected.
3156 @defun font-at position &optional window string
3157 Return the font object that is being used to display the character at
3158 position @var{position} in the window @var{window}.  If @var{window}
3159 is @code{nil}, it defaults to the selected window.  If @var{string} is
3160 @code{nil}, @var{position} specifies a position in the current buffer;
3161 otherwise, @var{string} should be a string, and @var{position}
3162 specifies a position in that string.
3163 @end defun
3165   A font spec is a Lisp object that contains a set of specifications
3166 that can be used to find a font.  More than one font may match the
3167 specifications in a font spec.
3169 @defun font-spec &rest arguments
3170 Return a new font spec using the specifications in @var{arguments},
3171 which should come in @code{property}-@code{value} pairs.  The possible
3172 specifications are as follows:
3174 @table @code
3175 @item :name
3176 The font name (a string), in either XLFD, Fontconfig, or GTK format.
3177 @xref{Fonts,,, emacs, The GNU Emacs Manual}.
3179 @item :family
3180 @itemx :foundry
3181 @itemx :weight
3182 @itemx :slant
3183 @itemx :width
3184 These have the same meanings as the face attributes of the same name.
3185 @xref{Face Attributes}.
3187 @item :size
3188 The font size---either a non-negative integer that specifies the pixel
3189 size, or a floating point number that specifies the point size.
3191 @item :adstyle
3192 Additional typographic style information for the font, such as
3193 @samp{sans}.  The value should be a string or a symbol.
3195 @item :registry
3196 The charset registry and encoding of the font, such as
3197 @samp{iso8859-1}.  The value should be a string or a symbol.
3199 @item :script
3200 The script that the font must support (a symbol).
3202 @item :otf
3203 The font must be an OpenType font that supports these OpenType
3204 features, provided Emacs is compiled with support for @samp{libotf} (a
3205 library for performing complex text layout in certain scripts).  The
3206 value must be a list of the form
3208 @smallexample
3209 @code{(@var{script-tag} @var{langsys-tag} @var{gsub} @var{gpos})}
3210 @end smallexample
3212 where @var{script-tag} is the OpenType script tag symbol;
3213 @var{langsys-tag} is the OpenType language system tag symbol, or
3214 @code{nil} to use the default language system; @code{gsub} is a list
3215 of OpenType GSUB feature tag symbols, or @code{nil} if none is
3216 required; and @code{gpos} is a list of OpenType GPOS feature tag
3217 symbols, or @code{nil} if none is required.  If @code{gsub} or
3218 @code{gpos} is a list, a @code{nil} element in that list means that
3219 the font must not match any of the remaining tag symbols.  The
3220 @code{gpos} element may be omitted.
3221 @end table
3222 @end defun
3224 @defun font-put font-spec property value
3225 Set the font property @var{property} in the font-spec @var{font-spec}
3226 to @var{value}.
3227 @end defun
3229   A font entity is a reference to a font that need not be open.  Its
3230 properties are intermediate between a font object and a font spec:
3231 like a font object, and unlike a font spec, it refers to a single,
3232 specific font.  Unlike a font object, creating a font entity does not
3233 load the contents of that font into computer memory.
3235 @defun find-font font-spec &optional frame
3236 This function returns a font entity that best matches the font spec
3237 @var{font-spec} on frame @var{frame}.  If @var{frame} is @code{nil},
3238 it defaults to the selected frame.
3239 @end defun
3241 @defun list-fonts font-spec &optional frame num prefer
3242 This function returns a list of all font entities that match the font
3243 spec @var{font-spec}.
3245 The optional argument @var{frame}, if non-@code{nil}, specifies the
3246 frame on which the fonts are to be displayed.  The optional argument
3247 @var{num}, if non-@code{nil}, should be an integer that specifies the
3248 maximum length of the returned list.  The optional argument
3249 @var{prefer}, if non-@code{nil}, should be another font spec, which is
3250 used to control the order of the returned list; the returned font
3251 entities are sorted in order of decreasing ``closeness'' to that font
3252 spec.
3253 @end defun
3255   If you call @code{set-face-attribute} and pass a font spec, font
3256 entity, or font name string as the value of the @code{:font}
3257 attribute, Emacs opens the best ``matching'' font that is available
3258 for display.  It then stores the corresponding font object as the
3259 actual value of the @code{:font} attribute for that face.
3261   The following functions can be used to obtain information about a
3262 font.  For these functions, the @var{font} argument can be a font
3263 object, a font entity, or a font spec.
3265 @defun font-get font property
3266 This function returns the value of the font property @var{property}
3267 for @var{font}.
3269 If @var{font} is a font spec and the font spec does not specify
3270 @var{property}, the return value is @code{nil}.  If @var{font} is a
3271 font object or font entity, the value for the @var{:script} property
3272 may be a list of scripts supported by the font.
3273 @end defun
3275 @defun font-face-attributes font &optional frame
3276 This function returns a list of face attributes corresponding to
3277 @var{font}.  The optional argument @var{frame} specifies the frame on
3278 which the font is to be displayed.  If it is @code{nil}, the selected
3279 frame is used.  The return value has the form
3281 @smallexample
3282 (:family @var{family} :height @var{height} :weight @var{weight}
3283    :slant @var{slant} :width @var{width})
3284 @end smallexample
3286 where the values of @var{family}, @var{height}, @var{weight},
3287 @var{slant}, and @var{width} are face attribute values.  Some of these
3288 key-attribute pairs may be omitted from the list if they are not
3289 specified by @var{font}.
3290 @end defun
3292 @defun font-xlfd-name font &optional fold-wildcards
3293 This function returns the XLFD (X Logical Font Descriptor), a string,
3294 matching @var{font}.  @xref{Fonts,,, emacs, The GNU Emacs Manual}, for
3295 information about XLFDs.  If the name is too long for an XLFD (which
3296 can contain at most 255 characters), the function returns @code{nil}.
3298 If the optional argument @var{fold-wildcards} is non-@code{nil},
3299 consecutive wildcards in the XLFD are folded into one.
3300 @end defun
3302 @node Fringes
3303 @section Fringes
3304 @cindex fringes
3306   On graphical displays, Emacs draws @dfn{fringes} next to each
3307 window: thin vertical strips down the sides which can display bitmaps
3308 indicating truncation, continuation, horizontal scrolling, and so on.
3310 @menu
3311 * Fringe Size/Pos::     Specifying where to put the window fringes.
3312 * Fringe Indicators::   Displaying indicator icons in the window fringes.
3313 * Fringe Cursors::      Displaying cursors in the right fringe.
3314 * Fringe Bitmaps::      Specifying bitmaps for fringe indicators.
3315 * Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes.
3316 * Overlay Arrow::       Display of an arrow to indicate position.
3317 @end menu
3319 @node Fringe Size/Pos
3320 @subsection Fringe Size and Position
3322   The following buffer-local variables control the position and width
3323 of fringes in windows showing that buffer.
3325 @defvar fringes-outside-margins
3326 The fringes normally appear between the display margins and the window
3327 text.  If the value is non-@code{nil}, they appear outside the display
3328 margins.  @xref{Display Margins}.
3329 @end defvar
3331 @defvar left-fringe-width
3332 This variable, if non-@code{nil}, specifies the width of the left
3333 fringe in pixels.  A value of @code{nil} means to use the left fringe
3334 width from the window's frame.
3335 @end defvar
3337 @defvar right-fringe-width
3338 This variable, if non-@code{nil}, specifies the width of the right
3339 fringe in pixels.  A value of @code{nil} means to use the right fringe
3340 width from the window's frame.
3341 @end defvar
3343   Any buffer which does not specify values for these variables uses
3344 the values specified by the @code{left-fringe} and @code{right-fringe}
3345 frame parameters (@pxref{Layout Parameters}).
3347   The above variables actually take effect via the function
3348 @code{set-window-buffer} (@pxref{Buffers and Windows}), which calls
3349 @code{set-window-fringes} as a subroutine.  If you change one of these
3350 variables, the fringe display is not updated in existing windows
3351 showing the buffer, unless you call @code{set-window-buffer} again in
3352 each affected window.  You can also use @code{set-window-fringes} to
3353 control the fringe display in individual windows.
3355 @defun set-window-fringes window left &optional right outside-margins
3356 This function sets the fringe widths of window @var{window}.
3357 If @var{window} is @code{nil}, the selected window is used.
3359 The argument @var{left} specifies the width in pixels of the left
3360 fringe, and likewise @var{right} for the right fringe.  A value of
3361 @code{nil} for either one stands for the default width.  If
3362 @var{outside-margins} is non-@code{nil}, that specifies that fringes
3363 should appear outside of the display margins.
3364 @end defun
3366 @defun window-fringes &optional window
3367 This function returns information about the fringes of a window
3368 @var{window}.  If @var{window} is omitted or @code{nil}, the selected
3369 window is used.  The value has the form @code{(@var{left-width}
3370 @var{right-width} @var{outside-margins})}.
3371 @end defun
3374 @node Fringe Indicators
3375 @subsection Fringe Indicators
3376 @cindex fringe indicators
3377 @cindex indicators, fringe
3379   @dfn{Fringe indicators} are tiny icons displayed in the window
3380 fringe to indicate truncated or continued lines, buffer boundaries,
3381 etc.
3383 @defopt indicate-empty-lines
3384 @cindex fringes, and empty line indication
3385 When this is non-@code{nil}, Emacs displays a special glyph in the
3386 fringe of each empty line at the end of the buffer, on graphical
3387 displays.  @xref{Fringes}.  This variable is automatically
3388 buffer-local in every buffer.
3389 @end defopt
3391 @defopt indicate-buffer-boundaries
3392 This buffer-local variable controls how the buffer boundaries and
3393 window scrolling are indicated in the window fringes.
3395 Emacs can indicate the buffer boundaries---that is, the first and last
3396 line in the buffer---with angle icons when they appear on the screen.
3397 In addition, Emacs can display an up-arrow in the fringe to show
3398 that there is text above the screen, and a down-arrow to show
3399 there is text below the screen.
3401 There are three kinds of basic values:
3403 @table @asis
3404 @item @code{nil}
3405 Don't display any of these fringe icons.
3406 @item @code{left}
3407 Display the angle icons and arrows in the left fringe.
3408 @item @code{right}
3409 Display the angle icons and arrows in the right fringe.
3410 @item any non-alist
3411 Display the angle icons in the left fringe
3412 and don't display the arrows.
3413 @end table
3415 Otherwise the value should be an alist that specifies which fringe
3416 indicators to display and where.  Each element of the alist should
3417 have the form @code{(@var{indicator} . @var{position})}.  Here,
3418 @var{indicator} is one of @code{top}, @code{bottom}, @code{up},
3419 @code{down}, and @code{t} (which covers all the icons not yet
3420 specified), while @var{position} is one of @code{left}, @code{right}
3421 and @code{nil}.
3423 For example, @code{((top . left) (t . right))} places the top angle
3424 bitmap in left fringe, and the bottom angle bitmap as well as both
3425 arrow bitmaps in right fringe.  To show the angle bitmaps in the left
3426 fringe, and no arrow bitmaps, use @code{((top .  left) (bottom . left))}.
3427 @end defopt
3429 @defvar fringe-indicator-alist
3430 This buffer-local variable specifies the mapping from logical fringe
3431 indicators to the actual bitmaps displayed in the window fringes.  The
3432 value is an alist of elements @code{(@var{indicator}
3433 . @var{bitmaps})}, where @var{indicator} specifies a logical indicator
3434 type and @var{bitmaps} specifies the fringe bitmaps to use for that
3435 indicator.
3437   Each @var{indicator} should be one of the following symbols:
3439 @table @asis
3440 @item @code{truncation}, @code{continuation}.
3441 Used for truncation and continuation lines.
3443 @item @code{up}, @code{down}, @code{top}, @code{bottom}, @code{top-bottom}
3444 Used when @code{indicate-buffer-boundaries} is non-@code{nil}:
3445 @code{up} and @code{down} indicate a buffer boundary lying above or
3446 below the window edge; @code{top} and @code{bottom} indicate the
3447 topmost and bottommost buffer text line; and @code{top-bottom}
3448 indicates where there is just one line of text in the buffer.
3450 @item @code{empty-line}
3451 Used to indicate empty lines when @code{indicate-empty-lines} is
3452 non-@code{nil}.
3454 @item @code{overlay-arrow}
3455 Used for overlay arrows (@pxref{Overlay Arrow}).
3456 @c Is this used anywhere?
3457 @c @item Unknown bitmap indicator:
3458 @c @code{unknown}.
3459 @end table
3461   Each @var{bitmaps} value may be a list of symbols @code{(@var{left}
3462 @var{right} [@var{left1} @var{right1}])}.  The @var{left} and
3463 @var{right} symbols specify the bitmaps shown in the left and/or right
3464 fringe, for the specific indicator.  @var{left1} and @var{right1} are
3465 specific to the @code{bottom} and @code{top-bottom} indicators, and
3466 are used to indicate that the last text line has no final newline.
3467 Alternatively, @var{bitmaps} may be a single symbol which is used in
3468 both left and right fringes.
3470   @xref{Fringe Bitmaps}, for a list of standard bitmap symbols and how
3471 to define your own.  In addition, @code{nil} represents the empty
3472 bitmap (i.e.@: an indicator that is not shown).
3474   When @code{fringe-indicator-alist} has a buffer-local value, and
3475 there is no bitmap defined for a logical indicator, or the bitmap is
3476 @code{t}, the corresponding value from the default value of
3477 @code{fringe-indicator-alist} is used.
3478 @end defvar
3480 @node Fringe Cursors
3481 @subsection Fringe Cursors
3482 @cindex fringe cursors
3483 @cindex cursor, fringe
3485   When a line is exactly as wide as the window, Emacs displays the
3486 cursor in the right fringe instead of using two lines.  Different
3487 bitmaps are used to represent the cursor in the fringe depending on
3488 the current buffer's cursor type.
3490 @defopt overflow-newline-into-fringe
3491 If this is non-@code{nil}, lines exactly as wide as the window (not
3492 counting the final newline character) are not continued.  Instead,
3493 when point is at the end of the line, the cursor appears in the right
3494 fringe.
3495 @end defopt
3497 @defvar fringe-cursor-alist
3498 This variable specifies the mapping from logical cursor type to the
3499 actual fringe bitmaps displayed in the right fringe.  The value is an
3500 alist where each element has the form @code{(@var{cursor-type}
3501 . @var{bitmap})}, which means to use the fringe bitmap @var{bitmap} to
3502 display cursors of type @var{cursor-type}.
3504 Each @var{cursor-type} should be one of @code{box}, @code{hollow},
3505 @code{bar}, @code{hbar}, or @code{hollow-small}.  The first four have
3506 the same meanings as in the @code{cursor-type} frame parameter
3507 (@pxref{Cursor Parameters}).  The @code{hollow-small} type is used
3508 instead of @code{hollow} when the normal @code{hollow-rectangle}
3509 bitmap is too tall to fit on a specific display line.
3511 Each @var{bitmap} should be a symbol specifying the fringe bitmap to
3512 be displayed for that logical cursor type.
3513 @iftex
3514 See the next subsection for details.
3515 @end iftex
3516 @ifnottex
3517 @xref{Fringe Bitmaps}.
3518 @end ifnottex
3520 When @code{fringe-cursor-alist} has a buffer-local value, and there is
3521 no bitmap defined for a cursor type, the corresponding value from the
3522 default value of @code{fringes-indicator-alist} is used.
3523 @end defvar
3525 @node Fringe Bitmaps
3526 @subsection Fringe Bitmaps
3527 @cindex fringe bitmaps
3528 @cindex bitmaps, fringe
3530   The @dfn{fringe bitmaps} are the actual bitmaps which represent the
3531 logical fringe indicators for truncated or continued lines, buffer
3532 boundaries, overlay arrows, etc.  Each bitmap is represented by a
3533 symbol.
3534 @iftex
3535 These symbols are referred to by the variables
3536 @code{fringe-indicator-alist} and @code{fringe-cursor-alist},
3537 described in the previous subsections.
3538 @end iftex
3539 @ifnottex
3540 These symbols are referred to by the variable
3541 @code{fringe-indicator-alist}, which maps fringe indicators to bitmaps
3542 (@pxref{Fringe Indicators}), and the variable
3543 @code{fringe-cursor-alist}, which maps fringe cursors to bitmaps
3544 (@pxref{Fringe Cursors}).
3545 @end ifnottex
3547   Lisp programs can also directly display a bitmap in the left or
3548 right fringe, by using a @code{display} property for one of the
3549 characters appearing in the line (@pxref{Other Display Specs}).  Such
3550 a display specification has the form
3552 @example
3553 (@var{fringe} @var{bitmap} [@var{face}])
3554 @end example
3556 @noindent
3557 @var{fringe} is either the symbol @code{left-fringe} or
3558 @code{right-fringe}.  @var{bitmap} is a symbol identifying the bitmap
3559 to display.  The optional @var{face} names a face whose foreground
3560 color is used to display the bitmap; this face is automatically merged
3561 with the @code{fringe} face.
3563   Here is a list of the standard fringe bitmaps defined in Emacs, and
3564 how they are currently used in Emacs (via
3565 @code{fringe-indicator-alist} and @code{fringe-cursor-alist}):
3567 @table @asis
3568 @item @code{left-arrow}, @code{right-arrow}
3569 Used to indicate truncated lines.
3571 @item @code{left-curly-arrow}, @code{right-curly-arrow}
3572 Used to indicate continued lines.
3574 @item @code{right-triangle}, @code{left-triangle}
3575 The former is used by overlay arrows.  The latter is unused.
3577 @item @code{up-arrow}, @code{down-arrow}, @code{top-left-angle} @code{top-right-angle}
3578 @itemx @code{bottom-left-angle}, @code{bottom-right-angle}
3579 @itemx @code{top-right-angle}, @code{top-left-angle}
3580 @itemx @code{left-bracket}, @code{right-bracket}, @code{top-right-angle}, @code{top-left-angle}
3581 Used to indicate buffer boundaries.
3583 @item @code{filled-rectangle}, @code{hollow-rectangle}
3584 @itemx @code{filled-square}, @code{hollow-square}
3585 @itemx @code{vertical-bar}, @code{horizontal-bar}
3586 Used for different types of fringe cursors.
3588 @item @code{empty-line}, @code{exclamation-mark}, @code{question-mark}, @code{exclamation-mark}
3589 Not used by core Emacs features.
3590 @end table
3592 @noindent
3593 The next subsection describes how to define your own fringe bitmaps.
3595 @defun fringe-bitmaps-at-pos &optional pos window
3596 This function returns the fringe bitmaps of the display line
3597 containing position @var{pos} in window @var{window}.  The return
3598 value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left}
3599 is the symbol for the fringe bitmap in the left fringe (or @code{nil}
3600 if no bitmap), @var{right} is similar for the right fringe, and @var{ov}
3601 is non-@code{nil} if there is an overlay arrow in the left fringe.
3603 The value is @code{nil} if @var{pos} is not visible in @var{window}.
3604 If @var{window} is @code{nil}, that stands for the selected window.
3605 If @var{pos} is @code{nil}, that stands for the value of point in
3606 @var{window}.
3607 @end defun
3609 @node Customizing Bitmaps
3610 @subsection Customizing Fringe Bitmaps
3612 @defun define-fringe-bitmap bitmap bits &optional height width align
3613 This function defines the symbol @var{bitmap} as a new fringe bitmap,
3614 or replaces an existing bitmap with that name.
3616 The argument @var{bits} specifies the image to use.  It should be
3617 either a string or a vector of integers, where each element (an
3618 integer) corresponds to one row of the bitmap.  Each bit of an integer
3619 corresponds to one pixel of the bitmap, where the low bit corresponds
3620 to the rightmost pixel of the bitmap.
3622 The height is normally the length of @var{bits}.  However, you
3623 can specify a different height with non-@code{nil} @var{height}.  The width
3624 is normally 8, but you can specify a different width with non-@code{nil}
3625 @var{width}.  The width must be an integer between 1 and 16.
3627 The argument @var{align} specifies the positioning of the bitmap
3628 relative to the range of rows where it is used; the default is to
3629 center the bitmap.  The allowed values are @code{top}, @code{center},
3630 or @code{bottom}.
3632 The @var{align} argument may also be a list @code{(@var{align}
3633 @var{periodic})} where @var{align} is interpreted as described above.
3634 If @var{periodic} is non-@code{nil}, it specifies that the rows in
3635 @code{bits} should be repeated enough times to reach the specified
3636 height.
3637 @end defun
3639 @defun destroy-fringe-bitmap bitmap
3640 This function destroy the fringe bitmap identified by @var{bitmap}.
3641 If @var{bitmap} identifies a standard fringe bitmap, it actually
3642 restores the standard definition of that bitmap, instead of
3643 eliminating it entirely.
3644 @end defun
3646 @defun set-fringe-bitmap-face bitmap &optional face
3647 This sets the face for the fringe bitmap @var{bitmap} to @var{face}.
3648 If @var{face} is @code{nil}, it selects the @code{fringe} face.  The
3649 bitmap's face controls the color to draw it in.
3651 @var{face} is merged with the @code{fringe} face, so normally
3652 @var{face} should specify only the foreground color.
3653 @end defun
3655 @node Overlay Arrow
3656 @subsection The Overlay Arrow
3657 @c @cindex overlay arrow  Duplicates variable names
3659   The @dfn{overlay arrow} is useful for directing the user's attention
3660 to a particular line in a buffer.  For example, in the modes used for
3661 interface to debuggers, the overlay arrow indicates the line of code
3662 about to be executed.  This feature has nothing to do with
3663 @dfn{overlays} (@pxref{Overlays}).
3665 @defvar overlay-arrow-string
3666 This variable holds the string to display to call attention to a
3667 particular line, or @code{nil} if the arrow feature is not in use.
3668 On a graphical display the contents of the string are ignored; instead a
3669 glyph is displayed in the fringe area to the left of the display area.
3670 @end defvar
3672 @defvar overlay-arrow-position
3673 This variable holds a marker that indicates where to display the overlay
3674 arrow.  It should point at the beginning of a line.  On a non-graphical
3675 display the arrow text
3676 appears at the beginning of that line, overlaying any text that would
3677 otherwise appear.  Since the arrow is usually short, and the line
3678 usually begins with indentation, normally nothing significant is
3679 overwritten.
3681 The overlay-arrow string is displayed in any given buffer if the value
3682 of @code{overlay-arrow-position} in that buffer points into that
3683 buffer.  Thus, it is possible to display multiple overlay arrow strings
3684 by creating buffer-local bindings of @code{overlay-arrow-position}.
3685 However, it is usually cleaner to use
3686 @code{overlay-arrow-variable-list} to achieve this result.
3687 @c !!! overlay-arrow-position: but the overlay string may remain in the display
3688 @c of some other buffer until an update is required.  This should be fixed
3689 @c now.  Is it?
3690 @end defvar
3692   You can do a similar job by creating an overlay with a
3693 @code{before-string} property.  @xref{Overlay Properties}.
3695   You can define multiple overlay arrows via the variable
3696 @code{overlay-arrow-variable-list}.
3698 @defvar overlay-arrow-variable-list
3699 This variable's value is a list of variables, each of which specifies
3700 the position of an overlay arrow.  The variable
3701 @code{overlay-arrow-position} has its normal meaning because it is on
3702 this list.
3703 @end defvar
3705 Each variable on this list can have properties
3706 @code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that
3707 specify an overlay arrow string (for text terminals) or fringe bitmap
3708 (for graphical terminals) to display at the corresponding overlay
3709 arrow position.  If either property is not set, the default
3710 @code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator
3711 is used.
3713 @node Scroll Bars
3714 @section Scroll Bars
3715 @cindex scroll bars
3717 Normally the frame parameter @code{vertical-scroll-bars} controls
3718 whether the windows in the frame have vertical scroll bars, and
3719 whether they are on the left or right.  The frame parameter
3720 @code{scroll-bar-width} specifies how wide they are (@code{nil}
3721 meaning the default).  @xref{Layout Parameters}.
3723 @defun frame-current-scroll-bars &optional frame
3724 This function reports the scroll bar type settings for frame
3725 @var{frame}.  The value is a cons cell
3726 @code{(@var{vertical-type} .@: @var{horizontal-type})}, where
3727 @var{vertical-type} is either @code{left}, @code{right}, or @code{nil}
3728 (which means no scroll bar.)  @var{horizontal-type} is meant to
3729 specify the horizontal scroll bar type, but since they are not
3730 implemented, it is always @code{nil}.
3731 @end defun
3733 @vindex vertical-scroll-bar
3734   You can enable or disable scroll bars for a particular buffer,
3735 by setting the variable @code{vertical-scroll-bar}.  This variable
3736 automatically becomes buffer-local when set.  The possible values are
3737 @code{left}, @code{right}, @code{t}, which means to use the
3738 frame's default, and @code{nil} for no scroll bar.
3740   You can also control this for individual windows.  Call the function
3741 @code{set-window-scroll-bars} to specify what to do for a specific window:
3743 @defun set-window-scroll-bars window width &optional vertical-type horizontal-type
3744 This function sets the width and type of scroll bars for window
3745 @var{window}.
3747 @var{width} specifies the scroll bar width in pixels (@code{nil} means
3748 use the width specified for the frame).  @var{vertical-type} specifies
3749 whether to have a vertical scroll bar and, if so, where.  The possible
3750 values are @code{left}, @code{right} and @code{nil}, just like the
3751 values of the @code{vertical-scroll-bars} frame parameter.
3753 The argument @var{horizontal-type} is meant to specify whether and
3754 where to have horizontal scroll bars, but since they are not
3755 implemented, it has no effect.  If @var{window} is @code{nil}, the
3756 selected window is used.
3757 @end defun
3759 @defun window-scroll-bars &optional window
3760 Report the width and type of scroll bars specified for @var{window}.
3761 If @var{window} is omitted or @code{nil}, the selected window is used.
3762 The value is a list of the form @code{(@var{width}
3763 @var{cols} @var{vertical-type} @var{horizontal-type})}.  The value
3764 @var{width} is the value that was specified for the width (which may
3765 be @code{nil}); @var{cols} is the number of columns that the scroll
3766 bar actually occupies.
3768 @var{horizontal-type} is not actually meaningful.
3769 @end defun
3771 If you don't specify these values for a window with
3772 @code{set-window-scroll-bars}, the buffer-local variables
3773 @code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being
3774 displayed control the window's vertical scroll bars.  The function
3775 @code{set-window-buffer} examines these variables.  If you change them
3776 in a buffer that is already visible in a window, you can make the
3777 window take note of the new values by calling @code{set-window-buffer}
3778 specifying the same buffer that is already displayed.
3780 @defopt scroll-bar-mode
3781 This variable, always local in all buffers, controls whether and where
3782 to put scroll bars in windows displaying the buffer.  The possible values
3783 are @code{nil} for no scroll bar, @code{left} to put a scroll bar on
3784 the left, and @code{right} to put a scroll bar on the right.
3785 @end defopt
3787 @defun window-current-scroll-bars &optional window
3788 This function reports the scroll bar type for window @var{window}.
3789 If @var{window} is omitted or @code{nil}, the selected window is used.
3790 The value is a cons cell
3791 @code{(@var{vertical-type} .@: @var{horizontal-type})}.  Unlike
3792 @code{window-scroll-bars}, this reports the scroll bar type actually
3793 used, once frame defaults and @code{scroll-bar-mode} are taken into
3794 account.
3795 @end defun
3797 @defvar scroll-bar-width
3798 This variable, always local in all buffers, specifies the width of the
3799 buffer's scroll bars, measured in pixels.  A value of @code{nil} means
3800 to use the value specified by the frame.
3801 @end defvar
3803 @node Display Property
3804 @section The @code{display} Property
3805 @cindex display specification
3806 @kindex display @r{(text property)}
3808   The @code{display} text property (or overlay property) is used to
3809 insert images into text, and to control other aspects of how text
3810 displays.  The value of the @code{display} property should be a
3811 display specification, or a list or vector containing several display
3812 specifications.  Display specifications in the same @code{display}
3813 property value generally apply in parallel to the text they cover.
3815   If several sources (overlays and/or a text property) specify values
3816 for the @code{display} property, only one of the values takes effect,
3817 following the rules of @code{get-char-property}.  @xref{Examining
3818 Properties}.
3820   The rest of this section describes several kinds of
3821 display specifications and what they mean.
3823 @menu
3824 * Replacing Specs::      Display specs that replace the text.
3825 * Specified Space::      Displaying one space with a specified width.
3826 * Pixel Specification::  Specifying space width or height in pixels.
3827 * Other Display Specs::     Displaying an image; adjusting the height,
3828                               spacing, and other properties of text.
3829 * Display Margins::     Displaying text or images to the side of the main text.
3830 @end menu
3832 @node Replacing Specs
3833 @subsection Display Specs That Replace The Text
3835   Some kinds of display specifications specify something to display
3836 instead of the text that has the property.  These are called
3837 @dfn{replacing} display specifications.  Emacs does not allow the user
3838 to interactively move point into the middle of buffer text that is
3839 replaced in this way.
3841   If a list of display specifications includes more than one replacing
3842 display specification, the first overrides the rest.  Replacing
3843 display specifications make most other display specifications
3844 irrelevant, since those don't apply to the replacement.
3846   For replacing display specifications, ``the text that has the
3847 property'' means all the consecutive characters that have the same
3848 Lisp object as their @code{display} property; these characters are
3849 replaced as a single unit.  If two characters have different Lisp
3850 objects as their @code{display} properties (i.e.@: objects which are
3851 not @code{eq}), they are handled separately.
3853   Here is an example which illustrates this point.  A string serves as
3854 a replacing display specification, which replaces the text that has
3855 the property with the specified string (@pxref{Other Display Specs}).
3856 Consider the following function:
3858 @smallexample
3859 (defun foo ()
3860   (dotimes (i 5)
3861     (let ((string (concat "A"))
3862           (start (+ i i (point-min))))
3863       (put-text-property start (1+ start) 'display string)
3864       (put-text-property start (+ 2 start) 'display string))))
3865 @end smallexample
3867 @noindent
3868 This function gives each of the first ten characters in the buffer a
3869 @code{display} property which is a string @code{"A"}, but they don't
3870 all get the same string object.  The first two characters get the same
3871 string object, so they are replaced with one @samp{A}; the fact that
3872 the display property was assigned in two separate calls to
3873 @code{put-text-property} is irrelevant.  Similarly, the next two
3874 characters get a second string (@code{concat} creates a new string
3875 object), so they are replaced with one @samp{A}; and so on.  Thus, the
3876 ten characters appear as five A's.
3878 @node Specified Space
3879 @subsection Specified Spaces
3880 @cindex spaces, specified height or width
3881 @cindex variable-width spaces
3883   To display a space of specified width and/or height, use a display
3884 specification of the form @code{(space . @var{props})}, where
3885 @var{props} is a property list (a list of alternating properties and
3886 values).  You can put this property on one or more consecutive
3887 characters; a space of the specified height and width is displayed in
3888 place of @emph{all} of those characters.  These are the properties you
3889 can use in @var{props} to specify the weight of the space:
3891 @table @code
3892 @item :width @var{width}
3893 If @var{width} is an integer or floating point number, it specifies
3894 that the space width should be @var{width} times the normal character
3895 width.  @var{width} can also be a @dfn{pixel width} specification
3896 (@pxref{Pixel Specification}).
3898 @item :relative-width @var{factor}
3899 Specifies that the width of the stretch should be computed from the
3900 first character in the group of consecutive characters that have the
3901 same @code{display} property.  The space width is the width of that
3902 character, multiplied by @var{factor}.
3904 @item :align-to @var{hpos}
3905 Specifies that the space should be wide enough to reach @var{hpos}.
3906 If @var{hpos} is a number, it is measured in units of the normal
3907 character width.  @var{hpos} can also be a @dfn{pixel width}
3908 specification (@pxref{Pixel Specification}).
3909 @end table
3911   You should use one and only one of the above properties.  You can
3912 also specify the height of the space, with these properties:
3914 @table @code
3915 @item :height @var{height}
3916 Specifies the height of the space.
3917 If @var{height} is an integer or floating point number, it specifies
3918 that the space height should be @var{height} times the normal character
3919 height.  The @var{height} may also be a @dfn{pixel height} specification
3920 (@pxref{Pixel Specification}).
3922 @item :relative-height @var{factor}
3923 Specifies the height of the space, multiplying the ordinary height
3924 of the text having this display specification by @var{factor}.
3926 @item :ascent @var{ascent}
3927 If the value of @var{ascent} is a non-negative number no greater than
3928 100, it specifies that @var{ascent} percent of the height of the space
3929 should be considered as the ascent of the space---that is, the part
3930 above the baseline.  The ascent may also be specified in pixel units
3931 with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}).
3933 @end table
3935   Don't use both @code{:height} and @code{:relative-height} together.
3937   The @code{:width} and @code{:align-to} properties are supported on
3938 non-graphic terminals, but the other space properties in this section
3939 are not.
3941   Note that space properties are treated as paragraph separators for
3942 the purposes of reordering bidirectional text for display.
3943 @xref{Bidirectional Display}, for the details.
3945 @node Pixel Specification
3946 @subsection Pixel Specification for Spaces
3947 @cindex spaces, pixel specification
3949   The value of the @code{:width}, @code{:align-to}, @code{:height},
3950 and @code{:ascent} properties can be a special kind of expression that
3951 is evaluated during redisplay.  The result of the evaluation is used
3952 as an absolute number of pixels.
3954   The following expressions are supported:
3956 @smallexample
3957 @group
3958   @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form}
3959   @var{num}  ::= @var{integer} | @var{float} | @var{symbol}
3960   @var{unit} ::= in | mm | cm | width | height
3961 @end group
3962 @group
3963   @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin
3964         |  scroll-bar | text
3965   @var{pos}  ::= left | center | right
3966   @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...)
3967   @var{op}   ::= + | -
3968 @end group
3969 @end smallexample
3971   The form @var{num} specifies a fraction of the default frame font
3972 height or width.  The form @code{(@var{num})} specifies an absolute
3973 number of pixels.  If @var{num} is a symbol, @var{symbol}, its
3974 buffer-local variable binding is used.
3976   The @code{in}, @code{mm}, and @code{cm} units specify the number of
3977 pixels per inch, millimeter, and centimeter, respectively.  The
3978 @code{width} and @code{height} units correspond to the default width
3979 and height of the current face.  An image specification @code{image}
3980 corresponds to the width or height of the image.
3982   The elements @code{left-fringe}, @code{right-fringe},
3983 @code{left-margin}, @code{right-margin}, @code{scroll-bar}, and
3984 @code{text} specify to the width of the corresponding area of the
3985 window.
3987   The @code{left}, @code{center}, and @code{right} positions can be
3988 used with @code{:align-to} to specify a position relative to the left
3989 edge, center, or right edge of the text area.
3991   Any of the above window elements (except @code{text}) can also be
3992 used with @code{:align-to} to specify that the position is relative to
3993 the left edge of the given area.  Once the base offset for a relative
3994 position has been set (by the first occurrence of one of these
3995 symbols), further occurrences of these symbols are interpreted as the
3996 width of the specified area.  For example, to align to the center of
3997 the left-margin, use
3999 @example
4000 :align-to (+ left-margin (0.5 . left-margin))
4001 @end example
4003   If no specific base offset is set for alignment, it is always relative
4004 to the left edge of the text area.  For example, @samp{:align-to 0} in a
4005 header-line aligns with the first text column in the text area.
4007   A value of the form @code{(@var{num} . @var{expr})} stands for the
4008 product of the values of @var{num} and @var{expr}.  For example,
4009 @code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 .
4010 @var{image})} specifies half the width (or height) of the specified
4011 image.
4013   The form @code{(+ @var{expr} ...)} adds up the value of the
4014 expressions.  The form @code{(- @var{expr} ...)} negates or subtracts
4015 the value of the expressions.
4017 @node Other Display Specs
4018 @subsection Other Display Specifications
4020   Here are the other sorts of display specifications that you can use
4021 in the @code{display} text property.
4023 @table @code
4024 @item @var{string}
4025 Display @var{string} instead of the text that has this property.
4027 Recursive display specifications are not supported---@var{string}'s
4028 @code{display} properties, if any, are not used.
4030 @item (image . @var{image-props})
4031 This kind of display specification is an image descriptor (@pxref{Images}).
4032 When used as a display specification, it means to display the image
4033 instead of the text that has the display specification.
4035 @item (slice @var{x} @var{y} @var{width} @var{height})
4036 This specification together with @code{image} specifies a @dfn{slice}
4037 (a partial area) of the image to display.  The elements @var{y} and
4038 @var{x} specify the top left corner of the slice, within the image;
4039 @var{width} and @var{height} specify the width and height of the
4040 slice.  Integer values are numbers of pixels.  A floating point number
4041 in the range 0.0--1.0 stands for that fraction of the width or height
4042 of the entire image.
4044 @item ((margin nil) @var{string})
4045 A display specification of this form means to display @var{string}
4046 instead of the text that has the display specification, at the same
4047 position as that text.  It is equivalent to using just @var{string},
4048 but it is done as a special case of marginal display (@pxref{Display
4049 Margins}).
4051 @item (left-fringe @var{bitmap} @r{[}@var{face}@r{]})
4052 @itemx (right-fringe @var{bitmap} @r{[}@var{face}@r{]})
4053 This display specification on any character of a line of text causes
4054 the specified @var{bitmap} be displayed in the left or right fringes
4055 for that line, instead of the characters that have the display
4056 specification.  The optional @var{face} specifies the colors to be
4057 used for the bitmap.  @xref{Fringe Bitmaps}, for the details.
4059 @item (space-width @var{factor})
4060 This display specification affects all the space characters within the
4061 text that has the specification.  It displays all of these spaces
4062 @var{factor} times as wide as normal.  The element @var{factor} should
4063 be an integer or float.  Characters other than spaces are not affected
4064 at all; in particular, this has no effect on tab characters.
4066 @item (height @var{height})
4067 This display specification makes the text taller or shorter.
4068 Here are the possibilities for @var{height}:
4070 @table @asis
4071 @item @code{(+ @var{n})}
4072 This means to use a font that is @var{n} steps larger.  A ``step'' is
4073 defined by the set of available fonts---specifically, those that match
4074 what was otherwise specified for this text, in all attributes except
4075 height.  Each size for which a suitable font is available counts as
4076 another step.  @var{n} should be an integer.
4078 @item @code{(- @var{n})}
4079 This means to use a font that is @var{n} steps smaller.
4081 @item a number, @var{factor}
4082 A number, @var{factor}, means to use a font that is @var{factor} times
4083 as tall as the default font.
4085 @item a symbol, @var{function}
4086 A symbol is a function to compute the height.  It is called with the
4087 current height as argument, and should return the new height to use.
4089 @item anything else, @var{form}
4090 If the @var{height} value doesn't fit the previous possibilities, it is
4091 a form.  Emacs evaluates it to get the new height, with the symbol
4092 @code{height} bound to the current specified font height.
4093 @end table
4095 @item (raise @var{factor})
4096 This kind of display specification raises or lowers the text
4097 it applies to, relative to the baseline of the line.
4099 @var{factor} must be a number, which is interpreted as a multiple of the
4100 height of the affected text.  If it is positive, that means to display
4101 the characters raised.  If it is negative, that means to display them
4102 lower down.
4104 If the text also has a @code{height} display specification, that does
4105 not affect the amount of raising or lowering, which is based on the
4106 faces used for the text.
4107 @end table
4109 @c We put all the `@code{(when ...)}' on one line to encourage
4110 @c makeinfo's end-of-sentence heuristics to DTRT.  Previously, the dot
4111 @c was at eol; the info file ended up w/ two spaces rendered after it.
4112   You can make any display specification conditional.  To do that,
4113 package it in another list of the form
4114 @code{(when @var{condition} . @var{spec})}.
4115 Then the specification @var{spec} applies only when
4116 @var{condition} evaluates to a non-@code{nil} value.  During the
4117 evaluation, @code{object} is bound to the string or buffer having the
4118 conditional @code{display} property.  @code{position} and
4119 @code{buffer-position} are bound to the position within @code{object}
4120 and the buffer position where the @code{display} property was found,
4121 respectively.  Both positions can be different when @code{object} is a
4122 string.
4124 @node Display Margins
4125 @subsection Displaying in the Margins
4126 @cindex display margins
4127 @cindex margins, display
4129   A buffer can have blank areas called @dfn{display margins} on the
4130 left and on the right.  Ordinary text never appears in these areas,
4131 but you can put things into the display margins using the
4132 @code{display} property.  There is currently no way to make text or
4133 images in the margin mouse-sensitive.
4135   The way to display something in the margins is to specify it in a
4136 margin display specification in the @code{display} property of some
4137 text.  This is a replacing display specification, meaning that the
4138 text you put it on does not get displayed; the margin display appears,
4139 but that text does not.
4141   A margin display specification looks like @code{((margin
4142 right-margin) @var{spec})} or @code{((margin left-margin) @var{spec})}.
4143 Here, @var{spec} is another display specification that says what to
4144 display in the margin.  Typically it is a string of text to display,
4145 or an image descriptor.
4147   To display something in the margin @emph{in association with}
4148 certain buffer text, without altering or preventing the display of
4149 that text, put a @code{before-string} property on the text and put the
4150 margin display specification on the contents of the before-string.
4152   Before the display margins can display anything, you must give
4153 them a nonzero width.  The usual way to do that is to set these
4154 variables:
4156 @defvar left-margin-width
4157 This variable specifies the width of the left margin.
4158 It is buffer-local in all buffers.
4159 @end defvar
4161 @defvar right-margin-width
4162 This variable specifies the width of the right margin.
4163 It is buffer-local in all buffers.
4164 @end defvar
4166   Setting these variables does not immediately affect the window.  These
4167 variables are checked when a new buffer is displayed in the window.
4168 Thus, you can make changes take effect by calling
4169 @code{set-window-buffer}.
4171   You can also set the margin widths immediately.
4173 @defun set-window-margins window left &optional right
4174 This function specifies the margin widths for window @var{window}.
4175 The argument @var{left} controls the left margin and
4176 @var{right} controls the right margin (default @code{0}).
4177 @end defun
4179 @defun window-margins &optional window
4180 This function returns the left and right margins of @var{window}
4181 as a cons cell of the form @code{(@var{left} . @var{right})}.
4182 If @var{window} is @code{nil}, the selected window is used.
4183 @end defun
4185 @node Images
4186 @section Images
4187 @cindex images in buffers
4189   To display an image in an Emacs buffer, you must first create an image
4190 descriptor, then use it as a display specifier in the @code{display}
4191 property of text that is displayed (@pxref{Display Property}).
4193   Emacs is usually able to display images when it is run on a
4194 graphical terminal.  Images cannot be displayed in a text terminal, on
4195 certain graphical terminals that lack the support for this, or if
4196 Emacs is compiled without image support.  You can use the function
4197 @code{display-images-p} to determine if images can in principle be
4198 displayed (@pxref{Display Feature Testing}).
4200 @menu
4201 * Image Formats::       Supported image formats.
4202 * Image Descriptors::   How to specify an image for use in @code{:display}.
4203 * XBM Images::          Special features for XBM format.
4204 * XPM Images::          Special features for XPM format.
4205 * GIF Images::          Special features for GIF format.
4206 * TIFF Images::         Special features for TIFF format.
4207 * PostScript Images::   Special features for PostScript format.
4208 * ImageMagick Images::  Special features available through ImageMagick.
4209 * Other Image Types::   Various other formats are supported.
4210 * Defining Images::     Convenient ways to define an image for later use.
4211 * Showing Images::      Convenient ways to display an image once it is defined.
4212 * Animated Images::     Some image formats can be animated.
4213 * Image Cache::         Internal mechanisms of image display.
4214 @end menu
4216 @node Image Formats
4217 @subsection Image Formats
4218 @cindex image formats
4219 @cindex image types
4221   Emacs can display a number of different image formats.  Some of
4222 these image formats are supported only if particular support libraries
4223 are installed.  On some platforms, Emacs can load support libraries on
4224 demand; if so, the variable @code{dynamic-library-alist} can be used
4225 to modify the set of known names for these dynamic libraries.
4226 @xref{Dynamic Libraries}.
4228   Supported image formats (and the required support libraries) include
4229 PBM and XBM (which do not depend on support libraries and are always
4230 available), XPM (@code{libXpm}), GIF (@code{libgif} or
4231 @code{libungif}), PostScript (@code{gs}), JPEG (@code{libjpeg}), TIFF
4232 (@code{libtiff}), PNG (@code{libpng}), and SVG (@code{librsvg}).
4234   Each of these image formats is associated with an @dfn{image type
4235 symbol}.  The symbols for the above formats are, respectively,
4236 @code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
4237 @code{jpeg}, @code{tiff}, @code{png}, and @code{svg}.
4239   Furthermore, if you build Emacs with ImageMagick
4240 (@code{libMagickWand}) support, Emacs can display any image format
4241 that ImageMagick can.  @xref{ImageMagick Images}.  All images
4242 displayed via ImageMagick have type symbol @code{imagemagick}.
4244 @defvar image-types
4245 This variable contains a list of type symbols for image formats which
4246 are potentially supported in the current configuration.
4248 ``Potentially'' means that Emacs knows about the image types, not
4249 necessarily that they can be used (for example, they could depend on
4250 unavailable dynamic libraries).  To know which image types are really
4251 available, use @code{image-type-available-p}.
4252 @end defvar
4254 @defun image-type-available-p type
4255 This function returns non-@code{nil} if images of type @var{type} can
4256 be loaded and displayed.  @var{type} must be an image type symbol.
4258 For image types whose support libraries are statically linked, this
4259 function always returns @code{t}.  For image types whose support
4260 libraries are dynamically loaded, it returns @code{t} if the library
4261 could be loaded and @code{nil} otherwise.
4262 @end defun
4264 @node Image Descriptors
4265 @subsection Image Descriptors
4266 @cindex image descriptor
4268   An @dfn{image descriptor} is a list which specifies the underlying
4269 data for an image, and how to display it.  It is typically used as the
4270 value of a @code{display} overlay or text property (@pxref{Other
4271 Display Specs}); but @xref{Showing Images}, for convenient helper
4272 functions to insert images into buffers.
4274   Each image descriptor has the form @code{(image . @var{props})},
4275 where @var{props} is a property list of alternating keyword symbols
4276 and values, including at least the pair @code{:type @var{TYPE}} which
4277 specifies the image type.
4279   The following is a list of properties that are meaningful for all
4280 image types (there are also properties which are meaningful only for
4281 certain image types, as documented in the following subsections):
4283 @table @code
4284 @item :type @var{type}
4285 The image type.
4286 @ifnottex
4287 @xref{Image Formats}.
4288 @end ifnottex
4289 Every image descriptor must include this property.
4291 @item :file @var{file}
4292 This says to load the image from file @var{file}.  If @var{file} is
4293 not an absolute file name, it is expanded in @code{data-directory}.
4295 @item :data @var{data}
4296 This specifies the raw image data.  Each image descriptor must have
4297 either @code{:data} or @code{:file}, but not both.
4299 For most image types, the value of a @code{:data} property should be a
4300 string containing the image data.  Some image types do not support
4301 @code{:data}; for some others, @code{:data} alone is not enough, so
4302 you need to use other image properties along with @code{:data}.  See
4303 the following subsections for details.
4305 @item :margin @var{margin}
4306 This specifies how many pixels to add as an extra margin around the
4307 image.  The value, @var{margin}, must be a non-negative number, or a
4308 pair @code{(@var{x} . @var{y})} of such numbers.  If it is a pair,
4309 @var{x} specifies how many pixels to add horizontally, and @var{y}
4310 specifies how many pixels to add vertically.  If @code{:margin} is not
4311 specified, the default is zero.
4313 @item :ascent @var{ascent}
4314 This specifies the amount of the image's height to use for its
4315 ascent---that is, the part above the baseline.  The value,
4316 @var{ascent}, must be a number in the range 0 to 100, or the symbol
4317 @code{center}.
4319 If @var{ascent} is a number, that percentage of the image's height is
4320 used for its ascent.
4322 If @var{ascent} is @code{center}, the image is vertically centered
4323 around a centerline which would be the vertical centerline of text drawn
4324 at the position of the image, in the manner specified by the text
4325 properties and overlays that apply to the image.
4327 If this property is omitted, it defaults to 50.
4329 @item :relief @var{relief}
4330 This adds a shadow rectangle around the image.  The value,
4331 @var{relief}, specifies the width of the shadow lines, in pixels.  If
4332 @var{relief} is negative, shadows are drawn so that the image appears
4333 as a pressed button; otherwise, it appears as an unpressed button.
4335 @item :conversion @var{algorithm}
4336 This specifies a conversion algorithm that should be applied to the
4337 image before it is displayed; the value, @var{algorithm}, specifies
4338 which algorithm.
4340 @table @code
4341 @item laplace
4342 @itemx emboss
4343 Specifies the Laplace edge detection algorithm, which blurs out small
4344 differences in color while highlighting larger differences.  People
4345 sometimes consider this useful for displaying the image for a
4346 ``disabled'' button.
4348 @item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
4349 Specifies a general edge-detection algorithm.  @var{matrix} must be
4350 either a nine-element list or a nine-element vector of numbers.  A pixel
4351 at position @math{x/y} in the transformed image is computed from
4352 original pixels around that position.  @var{matrix} specifies, for each
4353 pixel in the neighborhood of @math{x/y}, a factor with which that pixel
4354 will influence the transformed pixel; element @math{0} specifies the
4355 factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for
4356 the pixel at @math{x/y-1} etc., as shown below:
4357 @iftex
4358 @tex
4359 $$\pmatrix{x-1/y-1 & x/y-1  & x+1/y-1 \cr
4360    x-1/y  &   x/y &    x+1/y \cr
4361    x-1/y+1&   x/y+1 &  x+1/y+1 \cr}$$
4362 @end tex
4363 @end iftex
4364 @ifnottex
4365 @display
4366   (x-1/y-1  x/y-1  x+1/y-1
4367    x-1/y    x/y    x+1/y
4368    x-1/y+1  x/y+1  x+1/y+1)
4369 @end display
4370 @end ifnottex
4372 The resulting pixel is computed from the color intensity of the color
4373 resulting from summing up the RGB values of surrounding pixels,
4374 multiplied by the specified factors, and dividing that sum by the sum
4375 of the factors' absolute values.
4377 Laplace edge-detection currently uses a matrix of
4378 @iftex
4379 @tex
4380 $$\pmatrix{1 & 0 & 0 \cr
4381    0&  0 &  0 \cr
4382    0 & 0 & -1 \cr}$$
4383 @end tex
4384 @end iftex
4385 @ifnottex
4386 @display
4387   (1  0  0
4388    0  0  0
4389    0  0 -1)
4390 @end display
4391 @end ifnottex
4393 Emboss edge-detection uses a matrix of
4394 @iftex
4395 @tex
4396 $$\pmatrix{ 2 & -1 &  0 \cr
4397    -1 &  0 &  1 \cr
4398     0  & 1 & -2 \cr}$$
4399 @end tex
4400 @end iftex
4401 @ifnottex
4402 @display
4403   ( 2 -1  0
4404    -1  0  1
4405     0  1 -2)
4406 @end display
4407 @end ifnottex
4409 @item disabled
4410 Specifies transforming the image so that it looks ``disabled''.
4411 @end table
4413 @item :mask @var{mask}
4414 If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build
4415 a clipping mask for the image, so that the background of a frame is
4416 visible behind the image.  If @var{bg} is not specified, or if @var{bg}
4417 is @code{t}, determine the background color of the image by looking at
4418 the four corners of the image, assuming the most frequently occurring
4419 color from the corners is the background color of the image.  Otherwise,
4420 @var{bg} must be a list @code{(@var{red} @var{green} @var{blue})}
4421 specifying the color to assume for the background of the image.
4423 If @var{mask} is @code{nil}, remove a mask from the image, if it has
4424 one.  Images in some formats include a mask which can be removed by
4425 specifying @code{:mask nil}.
4427 @item :pointer @var{shape}
4428 This specifies the pointer shape when the mouse pointer is over this
4429 image.  @xref{Pointer Shape}, for available pointer shapes.
4431 @item :map @var{map}
4432 This associates an image map of @dfn{hot spots} with this image.
4434 An image map is an alist where each element has the format
4435 @code{(@var{area} @var{id} @var{plist})}.  An @var{area} is specified
4436 as either a rectangle, a circle, or a polygon.
4438 A rectangle is a cons
4439 @code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))}
4440 which specifies the pixel coordinates of the upper left and bottom right
4441 corners of the rectangle area.
4443 A circle is a cons
4444 @code{(circle . ((@var{x0} . @var{y0}) . @var{r}))}
4445 which specifies the center and the radius of the circle; @var{r} may
4446 be a float or integer.
4448 A polygon is a cons
4449 @code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])}
4450 where each pair in the vector describes one corner in the polygon.
4452 When the mouse pointer lies on a hot-spot area of an image, the
4453 @var{plist} of that hot-spot is consulted; if it contains a @code{help-echo}
4454 property, that defines a tool-tip for the hot-spot, and if it contains
4455 a @code{pointer} property, that defines the shape of the mouse cursor when
4456 it is on the hot-spot.
4457 @xref{Pointer Shape}, for available pointer shapes.
4459 When you click the mouse when the mouse pointer is over a hot-spot, an
4460 event is composed by combining the @var{id} of the hot-spot with the
4461 mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's
4462 @var{id} is @code{area4}.
4463 @end table
4465 @defun image-mask-p spec &optional frame
4466 This function returns @code{t} if image @var{spec} has a mask bitmap.
4467 @var{frame} is the frame on which the image will be displayed.
4468 @var{frame} @code{nil} or omitted means to use the selected frame
4469 (@pxref{Input Focus}).
4470 @end defun
4472 @node XBM Images
4473 @subsection XBM Images
4474 @cindex XBM
4476   To use XBM format, specify @code{xbm} as the image type.  This image
4477 format doesn't require an external library, so images of this type are
4478 always supported.
4480   Additional image properties supported for the @code{xbm} image type are:
4482 @table @code
4483 @item :foreground @var{foreground}
4484 The value, @var{foreground}, should be a string specifying the image
4485 foreground color, or @code{nil} for the default color.  This color is
4486 used for each pixel in the XBM that is 1.  The default is the frame's
4487 foreground color.
4489 @item :background @var{background}
4490 The value, @var{background}, should be a string specifying the image
4491 background color, or @code{nil} for the default color.  This color is
4492 used for each pixel in the XBM that is 0.  The default is the frame's
4493 background color.
4494 @end table
4496   If you specify an XBM image using data within Emacs instead of an
4497 external file, use the following three properties:
4499 @table @code
4500 @item :data @var{data}
4501 The value, @var{data}, specifies the contents of the image.
4502 There are three formats you can use for @var{data}:
4504 @itemize @bullet
4505 @item
4506 A vector of strings or bool-vectors, each specifying one line of the
4507 image.  Do specify @code{:height} and @code{:width}.
4509 @item
4510 A string containing the same byte sequence as an XBM file would contain.
4511 You must not specify @code{:height} and @code{:width} in this case,
4512 because omitting them is what indicates the data has the format of an
4513 XBM file.  The file contents specify the height and width of the image.
4515 @item
4516 A string or a bool-vector containing the bits of the image (plus perhaps
4517 some extra bits at the end that will not be used).  It should contain at
4518 least @var{width} * @code{height} bits.  In this case, you must specify
4519 @code{:height} and @code{:width}, both to indicate that the string
4520 contains just the bits rather than a whole XBM file, and to specify the
4521 size of the image.
4522 @end itemize
4524 @item :width @var{width}
4525 The value, @var{width}, specifies the width of the image, in pixels.
4527 @item :height @var{height}
4528 The value, @var{height}, specifies the height of the image, in pixels.
4529 @end table
4531 @node XPM Images
4532 @subsection XPM Images
4533 @cindex XPM
4535   To use XPM format, specify @code{xpm} as the image type.  The
4536 additional image property @code{:color-symbols} is also meaningful with
4537 the @code{xpm} image type:
4539 @table @code
4540 @item :color-symbols @var{symbols}
4541 The value, @var{symbols}, should be an alist whose elements have the
4542 form @code{(@var{name} . @var{color})}.  In each element, @var{name} is
4543 the name of a color as it appears in the image file, and @var{color}
4544 specifies the actual color to use for displaying that name.
4545 @end table
4547 @node GIF Images
4548 @subsection GIF Images
4549 @cindex GIF
4551   For GIF images, specify image type @code{gif}.
4553 @table @code
4554 @item :index @var{index}
4555 You can use @code{:index} to specify image number @var{index} from a
4556 GIF file that contains more than one image.  If the GIF file doesn't
4557 contain an image with the specified index, the image displays as a
4558 hollow box.  GIF files with more than one image can be animated,
4559 @pxref{Animated Images}.
4560 @end table
4562 @node TIFF Images
4563 @subsection TIFF Images
4564 @cindex TIFF
4566   For TIFF images, specify image type @code{tiff}.
4568 @table @code
4569 @item :index @var{index}
4570 You can use @code{:index} to specify image number @var{index} from a
4571 TIFF file that contains more than one image.  If the TIFF file doesn't
4572 contain an image with the specified index, the image displays as a
4573 hollow box.
4574 @end table
4576 @node PostScript Images
4577 @subsection PostScript Images
4578 @cindex postscript images
4580   To use PostScript for an image, specify image type @code{postscript}.
4581 This works only if you have Ghostscript installed.  You must always use
4582 these three properties:
4584 @table @code
4585 @item :pt-width @var{width}
4586 The value, @var{width}, specifies the width of the image measured in
4587 points (1/72 inch).  @var{width} must be an integer.
4589 @item :pt-height @var{height}
4590 The value, @var{height}, specifies the height of the image in points
4591 (1/72 inch).  @var{height} must be an integer.
4593 @item :bounding-box @var{box}
4594 The value, @var{box}, must be a list or vector of four integers, which
4595 specifying the bounding box of the PostScript image, analogous to the
4596 @samp{BoundingBox} comment found in PostScript files.
4598 @example
4599 %%BoundingBox: 22 171 567 738
4600 @end example
4601 @end table
4603 @node ImageMagick Images
4604 @subsection ImageMagick Images
4605 @cindex ImageMagick images
4606 @cindex images, support for more formats
4608   If you build Emacs with ImageMagick support, you can use the
4609 ImageMagick library to load many image formats (@pxref{File
4610 Conveniences,,, emacs, The GNU Emacs Manual}).  The image type symbol
4611 for images loaded via ImageMagick is @code{imagemagick}, regardless of
4612 the actual underlying image format.
4614 @defun imagemagick-types
4615 This function returns a list of image file extensions supported by the
4616 current ImageMagick installation.  Each list element is a symbol
4617 representing an internal ImageMagick name for an image type, such as
4618 @code{BMP} for @file{.bmp} images.
4619 @end defun
4621 @defopt imagemagick-enabled-types
4622 The value of this variable is a list of ImageMagick image types which
4623 Emacs may attempt to render using ImageMagick.  Each list element
4624 should be one of the symbols in the list returned by
4625 @code{imagemagick-types}, or an equivalent string.  Alternatively, a
4626 value of @code{t} enables ImageMagick for all possible image types.
4627 Regardless of the value of this variable,
4628 @code{imagemagick-types-inhibit} (see below) takes precedence.
4629 @end defopt
4631 @defopt imagemagick-types-inhibit
4632 The value of this variable lists the ImageMagick image types which
4633 should never be rendered using ImageMagick, regardless of the value of
4634 @code{imagemagick-enabled-types}.  A value of @code{t} disables
4635 ImageMagick entirely.
4636 @end defopt
4638   Images loaded with ImageMagick support the following additional
4639 image descriptor properties:
4641 @table @code
4642 @item :background @var{background}
4643 @var{background}, if non-@code{nil}, should be a string specifying a
4644 color, which is used as the image's background color if the image
4645 supports transparency.  If the value is @code{nil}, it defaults to the
4646 frame's background color.
4648 @item :width, :height
4649 The @code{:width} and @code{:height} keywords are used for scaling the
4650 image.  If only one of them is specified, the other one will be
4651 calculated so as to preserve the aspect ratio.  If both are specified,
4652 aspect ratio may not be preserved.
4654 @item :rotation
4655 Specifies a rotation angle in degrees.
4657 @item :index
4658 @c Doesn't work: http://debbugs.gnu.org/7978
4659 This has the same meaning as it does for GIF images (@pxref{GIF Images}),
4660 i.e. it specifies which image to view inside an image bundle file format
4661 such as DJVM.  You can use the @code{image-metadata} function to
4662 retrieve the total number of images in an image bundle.
4663 @end table
4665 @node Other Image Types
4666 @subsection Other Image Types
4667 @cindex PBM
4669   For PBM images, specify image type @code{pbm}.  Color, gray-scale and
4670 monochromatic images are supported.   For mono PBM images, two additional
4671 image properties are supported.
4673 @table @code
4674 @item :foreground @var{foreground}
4675 The value, @var{foreground}, should be a string specifying the image
4676 foreground color, or @code{nil} for the default color.  This color is
4677 used for each pixel in the PBM that is 1.  The default is the frame's
4678 foreground color.
4680 @item :background @var{background}
4681 The value, @var{background}, should be a string specifying the image
4682 background color, or @code{nil} for the default color.  This color is
4683 used for each pixel in the PBM that is 0.  The default is the frame's
4684 background color.
4685 @end table
4687   For JPEG images, specify image type @code{jpeg}.
4689   For TIFF images, specify image type @code{tiff}.
4691   For PNG images, specify image type @code{png}.
4693   For SVG images, specify image type @code{svg}.
4695 @node Defining Images
4696 @subsection Defining Images
4698   The functions @code{create-image}, @code{defimage} and
4699 @code{find-image} provide convenient ways to create image descriptors.
4701 @defun create-image file-or-data &optional type data-p &rest props
4702 This function creates and returns an image descriptor which uses the
4703 data in @var{file-or-data}.  @var{file-or-data} can be a file name or
4704 a string containing the image data; @var{data-p} should be @code{nil}
4705 for the former case, non-@code{nil} for the latter case.
4707 The optional argument @var{type} is a symbol specifying the image type.
4708 If @var{type} is omitted or @code{nil}, @code{create-image} tries to
4709 determine the image type from the file's first few bytes, or else
4710 from the file's name.
4712 The remaining arguments, @var{props}, specify additional image
4713 properties---for example,
4715 @example
4716 (create-image "foo.xpm" 'xpm nil :heuristic-mask t)
4717 @end example
4719 The function returns @code{nil} if images of this type are not
4720 supported.  Otherwise it returns an image descriptor.
4721 @end defun
4723 @defmac defimage symbol specs &optional doc
4724 This macro defines @var{symbol} as an image name.  The arguments
4725 @var{specs} is a list which specifies how to display the image.
4726 The third argument, @var{doc}, is an optional documentation string.
4728 Each argument in @var{specs} has the form of a property list, and each
4729 one should specify at least the @code{:type} property and either the
4730 @code{:file} or the @code{:data} property.  The value of @code{:type}
4731 should be a symbol specifying the image type, the value of
4732 @code{:file} is the file to load the image from, and the value of
4733 @code{:data} is a string containing the actual image data.  Here is an
4734 example:
4736 @example
4737 (defimage test-image
4738   ((:type xpm :file "~/test1.xpm")
4739    (:type xbm :file "~/test1.xbm")))
4740 @end example
4742 @code{defimage} tests each argument, one by one, to see if it is
4743 usable---that is, if the type is supported and the file exists.  The
4744 first usable argument is used to make an image descriptor which is
4745 stored in @var{symbol}.
4747 If none of the alternatives will work, then @var{symbol} is defined
4748 as @code{nil}.
4749 @end defmac
4751 @defun find-image specs
4752 This function provides a convenient way to find an image satisfying one
4753 of a list of image specifications @var{specs}.
4755 Each specification in @var{specs} is a property list with contents
4756 depending on image type.  All specifications must at least contain the
4757 properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
4758 or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
4759 the image type, e.g.@: @code{xbm}, @var{file} is the file to load the
4760 image from, and @var{data} is a string containing the actual image data.
4761 The first specification in the list whose @var{type} is supported, and
4762 @var{file} exists, is used to construct the image specification to be
4763 returned.  If no specification is satisfied, @code{nil} is returned.
4765 The image is looked for in @code{image-load-path}.
4766 @end defun
4768 @defvar image-load-path
4769 This variable's value is a list of locations in which to search for
4770 image files.  If an element is a string or a variable symbol whose
4771 value is a string, the string is taken to be the name of a directory
4772 to search.  If an element is a variable symbol whose value is a list,
4773 that is taken to be a list of directory names to search.
4775 The default is to search in the @file{images} subdirectory of the
4776 directory specified by @code{data-directory}, then the directory
4777 specified by @code{data-directory}, and finally in the directories in
4778 @code{load-path}.  Subdirectories are not automatically included in
4779 the search, so if you put an image file in a subdirectory, you have to
4780 supply the subdirectory name explicitly.  For example, to find the
4781 image @file{images/foo/bar.xpm} within @code{data-directory}, you
4782 should specify the image as follows:
4784 @example
4785 (defimage foo-image '((:type xpm :file "foo/bar.xpm")))
4786 @end example
4787 @end defvar
4789 @defun image-load-path-for-library library image &optional path no-error
4790 This function returns a suitable search path for images used by the
4791 Lisp package @var{library}.
4793 The function searches for @var{image} first using @code{image-load-path},
4794 excluding @file{@code{data-directory}/images}, and then in
4795 @code{load-path}, followed by a path suitable for @var{library}, which
4796 includes @file{../../etc/images} and @file{../etc/images} relative to
4797 the library file itself, and finally in
4798 @file{@code{data-directory}/images}.
4800 Then this function returns a list of directories which contains first
4801 the directory in which @var{image} was found, followed by the value of
4802 @code{load-path}.  If @var{path} is given, it is used instead of
4803 @code{load-path}.
4805 If @var{no-error} is non-@code{nil} and a suitable path can't be
4806 found, don't signal an error.  Instead, return a list of directories as
4807 before, except that @code{nil} appears in place of the image directory.
4809 Here is an example of using @code{image-load-path-for-library}:
4811 @example
4812 (defvar image-load-path) ; shush compiler
4813 (let* ((load-path (image-load-path-for-library
4814                     "mh-e" "mh-logo.xpm"))
4815        (image-load-path (cons (car load-path)
4816                               image-load-path)))
4817   (mh-tool-bar-folder-buttons-init))
4818 @end example
4819 @end defun
4821 @node Showing Images
4822 @subsection Showing Images
4824   You can use an image descriptor by setting up the @code{display}
4825 property yourself, but it is easier to use the functions in this
4826 section.
4828 @defun insert-image image &optional string area slice
4829 This function inserts @var{image} in the current buffer at point.  The
4830 value @var{image} should be an image descriptor; it could be a value
4831 returned by @code{create-image}, or the value of a symbol defined with
4832 @code{defimage}.  The argument @var{string} specifies the text to put
4833 in the buffer to hold the image.  If it is omitted or @code{nil},
4834 @code{insert-image} uses @code{" "} by default.
4836 The argument @var{area} specifies whether to put the image in a margin.
4837 If it is @code{left-margin}, the image appears in the left margin;
4838 @code{right-margin} specifies the right margin.  If @var{area} is
4839 @code{nil} or omitted, the image is displayed at point within the
4840 buffer's text.
4842 The argument @var{slice} specifies a slice of the image to insert.  If
4843 @var{slice} is @code{nil} or omitted the whole image is inserted.
4844 Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width}
4845 @var{height})} which specifies the @var{x} and @var{y} positions and
4846 @var{width} and @var{height} of the image area to insert.  Integer
4847 values are in units of pixels.  A floating point number in the range
4848 0.0--1.0 stands for that fraction of the width or height of the entire
4849 image.
4851 Internally, this function inserts @var{string} in the buffer, and gives
4852 it a @code{display} property which specifies @var{image}.  @xref{Display
4853 Property}.
4854 @end defun
4856 @cindex slice, image
4857 @cindex image slice
4858 @defun insert-sliced-image image &optional string area rows cols
4859 This function inserts @var{image} in the current buffer at point, like
4860 @code{insert-image}, but splits the image into @var{rows}x@var{cols}
4861 equally sized slices.
4863 If an image is inserted ``sliced'', Emacs displays each slice as a
4864 separate image, and allow more intuitive scrolling up/down, instead of
4865 jumping up/down the entire image when paging through a buffer that
4866 displays (large) images.
4867 @end defun
4869 @defun put-image image pos &optional string area
4870 This function puts image @var{image} in front of @var{pos} in the
4871 current buffer.  The argument @var{pos} should be an integer or a
4872 marker.  It specifies the buffer position where the image should appear.
4873 The argument @var{string} specifies the text that should hold the image
4874 as an alternative to the default.
4876 The argument @var{image} must be an image descriptor, perhaps returned
4877 by @code{create-image} or stored by @code{defimage}.
4879 The argument @var{area} specifies whether to put the image in a margin.
4880 If it is @code{left-margin}, the image appears in the left margin;
4881 @code{right-margin} specifies the right margin.  If @var{area} is
4882 @code{nil} or omitted, the image is displayed at point within the
4883 buffer's text.
4885 Internally, this function creates an overlay, and gives it a
4886 @code{before-string} property containing text that has a @code{display}
4887 property whose value is the image.  (Whew!)
4888 @end defun
4890 @defun remove-images start end &optional buffer
4891 This function removes images in @var{buffer} between positions
4892 @var{start} and @var{end}.  If @var{buffer} is omitted or @code{nil},
4893 images are removed from the current buffer.
4895 This removes only images that were put into @var{buffer} the way
4896 @code{put-image} does it, not images that were inserted with
4897 @code{insert-image} or in other ways.
4898 @end defun
4900 @defun image-size spec &optional pixels frame
4901 This function returns the size of an image as a pair
4902 @w{@code{(@var{width} . @var{height})}}.  @var{spec} is an image
4903 specification.  @var{pixels} non-@code{nil} means return sizes
4904 measured in pixels, otherwise return sizes measured in canonical
4905 character units (fractions of the width/height of the frame's default
4906 font).  @var{frame} is the frame on which the image will be displayed.
4907 @var{frame} null or omitted means use the selected frame (@pxref{Input
4908 Focus}).
4909 @end defun
4911 @defvar max-image-size
4912 This variable is used to define the maximum size of image that Emacs
4913 will load.  Emacs will refuse to load (and display) any image that is
4914 larger than this limit.
4916 If the value is an integer, it directly specifies the maximum
4917 image height and width, measured in pixels.  If it is a floating
4918 point number, it specifies the maximum image height and width
4919 as a ratio to the frame height and width.  If the value is
4920 non-numeric, there is no explicit limit on the size of images.
4922 The purpose of this variable is to prevent unreasonably large images
4923 from accidentally being loaded into Emacs.  It only takes effect the
4924 first time an image is loaded.  Once an image is placed in the image
4925 cache, it can always be displayed, even if the value of
4926 @var{max-image-size} is subsequently changed (@pxref{Image Cache}).
4927 @end defvar
4929 @node Animated Images
4930 @subsection Animated Images
4932 @cindex animation
4933 @cindex image animation
4934 Some image files can contain more than one image.  This can be used to
4935 create animation.  Currently, Emacs only supports animated GIF files.
4936 The following functions related to animated images are available.
4938 @defun image-animated-p image
4939 This function returns non-@code{nil} if @var{image} can be animated.
4940 The actual return value is a cons @code{(@var{nimages} . @var{delay})}, 
4941 where @var{nimages} is the number of frames and @var{delay} is the
4942 delay in seconds between them.
4943 @end defun
4945 @defun image-animate image &optional index limit
4946 This function animates @var{image}.  The optional integer @var{index}
4947 specifies the frame from which to start (default 0).  The optional
4948 argument @var{limit} controls the length of the animation.  If omitted
4949 or @code{nil}, the image animates once only; if @code{t} it loops
4950 forever; if a number animation stops after that many seconds.
4951 @end defun
4953 @noindent Animation operates by means of a timer.  Note that Emacs imposes a
4954 minimum frame delay of 0.01 seconds.
4956 @defun image-animate-timer image
4957 This function returns the timer responsible for animating @var{image},
4958 if there is one.
4959 @end defun
4962 @node Image Cache
4963 @subsection Image Cache
4964 @cindex image cache
4966   Emacs caches images so that it can display them again more
4967 efficiently.  When Emacs displays an image, it searches the image
4968 cache for an existing image specification @code{equal} to the desired
4969 specification.  If a match is found, the image is displayed from the
4970 cache.  Otherwise, Emacs loads the image normally.
4972 @defun image-flush spec &optional frame
4973 This function removes the image with specification @var{spec} from the
4974 image cache of frame @var{frame}.  Image specifications are compared
4975 using @code{equal}.  If @var{frame} is @code{nil}, it defaults to the
4976 selected frame.  If @var{frame} is @code{t}, the image is flushed on
4977 all existing frames.
4979 In Emacs's current implementation, each graphical terminal possesses an
4980 image cache, which is shared by all the frames on that terminal
4981 (@pxref{Multiple Terminals}).  Thus, refreshing an image in one frame
4982 also refreshes it in all other frames on the same terminal.
4983 @end defun
4985   One use for @code{image-flush} is to tell Emacs about a change in an
4986 image file.  If an image specification contains a @code{:file}
4987 property, the image is cached based on the file's contents when the
4988 image is first displayed.  Even if the file subsequently changes,
4989 Emacs continues displaying the old version of the image.  Calling
4990 @code{image-flush} flushes the image from the cache, forcing Emacs to
4991 re-read the file the next time it needs to display that image.
4993   Another use for @code{image-flush} is for memory conservation.  If
4994 your Lisp program creates a large number of temporary images over a
4995 period much shorter than @code{image-cache-eviction-delay} (see
4996 below), you can opt to flush unused images yourself, instead of
4997 waiting for Emacs to do it automatically.
4999 @defun clear-image-cache &optional filter
5000 This function clears an image cache, removing all the images stored in
5001 it.  If @var{filter} is omitted or @code{nil}, it clears the cache for
5002 the selected frame.  If @var{filter} is a frame, it clears the cache
5003 for that frame.  If @var{filter} is @code{t}, all image caches are
5004 cleared.  Otherwise, @var{filter} is taken to be a file name, and all
5005 images associated with that file name are removed from all image
5006 caches.
5007 @end defun
5009 If an image in the image cache has not been displayed for a specified
5010 period of time, Emacs removes it from the cache and frees the
5011 associated memory.
5013 @defvar image-cache-eviction-delay
5014 This variable specifies the number of seconds an image can remain in
5015 the cache without being displayed.  When an image is not displayed for
5016 this length of time, Emacs removes it from the image cache.
5018 Under some circumstances, if the number of images in the cache grows
5019 too large, the actual eviction delay may be shorter than this.
5021 If the value is @code{nil}, Emacs does not remove images from the cache
5022 except when you explicitly clear it.  This mode can be useful for
5023 debugging.
5024 @end defvar
5026 @node Buttons
5027 @section Buttons
5028 @cindex buttons in buffers
5029 @cindex clickable buttons in buffers
5031   The Button package defines functions for inserting and manipulating
5032 @dfn{buttons} that can be activated with the mouse or via keyboard
5033 commands.  These buttons are typically used for various kinds of
5034 hyperlinks.
5036   A button is essentially a set of text or overlay properties,
5037 attached to a stretch of text in a buffer.  These properties are
5038 called @dfn{button properties}.  One of these properties, the
5039 @dfn{action property}, specifies a function which is called when the
5040 user invokes the button using the keyboard or the mouse.  The action
5041 function may examine the button and use its other properties as
5042 desired.
5044   In some ways, the Button package duplicates the functionality in the
5045 Widget package.  @xref{Top, , Introduction, widget, The Emacs Widget
5046 Library}.  The advantage of the Button package is that it is faster,
5047 smaller, and simpler to program.  From the point of view of the user,
5048 the interfaces produced by the two packages are very similar.
5050 @menu
5051 * Button Properties::      Button properties with special meanings.
5052 * Button Types::           Defining common properties for classes of buttons.
5053 * Making Buttons::         Adding buttons to Emacs buffers.
5054 * Manipulating Buttons::   Getting and setting properties of buttons.
5055 * Button Buffer Commands:: Buffer-wide commands and bindings for buttons.
5056 @end menu
5058 @node Button Properties
5059 @subsection Button Properties
5060 @cindex button properties
5062   Each button has an associated list of properties defining its
5063 appearance and behavior, and other arbitrary properties may be used
5064 for application specific purposes.  The following properties have
5065 special meaning to the Button package:
5067 @table @code
5068 @item action
5069 @kindex action @r{(button property)}
5070 The function to call when the user invokes the button, which is passed
5071 the single argument @var{button}.  By default this is @code{ignore},
5072 which does nothing.
5074 @item mouse-action
5075 @kindex mouse-action @r{(button property)}
5076 This is similar to @code{action}, and when present, will be used
5077 instead of @code{action} for button invocations resulting from
5078 mouse-clicks (instead of the user hitting @key{RET}).  If not
5079 present, mouse-clicks use @code{action} instead.
5081 @item face
5082 @kindex face @r{(button property)}
5083 This is an Emacs face controlling how buttons of this type are
5084 displayed; by default this is the @code{button} face.
5086 @item mouse-face
5087 @kindex mouse-face @r{(button property)}
5088 This is an additional face which controls appearance during
5089 mouse-overs (merged with the usual button face); by default this is
5090 the usual Emacs @code{highlight} face.
5092 @item keymap
5093 @kindex keymap @r{(button property)}
5094 The button's keymap, defining bindings active within the button
5095 region.  By default this is the usual button region keymap, stored
5096 in the variable @code{button-map}, which defines @key{RET} and
5097 @key{mouse-2} to invoke the button.
5099 @item type
5100 @kindex type @r{(button property)}
5101 The button type.  @xref{Button Types}.
5103 @item help-echo
5104 @kindex help-index @r{(button property)}
5105 A string displayed by the Emacs tool-tip help system; by default,
5106 @code{"mouse-2, RET: Push this button"}.
5108 @item follow-link
5109 @kindex follow-link @r{(button property)}
5110 The follow-link property, defining how a @key{Mouse-1} click behaves
5111 on this button, @xref{Clickable Text}.
5113 @item button
5114 @kindex button @r{(button property)}
5115 All buttons have a non-@code{nil} @code{button} property, which may be useful
5116 in finding regions of text that comprise buttons (which is what the
5117 standard button functions do).
5118 @end table
5120   There are other properties defined for the regions of text in a
5121 button, but these are not generally interesting for typical uses.
5123 @node Button Types
5124 @subsection Button Types
5125 @cindex button types
5127   Every button has a @dfn{button type}, which defines default values
5128 for the button's properties.  Button types are arranged in a
5129 hierarchy, with specialized types inheriting from more general types,
5130 so that it's easy to define special-purpose types of buttons for
5131 specific tasks.
5133 @defun define-button-type name &rest properties
5134 Define a `button type' called @var{name} (a symbol).
5135 The remaining arguments
5136 form a sequence of @var{property value} pairs, specifying default
5137 property values for buttons with this type (a button's type may be set
5138 by giving it a @code{type} property when creating the button, using
5139 the @code{:type} keyword argument).
5141 In addition, the keyword argument @code{:supertype} may be used to
5142 specify a button-type from which @var{name} inherits its default
5143 property values.  Note that this inheritance happens only when
5144 @var{name} is defined; subsequent changes to a supertype are not
5145 reflected in its subtypes.
5146 @end defun
5148   Using @code{define-button-type} to define default properties for
5149 buttons is not necessary---buttons without any specified type use the
5150 built-in button-type @code{button}---but it is encouraged, since
5151 doing so usually makes the resulting code clearer and more efficient.
5153 @node Making Buttons
5154 @subsection Making Buttons
5155 @cindex making buttons
5157   Buttons are associated with a region of text, using an overlay or
5158 text properties to hold button-specific information, all of which are
5159 initialized from the button's type (which defaults to the built-in
5160 button type @code{button}).  Like all Emacs text, the appearance of
5161 the button is governed by the @code{face} property; by default (via
5162 the @code{face} property inherited from the @code{button} button-type)
5163 this is a simple underline, like a typical web-page link.
5165   For convenience, there are two sorts of button-creation functions,
5166 those that add button properties to an existing region of a buffer,
5167 called @code{make-...button}, and those that also insert the button
5168 text, called @code{insert-...button}.
5170   The button-creation functions all take the @code{&rest} argument
5171 @var{properties}, which should be a sequence of @var{property value}
5172 pairs, specifying properties to add to the button; see @ref{Button
5173 Properties}.  In addition, the keyword argument @code{:type} may be
5174 used to specify a button-type from which to inherit other properties;
5175 see @ref{Button Types}.  Any properties not explicitly specified
5176 during creation will be inherited from the button's type (if the type
5177 defines such a property).
5179   The following functions add a button using an overlay
5180 (@pxref{Overlays}) to hold the button properties:
5182 @defun make-button beg end &rest properties
5183 This makes a button from @var{beg} to @var{end} in the
5184 current buffer, and returns it.
5185 @end defun
5187 @defun insert-button label &rest properties
5188 This insert a button with the label @var{label} at point,
5189 and returns it.
5190 @end defun
5192   The following functions are similar, but using text properties
5193 (@pxref{Text Properties}) to hold the button properties.  Such buttons
5194 do not add markers to the buffer, so editing in the buffer does not
5195 slow down if there is an extremely large numbers of buttons.  However,
5196 if there is an existing face text property on the text (e.g.@: a face
5197 assigned by Font Lock mode), the button face may not be visible.  Both
5198 of these functions return the starting position of the new button.
5200 @defun make-text-button beg end &rest properties
5201 This makes a button from @var{beg} to @var{end} in the current buffer,
5202 using text properties.
5203 @end defun
5205 @defun insert-text-button label &rest properties
5206 This inserts a button with the label @var{label} at point, using text
5207 properties.
5208 @end defun
5210 @node Manipulating Buttons
5211 @subsection Manipulating Buttons
5212 @cindex manipulating buttons
5214 These are functions for getting and setting properties of buttons.
5215 Often these are used by a button's invocation function to determine
5216 what to do.
5218 Where a @var{button} parameter is specified, it means an object
5219 referring to a specific button, either an overlay (for overlay
5220 buttons), or a buffer-position or marker (for text property buttons).
5221 Such an object is passed as the first argument to a button's
5222 invocation function when it is invoked.
5224 @defun button-start button
5225 Return the position at which @var{button} starts.
5226 @end defun
5228 @defun button-end button
5229 Return the position at which @var{button} ends.
5230 @end defun
5232 @defun button-get button prop
5233 Get the property of button @var{button} named @var{prop}.
5234 @end defun
5236 @defun button-put button prop val
5237 Set @var{button}'s @var{prop} property to @var{val}.
5238 @end defun
5240 @defun button-activate button &optional use-mouse-action
5241 Call @var{button}'s @code{action} property (i.e., invoke it).  If
5242 @var{use-mouse-action} is non-@code{nil}, try to invoke the button's
5243 @code{mouse-action} property instead of @code{action}; if the button
5244 has no @code{mouse-action} property, use @code{action} as normal.
5245 @end defun
5247 @defun button-label button
5248 Return @var{button}'s text label.
5249 @end defun
5251 @defun button-type button
5252 Return @var{button}'s button-type.
5253 @end defun
5255 @defun button-has-type-p button type
5256 Return @code{t} if @var{button} has button-type @var{type}, or one of
5257 @var{type}'s subtypes.
5258 @end defun
5260 @defun button-at pos
5261 Return the button at position @var{pos} in the current buffer, or
5262 @code{nil}.  If the button at @var{pos} is a text property button, the
5263 return value is a marker pointing to @var{pos}.
5264 @end defun
5266 @defun button-type-put type prop val
5267 Set the button-type @var{type}'s @var{prop} property to @var{val}.
5268 @end defun
5270 @defun button-type-get type prop
5271 Get the property of button-type @var{type} named @var{prop}.
5272 @end defun
5274 @defun button-type-subtype-p type supertype
5275 Return @code{t} if button-type @var{type} is a subtype of @var{supertype}.
5276 @end defun
5278 @node Button Buffer Commands
5279 @subsection Button Buffer Commands
5280 @cindex button buffer commands
5282 These are commands and functions for locating and operating on
5283 buttons in an Emacs buffer.
5285 @code{push-button} is the command that a user uses to actually `push'
5286 a button, and is bound by default in the button itself to @key{RET}
5287 and to @key{mouse-2} using a local keymap in the button's overlay or
5288 text properties.  Commands that are useful outside the buttons itself,
5289 such as @code{forward-button} and @code{backward-button} are
5290 additionally available in the keymap stored in
5291 @code{button-buffer-map}; a mode which uses buttons may want to use
5292 @code{button-buffer-map} as a parent keymap for its keymap.
5294 If the button has a non-@code{nil} @code{follow-link} property, and
5295 @var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click
5296 will also activate the @code{push-button} command.
5297 @xref{Clickable Text}.
5299 @deffn Command push-button &optional pos use-mouse-action
5300 Perform the action specified by a button at location @var{pos}.
5301 @var{pos} may be either a buffer position or a mouse-event.  If
5302 @var{use-mouse-action} is non-@code{nil}, or @var{pos} is a
5303 mouse-event (@pxref{Mouse Events}), try to invoke the button's
5304 @code{mouse-action} property instead of @code{action}; if the button
5305 has no @code{mouse-action} property, use @code{action} as normal.
5306 @var{pos} defaults to point, except when @code{push-button} is invoked
5307 interactively as the result of a mouse-event, in which case, the mouse
5308 event's position is used.  If there's no button at @var{pos}, do
5309 nothing and return @code{nil}, otherwise return @code{t}.
5310 @end deffn
5312 @deffn Command forward-button n &optional wrap display-message
5313 Move to the @var{n}th next button, or @var{n}th previous button if
5314 @var{n} is negative.  If @var{n} is zero, move to the start of any
5315 button at point.  If @var{wrap} is non-@code{nil}, moving past either
5316 end of the buffer continues from the other end.  If
5317 @var{display-message} is non-@code{nil}, the button's help-echo string
5318 is displayed.  Any button with a non-@code{nil} @code{skip} property
5319 is skipped over.  Returns the button found.
5320 @end deffn
5322 @deffn Command backward-button n &optional wrap display-message
5323 Move to the @var{n}th previous button, or @var{n}th next button if
5324 @var{n} is negative.  If @var{n} is zero, move to the start of any
5325 button at point.  If @var{wrap} is non-@code{nil}, moving past either
5326 end of the buffer continues from the other end.  If
5327 @var{display-message} is non-@code{nil}, the button's help-echo string
5328 is displayed.  Any button with a non-@code{nil} @code{skip} property
5329 is skipped over.  Returns the button found.
5330 @end deffn
5332 @defun next-button pos &optional count-current
5333 @defunx previous-button pos &optional count-current
5334 Return the next button after (for @code{next-button} or before (for
5335 @code{previous-button}) position @var{pos} in the current buffer.  If
5336 @var{count-current} is non-@code{nil}, count any button at @var{pos}
5337 in the search, instead of starting at the next button.
5338 @end defun
5340 @node Abstract Display
5341 @section Abstract Display
5342 @cindex ewoc
5343 @cindex display, abstract
5344 @cindex display, arbitrary objects
5345 @cindex model/view/controller
5346 @cindex view part, model/view/controller
5348   The Ewoc package constructs buffer text that represents a structure
5349 of Lisp objects, and updates the text to follow changes in that
5350 structure.  This is like the ``view'' component in the
5351 ``model/view/controller'' design paradigm.
5353   An @dfn{ewoc} is a structure that organizes information required to
5354 construct buffer text that represents certain Lisp data.  The buffer
5355 text of the ewoc has three parts, in order: first, fixed @dfn{header}
5356 text; next, textual descriptions of a series of data elements (Lisp
5357 objects that you specify); and last, fixed @dfn{footer} text.
5358 Specifically, an ewoc contains information on:
5360 @itemize @bullet
5361 @item
5362 The buffer which its text is generated in.
5364 @item
5365 The text's start position in the buffer.
5367 @item
5368 The header and footer strings.
5370 @item
5371 A doubly-linked chain of @dfn{nodes}, each of which contains:
5373 @itemize
5374 @item
5375 A @dfn{data element}, a single Lisp object.
5377 @item
5378 Links to the preceding and following nodes in the chain.
5379 @end itemize
5381 @item
5382 A @dfn{pretty-printer} function which is responsible for
5383 inserting the textual representation of a data
5384 element value into the current buffer.
5385 @end itemize
5387   Typically, you define an ewoc with @code{ewoc-create}, and then pass
5388 the resulting ewoc structure to other functions in the Ewoc package to
5389 build nodes within it, and display it in the buffer.  Once it is
5390 displayed in the buffer, other functions determine the correspondence
5391 between buffer positions and nodes, move point from one node's textual
5392 representation to another, and so forth.  @xref{Abstract Display
5393 Functions}.
5395   A node @dfn{encapsulates} a data element much the way a variable
5396 holds a value.  Normally, encapsulation occurs as a part of adding a
5397 node to the ewoc.  You can retrieve the data element value and place a
5398 new value in its place, like so:
5400 @lisp
5401 (ewoc-data @var{node})
5402 @result{} value
5404 (ewoc-set-data @var{node} @var{new-value})
5405 @result{} @var{new-value}
5406 @end lisp
5408 @noindent
5409 You can also use, as the data element value, a Lisp object (list or
5410 vector) that is a container for the ``real'' value, or an index into
5411 some other structure.  The example (@pxref{Abstract Display Example})
5412 uses the latter approach.
5414   When the data changes, you will want to update the text in the
5415 buffer.  You can update all nodes by calling @code{ewoc-refresh}, or
5416 just specific nodes using @code{ewoc-invalidate}, or all nodes
5417 satisfying a predicate using @code{ewoc-map}.  Alternatively, you can
5418 delete invalid nodes using @code{ewoc-delete} or @code{ewoc-filter},
5419 and add new nodes in their place.  Deleting a node from an ewoc deletes
5420 its associated textual description from buffer, as well.
5422 @menu
5423 * Abstract Display Functions::  Functions in the Ewoc package.
5424 * Abstract Display Example::    Example of using Ewoc.
5425 @end menu
5427 @node Abstract Display Functions
5428 @subsection Abstract Display Functions
5430   In this subsection, @var{ewoc} and @var{node} stand for the
5431 structures described above (@pxref{Abstract Display}), while
5432 @var{data} stands for an arbitrary Lisp object used as a data element.
5434 @defun ewoc-create pretty-printer &optional header footer nosep
5435 This constructs and returns a new ewoc, with no nodes (and thus no data
5436 elements).  @var{pretty-printer} should be a function that takes one
5437 argument, a data element of the sort you plan to use in this ewoc, and
5438 inserts its textual description at point using @code{insert} (and never
5439 @code{insert-before-markers}, because that would interfere with the
5440 Ewoc package's internal mechanisms).
5442 Normally, a newline is automatically inserted after the header,
5443 the footer and every node's textual description.  If @var{nosep}
5444 is non-@code{nil}, no newline is inserted.  This may be useful for
5445 displaying an entire ewoc on a single line, for example, or for
5446 making nodes ``invisible'' by arranging for @var{pretty-printer}
5447 to do nothing for those nodes.
5449 An ewoc maintains its text in the buffer that is current when
5450 you create it, so switch to the intended buffer before calling
5451 @code{ewoc-create}.
5452 @end defun
5454 @defun ewoc-buffer ewoc
5455 This returns the buffer where @var{ewoc} maintains its text.
5456 @end defun
5458 @defun ewoc-get-hf ewoc
5459 This returns a cons cell @code{(@var{header} . @var{footer})}
5460 made from @var{ewoc}'s header and footer.
5461 @end defun
5463 @defun ewoc-set-hf ewoc header footer
5464 This sets the header and footer of @var{ewoc} to the strings
5465 @var{header} and @var{footer}, respectively.
5466 @end defun
5468 @defun ewoc-enter-first ewoc data
5469 @defunx ewoc-enter-last ewoc data
5470 These add a new node encapsulating @var{data}, putting it, respectively,
5471 at the beginning or end of @var{ewoc}'s chain of nodes.
5472 @end defun
5474 @defun ewoc-enter-before ewoc node data
5475 @defunx ewoc-enter-after ewoc node data
5476 These add a new node encapsulating @var{data}, adding it to
5477 @var{ewoc} before or after @var{node}, respectively.
5478 @end defun
5480 @defun ewoc-prev ewoc node
5481 @defunx ewoc-next ewoc node
5482 These return, respectively, the previous node and the next node of @var{node}
5483 in @var{ewoc}.
5484 @end defun
5486 @defun ewoc-nth ewoc n
5487 This returns the node in @var{ewoc} found at zero-based index @var{n}.
5488 A negative @var{n} means count from the end.  @code{ewoc-nth} returns
5489 @code{nil} if @var{n} is out of range.
5490 @end defun
5492 @defun ewoc-data node
5493 This extracts the data encapsulated by @var{node} and returns it.
5494 @end defun
5496 @defun ewoc-set-data node data
5497 This sets the data encapsulated by @var{node} to @var{data}.
5498 @end defun
5500 @defun ewoc-locate ewoc &optional pos guess
5501 This determines the node in @var{ewoc} which contains point (or
5502 @var{pos} if specified), and returns that node.  If @var{ewoc} has no
5503 nodes, it returns @code{nil}.  If @var{pos} is before the first node,
5504 it returns the first node; if @var{pos} is after the last node, it returns
5505 the last node.  The optional third arg @var{guess}
5506 should be a node that is likely to be near @var{pos}; this doesn't
5507 alter the result, but makes the function run faster.
5508 @end defun
5510 @defun ewoc-location node
5511 This returns the start position of @var{node}.
5512 @end defun
5514 @defun ewoc-goto-prev ewoc arg
5515 @defunx ewoc-goto-next ewoc arg
5516 These move point to the previous or next, respectively, @var{arg}th node
5517 in @var{ewoc}.  @code{ewoc-goto-prev} does not move if it is already at
5518 the first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next}
5519 moves past the last node, returning @code{nil}.  Excepting this special
5520 case, these functions return the node moved to.
5521 @end defun
5523 @defun ewoc-goto-node ewoc node
5524 This moves point to the start of @var{node} in @var{ewoc}.
5525 @end defun
5527 @defun ewoc-refresh ewoc
5528 This function regenerates the text of @var{ewoc}.  It works by
5529 deleting the text between the header and the footer, i.e., all the
5530 data elements' representations, and then calling the pretty-printer
5531 function for each node, one by one, in order.
5532 @end defun
5534 @defun ewoc-invalidate ewoc &rest nodes
5535 This is similar to @code{ewoc-refresh}, except that only @var{nodes} in
5536 @var{ewoc} are updated instead of the entire set.
5537 @end defun
5539 @defun ewoc-delete ewoc &rest nodes
5540 This deletes each node in @var{nodes} from @var{ewoc}.
5541 @end defun
5543 @defun ewoc-filter ewoc predicate &rest args
5544 This calls @var{predicate} for each data element in @var{ewoc} and
5545 deletes those nodes for which @var{predicate} returns @code{nil}.
5546 Any @var{args} are passed to @var{predicate}.
5547 @end defun
5549 @defun ewoc-collect ewoc predicate &rest args
5550 This calls @var{predicate} for each data element in @var{ewoc}
5551 and returns a list of those elements for which @var{predicate}
5552 returns non-@code{nil}.  The elements in the list are ordered
5553 as in the buffer.  Any @var{args} are passed to @var{predicate}.
5554 @end defun
5556 @defun ewoc-map map-function ewoc &rest args
5557 This calls @var{map-function} for each data element in @var{ewoc} and
5558 updates those nodes for which @var{map-function} returns non-@code{nil}.
5559 Any @var{args} are passed to @var{map-function}.
5560 @end defun
5562 @node Abstract Display Example
5563 @subsection Abstract Display Example
5565   Here is a simple example using functions of the ewoc package to
5566 implement a ``color components display'', an area in a buffer that
5567 represents a vector of three integers (itself representing a 24-bit RGB
5568 value) in various ways.
5570 @example
5571 (setq colorcomp-ewoc nil
5572       colorcomp-data nil
5573       colorcomp-mode-map nil
5574       colorcomp-labels ["Red" "Green" "Blue"])
5576 (defun colorcomp-pp (data)
5577   (if data
5578       (let ((comp (aref colorcomp-data data)))
5579         (insert (aref colorcomp-labels data) "\t: #x"
5580                 (format "%02X" comp) " "
5581                 (make-string (ash comp -2) ?#) "\n"))
5582     (let ((cstr (format "#%02X%02X%02X"
5583                         (aref colorcomp-data 0)
5584                         (aref colorcomp-data 1)
5585                         (aref colorcomp-data 2)))
5586           (samp " (sample text) "))
5587       (insert "Color\t: "
5588               (propertize samp 'face
5589                           `(foreground-color . ,cstr))
5590               (propertize samp 'face
5591                           `(background-color . ,cstr))
5592               "\n"))))
5594 (defun colorcomp (color)
5595   "Allow fiddling with COLOR in a new buffer.
5596 The buffer is in Color Components mode."
5597   (interactive "sColor (name or #RGB or #RRGGBB): ")
5598   (when (string= "" color)
5599     (setq color "green"))
5600   (unless (color-values color)
5601     (error "No such color: %S" color))
5602   (switch-to-buffer
5603    (generate-new-buffer (format "originally: %s" color)))
5604   (kill-all-local-variables)
5605   (setq major-mode 'colorcomp-mode
5606         mode-name "Color Components")
5607   (use-local-map colorcomp-mode-map)
5608   (erase-buffer)
5609   (buffer-disable-undo)
5610   (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8))
5611                                      (color-values color))))
5612         (ewoc (ewoc-create 'colorcomp-pp
5613                            "\nColor Components\n\n"
5614                            (substitute-command-keys
5615                             "\n\\@{colorcomp-mode-map@}"))))
5616     (set (make-local-variable 'colorcomp-data) data)
5617     (set (make-local-variable 'colorcomp-ewoc) ewoc)
5618     (ewoc-enter-last ewoc 0)
5619     (ewoc-enter-last ewoc 1)
5620     (ewoc-enter-last ewoc 2)
5621     (ewoc-enter-last ewoc nil)))
5622 @end example
5624 @cindex controller part, model/view/controller
5625   This example can be extended to be a ``color selection widget'' (in
5626 other words, the controller part of the ``model/view/controller''
5627 design paradigm) by defining commands to modify @code{colorcomp-data}
5628 and to ``finish'' the selection process, and a keymap to tie it all
5629 together conveniently.
5631 @smallexample
5632 (defun colorcomp-mod (index limit delta)
5633   (let ((cur (aref colorcomp-data index)))
5634     (unless (= limit cur)
5635       (aset colorcomp-data index (+ cur delta)))
5636     (ewoc-invalidate
5637      colorcomp-ewoc
5638      (ewoc-nth colorcomp-ewoc index)
5639      (ewoc-nth colorcomp-ewoc -1))))
5641 (defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1))
5642 (defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1))
5643 (defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1))
5644 (defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1))
5645 (defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1))
5646 (defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1))
5648 (defun colorcomp-copy-as-kill-and-exit ()
5649   "Copy the color components into the kill ring and kill the buffer.
5650 The string is formatted #RRGGBB (hash followed by six hex digits)."
5651   (interactive)
5652   (kill-new (format "#%02X%02X%02X"
5653                     (aref colorcomp-data 0)
5654                     (aref colorcomp-data 1)
5655                     (aref colorcomp-data 2)))
5656   (kill-buffer nil))
5658 (setq colorcomp-mode-map
5659       (let ((m (make-sparse-keymap)))
5660         (suppress-keymap m)
5661         (define-key m "i" 'colorcomp-R-less)
5662         (define-key m "o" 'colorcomp-R-more)
5663         (define-key m "k" 'colorcomp-G-less)
5664         (define-key m "l" 'colorcomp-G-more)
5665         (define-key m "," 'colorcomp-B-less)
5666         (define-key m "." 'colorcomp-B-more)
5667         (define-key m " " 'colorcomp-copy-as-kill-and-exit)
5668         m))
5669 @end smallexample
5671 Note that we never modify the data in each node, which is fixed when the
5672 ewoc is created to be either @code{nil} or an index into the vector
5673 @code{colorcomp-data}, the actual color components.
5675 @node Blinking
5676 @section Blinking Parentheses
5677 @cindex parenthesis matching
5678 @cindex blinking parentheses
5679 @cindex balancing parentheses
5681   This section describes the mechanism by which Emacs shows a matching
5682 open parenthesis when the user inserts a close parenthesis.
5684 @defvar blink-paren-function
5685 The value of this variable should be a function (of no arguments) to
5686 be called whenever a character with close parenthesis syntax is inserted.
5687 The value of @code{blink-paren-function} may be @code{nil}, in which
5688 case nothing is done.
5689 @end defvar
5691 @defopt blink-matching-paren
5692 If this variable is @code{nil}, then @code{blink-matching-open} does
5693 nothing.
5694 @end defopt
5696 @defopt blink-matching-paren-distance
5697 This variable specifies the maximum distance to scan for a matching
5698 parenthesis before giving up.
5699 @end defopt
5701 @defopt blink-matching-delay
5702 This variable specifies the number of seconds for the cursor to remain
5703 at the matching parenthesis.  A fraction of a second often gives
5704 good results, but the default is 1, which works on all systems.
5705 @end defopt
5707 @deffn Command blink-matching-open
5708 This function is the default value of @code{blink-paren-function}.  It
5709 assumes that point follows a character with close parenthesis syntax and
5710 moves the cursor momentarily to the matching opening character.  If that
5711 character is not already on the screen, it displays the character's
5712 context in the echo area.  To avoid long delays, this function does not
5713 search farther than @code{blink-matching-paren-distance} characters.
5715 Here is an example of calling this function explicitly.
5717 @smallexample
5718 @group
5719 (defun interactive-blink-matching-open ()
5720   "Indicate momentarily the start of sexp before point."
5721   (interactive)
5722 @end group
5723 @group
5724   (let ((blink-matching-paren-distance
5725          (buffer-size))
5726         (blink-matching-paren t))
5727     (blink-matching-open)))
5728 @end group
5729 @end smallexample
5730 @end deffn
5732 @node Character Display
5733 @section Character Display
5735   This section describes how characters are actually displayed by
5736 Emacs.  Typically, a character is displayed as a @dfn{glyph} (a
5737 graphical symbol which occupies one character position on the screen),
5738 whose appearance corresponds to the character itself.  For example,
5739 the character @samp{a} (character code 97) is displayed as @samp{a}.
5740 Some characters, however, are displayed specially.  For example, the
5741 formfeed character (character code 12) is usually displayed as a
5742 sequence of two glyphs, @samp{^L}, while the newline character
5743 (character code 10) starts a new screen line.
5745   You can modify how each character is displayed by defining a
5746 @dfn{display table}, which maps each character code into a sequence of
5747 glyphs.  @xref{Display Tables}.
5749 @menu
5750 * Usual Display::       The usual conventions for displaying characters.
5751 * Display Tables::      What a display table consists of.
5752 * Active Display Table::  How Emacs selects a display table to use.
5753 * Glyphs::              How to define a glyph, and what glyphs mean.
5754 * Glyphless Chars::     How glyphless characters are drawn.
5755 @end menu
5757 @node Usual Display
5758 @subsection Usual Display Conventions
5760   Here are the conventions for displaying each character code (in the
5761 absence of a display table, which can override these
5762 @iftex
5763 conventions).
5764 @end iftex
5765 @ifnottex
5766 conventions; @pxref{Display Tables}).
5767 @end ifnottex
5769 @cindex printable ASCII characters
5770 @itemize @bullet
5771 @item
5772 The @dfn{printable @acronym{ASCII} characters}, character codes 32
5773 through 126 (consisting of numerals, English letters, and symbols like
5774 @samp{#}) are displayed literally.
5776 @item
5777 The tab character (character code 9) displays as whitespace stretching
5778 up to the next tab stop column.  @xref{Text Display,,, emacs, The GNU
5779 Emacs Manual}.  The variable @code{tab-width} controls the number of
5780 spaces per tab stop (see below).
5782 @item
5783 The newline character (character code 10) has a special effect: it
5784 ends the preceding line and starts a new line.
5786 @cindex ASCII control characters
5787 @item
5788 The non-printable @dfn{@acronym{ASCII} control characters}---character
5789 codes 0 through 31, as well as the @key{DEL} character (character code
5790 127)---display in one of two ways according to the variable
5791 @code{ctl-arrow}.  If this variable is non-@code{nil} (the default),
5792 these characters are displayed as sequences of two glyphs, where the
5793 first glyph is @samp{^} (a display table can specify a glyph to use
5794 instead of @samp{^}); e.g.@: the @key{DEL} character is displayed as
5795 @samp{^?}.
5797 If @code{ctl-arrow} is @code{nil}, these characters are displayed as
5798 octal escapes (see below).
5800 This rule also applies to carriage return (character code 13), if that
5801 character appears in the buffer.  But carriage returns usually do not
5802 appear in buffer text; they are eliminated as part of end-of-line
5803 conversion (@pxref{Coding System Basics}).
5805 @cindex octal escapes
5806 @item
5807 @dfn{Raw bytes} are non-@acronym{ASCII} characters with codes 128
5808 through 255 (@pxref{Text Representations}).  These characters display
5809 as @dfn{octal escapes}: sequences of four glyphs, where the first
5810 glyph is the @acronym{ASCII} code for @samp{\}, and the others are
5811 digit characters representing the character code in octal.  (A display
5812 table can specify a glyph to use instead of @samp{\}.)
5814 @item
5815 Each non-@acronym{ASCII} character with code above 255 is displayed
5816 literally, if the terminal supports it.  If the terminal does not
5817 support it, the character is said to be @dfn{glyphless}, and it is
5818 usually displayed using a placeholder glyph.  For example, if a
5819 graphical terminal has no font for a character, Emacs usually displays
5820 a box containing the character code in hexadecimal.  @xref{Glyphless
5821 Chars}.
5822 @end itemize
5824   The above display conventions apply even when there is a display
5825 table, for any character whose entry in the active display table is
5826 @code{nil}.  Thus, when you set up a display table, you need only
5827 specify the characters for which you want special behavior.
5829   The following variables affect how certain characters are displayed
5830 on the screen.  Since they change the number of columns the characters
5831 occupy, they also affect the indentation functions.  They also affect
5832 how the mode line is displayed; if you want to force redisplay of the
5833 mode line using the new values, call the function
5834 @code{force-mode-line-update} (@pxref{Mode Line Format}).
5836 @defopt ctl-arrow
5837 @cindex control characters in display
5838 This buffer-local variable controls how control characters are
5839 displayed.  If it is non-@code{nil}, they are displayed as a caret
5840 followed by the character: @samp{^A}.  If it is @code{nil}, they are
5841 displayed as octal escapes: a backslash followed by three octal
5842 digits, as in @samp{\001}.
5843 @end defopt
5845 @defopt tab-width
5846 The value of this buffer-local variable is the spacing between tab
5847 stops used for displaying tab characters in Emacs buffers.  The value
5848 is in units of columns, and the default is 8.  Note that this feature
5849 is completely independent of the user-settable tab stops used by the
5850 command @code{tab-to-tab-stop}.  @xref{Indent Tabs}.
5851 @end defopt
5853 @node Display Tables
5854 @subsection Display Tables
5856 @cindex display table
5857   A display table is a special-purpose char-table
5858 (@pxref{Char-Tables}), with @code{display-table} as its subtype, which
5859 is used to override the usual character display conventions.  This
5860 section describes how to make, inspect, and assign elements to a
5861 display table object.
5863 @defun make-display-table
5864 This creates and returns a display table.  The table initially has
5865 @code{nil} in all elements.
5866 @end defun
5868   The ordinary elements of the display table are indexed by character
5869 codes; the element at index @var{c} says how to display the character
5870 code @var{c}.  The value should be @code{nil} (which means to display
5871 the character @var{c} according to the usual display conventions;
5872 @pxref{Usual Display}), or a vector of glyph codes (which means to
5873 display the character @var{c} as those glyphs; @pxref{Glyphs}).
5875   @strong{Warning:} if you use the display table to change the display
5876 of newline characters, the whole buffer will be displayed as one long
5877 ``line''.
5879   The display table also has six ``extra slots'' which serve special
5880 purposes.  Here is a table of their meanings; @code{nil} in any slot
5881 means to use the default for that slot, as stated below.
5883 @table @asis
5884 @item 0
5885 The glyph for the end of a truncated screen line (the default for this
5886 is @samp{$}).  @xref{Glyphs}.  On graphical terminals, Emacs uses
5887 arrows in the fringes to indicate truncation, so the display table has
5888 no effect.
5890 @item 1
5891 The glyph for the end of a continued line (the default is @samp{\}).
5892 On graphical terminals, Emacs uses curved arrows in the fringes to
5893 indicate continuation, so the display table has no effect.
5895 @item 2
5896 The glyph for indicating a character displayed as an octal character
5897 code (the default is @samp{\}).
5899 @item 3
5900 The glyph for indicating a control character (the default is @samp{^}).
5902 @item 4
5903 A vector of glyphs for indicating the presence of invisible lines (the
5904 default is @samp{...}).  @xref{Selective Display}.
5906 @item 5
5907 The glyph used to draw the border between side-by-side windows (the
5908 default is @samp{|}).  @xref{Splitting Windows}.  This takes effect only
5909 when there are no scroll bars; if scroll bars are supported and in use,
5910 a scroll bar separates the two windows.
5911 @end table
5913   For example, here is how to construct a display table that mimics
5914 the effect of setting @code{ctl-arrow} to a non-@code{nil} value
5915 (@pxref{Glyphs}, for the function @code{make-glyph-code}):
5917 @example
5918 (setq disptab (make-display-table))
5919 (dotimes (i 32)
5920   (or (= i ?\t)
5921       (= i ?\n)
5922       (aset disptab i
5923             (vector (make-glyph-code ?^ 'escape-glyph)
5924                     (make-glyph-code (+ i 64) 'escape-glyph)))))
5925 (aset disptab 127
5926       (vector (make-glyph-code ?^ 'escape-glyph)
5927               (make-glyph-code ?? 'escape-glyph)))))
5928 @end example
5930 @defun display-table-slot display-table slot
5931 This function returns the value of the extra slot @var{slot} of
5932 @var{display-table}.  The argument @var{slot} may be a number from 0 to
5933 5 inclusive, or a slot name (symbol).  Valid symbols are
5934 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
5935 @code{selective-display}, and @code{vertical-border}.
5936 @end defun
5938 @defun set-display-table-slot display-table slot value
5939 This function stores @var{value} in the extra slot @var{slot} of
5940 @var{display-table}.  The argument @var{slot} may be a number from 0 to
5941 5 inclusive, or a slot name (symbol).  Valid symbols are
5942 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
5943 @code{selective-display}, and @code{vertical-border}.
5944 @end defun
5946 @defun describe-display-table display-table
5947 This function displays a description of the display table
5948 @var{display-table} in a help buffer.
5949 @end defun
5951 @deffn Command describe-current-display-table
5952 This command displays a description of the current display table in a
5953 help buffer.
5954 @end deffn
5956 @node Active Display Table
5957 @subsection Active Display Table
5958 @cindex active display table
5960   Each window can specify a display table, and so can each buffer.
5961 The window's display table, if there is one, takes precedence over the
5962 buffer's display table.  If neither exists, Emacs tries to use the
5963 standard display table; if that is @code{nil}, Emacs uses the usual
5964 character display conventions (@pxref{Usual Display}).
5966   Note that display tables affect how the mode line is displayed, so
5967 if you want to force redisplay of the mode line using a new display
5968 table, call @code{force-mode-line-update} (@pxref{Mode Line Format}).
5970 @defun window-display-table &optional window
5971 This function returns @var{window}'s display table, or @code{nil} if
5972 there is none.  The default for @var{window} is the selected window.
5973 @end defun
5975 @defun set-window-display-table window table
5976 This function sets the display table of @var{window} to @var{table}.
5977 The argument @var{table} should be either a display table or
5978 @code{nil}.
5979 @end defun
5981 @defvar buffer-display-table
5982 This variable is automatically buffer-local in all buffers; its value
5983 specifies the buffer's display table.  If it is @code{nil}, there is
5984 no buffer display table.
5985 @end defvar
5987 @defvar standard-display-table
5988 The value of this variable is the standard display table, which is
5989 used when Emacs is displaying a buffer in a window with neither a
5990 window display table nor a buffer display table defined.  Its default
5991 is @code{nil}.
5992 @end defvar
5994 The @file{disp-table} library defines several functions for changing
5995 the standard display table.
5997 @node Glyphs
5998 @subsection Glyphs
5999 @cindex glyph
6001   A @dfn{glyph} is a graphical symbol which occupies a single
6002 character position on the screen.  Each glyph is represented in Lisp
6003 as a @dfn{glyph code}, which specifies a character and optionally a
6004 face to display it in (@pxref{Faces}).  The main use of glyph codes is
6005 as the entries of display tables (@pxref{Display Tables}).  The
6006 following functions are used to manipulate glyph codes:
6008 @defun make-glyph-code char &optional face
6009 This function returns a glyph code representing char @var{char} with
6010 face @var{face}.  If @var{face} is omitted or @code{nil}, the glyph
6011 uses the default face; in that case, the glyph code is an integer.  If
6012 @var{face} is non-@code{nil}, the glyph code is not necessarily an
6013 integer object.
6014 @end defun
6016 @defun glyph-char glyph
6017 This function returns the character of glyph code @var{glyph}.
6018 @end defun
6020 @defun glyph-face glyph
6021 This function returns face of glyph code @var{glyph}, or @code{nil} if
6022 @var{glyph} uses the default face.
6023 @end defun
6025 @ifnottex
6026   You can set up a @dfn{glyph table} to change how glyph codes are
6027 actually displayed on text terminals.  This feature is semi-obsolete;
6028 use @code{glyphless-char-display} instead (@pxref{Glyphless Chars}).
6030 @defvar glyph-table
6031 The value of this variable, if non-@code{nil}, is the current glyph
6032 table.  It takes effect only on character terminals; on graphical
6033 displays, all glyphs are displayed literally.  The glyph table should
6034 be a vector whose @var{g}th element specifies how to display glyph
6035 code @var{g}, where @var{g} is the glyph code for a glyph whose face
6036 is unspecified.  Each element should be one of the following:
6038 @table @asis
6039 @item @code{nil}
6040 Display this glyph literally.
6042 @item a string
6043 Display this glyph by sending the specified string to the terminal.
6045 @item a glyph code
6046 Display the specified glyph code instead.
6047 @end table
6049 Any integer glyph code greater than or equal to the length of the
6050 glyph table is displayed literally.
6051 @end defvar
6052 @end ifnottex
6054 @node Glyphless Chars
6055 @subsection Glyphless Character Display
6056 @cindex glyphless characters
6058   @dfn{Glyphless characters} are characters which are displayed in a
6059 special way, e.g.@: as a box containing a hexadecimal code, instead of
6060 being displayed literally.  These include characters which are
6061 explicitly defined to be glyphless, as well as characters for which
6062 there is no available font (on a graphical display), and characters
6063 which cannot be encoded by the terminal's coding system (on a text
6064 terminal).
6066 @defvar glyphless-char-display
6067 The value of this variable is a char-table which defines glyphless
6068 characters and how they are displayed.  Each entry must be one of the
6069 following display methods:
6071 @table @asis
6072 @item @code{nil}
6073 Display the character in the usual way.
6075 @item @code{zero-width}
6076 Don't display the character.
6078 @item @code{thin-space}
6079 Display a thin space, 1-pixel wide on graphical displays, or
6080 1-character wide on text terminals.
6082 @item @code{empty-box}
6083 Display an empty box.
6085 @item @code{hex-code}
6086 Display a box containing the Unicode codepoint of the character, in
6087 hexadecimal notation.
6089 @item an @acronym{ASCII} string
6090 Display a box containing that string.
6092 @item a cons cell @code{(@var{graphical} . @var{text})}
6093 Display with @var{graphical} on graphical displays, and with
6094 @var{text} on text terminals.  Both @var{graphical} and @var{text}
6095 must be one of the display methods described above.
6096 @end table
6098 @noindent
6099 The @code{thin-space}, @code{empty-box}, @code{hex-code}, and
6100 @acronym{ASCII} string display methods are drawn with the
6101 @code{glyphless-char} face.
6103 The char-table has one extra slot, which determines how to display any
6104 character that cannot be displayed with any available font, or cannot
6105 be encoded by the terminal's coding system.  Its value should be one
6106 of the above display methods, except @code{zero-width} or a cons cell.
6108 If a character has a non-@code{nil} entry in an active display table,
6109 the display table takes effect; in this case, Emacs does not consult
6110 @code{glyphless-char-display} at all.
6111 @end defvar
6113 @defopt glyphless-char-display-control
6114 This user option provides a convenient way to set
6115 @code{glyphless-char-display} for groups of similar characters.  Do
6116 not set its value directly from Lisp code; the value takes effect only
6117 via a custom @code{:set} function (@pxref{Variable Definitions}),
6118 which updates @code{glyphless-char-display}.
6120 Its value should be an alist of elements @code{(@var{group}
6121 . @var{method})}, where @var{group} is a symbol specifying a group of
6122 characters, and @var{method} is a symbol specifying how to display
6123 them.
6125 @var{group} should be one of the following:
6127 @table @code
6128 @item c0-control
6129 @acronym{ASCII} control characters @code{U+0000} to @code{U+001F},
6130 excluding the newline and tab characters (normally displayed as escape
6131 sequences like @samp{^A}; @pxref{Text Display,, How Text Is Displayed,
6132 emacs, The GNU Emacs Manual}).
6134 @item c1-control
6135 Non-@acronym{ASCII}, non-printing characters @code{U+0080} to
6136 @code{U+009F} (normally displayed as octal escape sequences like
6137 @samp{\230}).
6139 @item format-control
6140 Characters of Unicode General Category `Cf', such as @samp{U+200E}
6141 (Left-to-Right Mark), but excluding characters that have graphic
6142 images, such as @samp{U+00AD} (Soft Hyphen).
6144 @item no-font
6145 Characters for there is no suitable font, or which cannot be encoded
6146 by the terminal's coding system.
6147 @end table
6149 @c FIXME: this can also be `acronym', but that's not currently
6150 @c completely implemented; it applies only to the format-control
6151 @c group, and only works if the acronym is in `char-acronym-table'.
6152 The @var{method} symbol should be one of @code{zero-width},
6153 @code{thin-space}, @code{empty-box}, or @code{hex-code}.  These have
6154 the same meanings as in @code{glyphless-char-display}, above.
6155 @end defopt
6157 @node Beeping
6158 @section Beeping
6159 @cindex bell
6161   This section describes how to make Emacs ring the bell (or blink the
6162 screen) to attract the user's attention.  Be conservative about how
6163 often you do this; frequent bells can become irritating.  Also be
6164 careful not to use just beeping when signaling an error is more
6165 appropriate (@pxref{Errors}).
6167 @defun ding &optional do-not-terminate
6168 @cindex keyboard macro termination
6169 This function beeps, or flashes the screen (see @code{visible-bell} below).
6170 It also terminates any keyboard macro currently executing unless
6171 @var{do-not-terminate} is non-@code{nil}.
6172 @end defun
6174 @defun beep &optional do-not-terminate
6175 This is a synonym for @code{ding}.
6176 @end defun
6178 @defopt visible-bell
6179 This variable determines whether Emacs should flash the screen to
6180 represent a bell.  Non-@code{nil} means yes, @code{nil} means no.
6181 This is effective on graphical displays, and on text terminals
6182 provided the terminal's Termcap entry defines the visible bell
6183 capability (@samp{vb}).
6184 @end defopt
6186 @defvar ring-bell-function
6187 If this is non-@code{nil}, it specifies how Emacs should ``ring the
6188 bell''.  Its value should be a function of no arguments.  If this is
6189 non-@code{nil}, it takes precedence over the @code{visible-bell}
6190 variable.
6191 @end defvar
6193 @node Window Systems
6194 @section Window Systems
6196   Emacs works with several window systems, most notably the X Window
6197 System.  Both Emacs and X use the term ``window'', but use it
6198 differently.  An Emacs frame is a single window as far as X is
6199 concerned; the individual Emacs windows are not known to X at all.
6201 @defvar window-system
6202 This terminal-local variable tells Lisp programs what window system
6203 Emacs is using for displaying the frame.  The possible values are
6205 @table @code
6206 @item x
6207 @cindex X Window System
6208 Emacs is displaying the frame using X.
6209 @item w32
6210 Emacs is displaying the frame using native MS-Windows GUI.
6211 @item ns
6212 Emacs is displaying the frame using the Nextstep interface (used on
6213 GNUstep and Mac OS X).
6214 @item pc
6215 Emacs is displaying the frame using MS-DOS direct screen writes.
6216 @item nil
6217 Emacs is displaying the frame on a character-based terminal.
6218 @end table
6219 @end defvar
6221 @defvar initial-window-system
6222 This variable holds the value of @code{window-system} used for the
6223 first frame created by Emacs during startup.  (When Emacs is invoked
6224 with the @option{--daemon} option, it does not create any initial
6225 frames, so @code{initial-window-system} is @code{nil}.  @xref{Initial
6226 Options, daemon,, emacs, The GNU Emacs Manual}.)
6227 @end defvar
6229 @defun window-system &optional frame
6230 This function returns a symbol whose name tells what window system is
6231 used for displaying @var{frame} (which defaults to the currently
6232 selected frame).  The list of possible symbols it returns is the same
6233 one documented for the variable @code{window-system} above.
6234 @end defun
6236   Do @emph{not} use @code{window-system} and
6237 @code{initial-window-system} as predicates or boolean flag variables,
6238 if you want to write code that works differently on text terminals and
6239 graphic displays.  That is because @code{window-system} is not a good
6240 indicator of Emacs capabilities on a given display type.  Instead, use
6241 @code{display-graphic-p} or any of the other @code{display-*-p}
6242 predicates described in @ref{Display Feature Testing}.
6244 @defvar window-setup-hook
6245 This variable is a normal hook which Emacs runs after handling the
6246 initialization files.  Emacs runs this hook after it has completed
6247 loading your init file, the default initialization file (if
6248 any), and the terminal-specific Lisp code, and running the hook
6249 @code{term-setup-hook}.
6251 This hook is used for internal purposes: setting up communication with
6252 the window system, and creating the initial window.  Users should not
6253 interfere with it.
6254 @end defvar
6256 @node Bidirectional Display
6257 @section Bidirectional Display
6258 @cindex bidirectional display
6259 @cindex right-to-left text
6261   Emacs can display text written in scripts, such as Arabic, Farsi,
6262 and Hebrew, whose natural ordering for horizontal text display runs
6263 from right to left.  Furthermore, segments of Latin script and digits
6264 embedded in right-to-left text are displayed left-to-right, while
6265 segments of right-to-left script embedded in left-to-right text
6266 (e.g.@: Arabic or Hebrew text in comments or strings in a program
6267 source file) are appropriately displayed right-to-left.  We call such
6268 mixtures of left-to-right and right-to-left text @dfn{bidirectional
6269 text}.  This section describes the facilities and options for editing
6270 and displaying bidirectional text.
6272 @cindex logical order
6273 @cindex reading order
6274 @cindex visual order
6275 @cindex unicode bidirectional algorithm
6276 @cindex bidirectional reordering
6277   Text is stored in Emacs buffers and strings in @dfn{logical} (or
6278 @dfn{reading}) order, i.e.@: the order in which a human would read
6279 each character.  In right-to-left and bidirectional text, the order in
6280 which characters are displayed on the screen (called @dfn{visual
6281 order}) is not the same as logical order; the characters' screen
6282 positions do not increase monotonically with string or buffer
6283 position.  In performing this @dfn{bidirectional reordering}, Emacs
6284 follows the Unicode Bidirectional Algorithm (a.k.a.@: @acronym{UBA}),
6285 which is described in Annex #9 of the Unicode standard
6286 (@url{http://www.unicode.org/reports/tr9/}).  Emacs provides a ``Full
6287 Bidirectionality'' class implementation of the @acronym{UBA}.
6289 @defvar bidi-display-reordering
6290 If the value of this buffer-local variable is non-@code{nil} (the
6291 default), Emacs performs bidirectional reordering for display.  The
6292 reordering affects buffer text, as well as display strings and overlay
6293 strings from text and overlay properties in the buffer (@pxref{Overlay
6294 Properties}, and @pxref{Display Property}).  If the value is
6295 @code{nil}, Emacs does not perform bidirectional reordering in the
6296 buffer.
6298 The default value of @code{bidi-display-reordering} controls the
6299 reordering of strings which are not directly supplied by a buffer,
6300 including the text displayed in mode lines (@pxref{Mode Line Format})
6301 and header lines (@pxref{Header Lines}).
6302 @end defvar
6304 @cindex unibyte buffers, and bidi reordering
6305   Emacs never reorders the text of a unibyte buffer, even if
6306 @code{bidi-display-reordering} is non-@code{nil} in the buffer.  This
6307 is because unibyte buffers contain raw bytes, not characters, and thus
6308 lack the directionality properties required for reordering.
6309 Therefore, to test whether text in a buffer will be reordered for
6310 display, it is not enough to test the value of
6311 @code{bidi-display-reordering} alone.  The correct test is this:
6313 @example
6314  (if (and enable-multibyte-characters
6315           bidi-display-reordering)
6316      ;; Buffer is being reordered for display
6317    )
6318 @end example
6320   However, unibyte display and overlay strings @emph{are} reordered if
6321 their parent buffer is reordered.  This is because plain-@sc{ascii}
6322 strings are stored by Emacs as unibyte strings.  If a unibyte display
6323 or overlay string includes non-@sc{ascii} characters, these characters
6324 are assumed to have left-to-right direction.
6326 @cindex display properties, and bidi reordering of text
6327   Text covered by @code{display} text properties, by overlays with
6328 @code{display} properties whose value is a string, and by any other
6329 properties that replace buffer text, is treated as a single unit when
6330 it is reordered for display.  That is, the entire chunk of text
6331 covered by these properties is reordered together.  Moreover, the
6332 bidirectional properties of the characters in such a chunk of text are
6333 ignored, and Emacs reorders them as if they were replaced with a
6334 single character @code{U+FFFC}, known as the @dfn{Object Replacement
6335 Character}.  This means that placing a display property over a portion
6336 of text may change the way that the surrounding text is reordered for
6337 display.  To prevent this unexpected effect, always place such
6338 properties on text whose directionality is identical with text that
6339 surrounds it.
6341 @cindex base direction of a paragraph
6342   Each paragraph of bidirectional text has a @dfn{base direction},
6343 either right-to-left or left-to-right.  Left-to-right paragraphs are
6344 displayed beginning at the left margin of the window, and are
6345 truncated or continued when the text reaches the right margin.
6346 Right-to-left paragraphs are displayed beginning at the right margin,
6347 and are continued or truncated at the left margin.
6349   By default, Emacs determines the base direction of each paragraph by
6350 looking at the text at its beginning.  The precise method of
6351 determining the base direction is specified by the @acronym{UBA}; in a
6352 nutshell, the first character in a paragraph that has an explicit
6353 directionality determines the base direction of the paragraph.
6354 However, sometimes a buffer may need to force a certain base direction
6355 for its paragraphs.  For example, buffers containing program source
6356 code should force all paragraphs to be displayed left-to-right.  You
6357 can use following variable to do this:
6359 @defvar bidi-paragraph-direction
6360 If the value of this buffer-local variable is the symbol
6361 @code{right-to-left} or @code{left-to-right}, all paragraphs in the
6362 buffer are assumed to have that specified direction.  Any other value
6363 is equivalent to @code{nil} (the default), which means to determine
6364 the base direction of each paragraph from its contents.
6366 @cindex @code{prog-mode}, and @code{bidi-paragraph-direction}
6367 Modes for program source code should set this to @code{left-to-right}.
6368 Prog mode does this by default, so modes derived from Prog mode do not
6369 need to set this explicitly (@pxref{Basic Major Modes}).
6370 @end defvar
6372 @defun current-bidi-paragraph-direction &optional buffer
6373 This function returns the paragraph direction at point in the named
6374 @var{buffer}.  The returned value is a symbol, either
6375 @code{left-to-right} or @code{right-to-left}.  If @var{buffer} is
6376 omitted or @code{nil}, it defaults to the current buffer.  If the
6377 buffer-local value of the variable @code{bidi-paragraph-direction} is
6378 non-@code{nil}, the returned value will be identical to that value;
6379 otherwise, the returned value reflects the paragraph direction
6380 determined dynamically by Emacs.  For buffers whose value of
6381 @code{bidi-display-reordering} is @code{nil} as well as unibyte
6382 buffers, this function always returns @code{left-to-right}.
6383 @end defun
6385 @cindex layout on display, and bidirectional text
6386 @cindex jumbled display of bidirectional text
6387 @cindex concatenating bidirectional strings
6388   Bidirectional reordering can have surprising and unpleasant effects
6389 when two strings with bidirectional content are juxtaposed in a
6390 buffer, or otherwise programmatically concatenated into a string of
6391 text.  A typical problematic case is when a buffer consists of
6392 sequences of text ``fields'' separated by whitespace or punctuation
6393 characters, like Buffer Menu mode or Rmail Summary Mode.  Because the
6394 punctuation characters used as separators have @dfn{weak
6395 directionality}, they take on the directionality of surrounding text.
6396 As result, a numeric field that follows a field with bidirectional
6397 content can be displayed @emph{to the left} of the preceding field,
6398 messing up the expected layout.  There are several ways to avoid this
6399 problem:
6401 @itemize @minus
6402 @item
6403 Append the special character @code{U+200E}, LEFT-TO-RIGHT MARK, or
6404 @acronym{LRM}, to the end of each field that may have bidirectional
6405 content, or prepend it to the beginning of the following field.  The
6406 function @code{bidi-string-mark-left-to-right}, described below, comes
6407 in handy for this purpose.  (In a right-to-left paragraph, use
6408 @code{U+200F}, RIGHT-TO-LEFT MARK, or @acronym{RLM}, instead.)  This
6409 is one of the solutions recommended by the UBA.
6411 @item
6412 Include the tab character in the field separator.  The tab character
6413 plays the role of @dfn{segment separator} in bidirectional reordering,
6414 causing the text on either side to be reordered separately.
6416 @cindex @code{space} display spec, and bidirectional text
6417 @item
6418 Separate fields with a @code{display} property or overlay with a
6419 property value of the form @code{(space . PROPS)} (@pxref{Specified
6420 Space}).  Emacs treats this display specification as a @dfn{paragraph
6421 separator}, and reorders the text on either side separately.
6422 @end itemize
6424 @defun bidi-string-mark-left-to-right string
6425 This function returns its argument @var{string}, possibly modified,
6426 such that the result can be safely concatenated with another string,
6427 or juxtaposed with another string in a buffer, without disrupting the
6428 relative layout of this string and the next one on display.  If the
6429 string returned by this function is displayed as part of a
6430 left-to-right paragraph, it will always appear on display to the left
6431 of the text that follows it.  The function works by examining the
6432 characters of its argument, and if any of those characters could cause
6433 reordering on display, the function appends the @acronym{LRM}
6434 character to the string.  The appended @acronym{LRM} character is made
6435 invisible by giving it an @code{invisible} text property of @code{t}
6436 (@pxref{Invisible Text}).
6437 @end defun
6439   The reordering algorithm uses the bidirectional properties of the
6440 characters stored as their @code{bidi-class} property
6441 (@pxref{Character Properties}).  Lisp programs can change these
6442 properties by calling the @code{put-char-code-property} function.
6443 However, doing this requires a thorough understanding of the
6444 @acronym{UBA}, and is therefore not recommended.  Any changes to the
6445 bidirectional properties of a character have global effect: they
6446 affect all Emacs frames and windows.
6448   Similarly, the @code{mirroring} property is used to display the
6449 appropriate mirrored character in the reordered text.  Lisp programs
6450 can affect the mirrored display by changing this property.  Again, any
6451 such changes affect all of Emacs display.