display.texi 330 KB
Newer Older
1
@c -*- mode: texinfo; coding: utf-8 -*-
Glenn Morris's avatar
Glenn Morris committed
2
@c This is part of the GNU Emacs Lisp Reference Manual.
Paul Eggert's avatar
Paul Eggert committed
3
@c Copyright (C) 1990-1995, 1998-2019 Free Software Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
4
@c See the file elisp.texi for copying conditions.
5
@node Display
Glenn Morris's avatar
Glenn Morris committed
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
@chapter Emacs Display

  This chapter describes a number of features related to the display
that Emacs presents to the user.

@menu
* Refresh Screen::      Clearing the screen and redrawing everything on it.
* Forcing Redisplay::   Forcing redisplay.
* Truncation::          Folding or wrapping long text lines.
* The Echo Area::       Displaying messages at the bottom of the screen.
* Warnings::            Displaying warning messages for the user.
* Invisible Text::      Hiding part of the buffer text.
* Selective Display::   Hiding part of the buffer text (the old way).
* Temporary Displays::  Displays that go away automatically.
* Overlays::            Use overlays to highlight parts of the buffer.
21
* Size of Displayed Text::  How large displayed text is.
Glenn Morris's avatar
Glenn Morris committed
22 23 24 25
* Line Height::         Controlling the height of lines.
* Faces::               A face defines a graphics style for text characters:
                          font, colors, etc.
* Fringes::             Controlling window fringes.
26
* Scroll Bars::         Controlling scroll bars.
27
* Window Dividers::     Separating windows visually.
28
* Display Property::    Images, margins, text size, etc.
Glenn Morris's avatar
Glenn Morris committed
29
* Images::              Displaying images in Emacs buffers.
30
* Xwidgets::            Displaying native widgets in Emacs buffers.
Glenn Morris's avatar
Glenn Morris committed
31
* Buttons::             Adding clickable buttons to Emacs buffers.
32
* Abstract Display::    Emacs's Widget for Object Collections.
Glenn Morris's avatar
Glenn Morris committed
33
* Blinking::            How Emacs shows the matching open parenthesis.
34
* Character Display::   How Emacs displays individual characters.
Glenn Morris's avatar
Glenn Morris committed
35 36
* Beeping::             Audible signal to the user.
* Window Systems::      Which window system is being used.
37
* Tooltips::            Tooltip display in Emacs.
38 39
* Bidirectional Display:: Display of bidirectional scripts, such as
                             Arabic and Farsi.
Glenn Morris's avatar
Glenn Morris committed
40 41 42 43
@end menu

@node Refresh Screen
@section Refreshing the Screen
44 45
@cindex refresh the screen
@cindex screen refresh
Glenn Morris's avatar
Glenn Morris committed
46 47 48 49 50

  The function @code{redraw-frame} clears and redisplays the entire
contents of a given frame (@pxref{Frames}).  This is useful if the
screen is corrupted.

51 52
@defun redraw-frame &optional frame
This function clears and redisplays frame @var{frame}.  If @var{frame}
Glenn Morris's avatar
Glenn Morris committed
53
is omitted or @code{nil}, it redraws the selected frame.
Glenn Morris's avatar
Glenn Morris committed
54 55 56 57 58 59 60 61
@end defun

  Even more powerful is @code{redraw-display}:

@deffn Command redraw-display
This function clears and redisplays all visible frames.
@end deffn

62 63 64 65
  In Emacs, processing user input takes priority over redisplay.  If
you call these functions when input is available, they don't redisplay
immediately, but the requested redisplay does happen
eventually---after all the input has been processed.
Glenn Morris's avatar
Glenn Morris committed
66

67
  On text terminals, suspending and resuming Emacs normally also
68 69 70 71
refreshes the screen.  Some terminal emulators record separate
contents for display-oriented programs such as Emacs and for ordinary
sequential display.  If you are using such a terminal, you might want
to inhibit the redisplay on resumption.
Glenn Morris's avatar
Glenn Morris committed
72

73
@defopt no-redraw-on-reenter
Glenn Morris's avatar
Glenn Morris committed
74 75 76 77 78
@cindex suspend (cf. @code{no-redraw-on-reenter})
@cindex resume (cf. @code{no-redraw-on-reenter})
This variable controls whether Emacs redraws the entire screen after it
has been suspended and resumed.  Non-@code{nil} means there is no need
to redraw, @code{nil} means redrawing is needed.  The default is @code{nil}.
79
@end defopt
Glenn Morris's avatar
Glenn Morris committed
80 81 82 83 84

@node Forcing Redisplay
@section Forcing Redisplay
@cindex forcing redisplay

85
  Emacs normally tries to redisplay the screen whenever it waits for
86 87 88
input.  With the following function, you can request an immediate
attempt to redisplay, in the middle of Lisp code, without actually
waiting for input.
89 90

@defun redisplay &optional force
91 92
This function tries immediately to redisplay.  The optional argument
@var{force}, if non-@code{nil}, forces the redisplay to be performed,
93
instead of being preempted if input is pending.
94 95 96

The function returns @code{t} if it actually tried to redisplay, and
@code{nil} otherwise.  A value of @code{t} does not mean that
97 98
redisplay proceeded to completion; it could have been preempted by
newly arriving input.
99 100
@end defun

101 102 103 104 105
  Although @code{redisplay} tries immediately to redisplay, it does
not change how Emacs decides which parts of its frame(s) to redisplay.
By contrast, the following function adds certain windows to the
pending redisplay work (as if their contents had completely changed),
but does not immediately try to perform redisplay.
Glenn Morris's avatar
Glenn Morris committed
106

107 108 109 110 111 112 113 114 115 116
@defun force-window-update &optional object
This function forces some or all windows to be updated the next time
Emacs does a redisplay.  If @var{object} is a window, that window is
to be updated.  If @var{object} is a buffer or buffer name, all
windows displaying that buffer are to be updated.  If @var{object} is
@code{nil} (or omitted), all windows are to be updated.

This function does not do a redisplay immediately; Emacs does that as
it waits for input, or when the function @code{redisplay} is called.
@end defun
Glenn Morris's avatar
Glenn Morris committed
117

118 119 120 121 122 123 124 125 126 127 128 129 130
@defvar pre-redisplay-function
A function run just before redisplay.  It is called with one argument,
the set of windows to be redisplayed.  The set can be @code{nil},
meaning only the selected window, or @code{t}, meaning all the
windows.
@end defvar

@defvar pre-redisplay-functions
This hook is run just before redisplay.  It is called once in each
window that is about to be redisplayed, with @code{current-buffer} set
to the buffer displayed in that window.
@end defvar

Glenn Morris's avatar
Glenn Morris committed
131 132 133 134 135 136 137 138 139
@node Truncation
@section Truncation
@cindex line wrapping
@cindex line truncation
@cindex continuation lines
@cindex @samp{$} in display
@cindex @samp{\} in display

  When a line of text extends beyond the right edge of a window, Emacs
Paul Eggert's avatar
Paul Eggert committed
140
can @dfn{continue} the line (make it wrap to the next screen
Glenn Morris's avatar
Glenn Morris committed
141 142 143 144 145 146 147 148 149 150 151
line), or @dfn{truncate} the line (limit it to one screen line).  The
additional screen lines used to display a long text line are called
@dfn{continuation} lines.  Continuation is not the same as filling;
continuation happens on the screen only, not in the buffer contents,
and it breaks a line precisely at the right margin, not at a word
boundary.  @xref{Filling}.

   On a graphical display, tiny arrow images in the window fringes
indicate truncated and continued lines (@pxref{Fringes}).  On a text
terminal, a @samp{$} in the rightmost column of the window indicates
truncation; a @samp{\} on the rightmost column indicates a line that
Paul Eggert's avatar
Paul Eggert committed
152
wraps.  (The display table can specify alternate characters to use
Glenn Morris's avatar
Glenn Morris committed
153 154 155
for this; @pxref{Display Tables}).

@defopt truncate-lines
156 157 158 159
If this buffer-local variable is non-@code{nil}, lines that extend
beyond the right edge of the window are truncated; otherwise, they are
continued.  As a special exception, the variable
@code{truncate-partial-width-windows} takes precedence in
160
@dfn{partial-width} windows (i.e., windows that do not occupy the
161
entire frame width).
Glenn Morris's avatar
Glenn Morris committed
162 163 164
@end defopt

