display.texi 186 KB
Newer Older
Richard M. Stallman's avatar
Richard M. Stallman committed
1 2
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
3 4
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
@c   2002, 2005  Free Software Foundation, Inc.
Richard M. Stallman's avatar
Richard M. Stallman committed
5 6
@c See the file elisp.texi for copying conditions.
@setfilename ../info/display
7
@node Display, Calendar, Processes, Top
Richard M. Stallman's avatar
Richard M. Stallman committed
8 9 10 11 12 13 14
@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.
15
* Forcing Redisplay::   Forcing redisplay.
Richard M. Stallman's avatar
Richard M. Stallman committed
16 17
* Truncation::          Folding or wrapping long text lines.
* The Echo Area::       Where messages are displayed.
18
* Warnings::            Displaying warning messages for the user.
Eli Zaretskii's avatar
Eli Zaretskii committed
19
* Progress::            Informing user about progress of a long operation.
Karl Heuer's avatar
Karl Heuer committed
20 21
* Invisible Text::      Hiding part of the buffer text.
* Selective Display::   Hiding part of the buffer text (the old way).
Richard M. Stallman's avatar
Richard M. Stallman committed
22
* Temporary Displays::  Displays that go away automatically.
23
* Overlays::            Use overlays to highlight parts of the buffer.
Phillip Rulon's avatar
Phillip Rulon committed
24
* Width::               How wide a character or string is on the screen.
25
* Line Height::         Controlling the height of lines.
26
* Faces::               A face defines a graphics style for text characters:
Phillip Rulon's avatar
Phillip Rulon committed
27
                          font, colors, etc.
28
* Fringes::             Controlling window fringes.
29
* Scroll Bars::         Controlling vertical scroll bars.
Luc Teirlinck's avatar
Luc Teirlinck committed
30
* Pointer Shape::       Controlling the mouse pointer shape.
31 32
* Display Property::    Enabling special display features.
* Images::              Displaying images in Emacs buffers.
33
* Buttons::             Adding clickable buttons to Emacs buffers.
Richard M. Stallman's avatar
Richard M. Stallman committed
34
* Blinking::            How Emacs shows the matching open parenthesis.
35 36 37
* Inverse Video::       Specifying how the screen looks.
* Usual Display::       The usual conventions for displaying nonprinting chars.
* Display Tables::      How to specify other conventions.
Richard M. Stallman's avatar
Richard M. Stallman committed
38 39 40 41 42 43 44
* Beeping::             Audible signal to the user.
* Window Systems::      Which window system is being used.
@end menu

@node Refresh Screen
@section Refreshing the Screen

45 46 47
  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.
Richard M. Stallman's avatar
Richard M. Stallman committed
48 49 50 51 52 53

@c Emacs 19 feature
@defun redraw-frame frame
This function clears and redisplays frame @var{frame}.
@end defun

54
  Even more powerful is @code{redraw-display}:
Richard M. Stallman's avatar
Richard M. Stallman committed
55 56 57 58 59

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

60 61
  This function calls for redisplay of certain windows, the next time
redisplay is done, but does not clear them first.
62

63
@defun force-window-update &optional object
64 65 66
This function forces redisplay of some or all windows.  If
@var{object} is a window, it forces redisplay of that window.  If
@var{object} is a buffer or buffer name, it forces redisplay of all
67 68
windows displaying that buffer.  If @var{object} is @code{nil} (or
omitted), it forces redisplay of all windows.
69 70
@end defun

Karl Heuer's avatar
Karl Heuer committed
71 72 73 74 75
  Processing user input takes absolute priority over redisplay.  If you
call these functions when input is available, they do nothing
immediately, but a full redisplay does happen eventually---after all the
input has been processed.

Richard M. Stallman's avatar
Richard M. Stallman committed
76 77 78 79
  Normally, suspending and resuming Emacs also 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
Richard M. Stallman's avatar
Richard M. Stallman committed
80
resumption.
Richard M. Stallman's avatar
Richard M. Stallman committed
81 82 83 84 85

