[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/lispref/display.texi [lexbind]
From: |
Miles Bader |
Subject: |
[Emacs-diffs] Changes to emacs/lispref/display.texi [lexbind] |
Date: |
Mon, 25 Oct 2004 00:42:26 -0400 |
Index: emacs/lispref/display.texi
diff -c emacs/lispref/display.texi:1.83.2.18
emacs/lispref/display.texi:1.83.2.19
*** emacs/lispref/display.texi:1.83.2.18 Wed Oct 6 05:23:53 2004
--- emacs/lispref/display.texi Mon Oct 25 04:19:38 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.