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 CONTEXT)

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.

Optional CONTEXT can be nil or async. It is consulted by back ends before showing progress updates. For example, when CONTEXT is async, the echo area progress reports may be muted if the echo area is busy.

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
                                       context)
  "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.

Optional CONTEXT can be nil or `async'.  It is consulted by back ends before
showing progress updates.  For example, when CONTEXT is `async',
the echo area progress reports may be muted if the echo area is busy."
  (when (string-match "[[:alnum:]]\\'" message)
    (setq message (concat message "...")))
  (unless min-time
    (setq min-time 0.2))
  (let ((reporter
	 (cons (or min-value 0)
	       ;; FIXME: Use defstruct.
	       (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
                       ;; Unused (formerly SUFFIX).
                       nil
                       ;;
                       context))))
    ;; Force a call to `message' now.
    (progress-reporter-update reporter (or current-value min-value))
    reporter))