@defvar no-redraw-on-reenter
@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
86
has been suspended and resumed.  Non-@code{nil} means there is no need
87
to redraw, @code{nil} means redrawing is needed.  The default is @code{nil}.
Richard M. Stallman's avatar
Richard M. Stallman committed
88 89
@end defvar

90 91 92 93 94 95 96 97 98 99 100 101 102
@node Forcing Redisplay
@section Forcing Redisplay
@cindex forcing redisplay

  Emacs redisplay normally stops if input arrives, and does not happen
at all if input is available before it starts.  Most of the time, this
is exactly what you want.  However, you can prevent preemption by
binding @code{redisplay-dont-pause} to a non-@code{nil} value.

@tindex redisplay-dont-pause
@defvar redisplay-dont-pause
If this variable is non-@code{nil}, pending input does not
prevent or halt redisplay; redisplay occurs, and finishes,
103
regardless of whether input is available.
104 105 106 107 108 109 110 111 112 113 114
@end defvar

  You can request a display update, but only if no input is pending,
with @code{(sit-for 0)}.  To force a display update even when input is
pending, do this:

@example
(let ((redisplay-dont-pause t))
  (sit-for 0))
@end example

Richard M. Stallman's avatar
Richard M. Stallman committed
115 116 117 118 119 120 121 122 123 124 125 126
@node Truncation
@section Truncation
@cindex line wrapping
@cindex continuation lines
@cindex @samp{$} in display
@cindex @samp{\} in display

  When a line of text extends beyond the right edge of a window, the
line can either be continued on the next screen line, or truncated to
one screen line.  The additional screen lines used to display a long
text line are called @dfn{continuation} lines.  Normally, a @samp{$} in
the rightmost column of the window indicates truncation; a @samp{\} on
127 128 129
the rightmost column indicates a line that ``wraps'' onto the next line,
which is also called @dfn{continuing} the line.  (The display table can
specify alternative indicators; see @ref{Display Tables}.)
Richard M. Stallman's avatar
Richard M. Stallman committed
130

131 132
  On a window system display, the @samp{$} and @samp{\} indicators are
replaced with arrow images displayed in the window fringes
133
(@pxref{Fringes}).
134

Richard M. Stallman's avatar
Richard M. Stallman committed
135 136 137 138 139 140 141 142 143 144 145 146 147 148 149
  Note that continuation is different from 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}.

@defopt truncate-lines
This buffer-local variable controls how Emacs displays lines that extend
beyond the right edge of the window.  The default is @code{nil}, which
specifies continuation.  If the value is non-@code{nil}, then these
lines are truncated.

If the variable @code{truncate-partial-width-windows} is non-@code{nil},
then truncation is always used for side-by-side windows (within one
frame) regardless of the value of @code{truncate-lines}.
@end defopt

Karl Heuer's avatar
Karl Heuer committed
150
@defopt default-truncate-lines
Richard M. Stallman's avatar
Richard M. Stallman committed
151
This variable is the default value for @code{truncate-lines}, for
152
buffers that do not have buffer-local values for it.
Karl Heuer's avatar
Karl Heuer committed
153
@end defopt
Richard M. Stallman's avatar
Richard M. Stallman committed
154 155 156 157 158 159 160 161

@defopt truncate-partial-width-windows
This variable controls display of lines that extend beyond the right
edge of the window, in side-by-side windows (@pxref{Splitting Windows}).
If it is non-@code{nil}, these lines are truncated; otherwise,
@code{truncate-lines} says what to do with them.
@end defopt

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

165
  If your buffer contains @emph{very} long lines, and you use
Karl Heuer's avatar
Karl Heuer committed
166
continuation to display them, just thinking about them can make Emacs
Karl Heuer's avatar
Karl Heuer committed
167 168 169
redisplay slow.  The column computation and indentation functions also
become slow.  Then you might find it advisable to set
@code{cache-long-line-scans} to @code{t}.
Karl Heuer's avatar
Karl Heuer committed
170 171 172

@defvar cache-long-line-scans
If this variable is non-@code{nil}, various indentation and motion
Karl Heuer's avatar
Karl Heuer committed
173 174 175
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.
Karl Heuer's avatar
Karl Heuer committed
176

