emacs-diffs
[Top][All Lists]
Advanced

[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
  




reply via email to

[Prev in Thread] Current Thread [Next in Thread]