Info Catalog elisp: The Echo Area elisp: Progress

elisp: Displaying Messages

 
 37.4.1 Displaying Messages in the Echo Area
 -------------------------------------------
 
 This section describes the standard functions for displaying messages in
 the echo area.
 
  -- Function: message format-string &rest arguments
      This function displays a message in the echo area.  FORMAT-STRING
      is a format string, and ARGUMENTS are the objects for its format
      specifications, like in the ‘format-message’ function (
      Formatting Strings).  The resulting formatted string is displayed
      in the echo area; if it contains ‘face’ text properties, it is
      displayed with the specified faces (Faces).  The string is
      also added to the ‘*Messages*’ buffer, but without text properties
      (Logging Messages).
 
      The ‘text-quoting-style’ variable controls what quotes are
      generated; Keys in Documentation.  A call using a format
      like "Missing `%s'" with grave accents and apostrophes typically
      generates a message like "Missing ‘foo’" with matching curved
      quotes.  In contrast, a call using a format like "Missing '%s'"
      with only apostrophes typically generates a message like "Missing
      ’foo’" with only closing curved quotes, an unusual style in
      English.
 
      In batch mode, the message is printed to the standard error stream,
      followed by a newline.
 
      When ‘inhibit-message’ is non-‘nil’, no message will be displayed
      in the echo area, it will only be logged to ‘*Messages*’.
 
      If FORMAT-STRING is ‘nil’ or the empty string, ‘message’ clears the
      echo area; if the echo area has been expanded automatically, this
      brings it back to its normal size.  If the minibuffer is active,
      this brings the minibuffer contents back onto the screen
      immediately.
 
           (message "Reverting `%s'..." (buffer-name))
            ⊣ Reverting ‘subr.el’...
           ⇒ "Reverting ‘subr.el’..."
 
           ---------- Echo Area ----------
           Reverting ‘subr.el’...
           ---------- Echo Area ----------
 
      To automatically display a message in the echo area or in a
      pop-buffer, depending on its size, use ‘display-message-or-buffer’
      (see below).
 
      *Warning:* If you want to use your own string as a message
      verbatim, don’t just write ‘(message STRING)’.  If STRING contains
      ‘%’, ‘`’, or ‘'’ it may be reformatted, with undesirable results.
      Instead, use ‘(message "%s" STRING)’.
 
  -- Variable: inhibit-message
      When this variable is non-‘nil’, ‘message’ and related functions
      will not use the Echo Area to display messages.
 
  -- Macro: with-temp-message message &rest body
      This construct displays a message in the echo area temporarily,
      during the execution of BODY.  It displays MESSAGE, executes BODY,
      then returns the value of the last body form while restoring the
      previous echo area contents.
 
  -- Function: message-or-box format-string &rest arguments
      This function displays a message like ‘message’, but may display it
      in a dialog box instead of the echo area.  If this function is
      called in a command that was invoked using the mouse—more
      precisely, if ‘last-nonmenu-event’ (Command Loop Info) is
      either ‘nil’ or a list—then it uses a dialog box or pop-up menu to
      display the message.  Otherwise, it uses the echo area.  (This is
      the same criterion that ‘y-or-n-p’ uses to make a similar decision;
      see Yes-or-No Queries.)
 
      You can force use of the mouse or of the echo area by binding
      ‘last-nonmenu-event’ to a suitable value around the call.
 
  -- Function: message-box format-string &rest arguments
      This function displays a message like ‘message’, but uses a dialog
      box (or a pop-up menu) whenever that is possible.  If it is
      impossible to use a dialog box or pop-up menu, because the terminal
      does not support them, then ‘message-box’ uses the echo area, like
      ‘message’.
 
  -- Function: display-message-or-buffer message &optional buffer-name
           action frame
      This function displays the message MESSAGE, which may be either a
      string or a buffer.  If it is shorter than the maximum height of
      the echo area, as defined by ‘max-mini-window-height’, it is
      displayed in the echo area, using ‘message’.  Otherwise,
      ‘display-buffer’ is used to show it in a pop-up buffer.
 
      Returns either the string shown in the echo area, or when a pop-up
      buffer is used, the window used to display it.
 
      If MESSAGE is a string, then the optional argument BUFFER-NAME is
      the name of the buffer used to display it when a pop-up buffer is
      used, defaulting to ‘*Message*’.  In the case where MESSAGE is a
      string and displayed in the echo area, it is not specified whether
      the contents are inserted into the buffer anyway.
 
      The optional arguments ACTION and FRAME are as for
      ‘display-buffer’, and only used if a buffer is displayed.
 
  -- Function: current-message
      This function returns the message currently being displayed in the
      echo area, or ‘nil’ if there is none.
 

Info Catalog elisp: The Echo Area elisp: Progress