Karl Heuer's avatar
Karl Heuer committed
177
Turning on the cache slows down processing of short lines somewhat.
Karl Heuer's avatar
Karl Heuer committed
178

179
This variable is automatically buffer-local in every buffer.
Karl Heuer's avatar
Karl Heuer committed
180 181
@end defvar

Richard M. Stallman's avatar
Richard M. Stallman committed
182 183 184 185 186
@node The Echo Area
@section The Echo Area
@cindex error display
@cindex echo area

187 188 189 190 191 192 193 194
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
place on the screen as the echo area.  The @cite{GNU Emacs Manual}
specifies the rules for resolving conflicts between the echo area and
the minibuffer for use of that screen space (@pxref{Minibuffer,, The
Minibuffer, emacs, The GNU Emacs Manual}).
Richard M. Stallman's avatar
Richard M. Stallman committed
195 196 197 198 199 200

You can write output in the echo area by using the Lisp printing
functions with @code{t} as the stream (@pxref{Output Functions}), or as
follows:

@defun message string &rest arguments
201
This function displays a message in the echo area.  The
Richard M. Stallman's avatar
Richard M. Stallman committed
202 203 204 205 206
argument @var{string} is similar to a C language @code{printf} control
string.  See @code{format} in @ref{String Conversion}, for the details
on the conversion specifications.  @code{message} returns the
constructed string.

207 208 209
In batch mode, @code{message} prints the message text on the standard
error stream, followed by a newline.

210 211 212
If @var{string}, or strings among the @var{arguments}, have @code{face}
text properties, these affect the way the message is displayed.

Richard M. Stallman's avatar
Richard M. Stallman committed
213
@c Emacs 19 feature
214 215 216 217
If @var{string} is @code{nil}, @code{message} clears the echo area; if
the echo area has been expanded automatically, this brings it back to
its normal size.  If the minibuffer is active, this brings the
minibuffer contents back onto the screen immediately.
218

219
@vindex message-truncate-lines
Richard M. Stallman's avatar
Richard M. Stallman committed
220 221 222 223
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
truncated to fit it, as in Emacs 20 and before.
224

Richard M. Stallman's avatar
Richard M. Stallman committed
225 226 227 228 229 230 231 232 233 234 235 236 237 238
@example
@group
(message "Minibuffer depth is %d."
         (minibuffer-depth))
 @print{} Minibuffer depth is 0.
@result{} "Minibuffer depth is 0."
@end group

@group
---------- Echo Area ----------
Minibuffer depth is 0.
---------- Echo Area ----------
@end group
@end example
239 240

To automatically display a message in the echo area or in a pop-buffer,
241
depending on its size, use @code{display-message-or-buffer} (see below).
Richard M. Stallman's avatar
Richard M. Stallman committed
242 243
@end defun

244 245 246 247 248 249
@defopt max-mini-window-height
This variable specifies the maximum height for resizing minibuffer
windows.  If a float, it specifies a fraction of the height of the
frame.  If an integer, it specifies a number of lines.
@end defopt

250 251 252 253 254 255 256 257
@tindex with-temp-message
@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

258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279
@defun message-or-box 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 string &rest arguments
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

280
@defun display-message-or-buffer message &optional buffer-name not-this-window frame
Dave Love's avatar
Dave Love committed
281
@tindex display-message-or-buffer
282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300
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
pop-up buffer is used, defaulting to @samp{*Message*}.  In the case
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.

The optional arguments @var{not-this-window} and @var{frame} are as for
@code{display-buffer}, and only used if a buffer is displayed.
@end defun

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

306 307 308 309 310 311 312 313 314 315
@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

316 317 318 319 320
@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

Karl Heuer's avatar
Karl Heuer committed
321 322 323 324 325 326 327 328 329 330 331 332 333 334 335
Almost all the messages displayed in the echo area are also recorded
in the @samp{*Messages*} buffer.

@defopt message-log-max
This variable specifies how many lines to keep in the @samp{*Messages*}
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