@defopt truncate-partial-width-windows
Xue Fuqiao's avatar
Xue Fuqiao committed
165
@cindex partial-width windows
166 167 168 169 170 171 172 173 174 175 176
This variable controls line truncation in @dfn{partial-width} windows.
A partial-width window is one that does not occupy the entire frame
width (@pxref{Splitting Windows}).  If the value is @code{nil}, line
truncation is determined by the variable @code{truncate-lines} (see
above).  If the value is an integer @var{n}, lines are truncated if
the partial-width window has fewer than @var{n} columns, regardless of
the value of @code{truncate-lines}; if the partial-width window has
@var{n} or more columns, line truncation is determined by
@code{truncate-lines}.  For any other non-@code{nil} value, lines are
truncated in every partial-width window, regardless of the value of
@code{truncate-lines}.
Glenn Morris's avatar
Glenn Morris committed
177 178 179 180 181
@end defopt

  When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
a window, that forces truncation.

182
@defvar wrap-prefix
183
If this buffer-local variable is non-@code{nil}, it defines a
184 185 186 187 188 189 190 191 192
@dfn{wrap prefix} which Emacs displays at the start of every
continuation line.  (If lines are truncated, @code{wrap-prefix} is
never used.)  Its value may be a string or an image (@pxref{Other
Display Specs}), or a stretch of whitespace such as specified by the
@code{:width} or @code{:align-to} display properties (@pxref{Specified
Space}).  The value is interpreted in the same way as a @code{display}
text property.  @xref{Display Property}.

A wrap prefix may also be specified for regions of text, using the
193 194
@code{wrap-prefix} text or overlay property.  This takes precedence
over the @code{wrap-prefix} variable.  @xref{Special Properties}.
195 196 197
@end defvar

@defvar line-prefix
198
If this buffer-local variable is non-@code{nil}, it defines a
199 200 201 202 203 204 205 206
@dfn{line prefix} which Emacs displays at the start of every
non-continuation line.  Its value may be a string or an image
(@pxref{Other Display Specs}), or a stretch of whitespace such as
specified by the @code{:width} or @code{:align-to} display properties
(@pxref{Specified Space}).  The value is interpreted in the same way
as a @code{display} text property.  @xref{Display Property}.

A line prefix may also be specified for regions of text using the
207 208
@code{line-prefix} text or overlay property.  This takes precedence
over the @code{line-prefix} variable.  @xref{Special Properties}.
209 210
@end defvar

211
@ignore
212 213
  If your buffer contains only very short lines, you might find it
advisable to set @code{cache-long-scans} to @code{nil}.
Glenn Morris's avatar
Glenn Morris committed
214

215
@defvar cache-long-scans
216 217 218 219
If this variable is non-@code{nil} (the default), various indentation
and motion functions, and Emacs redisplay, cache the results of
scanning the buffer, and consult the cache to avoid rescanning regions
of the buffer unless they are modified.
Glenn Morris's avatar
Glenn Morris committed
220

221
Turning off the cache speeds up processing of short lines somewhat.
Glenn Morris's avatar
Glenn Morris committed
222 223 224

This variable is automatically buffer-local in every buffer.
@end defvar
225
@end ignore
Glenn Morris's avatar
Glenn Morris committed
226 227 228 229 230 231

@node The Echo Area
@section The Echo Area
@cindex error display
@cindex echo area

Xue Fuqiao's avatar
Xue Fuqiao committed
232
@c FIXME: Why not use @xref{Minibuffers} directly?  --xfq
Glenn Morris's avatar
Glenn Morris committed
233 234 235 236
  The @dfn{echo area} is used for displaying error messages
(@pxref{Errors}), for messages made with the @code{message} primitive,
and for echoing keystrokes.  It is not the same as the minibuffer,
despite the fact that the minibuffer appears (when active) in the same
237 238
place on the screen as the echo area.  @xref{Minibuffer,, The
Minibuffer, emacs, The GNU Emacs Manual}.
Glenn Morris's avatar
Glenn Morris committed
239

240 241 242
  Apart from the functions documented in this section, you can print
Lisp objects to the echo area by specifying @code{t} as the output
stream.  @xref{Output Streams}.
Glenn Morris's avatar
Glenn Morris committed
243 244 245 246 247 248 249 250 251 252 253 254

@menu
* Displaying Messages:: Explicitly displaying text in the echo area.
* Progress::            Informing user about progress of a long operation.
* Logging Messages::    Echo area messages are logged for the user.
* Echo Area Customization:: Controlling the echo area.
@end menu

@node Displaying Messages
@subsection Displaying Messages in the Echo Area
@cindex display message in echo area

255 256
  This section describes the standard functions for displaying
messages in the echo area.
Glenn Morris's avatar
Glenn Morris committed
257 258

@defun message format-string &rest arguments
259 260
This function displays a message in the echo area.
@var{format-string} is a format string, and @var{arguments} are the
261
objects for its format specifications, like in the @code{format-message}
262 263 264
function (@pxref{Formatting Strings}).  The resulting formatted string
is displayed in the echo area; if it contains @code{face} text
properties, it is displayed with the specified faces (@pxref{Faces}).
265
The string is also added to the @file{*Messages*} buffer, but without
266 267
text properties (@pxref{Logging Messages}).

268 269 270 271
Typically grave accent and apostrophe in the format translate to
matching curved quotes, e.g., @t{"Missing `%s'"} might result in
@t{"Missing ‘foo’"}.  @xref{Text Quoting Style}, for how to influence
or inhibit this translation.
272

273 274
In batch mode, the message is printed to the standard error stream,
followed by a newline.
Glenn Morris's avatar
Glenn Morris committed
275

276 277 278
When @code{inhibit-message} is non-@code{nil}, no message will be displayed
in the echo area, it will only be logged to @samp{*Messages*}.

279 280 281 282
If the minibuffer is active, it uses the @code{minibuffer-message}
function to display the message temporarily at the end of the
minibuffer (@pxref{Minibuffer Misc}).

Glenn Morris's avatar
Glenn Morris committed
283 284
If @var{format-string} is @code{nil} or the empty string,
@code{message} clears the echo area; if the echo area has been
285
expanded automatically, this brings it back to its normal size.
Glenn Morris's avatar
Glenn Morris committed
286 287 288

@example
@group
289 290 291
(message "Reverting `%s'..." (buffer-name))
 @print{} Reverting ‘subr.el’...
@result{} "Reverting ‘subr.el’..."
Glenn Morris's avatar
Glenn Morris committed
292 293 294 295
@end group

@group
---------- Echo Area ----------
296
Reverting ‘subr.el’...
Glenn Morris's avatar
Glenn Morris committed
297 298 299 300 301 302
---------- Echo Area ----------
@end group
@end example

To automatically display a message in the echo area or in a pop-buffer,
depending on its size, use @code{display-message-or-buffer} (see below).
303 304 305 306 307 308

