procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of 'minibuffer-message'

Browse source 
* doc/lispref/minibuf.texi (Minibuffer Misc): Clarify that
'minibuffer-message' behaves like 'message' if called from a
buffer that is not a minibuffer.

* lisp/minibuffer.el (minibuffer-message)
(set-minibuffer-message, clear-minibuffer-message): Doc fixes.
(Bug#64165)
This commit is contained in:
Eli Zaretskii 2023-06-20 15:31:57 +03:00
parent 6f211bc57b
commit 2591eb1190
2 changed files with 34 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
doc/lispref/minibuf.texi
View file

@ -2805,13 +2805,23 @@ minibuffer window, it returns @code{nil}.
@vindex minibuffer-message-timeout
@defun minibuffer-message string &rest args
This function displays @var{string} temporarily at the end of the
minibuffer text, for a few seconds, or until the next input event
arrives, whichever comes first. The variable
@code{minibuffer-message-timeout} specifies the number of seconds to
wait in the absence of input. It defaults to 2. If @var{args} is
non-@code{nil}, the actual message is obtained by passing @var{string}
and @var{args} through @code{format-message}. @xref{Formatting Strings}.
This function is like @code{message} (@pxref{Displaying Messages}),
but it displays the messages specially when the user types in the
minibuffer, typically because Emacs prompted the user for some input.
When the minibuffer is the current buffer, this function displays the
message specified by @var{string} temporarily at the end of the
minibuffer text, and thus avoids hiding the minibuffer text by the
echo-area display of the message. It leaves the message on display
for a few seconds, or until the next input event arrives, whichever
comes first. The variable @code{minibuffer-message-timeout} specifies
the number of seconds to wait in the absence of input. It defaults to
2. If @var{args} is non-@code{nil}, the actual message is obtained by
passing @var{string} and @var{args} through @code{format-message}.
@xref{Formatting Strings}.
If called when the minibuffer is not the current buffer, this function
just calls @code{message}, and thus @var{string} will be shown in the
echo-area.
@end defun
@deffn Command minibuffer-inactive-mode

24
lisp/minibuffer.el
View file

@ -715,11 +715,21 @@ for use at QPOS."
"Text properties added to the text shown by `minibuffer-message'.")
(defun minibuffer-message (message &rest args)
"Temporarily display MESSAGE at the end of the minibuffer.
The text is displayed for `minibuffer-message-timeout' seconds,
or until the next input event arrives, whichever comes first.
Enclose MESSAGE in [...] if this is not yet the case.
If ARGS are provided, then pass MESSAGE through `format-message'."
"Temporarily display MESSAGE at the end of minibuffer text.
This function is designed to be called from the minibuffer, i.e.,
when Emacs prompts the user for some input, and the user types
into the minibuffer. If called when the current buffer is not
the minibuffer, this function just calls `message', and thus
displays MESSAGE in the echo-area.
When called from the minibuffer, this function displays MESSAGE
at the end of minibuffer text for `minibuffer-message-timeout'
seconds, or until the next input event arrives, whichever comes first.
It encloses MESSAGE in [...] if it is not yet enclosed.
The intent is to show the message without hiding what the user typed.
If ARGS are provided, then the function first passes MESSAGE
through `format-message'.
If some of the minibuffer text has the `minibuffer-message' text
property, MESSAGE is shown at that position instead of EOB."
(if (not (minibufferp (current-buffer) t))
(progn
(if args
@ -796,7 +806,7 @@ The minibuffer message functions include `minibuffer-message' and
(next-single-property-change pt 'minibuffer-message nil (point-max)))))
(defun set-minibuffer-message (message)
"Temporarily display MESSAGE at the end of the minibuffer.
"Temporarily display MESSAGE at the end of the active minibuffer window.
If some part of the minibuffer text has the `minibuffer-message' property,
the message will be displayed before the first such character, instead of
at the end of the minibuffer.
@ -954,7 +964,7 @@ is at its default value `grow-only'."
multi-message-separator)))
(defun clear-minibuffer-message ()
"Clear minibuffer message.
"Clear message temporarily shown in the minibuffer.
Intended to be called via `clear-message-function'."
(when (not noninteractive)
(when (timerp minibuffer-message-timer)