Karl Heuer's avatar
Karl Heuer committed
336 337
@defvar echo-keystrokes
This variable determines how much time should elapse before command
Dave Love's avatar
Dave Love committed
338 339
characters echo.  Its value must be an integer or floating point number,
which specifies the
Karl Heuer's avatar
Karl Heuer committed
340 341
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
342 343 344
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.)
Karl Heuer's avatar
Karl Heuer committed
345 346 347 348

If the value is zero, then command input is not echoed.
@end defvar

349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396
@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.
@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.)

397
@cindex warning type
398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452
  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
for logging the warning.  By default, it is @samp{*Warnings*}.
@end defun

@defun lwarn type level message &rest args
This function reports a warning using the value of @code{(format
@var{message} @var{args}...)} as the message.  In other respects it is
equivalent to @code{display-warning}.
@end defun

@defun warn message &rest args
This function reports a warning using the value of @code{(format
@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

  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
Richard M. Stallman's avatar
Richard M. Stallman committed
453
If non-@code{nil}, the value is a function to generate prefix text for
454 455 456 457 458 459 460 461
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
Richard M. Stallman's avatar
Richard M. Stallman committed
462
@code{warning-levels}).  By constructing this value, the function can
463 464 465 466 467 468 469 470 471 472 473
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
Richard M. Stallman's avatar
Richard M. Stallman committed
474
than keep moving it for each warning so that it appears on the last one.
475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536
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

@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

  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
537

Eli Zaretskii's avatar
Eli Zaretskii committed
538 539 540 541
@node Progress
@section Reporting Operation Progress
@cindex progress reporting

542
  When an operation can take a while to finish, you should inform the
Eli Zaretskii's avatar
Eli Zaretskii committed
543 544 545
user about the progress it makes.  This way the user can estimate
remaining time and clearly see that Emacs is busy working, not hung.

546
  Functions listed in this section provide simple and efficient way of
Eli Zaretskii's avatar
Eli Zaretskii committed
547 548 549 550 551 552 553 554 555 556 557 558 559 560
reporting operation progress.  Here is a working example that does
nothing useful:

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

@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
561 562 563 564
This function creates and returns a @dfn{progress reporter}---an
object you will use as an argument for all other functions listed
here.  The idea is to precompute as much data as possible to make
progress reporting very fast.
Eli Zaretskii's avatar
Eli Zaretskii committed
565

566 567 568 569 570
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
on a filename, for instance, use @code{format} before calling this
function.
Eli Zaretskii's avatar
Eli Zaretskii committed
571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596

@var{min-value} and @var{max-value} arguments stand for starting and
final states of your operation.  For instance, if you scan a buffer,
they should be the results of @code{point-min} and @code{point-max}
correspondingly.  It is required that @var{max-value} is greater than
@var{min-value}.  If you create progress reporter when some part of
the operation has already been completed, then specify
@var{current-value} argument.  But normally you should omit it or set
it to @code{nil}---it will default to @var{min-value} then.

Remaining arguments control the rate of echo area updates.  Progress
reporter will wait for at least @var{min-change} more percents of the
operation to be completed before printing next message.
@var{min-time} specifies the minimum time in seconds to pass between
successive prints.  It can be fractional.  Depending on Emacs and
system capabilities, progress reporter may or may not respect this
last argument or do it with varying precision.  Default value for
@var{min-change} is 1 (one percent), for @var{min-time}---0.2
(seconds.)

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

@defun progress-reporter-update reporter value
This function does the main work of reporting progress of your
597
operation.  It displays the message of @var{reporter}, followed by
Eli Zaretskii's avatar
Eli Zaretskii committed
598
progress percentage determined by @var{value}.  If percentage is zero,
599 600
or close enough according to the @var{min-change} and @var{min-time}
arguments, then it is omitted from the output.
Eli Zaretskii's avatar
Eli Zaretskii committed
601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637

@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}.

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

@defun progress-reporter-force-update reporter value &optional new-message
This function is similar to @code{progress-reporter-update} except
that it prints a message in the echo area unconditionally.

The first two arguments have the same meaning as for
@code{progress-reporter-update}.  Optional @var{new-message} allows
you to change the message of the @var{reporter}.  Since this functions
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
prints the message of @var{reporter} followed by word ``done'' in the
echo area.

