Function: make-progress-reporter

make-progress-reporter is a byte-compiled function defined in subr.el.gz.

Signature

(make-progress-reporter MESSAGE &optional MIN-VALUE MAX-VALUE CURRENT-VALUE MIN-CHANGE MIN-TIME)

Documentation

Return progress reporter object for use with progress-reporter-update.

MESSAGE is shown in the echo area, with a status indicator appended to the end. When you call progress-reporter-done, the word "done" is printed after the MESSAGE. You can change the MESSAGE of an existing progress reporter by calling progress-reporter-force-update.

MIN-VALUE and MAX-VALUE, if non-nil, are starting (0% complete) and final (100% complete) states of operation; the latter should be larger. In this case, the status message shows the percentage progress.

If MIN-VALUE and/or MAX-VALUE is omitted or nil, the status message shows a "spinning", non-numeric indicator.

Optional CURRENT-VALUE is the initial progress; the default is MIN-VALUE. Optional MIN-CHANGE is the minimal change in percents to report; the default is 1%. CURRENT-VALUE and MIN-CHANGE do not have any effect if MIN-VALUE and/or MAX-VALUE are nil.

Optional MIN-TIME specifies the minimum interval time between
echo area updates (default is 0.2 seconds.) If the OS is not
capable of measuring fractions of seconds, this parameter is effectively rounded up.

View in manual

Probably introduced at or before Emacs version 22.1.

Aliases

progress-reporter-make

Source Code

;; Defined in /usr/src/emacs/lisp/subr.el.gz
(defun make-progress-reporter (message &optional min-value max-value
				       current-value min-change min-time)
  "Return progress reporter object for use with `progress-reporter-update'.

MESSAGE is shown in the echo area, with a status indicator
appended to the end.  When you call `progress-reporter-done', the
word \"done\" is printed after the MESSAGE.  You can change the
MESSAGE of an existing progress reporter by calling
`progress-reporter-force-update'.

MIN-VALUE and MAX-VALUE, if non-nil, are starting (0% complete)
and final (100% complete) states of operation; the latter should
be larger.  In this case, the status message shows the percentage
progress.

If MIN-VALUE and/or MAX-VALUE is omitted or nil, the status
message shows a \"spinning\", non-numeric indicator.

Optional CURRENT-VALUE is the initial progress; the default is
MIN-VALUE.
Optional MIN-CHANGE is the minimal change in percents to report;
the default is 1%.
CURRENT-VALUE and MIN-CHANGE do not have any effect if MIN-VALUE
and/or MAX-VALUE are nil.

Optional MIN-TIME specifies the minimum interval time between
echo area updates (default is 0.2 seconds.)  If the OS is not
capable of measuring fractions of seconds, this parameter is
effectively rounded up."
  (when (string-match "[[:alnum:]]\\'" message)
    (setq message (concat message "...")))
  (unless min-time
    (setq min-time 0.2))
  (let ((reporter
	 (cons (or min-value 0)
	       (vector (if (>= min-time 0.02)
			   (float-time) nil)
		       min-value
		       max-value
		       message
		       (if min-change (max (min min-change 50) 1) 1)
                       min-time
                       ;; SUFFIX
                       nil))))
    ;; Force a call to `message' now.
    (progress-reporter-update reporter (or current-value min-value))
    reporter))