This is elisp, produced by makeinfo version 4.0f from ./elisp.texi. INFO-DIR-SECTION Editors START-INFO-DIR-ENTRY * Elisp: (elisp). The Emacs Lisp Reference Manual. END-INFO-DIR-ENTRY This Info file contains edition 2.8 of the GNU Emacs Lisp Reference Manual, corresponding to Emacs version 21.2. Published by the Free Software Foundation 59 Temple Place, Suite 330 Boston, MA 02111-1307 USA Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "Copying", with the Front-Cover texts being "A GNU Manual", and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License". (a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development."  File: elisp, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes Process Filter Functions ------------------------ A process "filter function" is a function that receives the standard output from the associated process. If a process has a filter, then _all_ output from that process is passed to the filter. The process buffer is used directly for output from the process only when there is no filter. The filter function can only be called when Emacs is waiting for something, because process output arrives only at such times. Emacs waits when reading terminal input, in `sit-for' and `sleep-for' (*note Waiting::), and in `accept-process-output' (*note Accepting Output::). A filter function must accept two arguments: the associated process and a string, which is output just received from it. The function is then free to do whatever it chooses with the output. Quitting is normally inhibited within a filter function--otherwise, the effect of typing `C-g' at command level or to quit a user command would be unpredictable. If you want to permit quitting inside a filter function, bind `inhibit-quit' to `nil'. *Note Quitting::. If an error happens during execution of a filter function, it is caught automatically, so that it doesn't stop the execution of whatever program was running when the filter function was started. However, if `debug-on-error' is non-`nil', the error-catching is turned off. This makes it possible to use the Lisp debugger to debug the filter function. *Note Debugger::. Many filter functions sometimes or always insert the text in the process's buffer, mimicking the actions of Emacs when there is no filter. Such filter functions need to use `set-buffer' in order to be sure to insert in that buffer. To avoid setting the current buffer semipermanently, these filter functions must save and restore the current buffer. They should also update the process marker, and in some cases update the value of point. Here is how to do these things: (defun ordinary-insertion-filter (proc string) (with-current-buffer (process-buffer proc) (let ((moving (= (point) (process-mark proc)))) (save-excursion ;; Insert the text, advancing the process marker. (goto-char (process-mark proc)) (insert string) (set-marker (process-mark proc) (point))) (if moving (goto-char (process-mark proc)))))) The reason to use `with-current-buffer', rather than using `save-excursion' to save and restore the current buffer, is so as to preserve the change in point made by the second call to `goto-char'. To make the filter force the process buffer to be visible whenever new text arrives, insert the following line just before the `with-current-buffer' construct: (display-buffer (process-buffer proc)) To force point to the end of the new output, no matter where it was previously, eliminate the variable `moving' and call `goto-char' unconditionally. In earlier Emacs versions, every filter function that did regular expression searching or matching had to explicitly save and restore the match data. Now Emacs does this automatically for filter functions; they never need to do it explicitly. *Note Match Data::. A filter function that writes the output into the buffer of the process should check whether the buffer is still alive. If it tries to insert into a dead buffer, it will get an error. The expression `(buffer-name (process-buffer PROCESS))' returns `nil' if the buffer is dead. The output to the function may come in chunks of any size. A program that produces the same output twice in a row may send it as one batch of 200 characters one time, and five batches of 40 characters the next. If the filter looks for certain text strings in the subprocess output, make sure to handle the case where one of these strings is split across two or more batches of output. - Function: set-process-filter process filter This function gives PROCESS the filter function FILTER. If FILTER is `nil', it gives the process no filter. - Function: process-filter process This function returns the filter function of PROCESS, or `nil' if it has none. Here is an example of use of a filter function: (defun keep-output (process output) (setq kept (cons output kept))) => keep-output (setq kept nil) => nil (set-process-filter (get-process "shell") 'keep-output) => keep-output (process-send-string "shell" "ls ~/other\n") => nil kept => ("lewis@slug[8] % " "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~ address.txt backup.psf kolstad.psf backup.bib~ david.mss resume-Dec-86.mss~ backup.err david.psf resume-Dec.psf backup.mss dland syllabus.mss " "#backups.mss# backup.mss~ kolstad.mss ")  File: elisp, Node: Accepting Output, Prev: Filter Functions, Up: Output from Processes Accepting Output from Processes ------------------------------- Output from asynchronous subprocesses normally arrives only while Emacs is waiting for some sort of external event, such as elapsed time or terminal input. Occasionally it is useful in a Lisp program to explicitly permit output to arrive at a specific point, or even to wait until output arrives from a process. - Function: accept-process-output &optional process seconds millisec This function allows Emacs to read pending output from processes. The output is inserted in the associated buffers or given to their filter functions. If PROCESS is non-`nil' then this function does not return until some output has been received from PROCESS. The arguments SECONDS and MILLISEC let you specify timeout periods. The former specifies a period measured in seconds and the latter specifies one measured in milliseconds. The two time periods thus specified are added together, and `accept-process-output' returns after that much time whether or not there has been any subprocess output. The argument SECONDS need not be an integer. If it is a floating point number, this function waits for a fractional number of seconds. Some systems support only a whole number of seconds; on these systems, SECONDS is rounded down. Not all operating systems support waiting periods other than multiples of a second; on those that do not, you get an error if you specify nonzero MILLISEC. The function `accept-process-output' returns non-`nil' if it did get some output, or `nil' if the timeout expired before output arrived.  File: elisp, Node: Sentinels, Next: Transaction Queues, Prev: Output from Processes, Up: Processes Sentinels: Detecting Process Status Changes =========================================== A "process sentinel" is a function that is called whenever the associated process changes status for any reason, including signals (whether sent by Emacs or caused by the process's own actions) that terminate, stop, or continue the process. The process sentinel is also called if the process exits. The sentinel receives two arguments: the process for which the event occurred, and a string describing the type of event. The string describing the event looks like one of the following: * `"finished\n"'. * `"exited abnormally with code EXITCODE\n"'. * `"NAME-OF-SIGNAL\n"'. * `"NAME-OF-SIGNAL (core dumped)\n"'. A sentinel runs only while Emacs is waiting (e.g., for terminal input, or for time to elapse, or for process output). This avoids the timing errors that could result from running them at random places in the middle of other Lisp programs. A program can wait, so that sentinels will run, by calling `sit-for' or `sleep-for' (*note Waiting::), or `accept-process-output' (*note Accepting Output::). Emacs also allows sentinels to run when the command loop is reading input. Quitting is normally inhibited within a sentinel--otherwise, the effect of typing `C-g' at command level or to quit a user command would be unpredictable. If you want to permit quitting inside a sentinel, bind `inhibit-quit' to `nil'. *Note Quitting::. A sentinel that writes the output into the buffer of the process should check whether the buffer is still alive. If it tries to insert into a dead buffer, it will get an error. If the buffer is dead, `(buffer-name (process-buffer PROCESS))' returns `nil'. If an error happens during execution of a sentinel, it is caught automatically, so that it doesn't stop the execution of whatever programs was running when the sentinel was started. However, if `debug-on-error' is non-`nil', the error-catching is turned off. This makes it possible to use the Lisp debugger to debug the sentinel. *Note Debugger::. In earlier Emacs versions, every sentinel that did regular expression searching or matching had to explicitly save and restore the match data. Now Emacs does this automatically for sentinels; they never need to do it explicitly. *Note Match Data::. - Function: set-process-sentinel process sentinel This function associates SENTINEL with PROCESS. If SENTINEL is `nil', then the process will have no sentinel. The default behavior when there is no sentinel is to insert a message in the process's buffer when the process status changes. (defun msg-me (process event) (princ (format "Process: %s had the event `%s'" process event))) (set-process-sentinel (get-process "shell") 'msg-me) => msg-me (kill-process (get-process "shell")) -| Process: # had the event `killed' => # - Function: process-sentinel process This function returns the sentinel of PROCESS, or `nil' if it has none. - Function: waiting-for-user-input-p While a sentinel or filter function is running, this function returns non-`nil' if Emacs was waiting for keyboard input from the user at the time the sentinel or filter function was called, `nil' if it was not.  File: elisp, Node: Transaction Queues, Next: Network, Prev: Sentinels, Up: Processes Transaction Queues ================== You can use a "transaction queue" to communicate with a subprocess using transactions. First use `tq-create' to create a transaction queue communicating with a specified process. Then you can call `tq-enqueue' to send a transaction. - Function: tq-create process This function creates and returns a transaction queue communicating with PROCESS. The argument PROCESS should be a subprocess capable of sending and receiving streams of bytes. It may be a child process, or it may be a TCP connection to a server, possibly on another machine. - Function: tq-enqueue queue question regexp closure fn This function sends a transaction to queue QUEUE. Specifying the queue has the effect of specifying the subprocess to talk to. The argument QUESTION is the outgoing message that starts the transaction. The argument FN is the function to call when the corresponding answer comes back; it is called with two arguments: CLOSURE, and the answer received. The argument REGEXP is a regular expression that should match text at the end of the entire answer, but nothing before; that's how `tq-enqueue' determines where the answer ends. The return value of `tq-enqueue' itself is not meaningful. - Function: tq-close queue Shut down transaction queue QUEUE, waiting for all pending transactions to complete, and then terminate the connection or child process. Transaction queues are implemented by means of a filter function. *Note Filter Functions::.  File: elisp, Node: Network, Prev: Transaction Queues, Up: Processes Network Connections =================== Emacs Lisp programs can open TCP network connections to other processes on the same machine or other machines. A network connection is handled by Lisp much like a subprocess, and is represented by a process object. However, the process you are communicating with is not a child of the Emacs process, so you can't kill it or send it signals. All you can do is send and receive data. `delete-process' closes the connection, but does not kill the process at the other end; that process must decide what to do about closure of the connection. You can distinguish process objects representing network connections from those representing subprocesses with the `process-status' function. It always returns either `open' or `closed' for a network connection, and it never returns either of those values for a real subprocess. *Note Process Information::. - Function: open-network-stream name buffer-or-name host service This function opens a TCP connection for a service to a host. It returns a process object to represent the connection. The NAME argument specifies the name for the process object. It is modified as necessary to make it unique. The BUFFER-OR-NAME argument is the buffer to associate with the connection. Output from the connection is inserted in the buffer, unless you specify a filter function to handle the output. If BUFFER-OR-NAME is `nil', it means that the connection is not associated with any buffer. The arguments HOST and SERVICE specify where to connect to; HOST is the host name (a string), and SERVICE is the name of a defined network service (a string) or a port number (an integer).  File: elisp, Node: Display, Next: Calendar, Prev: Processes, Up: Top Emacs Display ************* This chapter describes a number of features related to the display that Emacs presents to the user. * Menu: * Refresh Screen:: Clearing the screen and redrawing everything on it. * Forcing Redisplay:: Forcing redisplay. * Truncation:: Folding or wrapping long text lines. * The Echo Area:: Where messages are displayed. * Invisible Text:: Hiding part of the buffer text. * Selective Display:: Hiding part of the buffer text (the old way). * Overlay Arrow:: Display of an arrow to indicate position. * Temporary Displays:: Displays that go away automatically. * Overlays:: Use overlays to highlight parts of the buffer. * Width:: How wide a character or string is on the screen. * Faces:: A face defines a graphics style for text characters: font, colors, etc. * Display Property:: Enabling special display features. * Images:: Displaying images in Emacs buffers. * Blinking:: How Emacs shows the matching open parenthesis. * Inverse Video:: Specifying how the screen looks. * Usual Display:: The usual conventions for displaying nonprinting chars. * Display Tables:: How to specify other conventions. * Beeping:: Audible signal to the user. * Window Systems:: Which window system is being used.  File: elisp, Node: Refresh Screen, Next: Forcing Redisplay, Up: Display Refreshing the Screen ===================== The function `redraw-frame' redisplays the entire contents of a given frame (*note Frames::). - Function: redraw-frame frame This function clears and redisplays frame FRAME. Even more powerful is `redraw-display': - Command: redraw-display This function clears and redisplays all visible frames. Processing user input takes absolute priority over redisplay. If you call these functions when input is available, they do nothing immediately, but a full redisplay does happen eventually--after all the input has been processed. Normally, suspending and resuming Emacs also refreshes the screen. Some terminal emulators record separate contents for display-oriented programs such as Emacs and for ordinary sequential display. If you are using such a terminal, you might want to inhibit the redisplay on resumption. - Variable: no-redraw-on-reenter This variable controls whether Emacs redraws the entire screen after it has been suspended and resumed. Non-`nil' means there is no need to redraw, `nil' means redrawing is needed. The default is `nil'.  File: elisp, Node: Forcing Redisplay, Next: Truncation, Prev: Refresh Screen, Up: Display Forcing Redisplay ================= Emacs redisplay normally stops if input arrives, and does not happen at all if input is available before it starts. Most of the time, this is exactly what you want. However, you can prevent preemption by binding `redisplay-dont-pause' to a non-`nil' value. - Variable: redisplay-dont-pause If this variable is non-`nil', pending input does not prevent or halt redisplay; redisplay occurs, and finishes, regardless of whether input is available. This feature is available as of Emacs 21. You can request a display update, but only if no input is pending, with `(sit-for 0)'. To force a display update even when input is pending, do this: (let ((redisplay-dont-pause t)) (sit-for 0))  File: elisp, Node: Truncation, Next: The Echo Area, Prev: Forcing Redisplay, Up: Display Truncation ========== When a line of text extends beyond the right edge of a window, the line can either be continued on the next screen line, or truncated to one screen line. The additional screen lines used to display a long text line are called "continuation" lines. Normally, a `$' in the rightmost column of the window indicates truncation; a `\' on the rightmost column indicates a line that "wraps" onto the next line, which is also called "continuing" the line. (The display table can specify alternative indicators; see *Note Display Tables::.) Note that continuation is different from filling; continuation happens on the screen only, not in the buffer contents, and it breaks a line precisely at the right margin, not at a word boundary. *Note Filling::. - User Option: truncate-lines This buffer-local variable controls how Emacs displays lines that extend beyond the right edge of the window. The default is `nil', which specifies continuation. If the value is non-`nil', then these lines are truncated. If the variable `truncate-partial-width-windows' is non-`nil', then truncation is always used for side-by-side windows (within one frame) regardless of the value of `truncate-lines'. - User Option: default-truncate-lines This variable is the default value for `truncate-lines', for buffers that do not have buffer-local values for it. - User Option: truncate-partial-width-windows This variable controls display of lines that extend beyond the right edge of the window, in side-by-side windows (*note Splitting Windows::). If it is non-`nil', these lines are truncated; otherwise, `truncate-lines' says what to do with them. When horizontal scrolling (*note Horizontal Scrolling::) is in use in a window, that forces truncation. You can override the glyphs that indicate continuation or truncation using the display table; see *Note Display Tables::. If your buffer contains _very_ long lines, and you use continuation to display them, just thinking about them can make Emacs redisplay slow. The column computation and indentation functions also become slow. Then you might find it advisable to set `cache-long-line-scans' to `t'. - Variable: cache-long-line-scans If this variable is non-`nil', various indentation and motion functions, and Emacs redisplay, cache the results of scanning the buffer, and consult the cache to avoid rescanning regions of the buffer unless they are modified. Turning on the cache slows down processing of short lines somewhat. This variable is automatically buffer-local in every buffer.  File: elisp, Node: The Echo Area, Next: Invisible Text, Prev: Truncation, Up: Display The Echo Area ============= The "echo area" is used for displaying messages made with the `message' primitive, and for echoing keystrokes. It is not the same as the minibuffer, despite the fact that the minibuffer appears (when active) in the same place on the screen as the echo area. The `GNU Emacs Manual' specifies the rules for resolving conflicts between the echo area and the minibuffer for use of that screen space (*note The Minibuffer: (emacs)Minibuffer.). Error messages appear in the echo area; see *Note Errors::. You can write output in the echo area by using the Lisp printing functions with `t' as the stream (*note Output Functions::), or as follows: - Function: message string &rest arguments This function displays a message in the echo area. The argument STRING is similar to a C language `printf' control string. See `format' in *Note String Conversion::, for the details on the conversion specifications. `message' returns the constructed string. In batch mode, `message' prints the message text on the standard error stream, followed by a newline. If STRING, or strings among the ARGUMENTS, have `face' text properties, these affect the way the message is displayed. If STRING is `nil', `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. Normally, displaying a long message resizes the echo area to display the entire message. But if the variable `message-truncate-lines' is non-`nil', the echo area does not resize, and the message is truncated to fit it, as in Emacs 20 and before. (message "Minibuffer depth is %d." (minibuffer-depth)) -| Minibuffer depth is 0. => "Minibuffer depth is 0." ---------- Echo Area ---------- Minibuffer depth is 0. ---------- 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'. - 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 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' (*note 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 *Note 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 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 not-this-window 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 NOT-THIS-WINDOW 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. - Variable: cursor-in-echo-area This variable controls where the cursor appears when a message is displayed in the echo area. If it is non-`nil', then the cursor appears at the end of the message. Otherwise, the cursor appears at point--not in the echo area at all. The value is normally `nil'; Lisp programs bind it to `t' for brief periods of time. - Variable: echo-area-clear-hook This normal hook is run whenever the echo area is cleared--either by `(message nil)' or for any other reason. Almost all the messages displayed in the echo area are also recorded in the `*Messages*' buffer. - User Option: message-log-max This variable specifies how many lines to keep in the `*Messages*' buffer. The value `t' means there is no limit on how many lines to keep. The value `nil' disables message logging entirely. Here's how to display a message and prevent it from being logged: (let (message-log-max) (message ...)) - Variable: echo-keystrokes This variable determines how much time should elapse before command characters echo. Its value must be an integer or floating point number, which specifies the number of seconds to wait before echoing. If the user types a prefix key (such as `C-x') and then delays this many seconds before continuing, the prefix key is echoed in the echo area. (Once echoing begins in a key sequence, all subsequent characters in the same key sequence are echoed immediately.) If the value is zero, then command input is not echoed.  File: elisp, Node: Invisible Text, Next: Selective Display, Prev: The Echo Area, Up: Display Invisible Text ============== You can make characters "invisible", so that they do not appear on the screen, with the `invisible' property. This can be either a text property (*note Text Properties::) or a property of an overlay (*note Overlays::). In the simplest case, any non-`nil' `invisible' property makes a character invisible. This is the default case--if you don't alter the default value of `buffer-invisibility-spec', this is how the `invisible' property works. More generally, you can use the variable `buffer-invisibility-spec' to control which values of the `invisible' property make text invisible. This permits you to classify the text into different subsets in advance, by giving them different `invisible' values, and subsequently make various subsets visible or invisible by changing the value of `buffer-invisibility-spec'. Controlling visibility with `buffer-invisibility-spec' is especially useful in a program to display the list of entries in a database. It permits the implementation of convenient filtering commands to view just a part of the entries in the database. Setting this variable is very fast, much faster than scanning all the text in the buffer looking for properties to change. - Variable: buffer-invisibility-spec This variable specifies which kinds of `invisible' properties actually make a character invisible. `t' A character is invisible if its `invisible' property is non-`nil'. This is the default. a list Each element of the list specifies a criterion for invisibility; if a character's `invisible' property fits any one of these criteria, the character is invisible. The list can have two kinds of elements: `ATOM' A character is invisible if its `invisible' property value is ATOM or if it is a list with ATOM as a member. `(ATOM . t)' A character is invisible if its `invisible' property value is ATOM or if it is a list with ATOM as a member. Moreover, if this character is at the end of a line and is followed by a visible newline, it displays an ellipsis. Two functions are specifically provided for adding elements to `buffer-invisibility-spec' and removing elements from it. - Function: add-to-invisibility-spec element Add the element ELEMENT to `buffer-invisibility-spec' (if it is not already present in that list). - Function: remove-from-invisibility-spec element Remove the element ELEMENT from `buffer-invisibility-spec'. This does nothing if ELEMENT is not in the list. One convention about the use of `buffer-invisibility-spec' is that a major mode should use the mode's own name as an element of `buffer-invisibility-spec' and as the value of the `invisible' property: ;; If you want to display an ellipsis: (add-to-invisibility-spec '(my-symbol . t)) ;; If you don't want ellipsis: (add-to-invisibility-spec 'my-symbol) (overlay-put (make-overlay beginning end) 'invisible 'my-symbol) ;; When done with the overlays: (remove-from-invisibility-spec '(my-symbol . t)) ;; Or respectively: (remove-from-invisibility-spec 'my-symbol) Ordinarily, commands that operate on text or move point do not care whether the text is invisible. The user-level line motion commands explicitly ignore invisible newlines if `line-move-ignore-invisible' is non-`nil', but only because they are explicitly programmed to do so. Incremental search can make invisible overlays visible temporarily and/or permanently when a match includes invisible text. To enable this, the overlay should have a non-`nil' `isearch-open-invisible' property. The property value should be a function to be called with the overlay as an argument. This function should make the overlay visible permanently; it is used when the match overlaps the overlay on exit from the search. During the search, such overlays are made temporarily visible by temporarily modifying their invisible and intangible properties. If you want this to be done differently for a certain overlay, give it an `isearch-open-invisible-temporary' property which is a function. The function is called with two arguments: the first is the overlay, and the second is `nil' to make the overlay visible, or `t' to make it invisible again.  File: elisp, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display Selective Display ================= "Selective display" refers to a pair of related features for hiding certain lines on the screen. The first variant, explicit selective display, is designed for use in a Lisp program: it controls which lines are hidden by altering the text. The invisible text feature (*note Invisible Text::) has partially replaced this feature. In the second variant, the choice of lines to hide is made automatically based on indentation. This variant is designed to be a user-level feature. The way you control explicit selective display is by replacing a newline (control-j) with a carriage return (control-m). The text that was formerly a line following that newline is now invisible. Strictly speaking, it is temporarily no longer a line at all, since only newlines can separate lines; it is now part of the previous line. Selective display does not directly affect editing commands. For example, `C-f' (`forward-char') moves point unhesitatingly into invisible text. However, the replacement of newline characters with carriage return characters affects some editing commands. For example, `next-line' skips invisible lines, since it searches only for newlines. Modes that use selective display can also define commands that take account of the newlines, or that make parts of the text visible or invisible. When you write a selectively displayed buffer into a file, all the control-m's are output as newlines. This means that when you next read in the file, it looks OK, with nothing invisible. The selective display effect is seen only within Emacs. - Variable: selective-display This buffer-local variable enables selective display. This means that lines, or portions of lines, may be made invisible. * If the value of `selective-display' is `t', then the character control-m marks the start of invisible text; the control-m, and the rest of the line following it, are not displayed. This is explicit selective display. * If the value of `selective-display' is a positive integer, then lines that start with more than that many columns of indentation are not displayed. When some portion of a buffer is invisible, the vertical movement commands operate as if that portion did not exist, allowing a single `next-line' command to skip any number of invisible lines. However, character movement commands (such as `forward-char') do not skip the invisible portion, and it is possible (if tricky) to insert or delete text in an invisible portion. In the examples below, we show the _display appearance_ of the buffer `foo', which changes with the value of `selective-display'. The _contents_ of the buffer do not change. (setq selective-display nil) => nil ---------- Buffer: foo ---------- 1 on this column 2on this column 3n this column 3n this column 2on this column 1 on this column ---------- Buffer: foo ---------- (setq selective-display 2) => 2 ---------- Buffer: foo ---------- 1 on this column 2on this column 2on this column 1 on this column ---------- Buffer: foo ---------- - Variable: selective-display-ellipses If this buffer-local variable is non-`nil', then Emacs displays `...' at the end of a line that is followed by invisible text. This example is a continuation of the previous one. (setq selective-display-ellipses t) => t ---------- Buffer: foo ---------- 1 on this column 2on this column ... 2on this column 1 on this column ---------- Buffer: foo ---------- You can use a display table to substitute other text for the ellipsis (`...'). *Note Display Tables::.  File: elisp, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display The Overlay Arrow ================= The "overlay arrow" is useful for directing the user's attention to a particular line in a buffer. For example, in the modes used for interface to debuggers, the overlay arrow indicates the line of code about to be executed. - Variable: overlay-arrow-string This variable holds the string to display to call attention to a particular line, or `nil' if the arrow feature is not in use. On a graphical display the contents of the string are ignored; instead a glyph is displayed in the fringe area to the left of the display area. - Variable: overlay-arrow-position This variable holds a marker that indicates where to display the overlay arrow. It should point at the beginning of a line. On a non-graphical display the arrow text appears at the beginning of that line, overlaying any text that would otherwise appear. Since the arrow is usually short, and the line usually begins with indentation, normally nothing significant is overwritten. The overlay string is displayed only in the buffer that this marker points into. Thus, only one buffer can have an overlay arrow at any given time. You can do a similar job by creating an overlay with a `before-string' property. *Note Overlay Properties::.  File: elisp, Node: Temporary Displays, Next: Overlays, Prev: Overlay Arrow, Up: Display 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 ---------- 20 # ---------- 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 ----------  File: elisp, Node: Overlays, Next: Width, Prev: Temporary Displays, Up: Display Overlays ======== You can use "overlays" to alter the appearance of a buffer's text on the screen, for the sake of presentation features. An overlay is an object that belongs to a particular buffer, and has a specified beginning and end. It also has properties that you can examine and set; these affect the display of the text within the overlay. * Menu: * Overlay Properties:: How to read and set properties. What properties do to the screen display. * Managing Overlays:: Creating and moving overlays. * Finding Overlays:: Searching for overlays.