emacs-31 b6849229003: Restore progress-reporter suffix as update-text (bug#81134)
Sean Whitton <[email protected]>
| Newsgroups | gmane.emacs.diffs |
|---|---|
| Message-ID | <[email protected]> |
branch: emacs-31 commit b6849229003f214570acedfa7e2755051c0e4305 Author: Stéphane Marks <[email protected]> Commit: Sean Whitton <[email protected]> Restore progress-reporter suffix as update-text (bug#81134) * lisp/subr.el (progress-reporter-update-functions): Update docstring. (progress-reporter-update): New UPDATE-TEXT argument replacing previously deleted SUFFIX. (make-progress-reporter): Document suffix slot available for reuse. (progress-reporter-force-update): Update function signature. (progress-reporter-echo-area): Restore the text argument and echo it. (progress-reporter-do-update): Update function signature. Treat UPDATE-TEXT as ephemeral and do not persist it in the reporter instance. Update the hook. (progress-reporter-done): Update the hook. * lisp/system-taskbar.el (system-taskbar--progress-reporter-update): Update function signature. * lisp/net/tramp.el (tramp-progress-reporter-update): Update function signature. * doc/lispref/display.texi (Progress): Update documentation. --- doc/lispref/display.texi | 15 ++++++------ lisp/net/tramp.el | 4 +-- lisp/subr.el | 63 +++++++++++++++++++++++++----------------------- lisp/system-taskbar.el | 4 +-- 4 files changed, 45 insertions(+), 41 deletions(-) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 49b09f6583d..e1b46d51489 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -531,7 +531,7 @@ This function calls @code{progress-reporter-update}, so the first message is printed immediately. @end defun -@defun progress-reporter-update reporter &optional value suffix +@defun progress-reporter-update reporter &optional value update-text This function does the main work of reporting progress of your operation. It displays the message of @var{reporter}, followed by progress percentage determined by @var{value}. If percentage is zero, @@ -545,10 +545,11 @@ state of your operation and must be between @var{min-value} and @code{make-progress-reporter}. For instance, if you scan a buffer, then @var{value} should be the result of a call to @code{point}. -Optional argument @var{suffix} is a string to be displayed after -@var{reporter}'s main message and progress text. If @var{reporter} is -a non-numerical reporter, then @var{value} should be @code{nil}, or a -string to use instead of @var{suffix}. +Optional argument @var{update-text} is a string to be displayed after +@var{reporter}'s main message and progress text. One typical use is as +the ``step'' of a long-running process so the user knows where it is. +If @var{reporter} is a non-numerical reporter, then @var{value} should +be @code{nil}, or a string to use instead of @var{update-text}. This function respects @var{min-change} and @var{min-time} as passed to @code{make-progress-reporter} and so does not output new messages @@ -557,11 +558,11 @@ 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 &optional value new-message suffix +@defun progress-reporter-force-update reporter &optional value new-message update-text This function is similar to @code{progress-reporter-update} except that it prints a message in the echo area unconditionally. -@var{reporter}, @var{value}, and @var{suffix} have the same meaning as for +@var{reporter}, @var{value}, and @var{update-text} 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 function always updates the echo area, such a change will be immediately diff --git a/lisp/net/tramp.el b/lisp/net/tramp.el index 1a10b8042a5..c5ecbdd9675 100644 --- a/lisp/net/tramp.el +++ b/lisp/net/tramp.el @@ -2215,12 +2215,12 @@ If VAR is nil, then we bind `v' to the structure and `method', `user', (ignore ,@(mapcar #'car bindings)) ,@body))) -(defun tramp-progress-reporter-update (reporter &optional value suffix) +(defun tramp-progress-reporter-update (reporter &optional value update-text) "Report progress of an operation for Tramp." (let* ((parameters (cdr reporter)) (message (aref parameters 3))) (when (string-search message (or (current-message) "")) - (progress-reporter-update reporter value suffix)))) + (progress-reporter-update reporter value update-text)))) ;;;###tramp-autoload (defvar tramp-inhibit-progress-reporter nil diff --git a/lisp/subr.el b/lisp/subr.el index 16234d313a7..58f388c146d 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -7097,7 +7097,8 @@ to deactivate this transient map, regardless of KEEP-PRED." ;; MESSAGE ;; MIN-CHANGE ;; MIN-TIME -;; MESSAGE-SUFFIX]) +;; UNUSED (formerly SUFFIX) +;; CONTEXT]) ;; ;; This weirdness is for optimization reasons: we want ;; `progress-reporter-update' to be as fast as possible, so @@ -7109,15 +7110,18 @@ to deactivate this transient map, regardless of KEEP-PRED." (defvar progress-reporter-update-functions (list #'progress-reporter-echo-area) "Special hook run on progress-reporter updates. -Each function is called with two arguments: +Each function is called with three arguments: REPORTER is the result of a call to `make-progress-reporter'. STATE can be one of: - A float representing the percentage complete in the range 0.0-1.0 for a numeric reporter. - A monotonically increasing integer for a pulsing reporter. -- The symbol `done' to indicate that the progress reporter is complete.") +- The symbol `done' to indicate that the progress reporter is complete. +UPDATE-TEXT is a string that a progress-reporter back-end might display +as a result of this update. A typical use is as the \"step\" of the +progress reporting process.") -(defsubst progress-reporter-update (reporter &optional value suffix) +(defsubst progress-reporter-update (reporter &optional value update-text) "Report progress of an operation, by default, in the echo area. REPORTER should be the result of a call to `make-progress-reporter'. @@ -7126,10 +7130,11 @@ made using non-nil MIN-VALUE and MAX-VALUE arguments to `make-progress-reporter'---then VALUE should be a number between MIN-VALUE and MAX-VALUE. -Optional argument SUFFIX is a string to be displayed after REPORTER's -main message and progress text. If REPORTER is a non-numerical -reporter, then VALUE should be nil, or a string to use instead of -SUFFIX. +Optional argument UPDATE-TEXT is a string that a progress-reporter +back-end might display as a result of this update. A typical use is as +the \"step\" of the progress reporting process. If REPORTER is a +non-numerical reporter, then VALUE should be nil, or a string to use +instead of UPDATE-TEXT. See `progress-reporter-update-functions' for the list of functions called on each update. @@ -7139,7 +7144,7 @@ last update is too small or insufficient time has passed, it does nothing." (when (or (not (numberp value)) ; For pulsing reporter (>= value (car reporter))) ; For numerical reporter - (progress-reporter-do-update reporter value suffix))) + (progress-reporter-do-update reporter value update-text))) (defun make-progress-reporter (message &optional min-value max-value current-value min-change min-time @@ -7189,7 +7194,7 @@ the echo area progress reports may be muted if the echo area is busy." message (if min-change (max (min min-change 50) 1) 1) min-time - ;; SUFFIX + ;; Unused (formerly SUFFIX). nil ;; context)))) @@ -7207,24 +7212,26 @@ the echo area progress reports may be muted if the echo area is busy." "Return REPORTER's context." (aref (cdr reporter) 7)) -(defun progress-reporter-force-update (reporter &optional value new-message suffix) +(defun progress-reporter-force-update (reporter &optional + value new-message update-text) "Report progress of an operation in the echo area unconditionally. -REPORTER, VALUE, and SUFFIX are the same as in `progress-reporter-update'. +REPORTER, VALUE, and UPDATE-TEXT are the same as in +`progress-reporter-update'. NEW-MESSAGE, if non-nil, sets a new message for the reporter." (let ((parameters (cdr reporter))) (when new-message (aset parameters 3 new-message)) (when (aref parameters 0) (aset parameters 0 (float-time))) - (progress-reporter-do-update reporter value suffix))) + (progress-reporter-do-update reporter value update-text))) (defvar progress-reporter--pulse-characters ["-" "\\" "|" "/"] "Characters to use for pulsing progress reporters.") -(defun progress-reporter-echo-area (reporter state) +(defun progress-reporter-echo-area (reporter state update-text) "Progress reporter echo area update function. -REPORTER and STATE are the same as in +REPORTER, STATE, and UPDATE-TEXT are the same as in `progress-reporter-update-functions'. Do not emit a message if the reporter context is `async' and the echo @@ -7233,21 +7240,22 @@ area is busy with something else." (unless (and (eq (progress-reporter-context reporter) 'async) (current-message) (not (string-prefix-p text (current-message)))) + (setq update-text (concat (if update-text " " "") update-text)) (pcase state ((pred floatp) (if (plusp state) - (message "%s%d%%" text (* state 100.0)) - (message "%s" text))) + (message "%s%d%%%s" text (* state 100.0) update-text) + (message "%s%s" text update-text))) ((pred integerp) (let ((message-log-max nil) (pulse-char (aref progress-reporter--pulse-characters (mod state (length progress-reporter--pulse-characters))))) - (message "%s %s" text pulse-char))) + (message "%s %s%s" text pulse-char update-text))) ('done (message "%sdone" text)))))) -(defun progress-reporter-do-update (reporter value &optional suffix) +(defun progress-reporter-do-update (reporter value &optional update-text) (let* ((parameters (cdr reporter)) (update-time (aref parameters 0)) (min-value (aref parameters 1)) @@ -7281,31 +7289,26 @@ area is busy with something else." (setcar reporter (ceiling (car reporter)))) ;; Print message only if enough time has passed (when enough-time-passed - (if suffix - (aset parameters 6 suffix) - (setq suffix (or (aref parameters 6) ""))) (run-hook-with-args 'progress-reporter-update-functions reporter - (/ percentage 100.0))))) + (/ percentage 100.0) + update-text)))) ;; Pulsing indicator (enough-time-passed - (when (and value (not suffix)) - (setq suffix value)) - (if suffix - (aset parameters 6 suffix) - (setq suffix (or (aref parameters 6) ""))) (let ((index (1+ (car reporter)))) (setcar reporter index) (run-hook-with-args 'progress-reporter-update-functions reporter - index)))))) + index + (or update-text value))))))) (defun progress-reporter-done (reporter) "Print reporter's message followed by word \"done\" in echo area. Call the functions on `progress-reporter-update-functions`." (run-hook-with-args 'progress-reporter-update-functions reporter - 'done)) + 'done + nil)) (defmacro dotimes-with-progress-reporter (spec reporter-or-message &rest body) "Loop a certain number of times and report progress in the echo area. diff --git a/lisp/system-taskbar.el b/lisp/system-taskbar.el index 973b426e026..d1fe276844d 100644 --- a/lisp/system-taskbar.el +++ b/lisp/system-taskbar.el @@ -273,9 +273,9 @@ If PROGRESS is nil, remove the progress indicator.") ;; `progress-reporter' support. -(defun system-taskbar--progress-reporter-update (_reporter state) +(defun system-taskbar--progress-reporter-update (_reporter state _update-text) "Progress reporter system taskbar update function. -REPORTER and STATE are the same as in +REPORTER, STATE, and UPDATE-TEXT are the same as in `progress-reporter-update-functions'." (when system-taskbar-mode (pcase state