[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/lispref/display.texi
From: |
Eli Zaretskii |
Subject: |
[Emacs-diffs] Changes to emacs/lispref/display.texi |
Date: |
Fri, 08 Oct 2004 13:46:41 -0400 |
Index: emacs/lispref/display.texi
diff -c emacs/lispref/display.texi:1.131 emacs/lispref/display.texi:1.132
*** emacs/lispref/display.texi:1.131 Tue Oct 5 08:55:12 2004
--- emacs/lispref/display.texi Fri Oct 8 17:35:47 2004
***************
*** 16,21 ****
--- 16,22 ----
* 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.
***************
*** 533,538 ****
--- 534,637 ----
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