[Emacs-diffs] Changes to emacs/lispref/display.texi [emacs-unicode-2]

[Miles Bader]

Index: emacs/lispref/display.texi
diff -c emacs/lispref/display.texi:1.95.2.8 emacs/lispref/display.texi:1.95.2.9
*** emacs/lispref/display.texi:1.95.2.8 Thu Sep 30 01:20:38 2004
--- emacs/lispref/display.texi  Thu Oct 14 08:49:57 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
  
***************
*** 2655,2663 ****
  @defun fringe-bitmaps-at-pos &optional pos window
  This function returns the fringe bitmaps of the display line
  containing position @var{pos} in window @var{window}.  The return
! value has the form @code{(@var{left} . @var{right})}, where @var{left}
  is the symbol for the fringe bitmap in the left fringe (or @code{nil}
! if no bitmap), and @var{right} is similar for the right fringe.
  
  The value is @code{nil} if @var{pos} is not visible in @var{window}.
  If @var{window} is @code{nil}, that stands for the selected window.
--- 2754,2763 ----
  @defun fringe-bitmaps-at-pos &optional pos window
  This function returns the fringe bitmaps of the display line
  containing position @var{pos} in window @var{window}.  The return
! value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left}
  is the symbol for the fringe bitmap in the left fringe (or @code{nil}
! if no bitmap), @var{right} is similar for the right fringe, and @var{ov}
! is address@hidden if there is an overlay arrow in the left fringe.
  
  The value is @code{nil} if @var{pos} is not visible in @var{window}.
  If @var{window} is @code{nil}, that stands for the selected window.