You should always call this function and not hope for
@code{progress-reporter-update} to print ``100%.''  Firstly, it may
never print it, there are many good reasons for this not to happen.
Secondly, ``done'' is more explicit.
@end defun

638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653
@defmac dotimes-with-progress-reporter (var count [result]) message body...
This is a convenience macro that works the same way as @code{dotimes}
does, but also reports loop progress using the functions described
above.  It allows you to save some typing.

You can rewrite the example in the beginning of this node using
this macro this way:

@example
(dotimes-with-progress-reporter
    (k 500)
    "Collecting some mana for Emacs..."
  (sit-for 0.01))
@end example
@end defmac

Karl Heuer's avatar
Karl Heuer committed
654 655 656 657 658 659
@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
660
text property (@pxref{Text Properties}) or a property of an overlay
661 662 663
(@pxref{Overlays}).  Cursor motion also partly ignores these
characters; if the command loop finds point within them, it moves
point to the other side of them.
Karl Heuer's avatar
Karl Heuer committed
664 665 666 667

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
668 669 670
@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.
Karl Heuer's avatar
Karl Heuer committed
671 672 673 674 675 676 677 678 679

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
Phillip Rulon's avatar
Phillip Rulon committed
680 681 682 683 684
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.
Karl Heuer's avatar
Karl Heuer committed
685 686 687

@defvar buffer-invisibility-spec
This variable specifies which kinds of @code{invisible} properties
688 689
actually make a character invisible.  Setting this variable makes it
buffer-local.
Karl Heuer's avatar
Karl Heuer committed
690 691 692 693 694 695 696

@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
697 698 699
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:
Karl Heuer's avatar
Karl Heuer committed
700 701 702

@table @code
@item @var{atom}
703
A character is invisible if its @code{invisible} property value
Karl Heuer's avatar
Karl Heuer committed
704 705 706
is @var{atom} or if it is a list with @var{atom} as a member.

@item (@var{atom} . t)
707
A character is invisible if its @code{invisible} property value
Karl Heuer's avatar
Karl Heuer committed
708 709 710 711 712 713 714
is @var{atom} or if it is a list with @var{atom} as a member.
Moreover, if this character is at the end of a line and is followed
by a visible newline, it displays an ellipsis.
@end table
@end table
@end defvar

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

@defun add-to-invisibility-spec element
719 720 721 722 723
This function adds the element @var{element} to
@code{buffer-invisibility-spec} (if it is not already present in that
list).  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.
724 725 726
@end defun

@defun remove-from-invisibility-spec element
Richard M. Stallman's avatar
Richard M. Stallman committed
727
This removes the element @var{element} from
728 729
@code{buffer-invisibility-spec}.  This does nothing if @var{element}
is not in the list.
730 731
@end defun

732 733 734 735
  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:
736 737

