New variable set-message-function to show message at the end of the minibuffer

* doc/lispref/display.texi (Displaying Messages): Document
set-message-function and clear-message-function.

* lisp/minibuffer.el (minibuffer-message-clear-timeout): New defcustom.
(minibuffer-message-timer, minibuffer-message-overlay): New variables.
(set-minibuffer-message, clear-minibuffer-message): New functions.
(set-message-function, clear-message-function): Set variables to
set-minibuffer-message and clear-minibuffer-message respectively.

* src/keyboard.c (read_char): Call clear_message when
Vclear_message_function is a function.

* src/xdisp.c (set_message): Call Vset_message_function when it's a function.
(clear_message): Call Vclear_message_function when it's a function.
(syms_of_xdisp): New variables set-message-function and clear-message-function
(bug#38457).

1 files changed, 29 insertions, 0 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 42b049eafde..0085f3b6750 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -306,6 +306,35 @@ reformatted, with undesirable results.  Instead, use @code{(message
 "%s" @var{string})}.
 @end defun
 
+@defvar set-message-function
+When this variable is non-@code{nil}, @code{message} and related functions
+call it as a function with one argument that is the message to show.
+
+When this function returns @code{nil}, the message is displayed in the
+echo area as usual.  When the function returns a string, the returned
+string is displayed in the echo area.  When this function returns
+other non-@code{nil} values, this means that the message was handled
+specially, so the same message is not displayed in the echo area.
+See also @code{clear-message-function} that can be used to clear the
+message displayed by this function.
+
+The default value is the function that displays the message at the end
+of the minibuffer when the minibuffer is active.
+@end defvar
+
+@defvar clear-message-function
+When this variable is non-@code{nil}, @code{message} and related functions
+call it without arguments when their message is @code{nil} or the empty string.
+
+Usually this function is called when the next input event arrives.
+The function is called without arguments.  It is expected to clear the
+message displayed by its counterpart function specified by
+@code{set-message-function}.
+
+The default value is the function that clears the message displayed at
+the end of the minibuffer when the minibuffer is active.
+@end defvar
+
 @defvar inhibit-message
 When this variable is non-@code{nil}, @code{message} and related functions
 will not use the Echo Area to display messages.