GNU Info

(elisp)Temporary Displays

---

Next: Overlays Prev: Overlay Arrow Up: Display

---

Enter node , (file) or (file)node

Temporary Displays
==================

   Temporary displays are used by Lisp programs to put output into a
buffer and then present it to the user for perusal rather than for
editing.  Many help commands use this feature.

 - Special Form: with-output-to-temp-buffer buffer-name forms...
     This function executes FORMS while arranging to insert any output
     they print into the buffer named BUFFER-NAME, which is first
     created if necessary, and put into Help mode.  Finally, the buffer
     is displayed in some window, but not selected.

     If the FORMS do not change the major mode in the output buffer, so
     that it is still Help mode at the end of their execution, then
     `with-output-to-temp-buffer' makes this buffer read-only at the
     end, and also scans it for function and variable names to make
     them into clickable cross-references.

     The string BUFFER-NAME specifies the temporary buffer, which need
     not already exist.  The argument must be a string, not a buffer.
     The buffer is erased initially (with no questions asked), and it is
     marked as unmodified after `with-output-to-temp-buffer' exits.

     `with-output-to-temp-buffer' binds `standard-output' to the
     temporary buffer, then it evaluates the forms in FORMS.  Output
     using the Lisp output functions within FORMS goes by default to
     that buffer (but screen display and messages in the echo area,
     although they are "output" in the general sense of the word, are
     not affected).  Note: Output Functions.

     Several hooks are available for customizing the behavior of this
     construct; they are listed below.

     The value of the last form in FORMS is returned.

          ---------- Buffer: foo ----------
           This is the contents of foo.
          ---------- Buffer: foo ----------
          
          (with-output-to-temp-buffer "foo"
              (print 20)
              (print standard-output))
          => #<buffer foo>
          
          ---------- Buffer: foo ----------
          20
          
          #<buffer foo>
          
          ---------- Buffer: foo ----------

 - Variable: temp-buffer-show-function
     If this variable is non-`nil', `with-output-to-temp-buffer' calls
     it as a function to do the job of displaying a help buffer.  The
     function gets one argument, which is the buffer it should display.

     It is a good idea for this function to run `temp-buffer-show-hook'
     just as `with-output-to-temp-buffer' normally would, inside of
     `save-selected-window' and with the chosen window and buffer
     selected.

 - Variable: temp-buffer-setup-hook
     This normal hook is run by `with-output-to-temp-buffer' before
     evaluating BODY.  When the hook runs, the help buffer is current.
     This hook is normally set up with a function to put the buffer in
     Help mode.

 - Variable: temp-buffer-show-hook
     This normal hook is run by `with-output-to-temp-buffer' after
     displaying the help buffer.  When the hook runs, the help buffer is
     current, and the window it was displayed in is selected.  This
     hook is normally set up with a function to make the buffer read
     only, and find function names and variable names in it, provided
     the major mode is still Help mode.

 - Function: momentary-string-display string position &optional char
          message
     This function momentarily displays STRING in the current buffer at
     POSITION.  It has no effect on the undo list or on the buffer's
     modification status.

     The momentary display remains until the next input event.  If the
     next input event is CHAR, `momentary-string-display' ignores it
     and returns.  Otherwise, that event remains buffered for
     subsequent use as input.  Thus, typing CHAR will simply remove the
     string from the display, while typing (say) `C-f' will remove the
     string from the display and later (presumably) move point forward.
     The argument CHAR is a space by default.

     The return value of `momentary-string-display' is not meaningful.

     If the string STRING does not contain control characters, you can
     do the same job in a more general way by creating (and then
     subsequently deleting) an overlay with a `before-string' property.
     Note: Overlay Properties.

     If MESSAGE is non-`nil', it is displayed in the echo area while
     STRING is displayed in the buffer.  If it is `nil', a default
     message says to type CHAR to continue.

     In this example, point is initially located at the beginning of the
     second line:

          ---------- Buffer: foo ----------
          This is the contents of foo.
          -!-Second line.
          ---------- Buffer: foo ----------
          
          (momentary-string-display
            "**** Important Message! ****"
            (point) ?\r
            "Type RET when done reading")
          => t
          
          ---------- Buffer: foo ----------
          This is the contents of foo.
          **** Important Message! ****Second line.
          ---------- Buffer: foo ----------
          
          ---------- Echo Area ----------
          Type RET when done reading
          ---------- Echo Area ----------