@example
738
;; @r{If you want to display an ellipsis:}
739
(add-to-invisibility-spec '(my-symbol . t))
740
;; @r{If you don't want ellipsis:}
741
(add-to-invisibility-spec 'my-symbol)
742 743 744 745

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

746
;; @r{When done with the overlays:}
747
(remove-from-invisibility-spec '(my-symbol . t))
748
;; @r{Or respectively:}
749 750 751
(remove-from-invisibility-spec 'my-symbol)
@end example

752
@vindex line-move-ignore-invisible
753
  Ordinarily, functions that operate on text or move point do not care
754 755 756 757
whether the text is invisible.  The user-level line motion commands
explicitly ignore invisible newlines if
@code{line-move-ignore-invisible} is non-@code{nil}, but only because
they are explicitly programmed to do so.
Karl Heuer's avatar
Karl Heuer committed
758

759 760 761 762 763 764 765 766 767 768
  However, if a command ends with point inside or immediately after
invisible text, the main editing loop moves point further forward or
further backward (in the same direction that the command already moved
it) until that condition is no longer true.  Thus, if the command
moved point back into an invisible range, Emacs moves point back to
the beginning of that range, following the previous visible character.
If the command moved point forward into an invisible range, Emacs
moves point forward past the first visible character that follows the
invisible text.

769 770 771 772 773 774 775 776 777 778
  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
779
want this to be done differently for a certain overlay, give it an
780 781
@code{isearch-open-invisible-temporary} property which is a function.
The function is called with two arguments: the first is the overlay, and
Gerd Moellmann's avatar
Gerd Moellmann committed
782
the second is @code{nil} to make the overlay visible, or @code{t} to
783
make it invisible again.
784

Richard M. Stallman's avatar
Richard M. Stallman committed
785 786 787 788
@node Selective Display
@section Selective Display
@cindex selective display

789 790
  @dfn{Selective display} refers to a pair of related features for
hiding certain lines on the screen.
Richard M. Stallman's avatar
Richard M. Stallman committed
791

792 793 794 795 796
  The first variant, explicit selective display, is designed for use
in a Lisp program: it controls which lines are hidden by altering the
text.  This kind of hiding in some ways resembles the effect of the
@code{invisible} property (@pxref{Invisible Text}), but the two
features are different and do not work the same way.
Karl Heuer's avatar
Karl Heuer committed
797 798

  In the second variant, the choice of lines to hide is made
Karl Heuer's avatar
Karl Heuer committed
799
automatically based on indentation.  This variant is designed to be a
Karl Heuer's avatar
Karl Heuer committed
800
user-level feature.
Richard M. Stallman's avatar
Richard M. Stallman committed
801 802

  The way you control explicit selective display is by replacing a
Richard M. Stallman's avatar
Richard M. Stallman committed
803
newline (control-j) with a carriage return (control-m).  The text that
804 805 806
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.
Richard M. Stallman's avatar
Richard M. Stallman committed
807 808

  Selective display does not directly affect editing commands.  For
809 810 811 812 813 814 815
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.
Richard M. Stallman's avatar
Richard M. Stallman committed
816 817 818

  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
819
in the file, it looks OK, with nothing hidden.  The selective display
Richard M. Stallman's avatar
Richard M. Stallman committed
820 821 822 823
effect is seen only within Emacs.

@defvar selective-display
This buffer-local variable enables selective display.  This means that
824
lines, or portions of lines, may be made hidden.
Richard M. Stallman's avatar
Richard M. Stallman committed
825 826 827

@itemize @bullet
@item
Phillip Rulon's avatar
Phillip Rulon committed
828
If the value of @code{selective-display} is @code{t}, then the character
829
control-m marks the start of hidden text; the control-m, and the rest
Phillip Rulon's avatar
Phillip Rulon committed
830 831
of the line following it, are not displayed.  This is explicit selective
display.
Richard M. Stallman's avatar
Richard M. Stallman committed
832 833 834 835 836 837 838

@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

839
When some portion of a buffer is hidden, the vertical movement
Richard M. Stallman's avatar
Richard M. Stallman committed
840
commands operate as if that portion did not exist, allowing a single
841
@code{next-line} command to skip any number of hidden lines.
Richard M. Stallman's avatar
Richard M. Stallman committed
842
However, character movement commands (such as @code{forward-char}) do
843 844
not skip the hidden portion, and it is possible (if tricky) to insert
or delete text in an hidden portion.
Richard M. Stallman's avatar
Richard M. Stallman committed
845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881

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

@defvar selective-display-ellipses
If this buffer-local variable is non-@code{nil}, then Emacs displays
882
@samp{@dots{}} at the end of a line that is followed by hidden text.
Richard M. Stallman's avatar
Richard M. Stallman committed
883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905
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}.
@end defvar

@node Temporary Displays
@section Temporary Displays

906 907 908
  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.
Richard M. Stallman's avatar
Richard M. Stallman committed
909 910

@defspec with-output-to-temp-buffer buffer-name forms@dots{}
911 912 913 914 915
This function executes @var{forms} 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.  Finally, the buffer is
displayed in some window, but not selected.

916 917
If the @var{forms} do not change the major mode in the output buffer,
so that it is still Help mode at the end of their execution, then
918
@code{with-output-to-temp-buffer} makes this buffer read-only at the
919
end, and also scans it for function and variable names to make them
Luc Teirlinck's avatar
Luc Teirlinck committed
920 921 922
into clickable cross-references.  @xref{Docstring hyperlinks, , Tips
for Documentation Strings}, in particular the item on hyperlinks in
documentation strings, for more details.
Richard M. Stallman's avatar
Richard M. Stallman committed
923 924 925 926 927 928 929 930 931 932 933 934 935

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.

@code{with-output-to-temp-buffer} binds @code{standard-output} to the
temporary buffer, then it evaluates the forms in @var{forms}.  Output
using the Lisp output functions within @var{forms} goes by default to
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}.

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

Richard M. Stallman's avatar
Richard M. Stallman committed
939 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
The value of the last form in @var{forms} is returned.

@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 ----------
20

#<buffer foo>

---------- Buffer: foo ----------
@end group
@end example
@end defspec

@defvar temp-buffer-show-function
Richard M. Stallman's avatar
Richard M. Stallman committed
965
If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
Richard M. Stallman's avatar
Richard M. Stallman committed
966 967
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.
968 969 970

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
971
@code{save-selected-window} and with the chosen window and buffer
972 973 974
selected.
@end defvar

975 976 977
@defvar temp-buffer-setup-hook
@tindex temp-buffer-setup-hook
This normal hook is run by @code{with-output-to-temp-buffer} before
Richard M. Stallman's avatar
Richard M. Stallman committed
978 979 980
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.
981 982
@end defvar

983 984
@defvar temp-buffer-show-hook
This normal hook is run by @code{with-output-to-temp-buffer} after
Richard M. Stallman's avatar
Richard M. Stallman committed
985 986 987 988 989
displaying the temporary buffer.  When the hook runs, the temporary buffer
is current, and the window it was displayed in is selected.  This hook
is normally set up with a function to make the buffer read only, and
find function names and variable names in it, provided the major mode
is Help mode.
Richard M. Stallman's avatar
Richard M. Stallman committed
990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006
@end defvar

@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.

Karl Heuer's avatar
Karl Heuer committed
1007
If the string @var{string} does not contain control characters, you can
1008 1009 1010
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}.
Karl Heuer's avatar
Karl Heuer committed
1011

Richard M. Stallman's avatar
Richard M. Stallman committed
1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052
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

You can use @dfn{overlays} to alter the appearance of a buffer's text on
Karl Heuer's avatar
Karl Heuer committed
1053 1054 1055 1056
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.
Richard M. Stallman's avatar
Richard M. Stallman committed
1057

Richard M. Stallman's avatar
Richard M. Stallman committed
1058 1059 1060 1061 1062 1063
An overlays 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.

Richard M. Stallman's avatar
Richard M. Stallman committed
1064
@menu
1065
* Managing Overlays::   Creating and moving overlays.
1066
* Overlay Properties::  How to read and set properties.
Richard M. Stallman's avatar
Richard M. Stallman committed
1067
			What properties do to the screen display.
1068
* Finding Overlays::    Searching for overlays.
Richard M. Stallman's avatar
Richard M. Stallman committed
1069 1070
@end menu

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 1103 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 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193
@node Managing Overlays
@subsection Managing Overlays

  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.

The arguments @var{front-advance} and @var{rear-advance} specify the
insertion type for the start of the overlay and for the end of the
overlay, respectively.  @xref{Marker Insertion Types}.  If
@var{front-advance} is non-@code{nil}, text inserted at the beginning
of the overlay is excluded from the overlay.  If @var{read-advance} is
non-@code{nil}, text inserted at the beginning 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
``lost''.
@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

Richard M. Stallman's avatar
Richard M. Stallman committed
1194 1195 1196
@node Overlay Properties
@subsection Overlay Properties

1197
  Overlay properties are like text properties in that the properties that
1198
alter how a character is displayed can come from either source.  But in
1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210
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.

  These functions read and set the properties of an overlay:
1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222

@defun overlay-get overlay prop
This function returns the value of property @var{prop} recorded in
@var{overlay}, if any.  If @var{overlay} does not record any value for
that property, but it does have a @code{category} property which is a
symbol, that symbol's @var{prop} property is used.  Otherwise, the value
is @code{nil}.
@end defun

@defun overlay-put overlay prop value
This function sets the value of property @var{prop} recorded in
@var{overlay} to @var{value}.