@strong{Warning:} If you want to use your own string as a message
verbatim, don't just write @code{(message @var{string})}.  If
@var{string} contains @samp{%}, @samp{`}, or @samp{'} it may be
reformatted, with undesirable results.  Instead, use @code{(message
"%s" @var{string})}.
Glenn Morris's avatar
Glenn Morris committed
309 310
@end defun

311 312 313 314 315
@defvar inhibit-message
When this variable is non-@code{nil}, @code{message} and related functions
will not use the Echo Area to display messages.
@end defvar

Glenn Morris's avatar
Glenn Morris committed
316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345
@defmac with-temp-message message &rest body
This construct displays a message in the echo area temporarily, during
the execution of @var{body}.  It displays @var{message}, executes
@var{body}, then returns the value of the last body form while restoring
the previous echo area contents.
@end defmac

@defun message-or-box format-string &rest arguments
This function displays a message like @code{message}, but may display it
in a dialog box instead of the echo area.  If this function is called in
a command that was invoked using the mouse---more precisely, if
@code{last-nonmenu-event} (@pxref{Command Loop Info}) is either
@code{nil} or a list---then it uses a dialog box or pop-up menu to
display the message.  Otherwise, it uses the echo area.  (This is the
same criterion that @code{y-or-n-p} uses to make a similar decision; see
@ref{Yes-or-No Queries}.)

You can force use of the mouse or of the echo area by binding
@code{last-nonmenu-event} to a suitable value around the call.
@end defun

@defun message-box format-string &rest arguments
@anchor{message-box}
This function displays a message like @code{message}, but uses a dialog
box (or a pop-up menu) whenever that is possible.  If it is impossible
to use a dialog box or pop-up menu, because the terminal does not
support them, then @code{message-box} uses the echo area, like
@code{message}.
@end defun

Eli Zaretskii's avatar
Eli Zaretskii committed
346
@defun display-message-or-buffer message &optional buffer-name action frame
Glenn Morris's avatar
Glenn Morris committed
347 348 349 350 351 352 353 354 355 356 357
This function displays the message @var{message}, which may be either a
string or a buffer.  If it is shorter than the maximum height of the
echo area, as defined by @code{max-mini-window-height}, it is displayed
in the echo area, using @code{message}.  Otherwise,
@code{display-buffer} is used to show it in a pop-up buffer.

Returns either the string shown in the echo area, or when a pop-up
buffer is used, the window used to display it.

If @var{message} is a string, then the optional argument
@var{buffer-name} is the name of the buffer used to display it when a
358
pop-up buffer is used, defaulting to @file{*Message*}.  In the case
Glenn Morris's avatar
Glenn Morris committed
359 360 361
where @var{message} is a string and displayed in the echo area, it is
not specified whether the contents are inserted into the buffer anyway.

Eli Zaretskii's avatar
Eli Zaretskii committed
362
The optional arguments @var{action} and @var{frame} are as for
Glenn Morris's avatar
Glenn Morris committed
363 364 365 366 367 368 369 370 371 372 373 374 375 376 377
@code{display-buffer}, and only used if a buffer is displayed.
@end defun

@defun current-message
This function returns the message currently being displayed in the
echo area, or @code{nil} if there is none.
@end defun

@node Progress
@subsection Reporting Operation Progress
@cindex progress reporting

  When an operation can take a while to finish, you should inform the
user about the progress it makes.  This way the user can estimate
remaining time and clearly see that Emacs is busy working, not hung.
378
A convenient way to do this is to use a @dfn{progress reporter}.
Glenn Morris's avatar
Glenn Morris committed
379

380
  Here is a working example that does nothing useful:
Glenn Morris's avatar
Glenn Morris committed
381 382 383 384 385 386 387 388 389 390 391

@smallexample
(let ((progress-reporter
       (make-progress-reporter "Collecting mana for Emacs..."
                               0  500)))
  (dotimes (k 500)
    (sit-for 0.01)
    (progress-reporter-update progress-reporter k))
  (progress-reporter-done progress-reporter))
@end smallexample

392 393 394 395 396
@defun make-progress-reporter message &optional min-value max-value current-value min-change min-time
This function creates and returns a progress reporter object, which
you will use as an argument for the other functions listed below.  The
idea is to precompute as much data as possible to make progress
reporting very fast.
Glenn Morris's avatar
Glenn Morris committed
397 398 399 400

When this progress reporter is subsequently used, it will display
@var{message} in the echo area, followed by progress percentage.
@var{message} is treated as a simple string.  If you need it to depend
401
on a filename, for instance, use @code{format-message} before calling this
Glenn Morris's avatar
Glenn Morris committed
402 403
function.

404 405
The arguments @var{min-value} and @var{max-value} should be numbers
standing for the starting and final states of the operation.  For
Paul Eggert's avatar
Paul Eggert committed
406
instance, an operation that scans a buffer should set these to the
407 408 409 410 411
results of @code{point-min} and @code{point-max} correspondingly.
@var{max-value} should be greater than @var{min-value}.

Alternatively, you can set @var{min-value} and @var{max-value} to
@code{nil}.  In that case, the progress reporter does not report
412
process percentages; it instead displays a ``spinner'' that rotates a
413 414 415 416 417 418 419 420 421 422 423 424 425
notch each time you update the progress reporter.

If @var{min-value} and @var{max-value} are numbers, you can give the
argument @var{current-value} a numerical value specifying the initial
progress; if omitted, this defaults to @var{min-value}.

The remaining arguments control the rate of echo area updates.  The
progress reporter will wait for at least @var{min-change} more
percents of the operation to be completed before printing next
message; the default is one percent.  @var{min-time} specifies the
minimum time in seconds to pass between successive prints; the default
is 0.2 seconds.  (On some operating systems, the progress reporter may
handle fractions of seconds with varying precision).
Glenn Morris's avatar
Glenn Morris committed
426 427 428 429 430

This function calls @code{progress-reporter-update}, so the first
message is printed immediately.
@end defun

431
@defun progress-reporter-update reporter &optional value suffix
Glenn Morris's avatar
Glenn Morris committed
432 433 434 435 436 437 438 439 440 441 442 443 444
This function does the main work of reporting progress of your
operation.  It displays the message of @var{reporter}, followed by
progress percentage determined by @var{value}.  If percentage is zero,
or close enough according to the @var{min-change} and @var{min-time}
arguments, then it is omitted from the output.

@var{reporter} must be the result of a call to
@code{make-progress-reporter}.  @var{value} specifies the current
state of your operation and must be between @var{min-value} and
@var{max-value} (inclusive) as passed to
@code{make-progress-reporter}.  For instance, if you scan a buffer,
then @var{value} should be the result of a call to @code{point}.

445 446 447 448 449
Optional argument @var{suffix} is a string to be displayed after
@var{reporter}'s main message and progress text.  If @var{reporter} is
a non-numerical reporter, then @var{value} should be @code{nil}, or a
string to use instead of @var{suffix}.

Glenn Morris's avatar
Glenn Morris committed
450 451 452 453 454 455 456
This function respects @var{min-change} and @var{min-time} as passed
to @code{make-progress-reporter} and so does not output new messages
on every invocation.  It is thus very fast and normally you should not
try to reduce the number of calls to it: resulting overhead will most
likely negate your effort.
@end defun

457
@defun progress-reporter-force-update reporter &optional value new-message suffix
Glenn Morris's avatar
Glenn Morris committed
458 459 460
This function is similar to @code{progress-reporter-update} except
that it prints a message in the echo area unconditionally.

461
@var{reporter}, @var{value}, and @var{suffix} have the same meaning as for
Glenn Morris's avatar
Glenn Morris committed
462
@code{progress-reporter-update}.  Optional @var{new-message} allows
463
you to change the message of the @var{reporter}.  Since this function
Glenn Morris's avatar
Glenn Morris committed
464 465 466 467 468 469
always updates the echo area, such a change will be immediately
presented to the user.
@end defun

@defun progress-reporter-done reporter
This function should be called when the operation is finished.  It
Paul Eggert's avatar
Paul Eggert committed
470
prints the message of @var{reporter} followed by word @samp{done} in the
Glenn Morris's avatar
Glenn Morris committed
471 472 473
echo area.

You should always call this function and not hope for
Paul Eggert's avatar
Paul Eggert committed
474
@code{progress-reporter-update} to print @samp{100%}.  Firstly, it may
Glenn Morris's avatar
Glenn Morris committed
475
never print it, there are many good reasons for this not to happen.
Paul Eggert's avatar
Paul Eggert committed
476
Secondly, @samp{done} is more explicit.
Glenn Morris's avatar
Glenn Morris committed
477 478
@end defun

479
@defmac dotimes-with-progress-reporter (var count [result]) reporter-or-message body@dots{}
Glenn Morris's avatar
Glenn Morris committed
480 481
This is a convenience macro that works the same way as @code{dotimes}
does, but also reports loop progress using the functions described
Eli Zaretskii's avatar
Eli Zaretskii committed
482 483 484
above.  It allows you to save some typing.  The argument
@var{reporter-or-message} can be either a string or a progress
reporter object.
Glenn Morris's avatar
Glenn Morris committed
485

Eli Zaretskii's avatar
Eli Zaretskii committed
486 487
You can rewrite the example in the beginning of this subsection using
this macro as follows:
Glenn Morris's avatar
Glenn Morris committed
488 489

@example
Eli Zaretskii's avatar
Eli Zaretskii committed
490
@group
Glenn Morris's avatar
Glenn Morris committed
491 492 493 494
(dotimes-with-progress-reporter
    (k 500)
    "Collecting some mana for Emacs..."
  (sit-for 0.01))
Eli Zaretskii's avatar
Eli Zaretskii committed
495
@end group
Glenn Morris's avatar
Glenn Morris committed
496
@end example
497

Eli Zaretskii's avatar
Eli Zaretskii committed
498 499 500 501
Using a reporter object as the @var{reporter-or-message} argument is
useful if you want to specify the optional arguments in
@var{make-progress-reporter}.  For instance, you can write the
previous example as follows:
502 503

@example
Eli Zaretskii's avatar
Eli Zaretskii committed
504
@group
505 506 507 508
(dotimes-with-progress-reporter
    (k 500)
    (make-progress-reporter "Collecting some mana for Emacs..." 0 500 0 1 1.5)
  (sit-for 0.01))
Eli Zaretskii's avatar
Eli Zaretskii committed
509
@end group
510
@end example
Glenn Morris's avatar
Glenn Morris committed
511 512
@end defmac

513 514 515
@defmac dolist-with-progress-reporter (var count [result]) reporter-or-message body@dots{}
This is another convenience macro that works the same way as @code{dolist}
does, but also reports loop progress using the functions described
Eli Zaretskii's avatar
Eli Zaretskii committed
516 517 518
above.  As in @code{dotimes-with-progress-reporter},
@code{reporter-or-message} can be a progress reporter or a string.
You can rewrite the previous example with this macro as follows:
519 520

@example
Eli Zaretskii's avatar
Eli Zaretskii committed
521
@group
522 523 524 525
(dolist-with-progress-reporter
    (k (number-sequence 0 500))
    "Collecting some mana for Emacs..."
  (sit-for 0.01))
Eli Zaretskii's avatar
Eli Zaretskii committed
526
@end group
527 528 529
@end example
@end defmac

Glenn Morris's avatar
Glenn Morris committed
530
@node Logging Messages
531
@subsection Logging Messages in @file{*Messages*}
Glenn Morris's avatar
Glenn Morris committed
532 533 534
@cindex logging echo-area messages

  Almost all the messages displayed in the echo area are also recorded
535
in the @file{*Messages*} buffer so that the user can refer back to
Glenn Morris's avatar
Glenn Morris committed
536
them.  This includes all the messages that are output with
537 538 539
@code{message}.  By default, this buffer is read-only and uses the major
mode @code{messages-buffer-mode}.  Nothing prevents the user from
killing the @file{*Messages*} buffer, but the next display of a message
540 541
recreates it.  Any Lisp code that needs to access the
@file{*Messages*} buffer directly and wants to ensure that it exists
Glenn Morris's avatar
Glenn Morris committed
542
should use the function @code{messages-buffer}.
543 544

@defun messages-buffer
545 546
This function returns the @file{*Messages*} buffer.  If it does not
exist, it creates it, and switches it to @code{messages-buffer-mode}.
547
@end defun
Glenn Morris's avatar
Glenn Morris committed
548 549

@defopt message-log-max
550
This variable specifies how many lines to keep in the @file{*Messages*}
Glenn Morris's avatar
Glenn Morris committed
551 552 553 554 555 556 557 558 559 560
buffer.  The value @code{t} means there is no limit on how many lines to
keep.  The value @code{nil} disables message logging entirely.  Here's
how to display a message and prevent it from being logged:

@example
(let (message-log-max)
  (message @dots{}))
@end example
@end defopt

561
  To make @file{*Messages*} more convenient for the user, the logging
Glenn Morris's avatar
Glenn Morris committed
562 563 564 565
facility combines successive identical messages.  It also combines
successive related messages for the sake of two cases: question
followed by answer, and a series of progress messages.

Paul Eggert's avatar
Paul Eggert committed
566
  A question followed by an answer has two messages like the
Glenn Morris's avatar
Glenn Morris committed
567 568 569 570 571
ones produced by @code{y-or-n-p}: the first is @samp{@var{question}},
and the second is @samp{@var{question}...@var{answer}}.  The first
message conveys no additional information beyond what's in the second,
so logging the second message discards the first from the log.

Paul Eggert's avatar
Paul Eggert committed
572
  A series of progress messages has successive messages like
Glenn Morris's avatar
Glenn Morris committed
573 574 575 576 577 578 579 580 581 582 583 584
those produced by @code{make-progress-reporter}.  They have the form
@samp{@var{base}...@var{how-far}}, where @var{base} is the same each
time, while @var{how-far} varies.  Logging each message in the series
discards the previous one, provided they are consecutive.

  The functions @code{make-progress-reporter} and @code{y-or-n-p}
don't have to do anything special to activate the message log
combination feature.  It operates whenever two consecutive messages
are logged that share a common prefix ending in @samp{...}.

@node Echo Area Customization
@subsection Echo Area Customization
585
@cindex echo area customization
Glenn Morris's avatar
Glenn Morris committed
586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603

  These variables control details of how the echo area works.

@defvar cursor-in-echo-area
This variable controls where the cursor appears when a message is
displayed in the echo area.  If it is non-@code{nil}, then the cursor
appears at the end of the message.  Otherwise, the cursor appears at
point---not in the echo area at all.

The value is normally @code{nil}; Lisp programs bind it to @code{t}
for brief periods of time.
@end defvar

@defvar echo-area-clear-hook
This normal hook is run whenever the echo area is cleared---either by
@code{(message nil)} or for any other reason.
@end defvar

604
@defopt echo-keystrokes
Glenn Morris's avatar
Glenn Morris committed
605
This variable determines how much time should elapse before command
606
characters echo.  Its value must be a number, and specifies the
Glenn Morris's avatar
Glenn Morris committed
607 608 609 610 611 612 613
number of seconds to wait before echoing.  If the user types a prefix
key (such as @kbd{C-x}) and then delays this many seconds before
continuing, the prefix key is echoed in the echo area.  (Once echoing
begins in a key sequence, all subsequent characters in the same key
sequence are echoed immediately.)

If the value is zero, then command input is not echoed.
614
@end defopt
Glenn Morris's avatar
Glenn Morris committed
615 616 617 618 619

@defvar message-truncate-lines
Normally, displaying a long message resizes the echo area to display
the entire message.  But if the variable @code{message-truncate-lines}
is non-@code{nil}, the echo area does not resize, and the message is
620
truncated to fit it.
Glenn Morris's avatar
Glenn Morris committed
621 622 623 624
@end defvar

  The variable @code{max-mini-window-height}, which specifies the
maximum height for resizing minibuffer windows, also applies to the
625
echo area (which is really a special use of the minibuffer window;
626
@pxref{Minibuffer Windows}).
Glenn Morris's avatar
Glenn Morris committed
627 628 629 630 631 632 633 634 635 636 637 638

@node Warnings
@section Reporting Warnings
@cindex warnings

  @dfn{Warnings} are a facility for a program to inform the user of a
possible problem, but continue running.

@menu
* Warning Basics::      Warnings concepts and functions to report them.
* Warning Variables::   Variables programs bind to customize their warnings.
* Warning Options::     Variables users set to control display of warnings.
639
* Delayed Warnings::    Deferring a warning until the end of a command.
Glenn Morris's avatar
Glenn Morris committed
640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676
@end menu

@node Warning Basics
@subsection Warning Basics
@cindex severity level

  Every warning has a textual message, which explains the problem for
the user, and a @dfn{severity level} which is a symbol.  Here are the
possible severity levels, in order of decreasing severity, and their
meanings:

@table @code
@item :emergency
A problem that will seriously impair Emacs operation soon
if you do not attend to it promptly.
@item :error
A report of data or circumstances that are inherently wrong.
@item :warning
A report of data or circumstances that are not inherently wrong, but
raise suspicion of a possible problem.
@item :debug
A report of information that may be useful if you are debugging.
@end table

  When your program encounters invalid input data, it can either
signal a Lisp error by calling @code{error} or @code{signal} or report
a warning with severity @code{:error}.  Signaling a Lisp error is the
easiest thing to do, but it means the program cannot continue
processing.  If you want to take the trouble to implement a way to
continue processing despite the bad data, then reporting a warning of
severity @code{:error} is the right way to inform the user of the
problem.  For instance, the Emacs Lisp byte compiler can report an
error that way and continue compiling other functions.  (If the
program signals a Lisp error and then handles it with
@code{condition-case}, the user won't see the error message; it could
show the message to the user by reporting it as a warning.)

677 678
@c FIXME: Why use "(bytecomp)" instead of "'bytecomp" or simply
@c "bytecomp" here?  The parens are part of warning-type-format but
Xue Fuqiao's avatar
Comment  
Xue Fuqiao committed
679
@c not part of the warning type. --xfq
Glenn Morris's avatar
Glenn Morris committed
680 681 682 683 684 685 686 687 688 689 690 691 692 693
@cindex warning type
  Each warning has a @dfn{warning type} to classify it.  The type is a
list of symbols.  The first symbol should be the custom group that you
use for the program's user options.  For example, byte compiler
warnings use the warning type @code{(bytecomp)}.  You can also
subcategorize the warnings, if you wish, by using more symbols in the
list.

@defun display-warning type message &optional level buffer-name
This function reports a warning, using @var{message} as the message
and @var{type} as the warning type.  @var{level} should be the
severity level, with @code{:warning} being the default.

@var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
694
for logging the warning.  By default, it is @file{*Warnings*}.
Glenn Morris's avatar
Glenn Morris committed
695 696 697
@end defun

@defun lwarn type level message &rest args
Paul Eggert's avatar
Paul Eggert committed
698
This function reports a warning using the value of @code{(format-message
699 700
@var{message} @var{args}...)} as the message in the @file{*Warnings*}
buffer.  In other respects it is equivalent to @code{display-warning}.
Glenn Morris's avatar
Glenn Morris committed
701 702 703
@end defun

@defun warn message &rest args
Paul Eggert's avatar
Paul Eggert committed
704
This function reports a warning using the value of @code{(format-message
Glenn Morris's avatar
Glenn Morris committed
705 706 707 708 709 710 711 712
@var{message} @var{args}...)} as the message, @code{(emacs)} as the
type, and @code{:warning} as the severity level.  It exists for
compatibility only; we recommend not using it, because you should
specify a specific warning type.
@end defun

@node Warning Variables
@subsection Warning Variables
713
@cindex warning variables
Glenn Morris's avatar
Glenn Morris committed
714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779

  Programs can customize how their warnings appear by binding
the variables described in this section.

@defvar warning-levels
This list defines the meaning and severity order of the warning
severity levels.  Each element defines one severity level,
and they are arranged in order of decreasing severity.

Each element has the form @code{(@var{level} @var{string}
@var{function})}, where @var{level} is the severity level it defines.
@var{string} specifies the textual description of this level.
@var{string} should use @samp{%s} to specify where to put the warning
type information, or it can omit the @samp{%s} so as not to include
that information.

The optional @var{function}, if non-@code{nil}, is a function to call
with no arguments, to get the user's attention.

Normally you should not change the value of this variable.
@end defvar

@defvar warning-prefix-function
If non-@code{nil}, the value is a function to generate prefix text for
warnings.  Programs can bind the variable to a suitable function.
@code{display-warning} calls this function with the warnings buffer
current, and the function can insert text in it.  That text becomes
the beginning of the warning message.

The function is called with two arguments, the severity level and its
entry in @code{warning-levels}.  It should return a list to use as the
entry (this value need not be an actual member of
@code{warning-levels}).  By constructing this value, the function can
change the severity of the warning, or specify different handling for
a given severity level.

If the variable's value is @code{nil} then there is no function
to call.
@end defvar

@defvar warning-series
Programs can bind this variable to @code{t} to say that the next
warning should begin a series.  When several warnings form a series,
that means to leave point on the first warning of the series, rather
than keep moving it for each warning so that it appears on the last one.
The series ends when the local binding is unbound and
@code{warning-series} becomes @code{nil} again.

The value can also be a symbol with a function definition.  That is
equivalent to @code{t}, except that the next warning will also call
the function with no arguments with the warnings buffer current.  The
function can insert text which will serve as a header for the series
of warnings.

Once a series has begun, the value is a marker which points to the
buffer position in the warnings buffer of the start of the series.

The variable's normal value is @code{nil}, which means to handle
each warning separately.
@end defvar

@defvar warning-fill-prefix
When this variable is non-@code{nil}, it specifies a fill prefix to
use for filling each warning's text.
@end defvar

780 781 782 783
@defvar warning-fill-column
The column at which to fill warnings.
@end defvar

Glenn Morris's avatar
Glenn Morris committed
784 785 786 787 788 789 790 791 792 793 794
@defvar warning-type-format
This variable specifies the format for displaying the warning type
in the warning message.  The result of formatting the type this way
gets included in the message under the control of the string in the
entry in @code{warning-levels}.  The default value is @code{" (%s)"}.
If you bind it to @code{""} then the warning type won't appear at
all.
@end defvar

@node Warning Options
@subsection Warning Options
795
@cindex warning options
Glenn Morris's avatar
Glenn Morris committed
796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826

  These variables are used by users to control what happens
when a Lisp program reports a warning.

@defopt warning-minimum-level
This user option specifies the minimum severity level that should be
shown immediately to the user.  The default is @code{:warning}, which
means to immediately display all warnings except @code{:debug}
warnings.
@end defopt

@defopt warning-minimum-log-level
This user option specifies the minimum severity level that should be
logged in the warnings buffer.  The default is @code{:warning}, which
means to log all warnings except @code{:debug} warnings.
@end defopt

@defopt warning-suppress-types
This list specifies which warning types should not be displayed
immediately for the user.  Each element of the list should be a list
of symbols.  If its elements match the first elements in a warning
type, then that warning is not displayed immediately.
@end defopt

@defopt warning-suppress-log-types
This list specifies which warning types should not be logged in the
warnings buffer.  Each element of the list should be a list of
symbols.  If it matches the first few elements in a warning type, then
that warning is not logged.
@end defopt

827 828
@node Delayed Warnings
@subsection Delayed Warnings
829
@cindex delayed warnings
830 831 832

Sometimes, you may wish to avoid showing a warning while a command is
running, and only show it only after the end of the command.  You can
833 834 835 836 837 838 839
use the function @code{delay-warning} for this.

@defun delay-warning type message &optional level buffer-name
This function is the delayed counterpart to @code{display-warning}
(@pxref{Warning Basics}), and it is called with the same arguments.
The warning message is queued into @code{delayed-warnings-list}.
@end defun
840 841 842 843 844 845 846 847 848 849 850

@defvar delayed-warnings-list
The value of this variable is a list of warnings to be displayed after
the current command has finished.  Each element must be a list

@smallexample
(@var{type} @var{message} [@var{level} [@var{buffer-name}]])
@end smallexample

@noindent
with the same form, and the same meanings, as the argument list of
851 852
@code{display-warning}.  Immediately after running
@code{post-command-hook} (@pxref{Command Overview}), the Emacs
853 854 855 856 857 858 859 860 861
command loop displays all the warnings specified by this variable,
then resets it to @code{nil}.
@end defvar

  Programs which need to further customize the delayed warnings
mechanism can change the variable @code{delayed-warnings-hook}:

@defvar delayed-warnings-hook
This is a normal hook which is run by the Emacs command loop, after
Glenn Morris's avatar
Glenn Morris committed
862
@code{post-command-hook}, in order to process and display delayed
863 864 865 866 867 868 869 870 871 872 873
warnings.

Its default value is a list of two functions:

@smallexample
(collapse-delayed-warnings display-delayed-warnings)
@end smallexample

@findex collapse-delayed-warnings
@findex display-delayed-warnings
@noindent
874 875
The function @code{collapse-delayed-warnings} removes repeated entries
from @code{delayed-warnings-list}.  The function
876 877 878 879 880
@code{display-delayed-warnings} calls @code{display-warning} on each
of the entries in @code{delayed-warnings-list}, in turn, and then sets
@code{delayed-warnings-list} to @code{nil}.
@end defvar

Glenn Morris's avatar
Glenn Morris committed
881 882 883 884 885 886
@node Invisible Text
@section Invisible Text

@cindex invisible text
You can make characters @dfn{invisible}, so that they do not appear on
the screen, with the @code{invisible} property.  This can be either a
887
text property (@pxref{Text Properties}) or an overlay property
Glenn Morris's avatar
Glenn Morris committed
888
(@pxref{Overlays}).  Cursor motion also partly ignores these
889 890 891
characters; if the command loop finds that point is inside a range of
invisible text after a command, it relocates point to the other side
of the text.
Glenn Morris's avatar
Glenn Morris committed
892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930

In the simplest case, any non-@code{nil} @code{invisible} property makes
a character invisible.  This is the default case---if you don't alter
the default value of @code{buffer-invisibility-spec}, this is how the
@code{invisible} property works.  You should normally use @code{t}
as the value of the @code{invisible} property if you don't plan
to set @code{buffer-invisibility-spec} yourself.

More generally, you can use the variable @code{buffer-invisibility-spec}
to control which values of the @code{invisible} property make text
invisible.  This permits you to classify the text into different subsets
in advance, by giving them different @code{invisible} values, and
subsequently make various subsets visible or invisible by changing the
value of @code{buffer-invisibility-spec}.

Controlling visibility with @code{buffer-invisibility-spec} is
especially useful in a program to display the list of entries in a
database.  It permits the implementation of convenient filtering
commands to view just a part of the entries in the database.  Setting
this variable is very fast, much faster than scanning all the text in
the buffer looking for properties to change.

@defvar buffer-invisibility-spec
This variable specifies which kinds of @code{invisible} properties
actually make a character invisible.  Setting this variable makes it
buffer-local.

@table @asis
@item @code{t}
A character is invisible if its @code{invisible} property is
non-@code{nil}.  This is the default.

@item a list
Each element of the list specifies a criterion for invisibility; if a
character's @code{invisible} property fits any one of these criteria,
the character is invisible.  The list can have two kinds of elements:

@table @code
@item @var{atom}
931 932 933
A character is invisible if its @code{invisible} property value is
@var{atom} or if it is a list with @var{atom} as a member; comparison
is done with @code{eq}.
Glenn Morris's avatar
Glenn Morris committed
934 935 936

@item (@var{atom} . t)
A character is invisible if its @code{invisible} property value is
937 938 939
@var{atom} or if it is a list with @var{atom} as a member; comparison
is done with @code{eq}.  Moreover, a sequence of such characters
displays as an ellipsis.
Glenn Morris's avatar
Glenn Morris committed
940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973
@end table
@end table
@end defvar

  Two functions are specifically provided for adding elements to
@code{buffer-invisibility-spec} and removing elements from it.

@defun add-to-invisibility-spec element
This function adds the element @var{element} to
@code{buffer-invisibility-spec}.  If @code{buffer-invisibility-spec}
was @code{t}, it changes to a list, @code{(t)}, so that text whose
@code{invisible} property is @code{t} remains invisible.
@end defun

@defun remove-from-invisibility-spec element
This removes the element @var{element} from
@code{buffer-invisibility-spec}.  This does nothing if @var{element}
is not in the list.
@end defun

  A convention for use of @code{buffer-invisibility-spec} is that a
major mode should use the mode's own name as an element of
@code{buffer-invisibility-spec} and as the value of the
@code{invisible} property:

@example
;; @r{If you want to display an ellipsis:}
(add-to-invisibility-spec '(my-symbol . t))
;; @r{If you don't want ellipsis:}
(add-to-invisibility-spec 'my-symbol)

(overlay-put (make-overlay beginning end)
             'invisible 'my-symbol)

974
;; @r{When done with the invisibility:}
Glenn Morris's avatar
Glenn Morris committed
975 976 977 978 979
(remove-from-invisibility-spec '(my-symbol . t))
;; @r{Or respectively:}
(remove-from-invisibility-spec 'my-symbol)
@end example

980 981 982 983
  You can check for invisibility using the following function:

@defun invisible-p pos-or-prop
If @var{pos-or-prop} is a marker or number, this function returns a
984 985
non-@code{nil} value if the text at that position is currently
invisible.
986 987 988 989 990 991

If @var{pos-or-prop} is any other kind of Lisp object, that is taken
to mean a possible value of the @code{invisible} text or overlay
property.  In that case, this function returns a non-@code{nil} value
if that value would cause text to become invisible, based on the
current value of @code{buffer-invisibility-spec}.
992 993 994 995

The return value of this function is @code{t} if the text would be
completely hidden on display, or a non-@code{nil}, non-@code{t} value
if the text would be replaced by an ellipsis.
996 997
@end defun

Glenn Morris's avatar
Glenn Morris committed
998 999
@vindex line-move-ignore-invisible
  Ordinarily, functions that operate on text or move point do not care
1000 1001 1002 1003 1004 1005 1006 1007
whether the text is invisible, they process invisible characters and
visible characters alike.  The user-level line motion commands,
such as @code{next-line}, @code{previous-line}, ignore invisible
newlines if @code{line-move-ignore-invisible} is non-@code{nil} (the
default), i.e., behave like these invisible newlines didn't exist in
the buffer, but only because they are explicitly programmed to do so.

  If a command ends with point inside or at the boundary of
1008 1009 1010 1011 1012 1013 1014 1015 1016
invisible text, the main editing loop relocates point to one of the
two ends of the invisible text.  Emacs chooses the direction of
relocation so that it is the same as the overall movement direction of
the command; if in doubt, it prefers a position where an inserted char
would not inherit the @code{invisible} property.  Additionally, if the
text is not replaced by an ellipsis and the command only moved within
the invisible text, then point is moved one extra character so as to
try and reflect the command's movement by a visible movement of the
cursor.
1017 1018 1019 1020 1021 1022

  Thus, if the command moved point back to an invisible range (with the usual
stickiness), Emacs moves point back to the beginning of that range.  If the
command moved point forward into an invisible range, Emacs moves point forward
to the first visible character that follows the invisible text and then forward
one more character.
Glenn Morris's avatar
Glenn Morris committed
1023

1024 1025 1026 1027
  These @dfn{adjustments} of point that ended up in the middle of
invisible text can be disabled by setting @code{disable-point-adjustment}
to a non-@code{nil} value.  @xref{Adjusting Point}.

Glenn Morris's avatar
Glenn Morris committed
1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050
  Incremental search can make invisible overlays visible temporarily
and/or permanently when a match includes invisible text.  To enable
this, the overlay should have a non-@code{nil}
@code{isearch-open-invisible} property.  The property value should be a
function to be called with the overlay as an argument.  This function
should make the overlay visible permanently; it is used when the match
overlaps the overlay on exit from the search.

  During the search, such overlays are made temporarily visible by
temporarily modifying their invisible and intangible properties.  If you
want this to be done differently for a certain overlay, give it an
@code{isearch-open-invisible-temporary} property which is a function.
The function is called with two arguments: the first is the overlay, and
the second is @code{nil} to make the overlay visible, or @code{t} to
make it invisible again.

@node Selective Display
@section Selective Display
@c @cindex selective display   Duplicates selective-display

  @dfn{Selective display} refers to a pair of related features for
hiding certain lines on the screen.

1051
@cindex explicit selective display
1052 1053
  The first variant, explicit selective display, was designed for use in a Lisp
program: it controls which lines are hidden by altering the text.  This kind of
1054 1055
hiding is now obsolete and deprecated; instead you should use the
@code{invisible} property (@pxref{Invisible Text}) to get the same effect.
Glenn Morris's avatar
Glenn Morris committed
1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102

  In the second variant, the choice of lines to hide is made
automatically based on indentation.  This variant is designed to be a
user-level feature.

  The way you control explicit selective display is by replacing a
newline (control-j) with a carriage return (control-m).  The text that
was formerly a line following that newline is now hidden.  Strictly
speaking, it is temporarily no longer a line at all, since only
newlines can separate lines; it is now part of the previous line.

  Selective display does not directly affect editing commands.  For
example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly
into hidden text.  However, the replacement of newline characters with
carriage return characters affects some editing commands.  For
example, @code{next-line} skips hidden lines, since it searches only
for newlines.  Modes that use selective display can also define
commands that take account of the newlines, or that control which
parts of the text are hidden.

  When you write a selectively displayed buffer into a file, all the
control-m's are output as newlines.  This means that when you next read
in the file, it looks OK, with nothing hidden.  The selective display
effect is seen only within Emacs.

@defvar selective-display
This buffer-local variable enables selective display.  This means that
lines, or portions of lines, may be made hidden.

@itemize @bullet
@item
If the value of @code{selective-display} is @code{t}, then the character
control-m marks the start of hidden text; the control-m, and the rest
of the line following it, are not displayed.  This is explicit selective
display.

@item
If the value of @code{selective-display} is a positive integer, then
lines that start with more than that many columns of indentation are not
displayed.
@end itemize

When some portion of a buffer is hidden, the vertical movement
commands operate as if that portion did not exist, allowing a single
@code{next-line} command to skip any number of hidden lines.
However, character movement commands (such as @code{forward-char}) do
not skip the hidden portion, and it is possible (if tricky) to insert
1103
or delete text in a hidden portion.
Glenn Morris's avatar
Glenn Morris committed
1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138

In the examples below, we show the @emph{display appearance} of the
buffer @code{foo}, which changes with the value of
@code{selective-display}.  The @emph{contents} of the buffer do not
change.

@example
@group
(setq selective-display nil)
     @result{} nil

---------- Buffer: foo ----------
1 on this column
 2on this column
  3n this column
  3n this column
 2on this column
1 on this column
---------- Buffer: foo ----------
@end group

@group
(setq selective-display 2)
     @result{} 2

---------- Buffer: foo ----------
1 on this column
 2on this column
 2on this column
1 on this column
---------- Buffer: foo ----------
@end group
@end example
@end defvar

1139
@defopt selective-display-ellipses
Glenn Morris's avatar
Glenn Morris committed
1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159
If this buffer-local variable is non-@code{nil}, then Emacs displays
@samp{@dots{}} at the end of a line that is followed by hidden text.
This example is a continuation of the previous one.

@example
@group
(setq selective-display-ellipses t)
     @result{} t

---------- Buffer: foo ----------
1 on this column
 2on this column ...
 2on this column
1 on this column
---------- Buffer: foo ----------
@end group
@end example

You can use a display table to substitute other text for the ellipsis
(@samp{@dots{}}).  @xref{Display Tables}.
1160
@end defopt
Glenn Morris's avatar
Glenn Morris committed
1161 1162 1163

@node Temporary Displays
@section Temporary Displays
1164 1165
@cindex temporary display
@cindex temporary buffer display
Glenn Morris's avatar
Glenn Morris committed
1166 1167 1168 1169 1170

  Temporary displays are used by Lisp programs to put output into a
buffer and then present it to the user for perusal rather than for
editing.  Many help commands use this feature.

1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183
@defmac with-output-to-temp-buffer buffer-name body@dots{}
This function executes the forms in @var{body} while arranging to insert
any output they print into the buffer named @var{buffer-name}, which is
first created if necessary, and put into Help mode.  (See the similar
form @code{with-temp-buffer-window} below.)  Finally, the buffer is
displayed in some window, but that window is not selected.

If the forms in @var{body} do not change the major mode in the output
buffer, so that it is still Help mode at the end of their execution,
then @code{with-output-to-temp-buffer} makes this buffer read-only at
the end, and also scans it for function and variable names to make them
into clickable cross-references.  @xref{Docstring hyperlinks, , Tips for
Documentation Strings}, in particular the item on hyperlinks in
Glenn Morris's avatar
Glenn Morris committed
1184 1185
documentation strings, for more details.

1186 1187 1188 1189
The string @var{buffer-name} specifies the temporary buffer, which need
not already exist.  The argument must be a string, not a buffer.  The
buffer is erased initially (with no questions asked), and it is marked
as unmodified after @code{with-output-to-temp-buffer} exits.
Glenn Morris's avatar
Glenn Morris committed
1190 1191

@code{with-output-to-temp-buffer} binds @code{standard-output} to the
1192 1193
temporary buffer, then it evaluates the forms in @var{body}.  Output
using the Lisp output functions within @var{body} goes by default to
Glenn Morris's avatar
Glenn Morris committed
1194 1195 1196 1197 1198 1199 1200
that buffer (but screen display and messages in the echo area, although
they are ``output'' in the general sense of the word, are not affected).
@xref{Output Functions}.

Several hooks are available for customizing the behavior
of this construct; they are listed below.

1201
The value of the last form in @var{body} is returned.
Glenn Morris's avatar
Glenn Morris committed
1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216

@example
@group
---------- Buffer: foo ----------
 This is the contents of foo.
---------- Buffer: foo ----------
@end group

@group
(with-output-to-temp-buffer "foo"
    (print 20)
    (print standard-output))
@result{} #<buffer foo>

---------- Buffer: foo ----------
Xue Fuqiao's avatar
Xue Fuqiao committed
1217

Glenn Morris's avatar
Glenn Morris committed
1218 1219 1220 1221 1222 1223 1224
20

#<buffer foo>

---------- Buffer: foo ----------
@end group
@end example
1225
@end defmac
Glenn Morris's avatar
Glenn Morris committed
1226

1227
@defopt temp-buffer-show-function
Glenn Morris's avatar
Glenn Morris committed
1228 1229 1230 1231 1232 1233 1234 1235
If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
calls it as a function to do the job of displaying a help buffer.  The
function gets one argument, which is the buffer it should display.

It is a good idea for this function to run @code{temp-buffer-show-hook}
just as @code{with-output-to-temp-buffer} normally would, inside of
@code{save-selected-window} and with the chosen window and buffer
selected.
1236
@end defopt
Glenn Morris's avatar
Glenn Morris committed
1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247

@defvar temp-buffer-setup-hook
This normal hook is run by @code{with-output-to-temp-buffer} before
evaluating @var{body}.  When the hook runs, the temporary buffer is
current.  This hook is normally set up with a function to put the
buffer in Help mode.
@end defvar

@defvar temp-buffer-show-hook
This normal hook is run by @code{with-output-to-temp-buffer} after
displaying the temporary buffer.  When the hook runs, the temporary buffer
1248
is current, and the window it was displayed in is selected.
Glenn Morris's avatar
Glenn Morris committed
1249 1250
@end defvar

1251
@defmac with-temp-buffer-window buffer-or-name action quit-function body@dots{}
1252
This macro is similar to @code{with-output-to-temp-buffer}.  Like that
1253 1254
construct, it executes @var{body} while arranging to insert any output
it prints into the buffer named @var{buffer-or-name} and displays that
1255
buffer in some window.  Unlike @code{with-output-to-temp-buffer},
1256
however, it does not automatically switch that buffer to Help mode.
1257

1258 1259 1260 1261 1262
The argument @var{buffer-or-name} specifies the temporary buffer.  It
can be either a buffer, which must already exist, or a string, in which
case a buffer of that name is created, if necessary.  The buffer is
marked as unmodified and read-only when @code{with-temp-buffer-window}
exits.
1263 1264

This macro does not call @code{temp-buffer-show-function}.  Rather, it
1265 1266
passes the @var{action} argument to @code{display-buffer}
(@pxref{Choosing Window}) in order to display the buffer.
1267

1268 1269 1270
The value of the last form in @var{body} is returned, unless the
argument @var{quit-function} is specified.  In that case, it is called
with two arguments: the window showing the buffer and the result of
1271 1272
@var{body}.  The final return value is then whatever @var{quit-function}
returns.
1273 1274 1275 1276 1277 1278 1279 1280

@vindex temp-buffer-window-setup-hook
@vindex temp-buffer-window-show-hook
This macro uses the normal hooks @code{temp-buffer-window-setup-hook}
and @code{temp-buffer-window-show-hook} in place of the analogous hooks
run by @code{with-output-to-temp-buffer}.
@end defmac

1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295
The two constructs described next are mostly identical to
@code{with-temp-buffer-window} but differ from it as specified:

@defmac with-current-buffer-window buffer-or-name action quit-function &rest body
This macro is like @code{with-temp-buffer-window} but unlike that makes
the buffer specified by @var{buffer-or-name} current for running
@var{body}.
@end defmac

@defmac with-displayed-buffer-window buffer-or-name action quit-function &rest body
This macro is like @code{with-current-buffer-window} but unlike that
displays the buffer specified by @var{buffer-or-name} @emph{before}
running @var{body}.
@end defmac

1296
A window showing a temporary buffer can be fitted to the size of that
1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328
buffer using the following mode:

@defopt temp-buffer-resize-mode
When this minor mode is enabled, windows showing a temporary buffer are
automatically resized to fit their buffer's contents.

A window is resized if and only if it has been specially created for the
buffer.  In particular, windows that have shown another buffer before
are not resized.  By default, this mode uses @code{fit-window-to-buffer}
(@pxref{Resizing Windows}) for resizing.  You can specify a different
function by customizing the options @code{temp-buffer-max-height} and
@code{temp-buffer-max-width} below.
@end defopt

@defopt temp-buffer-max-height
This option specifies the maximum height (in lines) of a window
displaying a temporary buffer when @code{temp-buffer-resize-mode} is
enabled.  It can also be a function to be called to choose the height
for such a buffer.  It gets one argument, the buffer, and should return
a positive integer.  At the time the function is called, the window to
be resized is selected.
@end defopt

@defopt temp-buffer-max-width
This option specifies the maximum width of a window (in columns)
displaying a temporary buffer when @code{temp-buffer-resize-mode} is
enabled.  It can also be a function to be called to choose the width for
such a buffer.  It gets one argument, the buffer, and should return a
positive integer.  At the time the function is called, the window to be
resized is selected.
@end defopt

1329
The following function uses the current buffer for temporary display:
1330

Glenn Morris's avatar
Glenn Morris committed
1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389
@defun momentary-string-display string position &optional char message
This function momentarily displays @var{string} in the current buffer at
@var{position}.  It has no effect on the undo list or on the buffer's
modification status.

The momentary display remains until the next input event.  If the next
input event is @var{char}, @code{momentary-string-display} ignores it
and returns.  Otherwise, that event remains buffered for subsequent use
as input.  Thus, typing @var{char} will simply remove the string from
the display, while typing (say) @kbd{C-f} will remove the string from
the display and later (presumably) move point forward.  The argument
@var{char} is a space by default.

The return value of @code{momentary-string-display} is not meaningful.

If the string @var{string} does not contain control characters, you can
do the same job in a more general way by creating (and then subsequently
deleting) an overlay with a @code{before-string} property.
@xref{Overlay Properties}.

If @var{message} is non-@code{nil}, it is displayed in the echo area
while @var{string} is displayed in the buffer.  If it is @code{nil}, a
default message says to type @var{char} to continue.

In this example, point is initially located at the beginning of the
second line:

@example
@group
---------- Buffer: foo ----------
This is the contents of foo.
@point{}Second line.
---------- Buffer: foo ----------
@end group

@group
(momentary-string-display
  "**** Important Message! ****"
  (point) ?\r
  "Type RET when done reading")
@result{} t
@end group

@group
---------- Buffer: foo ----------
This is the contents of foo.
**** Important Message! ****Second line.
---------- Buffer: foo ----------

---------- Echo Area ----------
Type RET when done reading
---------- Echo Area ----------
@end group
@end example
@end defun

@node Overlays
@section Overlays
@cindex overlays
Xue Fuqiao's avatar
Xue Fuqiao committed
1390
@c FIXME: mention intervals in this section?
Glenn Morris's avatar
Glenn Morris committed
1391 1392 1393 1394 1395 1396 1397

You can use @dfn{overlays} to alter the appearance of a buffer's text on
the screen, for the sake of presentation features.  An overlay is an
object that belongs to a particular buffer, and has a specified
beginning and end.  It also has properties that you can examine and set;
these affect the display of the text within the overlay.

1398
@cindex scalability of overlays
1399
@cindex overlays, scalability
1400 1401 1402 1403 1404
The visual effect of an overlay is the same as of the corresponding
text property (@pxref{Text Properties}).  However, due to a different
implementation, overlays generally don't scale well (many operations
take a time that is proportional to the number of overlays in the
buffer).  If you need to affect the visual appearance of many portions
1405
in the buffer, we recommend using text properties.
1406

Glenn Morris's avatar
Glenn Morris committed
1407 1408 1409 1410 1411 1412 1413 1414 1415
An overlay uses markers to record its beginning and end; thus,
editing the text of the buffer adjusts the beginning and end of each
overlay so that it stays with the text.  When you create the overlay,
you can specify whether text inserted at the beginning should be
inside the overlay or outside, and likewise for the end of the overlay.

@menu
* Managing Overlays::   Creating and moving overlays.
* Overlay Properties::  How to read and set properties.
Glenn Morris's avatar
Glenn Morris committed
1416
                          What properties do to the screen display.
Glenn Morris's avatar
Glenn Morris committed
1417 1418 1419 1420 1421
* Finding Overlays::    Searching for overlays.
@end menu

@node Managing Overlays
@subsection Managing Overlays
1422 1423
@cindex managing overlays
@cindex overlays, managing
Glenn Morris's avatar
Glenn Morris committed
1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440

  This section describes the functions to create, delete and move
overlays, and to examine their contents.  Overlay changes are not
recorded in the buffer's undo list, since the overlays are not
part of the buffer's contents.

@defun overlayp object
This function returns @code{t} if @var{object} is an overlay.
@end defun

@defun make-overlay start end &optional buffer front-advance rear-advance
This function creates and returns an overlay that belongs to
@var{buffer} and ranges from @var{start} to @var{end}.  Both @var{start}
and @var{end} must specify buffer positions; they may be integers or
markers.  If @var{buffer} is omitted, the overlay is created in the
current buffer.

1441 1442 1443 1444 1445 1446 1447 1448 1449
@cindex empty overlay
@cindex overlay, empty
An overlay whose @var{start} and @var{end} specify the same buffer
position is known as @dfn{empty}.  A non-empty overlay can become
empty if the text between its @var{start} and @var{end} is deleted.
When that happens, the overlay is by default not deleted, but you can
cause it to be deleted by giving it the @samp{evaporate} property
(@pxref{Overlay Properties, evaporate property}).

Glenn Morris's avatar
Glenn Morris committed
1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499
The arguments @var{front-advance} and @var{rear-advance} specify the
marker insertion type for the start of the overlay and for the end of
the overlay, respectively.  @xref{Marker Insertion Types}.  If they
are both @code{nil}, the default, then the overlay extends to include
any text inserted at the beginning, but not text inserted at the end.
If @var{front-advance} is non-@code{nil}, text inserted at the
beginning of the overlay is excluded from the overlay.  If
@var{rear-advance} is non-@code{nil}, text inserted at the end of the
overlay is included in the overlay.
@end defun

@defun overlay-start overlay
This function returns the position at which @var{overlay} starts,
as an integer.
@end defun

@defun overlay-end overlay
This function returns the position at which @var{overlay} ends,
as an integer.
@end defun

@defun overlay-buffer overlay
This function returns the buffer that @var{overlay} belongs to.  It
returns @code{nil} if @var{overlay} has been deleted.
@end defun

@defun delete-overlay overlay
This function deletes @var{overlay}.  The overlay continues to exist as
a Lisp object, and its property list is unchanged, but it ceases to be
attached to the buffer it belonged to, and ceases to have any effect on
display.

A deleted overlay is not permanently disconnected.  You can give it a
position in a buffer again by calling @code{move-overlay}.
@end defun

@defun move-overlay overlay start end &optional buffer
This function moves @var{overlay} to @var{buffer}, and places its bounds
at @var{start} and @var{end}.  Both arguments @var{start} and @var{end}
must specify buffer positions; they may be integers or markers.

If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
was already associated with; if @var{overlay} was deleted, it goes into
the current buffer.

The return value is @var{overlay}.

This is the only valid way to change the endpoints of an overlay.  Do
not try modifying the markers in the overlay by hand, as that fails to
update other vital data structures and can cause some overlays to be
Paul Eggert's avatar
Paul Eggert committed
1500
lost.
Glenn Morris's avatar
Glenn Morris committed
1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512
@end defun

@defun remove-overlays &optional start end name value
This function removes all the overlays between @var{start} and
@var{end} whose property @var{name} has the value @var{value}.  It can
move the endpoints of the overlays in the region, or split them.

If @var{name} is omitted or @code{nil}, it means to delete all overlays in
the specified region.  If @var{start} and/or @var{end} are omitted or
@code{nil}, that means the beginning and end of the buffer respectively.
Therefore, @code{(remove-overlays)} removes all the overlays in the
current buffer.
1513 1514 1515 1516 1517 1518 1519 1520
@end defun

@defun copy-overlay overlay
This function returns a copy of @var{overlay}.  The copy has the same
endpoints and properties as @var{overlay}.  However, the marker
insertion type for the start of the overlay and for the end of the
overlay are set to their default values (@pxref{Marker Insertion
Types}).
Glenn Morris's avatar
Glenn Morris committed
1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576
@end defun

  Here are some examples:

@example
;; @r{Create an overlay.}
(setq foo (make-overlay 1 10))
     @result{} #<overlay from 1 to 10 in display.texi>
(overlay-start foo)
     @result{} 1
(overlay-end foo)
     @result{} 10
(overlay-buffer foo)
     @result{} #<buffer display.texi>
;; @r{Give it a property we can check later.}
(overlay-put foo 'happy t)
     @result{} t
;; @r{Verify the property is present.}
(overlay-get foo 'happy)
     @result{} t
;; @r{Move the overlay.}
(move-overlay foo 5 20)
     @result{} #<overlay from 5 to 20 in display.texi>
(overlay-start foo)
     @result{} 5
(overlay-end foo)
     @result{} 20
;; @r{Delete the overlay.}
(delete-overlay foo)
     @result{} nil
;; @r{Verify it is deleted.}
foo
     @result{} #<overlay in no buffer>
;; @r{A deleted overlay has no position.}
(overlay-start foo)
     @result{} nil
(overlay-end foo)
     @result{} nil
(overlay-buffer foo)
     @result{} nil
;; @r{Undelete the overlay.}
(move-overlay foo 1 20)
     @result{} #<overlay from 1 to 20 in display.texi>
;; @r{Verify the results.}
(overlay-start foo)
     @result{} 1
(overlay-end foo)
     @result{} 20
(overlay-buffer foo)
     @result{} #<buffer display.texi>
;; @r{Moving and deleting the overlay does not change its properties.}
(overlay-get foo 'happy)
     @result{} t
@end example

  Emacs stores the overlays of each buffer in two lists, divided
Paul Eggert's avatar
Paul Eggert committed
1577
around an arbitrary center position.  One list extends backwards
Glenn Morris's avatar
Glenn Morris committed
1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592
through the buffer from that center position, and the other extends
forwards from that center position.  The center position can be anywhere
in the buffer.

@defun overlay-recenter pos
This function recenters the overlays of the current buffer around
position @var{pos}.  That makes overlay lookup faster for positions
near @var{pos}, but slower for positions far away from @var{pos}.
@end defun

  A loop that scans the buffer forwards, creating overlays, can run
faster if you do @code{(overlay-recenter (point-max))} first.

@node Overlay Properties
@subsection Overlay Properties
1593
@cindex overlay properties
Glenn Morris's avatar
Glenn Morris committed
1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607

  Overlay properties are like text properties in that the properties that
alter how a character is displayed can come from either source.  But in
most respects they are different.  @xref{Text Properties}, for comparison.

  Text properties are considered a part of the text; overlays and
their properties are specifically considered not to be part of the
text.  Thus, copying text between various buffers and strings
preserves text properties, but does not try to preserve overlays.
Changing a buffer's text properties marks the buffer as modified,
while moving an overlay or changing its properties does not.  Unlike
text property changes, overlay property changes are not recorded in
the buffer's undo list.

1608 1609
  Since more than one overlay can specify a property value for the
same character, Emacs lets you specify a priority value of each
1610 1611
overlay.  The priority value is used to decide which of the
overlapping overlays will ``win''.
1612