diff options
Diffstat (limited to 'devdocs/elisp/progress.html')
| -rw-r--r-- | devdocs/elisp/progress.html | 51 |
1 files changed, 51 insertions, 0 deletions
diff --git a/devdocs/elisp/progress.html b/devdocs/elisp/progress.html new file mode 100644 index 00000000..7853d0f5 --- /dev/null +++ b/devdocs/elisp/progress.html @@ -0,0 +1,51 @@ + <h4 class="subsection">Reporting Operation Progress</h4> <p>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. A convenient way to do this is to use a <em>progress reporter</em>. </p> <p>Here is a working example that does nothing useful: </p> <div class="example"> <pre class="example">(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)) +</pre> +</div> <dl> <dt id="make-progress-reporter">Function: <strong>make-progress-reporter</strong> <em>message &optional min-value max-value current-value min-change min-time</em> +</dt> <dd> +<p>This function creates and returns a progress reporter object, which you will use as an argument for the other functions listed below. The idea is to precompute as much data as possible to make progress reporting very fast. </p> <p>When this progress reporter is subsequently used, it will display <var>message</var> in the echo area, followed by progress percentage. <var>message</var> is treated as a simple string. If you need it to depend on a filename, for instance, use <code>format-message</code> before calling this function. </p> <p>The arguments <var>min-value</var> and <var>max-value</var> should be numbers standing for the starting and final states of the operation. For instance, an operation that scans a buffer should set these to the results of <code>point-min</code> and <code>point-max</code> correspondingly. <var>max-value</var> should be greater than <var>min-value</var>. </p> <p>Alternatively, you can set <var>min-value</var> and <var>max-value</var> to <code>nil</code>. In that case, the progress reporter does not report process percentages; it instead displays a “spinner” that rotates a notch each time you update the progress reporter. </p> <p>If <var>min-value</var> and <var>max-value</var> are numbers, you can give the argument <var>current-value</var> a numerical value specifying the initial progress; if omitted, this defaults to <var>min-value</var>. </p> <p>The remaining arguments control the rate of echo area updates. The progress reporter will wait for at least <var>min-change</var> more percents of the operation to be completed before printing next message; the default is one percent. <var>min-time</var> specifies the minimum time in seconds to pass between successive prints; the default is 0.2 seconds. (On some operating systems, the progress reporter may handle fractions of seconds with varying precision). </p> <p>This function calls <code>progress-reporter-update</code>, so the first message is printed immediately. </p> +</dd> +</dl> <dl> <dt id="progress-reporter-update">Function: <strong>progress-reporter-update</strong> <em>reporter &optional value suffix</em> +</dt> <dd> +<p>This function does the main work of reporting progress of your operation. It displays the message of <var>reporter</var>, followed by progress percentage determined by <var>value</var>. If percentage is zero, or close enough according to the <var>min-change</var> and <var>min-time</var> arguments, then it is omitted from the output. </p> <p><var>reporter</var> must be the result of a call to <code>make-progress-reporter</code>. <var>value</var> specifies the current state of your operation and must be between <var>min-value</var> and <var>max-value</var> (inclusive) as passed to <code>make-progress-reporter</code>. For instance, if you scan a buffer, then <var>value</var> should be the result of a call to <code>point</code>. </p> <p>Optional argument <var>suffix</var> is a string to be displayed after <var>reporter</var>’s main message and progress text. If <var>reporter</var> is a non-numerical reporter, then <var>value</var> should be <code>nil</code>, or a string to use instead of <var>suffix</var>. </p> <p>This function respects <var>min-change</var> and <var>min-time</var> as passed to <code>make-progress-reporter</code> 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. </p> +</dd> +</dl> <dl> <dt id="progress-reporter-force-update">Function: <strong>progress-reporter-force-update</strong> <em>reporter &optional value new-message suffix</em> +</dt> <dd> +<p>This function is similar to <code>progress-reporter-update</code> except that it prints a message in the echo area unconditionally. </p> <p><var>reporter</var>, <var>value</var>, and <var>suffix</var> have the same meaning as for <code>progress-reporter-update</code>. Optional <var>new-message</var> allows you to change the message of the <var>reporter</var>. Since this function always updates the echo area, such a change will be immediately presented to the user. </p> +</dd> +</dl> <dl> <dt id="progress-reporter-done">Function: <strong>progress-reporter-done</strong> <em>reporter</em> +</dt> <dd> +<p>This function should be called when the operation is finished. It prints the message of <var>reporter</var> followed by word ‘<samp>done</samp>’ in the echo area. </p> <p>You should always call this function and not hope for <code>progress-reporter-update</code> to print ‘<samp>100%</samp>’. Firstly, it may never print it, there are many good reasons for this not to happen. Secondly, ‘<samp>done</samp>’ is more explicit. </p> +</dd> +</dl> <dl> <dt id="dotimes-with-progress-reporter">Macro: <strong>dotimes-with-progress-reporter</strong> <em>(var count [result]) reporter-or-message body…</em> +</dt> <dd> +<p>This is a convenience macro that works the same way as <code>dotimes</code> does, but also reports loop progress using the functions described above. It allows you to save some typing. The argument <var>reporter-or-message</var> can be either a string or a progress reporter object. </p> <p>You can rewrite the example in the beginning of this subsection using this macro as follows: </p> <div class="example"> <pre class="example">(dotimes-with-progress-reporter + (k 500) + "Collecting some mana for Emacs..." + (sit-for 0.01)) +</pre> +</div> <p>Using a reporter object as the <var>reporter-or-message</var> argument is useful if you want to specify the optional arguments in <var>make-progress-reporter</var>. For instance, you can write the previous example as follows: </p> <div class="example"> <pre class="example">(dotimes-with-progress-reporter + (k 500) + (make-progress-reporter "Collecting some mana for Emacs..." 0 500 0 1 1.5) + (sit-for 0.01)) +</pre> +</div> </dd> +</dl> <dl> <dt id="dolist-with-progress-reporter">Macro: <strong>dolist-with-progress-reporter</strong> <em>(var count [result]) reporter-or-message body…</em> +</dt> <dd> +<p>This is another convenience macro that works the same way as <code>dolist</code> does, but also reports loop progress using the functions described above. As in <code>dotimes-with-progress-reporter</code>, <code>reporter-or-message</code> can be a progress reporter or a string. You can rewrite the previous example with this macro as follows: </p> <div class="example"> <pre class="example">(dolist-with-progress-reporter + (k (number-sequence 0 500)) + "Collecting some mana for Emacs..." + (sit-for 0.01)) +</pre> +</div> </dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Progress.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Progress.html</a> + </p> +</div> |