comparison lispref/display.texi @ 57389:218fcd9a7703

(Progress): New node.

57388:97ac56ad8d32

* Refresh Screen::      Clearing the screen and redrawing everything on it.
* Forcing Redisplay::   Forcing redisplay.
* Truncation::          Folding or wrapping long text lines.
* The Echo Area::       Where messages are displayed.
* 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).
* Overlay Arrow::       Display of an arrow to indicate position.
* Temporary Displays::  Displays that go away automatically.
* Overlays::            Use overlays to highlight parts of the buffer.

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

@node Invisible Text
@section Invisible Text

@cindex invisible text

57389:218fcd9a7703

* Refresh Screen::      Clearing the screen and redrawing everything on it.
* Forcing Redisplay::   Forcing redisplay.
* Truncation::          Folding or wrapping long text lines.
* The Echo Area::       Where messages are displayed.
* Warnings::            Displaying warning messages for the user.
* Progress::            Informing user about progress of a long operation.
* Invisible Text::      Hiding part of the buffer text.
* Selective Display::   Hiding part of the buffer text (the old way).
* Overlay Arrow::       Display of an arrow to indicate position.
* Temporary Displays::  Displays that go away automatically.
* Overlays::            Use overlays to highlight parts of the buffer.

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

@node Progress
@section 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.

Functions listed in this section provide simple and efficient way of
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
This function creates a progress reporter---the 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.

The @var{message} will be displayed 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.

@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
operation.  It print the message of @var{reporter} followed by
progress percentage determined by @var{value}.  If percentage is zero,
then it is not printed at all.

@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

@node Invisible Text
@section Invisible Text

@cindex invisible text