38.4.2 Reporting Operation Progress

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:

(let ((progress-reporter
       (make-progress-reporter "Collecting mana for Emacs..."
                               0  500)))
  (dotimes (k 500)
    (sit-for 0.01)
    (progress-reporter-update progress-reporter k))
  (progress-reporter-done progress-reporter))

Function: make-progress-reporter message min-value max-value &optional current-value min-change min-time

This function creates and returns a progress reporter—an 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.

When this progress reporter is subsequently used, it will display message in the echo area, followed by progress percentage. message is treated as a simple string. If you need it to depend on a filename, for instance, use format before calling this function.

min-value and 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 point-min and point-max correspondingly. It is required that max-value is greater than min-value. If you create progress reporter when some part of the operation has already been completed, then specify current-value argument. But normally you should omit it or set it to nil—it will default to min-value then.

Remaining arguments control the rate of echo area updates. Progress reporter will wait for at least min-change more percents of the operation to be completed before printing next message. 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 min-change is 1 (one percent), for min-time—0.2 (seconds.)

This function calls progress-reporter-update, so the first message is printed immediately.

Function: progress-reporter-update reporter value

This function does the main work of reporting progress of your operation. It displays the message of reporter, followed by progress percentage determined by value. If percentage is zero, or close enough according to the min-change and min-time arguments, then it is omitted from the output.

reporter must be the result of a call to make-progress-reporter. value specifies the current state of your operation and must be between min-value and max-value (inclusive) as passed to make-progress-reporter. For instance, if you scan a buffer, then value should be the result of a call to point.

This function respects min-change and min-time as passed to 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.

Function: progress-reporter-force-update reporter value &optional new-message

This function is similar to progress-reporter-update except that it prints a message in the echo area unconditionally.

The first two arguments have the same meaning as for progress-reporter-update. Optional new-message allows you to change the message of the reporter. Since this functions always updates the echo area, such a change will be immediately presented to the user.

Function: progress-reporter-done reporter

This function should be called when the operation is finished. It prints the message of reporter followed by word “done” in the echo area.

You should always call this function and not hope for 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.

Macro: dotimes-with-progress-reporter (var count [result]) message body…

This is a convenience macro that works the same way as dotimes does, but also reports loop progress using the functions described above. It allows you to save some typing.

You can rewrite the example in the beginning of this node using this macro this way:

(dotimes-with-progress-reporter (k 500) "Collecting some mana for Emacs..." (sit-for 0.01))

Ce document a été généré par Eric Reinbold le 13 Octobre 2007 en utilisant texi2html 1.78.