This is ../../info/elisp, produced by makeinfo version 4.11 from elisp.texi. This is edition 3.0 of the GNU Emacs Lisp Reference Manual, corresponding to Emacs version 23.2. Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 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.3 or any later version published by the Free Software Foundation; with the Invariant Sections being "GNU General Public License," 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 the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom." INFO-DIR-SECTION Emacs START-INFO-DIR-ENTRY * Elisp: (elisp). The Emacs Lisp Reference Manual. END-INFO-DIR-ENTRY  File: elisp, Node: Modification Time, Next: Read Only Buffers, Prev: Buffer Modification, Up: Buffers 27.6 Buffer Modification Time ============================= Suppose that you visit a file and make changes in its buffer, and meanwhile the file itself is changed on disk. At this point, saving the buffer would overwrite the changes in the file. Occasionally this may be what you want, but usually it would lose valuable information. Emacs therefore checks the file's modification time using the functions described below before saving the file. (*Note File Attributes::, for how to examine a file's modification time.) -- Function: verify-visited-file-modtime buffer This function compares what BUFFER has recorded for the modification time of its visited file against the actual modification time of the file as recorded by the operating system. The two should be the same unless some other process has written the file since Emacs visited or saved it. The function returns `t' if the last actual modification time and Emacs's recorded modification time are the same, `nil' otherwise. It also returns `t' if the buffer has no recorded last modification time, that is if `visited-file-modtime' would return zero. It always returns `t' for buffers that are not visiting a file, even if `visited-file-modtime' returns a non-zero value. For instance, it always returns `t' for dired buffers. It returns `t' for buffers that are visiting a file that does not exist and never existed, but `nil' for file-visiting buffers whose file has been deleted. -- Function: clear-visited-file-modtime This function clears out the record of the last modification time of the file being visited by the current buffer. As a result, the next attempt to save this buffer will not complain of a discrepancy in file modification times. This function is called in `set-visited-file-name' and other exceptional places where the usual test to avoid overwriting a changed file should not be done. -- Function: visited-file-modtime This function returns the current buffer's recorded last file modification time, as a list of the form `(HIGH LOW)'. (This is the same format that `file-attributes' uses to return time values; see *note File Attributes::.) If the buffer has no recorded last modification time, this function returns zero. This case occurs, for instance, if the buffer is not visiting a file or if the time has been explicitly cleared by `clear-visited-file-modtime'. Note, however, that `visited-file-modtime' returns a list for some non-file buffers too. For instance, in a Dired buffer listing a directory, it returns the last modification time of that directory, as recorded by Dired. For a new buffer visiting a not yet existing file, HIGH is -1 and LOW is 65535, that is, 2**16 - 1. -- Function: set-visited-file-modtime &optional time This function updates the buffer's record of the last modification time of the visited file, to the value specified by TIME if TIME is not `nil', and otherwise to the last modification time of the visited file. If TIME is neither `nil' nor zero, it should have the form `(HIGH . LOW)' or `(HIGH LOW)', in either case containing two integers, each of which holds 16 bits of the time. This function is useful if the buffer was not read from the file normally, or if the file itself has been changed for some known benign reason. -- Function: ask-user-about-supersession-threat filename This function is used to ask a user how to proceed after an attempt to modify an buffer visiting file FILENAME when the file is newer than the buffer text. Emacs detects this because the modification time of the file on disk is newer than the last save-time of the buffer. This means some other program has probably altered the file. Depending on the user's answer, the function may return normally, in which case the modification of the buffer proceeds, or it may signal a `file-supersession' error with data `(FILENAME)', in which case the proposed buffer modification is not allowed. This function is called automatically by Emacs on the proper occasions. It exists so you can customize Emacs by redefining it. See the file `userlock.el' for the standard definition. See also the file locking mechanism in *note File Locks::.  File: elisp, Node: Read Only Buffers, Next: The Buffer List, Prev: Modification Time, Up: Buffers 27.7 Read-Only Buffers ====================== If a buffer is "read-only", then you cannot change its contents, although you may change your view of the contents by scrolling and narrowing. Read-only buffers are used in two kinds of situations: * A buffer visiting a write-protected file is normally read-only. Here, the purpose is to inform the user that editing the buffer with the aim of saving it in the file may be futile or undesirable. The user who wants to change the buffer text despite this can do so after clearing the read-only flag with `C-x C-q'. * Modes such as Dired and Rmail make buffers read-only when altering the contents with the usual editing commands would probably be a mistake. The special commands of these modes bind `buffer-read-only' to `nil' (with `let') or bind `inhibit-read-only' to `t' around the places where they themselves change the text. -- Variable: buffer-read-only This buffer-local variable specifies whether the buffer is read-only. The buffer is read-only if this variable is non-`nil'. -- Variable: inhibit-read-only If this variable is non-`nil', then read-only buffers and, depending on the actual value, some or all read-only characters may be modified. Read-only characters in a buffer are those that have non-`nil' `read-only' properties (either text properties or overlay properties). *Note Special Properties::, for more information about text properties. *Note Overlays::, for more information about overlays and their properties. If `inhibit-read-only' is `t', all `read-only' character properties have no effect. If `inhibit-read-only' is a list, then `read-only' character properties have no effect if they are members of the list (comparison is done with `eq'). -- Command: toggle-read-only &optional arg This command toggles whether the current buffer is read-only. It is intended for interactive use; do not use it in programs. At any given point in a program, you should know whether you want the read-only flag on or off; so you can set `buffer-read-only' explicitly to the proper value, `t' or `nil'. If ARG is non-`nil', it should be a raw prefix argument. `toggle-read-only' sets `buffer-read-only' to `t' if the numeric value of that prefix argument is positive and to `nil' otherwise. *Note Prefix Command Arguments::. -- Function: barf-if-buffer-read-only This function signals a `buffer-read-only' error if the current buffer is read-only. *Note Using Interactive::, for another way to signal an error if the current buffer is read-only.  File: elisp, Node: The Buffer List, Next: Creating Buffers, Prev: Read Only Buffers, Up: Buffers 27.8 The Buffer List ==================== The "buffer list" is a list of all live buffers. The order of the buffers in this list is based primarily on how recently each buffer has been displayed in a window. Several functions, notably `other-buffer', use this ordering. A buffer list displayed for the user also follows this order. Creating a buffer adds it to the end of the buffer list, and killing a buffer removes it from that list. A buffer moves to the front of this list whenever it is chosen for display in a window (*note Displaying Buffers::) or a window displaying it is selected (*note Selecting Windows::). A buffer moves to the end of the list when it is buried (see `bury-buffer', below). There are no functions available to the Lisp programmer which directly manipulate the buffer list. In addition to the fundamental buffer list just described, Emacs maintains a local buffer list for each frame, in which the buffers that have been displayed (or had their windows selected) in that frame come first. (This order is recorded in the frame's `buffer-list' frame parameter; see *note Buffer Parameters::.) Buffers never displayed in that frame come afterward, ordered according to the fundamental buffer list. -- Function: buffer-list &optional frame This function returns the buffer list, including all buffers, even those whose names begin with a space. The elements are actual buffers, not their names. If FRAME is a frame, this returns FRAME's local buffer list. If FRAME is `nil' or omitted, the fundamental buffer list is used: the buffers appear in order of most recent display or selection, regardless of which frames they were displayed on. (buffer-list) => (# # # # #) ;; Note that the name of the minibuffer ;; begins with a space! (mapcar (function buffer-name) (buffer-list)) => ("buffers.texi" " *Minibuf-1*" "buffer.c" "*Help*" "TAGS") The list returned by `buffer-list' is constructed specifically; it is not an internal Emacs data structure, and modifying it has no effect on the order of buffers. If you want to change the order of buffers in the fundamental buffer list, here is an easy way: (defun reorder-buffer-list (new-list) (while new-list (bury-buffer (car new-list)) (setq new-list (cdr new-list)))) With this method, you can specify any order for the list, but there is no danger of losing a buffer or adding something that is not a valid live buffer. To change the order or value of a specific frame's buffer list, set that frame's `buffer-list' parameter with `modify-frame-parameters' (*note Parameter Access::). -- Function: other-buffer &optional buffer visible-ok frame This function returns the first buffer in the buffer list other than BUFFER. Usually, this is the buffer appearing in the most recently selected window (in frame FRAME or else the selected frame, *note Input Focus::), aside from BUFFER. Buffers whose names start with a space are not considered at all. If BUFFER is not supplied (or if it is not a live buffer), then `other-buffer' returns the first buffer in the selected frame's local buffer list. (If FRAME is non-`nil', it returns the first buffer in FRAME's local buffer list instead.) If FRAME has a non-`nil' `buffer-predicate' parameter, then `other-buffer' uses that predicate to decide which buffers to consider. It calls the predicate once for each buffer, and if the value is `nil', that buffer is ignored. *Note Buffer Parameters::. If VISIBLE-OK is `nil', `other-buffer' avoids returning a buffer visible in any window on any visible frame, except as a last resort. If VISIBLE-OK is non-`nil', then it does not matter whether a buffer is displayed somewhere or not. If no suitable buffer exists, the buffer `*scratch*' is returned (and created, if necessary). -- Function: last-buffer &optional buffer visible-ok frame This function returns the last buffer in FRAME's buffer list other than BUFFER. If FRAME is omitted or `nil', it uses the selected frame's buffer list. The argument VISIBLE-OK is handled as with `other-buffer', see above. If no suitable buffer can be found, the buffer `*scratch*' is returned. -- Command: bury-buffer &optional buffer-or-name This command puts BUFFER-OR-NAME at the end of the buffer list, without changing the order of any of the other buffers on the list. This buffer therefore becomes the least desirable candidate for `other-buffer' to return. The argument can be either a buffer itself or the name of one. `bury-buffer' operates on each frame's `buffer-list' parameter as well as the fundamental buffer list; therefore, the buffer that you bury will come last in the value of `(buffer-list FRAME)' and in the value of `(buffer-list)'. If BUFFER-OR-NAME is `nil' or omitted, this means to bury the current buffer. In addition, if the buffer is displayed in the selected window, this switches to some other buffer (obtained using `other-buffer') in the selected window. *Note Displaying Buffers::. But if the selected window is dedicated to its buffer, it deletes that window if there are other windows left on its frame. Otherwise, if the selected window is the only window on its frame, it iconifies that frame. If BUFFER-OR-NAME is displayed in some other window, it remains displayed there. To replace a buffer in all the windows that display it, use `replace-buffer-in-windows'. *Note Buffers and Windows::. -- Command: unbury-buffer This command switches to the last buffer in the local buffer list of the selected frame. More precisely, it calls the function `switch-to-buffer' (*note Displaying Buffers::), to display the buffer returned by `last-buffer', see above, in the selected window.  File: elisp, Node: Creating Buffers, Next: Killing Buffers, Prev: The Buffer List, Up: Buffers 27.9 Creating Buffers ===================== This section describes the two primitives for creating buffers. `get-buffer-create' creates a buffer if it finds no existing buffer with the specified name; `generate-new-buffer' always creates a new buffer and gives it a unique name. Other functions you can use to create buffers include `with-output-to-temp-buffer' (*note Temporary Displays::) and `create-file-buffer' (*note Visiting Files::). Starting a subprocess can also create a buffer (*note Processes::). -- Function: get-buffer-create buffer-or-name This function returns a buffer named BUFFER-OR-NAME. The buffer returned does not become the current buffer--this function does not change which buffer is current. BUFFER-OR-NAME must be either a string or an existing buffer. If it is a string and a live buffer with that name already exists, `get-buffer-create' returns that buffer. If no such buffer exists, it creates a new buffer. If BUFFER-OR-NAME is a buffer instead of a string, it is returned as given, even if it is dead. (get-buffer-create "foo") => # The major mode for a newly created buffer is set to Fundamental mode. (The default value of the variable `major-mode' is handled at a higher level; see *note Auto Major Mode::.) If the name begins with a space, the buffer initially disables undo information recording (*note Undo::). -- Function: generate-new-buffer name This function returns a newly created, empty buffer, but does not make it current. If there is no buffer named NAME, then that is the name of the new buffer. If that name is in use, this function adds suffixes of the form `' to NAME, where N is an integer. It tries successive integers starting with 2 until it finds an available name. An error is signaled if NAME is not a string. (generate-new-buffer "bar") => # (generate-new-buffer "bar") => #> (generate-new-buffer "bar") => #> The major mode for the new buffer is set to Fundamental mode. The default value of the variable `major-mode' is handled at a higher level. *Note Auto Major Mode::. See the related function `generate-new-buffer-name' in *note Buffer Names::.  File: elisp, Node: Killing Buffers, Next: Indirect Buffers, Prev: Creating Buffers, Up: Buffers 27.10 Killing Buffers ===================== "Killing a buffer" makes its name unknown to Emacs and makes the memory space it occupied available for other use. The buffer object for the buffer that has been killed remains in existence as long as anything refers to it, but it is specially marked so that you cannot make it current or display it. Killed buffers retain their identity, however; if you kill two distinct buffers, they remain distinct according to `eq' although both are dead. If you kill a buffer that is current or displayed in a window, Emacs automatically selects or displays some other buffer instead. This means that killing a buffer can in general change the current buffer. Therefore, when you kill a buffer, you should also take the precautions associated with changing the current buffer (unless you happen to know that the buffer being killed isn't current). *Note Current Buffer::. If you kill a buffer that is the base buffer of one or more indirect buffers, the indirect buffers are automatically killed as well. The `buffer-name' of a killed buffer is `nil'. You can use this feature to test whether a buffer has been killed: (defun buffer-killed-p (buffer) "Return t if BUFFER is killed." (not (buffer-name buffer))) -- Command: kill-buffer &optional buffer-or-name This function kills the buffer BUFFER-OR-NAME, freeing all its memory for other uses or to be returned to the operating system. If BUFFER-OR-NAME is `nil' or omitted, it kills the current buffer. Any processes that have this buffer as the `process-buffer' are sent the `SIGHUP' signal, which normally causes them to terminate. (The basic meaning of `SIGHUP' is that a dialup line has been disconnected.) *Note Signals to Processes::. If the buffer is visiting a file and contains unsaved changes, `kill-buffer' asks the user to confirm before the buffer is killed. It does this even if not called interactively. To prevent the request for confirmation, clear the modified flag before calling `kill-buffer'. *Note Buffer Modification::. This function calls `replace-buffer-in-windows' for cleaning up all windows currently displaying the buffer to be killed. Killing a buffer that is already dead has no effect. This function returns `t' if it actually killed the buffer. It returns `nil' if the user refuses to confirm or if BUFFER-OR-NAME was already dead. (kill-buffer "foo.unchanged") => t (kill-buffer "foo.changed") ---------- Buffer: Minibuffer ---------- Buffer foo.changed modified; kill anyway? (yes or no) yes ---------- Buffer: Minibuffer ---------- => t -- Variable: kill-buffer-query-functions After confirming unsaved changes, `kill-buffer' calls the functions in the list `kill-buffer-query-functions', in order of appearance, with no arguments. The buffer being killed is the current buffer when they are called. The idea of this feature is that these functions will ask for confirmation from the user. If any of them returns `nil', `kill-buffer' spares the buffer's life. -- Variable: kill-buffer-hook This is a normal hook run by `kill-buffer' after asking all the questions it is going to ask, just before actually killing the buffer. The buffer to be killed is current when the hook functions run. *Note Hooks::. This variable is a permanent local, so its local binding is not cleared by changing major modes. -- User Option: buffer-offer-save This variable, if non-`nil' in a particular buffer, tells `save-buffers-kill-emacs' and `save-some-buffers' (if the second optional argument to that function is `t') to offer to save that buffer, just as they offer to save file-visiting buffers. *Note Definition of save-some-buffers::. The variable `buffer-offer-save' automatically becomes buffer-local when set for any reason. *Note Buffer-Local Variables::. -- Variable: buffer-save-without-query This variable, if non-`nil' in a particular buffer, tells `save-buffers-kill-emacs' and `save-some-buffers' to save this buffer (if it's modified) without asking the user. The variable automatically becomes buffer-local when set for any reason. -- Function: buffer-live-p object This function returns `t' if OBJECT is a buffer which has not been killed, `nil' otherwise.  File: elisp, Node: Indirect Buffers, Next: Swapping Text, Prev: Killing Buffers, Up: Buffers 27.11 Indirect Buffers ====================== An "indirect buffer" shares the text of some other buffer, which is called the "base buffer" of the indirect buffer. In some ways it is the analogue, for buffers, of a symbolic link among files. The base buffer may not itself be an indirect buffer. The text of the indirect buffer is always identical to the text of its base buffer; changes made by editing either one are visible immediately in the other. This includes the text properties as well as the characters themselves. In all other respects, the indirect buffer and its base buffer are completely separate. They have different names, independent values of point, independent narrowing, independent markers and overlays (though inserting or deleting text in either buffer relocates the markers and overlays for both), independent major modes, and independent buffer-local variable bindings. An indirect buffer cannot visit a file, but its base buffer can. If you try to save the indirect buffer, that actually saves the base buffer. Killing an indirect buffer has no effect on its base buffer. Killing the base buffer effectively kills the indirect buffer in that it cannot ever again be the current buffer. -- Command: make-indirect-buffer base-buffer name &optional clone This creates and returns an indirect buffer named NAME whose base buffer is BASE-BUFFER. The argument BASE-BUFFER may be a live buffer or the name (a string) of an existing buffer. If NAME is the name of an existing buffer, an error is signaled. If CLONE is non-`nil', then the indirect buffer originally shares the "state" of BASE-BUFFER such as major mode, minor modes, buffer local variables and so on. If CLONE is omitted or `nil' the indirect buffer's state is set to the default state for new buffers. If BASE-BUFFER is an indirect buffer, its base buffer is used as the base for the new buffer. If, in addition, CLONE is non-`nil', the initial state is copied from the actual base buffer, not from BASE-BUFFER. -- Command: clone-indirect-buffer newname display-flag &optional norecord This function creates and returns a new indirect buffer that shares the current buffer's base buffer and copies the rest of the current buffer's attributes. (If the current buffer is not indirect, it is used as the base buffer.) If DISPLAY-FLAG is non-`nil', that means to display the new buffer by calling `pop-to-buffer'. If NORECORD is non-`nil', that means not to put the new buffer to the front of the buffer list. -- Function: buffer-base-buffer &optional buffer This function returns the base buffer of BUFFER, which defaults to the current buffer. If BUFFER is not indirect, the value is `nil'. Otherwise, the value is another buffer, which is never an indirect buffer.  File: elisp, Node: Swapping Text, Next: Buffer Gap, Prev: Indirect Buffers, Up: Buffers 27.12 Swapping Text Between Two Buffers ======================================= Specialized modes sometimes need to let the user access from the same buffer several vastly different types of text. For example, you may need to display a summary of the buffer text, in addition to letting the user access the text itself. This could be implemented with multiple buffers (kept in sync when the user edits the text), or with narrowing (*note Narrowing::). But these alternatives might sometimes become tedious or prohibitively expensive, especially if each type of text requires expensive buffer-global operations in order to provide correct display and editing commands. Emacs provides another facility for such modes: you can quickly swap buffer text between two buffers with `buffer-swap-text'. This function is very fast because it doesn't move any text, it only changes the internal data structures of the buffer object to point to a different chunk of text. Using it, you can pretend that a group of two or more buffers are actually a single virtual buffer that holds the contents of all the individual buffers together. -- Function: buffer-swap-text buffer This function swaps the text of the current buffer and that of its argument BUFFER. It signals an error if one of the two buffers is an indirect buffer (*note Indirect Buffers::) or is a base buffer of an indirect buffer. All the buffer properties that are related to the buffer text are swapped as well: the positions of point and mark, all the markers, the overlays, the text properties, the undo list, the value of the `enable-multibyte-characters' flag (*note enable-multibyte-characters: Text Representations.), etc. If you use `buffer-swap-text' on a file-visiting buffer, you should set up a hook to save the buffer's original text rather than what it was swapped with. `write-region-annotate-functions' works for this purpose. You should probably set `buffer-saved-size' to -2 in the buffer, so that changes in the text it is swapped with will not interfere with auto-saving.  File: elisp, Node: Buffer Gap, Prev: Swapping Text, Up: Buffers 27.13 The Buffer Gap ==================== Emacs buffers are implemented using an invisible "gap" to make insertion and deletion faster. Insertion works by filling in part of the gap, and deletion adds to the gap. Of course, this means that the gap must first be moved to the locus of the insertion or deletion. Emacs moves the gap only when you try to insert or delete. This is why your first editing command in one part of a large buffer, after previously editing in another far-away part, sometimes involves a noticeable delay. This mechanism works invisibly, and Lisp code should never be affected by the gap's current location, but these functions are available for getting information about the gap status. -- Function: gap-position This function returns the current gap position in the current buffer. -- Function: gap-size This function returns the current gap size of the current buffer.  File: elisp, Node: Windows, Next: Frames, Prev: Buffers, Up: Top 28 Windows ********** This chapter describes most of the functions and variables related to Emacs windows. *Note Frames and Windows::, for how windows relate to frames. *Note Display::, for information on how text is displayed in windows. * Menu: * Basic Windows:: Basic information on using windows. * Splitting Windows:: Splitting one window into two windows. * Deleting Windows:: Deleting a window gives its space to other windows. * Selecting Windows:: The selected window is the one that you edit in. * Cyclic Window Ordering:: Moving around the existing windows. * Buffers and Windows:: Each window displays the contents of a buffer. * Displaying Buffers:: Higher-level functions for displaying a buffer and choosing a window for it. * Choosing Window:: How to choose a window for displaying a buffer. * Dedicated Windows:: How to avoid displaying another buffer in a specific window. * Window Point:: Each window has its own location of point. * Window Start and End:: Buffer positions indicating which text is on-screen in a window. * Textual Scrolling:: Moving text up and down through the window. * Vertical Scrolling:: Moving the contents up and down on the window. * Horizontal Scrolling:: Moving the contents sideways on the window. * Size of Window:: Accessing the size of a window. * Resizing Windows:: Changing the size of a window. * Coordinates and Windows:: Converting coordinates to windows. * Window Tree:: The layout and sizes of all windows in a frame. * Window Configurations:: Saving and restoring the state of the screen. * Window Parameters:: Associating additional information with windows. * Window Hooks:: Hooks for scrolling, window size changes, redisplay going past a certain point, or window configuration changes.  File: elisp, Node: Basic Windows, Next: Splitting Windows, Up: Windows 28.1 Basic Concepts of Emacs Windows ==================================== A "window" in Emacs is the physical area of the screen in which a buffer is displayed. The term is also used to refer to a Lisp object that represents that screen area in Emacs Lisp. It should be clear from the context which is meant. Emacs groups windows into frames; see *note Frames::. A frame represents an area of screen available for Emacs to use. Each frame always contains at least one window, but you can subdivide it vertically or horizontally into multiple, nonoverlapping Emacs windows. In each frame, at any time, one and only one window is designated as "selected within the frame". The frame's cursor appears in that window, but the other windows have "non-selected" cursors, normally less visible. (*Note Cursor Parameters::, for customizing this.) At any time, one frame is the selected frame; and the window selected within that frame is "the selected window". The selected window's buffer is usually the current buffer (except when `set-buffer' has been used); see *note Current Buffer::. For practical purposes, a window exists only while it is displayed in a frame. Once removed from the frame, the window is effectively deleted and should not be used, _even though there may still be references to it_ from other Lisp objects; see *note Deleting Windows::. Restoring a saved window configuration is the only way for a window no longer on the screen to come back to life; see *note Window Configurations::. Users create multiple windows so they can look at several buffers at once. Lisp libraries use multiple windows for a variety of reasons, but most often to display related information. In Rmail, for example, you can move through a summary buffer in one window while the other window shows messages one at a time as they are reached. The meaning of "window" in Emacs is similar to what it means in the context of general-purpose window systems such as X, but not identical. The X Window System places X windows on the screen; Emacs uses one or more X windows as frames, and subdivides them into Emacs windows. When you use Emacs on a character-only terminal, Emacs treats the whole terminal screen as one frame. Most window systems support arbitrarily located overlapping windows. In contrast, Emacs windows are "tiled"; they never overlap, and together they fill the whole screen or frame. Because of the way in which Emacs creates new windows (*note Splitting Windows::) and resizes them (*note Resizing Windows::), not all conceivable tilings of windows on an Emacs frame are actually possible. -- Function: windowp object This function returns `t' if OBJECT is a window.  File: elisp, Node: Splitting Windows, Next: Deleting Windows, Prev: Basic Windows, Up: Windows 28.2 Splitting Windows ====================== The functions described below are the primitives used to split a window into two windows. They do not accept a buffer as an argument. Rather, the two "halves" of the split window initially display the same buffer previously visible in the window that was split. -- Command: split-window &optional window size horizontal This function splits a new window out of WINDOW's screen area. It returns the new window. The default for WINDOW is the selected window. When you split the selected window, it remains selected. If HORIZONTAL is non-`nil', then WINDOW splits into two side by side windows. The original window keeps the leftmost SIZE columns, and gives the rest of the columns to the new window. Otherwise, WINDOW splits into windows one above the other, the original window keeps the upper SIZE lines and gives the rest of the lines to the new window. The original window WINDOW is therefore the left-hand or upper of the two, and the new window is the right-hand or lower. If SIZE is omitted or `nil', then WINDOW is divided evenly into two parts. (If there is an odd line, it is allocated to the new window.) When `split-window' is called interactively, all its arguments are `nil'. If splitting would result in making a window that is smaller than `window-min-height' or `window-min-width' (*note Resizing Windows::), `split-window' signals an error and does not split the window at all. The following example starts with one window on a screen that is 50 lines high by 80 columns wide; then it splits the window. (setq w (selected-window)) => # (window-edges) ; Edges in order: => (0 0 80 50) ; left-top-right-bottom ;; Returns window created (setq w2 (split-window w 15)) => # (window-edges w2) => (0 15 80 50) ; Bottom window; ; top is line 15 (window-edges w) => (0 0 80 15) ; Top window The screen looks like this: __________ | | line 0 | w | |__________| | | line 15 | w2 | |__________| line 50 column 0 column 80 Next, split the top window horizontally: (setq w3 (split-window w 35 t)) => # (window-edges w3) => (35 0 80 15) ; Left edge at column 35 (window-edges w) => (0 0 35 15) ; Right edge at column 35 (window-edges w2) => (0 15 80 50) ; Bottom window unchanged Now the screen looks like this: column 35 __________ | | | line 0 | w | w3 | |___|______| | | line 15 | w2 | |__________| line 50 column 0 column 80 Normally, Emacs indicates the border between two side-by-side windows with a scroll bar (*note Scroll Bars::), or with `|' characters. The display table can specify alternative border characters; see *note Display Tables::. -- Command: split-window-vertically &optional size This function splits the selected window into two windows, one above the other, leaving the upper of the two windows selected, with SIZE lines. (If SIZE is negative, then the lower of the two windows gets -SIZE lines and the upper window gets the rest, but the upper window is still the one selected.) However, if `split-window-keep-point' (see below) is `nil', then either window can be selected. In other respects, this function is similar to `split-window'. In particular, the upper window is the original one and the return value is the new, lower window. -- User Option: split-window-keep-point If this variable is non-`nil' (the default), then `split-window-vertically' behaves as described above. If it is `nil', then `split-window-vertically' adjusts point in each of the two windows to avoid scrolling. (This is useful on slow terminals.) It selects whichever window contains the screen line that point was previously on. This variable affects the behavior of `split-window-vertically' only. It has no effect on the other functions described here. -- Command: split-window-horizontally &optional size This function splits the selected window into two windows side-by-side, leaving the selected window on the left with SIZE columns. If SIZE is negative, the rightmost window gets -SIZE columns, but the leftmost window still remains selected. This function is basically an interface to `split-window'. You could define a simplified version of the function like this: (defun split-window-horizontally (&optional arg) "Split selected window into two windows, side by side..." (interactive "P") (let ((size (and arg (prefix-numeric-value arg)))) (and size (< size 0) (setq size (+ (window-width) size))) (split-window nil size t))) -- Function: one-window-p &optional no-mini all-frames This function returns non-`nil' if there is only one window. The argument NO-MINI, if non-`nil', means don't count the minibuffer even if it is active; otherwise, the minibuffer window is counted when it is active. The argument ALL-FRAMES specifies which frames to consider. Here are the possible values and their meanings: `nil' Count the windows in the selected frame, plus the minibuffer used by that frame even if it lies in some other frame. `t' Count all windows in all existing frames. `visible' Count all windows in all visible frames. 0 Count all windows in all visible or iconified frames. anything else Count precisely the windows in the selected frame, and no others.  File: elisp, Node: Deleting Windows, Next: Selecting Windows, Prev: Splitting Windows, Up: Windows 28.3 Deleting Windows ===================== A window remains visible on its frame unless you "delete" it by calling certain functions that delete windows. A deleted window cannot appear on the screen, but continues to exist as a Lisp object until there are no references to it. There is no way to cancel the deletion of a window aside from restoring a saved window configuration (*note Window Configurations::). Restoring a window configuration also deletes any windows that aren't part of that configuration. When you delete a window, the space it took up is given to one of its sibling windows adjacent to it. -- Function: window-live-p window This function returns `nil' if WINDOW is deleted, and `t' otherwise. *Warning:* Erroneous information or fatal errors may result from using a deleted window as if it were live. -- Command: delete-window &optional window This function removes WINDOW from display and returns `nil'. The default for WINDOW is the selected window. An error is signaled if WINDOW is the only window on its frame. -- Command: delete-other-windows &optional window This function makes WINDOW the only window on its frame, by deleting the other windows in that frame. The default for WINDOW is the selected window. The return value is `nil'. -- Command: delete-windows-on &optional buffer-or-name frame This function deletes all windows showing BUFFER-OR-NAME. If there are no windows showing BUFFER-OR-NAME, it does nothing. The optional argument BUFFER-OR-NAME may be a buffer or the name of an existing buffer and defaults to the current buffer. `delete-windows-on' operates frame by frame. If a frame has several windows showing different buffers, then those showing BUFFER-OR-NAME are removed, and the others expand to fill the space. If all windows in some frame are showing BUFFER-OR-NAME (including the case where there is only one window), then the frame winds up with a single window showing another buffer chosen with `other-buffer' (*note The Buffer List::). If, however, the window showing BUFFER-OR-NAME is dedicated to its buffer (*note Dedicated Windows::), and there are other frames left, that window's frame is deleted. The optional argument FRAME specifies which frames to operate on. This function does not use it in quite the same way as the other functions which scan all windows; specifically, the values `t' and `nil' have the opposite of their meanings in other functions. Here are the full details: * If it is `nil', operate on all frames. * If it is `t', operate on the selected frame. * If it is `visible', operate on all visible frames. * If it is 0, operate on all visible or iconified frames. * If it is a frame, operate on that frame. This function always returns `nil'.  File: elisp, Node: Selecting Windows, Next: Cyclic Window Ordering, Prev: Deleting Windows, Up: Windows 28.4 Selecting Windows ====================== When a window is selected, the buffer in the window becomes the current buffer, and the cursor will appear in it. -- Function: selected-window This function returns the selected window. This is the window in which the cursor appears and to which many commands apply. -- Function: select-window window &optional norecord This function makes WINDOW the selected window. The cursor then appears in WINDOW (after redisplay). Unless WINDOW was already selected, `select-window' makes WINDOW's buffer the current buffer. The return value is WINDOW. Normally, WINDOW's selected buffer is moved to the front of the buffer list (*note The Buffer List::) and WINDOW becomes the most recently selected window. But if NORECORD is non-`nil', the buffer list remains unchanged and WINDOW does not become the most recently selected one. (setq w (next-window)) (select-window w) => # -- Macro: save-selected-window forms... This macro records the selected frame, as well as the selected window of each frame, executes FORMS in sequence, then restores the earlier selected frame and windows. It also saves and restores the current buffer. It returns the value of the last form in FORMS. This macro does not save or restore anything about the sizes, arrangement or contents of windows; therefore, if FORMS change them, the change persists. If the previously selected window of some frame is no longer live at the time of exit from FORMS, that frame's selected window is left alone. If the previously selected window is no longer live, then whatever window is selected at the end of FORMS remains selected. The current buffer is restored if and only if it is still live when exiting FORMS. This macro changes neither the ordering of recently selected windows nor the buffer list. -- Macro: with-selected-window window forms... This macro selects WINDOW, executes FORMS in sequence, then restores the previously selected window and current buffer. The ordering of recently selected windows and the buffer list remain unchanged unless you deliberately change them within FORMS, for example, by calling `select-window' with argument NORECORD `nil'. The following functions choose one of the windows on the screen, offering various criteria for the choice. -- Function: get-lru-window &optional frame dedicated This function returns the window least recently "used" (that is, selected) among a set of candidate windows. If any full-width windows are present, it only considers these. The selected window is returned if it is the only candidate. A minibuffer window is never a candidate. A dedicated window (*note Dedicated Windows::) is never a candidate unless the optional argument DEDICATED is non-`nil'. The optional argument FRAME specifies which windows are considered. * If it is `nil', consider windows on the selected frame. * If it is `t', consider windows on all frames. * If it is `visible', consider windows on all visible frames. * If it is 0, consider windows on all visible or iconified frames. * If it is a frame, consider windows on that frame. -- Function: get-largest-window &optional frame dedicated This function returns the window with the largest area (height times width). If there are no side-by-side windows, then this is the window with the most lines. A minibuffer window is never a candidate. A dedicated window (*note Dedicated Windows::) is never a candidate unless the optional argument DEDICATED is non-`nil'. If there are two candidate windows of the same size, this function prefers the one that comes first in the cyclic ordering of windows, starting from the selected window (*note Cyclic Window Ordering::). The optional argument FRAME specifies which set of windows to consider, see `get-lru-window' above. -- Function: get-window-with-predicate predicate &optional minibuf all-frames default This function returns a window satisfying PREDICATE. It cycles through all visible windows using `walk-windows' (*note Cyclic Window Ordering::), calling PREDICATE on each one of them with that window as its argument. The function returns the first window for which PREDICATE returns a non-`nil' value; if that never happens, it returns DEFAULT (which defaults to `nil'). The optional arguments MINIBUF and ALL-FRAMES specify the set of windows to include in the scan. See the description of `next-window' in *note Cyclic Window Ordering::, for details.  File: elisp, Node: Cyclic Window Ordering, Next: Buffers and Windows, Prev: Selecting Windows, Up: Windows 28.5 Cyclic Ordering of Windows =============================== When you use the command `C-x o' (`other-window') to select some other window, it moves through the windows on the screen in a specific order. For any given configuration of windows, this order never varies. It is called the "cyclic ordering of windows". For a particular frame, this ordering generally goes from top to bottom, and from left to right. But it may go down first or go right first, depending on the order in which windows were split. If the first split was vertical (into windows one above each other), and then the subwindows were split horizontally, then the ordering is left to right in the top of the frame, and then left to right in the next lower part of the frame, and so on. If the first split was horizontal, the ordering is top to bottom in the left part, and so on. In general, within each set of siblings at any level in the window tree (*note Window Tree::), the order is left to right, or top to bottom. -- Function: next-window &optional window minibuf all-frames This function returns the window following WINDOW in the cyclic ordering of windows. This is the window `C-x o' selects if typed when WINDOW is selected. The default for WINDOW is the selected window. The value of the optional argument MINIBUF specifies whether the minibuffer is included in the window order. Normally, when MINIBUF is `nil', the minibuffer is included only if it is currently "active"; this matches the behavior of `C-x o'. (The minibuffer window is active while the minibuffer is in use; see *note Minibuffers::.) If MINIBUF is `t', the cyclic ordering includes the minibuffer window even if it is not active. If MINIBUF is neither `t' nor `nil', the minibuffer window is not included even if it is active. The optional argument ALL-FRAMES specifies which frames to consider. Here are the possible values and their meanings: `nil' Consider all the windows in WINDOW's frame, plus the minibuffer used by that frame even if it lies in some other frame. If the minibuffer counts (as determined by MINIBUF), then all windows on all frames that share that minibuffer count too. `t' Consider all windows in all existing frames. `visible' Consider all windows in all visible frames. (To get useful results, you must ensure WINDOW is in a visible frame.) 0 Consider all windows in all visible or iconified frames. a frame Consider all windows on that frame. anything else Consider precisely the windows in WINDOW's frame, and no others. This example assumes there are two windows, both displaying the buffer `windows.texi': (selected-window) => # (next-window (selected-window)) => # (next-window (next-window (selected-window))) => # -- Function: previous-window &optional window minibuf all-frames This function returns the window preceding WINDOW in the cyclic ordering of windows. The other arguments specify which windows to include in the cycle, as in `next-window'. -- Command: other-window count &optional all-frames This function selects another window in the cyclic ordering of windows. COUNT specifies the number of windows to skip in the ordering, starting with the selected window, before making the selection. If COUNT is a positive number, it skips COUNT windows forwards. COUNT negative means skip -COUNT windows backwards. If COUNT is zero, it does not skip any window, thus re-selecting the selected window. In an interactive call, COUNT is the numeric prefix argument. The optional argument ALL-FRAMES has the same meaning as in `next-window', but the MINIBUF argument of `next-window' is always effectively `nil'. This function returns `nil'. -- Function: walk-windows proc &optional minibuf all-frames This function cycles through all windows. It calls the function `proc' once for each window, with the window as its sole argument. The optional arguments MINIBUF and ALL-FRAMES specify the set of windows to include in the walk. See `next-window', above, for details. -- Function: window-list &optional frame minibuf window This function returns a list of all windows on FRAME, starting with WINDOW. The default for FRAME is the selected frame; the default for WINDOW is the selected window. The value of MINIBUF specifies if the minibuffer window shall be included in the result list. If MINIBUF is `t', the result always includes the minibuffer window. If MINIBUF is `nil' or omitted, that includes the minibuffer window if it is active. If MINIBUF is neither `nil' nor `t', the result never includes the minibuffer window.  File: elisp, Node: Buffers and Windows, Next: Displaying Buffers, Prev: Cyclic Window Ordering, Up: Windows 28.6 Buffers and Windows ======================== This section describes low-level functions to examine windows or to display buffers in windows in a precisely controlled fashion. *Note Displaying Buffers::, for related functions that find a window to use and specify a buffer for it. The functions described there are easier to use, but they employ heuristics in choosing or creating a window; use the functions described here when you need complete control. -- Function: set-window-buffer window buffer-or-name &optional keep-margins This function makes WINDOW display BUFFER-OR-NAME as its contents. It returns `nil'. The default for WINDOW is the selected window. The argument BUFFER-OR-NAME must specify a buffer or the name of an existing buffer. `set-window-buffer' is the fundamental primitive for changing which buffer is displayed in a window, and all ways of doing that call this function. (set-window-buffer (selected-window) "foo") => nil Normally, displaying BUFFER-OR-NAME in WINDOW resets the window's position, display margins, fringe widths, and scroll bar settings based on the local variables of that buffer. However, if KEEP-MARGINS is non-`nil', display margins and fringe widths of WINDOW remain unchanged. *Note Fringes::. `set-window-buffer' signals an error when WINDOW is "strongly" dedicated to its buffer (*note Dedicated Windows::) and does not already display BUFFER-OR-NAME. Note that this function runs `window-scroll-functions' before running `window-configuration-change-hook'. -- Variable: buffer-display-count This buffer-local variable records the number of times a buffer has been displayed in a window. It is incremented each time `set-window-buffer' is called for the buffer. -- Function: window-buffer &optional window This function returns the buffer that WINDOW is displaying. The default for WINDOW is the selected window. (window-buffer) => # -- Function: get-buffer-window &optional buffer-or-name all-frames This function returns a window currently displaying BUFFER-OR-NAME, or `nil' if there is none. If there are several such windows, then the function returns the first one in the cyclic ordering of windows, starting from the selected window. *Note Cyclic Window Ordering::. The argument BUFFER-OR-NAME may be a buffer or a buffer name and defaults to the current buffer. The optional argument ALL-FRAMES specifies which windows to consider: * `nil' means consider windows on the selected frame. * `t' means consider windows on all existing frames. * `visible' means consider windows on all visible frames. * 0 means consider windows on all visible or iconified frames. * A frame means consider windows on that frame only. Observe that the behavior of `get-buffer-window' may differ from that of `next-window' (*note Cyclic Window Ordering::) when ALL-FRAMES equals `nil' or any value not listed here. Perhaps we will change `get-buffer-window' in the future to make it compatible with the other functions. -- Function: get-buffer-window-list &optional buffer-or-name minibuf all-frames This function returns a list of all windows currently displaying BUFFER-OR-NAME. The argument BUFFER-OR-NAME may be a buffer or the name of an existing buffer and defaults to the current buffer. The two remaining arguments work like the same-named arguments of `next-window'; they are _not_ like the optional arguments of `get-buffer-window'. -- Variable: buffer-display-time This variable records the time at which a buffer was last made visible in a window. It is always local in each buffer; each time `set-window-buffer' is called, it sets this variable to `(current-time)' in the specified buffer (*note Time of Day::). When a buffer is first created, `buffer-display-time' starts out with the value `nil'.  File: elisp, Node: Displaying Buffers, Next: Choosing Window, Prev: Buffers and Windows, Up: Windows 28.7 Displaying Buffers in Windows ================================== In this section we describe convenient functions that choose a window automatically and use it to display a specified buffer. These functions can also split an existing window in certain circumstances. We also describe variables that parameterize the heuristics used for choosing a window. *Note Buffers and Windows::, for low-level primitives that give you more precise control. All of these functions work by calling `set-window-buffer'. Do not use the functions in this section in order to make a buffer current so that a Lisp program can access or modify it; they are too drastic for that purpose, since they change the display of buffers in windows, which would be gratuitous and surprise the user. Instead, use `set-buffer' and `save-current-buffer' (*note Current Buffer::), which designate buffers as current for programmed access without affecting the display of buffers in windows. -- Command: switch-to-buffer buffer-or-name &optional norecord This function makes BUFFER-OR-NAME the current buffer, and also displays the buffer in the selected window. This means that a human can see the buffer and subsequent keyboard commands will apply to it. Contrast this with `set-buffer', which makes BUFFER-OR-NAME the current buffer but does not display it in the selected window; see *note Current Buffer::. If BUFFER-OR-NAME is `nil', `switch-to-buffer' chooses a buffer using `other-buffer'. If BUFFER-OR-NAME is a string that does not identify an existing buffer, then a new buffer by that name is created. The major mode for the new buffer is set according to the variable `major-mode'; see *note Auto Major Mode::. When the selected window is the minibuffer window or is strongly dedicated to its buffer (*note Dedicated Windows::), this function calls `pop-to-buffer' (see below) to display the buffer in some other window. Normally the specified buffer is put at the front of the buffer list (both the selected frame's buffer list and the frame-independent buffer list). This affects the operation of `other-buffer'. However, if NORECORD is non-`nil', this is not done. *Note The Buffer List::. The `switch-to-buffer' function is often used interactively, as the binding of `C-x b'. It is also used frequently in programs. It returns the buffer that it switched to. The next two functions are similar to `switch-to-buffer', except for the described features. -- Command: switch-to-buffer-other-window buffer-or-name &optional norecord This function makes the buffer specified by BUFFER-OR-NAME current and displays it in a window not currently selected, using the function `pop-to-buffer' (see below). The currently selected window is absolutely never used to do the job. If the selected window already displays BUFFER-OR-NAME, then it continues to do so, but another window is nonetheless found to display it in as well. This function updates the buffer list just like `switch-to-buffer' unless NORECORD is non-`nil'. -- Command: pop-to-buffer buffer-or-name &optional other-window norecord This command makes BUFFER-OR-NAME the current buffer and switches to it in some window, preferably not the window previously selected. The "popped-to" window becomes the selected window. Its frame is given the X server's focus, if possible; see *note Input Focus::. The return value is the buffer that was switched to. If BUFFER-OR-NAME is `nil', that means to choose some other buffer, but you don't specify which. If BUFFER-OR-NAME is a string that does not name an existing buffer, a buffer by that name is created. The major mode for the new buffer is set according to the variable `major-mode'. *Note Auto Major Mode::. If either of the variables `display-buffer-reuse-frames' or `pop-up-frames' is non-`nil', `pop-to-buffer' looks for a window in any visible frame already displaying the buffer; if there is one, it selects and returns that window. If no such window exists and `pop-up-frames' is non-`nil', it creates a new frame and displays the buffer in it. Otherwise, `pop-to-buffer' operates entirely within the selected frame. (If the selected frame has just a minibuffer, `pop-to-buffer' operates within the most recently selected frame that was not just a minibuffer.) If the variable `pop-up-windows' is non-`nil', windows may be split to create a new window that is different from the original window. For details, see *note Choosing Window::. If OTHER-WINDOW is non-`nil', `pop-to-buffer' finds or creates another window even if BUFFER-OR-NAME is already visible in the selected window. Thus BUFFER-OR-NAME could end up displayed in two windows. On the other hand, if BUFFER-OR-NAME is already displayed in the selected window and OTHER-WINDOW is `nil', then the selected window is considered sufficient for displaying BUFFER-OR-NAME, so that nothing needs to be done. All the variables that affect `display-buffer' affect `pop-to-buffer' as well. *Note Choosing Window::. This function updates the buffer list just like `switch-to-buffer' unless NORECORD is non-`nil'. -- Command: replace-buffer-in-windows &optional buffer-or-name This function replaces BUFFER-OR-NAME in all windows displaying it with some other buffer. It uses `other-buffer' to choose the other buffer. In the usual applications of this function, you don't care which other buffer is used; you just want to make sure that BUFFER-OR-NAME is no longer displayed. The argument BUFFER-OR-NAME may be a buffer or the name of an existing buffer and defaults to the current buffer. If a window displaying BUFFER-OR-NAME is dedicated (*note Dedicated Windows::), and is not the only window on its frame, that window is deleted. If that window is the only window on its frame and there are other frames left, the window's frame is deleted too. If there are no other frames left, some other buffer is displayed in that window. This function returns `nil'.  File: elisp, Node: Choosing Window, Next: Dedicated Windows, Prev: Displaying Buffers, Up: Windows 28.8 Choosing a Window for Display ================================== This section describes the basic facility that chooses a window to display a buffer in--`display-buffer'. Higher-level functions and commands, like `switch-to-buffer' and `pop-to-buffer', use this subroutine. Here we describe how to use `display-buffer' and how to customize it. -- Command: display-buffer buffer-or-name &optional not-this-window frame This command makes BUFFER-OR-NAME appear in some window, but it does not select that window and does not make the buffer specified by BUFFER-OR-NAME current. The identity of the selected window is unaltered by this function. The argument BUFFER-OR-NAME must be a buffer or the name of an existing buffer. NOT-THIS-WINDOW non-`nil' means to display the specified buffer in a window other than the selected one, even if it is already displayed in the selected window. This can cause the buffer to appear in two windows at once. Otherwise, if BUFFER-OR-NAME is already being displayed in any window, that is good enough, so this function does nothing. `display-buffer' returns the window chosen to display BUFFER-OR-NAME. If the optional argument FRAME is non-`nil', it specifies which frames to check when deciding whether the buffer is already displayed. If the buffer is already displayed in some window on one of these frames, `display-buffer' simply returns that window. Here are the possible values of FRAME: * `nil' means consider windows on the selected frame. (Actually, the last non-minibuffer frame.) * `t' means consider windows on all frames. * `visible' means consider windows on all visible frames. * 0 means consider windows on all visible or iconified frames. * A frame means consider windows on that frame only. Precisely how `display-buffer' finds or creates a window depends on the variables described below. -- User Option: display-buffer-reuse-frames If this variable is non-`nil', `display-buffer' searches visible and iconified frames for a window displaying BUFFER-OR-NAME. If there is such a window, `display-buffer' makes that window's frame visible and raises it if necessary, and returns the window. If there is no such window or `display-buffer-reuse-frames' is `nil', the behavior of `display-buffer' is determined by the variables described next. -- User Option: pop-up-windows This variable specifies whether `display-buffer' is allowed to split (*note Splitting Windows::) an existing window. If this variable is non-`nil', `display-buffer' tries to split the largest or least recently used window on the selected frame. (If the selected frame is a minibuffer-only frame, `display-buffer' tries to split a window on another frame instead.) If this variable is `nil' or the variable `pop-up-frames' (see below) is non-`nil', `display-buffer' does not split any window. -- User Option: split-window-preferred-function This variable must specify a function with one argument, which is a window. The `display-buffer' routines will call this function with one or more candidate windows when they look for a window to split. The function is expected to split that window and return the new window. If the function returns `nil', this means that the argument window cannot (or shall not) be split. The default value of `split-window-preferred-function' is the function `split-window-sensibly' described below. If you customize this option, bear in mind that the `display-buffer' routines may call your function up to two times when trying to split a window. The argument of the first call is the largest window on the chosen frame (as returned by `get-largest-window'). If that call fails to return a live window, your function is called a second time with the least recently used window on that frame (as returned by `get-lru-window'). The function specified by this option may try to split any other window instead of the argument window. Note that the window selected at the time `display-buffer' was invoked is still selected when your function is called. Hence, you can split the selected window (instead of the largest or least recently used one) by simply ignoring the window argument in the body of your function. You can even choose to not split any window as long as the return value of your function specifies a live window or `nil', but you are not encouraged to do so unconditionally. If you want `display-buffer' to never split any windows, set `pop-up-windows' to `nil'. -- Function: split-window-sensibly window This function takes a window as argument and tries to split that window in a suitable way. The two variables described next are useful for tuning the behavior of this function. -- User Option: split-height-threshold This variable specifies whether `split-window-sensibly' may split windows vertically. If it is an integer, `split-window-sensibly' tries to vertically split a window only if it has at least this many lines. If the window has less lines, splitting fails, or the value of this variable is `nil', `split-window-sensibly' will try to split the window horizontally, subject to restrictions of `split-width-threshold' (see below). If splitting horizontally fails too and the window is the only window on its frame, `split-window-sensibly' will try to split the window vertically disregarding the value of `split-height-threshold'. If this fails as well, `split-window-sensibly' returns `nil'. `split-window-sensibly' does not split vertically a window whose height is fixed (*note Resizing Windows::). Also, it vertically splits a window only if the space taken up by that window can accommodate two windows one above the other that are both at least `window-min-height' lines tall. Moreover, if the window that shall be split has a mode line, `split-window-sensibly' does not split the window unless the new window can accomodate a mode line too. -- User Option: split-width-threshold This variable specifies whether `split-window-sensibly' may split windows horizontally. If it is an integer, `split-window-sensibly' tries to horizontally split a window only if it has at least this many columns. If it is `nil', `split-window-sensibly' will not split the window horizontally. (It still might split the window vertically, though, see above.) `split-window-sensibly' does not split horizontally a window if that window's width is fixed (*note Resizing Windows::). Also, it horizontally splits a window only if the space that window takes up can accommodate two windows side by side that are both at least `window-min-width' columns wide. -- User Option: even-window-heights This variable specifies whether `display-buffer' should even out window heights if the buffer gets displayed in an existing window, above or beneath another window. If `even-window-heights' is non-`nil', the default, window heights will be evened out. If either of the involved window has fixed height (*note Resizing Windows::) or `even-window-heights' is `nil', the original window heights will be left alone. -- User Option: pop-up-frames This variable specifies whether `display-buffer' should make new frames. If it is non-`nil', `display-buffer' looks for a window already displaying BUFFER-OR-NAME on any visible or iconified frame. If it finds such a window, it makes that window's frame visible and raises it if necessary, and returns the window. Otherwise it makes a new frame, unless the variable's value is `graphic-only' and the selected frame is not on a graphic display. *Note Frames::, for more information. Note that the value of `pop-up-windows' does not matter if `pop-up-frames' is non-`nil'. If `pop-up-frames' is `nil', then `display-buffer' either splits a window or reuses one. -- User Option: pop-up-frame-function This variable specifies how to make a new frame if `pop-up-frames' is non-`nil'. The value of this variable must be a function of no arguments. When `display-buffer' makes a new frame, it does so by calling that function, which should return a frame. The default value of this variable is a function that creates a frame using the parameters specified by `pop-up-frame-alist' described next. -- User Option: pop-up-frame-alist This variable holds an alist specifying frame parameters used by the default value of `pop-up-frame-function' for making new frames. *Note Frame Parameters::, for more information about frame parameters. -- User Option: special-display-buffer-names A list of buffer names identifying buffers that should be displayed specially. If the name of BUFFER-OR-NAME is in this list, `display-buffer' handles the buffer specially. By default, special display means to give the buffer a dedicated frame. If an element is a list, instead of a string, then the CAR of that list is the buffer name, and the rest of that list says how to create the frame. There are two possibilities for the rest of that list (its CDR): It can be an alist, specifying frame parameters, or it can contain a function and arguments to give to it. (The function's first argument is always the buffer to be displayed; the arguments from the list come after that.) For example: (("myfile" (minibuffer) (menu-bar-lines . 0))) specifies to display a buffer named `myfile' in a dedicated frame with specified `minibuffer' and `menu-bar-lines' parameters. The list of frame parameters can also use the phony frame parameters `same-frame' and `same-window'. If the specified frame parameters include `(same-window . VALUE)' and VALUE is non-`nil', that means to display the buffer in the current selected window. Otherwise, if they include `(same-frame . VALUE)' and VALUE is non-`nil', that means to display the buffer in a new window in the currently selected frame. -- User Option: special-display-regexps A list of regular expressions specifying buffers that should be displayed specially. If the buffer's name matches any of the regular expressions in this list, `display-buffer' handles the buffer specially. By default, special display means to give the buffer a dedicated frame. If an element is a list, instead of a string, then the CAR of the list is the regular expression, and the rest of the list says how to create the frame. See `special-display-buffer-names' above. -- Function: special-display-p buffer-name This function returns non-`nil' if displaying a buffer named BUFFER-NAME with `display-buffer' would create a special frame. The value is `t' if it would use the default frame parameters, or else the specified list of frame parameters. -- User Option: special-display-function This variable holds the function to call to display a buffer specially. It receives the buffer as an argument, and should return the window in which it is displayed. The default value of this variable is `special-display-popup-frame', see below. -- Function: special-display-popup-frame buffer &optional args This function tries to make BUFFER visible in a frame of its own. If BUFFER is already displayed in some window, it makes that window's frame visible and raises it. Otherwise, it creates a frame that is dedicated to BUFFER. The return value is the window used to display BUFFER. If ARGS is an alist, it specifies frame parameters for the new frame. If ARGS is a list whose CAR is a symbol, then `(car ARGS)' is called as a function to actually create and set up the frame; it is called with BUFFER as first argument, and `(cdr ARGS)' as additional arguments. This function always uses an existing window displaying BUFFER, whether or not it is in a frame of its own; but if you set up the above variables in your init file, before BUFFER was created, then presumably the window was previously made by this function. -- User Option: special-display-frame-alist This variable holds frame parameters for `special-display-popup-frame' to use when it creates a frame. -- User Option: same-window-buffer-names A list of buffer names for buffers that should be displayed in the selected window. If the buffer's name is in this list, `display-buffer' handles the buffer by switching to it in the selected window. -- User Option: same-window-regexps A list of regular expressions that specify buffers that should be displayed in the selected window. If the buffer's name matches any of the regular expressions in this list, `display-buffer' handles the buffer by switching to it in the selected window. -- Function: same-window-p buffer-name This function returns `t' if displaying a buffer named BUFFER-NAME with `display-buffer' would put it in the selected window. -- User Option: display-buffer-function This variable is the most flexible way to customize the behavior of `display-buffer'. If it is non-`nil', it should be a function that `display-buffer' calls to do the work. The function should accept two arguments, the first two arguments that `display-buffer' received. It should choose or create a window, display the specified buffer in it, and then return the window. This variable takes precedence over all the other options described above. If all options described above fail to produce a suitable window, `display-buffer' tries to reuse an existing window. As a last resort, it will try to display BUFFER-OR-NAME on a separate frame. In that case, the value of `pop-up-frames' is disregarded.  File: elisp, Node: Dedicated Windows, Next: Window Point, Prev: Choosing Window, Up: Windows 28.9 Dedicated Windows ====================== Functions for displaying a buffer can be told to not use specific windows by marking these windows as "dedicated" to their buffers. `display-buffer' (*note Choosing Window::) never uses a dedicated window for displaying another buffer in it. `get-lru-window' and `get-largest-window' (*note Selecting Windows::) do not consider dedicated windows as candidates when their DEDICATED argument is non-`nil'. The behavior of `set-window-buffer' (*note Buffers and Windows::) with respect to dedicated windows is slightly different, see below. When `delete-windows-on' (*note Deleting Windows::) wants to delete a dedicated window and that window is the only window on its frame, it deletes the window's frame too, provided there are other frames left. `replace-buffer-in-windows' (*note Displaying Buffers::) tries to delete all dedicated windows showing its buffer argument. When such a window is the only window on its frame, that frame is deleted, provided there are other frames left. If there are no more frames left, some other buffer is displayed in the window, and the window is marked as non-dedicated. When you kill a buffer (*note Killing Buffers::) displayed in a dedicated window, any such window usually gets deleted too, since `kill-buffer' calls `replace-buffer-in-windows' for cleaning up windows. Burying a buffer (*note The Buffer List::) deletes the selected window if it is dedicated to that buffer. If, however, that window is the only window on its frame, `bury-buffer' displays another buffer in it and iconifies the frame. -- Function: window-dedicated-p &optional window This function returns non-`nil' if WINDOW is dedicated to its buffer and `nil' otherwise. More precisely, the return value is the value assigned by the last call of `set-window-dedicated-p' for WINDOW or `nil' if that function was never called with WINDOW as its argument. The default for WINDOW is the selected window. -- Function: set-window-dedicated-p window flag This function marks WINDOW as dedicated to its buffer if FLAG is non-`nil', and non-dedicated otherwise. As a special case, if FLAG is `t', WINDOW becomes "strongly" dedicated to its buffer. `set-window-buffer' signals an error when the window it acts upon is strongly dedicated to its buffer and does not already display the buffer it is asked to display. Other functions do not treat `t' differently from any non-`nil' value.  File: elisp, Node: Window Point, Next: Window Start and End, Prev: Dedicated Windows, Up: Windows 28.10 Windows and Point ======================= Each window has its own value of point (*note Point::), independent of the value of point in other windows displaying the same buffer. This makes it useful to have multiple windows showing one buffer. * The window point is established when a window is first created; it is initialized from the buffer's point, or from the window point of another window opened on the buffer if such a window exists. * Selecting a window sets the value of point in its buffer from the window's value of point. Conversely, deselecting a window sets the window's value of point from that of the buffer. Thus, when you switch between windows that display a given buffer, the point value for the selected window is in effect in the buffer, while the point values for the other windows are stored in those windows. * As long as the selected window displays the current buffer, the window's point and the buffer's point always move together; they remain equal. As far as the user is concerned, point is where the cursor is, and when the user switches to another buffer, the cursor jumps to the position of point in that buffer. -- Function: window-point &optional window This function returns the current position of point in WINDOW. For a nonselected window, this is the value point would have (in that window's buffer) if that window were selected. The default for WINDOW is the selected window. When WINDOW is the selected window and its buffer is also the current buffer, the value returned is the same as point in that buffer. Strictly speaking, it would be more correct to return the "top-level" value of point, outside of any `save-excursion' forms. But that value is hard to find. -- Function: set-window-point window position This function positions point in WINDOW at position POSITION in WINDOW's buffer. It returns POSITION. If WINDOW is selected, and its buffer is current, this simply does `goto-char'. -- Variable: window-point-insertion-type This variable specifies the marker insertion type (*note Marker Insertion Types::) of `window-point'. The default is `nil', so `window-point' will stay behind text inserted there.  File: elisp, Node: Window Start and End, Next: Textual Scrolling, Prev: Window Point, Up: Windows 28.11 The Window Start and End Positions ======================================== Each window maintains a marker used to keep track of a buffer position that specifies where in the buffer display should start. This position is called the "display-start" position of the window (or just the "start"). The character after this position is the one that appears at the upper left corner of the window. It is usually, but not inevitably, at the beginning of a text line. After switching windows or buffers, and in some other cases, if the window start is in the middle of a line, Emacs adjusts the window start to the start of a line. This prevents certain operations from leaving the window start at a meaningless point within a line. This feature may interfere with testing some Lisp code by executing it using the commands of Lisp mode, because they trigger this readjustment. To test such code, put it into a command and bind the command to a key. -- Function: window-start &optional window This function returns the display-start position of window WINDOW. If WINDOW is `nil', the selected window is used. For example, (window-start) => 7058 When you create a window, or display a different buffer in it, the display-start position is set to a display-start position recently used for the same buffer, or to `point-min' if the buffer doesn't have any. Redisplay updates the window-start position (if you have not specified it explicitly since the previous redisplay)--to make sure point appears on the screen. Nothing except redisplay automatically changes the window-start position; if you move point, do not expect the window-start position to change in response until after the next redisplay. For a realistic example of using `window-start', see the description of `count-lines'. *Note Definition of count-lines::. -- Function: window-end &optional window update This function returns the position where display of its buffer ends in WINDOW. The default for WINDOW is the selected window. Simply changing the buffer text or moving point does not update the value that `window-end' returns. The value is updated only when Emacs redisplays and redisplay completes without being preempted. If the last redisplay of WINDOW was preempted, and did not finish, Emacs does not know the position of the end of display in that window. In that case, this function returns `nil'. If UPDATE is non-`nil', `window-end' always returns an up-to-date value for where display ends, based on the current `window-start' value. If a previously saved value of that position is still valid, `window-end' returns that value; otherwise it computes the correct value by scanning the buffer text. Even if UPDATE is non-`nil', `window-end' does not attempt to scroll the display if point has moved off the screen, the way real redisplay would do. It does not alter the `window-start' value. In effect, it reports where the displayed text will end if scrolling is not required. -- Function: set-window-start window position &optional noforce This function sets the display-start position of WINDOW to POSITION in WINDOW's buffer. It returns POSITION. The display routines insist that the position of point be visible when a buffer is displayed. Normally, they change the display-start position (that is, scroll the window) whenever necessary to make point visible. However, if you specify the start position with this function using `nil' for NOFORCE, it means you want display to start at POSITION even if that would put the location of point off the screen. If this does place point off screen, the display routines move point to the left margin on the middle line in the window. For example, if point is 1 and you set the start of the window to 37, the start of the next line, point will be "above" the top of the window. The display routines will automatically move point if it is still 1 when redisplay occurs. Here is an example: ;; Here is what `foo' looks like before executing ;; the `set-window-start' expression. ---------- Buffer: foo ---------- -!-This is the contents of buffer foo. 2 3 4 5 6 ---------- Buffer: foo ---------- (set-window-start (selected-window) (save-excursion (goto-char 1) (forward-line 1) (point))) => 37 ;; Here is what `foo' looks like after executing ;; the `set-window-start' expression. ---------- Buffer: foo ---------- 2 3 -!-4 5 6 ---------- Buffer: foo ---------- If NOFORCE is non-`nil', and POSITION would place point off screen at the next redisplay, then redisplay computes a new window-start position that works well with point, and thus POSITION is not used. -- Function: pos-visible-in-window-p &optional position window partially This function returns non-`nil' if POSITION is within the range of text currently visible on the screen in WINDOW. It returns `nil' if POSITION is scrolled vertically out of view. Locations that are partially obscured are not considered visible unless PARTIALLY is non-`nil'. The argument POSITION defaults to the current position of point in WINDOW; WINDOW, to the selected window. If POSITION is `t', that means to check the last visible position in WINDOW. The `pos-visible-in-window-p' function considers only vertical scrolling. If POSITION is out of view only because WINDOW has been scrolled horizontally, `pos-visible-in-window-p' returns non-`nil' anyway. *Note Horizontal Scrolling::. If POSITION is visible, `pos-visible-in-window-p' returns `t' if PARTIALLY is `nil'; if PARTIALLY is non-`nil', and the character following POSITION is fully visible, it returns a list of the form `(X Y)', where X and Y are the pixel coordinates relative to the top left corner of the window; otherwise it returns an extended list of the form `(X Y RTOP RBOT ROWH VPOS)', where RTOP and RBOT specify the number of off-window pixels at the top and bottom of the row at POSITION, ROWH specifies the visible height of that row, and VPOS specifies the vertical position (zero-based row number) of that row. Here is an example: ;; If point is off the screen now, recenter it now. (or (pos-visible-in-window-p (point) (selected-window)) (recenter 0)) -- Function: window-line-height &optional line window This function returns the height of text line LINE in WINDOW. If LINE is one of `header-line' or `mode-line', `window-line-height' returns information about the corresponding line of the window. Otherwise, LINE is a text line number starting from 0. A negative number counts from the end of the window. The default for LINE is the current line in WINDOW; the default for WINDOW is the selected window. If the display is not up to date, `window-line-height' returns `nil'. In that case, `pos-visible-in-window-p' may be used to obtain related information. If there is no line corresponding to the specified LINE, `window-line-height' returns `nil'. Otherwise, it returns a list `(HEIGHT VPOS YPOS OFFBOT)', where HEIGHT is the height in pixels of the visible part of the line, VPOS and YPOS are the vertical position in lines and pixels of the line relative to the top of the first text line, and OFFBOT is the number of off-window pixels at the bottom of the text line. If there are off-window pixels at the top of the (first) text line, YPOS is negative.  File: elisp, Node: Textual Scrolling, Next: Vertical Scrolling, Prev: Window Start and End, Up: Windows 28.12 Textual Scrolling ======================= "Textual scrolling" means moving the text up or down through a window. It works by changing the value of the window's display-start location. It may also change the value of `window-point' to keep point on the screen. Textual scrolling was formerly called "vertical scrolling," but we changed its name to distinguish it from the new vertical fractional scrolling feature (*note Vertical Scrolling::). In the commands `scroll-up' and `scroll-down', the directions "up" and "down" refer to the motion of the text in the buffer at which you are looking through the window. Imagine that the text is written on a long roll of paper and that the scrolling commands move the paper up and down. Thus, if you are looking at text in the middle of a buffer and repeatedly call `scroll-down', you will eventually see the beginning of the buffer. Some people have urged that the opposite convention be used: they imagine that the window moves over text that remains in place. Then "down" commands would take you to the end of the buffer. This view is more consistent with the actual relationship between windows and the text in the buffer, but it is less like what the user sees. The position of a window on the terminal does not move, and short scrolling commands clearly move the text up or down on the screen. We have chosen names that fit the user's point of view. The textual scrolling functions (aside from `scroll-other-window') have unpredictable results if the current buffer is different from the buffer that is displayed in the selected window. *Note Current Buffer::. If the window contains a row which is taller than the height of the window (for example in the presence of a large image), the scroll functions will adjust the window's vertical scroll position to scroll the partially visible row. To disable this feature, Lisp code may bind the variable `auto-window-vscroll' to `nil' (*note Vertical Scrolling::). -- Command: scroll-up &optional count This function scrolls the text in the selected window upward COUNT lines. If COUNT is negative, scrolling is actually downward. If COUNT is `nil' (or omitted), then the length of scroll is `next-screen-context-lines' lines less than the usable height of the window (not counting its mode line). `scroll-up' returns `nil', unless it gets an error because it can't scroll any further. -- Command: scroll-down &optional count This function scrolls the text in the selected window downward COUNT lines. If COUNT is negative, scrolling is actually upward. If COUNT is omitted or `nil', then the length of the scroll is `next-screen-context-lines' lines less than the usable height of the window (not counting its mode line). `scroll-down' returns `nil', unless it gets an error because it can't scroll any further. -- Command: scroll-other-window &optional count This function scrolls the text in another window upward COUNT lines. Negative values of COUNT, or `nil', are handled as in `scroll-up'. You can specify which buffer to scroll by setting the variable `other-window-scroll-buffer' to a buffer. If that buffer isn't already displayed, `scroll-other-window' displays it in some window. When the selected window is the minibuffer, the next window is normally the one at the top left corner. You can specify a different window to scroll, when the minibuffer is selected, by setting the variable `minibuffer-scroll-window'. This variable has no effect when any other window is selected. When it is non-`nil' and the minibuffer is selected, it takes precedence over `other-window-scroll-buffer'. *Note Definition of minibuffer-scroll-window::. When the minibuffer is active, it is the next window if the selected window is the one at the bottom right corner. In this case, `scroll-other-window' attempts to scroll the minibuffer. If the minibuffer contains just one line, it has nowhere to scroll to, so the line reappears after the echo area momentarily displays the message `Beginning of buffer'. -- Variable: other-window-scroll-buffer If this variable is non-`nil', it tells `scroll-other-window' which buffer's window to scroll. -- User Option: scroll-margin This option specifies the size of the scroll margin--a minimum number of lines between point and the top or bottom of a window. Whenever point gets within this many lines of the top or bottom of the window, redisplay scrolls the text automatically (if possible) to move point out of the margin, closer to the center of the window. -- User Option: scroll-conservatively This variable controls how scrolling is done automatically when point moves off the screen (or into the scroll margin). If the value is a positive integer N, then redisplay scrolls the text up to N lines in either direction, if that will bring point back into proper view. This behavior is called "conservative scrolling". Otherwise, scrolling happens in the usual way, under the control of other variables such as `scroll-up-aggressively' and `scroll-down-aggressively'. The default value is zero, which means that conservative scrolling never happens. -- User Option: scroll-down-aggressively The value of this variable should be either `nil' or a fraction F between 0 and 1. If it is a fraction, that specifies where on the screen to put point when scrolling down. More precisely, when a window scrolls down because point is above the window start, the new start position is chosen to put point F part of the window height from the top. The larger F, the more aggressive the scrolling. A value of `nil' is equivalent to .5, since its effect is to center point. This variable automatically becomes buffer-local when set in any fashion. -- User Option: scroll-up-aggressively Likewise, for scrolling up. The value, F, specifies how far point should be placed from the bottom of the window; thus, as with `scroll-up-aggressively', a larger value scrolls more aggressively. -- User Option: scroll-step This variable is an older variant of `scroll-conservatively'. The difference is that if its value is N, that permits scrolling only by precisely N lines, not a smaller number. This feature does not work with `scroll-margin'. The default value is zero. -- User Option: scroll-preserve-screen-position If this option is `t', scrolling which would move the current point position out of the window chooses the new position of point so that the vertical position of the cursor is unchanged, if possible. If it is non-`nil' and not `t', then the scrolling functions always preserve the vertical position of point, if possible. -- User Option: next-screen-context-lines The value of this variable is the number of lines of continuity to retain when scrolling by full screens. For example, `scroll-up' with an argument of `nil' scrolls so that this many lines at the bottom of the window appear instead at the top. The default value is `2'. -- Command: recenter &optional count This function scrolls the text in the selected window so that point is displayed at a specified vertical position within the window. It does not "move point" with respect to the text. If COUNT is a nonnegative number, that puts the line containing point COUNT lines down from the top of the window. If COUNT is a negative number, then it counts upward from the bottom of the window, so that -1 stands for the last usable line in the window. If COUNT is a non-`nil' list, then it stands for the line in the middle of the window. If COUNT is `nil', `recenter' puts the line containing point in the middle of the window, then clears and redisplays the entire selected frame. When `recenter' is called interactively, COUNT is the raw prefix argument. Thus, typing `C-u' as the prefix sets the COUNT to a non-`nil' list, while typing `C-u 4' sets COUNT to 4, which positions the current line four lines from the top. With an argument of zero, `recenter' positions the current line at the top of the window. This action is so handy that some people make a separate key binding to do this. For example, (defun line-to-top-of-window () "Scroll current line to top of window. Replaces three keystroke sequence C-u 0 C-l." (interactive) (recenter 0)) (global-set-key [kp-multiply] 'line-to-top-of-window)  File: elisp, Node: Vertical Scrolling, Next: Horizontal Scrolling, Prev: Textual Scrolling, Up: Windows 28.13 Vertical Fractional Scrolling =================================== "Vertical fractional scrolling" means shifting text in a window up or down by a specified multiple or fraction of a line. Each window has a "vertical scroll position", which is a number, never less than zero. It specifies how far to raise the contents of the window. Raising the window contents generally makes all or part of some lines disappear off the top, and all or part of some other lines appear at the bottom. The usual value is zero. The vertical scroll position is measured in units of the normal line height, which is the height of the default font. Thus, if the value is .5, that means the window contents are scrolled up half the normal line height. If it is 3.3, that means the window contents are scrolled up somewhat over three times the normal line height. What fraction of a line the vertical scrolling covers, or how many lines, depends on what the lines contain. A value of .5 could scroll a line whose height is very short off the screen, while a value of 3.3 could scroll just part of the way through a tall line or an image. -- Function: window-vscroll &optional window pixels-p This function returns the current vertical scroll position of WINDOW. The default for WINDOW is the selected window. If PIXELS-P is non-`nil', the return value is measured in pixels, rather than in units of the normal line height. (window-vscroll) => 0 -- Function: set-window-vscroll window lines &optional pixels-p This function sets WINDOW's vertical scroll position to LINES. If WINDOW is `nil', the selected window is used. The argument LINES should be zero or positive; if not, it is taken as zero. The actual vertical scroll position must always correspond to an integral number of pixels, so the value you specify is rounded accordingly. The return value is the result of this rounding. (set-window-vscroll (selected-window) 1.2) => 1.13 If PIXELS-P is non-`nil', LINES specifies a number of pixels. In this case, the return value is LINES. -- Variable: auto-window-vscroll If this variable is non-`nil', the line-move, scroll-up, and scroll-down functions will automatically modify the vertical scroll position to scroll through display rows that are taller than the height of the window, for example in the presence of large images.  File: elisp, Node: Horizontal Scrolling, Next: Size of Window, Prev: Vertical Scrolling, Up: Windows 28.14 Horizontal Scrolling ========================== "Horizontal scrolling" means shifting the image in the window left or right by a specified multiple of the normal character width. Each window has a "horizontal scroll position", which is a number, never less than zero. It specifies how far to shift the contents left. Shifting the window contents left generally makes all or part of some characters disappear off the left, and all or part of some other characters appear at the right. The usual value is zero. The horizontal scroll position is measured in units of the normal character width, which is the width of space in the default font. Thus, if the value is 5, that means the window contents are scrolled left by 5 times the normal character width. How many characters actually disappear off to the left depends on their width, and could vary from line to line. Because we read from side to side in the "inner loop," and from top to bottom in the "outer loop," the effect of horizontal scrolling is not like that of textual or vertical scrolling. Textual scrolling involves selection of a portion of text to display, and vertical scrolling moves the window contents contiguously; but horizontal scrolling causes part of _each line_ to go off screen. Usually, no horizontal scrolling is in effect; then the leftmost column is at the left edge of the window. In this state, scrolling to the right is meaningless, since there is no data to the left of the edge to be revealed by it; so this is not allowed. Scrolling to the left is allowed; it scrolls the first columns of text off the edge of the window and can reveal additional columns on the right that were truncated before. Once a window has a nonzero amount of leftward horizontal scrolling, you can scroll it back to the right, but only so far as to reduce the net horizontal scroll to zero. There is no limit to how far left you can scroll, but eventually all the text will disappear off the left edge. If `auto-hscroll-mode' is set, redisplay automatically alters the horizontal scrolling of a window as necessary to ensure that point is always visible. However, you can still set the horizontal scrolling value explicitly. The value you specify serves as a lower bound for automatic scrolling, i.e. automatic scrolling will not scroll a window to a column less than the specified one. -- Command: scroll-left &optional count set-minimum This function scrolls the selected window COUNT columns to the left (or to the right if COUNT is negative). The default for COUNT is the window width, minus 2. The return value is the total amount of leftward horizontal scrolling in effect after the change--just like the value returned by `window-hscroll' (below). Once you scroll a window as far right as it can go, back to its normal position where the total leftward scrolling is zero, attempts to scroll any farther right have no effect. If SET-MINIMUM is non-`nil', the new scroll amount becomes the lower bound for automatic scrolling; that is, automatic scrolling will not scroll a window to a column less than the value returned by this function. Interactive calls pass non-`nil' for SET-MINIMUM. -- Command: scroll-right &optional count set-minimum This function scrolls the selected window COUNT columns to the right (or to the left if COUNT is negative). The default for COUNT is the window width, minus 2. Aside from the direction of scrolling, this works just like `scroll-left'. -- Function: window-hscroll &optional window This function returns the total leftward horizontal scrolling of WINDOW--the number of columns by which the text in WINDOW is scrolled left past the left margin. The default for WINDOW is the selected window. The return value is never negative. It is zero when no horizontal scrolling has been done in WINDOW (which is usually the case). (window-hscroll) => 0 (scroll-left 5) => 5 (window-hscroll) => 5 -- Function: set-window-hscroll window columns This function sets horizontal scrolling of WINDOW. The value of COLUMNS specifies the amount of scrolling, in terms of columns from the left margin. The argument COLUMNS should be zero or positive; if not, it is taken as zero. Fractional values of COLUMNS are not supported at present. Note that `set-window-hscroll' may appear not to work if you test it by evaluating a call with `M-:' in a simple way. What happens is that the function sets the horizontal scroll value and returns, but then redisplay adjusts the horizontal scrolling to make point visible, and this overrides what the function did. You can observe the function's effect if you call it while point is sufficiently far from the left margin that it will remain visible. The value returned is COLUMNS. (set-window-hscroll (selected-window) 10) => 10 Here is how you can determine whether a given position POSITION is off the screen due to horizontal scrolling: (defun hscroll-on-screen (window position) (save-excursion (goto-char position) (and (>= (- (current-column) (window-hscroll window)) 0) (< (- (current-column) (window-hscroll window)) (window-width window)))))  File: elisp, Node: Size of Window, Next: Resizing Windows, Prev: Horizontal Scrolling, Up: Windows 28.15 The Size of a Window ========================== An Emacs window is rectangular, and its size information consists of the height (the number of lines) and the width (the number of character positions in each line). The mode line is included in the height. But the width does not count the scroll bar or the column of `|' characters that separates side-by-side windows. The following three functions return size information about a window: -- Function: window-height &optional window This function returns the number of lines in WINDOW (by default the selected window), including any mode line and header line. The result is almost always less than the value of `frame-height' for the associated frame, because the latter also includes any echo area. Depending on the toolkit in use, the frame height can also include the menu bar and tool bar (*note Size and Position::). Therefore in general it is not straightforward to compare window and frame heights (see `window-full-height-p' below). (window-height) => 23 (split-window-vertically) => # (window-height) => 11 -- Function: window-body-height &optional window Like `window-height' but the value does not include the mode line (if any) or the header line (if any). -- Function: window-full-height-p &optional window This function returns non-`nil' if WINDOW is as tall as the frame that contains it. The default for WINDOW is the selected window. -- Function: window-width &optional window This function returns the number of columns in WINDOW. The default for WINDOW is the selected window. The return value does not include the window's scroll bar or the column of `|' characters that separates side-by-side windows. Moreover, the return value does not include the space used for displaying fringes and margins. Hence you cannot, in general, compare the return values of `window-width' and `frame-width' for equality to determine whether a window is a wide as the containing frame. Use the function `window-full-width-p', see below, instead. (window-width) => 80 -- Function: window-full-width-p &optional window This function returns non-`nil' if WINDOW is as wide as the frame that contains it; otherwise `nil'. The default for WINDOW is the selected window. -- Function: window-edges &optional window This function returns a list of the edge coordinates of WINDOW. The default for WINDOW is the selected window. The order of the list is `(LEFT TOP RIGHT BOTTOM)', all elements relative to 0, 0 at the top left corner of the frame. The element RIGHT of the value is one more than the rightmost column used by WINDOW, and BOTTOM is one more than the bottommost row used by WINDOW and its mode-line. The edges include the space used by the window's scroll bar, display margins, fringes, header line, and mode line, if it has them. Also, if the window has a neighbor on the right, its right edge value includes the width of the separator line between the window and that neighbor. Since the width of the window does not include this separator, the width does not usually equal the difference between the right and left edges. -- Function: window-inside-edges &optional window This is similar to `window-edges', but the edge values it returns include only the text area of the window. They do not include the header line, mode line, scroll bar or vertical separator, fringes, or display margins. Here are the results obtained on a typical 24-line terminal with just one window, with menu bar enabled: (window-edges (selected-window)) => (0 1 80 23) (window-inside-edges (selected-window)) => (0 1 80 22) The bottom edge is at line 23 because the last line is the echo area. The bottom inside edge is at line 22, which is the window's mode line. If WINDOW is at the upper left corner of its frame, and there is no menu bar, then BOTTOM returned by `window-edges' is the same as the value of `(window-height)', RIGHT is almost the same as the value of `(window-width)', and TOP and LEFT are zero. For example, the edges of the following window are `0 0 8 5'. Assuming that the frame has more than 8 columns, the last column of the window (column 7) holds a border rather than text. The last row (row 4) holds the mode line, shown here with `xxxxxxxxx'. 0 _______ 0 | | | | | | | | xxxxxxxxx 4 7 In the following example, let's suppose that the frame is 7 columns wide. Then the edges of the left window are `0 0 4 3' and the edges of the right window are `4 0 7 3'. The inside edges of the left window are `0 0 3 2', and the inside edges of the right window are `4 0 7 2', ___ ___ | | | | | | xxxxxxxxx 0 34 7 -- Function: window-pixel-edges &optional window This function is like `window-edges' except that, on a graphical display, the edge values are measured in pixels instead of in character lines and columns. -- Function: window-inside-pixel-edges &optional window This function is like `window-inside-edges' except that, on a graphical display, the edge values are measured in pixels instead of in character lines and columns.  File: elisp, Node: Resizing Windows, Next: Coordinates and Windows, Prev: Size of Window, Up: Windows 28.16 Changing the Size of a Window =================================== The window size functions fall into two classes: high-level commands that change the size of windows and low-level functions that access window size. Emacs does not permit overlapping windows or gaps between windows, so resizing a window always affects at least one other window. -- Command: enlarge-window size &optional horizontal This function makes the selected window SIZE lines taller by stealing lines from windows above or below. In a first round, it takes lines from one window at a time until that window is `window-min-height' lines tall, then takes from another. If, at the end of the first round, the selected window is still not tall enough, `enlarge-window' starts a second round, where it deletes windows above or below the selected one. If HORIZONTAL is non-`nil', this function makes the window SIZE columns wider, stealing columns instead of lines. If a window from which columns are stolen shrinks below `window-min-width' columns, that window disappears. If the requested size would exceed that of the window's frame, then the function makes the window occupy the entire height (or width) of the frame. If there are various other windows from which lines or columns can be stolen, and some of them specify fixed size (using `window-size-fixed', see below), they are left untouched while other windows are "robbed." If it would be necessary to alter the size of a fixed-size window, `enlarge-window' gets an error instead. If SIZE is negative, this function shrinks the selected window by -SIZE lines or columns. If that makes the window smaller than the minimum size (`window-min-height' and `window-min-width'), then `enlarge-window' deletes the window. `enlarge-window' returns `nil'. -- Command: enlarge-window-horizontally columns This function makes the selected window COLUMNS wider. It could be defined as follows: (defun enlarge-window-horizontally (columns) (interactive "p") (enlarge-window columns t)) -- Command: shrink-window size &optional horizontal This function is like `enlarge-window' but negates the argument SIZE, making the selected window smaller by giving lines (or columns) to the other windows. If the window shrinks below `window-min-height' or `window-min-width', then it disappears. If SIZE is negative, the window is enlarged by -SIZE lines or columns. -- Command: shrink-window-horizontally columns This function makes the selected window COLUMNS narrower. It could be defined as follows: (defun shrink-window-horizontally (columns) (interactive "p") (shrink-window columns t)) -- Function: adjust-window-trailing-edge window delta horizontal This function makes the selected window DELTA lines taller or DELTA columns wider, by moving the bottom or right edge. This function does not delete other windows; if it cannot make the requested size adjustment, it signals an error. On success, this function returns `nil'. -- Command: fit-window-to-buffer &optional window max-height min-height This command makes WINDOW the right height to display its contents exactly. The default for WINDOW is the selected window. The optional argument MAX-HEIGHT specifies the maximum height the window is allowed to be; `nil' means use the maximum permissible height of a window on WINDOW's frame. The optional argument MIN-HEIGHT specifies the minimum height for the window; `nil' means use `window-min-height'. All these height values include the mode line and/or header line. This function can delete windows when their height shrinks below MIN-HEIGHT. It returns non-`nil' if it orderly resized WINDOW, and `nil' otherwise. -- Command: shrink-window-if-larger-than-buffer &optional window This command shrinks WINDOW vertically to be as small as possible while still showing the full contents of its buffer--but not less than `window-min-height' lines. The default for WINDOW is the selected window. However, this command does nothing if the window is already too small to display the whole text of the buffer, or if part of the contents are currently scrolled off screen, or if the window is not the full width of its frame, or if the window is the only window in its frame. This command returns non-`nil' if it actually shrank the window and `nil' otherwise. -- Variable: window-size-fixed If this variable is non-`nil', in a given buffer, then the size of any window displaying that buffer remains fixed unless you either explicitly change it or Emacs has no other choice. If the value is `height', then only the window's height is fixed; if the value is `width', then only the window's width is fixed. Any other non-`nil' value fixes both the width and the height. This variable automatically becomes buffer-local when set. Explicit size-change functions such as `enlarge-window' get an error if they would have to change a window size which is fixed. Therefore, when you want to change the size of such a window, you should bind `window-size-fixed' to `nil', like this: (let ((window-size-fixed nil)) (enlarge-window 10)) Deleting an adjacent window or changing the frame size may change the size of a fixed-size window, if there is no other alternative. The following two variables constrain the window-structure-changing functions to a minimum height and width. -- User Option: window-min-height The value of this variable specifies how short a window may become before it is automatically deleted. Making a window smaller than `window-min-height' automatically deletes it, and no window may be created shorter than this. The value is measured in line units. When the window wants a mode line and/or a header line, they are counted as one line each. The default value is `4'. A value less than `1' is ignored. -- User Option: window-min-width The value of this variable specifies how narrow a window may become before it is automatically deleted. Making a window smaller than `window-min-width' automatically deletes it, and no window may be created narrower than this. The value is measured in characters and includes any fringes or the scroll bar. The default value is `10'. A value less than `2' is ignored. Emacs provides two functions to balance windows, that is, to even out the sizes of windows on the same frame. The minibuffer window and fixed-size windows are not resized by these functions. -- Command: balance-windows &optional window-or-frame This function balances windows in a way that gives more space to full-width and/or full-height windows. If WINDOW-OR-FRAME specifies a frame, it balances all windows on that frame. If WINDOW-OR-FRAME specifies a window, it balances this window and its "siblings" only. Think of a sibling as the other (original or new) window with respect to the present one, involved in the process of splitting; see *note Splitting Windows::. Since a sibling may have been split again, a window can have more than one sibling. -- Command: balance-windows-area This function attempts to give all windows on the selected frame approximately the same share of the screen area. This means that full-width or full-height windows are not given more space than other windows.  File: elisp, Node: Coordinates and Windows, Next: Window Tree, Prev: Resizing Windows, Up: Windows 28.17 Coordinates and Windows ============================= This section describes how to relate screen coordinates to windows. -- Function: window-at x y &optional frame This function returns the window containing the specified cursor position in the frame FRAME. The coordinates X and Y are measured in characters and count from the top left corner of the frame. If they are out of range, `window-at' returns `nil'. If you omit FRAME, the selected frame is used. -- Function: coordinates-in-window-p coordinates window This function checks whether a particular frame position falls within the window WINDOW. The argument COORDINATES is a cons cell of the form `(X . Y)'. The coordinates X and Y are measured in characters, and count from the top left corner of the screen or frame. The value returned by `coordinates-in-window-p' is non-`nil' if the coordinates are inside WINDOW. The value also indicates what part of the window the position is in, as follows: `(RELX . RELY)' The coordinates are inside WINDOW. The numbers RELX and RELY are the equivalent window-relative coordinates for the specified position, counting from 0 at the top left corner of the window. `mode-line' The coordinates are in the mode line of WINDOW. `header-line' The coordinates are in the header line of WINDOW. `vertical-line' The coordinates are in the vertical line between WINDOW and its neighbor to the right. This value occurs only if the window doesn't have a scroll bar; positions in a scroll bar are considered outside the window for these purposes. `left-fringe' `right-fringe' The coordinates are in the left or right fringe of the window. `left-margin' `right-margin' The coordinates are in the left or right margin of the window. `nil' The coordinates are not in any part of WINDOW. The function `coordinates-in-window-p' does not require a frame as argument because it always uses the frame that WINDOW is on.  File: elisp, Node: Window Tree, Next: Window Configurations, Prev: Coordinates and Windows, Up: Windows 28.18 The Window Tree ===================== A "window tree" specifies the layout, size, and relationship between all windows in one frame. -- Function: window-tree &optional frame This function returns the window tree for frame FRAME. If FRAME is omitted, the selected frame is used. The return value is a list of the form `(ROOT MINI)', where ROOT represents the window tree of the frame's root window, and MINI is the frame's minibuffer window. If the root window is not split, ROOT is the root window itself. Otherwise, ROOT is a list `(DIR EDGES W1 W2 ...)' where DIR is `nil' for a horizontal split, and `t' for a vertical split, EDGES gives the combined size and position of the subwindows in the split, and the rest of the elements are the subwindows in the split. Each of the subwindows may again be a window or a list representing a window split, and so on. The EDGES element is a list `(LEFT TOP RIGHT BOTTOM)' similar to the value returned by `window-edges'.  File: elisp, Node: Window Configurations, Next: Window Parameters, Prev: Window Tree, Up: Windows 28.19 Window Configurations =========================== A "window configuration" records the entire layout of one frame--all windows, their sizes, which buffers they contain, how those buffers are scrolled, and their values of point and the mark; also their fringes, margins, and scroll bar settings. It also includes the value of `minibuffer-scroll-window'. As a special exception, the window configuration does not record the value of point in the selected window for the current buffer. Also, the window configuration does not record the values of window parameters; see *note Window Parameters::. You can bring back an entire frame layout by restoring a previously saved window configuration. If you want to record the layout of all frames instead of just one, use a frame configuration instead of a window configuration; see *note Frame Configurations::. -- Function: current-window-configuration &optional frame This function returns a new object representing FRAME's current window configuration. The default for FRAME is the selected frame. -- Function: set-window-configuration configuration This function restores the configuration of windows and buffers as specified by CONFIGURATION, for the frame that CONFIGURATION was created for. The argument CONFIGURATION must be a value that was previously returned by `current-window-configuration'. The configuration is restored in the frame from which CONFIGURATION was made, whether that frame is selected or not. This always counts as a window size change and triggers execution of the `window-size-change-functions' (*note Window Hooks::), because `set-window-configuration' doesn't know how to tell whether the new configuration actually differs from the old one. If the frame which CONFIGURATION was saved from is dead, all this function does is restore the three variables `window-min-height', `window-min-width' and `minibuffer-scroll-window'. In this case, the function returns `nil'. Otherwise, it returns `t'. Here is a way of using this function to get the same effect as `save-window-excursion': (let ((config (current-window-configuration))) (unwind-protect (progn (split-window-vertically nil) ...) (set-window-configuration config))) -- Special Form: save-window-excursion forms... This special form records the window configuration, executes FORMS in sequence, then restores the earlier window configuration. The window configuration includes, for each window, the value of point and the portion of the buffer that is visible. It also includes the choice of selected window. However, it does not include the value of point in the current buffer; use `save-excursion' also, if you wish to preserve that. Don't use this construct when `save-selected-window' is sufficient. Exit from `save-window-excursion' always triggers execution of `window-size-change-functions'. (It doesn't know how to tell whether the restored configuration actually differs from the one in effect at the end of the FORMS.) The return value is the value of the final form in FORMS. For example: (split-window) => # (setq w (selected-window)) => # (save-window-excursion (delete-other-windows w) (switch-to-buffer "foo") 'do-something) => do-something ;; The screen is now split again. -- Function: window-configuration-p object This function returns `t' if OBJECT is a window configuration. -- Function: compare-window-configurations config1 config2 This function compares two window configurations as regards the structure of windows, but ignores the values of point and mark and the saved scrolling positions--it can return `t' even if those aspects differ. The function `equal' can also compare two window configurations; it regards configurations as unequal if they differ in any respect, even a saved point or mark. -- Function: window-configuration-frame config This function returns the frame for which the window configuration CONFIG was made. Other primitives to look inside of window configurations would make sense, but are not implemented because we did not need them. See the file `winner.el' for some more operations on windows configurations.  File: elisp, Node: Window Parameters, Next: Window Hooks, Prev: Window Configurations, Up: Windows 28.20 Window Parameters ======================= This sections describes how window parameters can be used to associate additional information with windows. -- Function: window-parameter window parameter This function returns WINDOW's value for PARAMETER. The default for WINDOW is the selected window. If WINDOW has no setting for PARAMETER, this function returns `nil'. -- Function: window-parameters &optional window This function returns all parameters of WINDOW and their values. The default for WINDOW is the selected window. The return value is an association list of elements of the form `(PARAMETER . VALUE)'. -- Function: set-window-parameter window parameter value This function sets WINDOW's value of PARAMETER to VALUE and returns VALUE. The default for WINDOW is the selected window. Currently, window parameters are not saved in window configurations and consequently not restored by `set-window-configuration'. Hence, any change of a parameter introduced via `set-window-parameter' can be undone only by invoking `set-window-parameter' for the same parameter again. Since `save-window-excursion' relies on window configurations (*note Window Configurations::), window parameters are not saved and restored by that special form, either.  File: elisp, Node: Window Hooks, Prev: Window Parameters, Up: Windows 28.21 Hooks for Window Scrolling and Changes ============================================ This section describes how a Lisp program can take action whenever a window displays a different part of its buffer or a different buffer. There are three actions that can change this: scrolling the window, switching buffers in the window, and changing the size of the window. The first two actions run `window-scroll-functions'; the last runs `window-size-change-functions'. -- Variable: window-scroll-functions This variable holds a list of functions that Emacs should call before redisplaying a window with scrolling. Displaying a different buffer in the window also runs these functions. This variable is not a normal hook, because each function is called with two arguments: the window, and its new display-start position. These functions must be careful in using `window-end' (*note Window Start and End::); if you need an up-to-date value, you must use the UPDATE argument to ensure you get it. *Warning:* don't use this feature to alter the way the window is scrolled. It's not designed for that, and such use probably won't work. -- Variable: window-size-change-functions This variable holds a list of functions to be called if the size of any window changes for any reason. The functions are called just once per redisplay, and just once for each frame on which size changes have occurred. Each function receives the frame as its sole argument. There is no direct way to find out which windows on that frame have changed size, or precisely how. However, if a size-change function records, at each call, the existing windows and their sizes, it can also compare the present sizes and the previous sizes. Creating or deleting windows counts as a size change, and therefore causes these functions to be called. Changing the frame size also counts, because it changes the sizes of the existing windows. It is not a good idea to use `save-window-excursion' (*note Window Configurations::) in these functions, because that always counts as a size change, and it would cause these functions to be called over and over. In most cases, `save-selected-window' (*note Selecting Windows::) is what you need here. -- Variable: window-configuration-change-hook A normal hook that is run every time you change the window configuration of an existing frame. This includes splitting or deleting windows, changing the sizes of windows, or displaying a different buffer in a window. The buffer-local part of this hook is run once per each window on the affected frame, with the relevant window selected and its buffer current. The global part is run once for the modified frame, with that frame selected. In addition, you can use `jit-lock-register' to register a Font Lock fontification function, which will be called whenever parts of a buffer are (re)fontified because a window was scrolled or its size changed. *Note Other Font Lock Variables::.  File: elisp, Node: Frames, Next: Positions, Prev: Windows, Up: Top 29 Frames ********* A "frame" is a screen object that contains one or more Emacs windows (*note Windows::). It is the kind of object called a "window" in the terminology of graphical environments; but we can't call it a "window" here, because Emacs uses that word in a different way. In Emacs Lisp, a "frame object" is a Lisp object that represents a frame on the screen. *Note Frame Type::. A frame initially contains a single main window and/or a minibuffer window; you can subdivide the main window vertically or horizontally into smaller windows. *Note Splitting Windows::. A "terminal" is a display device capable of displaying one or more Emacs frames. In Emacs Lisp, a "terminal object" is a Lisp object that represents a terminal. *Note Terminal Type::. There are two classes of terminals: text-only terminals and graphical terminals. Text-only terminals are non-graphics-capable display devices, including "terminal emulators" such as xterm. On text-only terminals, each frame occupies the entire terminal screen; although you can create additional frames and switch between them, only one frame can be shown at any given time. We refer to frames on text-only terminals as "terminal frames". Graphical terminals, on the other hand, are graphics-capable windowing systems, such as the X Window System. On a graphical terminal, Emacs can display multiple frames simultaneously. We refer to such frames as "window frames". On GNU and Unix systems, you can create additional frames on any available terminal, within a single Emacs session, regardless of whether Emacs was started on a text-only or graphical terminal. Emacs can display on both graphical and text-only terminals simultaneously. This comes in handy, for instance, when you connect to the same session from several remote locations. *Note Multiple Terminals::. -- Function: framep object This predicate returns a non-`nil' value if OBJECT is a frame, and `nil' otherwise. For a frame, the value indicates which kind of display the frame uses: `x' The frame is displayed in an X window. `t' A terminal frame on a character display. `w32' The frame is displayed on MS-Windows 9X/NT. `ns' The frame is displayed on a GNUstep or Macintosh Cocoa display. `pc' The frame is displayed on an MS-DOS terminal. -- Function: frame-terminal &optional frame This function returns the terminal object that displays FRAME. If FRAME is `nil' or unspecified, it defaults to the selected frame. -- Function: terminal-live-p object This predicate returns a non-`nil' value if OBJECT is a terminal that is alive (i.e. was not deleted), and `nil' otherwise. For live terminals, the return value indicates what kind of frames are displayed on that terminal; the list of possible values is the same as for `framep' above. * Menu: * Creating Frames:: Creating additional frames. * Multiple Terminals:: Displaying on several different devices. * Frame Parameters:: Controlling frame size, position, font, etc. * Terminal Parameters:: Parameters common for all frames on terminal. * Frame Titles:: Automatic updating of frame titles. * Deleting Frames:: Frames last until explicitly deleted. * Finding All Frames:: How to examine all existing frames. * Frames and Windows:: A frame contains windows; display of text always works through windows. * Minibuffers and Frames:: How a frame finds the minibuffer to use. * Input Focus:: Specifying the selected frame. * Visibility of Frames:: Frames may be visible or invisible, or icons. * Raising and Lowering:: Raising a frame makes it hide other windows; lowering it makes the others hide it. * Frame Configurations:: Saving the state of all frames. * Mouse Tracking:: Getting events that say when the mouse moves. * Mouse Position:: Asking where the mouse is, or moving it. * Pop-Up Menus:: Displaying a menu for the user to select from. * Dialog Boxes:: Displaying a box to ask yes or no. * Pointer Shape:: Specifying the shape of the mouse pointer. * Window System Selections:: Transferring text to and from other X clients. * Drag and Drop:: Internals of Drag-and-Drop implementation. * Color Names:: Getting the definitions of color names. * Text Terminal Colors:: Defining colors for text-only terminals. * Resources:: Getting resource values from the server. * Display Feature Testing:: Determining the features of a terminal.  File: elisp, Node: Creating Frames, Next: Multiple Terminals, Up: Frames 29.1 Creating Frames ==================== To create a new frame, call the function `make-frame'. -- Function: make-frame &optional alist This function creates and returns a new frame, displaying the current buffer. The ALIST argument is an alist that specifies frame parameters for the new frame. *Note Frame Parameters::. If you specify the `terminal' parameter in ALIST, the new frame is created on that terminal. Otherwise, if you specify the `window-system' frame parameter in ALIST, that determines whether the frame should be displayed on a text-only or graphical terminal. *Note Window Systems::. If neither is specified, the new frame is created in the same terminal as the selected frame. Any parameters not mentioned in ALIST default to the values in the alist `default-frame-alist' (*note Initial Parameters::); parameters not specified there default from the X resources or its equivalent on your operating system (*note X Resources: (emacs)X Resources.). After the frame is created, Emacs applies any parameters listed in `frame-inherited-parameters' (see below) and not present in the argument, taking the values from the frame that was selected when `make-frame' was called. This function itself does not make the new frame the selected frame. *Note Input Focus::. The previously selected frame remains selected. On graphical terminals, however, the windowing system may select the new frame for its own reasons. -- Variable: before-make-frame-hook A normal hook run by `make-frame' before it creates the frame. -- Variable: after-make-frame-functions An abnormal hook run by `make-frame' after it creates the frame. Each function in `after-make-frame-functions' receives one argument, the frame just created. -- Variable: frame-inherited-parameters This variable specifies the list of frame parameters that a newly created frame inherits from the currently selected frame. For each parameter (a symbol) that is an element in the list and is not present in the argument to `make-frame', the function sets the value of that parameter in the created frame to its value in the selected frame.  File: elisp, Node: Multiple Terminals, Next: Frame Parameters, Prev: Creating Frames, Up: Frames 29.2 Multiple Terminals ======================= Emacs represents each terminal, whether graphical or text-only, as a "terminal object" data type (*note Terminal Type::). On GNU and Unix systems, Emacs can use multiple terminals simultaneously in each session. On other systems, it can only use a single terminal. Each terminal object has the following attributes: * The name of the device used by the terminal (e.g., `:0.0' or `/dev/tty'). * The terminal and keyboard coding systems used on the terminal. *Note Terminal I/O Encoding::. * The kind of display associated with the terminal. This is the symbol returned by the function `terminal-live-p' (i.e., `x', `t', `w32', `ns', or `pc'). *Note Frames::. * A list of terminal parameters. *Note Terminal Parameters::. There is no primitive for creating terminal objects. Emacs creates them as needed, such as when you call `make-frame-on-display' (which is described below). -- Function: terminal-name &optional terminal This function returns the file name of the device used by TERMINAL. If TERMINAL is omitted or `nil', it defaults to the selected frame's terminal. TERMINAL can also be a frame, meaning that frame's terminal. -- Function: terminal-list This function returns a list of all terminal objects currently in use. -- Function: get-device-terminal device This function returns a terminal whose device name is given by DEVICE. If DEVICE is a string, it can be either the file name of a terminal device, or the name of an X display of the form `HOST:SERVER.SCREEN'. If DEVICE is a frame, this function returns that frame's terminal; `nil' means the selected frame. Finally, if DEVICE is a terminal object that represents a live terminal, that terminal is returned. The function signals an error if its argument is none of the above. -- Function: delete-terminal &optional terminal force This function deletes all frames on TERMINAL and frees the resources used by it. It runs the abnormal hook `delete-terminal-functions', passing TERMINAL as the argument to each function. If TERMINAL is omitted or `nil', it defaults to the selected frame's terminal. TERMINAL can also be a frame, meaning that frame's terminal. Normally, this function signals an error if you attempt to delete the sole active terminal, but if FORCE is non-`nil', you are allowed to do so. Emacs automatically calls this function when the last frame on a terminal is deleted (*note Deleting Frames::). -- Variable: delete-terminal-functions An abnormal hook run by `delete-terminal'. Each function receives one argument, the TERMINAL argument passed to `delete-terminal'. Due to technical details, the functions may be called either just before the terminal is deleted, or just afterwards. A few Lisp variables are "terminal-local"; that is, they have a separate binding for each terminal. The binding in effect at any time is the one for the terminal that the currently selected frame belongs to. These variables include `default-minibuffer-frame', `defining-kbd-macro', `last-kbd-macro', and `system-key-alist'. They are always terminal-local, and can never be buffer-local (*note Buffer-Local Variables::). On GNU and Unix systems, each X display is a separate graphical terminal. When Emacs is started from within the X window system, it uses the X display chosen with the `DISPLAY' environment variable, or with the `--display' option. *Note Initial Options: (emacs)Initial Options. Emacs can connect to other X displays via the command `make-frame-on-display'. Each X display has its own selected frame and its own minibuffer windows; however, only one of those frames is "_the_ selected frame" at any given moment (*note Input Focus::). Emacs can even connect to other text-only terminals, by interacting with the `emacsclient' program. *Note Emacs Server: (emacs)Emacs Server. A single X server can handle more than one display. Each X display has a three-part name, `HOST:SERVER.SCREEN'. The first two parts, HOST and SERVER, identify the X server; the third part, SCREEN, identifies a screen number on that X server. When you use two or more screens belonging to one server, Emacs knows by the similarity in their names that they share a single keyboard. On some "multi-monitor" setups, a single X display outputs to more than one monitor. Currently, there is no way for Emacs to distinguish between the different physical monitors. -- Command: make-frame-on-display display &optional parameters This function creates and returns a new frame on DISPLAY, taking the other frame parameters from the alist PARAMETERS. DISPLAY should be the name of an X display (a string). Before creating the frame, this function ensures that Emacs is "set up" to display graphics. For instance, if Emacs has not processed X resources (e.g., if it was started on a text-only terminal), it does so at this time. In all other respects, this function behaves like `make-frame' (*note Creating Frames::). -- Function: x-display-list This function returns a list that indicates which X displays Emacs has a connection to. The elements of the list are strings, and each one is a display name. -- Function: x-open-connection display &optional xrm-string must-succeed This function opens a connection to the X display DISPLAY, without creating a frame on that display. Normally, Emacs Lisp programs need not call this function, as `make-frame-on-display' calls it automatically. The only reason for calling it is to check whether communication can be established with a given X display. The optional argument XRM-STRING, if not `nil', is a string of resource names and values, in the same format used in the `.Xresources' file. *Note X Resources: (emacs)X Resources. These values apply to all Emacs frames created on this display, overriding the resource values recorded in the X server. Here's an example of what this string might look like: "*BorderWidth: 3\n*InternalBorder: 2\n" If MUST-SUCCEED is non-`nil', failure to open the connection terminates Emacs. Otherwise, it is an ordinary Lisp error. -- Function: x-close-connection display This function closes the connection to display DISPLAY. Before you can do this, you must first delete all the frames that were open on that display (*note Deleting Frames::).  File: elisp, Node: Frame Parameters, Next: Terminal Parameters, Prev: Multiple Terminals, Up: Frames 29.3 Frame Parameters ===================== A frame has many parameters that control its appearance and behavior. Just what parameters a frame has depends on what display mechanism it uses. Frame parameters exist mostly for the sake of window systems. A terminal frame has a few parameters, mostly for compatibility's sake; only the `height', `width', `name', `title', `menu-bar-lines', `buffer-list' and `buffer-predicate' parameters do something special. If the terminal supports colors, the parameters `foreground-color', `background-color', `background-mode' and `display-type' are also meaningful. If the terminal supports frame transparency, the parameter `alpha' is also meaningful. You can use frame parameters to define frame-local bindings for variables. *Note Frame-Local Variables::. * Menu: * Parameter Access:: How to change a frame's parameters. * Initial Parameters:: Specifying frame parameters when you make a frame. * Window Frame Parameters:: List of frame parameters for window systems. * Size and Position:: Changing the size and position of a frame. * Geometry:: Parsing geometry specifications.  File: elisp, Node: Parameter Access, Next: Initial Parameters, Up: Frame Parameters 29.3.1 Access to Frame Parameters --------------------------------- These functions let you read and change the parameter values of a frame. -- Function: frame-parameter frame parameter This function returns the value of the parameter PARAMETER (a symbol) of FRAME. If FRAME is `nil', it returns the selected frame's parameter. If FRAME has no setting for PARAMETER, this function returns `nil'. -- Function: frame-parameters &optional frame The function `frame-parameters' returns an alist listing all the parameters of FRAME and their values. If FRAME is `nil' or omitted, this returns the selected frame's parameters -- Function: modify-frame-parameters frame alist This function alters the parameters of frame FRAME based on the elements of ALIST. Each element of ALIST has the form `(PARM . VALUE)', where PARM is a symbol naming a parameter. If you don't mention a parameter in ALIST, its value doesn't change. If FRAME is `nil', it defaults to the selected frame. You can use this function to define frame-local bindings for variables, see *note Frame-Local Variables::. -- Function: set-frame-parameter frame parm value This function sets the frame parameter PARM to the specified VALUE. If FRAME is `nil', it defaults to the selected frame. -- Function: modify-all-frames-parameters alist This function alters the frame parameters of all existing frames according to ALIST, then modifies `default-frame-alist' (and, if necessary, `initial-frame-alist') to apply the same parameter values to frames that will be created henceforth.  File: elisp, Node: Initial Parameters, Next: Window Frame Parameters, Prev: Parameter Access, Up: Frame Parameters 29.3.2 Initial Frame Parameters ------------------------------- You can specify the parameters for the initial startup frame by setting `initial-frame-alist' in your init file (*note Init File::). -- User Option: initial-frame-alist This variable's value is an alist of parameter values used when creating the initial window frame. You can set this variable to specify the appearance of the initial frame without altering subsequent frames. Each element has the form: (PARAMETER . VALUE) Emacs creates the initial frame before it reads your init file. After reading that file, Emacs checks `initial-frame-alist', and applies the parameter settings in the altered value to the already created initial frame. If these settings affect the frame geometry and appearance, you'll see the frame appear with the wrong ones and then change to the specified ones. If that bothers you, you can specify the same geometry and appearance with X resources; those do take effect before the frame is created. *Note X Resources: (emacs)X Resources. X resource settings typically apply to all frames. If you want to specify some X resources solely for the sake of the initial frame, and you don't want them to apply to subsequent frames, here's how to achieve this. Specify parameters in `default-frame-alist' to override the X resources for subsequent frames; then, to prevent these from affecting the initial frame, specify the same parameters in `initial-frame-alist' with values that match the X resources. If these parameters specify a separate minibuffer-only frame with `(minibuffer . nil)', and you have not created one, Emacs creates one for you. -- User Option: minibuffer-frame-alist This variable's value is an alist of parameter values used when creating an initial minibuffer-only frame. This is the minibuffer-only frame that Emacs creates if `initial-frame-alist' specifies a frame with no minibuffer. -- User Option: default-frame-alist This is an alist specifying default values of frame parameters for all Emacs frames--the first frame, and subsequent frames. When using the X Window System, you can get the same results by means of X resources in many cases. Setting this variable does not affect existing frames. Functions that display a buffer in a separate frame can override the default parameters by supplying their own parameters. *Note Definition of special-display-frame-alist::. If you use options that specify window appearance when you invoke Emacs, they take effect by adding elements to `default-frame-alist'. One exception is `-geometry', which adds the specified position to `initial-frame-alist' instead. *Note Command Line Arguments for Emacs Invocation: (emacs)Emacs Invocation.  File: elisp, Node: Window Frame Parameters, Next: Size and Position, Prev: Initial Parameters, Up: Frame Parameters 29.3.3 Window Frame Parameters ------------------------------ Just what parameters a frame has depends on what display mechanism it uses. This section describes the parameters that have special meanings on some or all kinds of terminals. Of these, `name', `title', `height', `width', `buffer-list' and `buffer-predicate' provide meaningful information in terminal frames, and `tty-color-mode' is meaningful _only_ in terminal frames. * Menu: * Basic Parameters:: Parameters that are fundamental. * Position Parameters:: The position of the frame on the screen. * Size Parameters:: Frame's size. * Layout Parameters:: Size of parts of the frame, and enabling or disabling some parts. * Buffer Parameters:: Which buffers have been or should be shown. * Management Parameters:: Communicating with the window manager. * Cursor Parameters:: Controlling the cursor appearance. * Font and Color Parameters:: Fonts and colors for the frame text.  File: elisp, Node: Basic Parameters, Next: Position Parameters, Up: Window Frame Parameters 29.3.3.1 Basic Parameters ......................... These frame parameters give the most basic information about the frame. `title' and `name' are meaningful on all terminals. `display' The display on which to open this frame. It should be a string of the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment variable. `display-type' This parameter describes the range of possible colors that can be used in this frame. Its value is `color', `grayscale' or `mono'. `title' If a frame has a non-`nil' title, it appears in the window system's title bar at the top of the frame, and also in the mode line of windows in that frame if `mode-line-frame-identification' uses `%F' (*note %-Constructs::). This is normally the case when Emacs is not using a window system, and can only display one frame at a time. *Note Frame Titles::. `name' The name of the frame. The frame name serves as a default for the frame title, if the `title' parameter is unspecified or `nil'. If you don't specify a name, Emacs sets the frame name automatically (*note Frame Titles::). If you specify the frame name explicitly when you create the frame, the name is also used (instead of the name of the Emacs executable) when looking up X resources for the frame.  File: elisp, Node: Position Parameters, Next: Size Parameters, Prev: Basic Parameters, Up: Window Frame Parameters 29.3.3.2 Position Parameters ............................ Position parameters' values are normally measured in pixels, but on text-only terminals they count characters or lines instead. `left' The position, in pixels, of the left (or right) edge of the frame with respect to the left (or right) edge of the screen. The value may be: an integer A positive integer relates the left edge of the frame to the left edge of the screen. A negative integer relates the right frame edge to the right screen edge. `(+ POS)' This specifies the position of the left frame edge relative to the left screen edge. The integer POS may be positive or negative; a negative value specifies a position outside the screen. `(- POS)' This specifies the position of the right frame edge relative to the right screen edge. The integer POS may be positive or negative; a negative value specifies a position outside the screen. Some window managers ignore program-specified positions. If you want to be sure the position you specify is not ignored, specify a non-`nil' value for the `user-position' parameter as well. `top' The screen position of the top (or bottom) edge, in pixels, with respect to the top (or bottom) edge of the screen. It works just like `left', except vertically instead of horizontally. `icon-left' The screen position of the left edge _of the frame's icon_, in pixels, counting from the left edge of the screen. This takes effect if and when the frame is iconified. If you specify a value for this parameter, then you must also specify a value for `icon-top' and vice versa. The window manager may ignore these two parameters. `icon-top' The screen position of the top edge _of the frame's icon_, in pixels, counting from the top edge of the screen. This takes effect if and when the frame is iconified. `user-position' When you create a frame and specify its screen position with the `left' and `top' parameters, use this parameter to say whether the specified position was user-specified (explicitly requested in some way by a human user) or merely program-specified (chosen by a program). A non-`nil' value says the position was user-specified. Window managers generally heed user-specified positions, and some heed program-specified positions too. But many ignore program-specified positions, placing the window in a default fashion or letting the user place it with the mouse. Some window managers, including `twm', let the user specify whether to obey program-specified positions or ignore them. When you call `make-frame', you should specify a non-`nil' value for this parameter if the values of the `left' and `top' parameters represent the user's stated preference; otherwise, use `nil'.  File: elisp, Node: Size Parameters, Next: Layout Parameters, Prev: Position Parameters, Up: Window Frame Parameters 29.3.3.3 Size Parameters ........................ Size parameters' values are normally measured in pixels, but on text-only terminals they count characters or lines instead. `height' The height of the frame contents, in characters. (To get the height in pixels, call `frame-pixel-height'; see *note Size and Position::.) `width' The width of the frame contents, in characters. (To get the width in pixels, call `frame-pixel-width'; see *note Size and Position::.) `user-size' This does for the size parameters `height' and `width' what the `user-position' parameter (see above) does for the position parameters `top' and `left'. `fullscreen' Specify that width, height or both shall be maximized. The value `fullwidth' specifies that width shall be as wide as possible. The value `fullheight' specifies that height shall be as tall as possible. The value `fullboth' specifies that both the width and the height shall be set to the size of the screen. The value `maximized' specifies that the frame shall be maximized. The difference between `maximized' and `fullboth' is that the former still has window manager decorations while the latter really covers the whole screen.  File: elisp, Node: Layout Parameters, Next: Buffer Parameters, Prev: Size Parameters, Up: Window Frame Parameters 29.3.3.4 Layout Parameters .......................... These frame parameters enable or disable various parts of the frame, or control their sizes. `border-width' The width in pixels of the frame's border. `internal-border-width' The distance in pixels between text (or fringe) and the frame's border. `vertical-scroll-bars' Whether the frame has scroll bars for vertical scrolling, and which side of the frame they should be on. The possible values are `left', `right', and `nil' for no scroll bars. `scroll-bar-width' The width of vertical scroll bars, in pixels, or `nil' meaning to use the default width. `left-fringe' `right-fringe' The default width of the left and right fringes of windows in this frame (*note Fringes::). If either of these is zero, that effectively removes the corresponding fringe. A value of `nil' stands for the standard fringe width, which is the width needed to display the fringe bitmaps. The combined fringe widths must add up to an integral number of columns, so the actual default fringe widths for the frame may be larger than the specified values. The extra width needed to reach an acceptable total is distributed evenly between the left and right fringe. However, you can force one fringe or the other to a precise width by specifying that width as a negative integer. If both widths are negative, only the left fringe gets the specified width. `menu-bar-lines' The number of lines to allocate at the top of the frame for a menu bar. The default is 1. A value of `nil' means don't display a menu bar. *Note Menu Bar::. (The X toolkit and GTK allow at most one menu bar line; they treat larger values as 1.) `tool-bar-lines' The number of lines to use for the tool bar. A value of `nil' means don't display a tool bar. (GTK and Nextstep allow at most one tool bar line; they treat larger values as 1.) `line-spacing' Additional space to leave below each text line, in pixels (a positive integer). *Note Line Height::, for more information.  File: elisp, Node: Buffer Parameters, Next: Management Parameters, Prev: Layout Parameters, Up: Window Frame Parameters 29.3.3.5 Buffer Parameters .......................... These frame parameters, meaningful on all kinds of terminals, deal with which buffers have been, or should, be displayed in the frame. `minibuffer' Whether this frame has its own minibuffer. The value `t' means yes, `nil' means no, `only' means this frame is just a minibuffer. If the value is a minibuffer window (in some other frame), the frame uses that minibuffer. This frame parameter takes effect when the frame is created, and can not be changed afterwards. `buffer-predicate' The buffer-predicate function for this frame. The function `other-buffer' uses this predicate (from the selected frame) to decide which buffers it should consider, if the predicate is not `nil'. It calls the predicate with one argument, a buffer, once for each buffer; if the predicate returns a non-`nil' value, it considers that buffer. `buffer-list' A list of buffers that have been selected in this frame, ordered most-recently-selected first. `unsplittable' If non-`nil', this frame's window is never split automatically.  File: elisp, Node: Management Parameters, Next: Cursor Parameters, Prev: Buffer Parameters, Up: Window Frame Parameters 29.3.3.6 Window Management Parameters ..................................... These frame parameters, meaningful only on window system displays, interact with the window manager. `visibility' The state of visibility of the frame. There are three possibilities: `nil' for invisible, `t' for visible, and `icon' for iconified. *Note Visibility of Frames::. `auto-raise' Whether selecting the frame raises it (non-`nil' means yes). `auto-lower' Whether deselecting the frame lowers it (non-`nil' means yes). `icon-type' The type of icon to use for this frame when it is iconified. If the value is a string, that specifies a file containing a bitmap to use. Any other non-`nil' value specifies the default bitmap icon (a picture of a gnu); `nil' specifies a text icon. `icon-name' The name to use in the icon for this frame, when and if the icon appears. If this is `nil', the frame's title is used. `window-id' The number of the window-system window used by the frame to contain the actual Emacs windows. `outer-window-id' The number of the outermost window-system window used for the whole frame. `wait-for-wm' If non-`nil', tell Xt to wait for the window manager to confirm geometry changes. Some window managers, including versions of Fvwm2 and KDE, fail to confirm, so Xt hangs. Set this to `nil' to prevent hanging with those window managers. `sticky' If non-`nil', the frame is visible on all virtual desktops on systems with virtual desktops.  File: elisp, Node: Cursor Parameters, Next: Font and Color Parameters, Prev: Management Parameters, Up: Window Frame Parameters 29.3.3.7 Cursor Parameters .......................... This frame parameter controls the way the cursor looks. `cursor-type' How to display the cursor. Legitimate values are: `box' Display a filled box. (This is the default.) `hollow' Display a hollow box. `nil' Don't display a cursor. `bar' Display a vertical bar between characters. `(bar . WIDTH)' Display a vertical bar WIDTH pixels wide between characters. `hbar' Display a horizontal bar. `(hbar . HEIGHT)' Display a horizontal bar HEIGHT pixels high. The buffer-local variable `cursor-type' overrides the value of the `cursor-type' frame parameter, but if it is `t', that means to use the cursor specified for the frame. -- User Option: blink-cursor-alist This variable specifies how to blink the cursor. Each element has the form `(ON-STATE . OFF-STATE)'. Whenever the cursor type equals ON-STATE (comparing using `equal'), the corresponding OFF-STATE specifies what the cursor looks like when it blinks "off." Both ON-STATE and OFF-STATE should be suitable values for the `cursor-type' frame parameter. There are various defaults for how to blink each type of cursor, if the type is not mentioned as an ON-STATE here. Changes in this variable do not take effect immediately, only when you specify the `cursor-type' frame parameter. -- User Option: cursor-in-non-selected-windows This variable controls how the cursor looks in a window that is not selected. It supports the same values as the `cursor-type' frame parameter; also, `nil' means don't display a cursor in nonselected windows, and `t' (the default) means use a standard modification of the usual cursor type (solid box becomes hollow box, and bar becomes a narrower bar).  File: elisp, Node: Font and Color Parameters, Prev: Cursor Parameters, Up: Window Frame Parameters 29.3.3.8 Font and Color Parameters .................................. These frame parameters control the use of fonts and colors. `font-backend' A list of symbols, specifying the "font backends" to use for drawing fonts in the frame, in order of priority. On X, there are currently two available font backends: `x' (the X core font driver) and `xft' (the Xft font driver). On other systems, there is only one available font backend, so it does not make sense to modify this frame parameter. `background-mode' This parameter is either `dark' or `light', according to whether the background color is a light one or a dark one. `tty-color-mode' This parameter overrides the terminal's color support as given by the system's terminal capabilities database in that this parameter's value specifies the color mode to use in terminal frames. The value can be either a symbol or a number. A number specifies the number of colors to use (and, indirectly, what commands to issue to produce each color). For example, `(tty-color-mode . 8)' specifies use of the ANSI escape sequences for 8 standard text colors. A value of -1 turns off color support. If the parameter's value is a symbol, it specifies a number through the value of `tty-color-mode-alist', and the associated number is used instead. `screen-gamma' If this is a number, Emacs performs "gamma correction" which adjusts the brightness of all colors. The value should be the screen gamma of your display, a floating point number. Usual PC monitors have a screen gamma of 2.2, so color values in Emacs, and in X windows generally, are calibrated to display properly on a monitor with that gamma value. If you specify 2.2 for `screen-gamma', that means no correction is needed. Other values request correction, designed to make the corrected colors appear on your screen the way they would have appeared without correction on an ordinary monitor with a gamma value of 2.2. If your monitor displays colors too light, you should specify a `screen-gamma' value smaller than 2.2. This requests correction that makes colors darker. A screen gamma value of 1.5 may give good results for LCD color displays. `alpha' This parameter specifies the opacity of the frame, on graphical displays that support variable opacity. It should be an integer between 0 and 100, where 0 means completely transparent and 100 means completely opaque. It can also have a `nil' value, which tells Emacs not to set the frame opacity (leaving it to the window manager). To prevent the frame from disappearing completely from view, the variable `frame-alpha-lower-limit' defines a lower opacity limit. If the value of the frame parameter is less than the value of this variable, Emacs uses the latter. By default, `frame-alpha-lower-limit' is 20. The `alpha' frame parameter can also be a cons cell `(`active' . `inactive')', where `active' is the opacity of the frame when it is selected, and `inactive' is the opactity when it is not selected. The following frame parameters are semi-obsolete in that they are automatically equivalent to particular face attributes of particular faces (*note Standard Faces: (emacs)Standard Faces.): `font' The name of the font for displaying text in the frame. This is a string, either a valid font name for your system or the name of an Emacs fontset (*note Fontsets::). It is equivalent to the `font' attribute of the `default' face. `foreground-color' The color to use for the image of a character. It is equivalent to the `:foreground' attribute of the `default' face. `background-color' The color to use for the background of characters. It is equivalent to the `:background' attribute of the `default' face. `mouse-color' The color for the mouse pointer. It is equivalent to the `:background' attribute of the `mouse' face. `cursor-color' The color for the cursor that shows point. It is equivalent to the `:background' attribute of the `cursor' face. `border-color' The color for the border of the frame. It is equivalent to the `:background' attribute of the `border' face. `scroll-bar-foreground' If non-`nil', the color for the foreground of scroll bars. It is equivalent to the `:foreground' attribute of the `scroll-bar' face. `scroll-bar-background' If non-`nil', the color for the background of scroll bars. It is equivalent to the `:background' attribute of the `scroll-bar' face.  File: elisp, Node: Size and Position, Next: Geometry, Prev: Window Frame Parameters, Up: Frame Parameters 29.3.4 Frame Size And Position ------------------------------ You can read or change the size and position of a frame using the frame parameters `left', `top', `height', and `width'. Whatever geometry parameters you don't specify are chosen by the window manager in its usual fashion. Here are some special features for working with sizes and positions. (For the precise meaning of "selected frame" used by these functions, see *note Input Focus::.) -- Function: set-frame-position frame left top This function sets the position of the top left corner of FRAME to LEFT and TOP. These arguments are measured in pixels, and normally count from the top left corner of the screen. Negative parameter values position the bottom edge of the window up from the bottom edge of the screen, or the right window edge to the left of the right edge of the screen. It would probably be better if the values were always counted from the left and top, so that negative arguments would position the frame partly off the top or left edge of the screen, but it seems inadvisable to change that now. -- Function: frame-height &optional frame -- Function: frame-width &optional frame These functions return the height and width of FRAME, measured in lines and columns. If you don't supply FRAME, they use the selected frame. -- Function: frame-pixel-height &optional frame -- Function: frame-pixel-width &optional frame These functions return the height and width of the main display area of FRAME, measured in pixels. If you don't supply FRAME, they use the selected frame. For a text-only terminal, the results are in characters rather than pixels. These values include the internal borders, and windows' scroll bars and fringes (which belong to individual windows, not to the frame itself). The exact value of the heights depends on the window-system and toolkit in use. With Gtk+, the height does not include any tool bar or menu bar. With the Motif or Lucid toolkits, it includes the tool bar but not the menu bar. In a graphical version with no toolkit, it includes both the tool bar and menu bar. For a text-only terminal, the result includes the menu bar. -- Function: frame-char-height &optional frame -- Function: frame-char-width &optional frame These functions return the height and width of a character in FRAME, measured in pixels. The values depend on the choice of font. If you don't supply FRAME, these functions use the selected frame. -- Function: set-frame-size frame cols rows This function sets the size of FRAME, measured in characters; COLS and ROWS specify the new width and height. To set the size based on values measured in pixels, use `frame-char-height' and `frame-char-width' to convert them to units of characters. -- Function: set-frame-height frame lines &optional pretend This function resizes FRAME to a height of LINES lines. The sizes of existing windows in FRAME are altered proportionally to fit. If PRETEND is non-`nil', then Emacs displays LINES lines of output in FRAME, but does not change its value for the actual height of the frame. This is only useful for a terminal frame. Using a smaller height than the terminal actually implements may be useful to reproduce behavior observed on a smaller screen, or if the terminal malfunctions when using its whole screen. Setting the frame height "for real" does not always work, because knowing the correct actual size may be necessary for correct cursor positioning on a terminal frame. -- Function: set-frame-width frame width &optional pretend This function sets the width of FRAME, measured in characters. The argument PRETEND has the same meaning as in `set-frame-height'. The older functions `set-screen-height' and `set-screen-width' were used to specify the height and width of the screen, in Emacs versions that did not support multiple frames. They are semi-obsolete, but still work; they apply to the selected frame.  File: elisp, Node: Geometry, Prev: Size and Position, Up: Frame Parameters 29.3.5 Geometry --------------- Here's how to examine the data in an X-style window geometry specification: -- Function: x-parse-geometry geom The function `x-parse-geometry' converts a standard X window geometry string to an alist that you can use as part of the argument to `make-frame'. The alist describes which parameters were specified in GEOM, and gives the values specified for them. Each element looks like `(PARAMETER . VALUE)'. The possible PARAMETER values are `left', `top', `width', and `height'. For the size parameters, the value must be an integer. The position parameter names `left' and `top' are not totally accurate, because some values indicate the position of the right or bottom edges instead. The VALUE possibilities for the position parameters are: an integer, a list `(+ POS)', or a list `(- POS)'; as previously described (*note Position Parameters::). Here is an example: (x-parse-geometry "35x70+0-0") => ((height . 70) (width . 35) (top - 0) (left . 0))  File: elisp, Node: Terminal Parameters, Next: Frame Titles, Prev: Frame Parameters, Up: Frames 29.4 Terminal Parameters ======================== Each terminal has a list of associated parameters. These "terminal parameters" are mostly a convenient way of storage for terminal-local variables, but some terminal parameters have a special meaning. This section describes functions to read and change the parameter values of a terminal. They all accept as their argument either a terminal or a frame; the latter means use that frame's terminal. An argument of `nil' means the selected frame's terminal. -- Function: terminal-parameters &optional terminal This function returns an alist listing all the parameters of TERMINAL and their values. -- Function: terminal-parameter terminal parameter This function returns the value of the parameter PARAMETER (a symbol) of TERMINAL. If TERMINAL has no setting for PARAMETER, this function returns `nil'. -- Function: set-terminal-parameter terminal parameter value This function sets the parameter PARM of TERMINAL to the specified VALUE, and returns the previous value of that parameter. Here's a list of a few terminal parameters that have a special meaning: `background-mode' The classification of the terminal's background color, either `light' or `dark'. `normal-erase-is-backspace' Value is either 1 or 0, depending on whether `normal-erase-is-backspace-mode' is turned on or off on this terminal. *Note DEL Does Not Delete: (emacs)DEL Does Not Delete. `terminal-initted' After the terminal is initialized, this is set to the terminal-specific initialization function.  File: elisp, Node: Frame Titles, Next: Deleting Frames, Prev: Terminal Parameters, Up: Frames 29.5 Frame Titles ================= Every frame has a `name' parameter; this serves as the default for the frame title which window systems typically display at the top of the frame. You can specify a name explicitly by setting the `name' frame property. Normally you don't specify the name explicitly, and Emacs computes the frame name automatically based on a template stored in the variable `frame-title-format'. Emacs recomputes the name each time the frame is redisplayed. -- Variable: frame-title-format This variable specifies how to compute a name for a frame when you have not explicitly specified one. The variable's value is actually a mode line construct, just like `mode-line-format', except that the `%c' and `%l' constructs are ignored. *Note Mode Line Data::. -- Variable: icon-title-format This variable specifies how to compute the name for an iconified frame, when you have not explicitly specified the frame title. This title appears in the icon itself. -- Variable: multiple-frames This variable is set automatically by Emacs. Its value is `t' when there are two or more frames (not counting minibuffer-only frames or invisible frames). The default value of `frame-title-format' uses `multiple-frames' so as to put the buffer name in the frame title only when there is more than one frame. The value of this variable is not guaranteed to be accurate except while processing `frame-title-format' or `icon-title-format'.  File: elisp, Node: Deleting Frames, Next: Finding All Frames, Prev: Frame Titles, Up: Frames 29.6 Deleting Frames ==================== Frames remain potentially visible until you explicitly "delete" them. A deleted frame cannot appear on the screen, but continues to exist as a Lisp object until there are no references to it. -- Command: delete-frame &optional frame force This function deletes the frame FRAME. Unless FRAME is a tooltip, it first runs the hook `delete-frame-functions' (each function gets one argument, FRAME). By default, FRAME is the selected frame. A frame cannot be deleted if its minibuffer is used by other frames. Normally, you cannot delete a frame if all other frames are invisible, but if FORCE is non-`nil', then you are allowed to do so. -- Function: frame-live-p frame The function `frame-live-p' returns non-`nil' if the frame FRAME has not been deleted. The possible non-`nil' return values are like those of `framep'. *Note Frames::. Some window managers provide a command to delete a window. These work by sending a special message to the program that operates the window. When Emacs gets one of these commands, it generates a `delete-frame' event, whose normal definition is a command that calls the function `delete-frame'. *Note Misc Events::.  File: elisp, Node: Finding All Frames, Next: Frames and Windows, Prev: Deleting Frames, Up: Frames 29.7 Finding All Frames ======================= -- Function: frame-list The function `frame-list' returns a list of all the live frames, i.e. those that have not been deleted. It is analogous to `buffer-list' for buffers, and includes frames on all terminals. The list that you get is newly created, so modifying the list doesn't have any effect on the internals of Emacs. -- Function: visible-frame-list This function returns a list of just the currently visible frames. *Note Visibility of Frames::. (Terminal frames always count as "visible," even though only the selected one is actually displayed.) -- Function: next-frame &optional frame minibuf The function `next-frame' lets you cycle conveniently through all the frames on the current display from an arbitrary starting point. It returns the "next" frame after FRAME in the cycle. If FRAME is omitted or `nil', it defaults to the selected frame (*note Input Focus::). The second argument, MINIBUF, says which frames to consider: `nil' Exclude minibuffer-only frames. `visible' Consider all visible frames. 0 Consider all visible or iconified frames. a window Consider only the frames using that particular window as their minibuffer. anything else Consider all frames. -- Function: previous-frame &optional frame minibuf Like `next-frame', but cycles through all frames in the opposite direction. See also `next-window' and `previous-window', in *note Cyclic Window Ordering::.  File: elisp, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames 29.8 Frames and Windows ======================= Each window is part of one and only one frame; you can get that frame with `window-frame'. -- Function: window-frame window This function returns the frame that WINDOW is on. All the non-minibuffer windows in a frame are arranged in a cyclic order. The order runs from the frame's top window, which is at the upper left corner, down and to the right, until it reaches the window at the lower right corner (always the minibuffer window, if the frame has one), and then it moves back to the top. *Note Cyclic Window Ordering::. -- Function: frame-first-window &optional frame This returns the topmost, leftmost window of frame FRAME. If omitted or `nil', FRAME defaults to the selected frame. At any time, exactly one window on any frame is "selected within the frame". The significance of this designation is that selecting the frame also selects this window. Conversely, selecting a window for Emacs with `select-window' also makes that window selected within its frame. *Note Selecting Windows::. -- Function: frame-selected-window &optional frame This function returns the window on FRAME that is selected within FRAME. If omitted or `nil', FRAME defaults to the selected frame. -- Function: set-frame-selected-window frame window &optional norecord This sets the selected window of frame FRAME to WINDOW. If FRAME is `nil', it operates on the selected frame. If FRAME is the selected frame, this makes WINDOW the selected window. This function returns WINDOW. Optional argument NORECORD non-`nil' means to neither change the order of recently selected windows nor the buffer list (*note The Buffer List::). Another function that (usually) returns one of the windows in a given frame is `minibuffer-window'. *Note Definition of minibuffer-window::.  File: elisp, Node: Minibuffers and Frames, Next: Input Focus, Prev: Frames and Windows, Up: Frames 29.9 Minibuffers and Frames =========================== Normally, each frame has its own minibuffer window at the bottom, which is used whenever that frame is selected. If the frame has a minibuffer, you can get it with `minibuffer-window' (*note Definition of minibuffer-window::). However, you can also create a frame with no minibuffer. Such a frame must use the minibuffer window of some other frame. When you create the frame, you can specify explicitly the minibuffer window to use (in some other frame). If you don't, then the minibuffer is found in the frame which is the value of the variable `default-minibuffer-frame'. Its value should be a frame that does have a minibuffer. If you use a minibuffer-only frame, you might want that frame to raise when you enter the minibuffer. If so, set the variable `minibuffer-auto-raise' to `t'. *Note Raising and Lowering::. -- Variable: default-minibuffer-frame This variable specifies the frame to use for the minibuffer window, by default. It does not affect existing frames. It is always local to the current terminal and cannot be buffer-local. *Note Multiple Terminals::.  File: elisp, Node: Input Focus, Next: Visibility of Frames, Prev: Minibuffers and Frames, Up: Frames 29.10 Input Focus ================= At any time, one frame in Emacs is the "selected frame". The selected window always resides on the selected frame. When Emacs displays its frames on several terminals (*note Multiple Terminals::), each terminal has its own selected frame. But only one of these is "_the_ selected frame": it's the frame that belongs to the terminal from which the most recent input came. That is, when Emacs runs a command that came from a certain terminal, the selected frame is the one of that terminal. Since Emacs runs only a single command at any given time, it needs to consider only one selected frame at a time; this frame is what we call "the selected frame" in this manual. The display on which the selected frame is shown is the "selected frame's display". -- Function: selected-frame This function returns the selected frame. Some window systems and window managers direct keyboard input to the window object that the mouse is in; others require explicit clicks or commands to "shift the focus" to various window objects. Either way, Emacs automatically keeps track of which frame has the focus. To explicitly switch to a different frame from a Lisp function, call `select-frame-set-input-focus'. Lisp programs can also switch frames "temporarily" by calling the function `select-frame'. This does not alter the window system's concept of focus; rather, it escapes from the window manager's control until that control is somehow reasserted. When using a text-only terminal, only one frame can be displayed at a time on the terminal, so after a call to `select-frame', the next redisplay actually displays the newly selected frame. This frame remains selected until a subsequent call to `select-frame'. Each terminal frame has a number which appears in the mode line before the buffer name (*note Mode Line Variables::). -- Function: select-frame-set-input-focus frame This function selects FRAME, raises it (should it happen to be obscured by other frames) and tries to give it the X server's focus. On a text-only terminal, the next redisplay displays the new frame on the entire terminal screen. The return value of this function is not significant. -- Function: select-frame frame &optional norecord This function selects frame FRAME, temporarily disregarding the focus of the X server if any. The selection of FRAME lasts until the next time the user does something to select a different frame, or until the next time this function is called. (If you are using a window system, the previously selected frame may be restored as the selected frame after return to the command loop, because it still may have the window system's input focus.) The specified FRAME becomes the selected frame, as explained above, and the terminal that FRAME is on becomes the selected terminal. The window selected within FRAME becomes the selected window. This function returns FRAME, or `nil' if FRAME has been deleted. Optional argument NORECORD non-`nil' means to neither change the order of recently selected windows nor the buffer list. *Note The Buffer List::. In general, you should never use `select-frame' in a way that could switch to a different terminal without switching back when you're done. Emacs cooperates with the window system by arranging to select frames as the server and window manager request. It does so by generating a special kind of input event, called a "focus" event, when appropriate. The command loop handles a focus event by calling `handle-switch-frame'. *Note Focus Events::. -- Command: handle-switch-frame frame This function handles a focus event by selecting frame FRAME. Focus events normally do their job by invoking this command. Don't call it for any other reason. -- Function: redirect-frame-focus frame &optional focus-frame This function redirects focus from FRAME to FOCUS-FRAME. This means that FOCUS-FRAME will receive subsequent keystrokes and events intended for FRAME. After such an event, the value of `last-event-frame' will be FOCUS-FRAME. Also, switch-frame events specifying FRAME will instead select FOCUS-FRAME. If FOCUS-FRAME is omitted or `nil', that cancels any existing redirection for FRAME, which therefore once again receives its own events. One use of focus redirection is for frames that don't have minibuffers. These frames use minibuffers on other frames. Activating a minibuffer on another frame redirects focus to that frame. This puts the focus on the minibuffer's frame, where it belongs, even though the mouse remains in the frame that activated the minibuffer. Selecting a frame can also change focus redirections. Selecting frame `bar', when `foo' had been selected, changes any redirections pointing to `foo' so that they point to `bar' instead. This allows focus redirection to work properly when the user switches from one frame to another using `select-window'. This means that a frame whose focus is redirected to itself is treated differently from a frame whose focus is not redirected. `select-frame' affects the former but not the latter. The redirection lasts until `redirect-frame-focus' is called to change it. -- User Option: focus-follows-mouse This option is how you inform Emacs whether the window manager transfers focus when the user moves the mouse. Non-`nil' says that it does. When this is so, the command `other-frame' moves the mouse to a position consistent with the new selected frame.  File: elisp, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames 29.11 Visibility of Frames ========================== A window frame may be "visible", "invisible", or "iconified". If it is visible, you can see its contents, unless other windows cover it. If it is iconified, the frame's contents do not appear on the screen, but an icon does. (Note: because of the way in which some window managers implement the concept of multiple workspaces, or desktops, all frames on other workspaces may appear to Emacs to be iconified.) If the frame is invisible, it doesn't show on the screen, not even as an icon. Visibility is meaningless for terminal frames, since only the selected one is actually displayed in any case. -- Command: make-frame-visible &optional frame This function makes frame FRAME visible. If you omit FRAME, it makes the selected frame visible. This does not raise the frame, but you can do that with `raise-frame' if you wish (*note Raising and Lowering::). -- Command: make-frame-invisible &optional frame force This function makes frame FRAME invisible. If you omit FRAME, it makes the selected frame invisible. Unless FORCE is non-`nil', this function refuses to make FRAME invisible if all other frames are invisible.. -- Command: iconify-frame &optional frame This function iconifies frame FRAME. If you omit FRAME, it iconifies the selected frame. -- Function: frame-visible-p frame This returns the visibility status of frame FRAME. The value is `t' if FRAME is visible, `nil' if it is invisible, and `icon' if it is iconified. On a text-only terminal, all frames are considered visible, whether they are currently being displayed or not, and this function returns `t' for all frames. The visibility status of a frame is also available as a frame parameter. You can read or change it as such. *Note Management Parameters::. The user can iconify and deiconify frames with the window manager. This happens below the level at which Emacs can exert any control, but Emacs does provide events that you can use to keep track of such changes. *Note Misc Events::.  File: elisp, Node: Raising and Lowering, Next: Frame Configurations, Prev: Visibility of Frames, Up: Frames 29.12 Raising and Lowering Frames ================================= Most window systems use a desktop metaphor. Part of this metaphor is the idea that windows are stacked in a notional third dimension perpendicular to the screen surface, and thus ordered from "highest" to "lowest." Where two windows overlap, the one higher up covers the one underneath. Even a window at the bottom of the stack can be seen if no other window overlaps it. A window's place in this ordering is not fixed; in fact, users tend to change the order frequently. "Raising" a window means moving it "up," to the top of the stack. "Lowering" a window means moving it to the bottom of the stack. This motion is in the notional third dimension only, and does not change the position of the window on the screen. With Emacs, frames constitute the windows in the metaphor sketched above. You can raise and lower frames using these functions: -- Command: raise-frame &optional frame This function raises frame FRAME (default, the selected frame). If FRAME is invisible or iconified, this makes it visible. -- Command: lower-frame &optional frame This function lowers frame FRAME (default, the selected frame). -- User Option: minibuffer-auto-raise If this is non-`nil', activation of the minibuffer raises the frame that the minibuffer window is in. You can also enable auto-raise (raising automatically when a frame is selected) or auto-lower (lowering automatically when it is deselected) for any frame using frame parameters. *Note Management Parameters::.  File: elisp, Node: Frame Configurations, Next: Mouse Tracking, Prev: Raising and Lowering, Up: Frames 29.13 Frame Configurations ========================== A "frame configuration" records the current arrangement of frames, all their properties, and the window configuration of each one. (*Note Window Configurations::.) -- Function: current-frame-configuration This function returns a frame configuration list that describes the current arrangement of frames and their contents. -- Function: set-frame-configuration configuration &optional nodelete This function restores the state of frames described in CONFIGURATION. However, this function does not restore deleted frames. Ordinarily, this function deletes all existing frames not listed in CONFIGURATION. But if NODELETE is non-`nil', the unwanted frames are iconified instead.  File: elisp, Node: Mouse Tracking, Next: Mouse Position, Prev: Frame Configurations, Up: Frames 29.14 Mouse Tracking ==================== Sometimes it is useful to "track" the mouse, which means to display something to indicate where the mouse is and move the indicator as the mouse moves. For efficient mouse tracking, you need a way to wait until the mouse actually moves. The convenient way to track the mouse is to ask for events to represent mouse motion. Then you can wait for motion by waiting for an event. In addition, you can easily handle any other sorts of events that may occur. That is useful, because normally you don't want to track the mouse forever--only until some other event, such as the release of a button. -- Special Form: track-mouse body... This special form executes BODY, with generation of mouse motion events enabled. Typically, BODY would use `read-event' to read the motion events and modify the display accordingly. *Note Motion Events::, for the format of mouse motion events. The value of `track-mouse' is that of the last form in BODY. You should design BODY to return when it sees the up-event that indicates the release of the button, or whatever kind of event means it is time to stop tracking. The usual purpose of tracking mouse motion is to indicate on the screen the consequences of pushing or releasing a button at the current position. In many cases, you can avoid the need to track the mouse by using the `mouse-face' text property (*note Special Properties::). That works at a much lower level and runs more smoothly than Lisp-level mouse tracking.  File: elisp, Node: Mouse Position, Next: Pop-Up Menus, Prev: Mouse Tracking, Up: Frames 29.15 Mouse Position ==================== The functions `mouse-position' and `set-mouse-position' give access to the current position of the mouse. -- Function: mouse-position This function returns a description of the position of the mouse. The value looks like `(FRAME X . Y)', where X and Y are integers giving the position in characters relative to the top left corner of the inside of FRAME. -- Variable: mouse-position-function If non-`nil', the value of this variable is a function for `mouse-position' to call. `mouse-position' calls this function just before returning, with its normal return value as the sole argument, and it returns whatever this function returns to it. This abnormal hook exists for the benefit of packages like `xt-mouse.el' that need to do mouse handling at the Lisp level. -- Function: set-mouse-position frame x y This function "warps the mouse" to position X, Y in frame FRAME. The arguments X and Y are integers, giving the position in characters relative to the top left corner of the inside of FRAME. If FRAME is not visible, this function does nothing. The return value is not significant. -- Function: mouse-pixel-position This function is like `mouse-position' except that it returns coordinates in units of pixels rather than units of characters. -- Function: set-mouse-pixel-position frame x y This function warps the mouse like `set-mouse-position' except that X and Y are in units of pixels rather than units of characters. These coordinates are not required to be within the frame. If FRAME is not visible, this function does nothing. The return value is not significant.  File: elisp, Node: Pop-Up Menus, Next: Dialog Boxes, Prev: Mouse Position, Up: Frames 29.16 Pop-Up Menus ================== When using a window system, a Lisp program can pop up a menu so that the user can choose an alternative with the mouse. -- Function: x-popup-menu position menu This function displays a pop-up menu and returns an indication of what selection the user makes. The argument POSITION specifies where on the screen to put the top left corner of the menu. It can be either a mouse button event (which says to put the menu where the user actuated the button) or a list of this form: ((XOFFSET YOFFSET) WINDOW) where XOFFSET and YOFFSET are coordinates, measured in pixels, counting from the top left corner of WINDOW. WINDOW may be a window or a frame. If POSITION is `t', it means to use the current mouse position. If POSITION is `nil', it means to precompute the key binding equivalents for the keymaps specified in MENU, without actually displaying or popping up the menu. The argument MENU says what to display in the menu. It can be a keymap or a list of keymaps (*note Menu Keymaps::). In this case, the return value is the list of events corresponding to the user's choice. (This list has more than one element if the choice occurred in a submenu.) Note that `x-popup-menu' does not actually execute the command bound to that sequence of events. Alternatively, MENU can have the following form: (TITLE PANE1 PANE2...) where each pane is a list of form (TITLE ITEM1 ITEM2...) Each item should normally be a cons cell `(LINE . VALUE)', where LINE is a string, and VALUE is the value to return if that LINE is chosen. An item can also be a string; this makes a non-selectable line in the menu. If the user gets rid of the menu without making a valid choice, for instance by clicking the mouse away from a valid choice or by typing keyboard input, then this normally results in a quit and `x-popup-menu' does not return. But if POSITION is a mouse button event (indicating that the user invoked the menu with the mouse) then no quit occurs and `x-popup-menu' returns `nil'. *Usage note:* Don't use `x-popup-menu' to display a menu if you could do the job with a prefix key defined with a menu keymap. If you use a menu keymap to implement a menu, `C-h c' and `C-h a' can see the individual items in that menu and provide help for them. If instead you implement the menu by defining a command that calls `x-popup-menu', the help facilities cannot know what happens inside that command, so they cannot give any help for the menu's items. The menu bar mechanism, which lets you switch between submenus by moving the mouse, cannot look within the definition of a command to see that it calls `x-popup-menu'. Therefore, if you try to implement a submenu using `x-popup-menu', it cannot work with the menu bar in an integrated fashion. This is why all menu bar submenus are implemented with menu keymaps within the parent menu, and never with `x-popup-menu'. *Note Menu Bar::. If you want a menu bar submenu to have contents that vary, you should still use a menu keymap to implement it. To make the contents vary, add a hook function to `menu-bar-update-hook' to update the contents of the menu keymap as necessary.  File: elisp, Node: Dialog Boxes, Next: Pointer Shape, Prev: Pop-Up Menus, Up: Frames 29.17 Dialog Boxes ================== A dialog box is a variant of a pop-up menu--it looks a little different, it always appears in the center of a frame, and it has just one level and one or more buttons. The main use of dialog boxes is for asking questions that the user can answer with "yes," "no," and a few other alternatives. With a single button, they can also force the user to acknowledge important information. The functions `y-or-n-p' and `yes-or-no-p' use dialog boxes instead of the keyboard, when called from commands invoked by mouse clicks. -- Function: x-popup-dialog position contents &optional header This function displays a pop-up dialog box and returns an indication of what selection the user makes. The argument CONTENTS specifies the alternatives to offer; it has this format: (TITLE (STRING . VALUE)...) which looks like the list that specifies a single pane for `x-popup-menu'. The return value is VALUE from the chosen alternative. As for `x-popup-menu', an element of the list may be just a string instead of a cons cell `(STRING . VALUE)'. That makes a box that cannot be selected. If `nil' appears in the list, it separates the left-hand items from the right-hand items; items that precede the `nil' appear on the left, and items that follow the `nil' appear on the right. If you don't include a `nil' in the list, then approximately half the items appear on each side. Dialog boxes always appear in the center of a frame; the argument POSITION specifies which frame. The possible values are as in `x-popup-menu', but the precise coordinates or the individual window don't matter; only the frame matters. If HEADER is non-`nil', the frame title for the box is `Information', otherwise it is `Question'. The former is used for `message-box' (*note message-box::). In some configurations, Emacs cannot display a real dialog box; so instead it displays the same items in a pop-up menu in the center of the frame. If the user gets rid of the dialog box without making a valid choice, for instance using the window manager, then this produces a quit and `x-popup-dialog' does not return.  File: elisp, Node: Pointer Shape, Next: Window System Selections, Prev: Dialog Boxes, Up: Frames 29.18 Pointer Shape =================== You can specify the mouse pointer style for particular text or images using the `pointer' text property, and for images with the `:pointer' and `:map' image properties. The values you can use in these properties are `text' (or `nil'), `arrow', `hand', `vdrag', `hdrag', `modeline', and `hourglass'. `text' stands for the usual mouse pointer style used over text. Over void parts of the window (parts that do not correspond to any of the buffer contents), the mouse pointer usually uses the `arrow' style, but you can specify a different style (one of those above) by setting `void-text-area-pointer'. -- Variable: void-text-area-pointer This variable specifies the mouse pointer style for void text areas. These include the areas after the end of a line or below the last line in the buffer. The default is to use the `arrow' (non-text) pointer style. When using X, you can specify what the `text' pointer style really looks like by setting the variable `x-pointer-shape'. -- Variable: x-pointer-shape This variable specifies the pointer shape to use ordinarily in the Emacs frame, for the `text' pointer style. -- Variable: x-sensitive-text-pointer-shape This variable specifies the pointer shape to use when the mouse is over mouse-sensitive text. These variables affect newly created frames. They do not normally affect existing frames; however, if you set the mouse color of a frame, that also installs the current value of those two variables. *Note Font and Color Parameters::. The values you can use, to specify either of these pointer shapes, are defined in the file `lisp/term/x-win.el'. Use `M-x apropos x-pointer ' to see a list of them.  File: elisp, Node: Window System Selections, Next: Drag and Drop, Prev: Pointer Shape, Up: Frames 29.19 Window System Selections ============================== The X server records a set of "selections" which permit transfer of data between application programs. The various selections are distinguished by "selection types", represented in Emacs by symbols. X clients including Emacs can read or set the selection for any given type. -- Command: x-set-selection type data This function sets a "selection" in the X server. It takes two arguments: a selection type TYPE, and the value to assign to it, DATA. If DATA is `nil', it means to clear out the selection. Otherwise, DATA may be a string, a symbol, an integer (or a cons of two integers or list of two integers), an overlay, or a cons of two markers pointing to the same buffer. An overlay or a pair of markers stands for text in the overlay or between the markers. The argument DATA may also be a vector of valid non-vector selection values. Each possible TYPE has its own selection value, which changes independently. The usual values of TYPE are `PRIMARY', `SECONDARY' and `CLIPBOARD'; these are symbols with upper-case names, in accord with X Window System conventions. If TYPE is `nil', that stands for `PRIMARY'. This function returns DATA. -- Function: x-get-selection &optional type data-type This function accesses selections set up by Emacs or by other X clients. It takes two optional arguments, TYPE and DATA-TYPE. The default for TYPE, the selection type, is `PRIMARY'. The DATA-TYPE argument specifies the form of data conversion to use, to convert the raw data obtained from another X client into Lisp data. Meaningful values include `TEXT', `STRING', `UTF8_STRING', `TARGETS', `LENGTH', `DELETE', `FILE_NAME', `CHARACTER_POSITION', `NAME', `LINE_NUMBER', `COLUMN_NUMBER', `OWNER_OS', `HOST_NAME', `USER', `CLASS', `ATOM', and `INTEGER'. (These are symbols with upper-case names in accord with X conventions.) The default for DATA-TYPE is `STRING'. The X server also has a set of eight numbered "cut buffers" which can store text or other data being moved between applications. Cut buffers are considered obsolete, but Emacs supports them for the sake of X clients that still use them. Cut buffers are numbered from 0 to 7. -- Function: x-get-cut-buffer &optional n This function returns the contents of cut buffer number N. If omitted N defaults to 0. -- Function: x-set-cut-buffer string &optional push This function stores STRING into the first cut buffer (cut buffer 0). If PUSH is `nil', only the first cut buffer is changed. If PUSH is non-`nil', that says to move the values down through the series of cut buffers, much like the way successive kills in Emacs move down the kill ring. In other words, the previous value of the first cut buffer moves into the second cut buffer, and the second to the third, and so on through all eight cut buffers. -- User Option: selection-coding-system This variable specifies the coding system to use when reading and writing selections or the clipboard. *Note Coding Systems::. The default is `compound-text-with-extensions', which converts to the text representation that X11 normally uses. When Emacs runs on MS-Windows, it does not implement X selections in general, but it does support the clipboard. `x-get-selection' and `x-set-selection' on MS-Windows support the text data type only; if the clipboard holds other types of data, Emacs treats the clipboard as empty. -- User Option: x-select-enable-clipboard If this is non-`nil', the Emacs yank functions consult the clipboard before the primary selection, and the kill functions store in the clipboard as well as the primary selection. Otherwise they do not access the clipboard at all. The default is `nil' on most systems, but `t' on MS-Windows.  File: elisp, Node: Drag and Drop, Next: Color Names, Prev: Window System Selections, Up: Frames 29.20 Drag and Drop =================== When a user drags something from another application over Emacs, that other application expects Emacs to tell it if Emacs can handle the data that is dragged. The variable `x-dnd-test-function' is used by Emacs to determine what to reply. The default value is `x-dnd-default-test-function' which accepts drops if the type of the data to be dropped is present in `x-dnd-known-types'. You can customize `x-dnd-test-function' and/or `x-dnd-known-types' if you want Emacs to accept or reject drops based on some other criteria. If you want to change the way Emacs handles drop of different types or add a new type, customize `x-dnd-types-alist'. This requires detailed knowledge of what types other applications use for drag and drop. When an URL is dropped on Emacs it may be a file, but it may also be another URL type (ftp, http, etc.). Emacs first checks `dnd-protocol-alist' to determine what to do with the URL. If there is no match there and if `browse-url-browser-function' is an alist, Emacs looks for a match there. If no match is found the text for the URL is inserted. If you want to alter Emacs behavior, you can customize these variables.  File: elisp, Node: Color Names, Next: Text Terminal Colors, Prev: Drag and Drop, Up: Frames 29.21 Color Names ================= A color name is text (usually in a string) that specifies a color. Symbolic names such as `black', `white', `red', etc., are allowed; use `M-x list-colors-display' to see a list of defined names. You can also specify colors numerically in forms such as `#RGB' and `RGB:R/G/B', where R specifies the red level, G specifies the green level, and B specifies the blue level. You can use either one, two, three, or four hex digits for R; then you must use the same number of hex digits for all G and B as well, making either 3, 6, 9 or 12 hex digits in all. (See the documentation of the X Window System for more details about numerical RGB specification of colors.) These functions provide a way to determine which color names are valid, and what they look like. In some cases, the value depends on the "selected frame", as described below; see *note Input Focus::, for the meaning of the term "selected frame." To read user input of color names with completion, use `read-color' (*note read-color: High-Level Completion.). -- Function: color-defined-p color &optional frame This function reports whether a color name is meaningful. It returns `t' if so; otherwise, `nil'. The argument FRAME says which frame's display to ask about; if FRAME is omitted or `nil', the selected frame is used. Note that this does not tell you whether the display you are using really supports that color. When using X, you can ask for any defined color on any kind of display, and you will get some result--typically, the closest it can do. To determine whether a frame can really display a certain color, use `color-supported-p' (see below). This function used to be called `x-color-defined-p', and that name is still supported as an alias. -- Function: defined-colors &optional frame This function returns a list of the color names that are defined and supported on frame FRAME (default, the selected frame). If FRAME does not support colors, the value is `nil'. This function used to be called `x-defined-colors', and that name is still supported as an alias. -- Function: color-supported-p color &optional frame background-p This returns `t' if FRAME can really display the color COLOR (or at least something close to it). If FRAME is omitted or `nil', the question applies to the selected frame. Some terminals support a different set of colors for foreground and background. If BACKGROUND-P is non-`nil', that means you are asking whether COLOR can be used as a background; otherwise you are asking whether it can be used as a foreground. The argument COLOR must be a valid color name. -- Function: color-gray-p color &optional frame This returns `t' if COLOR is a shade of gray, as defined on FRAME's display. If FRAME is omitted or `nil', the question applies to the selected frame. If COLOR is not a valid color name, this function returns `nil'. -- Function: color-values color &optional frame This function returns a value that describes what COLOR should ideally look like on FRAME. If COLOR is defined, the value is a list of three integers, which give the amount of red, the amount of green, and the amount of blue. Each integer ranges in principle from 0 to 65535, but some displays may not use the full range. This three-element list is called the "rgb values" of the color. If COLOR is not defined, the value is `nil'. (color-values "black") => (0 0 0) (color-values "white") => (65280 65280 65280) (color-values "red") => (65280 0 0) (color-values "pink") => (65280 49152 51968) (color-values "hungry") => nil The color values are returned for FRAME's display. If FRAME is omitted or `nil', the information is returned for the selected frame's display. If the frame cannot display colors, the value is `nil'. This function used to be called `x-color-values', and that name is still supported as an alias.  File: elisp, Node: Text Terminal Colors, Next: Resources, Prev: Color Names, Up: Frames 29.22 Text Terminal Colors ========================== Text-only terminals usually support only a small number of colors, and the computer uses small integers to select colors on the terminal. This means that the computer cannot reliably tell what the selected color looks like; instead, you have to inform your application which small integers correspond to which colors. However, Emacs does know the standard set of colors and will try to use them automatically. The functions described in this section control how terminal colors are used by Emacs. Several of these functions use or return "rgb values", described in *note Color Names::. These functions accept a display (either a frame or the name of a terminal) as an optional argument. We hope in the future to make Emacs support different colors on different text-only terminals; then this argument will specify which terminal to operate on (the default being the selected frame's terminal; *note Input Focus::). At present, though, the FRAME argument has no effect. -- Function: tty-color-define name number &optional rgb frame This function associates the color name NAME with color number NUMBER on the terminal. The optional argument RGB, if specified, is an rgb value, a list of three numbers that specify what the color actually looks like. If you do not specify RGB, then this color cannot be used by `tty-color-approximate' to approximate other colors, because Emacs will not know what it looks like. -- Function: tty-color-clear &optional frame This function clears the table of defined colors for a text-only terminal. -- Function: tty-color-alist &optional frame This function returns an alist recording the known colors supported by a text-only terminal. Each element has the form `(NAME NUMBER . RGB)' or `(NAME NUMBER)'. Here, NAME is the color name, NUMBER is the number used to specify it to the terminal. If present, RGB is a list of three color values (for red, green, and blue) that says what the color actually looks like. -- Function: tty-color-approximate rgb &optional frame This function finds the closest color, among the known colors supported for DISPLAY, to that described by the rgb value RGB (a list of color values). The return value is an element of `tty-color-alist'. -- Function: tty-color-translate color &optional frame This function finds the closest color to COLOR among the known colors supported for DISPLAY and returns its index (an integer). If the name COLOR is not defined, the value is `nil'.  File: elisp, Node: Resources, Next: Display Feature Testing, Prev: Text Terminal Colors, Up: Frames 29.23 X Resources ================= This section describes some of the functions and variables for querying and using X resources, or their equivalent on your operating system. *Note X Resources: (emacs)X Resources, for more information about X resources. -- Function: x-get-resource attribute class &optional component subclass The function `x-get-resource' retrieves a resource value from the X Window defaults database. Resources are indexed by a combination of a "key" and a "class". This function searches using a key of the form `INSTANCE.ATTRIBUTE' (where INSTANCE is the name under which Emacs was invoked), and using `Emacs.CLASS' as the class. The optional arguments COMPONENT and SUBCLASS add to the key and the class, respectively. You must specify both of them or neither. If you specify them, the key is `INSTANCE.COMPONENT.ATTRIBUTE', and the class is `Emacs.CLASS.SUBCLASS'. -- Variable: x-resource-class This variable specifies the application name that `x-get-resource' should look up. The default value is `"Emacs"'. You can examine X resources for application names other than "Emacs" by binding this variable to some other string, around a call to `x-get-resource'. -- Variable: x-resource-name This variable specifies the instance name that `x-get-resource' should look up. The default value is the name Emacs was invoked with, or the value specified with the `-name' or `-rn' switches. To illustrate some of the above, suppose that you have the line: xterm.vt100.background: yellow in your X resources file (whose name is usually `~/.Xdefaults' or `~/.Xresources'). Then: (let ((x-resource-class "XTerm") (x-resource-name "xterm")) (x-get-resource "vt100.background" "VT100.Background")) => "yellow" (let ((x-resource-class "XTerm") (x-resource-name "xterm")) (x-get-resource "background" "VT100" "vt100" "Background")) => "yellow" -- Variable: inhibit-x-resources If this variable is non-`nil', Emacs does not look up X resources, and X resources do not have any effect when creating new frames.  File: elisp, Node: Display Feature Testing, Prev: Resources, Up: Frames 29.24 Display Feature Testing ============================= The functions in this section describe the basic capabilities of a particular display. Lisp programs can use them to adapt their behavior to what the display can do. For example, a program that ordinarily uses a popup menu could use the minibuffer if popup menus are not supported. The optional argument DISPLAY in these functions specifies which display to ask the question about. It can be a display name, a frame (which designates the display that frame is on), or `nil' (which refers to the selected frame's display, *note Input Focus::). *Note Color Names::, *note Text Terminal Colors::, for other functions to obtain information about displays. -- Function: display-popup-menus-p &optional display This function returns `t' if popup menus are supported on DISPLAY, `nil' if not. Support for popup menus requires that the mouse be available, since the user cannot choose menu items without a mouse. -- Function: display-graphic-p &optional display This function returns `t' if DISPLAY is a graphic display capable of displaying several frames and several different fonts at once. This is true for displays that use a window system such as X, and false for text-only terminals. -- Function: display-mouse-p &optional display This function returns `t' if DISPLAY has a mouse available, `nil' if not. -- Function: display-color-p &optional display This function returns `t' if the screen is a color screen. It used to be called `x-display-color-p', and that name is still supported as an alias. -- Function: display-grayscale-p &optional display This function returns `t' if the screen can display shades of gray. (All color displays can do this.) -- Function: display-supports-face-attributes-p attributes &optional display This function returns non-`nil' if all the face attributes in ATTRIBUTES are supported (*note Face Attributes::). The definition of `supported' is somewhat heuristic, but basically means that a face containing all the attributes in ATTRIBUTES, when merged with the default face for display, can be represented in a way that's 1. different in appearance than the default face, and 2. `close in spirit' to what the attributes specify, if not exact. Point (2) implies that a `:weight black' attribute will be satisfied by any display that can display bold, as will `:foreground "yellow"' as long as some yellowish color can be displayed, but `:slant italic' will _not_ be satisfied by the tty display code's automatic substitution of a `dim' face for italic. -- Function: display-selections-p &optional display This function returns `t' if DISPLAY supports selections. Windowed displays normally support selections, but they may also be supported in some other cases. -- Function: display-images-p &optional display This function returns `t' if DISPLAY can display images. Windowed displays ought in principle to handle images, but some systems lack the support for that. On a display that does not support images, Emacs cannot display a tool bar. -- Function: display-screens &optional display This function returns the number of screens associated with the display. -- Function: display-pixel-height &optional display This function returns the height of the screen in pixels. On a character terminal, it gives the height in characters. For graphical terminals, note that on "multi-monitor" setups this refers to the pixel width for all physical monitors associated with DISPLAY. *Note Multiple Terminals::. -- Function: display-pixel-width &optional display This function returns the width of the screen in pixels. On a character terminal, it gives the width in characters. For graphical terminals, note that on "multi-monitor" setups this refers to the pixel width for all physical monitors associated with DISPLAY. *Note Multiple Terminals::. -- Function: display-mm-height &optional display This function returns the height of the screen in millimeters, or `nil' if Emacs cannot get that information. -- Function: display-mm-width &optional display This function returns the width of the screen in millimeters, or `nil' if Emacs cannot get that information. -- User Option: display-mm-dimensions-alist This variable allows the user to specify the dimensions of graphical displays returned by `display-mm-height' and `display-mm-width' in case the system provides incorrect values. -- Function: display-backing-store &optional display This function returns the backing store capability of the display. Backing store means recording the pixels of windows (and parts of windows) that are not exposed, so that when exposed they can be displayed very quickly. Values can be the symbols `always', `when-mapped', or `not-useful'. The function can also return `nil' when the question is inapplicable to a certain kind of display. -- Function: display-save-under &optional display This function returns non-`nil' if the display supports the SaveUnder feature. That feature is used by pop-up windows to save the pixels they obscure, so that they can pop down quickly. -- Function: display-planes &optional display This function returns the number of planes the display supports. This is typically the number of bits per pixel. For a tty display, it is log to base two of the number of colors supported. -- Function: display-visual-class &optional display This function returns the visual class for the screen. The value is one of the symbols `static-gray', `gray-scale', `static-color', `pseudo-color', `true-color', and `direct-color'. -- Function: display-color-cells &optional display This function returns the number of color cells the screen supports. These functions obtain additional information specifically about X displays. -- Function: x-server-version &optional display This function returns the list of version numbers of the X server running the display. The value is a list of three integers: the major and minor version numbers of the X protocol, and the distributor-specific release number of the X server software itself. -- Function: x-server-vendor &optional display This function returns the "vendor" that provided the X server software (as a string). Really this means whoever distributes the X server. When the developers of X labelled software distributors as "vendors," they showed their false assumption that no system could ever be developed and distributed noncommercially.  File: elisp, Node: Positions, Next: Markers, Prev: Frames, Up: Top 30 Positions ************ A "position" is the index of a character in the text of a buffer. More precisely, a position identifies the place between two characters (or before the first character, or after the last character), so we can speak of the character before or after a given position. However, we often speak of the character "at" a position, meaning the character after that position. Positions are usually represented as integers starting from 1, but can also be represented as "markers"--special objects that relocate automatically when text is inserted or deleted so they stay with the surrounding characters. Functions that expect an argument to be a position (an integer), but accept a marker as a substitute, normally ignore which buffer the marker points into; they convert the marker to an integer, and use that integer, exactly as if you had passed the integer as the argument, even if the marker points to the "wrong" buffer. A marker that points nowhere cannot convert to an integer; using it instead of an integer causes an error. *Note Markers::. See also the "field" feature (*note Fields::), which provides functions that are used by many cursor-motion commands. * Menu: * Point:: The special position where editing takes place. * Motion:: Changing point. * Excursions:: Temporary motion and buffer changes. * Narrowing:: Restricting editing to a portion of the buffer.  File: elisp, Node: Point, Next: Motion, Up: Positions 30.1 Point ========== "Point" is a special buffer position used by many editing commands, including the self-inserting typed characters and text insertion functions. Other commands move point through the text to allow editing and insertion at different places. Like other positions, point designates a place between two characters (or before the first character, or after the last character), rather than a particular character. Usually terminals display the cursor over the character that immediately follows point; point is actually before the character on which the cursor sits. The value of point is a number no less than 1, and no greater than the buffer size plus 1. If narrowing is in effect (*note Narrowing::), then point is constrained to fall within the accessible portion of the buffer (possibly at one end of it). Each buffer has its own value of point, which is independent of the value of point in other buffers. Each window also has a value of point, which is independent of the value of point in other windows on the same buffer. This is why point can have different values in various windows that display the same buffer. When a buffer appears in only one window, the buffer's point and the window's point normally have the same value, so the distinction is rarely important. *Note Window Point::, for more details. -- Function: point This function returns the value of point in the current buffer, as an integer. (point) => 175 -- Function: point-min This function returns the minimum accessible value of point in the current buffer. This is normally 1, but if narrowing is in effect, it is the position of the start of the region that you narrowed to. (*Note Narrowing::.) -- Function: point-max This function returns the maximum accessible value of point in the current buffer. This is `(1+ (buffer-size))', unless narrowing is in effect, in which case it is the position of the end of the region that you narrowed to. (*Note Narrowing::.) -- Function: buffer-end flag This function returns `(point-max)' if FLAG is greater than 0, `(point-min)' otherwise. The argument FLAG must be a number. -- Function: buffer-size &optional buffer This function returns the total number of characters in the current buffer. In the absence of any narrowing (*note Narrowing::), `point-max' returns a value one larger than this. If you specify a buffer, BUFFER, then the value is the size of BUFFER. (buffer-size) => 35 (point-max) => 36  File: elisp, Node: Motion, Next: Excursions, Prev: Point, Up: Positions 30.2 Motion =========== Motion functions change the value of point, either relative to the current value of point, relative to the beginning or end of the buffer, or relative to the edges of the selected window. *Note Point::. * Menu: * Character Motion:: Moving in terms of characters. * Word Motion:: Moving in terms of words. * Buffer End Motion:: Moving to the beginning or end of the buffer. * Text Lines:: Moving in terms of lines of text. * Screen Lines:: Moving in terms of lines as displayed. * List Motion:: Moving by parsing lists and sexps. * Skipping Characters:: Skipping characters belonging to a certain set.  File: elisp, Node: Character Motion, Next: Word Motion, Up: Motion 30.2.1 Motion by Characters --------------------------- These functions move point based on a count of characters. `goto-char' is the fundamental primitive; the other functions use that. -- Command: goto-char position This function sets point in the current buffer to the value POSITION. If POSITION is less than 1, it moves point to the beginning of the buffer. If POSITION is greater than the length of the buffer, it moves point to the end. If narrowing is in effect, POSITION still counts from the beginning of the buffer, but point cannot go outside the accessible portion. If POSITION is out of range, `goto-char' moves point to the beginning or the end of the accessible portion. When this function is called interactively, POSITION is the numeric prefix argument, if provided; otherwise it is read from the minibuffer. `goto-char' returns POSITION. -- Command: forward-char &optional count This function moves point COUNT characters forward, towards the end of the buffer (or backward, towards the beginning of the buffer, if COUNT is negative). If COUNT is `nil', the default is 1. If this attempts to move past the beginning or end of the buffer (or the limits of the accessible portion, when narrowing is in effect), it signals an error with error symbol `beginning-of-buffer' or `end-of-buffer'. In an interactive call, COUNT is the numeric prefix argument. -- Command: backward-char &optional count This is just like `forward-char' except that it moves in the opposite direction.  File: elisp, Node: Word Motion, Next: Buffer End Motion, Prev: Character Motion, Up: Motion 30.2.2 Motion by Words ---------------------- These functions for parsing words use the syntax table to decide whether a given character is part of a word. *Note Syntax Tables::. -- Command: forward-word &optional count This function moves point forward COUNT words (or backward if COUNT is negative). If COUNT is `nil', it moves forward one word. "Moving one word" means moving until point crosses a word-constituent character and then encounters a word-separator character. However, this function cannot move point past the boundary of the accessible portion of the buffer, or across a field boundary (*note Fields::). The most common case of a field boundary is the end of the prompt in the minibuffer. If it is possible to move COUNT words, without being stopped prematurely by the buffer boundary or a field boundary, the value is `t'. Otherwise, the return value is `nil' and point stops at the buffer boundary or field boundary. If `inhibit-field-text-motion' is non-`nil', this function ignores field boundaries. In an interactive call, COUNT is specified by the numeric prefix argument. If COUNT is omitted or `nil', it defaults to 1. -- Command: backward-word &optional count This function is just like `forward-word', except that it moves backward until encountering the front of a word, rather than forward. -- User Option: words-include-escapes This variable affects the behavior of `forward-word' and everything that uses it. If it is non-`nil', then characters in the "escape" and "character quote" syntax classes count as part of words. Otherwise, they do not. -- Variable: inhibit-field-text-motion If this variable is non-`nil', certain motion functions including `forward-word', `forward-sentence', and `forward-paragraph' ignore field boundaries.  File: elisp, Node: Buffer End Motion, Next: Text Lines, Prev: Word Motion, Up: Motion 30.2.3 Motion to an End of the Buffer ------------------------------------- To move point to the beginning of the buffer, write: (goto-char (point-min)) Likewise, to move to the end of the buffer, use: (goto-char (point-max)) Here are two commands that users use to do these things. They are documented here to warn you not to use them in Lisp programs, because they set the mark and display messages in the echo area. -- Command: beginning-of-buffer &optional n This function moves point to the beginning of the buffer (or the limits of the accessible portion, when narrowing is in effect), setting the mark at the previous position (except in Transient Mark mode, if the mark is already active, it does not set the mark.) If N is non-`nil', then it puts point N tenths of the way from the beginning of the accessible portion of the buffer. In an interactive call, N is the numeric prefix argument, if provided; otherwise N defaults to `nil'. *Warning:* Don't use this function in Lisp programs! -- Command: end-of-buffer &optional n This function moves point to the end of the buffer (or the limits of the accessible portion, when narrowing is in effect), setting the mark at the previous position (except in Transient Mark mode when the mark is already active). If N is non-`nil', then it puts point N tenths of the way from the end of the accessible portion of the buffer. In an interactive call, N is the numeric prefix argument, if provided; otherwise N defaults to `nil'. *Warning:* Don't use this function in Lisp programs!  File: elisp, Node: Text Lines, Next: Screen Lines, Prev: Buffer End Motion, Up: Motion 30.2.4 Motion by Text Lines --------------------------- Text lines are portions of the buffer delimited by newline characters, which are regarded as part of the previous line. The first text line begins at the beginning of the buffer, and the last text line ends at the end of the buffer whether or not the last character is a newline. The division of the buffer into text lines is not affected by the width of the window, by line continuation in display, or by how tabs and control characters are displayed. -- Command: beginning-of-line &optional count This function moves point to the beginning of the current line. With an argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and then to the beginning of the line. This function does not move point across a field boundary (*note Fields::) unless doing so would move beyond there to a different line; therefore, if COUNT is `nil' or 1, and point starts at a field boundary, point does not move. To ignore field boundaries, either bind `inhibit-field-text-motion' to `t', or use the `forward-line' function instead. For instance, `(forward-line 0)' does the same thing as `(beginning-of-line)', except that it ignores field boundaries. If this function reaches the end of the buffer (or of the accessible portion, if narrowing is in effect), it positions point there. No error is signaled. -- Function: line-beginning-position &optional count Return the position that `(beginning-of-line COUNT)' would move to. -- Command: end-of-line &optional count This function moves point to the end of the current line. With an argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and then to the end of the line. This function does not move point across a field boundary (*note Fields::) unless doing so would move beyond there to a different line; therefore, if COUNT is `nil' or 1, and point starts at a field boundary, point does not move. To ignore field boundaries, bind `inhibit-field-text-motion' to `t'. If this function reaches the end of the buffer (or of the accessible portion, if narrowing is in effect), it positions point there. No error is signaled. -- Function: line-end-position &optional count Return the position that `(end-of-line COUNT)' would move to. -- Command: forward-line &optional count This function moves point forward COUNT lines, to the beginning of the line. If COUNT is negative, it moves point -COUNT lines backward, to the beginning of a line. If COUNT is zero, it moves point to the beginning of the current line. If COUNT is `nil', that means 1. If `forward-line' encounters the beginning or end of the buffer (or of the accessible portion) before finding that many lines, it sets point there. No error is signaled. `forward-line' returns the difference between COUNT and the number of lines actually moved. If you attempt to move down five lines from the beginning of a buffer that has only three lines, point stops at the end of the last line, and the value will be 2. In an interactive call, COUNT is the numeric prefix argument. -- Function: count-lines start end This function returns the number of lines between the positions START and END in the current buffer. If START and END are equal, then it returns 0. Otherwise it returns at least 1, even if START and END are on the same line. This is because the text between them, considered in isolation, must contain at least one line unless it is empty. Here is an example of using `count-lines': (defun current-line () "Return the vertical position of point..." (+ (count-lines (window-start) (point)) (if (= (current-column) 0) 1 0))) -- Function: line-number-at-pos &optional pos This function returns the line number in the current buffer corresponding to the buffer position POS. If POS is `nil' or omitted, the current buffer position is used. Also see the functions `bolp' and `eolp' in *note Near Point::. These functions do not move point, but test whether it is already at the beginning or end of a line.  File: elisp, Node: Screen Lines, Next: List Motion, Prev: Text Lines, Up: Motion 30.2.5 Motion by Screen Lines ----------------------------- The line functions in the previous section count text lines, delimited only by newline characters. By contrast, these functions count screen lines, which are defined by the way the text appears on the screen. A text line is a single screen line if it is short enough to fit the width of the selected window, but otherwise it may occupy several screen lines. In some cases, text lines are truncated on the screen rather than continued onto additional screen lines. In these cases, `vertical-motion' moves point much like `forward-line'. *Note Truncation::. Because the width of a given string depends on the flags that control the appearance of certain characters, `vertical-motion' behaves differently, for a given piece of text, depending on the buffer it is in, and even on the selected window (because the width, the truncation flag, and display table may vary between windows). *Note Usual Display::. These functions scan text to determine where screen lines break, and thus take time proportional to the distance scanned. If you intend to use them heavily, Emacs provides caches which may improve the performance of your code. *Note cache-long-line-scans: Truncation. -- Function: vertical-motion count &optional window This function moves point to the start of the screen line COUNT screen lines down from the screen line containing point. If COUNT is negative, it moves up instead. The COUNT argument can be a cons cell, `(COLS . LINES)', instead of an integer. Then the function moves by LINES screen lines, and puts point COLS columns from the start of that screen line. The return value is the number of screen lines over which point was moved. The value may be less in absolute value than COUNT if the beginning or end of the buffer was reached. The window WINDOW is used for obtaining parameters such as the width, the horizontal scrolling, and the display table. But `vertical-motion' always operates on the current buffer, even if WINDOW currently displays some other buffer. -- Function: count-screen-lines &optional beg end count-final-newline window This function returns the number of screen lines in the text from BEG to END. The number of screen lines may be different from the number of actual lines, due to line continuation, the display table, etc. If BEG and END are `nil' or omitted, they default to the beginning and end of the accessible portion of the buffer. If the region ends with a newline, that is ignored unless the optional third argument COUNT-FINAL-NEWLINE is non-`nil'. The optional fourth argument WINDOW specifies the window for obtaining parameters such as width, horizontal scrolling, and so on. The default is to use the selected window's parameters. Like `vertical-motion', `count-screen-lines' always uses the current buffer, regardless of which buffer is displayed in WINDOW. This makes possible to use `count-screen-lines' in any buffer, whether or not it is currently displayed in some window. -- Command: move-to-window-line count This function moves point with respect to the text currently displayed in the selected window. It moves point to the beginning of the screen line COUNT screen lines from the top of the window. If COUNT is negative, that specifies a position -COUNT lines from the bottom (or the last line of the buffer, if the buffer ends above the specified screen position). If COUNT is `nil', then point moves to the beginning of the line in the middle of the window. If the absolute value of COUNT is greater than the size of the window, then point moves to the place that would appear on that screen line if the window were tall enough. This will probably cause the next redisplay to scroll to bring that location onto the screen. In an interactive call, COUNT is the numeric prefix argument. The value returned is the window line number point has moved to, with the top line in the window numbered 0. -- Function: compute-motion from frompos to topos width offsets window This function scans the current buffer, calculating screen positions. It scans the buffer forward from position FROM, assuming that is at screen coordinates FROMPOS, to position TO or coordinates TOPOS, whichever comes first. It returns the ending buffer position and screen coordinates. The coordinate arguments FROMPOS and TOPOS are cons cells of the form `(HPOS . VPOS)'. The argument WIDTH is the number of columns available to display text; this affects handling of continuation lines. `nil' means the actual number of usable text columns in the window, which is equivalent to the value returned by `(window-width window)'. The argument OFFSETS is either `nil' or a cons cell of the form `(HSCROLL . TAB-OFFSET)'. Here HSCROLL is the number of columns not being displayed at the left margin; most callers get this by calling `window-hscroll'. Meanwhile, TAB-OFFSET is the offset between column numbers on the screen and column numbers in the buffer. This can be nonzero in a continuation line, when the previous screen lines' widths do not add up to a multiple of `tab-width'. It is always zero in a non-continuation line. The window WINDOW serves only to specify which display table to use. `compute-motion' always operates on the current buffer, regardless of what buffer is displayed in WINDOW. The return value is a list of five elements: (POS HPOS VPOS PREVHPOS CONTIN) Here POS is the buffer position where the scan stopped, VPOS is the vertical screen position, and HPOS is the horizontal screen position. The result PREVHPOS is the horizontal position one character back from POS. The result CONTIN is `t' if the last line was continued after (or within) the previous character. For example, to find the buffer position of column COL of screen line LINE of a certain window, pass the window's display start location as FROM and the window's upper-left coordinates as FROMPOS. Pass the buffer's `(point-max)' as TO, to limit the scan to the end of the accessible portion of the buffer, and pass LINE and COL as TOPOS. Here's a function that does this: (defun coordinates-of-position (col line) (car (compute-motion (window-start) '(0 . 0) (point-max) (cons col line) (window-width) (cons (window-hscroll) 0) (selected-window)))) When you use `compute-motion' for the minibuffer, you need to use `minibuffer-prompt-width' to get the horizontal position of the beginning of the first screen line. *Note Minibuffer Contents::.  File: elisp, Node: List Motion, Next: Skipping Characters, Prev: Screen Lines, Up: Motion 30.2.6 Moving over Balanced Expressions --------------------------------------- Here are several functions concerned with balanced-parenthesis expressions (also called "sexps" in connection with moving across them in Emacs). The syntax table controls how these functions interpret various characters; see *note Syntax Tables::. *Note Parsing Expressions::, for lower-level primitives for scanning sexps or parts of sexps. For user-level commands, see *note Commands for Editing with Parentheses: (emacs)Parentheses. -- Command: forward-list &optional arg This function moves forward across ARG (default 1) balanced groups of parentheses. (Other syntactic entities such as words or paired string quotes are ignored.) -- Command: backward-list &optional arg This function moves backward across ARG (default 1) balanced groups of parentheses. (Other syntactic entities such as words or paired string quotes are ignored.) -- Command: up-list &optional arg This function moves forward out of ARG (default 1) levels of parentheses. A negative argument means move backward but still to a less deep spot. -- Command: down-list &optional arg This function moves forward into ARG (default 1) levels of parentheses. A negative argument means move backward but still go deeper in parentheses (-ARG levels). -- Command: forward-sexp &optional arg This function moves forward across ARG (default 1) balanced expressions. Balanced expressions include both those delimited by parentheses and other kinds, such as words and string constants. *Note Parsing Expressions::. For example, ---------- Buffer: foo ---------- (concat-!- "foo " (car x) y z) ---------- Buffer: foo ---------- (forward-sexp 3) => nil ---------- Buffer: foo ---------- (concat "foo " (car x) y-!- z) ---------- Buffer: foo ---------- -- Command: backward-sexp &optional arg This function moves backward across ARG (default 1) balanced expressions. -- Command: beginning-of-defun &optional arg This function moves back to the ARGth beginning of a defun. If ARG is negative, this actually moves forward, but it still moves to the beginning of a defun, not to the end of one. ARG defaults to 1. -- Command: end-of-defun &optional arg This function moves forward to the ARGth end of a defun. If ARG is negative, this actually moves backward, but it still moves to the end of a defun, not to the beginning of one. ARG defaults to 1. -- User Option: defun-prompt-regexp If non-`nil', this buffer-local variable holds a regular expression that specifies what text can appear before the open-parenthesis that starts a defun. That is to say, a defun begins on a line that starts with a match for this regular expression, followed by a character with open-parenthesis syntax. -- User Option: open-paren-in-column-0-is-defun-start If this variable's value is non-`nil', an open parenthesis in column 0 is considered to be the start of a defun. If it is `nil', an open parenthesis in column 0 has no special meaning. The default is `t'. -- Variable: beginning-of-defun-function If non-`nil', this variable holds a function for finding the beginning of a defun. The function `beginning-of-defun' calls this function instead of using its normal method, passing it its optional argument. If the argument is non-`nil', the function should move back by that many functions, like `beginning-of-defun' does. -- Variable: end-of-defun-function If non-`nil', this variable holds a function for finding the end of a defun. The function `end-of-defun' calls this function instead of using its normal method.  File: elisp, Node: Skipping Characters, Prev: List Motion, Up: Motion 30.2.7 Skipping Characters -------------------------- The following two functions move point over a specified set of characters. For example, they are often used to skip whitespace. For related functions, see *note Motion and Syntax::. These functions convert the set string to multibyte if the buffer is multibyte, and they convert it to unibyte if the buffer is unibyte, as the search functions do (*note Searching and Matching::). -- Function: skip-chars-forward character-set &optional limit This function moves point in the current buffer forward, skipping over a given set of characters. It examines the character following point, then advances point if the character matches CHARACTER-SET. This continues until it reaches a character that does not match. The function returns the number of characters moved over. The argument CHARACTER-SET is a string, like the inside of a `[...]' in a regular expression except that `]' does not terminate it, and `\' quotes `^', `-' or `\'. Thus, `"a-zA-Z"' skips over all letters, stopping before the first nonletter, and `"^a-zA-Z"' skips nonletters stopping before the first letter. See *Note Regular Expressions::. Character classes can also be used, e.g. `"[:alnum:]"'. See *note Char Classes::. If LIMIT is supplied (it must be a number or a marker), it specifies the maximum position in the buffer that point can be skipped to. Point will stop at or before LIMIT. In the following example, point is initially located directly before the `T'. After the form is evaluated, point is located at the end of that line (between the `t' of `hat' and the newline). The function skips all letters and spaces, but not newlines. ---------- Buffer: foo ---------- I read "-!-The cat in the hat comes back" twice. ---------- Buffer: foo ---------- (skip-chars-forward "a-zA-Z ") => 18 ---------- Buffer: foo ---------- I read "The cat in the hat-!- comes back" twice. ---------- Buffer: foo ---------- -- Function: skip-chars-backward character-set &optional limit This function moves point backward, skipping characters that match CHARACTER-SET, until LIMIT. It is just like `skip-chars-forward' except for the direction of motion. The return value indicates the distance traveled. It is an integer that is zero or less.  File: elisp, Node: Excursions, Next: Narrowing, Prev: Motion, Up: Positions 30.3 Excursions =============== It is often useful to move point "temporarily" within a localized portion of the program, or to switch buffers temporarily. This is called an "excursion", and it is done with the `save-excursion' special form. This construct initially remembers the identity of the current buffer, and its values of point and the mark, and restores them after the completion of the excursion. The forms for saving and restoring the configuration of windows are described elsewhere (see *note Window Configurations::, and *note Frame Configurations::). When only the identity of the current buffer needs to be saved and restored, it is preferable to use `save-current-buffer' instead. -- Special Form: save-excursion body... The `save-excursion' special form saves the identity of the current buffer and the values of point and the mark in it, evaluates BODY, and finally restores the buffer and its saved values of point and the mark. All three saved values are restored even in case of an abnormal exit via `throw' or error (*note Nonlocal Exits::). The `save-excursion' special form is the standard way to move point within one part of a program and avoid affecting the rest of the program. It is used more than 4000 times in the Lisp sources of Emacs. `save-excursion' does not save the values of point and the mark for other buffers, so changes in other buffers remain in effect after `save-excursion' exits. Likewise, `save-excursion' does not restore window-buffer correspondences altered by functions such as `switch-to-buffer'. One way to restore these correspondences, and the selected window, is to use `save-window-excursion' inside `save-excursion' (*note Window Configurations::). The value returned by `save-excursion' is the result of the last form in BODY, or `nil' if no body forms were given. (save-excursion FORMS) == (let ((old-buf (current-buffer)) (old-pnt (point-marker)) (old-mark (copy-marker (mark-marker)))) (unwind-protect (progn FORMS) (set-buffer old-buf) (goto-char old-pnt) (set-marker (mark-marker) old-mark))) *Warning:* Ordinary insertion of text adjacent to the saved point value relocates the saved value, just as it relocates all markers. More precisely, the saved value is a marker with insertion type `nil'. *Note Marker Insertion Types::. Therefore, when the saved point value is restored, it normally comes before the inserted text. Although `save-excursion' saves the location of the mark, it does not prevent functions which modify the buffer from setting `deactivate-mark', and thus causing the deactivation of the mark after the command finishes. *Note The Mark::.  File: elisp, Node: Narrowing, Prev: Excursions, Up: Positions 30.4 Narrowing ============== "Narrowing" means limiting the text addressable by Emacs editing commands to a limited range of characters in a buffer. The text that remains addressable is called the "accessible portion" of the buffer. Narrowing is specified with two buffer positions which become the beginning and end of the accessible portion. For most editing commands and most Emacs primitives, these positions replace the values of the beginning and end of the buffer. While narrowing is in effect, no text outside the accessible portion is displayed, and point cannot move outside the accessible portion. Values such as positions or line numbers, which usually count from the beginning of the buffer, do so despite narrowing, but the functions which use them refuse to operate on text that is inaccessible. The commands for saving buffers are unaffected by narrowing; they save the entire buffer regardless of any narrowing. If you need to display in a single buffer several very different types of text, consider using an alternative facility described in *note Swapping Text::. -- Command: narrow-to-region start end This function sets the accessible portion of the current buffer to start at START and end at END. Both arguments should be character positions. In an interactive call, START and END are set to the bounds of the current region (point and the mark, with the smallest first). -- Command: narrow-to-page &optional move-count This function sets the accessible portion of the current buffer to include just the current page. An optional first argument MOVE-COUNT non-`nil' means to move forward or backward by MOVE-COUNT pages and then narrow to one page. The variable `page-delimiter' specifies where pages start and end (*note Standard Regexps::). In an interactive call, MOVE-COUNT is set to the numeric prefix argument. -- Command: widen This function cancels any narrowing in the current buffer, so that the entire contents are accessible. This is called "widening". It is equivalent to the following expression: (narrow-to-region 1 (1+ (buffer-size))) -- Special Form: save-restriction body... This special form saves the current bounds of the accessible portion, evaluates the BODY forms, and finally restores the saved bounds, thus restoring the same state of narrowing (or absence thereof) formerly in effect. The state of narrowing is restored even in the event of an abnormal exit via `throw' or error (*note Nonlocal Exits::). Therefore, this construct is a clean way to narrow a buffer temporarily. The value returned by `save-restriction' is that returned by the last form in BODY, or `nil' if no body forms were given. *Caution:* it is easy to make a mistake when using the `save-restriction' construct. Read the entire description here before you try it. If BODY changes the current buffer, `save-restriction' still restores the restrictions on the original buffer (the buffer whose restrictions it saved from), but it does not restore the identity of the current buffer. `save-restriction' does _not_ restore point and the mark; use `save-excursion' for that. If you use both `save-restriction' and `save-excursion' together, `save-excursion' should come first (on the outside). Otherwise, the old point value would be restored with temporary narrowing still in effect. If the old point value were outside the limits of the temporary narrowing, this would fail to restore it accurately. Here is a simple example of correct use of `save-restriction': ---------- Buffer: foo ---------- This is the contents of foo This is the contents of foo This is the contents of foo-!- ---------- Buffer: foo ---------- (save-excursion (save-restriction (goto-char 1) (forward-line 2) (narrow-to-region 1 (point)) (goto-char (point-min)) (replace-string "foo" "bar"))) ---------- Buffer: foo ---------- This is the contents of bar This is the contents of bar This is the contents of foo-!- ---------- Buffer: foo ----------  File: elisp, Node: Markers, Next: Text, Prev: Positions, Up: Top 31 Markers ********** A "marker" is a Lisp object used to specify a position in a buffer relative to the surrounding text. A marker changes its offset from the beginning of the buffer automatically whenever text is inserted or deleted, so that it stays with the two characters on either side of it. * Menu: * Overview of Markers:: The components of a marker, and how it relocates. * Predicates on Markers:: Testing whether an object is a marker. * Creating Markers:: Making empty markers or markers at certain places. * Information from Markers:: Finding the marker's buffer or character position. * Marker Insertion Types:: Two ways a marker can relocate when you insert where it points. * Moving Markers:: Moving the marker to a new buffer or position. * The Mark:: How "the mark" is implemented with a marker. * The Region:: How to access "the region".  File: elisp, Node: Overview of Markers, Next: Predicates on Markers, Up: Markers 31.1 Overview of Markers ======================== A marker specifies a buffer and a position in that buffer. The marker can be used to represent a position in the functions that require one, just as an integer could be used. In that case, the marker's buffer is normally ignored. Of course, a marker used in this way usually points to a position in the buffer that the function operates on, but that is entirely the programmer's responsibility. *Note Positions::, for a complete description of positions. A marker has three attributes: the marker position, the marker buffer, and the insertion type. The marker position is an integer that is equivalent (at a given time) to the marker as a position in that buffer. But the marker's position value can change often during the life of the marker. Insertion and deletion of text in the buffer relocate the marker. The idea is that a marker positioned between two characters remains between those two characters despite insertion and deletion elsewhere in the buffer. Relocation changes the integer equivalent of the marker. Deleting text around a marker's position leaves the marker between the characters immediately before and after the deleted text. Inserting text at the position of a marker normally leaves the marker either in front of or after the new text, depending on the marker's "insertion type" (*note Marker Insertion Types::)--unless the insertion is done with `insert-before-markers' (*note Insertion::). Insertion and deletion in a buffer must check all the markers and relocate them if necessary. This slows processing in a buffer with a large number of markers. For this reason, it is a good idea to make a marker point nowhere if you are sure you don't need it any more. Unreferenced markers are garbage collected eventually, but until then will continue to use time if they do point somewhere. Because it is common to perform arithmetic operations on a marker position, most of the arithmetic operations (including `+' and `-') accept markers as arguments. In such cases, the marker stands for its current position. Here are examples of creating markers, setting markers, and moving point to markers: ;; Make a new marker that initially does not point anywhere: (setq m1 (make-marker)) => # ;; Set `m1' to point between the 99th and 100th characters ;; in the current buffer: (set-marker m1 100) => # ;; Now insert one character at the beginning of the buffer: (goto-char (point-min)) => 1 (insert "Q") => nil ;; `m1' is updated appropriately. m1 => # ;; Two markers that point to the same position ;; are not `eq', but they are `equal'. (setq m2 (copy-marker m1)) => # (eq m1 m2) => nil (equal m1 m2) => t ;; When you are finished using a marker, make it point nowhere. (set-marker m1 nil) => #  File: elisp, Node: Predicates on Markers, Next: Creating Markers, Prev: Overview of Markers, Up: Markers 31.2 Predicates on Markers ========================== You can test an object to see whether it is a marker, or whether it is either an integer or a marker. The latter test is useful in connection with the arithmetic functions that work with both markers and integers. -- Function: markerp object This function returns `t' if OBJECT is a marker, `nil' otherwise. Note that integers are not markers, even though many functions will accept either a marker or an integer. -- Function: integer-or-marker-p object This function returns `t' if OBJECT is an integer or a marker, `nil' otherwise. -- Function: number-or-marker-p object This function returns `t' if OBJECT is a number (either integer or floating point) or a marker, `nil' otherwise.  File: elisp, Node: Creating Markers, Next: Information from Markers, Prev: Predicates on Markers, Up: Markers 31.3 Functions that Create Markers ================================== When you create a new marker, you can make it point nowhere, or point to the present position of point, or to the beginning or end of the accessible portion of the buffer, or to the same place as another given marker. The next four functions all return markers with insertion type `nil'. *Note Marker Insertion Types::. -- Function: make-marker This function returns a newly created marker that does not point anywhere. (make-marker) => # -- Function: point-marker This function returns a new marker that points to the present position of point in the current buffer. *Note Point::. For an example, see `copy-marker', below. -- Function: point-min-marker This function returns a new marker that points to the beginning of the accessible portion of the buffer. This will be the beginning of the buffer unless narrowing is in effect. *Note Narrowing::. -- Function: point-max-marker This function returns a new marker that points to the end of the accessible portion of the buffer. This will be the end of the buffer unless narrowing is in effect. *Note Narrowing::. Here are examples of this function and `point-min-marker', shown in a buffer containing a version of the source file for the text of this chapter. (point-min-marker) => # (point-max-marker) => # (narrow-to-region 100 200) => nil (point-min-marker) => # (point-max-marker) => # -- Function: copy-marker marker-or-integer &optional insertion-type If passed a marker as its argument, `copy-marker' returns a new marker that points to the same place and the same buffer as does MARKER-OR-INTEGER. If passed an integer as its argument, `copy-marker' returns a new marker that points to position MARKER-OR-INTEGER in the current buffer. The new marker's insertion type is specified by the argument INSERTION-TYPE. *Note Marker Insertion Types::. If passed an integer argument less than 1, `copy-marker' returns a new marker that points to the beginning of the current buffer. If passed an integer argument greater than the length of the buffer, `copy-marker' returns a new marker that points to the end of the buffer. (copy-marker 0) => # (copy-marker 20000) => # An error is signaled if MARKER is neither a marker nor an integer. Two distinct markers are considered `equal' (even though not `eq') to each other if they have the same position and buffer, or if they both point nowhere. (setq p (point-marker)) => # (setq q (copy-marker p)) => # (eq p q) => nil (equal p q) => t  File: elisp, Node: Information from Markers, Next: Marker Insertion Types, Prev: Creating Markers, Up: Markers 31.4 Information from Markers ============================= This section describes the functions for accessing the components of a marker object. -- Function: marker-position marker This function returns the position that MARKER points to, or `nil' if it points nowhere. -- Function: marker-buffer marker This function returns the buffer that MARKER points into, or `nil' if it points nowhere. (setq m (make-marker)) => # (marker-position m) => nil (marker-buffer m) => nil (set-marker m 3770 (current-buffer)) => # (marker-buffer m) => # (marker-position m) => 3770 -- Function: buffer-has-markers-at position This function returns `t' if one or more markers point at position POSITION in the current buffer.  File: elisp, Node: Marker Insertion Types, Next: Moving Markers, Prev: Information from Markers, Up: Markers 31.5 Marker Insertion Types =========================== When you insert text directly at the place where a marker points, there are two possible ways to relocate that marker: it can point before the inserted text, or point after it. You can specify which one a given marker should do by setting its "insertion type". Note that use of `insert-before-markers' ignores markers' insertion types, always relocating a marker to point after the inserted text. -- Function: set-marker-insertion-type marker type This function sets the insertion type of marker MARKER to TYPE. If TYPE is `t', MARKER will advance when text is inserted at its position. If TYPE is `nil', MARKER does not advance when text is inserted there. -- Function: marker-insertion-type marker This function reports the current insertion type of MARKER. Most functions that create markers, without an argument allowing to specify the insertion type, create them with insertion type `nil'. Also, the mark has, by default, insertion type `nil'.  File: elisp, Node: Moving Markers, Next: The Mark, Prev: Marker Insertion Types, Up: Markers 31.6 Moving Marker Positions ============================ This section describes how to change the position of an existing marker. When you do this, be sure you know whether the marker is used outside of your program, and, if so, what effects will result from moving it--otherwise, confusing things may happen in other parts of Emacs. -- Function: set-marker marker position &optional buffer This function moves MARKER to POSITION in BUFFER. If BUFFER is not provided, it defaults to the current buffer. If POSITION is less than 1, `set-marker' moves MARKER to the beginning of the buffer. If POSITION is greater than the size of the buffer, `set-marker' moves marker to the end of the buffer. If POSITION is `nil' or a marker that points nowhere, then MARKER is set to point nowhere. The value returned is MARKER. (setq m (point-marker)) => # (set-marker m 55) => # (setq b (get-buffer "foo")) => # (set-marker m 0 b) => # -- Function: move-marker marker position &optional buffer This is another name for `set-marker'.  File: elisp, Node: The Mark, Next: The Region, Prev: Moving Markers, Up: Markers 31.7 The Mark ============= Each buffer has a special marker, which is designated "the mark". When a buffer is newly created, this marker exists but does not point anywhere; this means that the mark "doesn't exist" in that buffer yet. Subsequent commands can set the mark. The mark specifies a position to bound a range of text for many commands, such as `kill-region' and `indent-rigidly'. These commands typically act on the text between point and the mark, which is called the "region". If you are writing a command that operates on the region, don't examine the mark directly; instead, use `interactive' with the `r' specification. This provides the values of point and the mark as arguments to the command in an interactive call, but permits other Lisp programs to specify arguments explicitly. *Note Interactive Codes::. Some commands set the mark as a side-effect. Commands should do this only if it has a potential use to the user, and never for their own internal purposes. For example, the `replace-regexp' command sets the mark to the value of point before doing any replacements, because this enables the user to move back there conveniently after the replace is finished. Once the mark "exists" in a buffer, it normally never ceases to exist. However, it may become "inactive", if Transient Mark mode is enabled. The buffer-local variable `mark-active', if non-`nil', means that the mark is active. A command can call the function `deactivate-mark' to deactivate the mark directly, or it can request deactivation of the mark upon return to the editor command loop by setting the variable `deactivate-mark' to a non-`nil' value. If Transient Mode is enabled, certain editing commands that normally apply to text near point, apply instead to the region when the mark is active. This is the main motivation for using Transient Mark mode. (Another is that this enables highlighting of the region when the mark is active. *Note Display::.) In addition to the mark, each buffer has a "mark ring" which is a list of markers containing previous values of the mark. When editing commands change the mark, they should normally save the old value of the mark on the mark ring. The variable `mark-ring-max' specifies the maximum number of entries in the mark ring; once the list becomes this long, adding a new element deletes the last element. There is also a separate global mark ring, but that is used only in a few particular user-level commands, and is not relevant to Lisp programming. So we do not describe it here. -- Function: mark &optional force This function returns the current buffer's mark position as an integer, or `nil' if no mark has ever been set in this buffer. If Transient Mark mode is enabled, and `mark-even-if-inactive' is `nil', `mark' signals an error if the mark is inactive. However, if FORCE is non-`nil', then `mark' disregards inactivity of the mark, and returns the mark position (or `nil') anyway. -- Function: mark-marker This function returns the marker that represents the current buffer's mark. It is not a copy, it is the marker used internally. Therefore, changing this marker's position will directly affect the buffer's mark. Don't do that unless that is the effect you want. (setq m (mark-marker)) => # (set-marker m 100) => # (mark-marker) => # Like any marker, this marker can be set to point at any buffer you like. If you make it point at any buffer other than the one of which it is the mark, it will yield perfectly consistent, but rather odd, results. We recommend that you not do it! -- Function: set-mark position This function sets the mark to POSITION, and activates the mark. The old value of the mark is _not_ pushed onto the mark ring. *Please note:* Use this function only if you want the user to see that the mark has moved, and you want the previous mark position to be lost. Normally, when a new mark is set, the old one should go on the `mark-ring'. For this reason, most applications should use `push-mark' and `pop-mark', not `set-mark'. Novice Emacs Lisp programmers often try to use the mark for the wrong purposes. The mark saves a location for the user's convenience. An editing command should not alter the mark unless altering the mark is part of the user-level functionality of the command. (And, in that case, this effect should be documented.) To remember a location for internal use in the Lisp program, store it in a Lisp variable. For example: (let ((beg (point))) (forward-line 1) (delete-region beg (point))). -- Function: push-mark &optional position nomsg activate This function sets the current buffer's mark to POSITION, and pushes a copy of the previous mark onto `mark-ring'. If POSITION is `nil', then the value of point is used. `push-mark' returns `nil'. The function `push-mark' normally _does not_ activate the mark. To do that, specify `t' for the argument ACTIVATE. A `Mark set' message is displayed unless NOMSG is non-`nil'. -- Function: pop-mark This function pops off the top element of `mark-ring' and makes that mark become the buffer's actual mark. This does not move point in the buffer, and it does nothing if `mark-ring' is empty. It deactivates the mark. The return value is not meaningful. -- User Option: transient-mark-mode This variable, if non-`nil', enables Transient Mark mode. In Transient Mark mode, every buffer-modifying primitive sets `deactivate-mark'. As a consequence, most commands that modify the buffer also deactivate the mark. When Transient Mark mode is enabled and the mark is active, many commands that normally apply to the text near point instead apply to the region. Such commands should use the function `use-region-p' to test whether they should operate on the region. *Note The Region::. Lisp programs can set `transient-mark-mode' to non-`nil', non-`t' values to enable Transient Mark mode temporarily. If the value is `lambda', Transient Mark mode is automatically turned off after any action, such as buffer modification, that would normally deactivate the mark. If the value is `(only . OLDVAL)', then `transient-mark-mode' is set to the value OLDVAL after any subsequent command that moves point and is not shift-translated (*note shift-translation: Key Sequence Input.), or after any other action that would normally deactivate the mark. -- User Option: mark-even-if-inactive If this is non-`nil', Lisp programs and the Emacs user can use the mark even when it is inactive. This option affects the behavior of Transient Mark mode. When the option is non-`nil', deactivation of the mark turns off region highlighting, but commands that use the mark behave as if the mark were still active. -- Variable: deactivate-mark If an editor command sets this variable non-`nil', then the editor command loop deactivates the mark after the command returns (if Transient Mark mode is enabled). All the primitives that change the buffer set `deactivate-mark', to deactivate the mark when the command is finished. To write Lisp code that modifies the buffer without causing deactivation of the mark at the end of the command, bind `deactivate-mark' to `nil' around the code that does the modification. For example: (let (deactivate-mark) (insert " ")) -- Function: deactivate-mark &optional force If Transient Mark mode is enabled or FORCE is non-`nil', this function deactivates the mark and runs the normal hook `deactivate-mark-hook'. Otherwise, it does nothing. -- Variable: mark-active The mark is active when this variable is non-`nil'. This variable is always buffer-local in each buffer. Do _not_ use the value of this variable to decide whether a command that normally operates on text near point should operate on the region instead. Use the function `use-region-p' for that (*note The Region::). -- Variable: activate-mark-hook -- Variable: deactivate-mark-hook These normal hooks are run, respectively, when the mark becomes active and when it becomes inactive. The hook `activate-mark-hook' is also run at the end of a command if the mark is active and it is possible that the region may have changed. -- Function: handle-shift-selection This function implements the "shift-selection" behavior of point-motion commands. *Note Shift Selection: (emacs)Shift Selection. It is called automatically by the Emacs command loop whenever a command with a `^' character in its `interactive' spec is invoked, before the command itself is executed (*note ^: Interactive Codes.). If `shift-select-mode' is non-`nil' and the current command was invoked via shift translation (*note shift-translation: Key Sequence Input.), this function sets the mark and temporarily activates the region, unless the region was already temporarily activated in this way. Otherwise, if the region has been activated temporarily, it deactivates the mark and restores the variable `transient-mark-mode' to its earlier value. -- Variable: mark-ring The value of this buffer-local variable is the list of saved former marks of the current buffer, most recent first. mark-ring => (# # ...) -- User Option: mark-ring-max The value of this variable is the maximum size of `mark-ring'. If more marks than this are pushed onto the `mark-ring', `push-mark' discards an old mark when it adds a new one.  File: elisp, Node: The Region, Prev: The Mark, Up: Markers 31.8 The Region =============== The text between point and the mark is known as "the region". Various functions operate on text delimited by point and the mark, but only those functions specifically related to the region itself are described here. The next two functions signal an error if the mark does not point anywhere. If Transient Mark mode is enabled and `mark-even-if-inactive' is `nil', they also signal an error if the mark is inactive. -- Function: region-beginning This function returns the position of the beginning of the region (as an integer). This is the position of either point or the mark, whichever is smaller. -- Function: region-end This function returns the position of the end of the region (as an integer). This is the position of either point or the mark, whichever is larger. Few programs need to use the `region-beginning' and `region-end' functions. A command designed to operate on a region should normally use `interactive' with the `r' specification to find the beginning and end of the region. This lets other Lisp programs specify the bounds explicitly as arguments. (*Note Interactive Codes::.) -- Function: use-region-p This function returns `t' if Transient Mark mode is enabled, the mark is active, and there's a valid region in the buffer. Commands that operate on the region (instead of on text near point) when there's an active mark should use this to test whether to do that.  File: elisp, Node: Text, Next: Non-ASCII Characters, Prev: Markers, Up: Top 32 Text ******* This chapter describes the functions that deal with the text in a buffer. Most examine, insert, or delete text in the current buffer, often operating at point or on text adjacent to point. Many are interactive. All the functions that change the text provide for undoing the changes (*note Undo::). Many text-related functions operate on a region of text defined by two buffer positions passed in arguments named START and END. These arguments should be either markers (*note Markers::) or numeric character positions (*note Positions::). The order of these arguments does not matter; it is all right for START to be the end of the region and END the beginning. For example, `(delete-region 1 10)' and `(delete-region 10 1)' are equivalent. An `args-out-of-range' error is signaled if either START or END is outside the accessible portion of the buffer. In an interactive call, point and the mark are used for these arguments. Throughout this chapter, "text" refers to the characters in the buffer, together with their properties (when relevant). Keep in mind that point is always between two characters, and the cursor appears on the character after point. * Menu: * Near Point:: Examining text in the vicinity of point. * Buffer Contents:: Examining text in a general fashion. * Comparing Text:: Comparing substrings of buffers. * Insertion:: Adding new text to a buffer. * Commands for Insertion:: User-level commands to insert text. * Deletion:: Removing text from a buffer. * User-Level Deletion:: User-level commands to delete text. * The Kill Ring:: Where removed text sometimes is saved for later use. * Undo:: Undoing changes to the text of a buffer. * Maintaining Undo:: How to enable and disable undo information. How to control how much information is kept. * Filling:: Functions for explicit filling. * Margins:: How to specify margins for filling commands. * Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context. * Auto Filling:: How auto-fill mode is implemented to break lines. * Sorting:: Functions for sorting parts of the buffer. * Columns:: Computing horizontal positions, and using them. * Indentation:: Functions to insert or adjust indentation. * Case Changes:: Case conversion of parts of the buffer. * Text Properties:: Assigning Lisp property lists to text characters. * Substitution:: Replacing a given character wherever it appears. * Transposition:: Swapping two portions of a buffer. * Registers:: How registers are implemented. Accessing the text or position stored in a register. * Base 64:: Conversion to or from base 64 encoding. * MD5 Checksum:: Compute the MD5 "message digest"/"checksum". * Atomic Changes:: Installing several buffer changes "atomically". * Change Hooks:: Supplying functions to be run when text is changed.  File: elisp, Node: Near Point, Next: Buffer Contents, Up: Text 32.1 Examining Text Near Point ============================== Many functions are provided to look at the characters around point. Several simple functions are described here. See also `looking-at' in *note Regexp Search::. In the following four functions, "beginning" or "end" of buffer refers to the beginning or end of the accessible portion. -- Function: char-after &optional position This function returns the character in the current buffer at (i.e., immediately after) position POSITION. If POSITION is out of range for this purpose, either before the beginning of the buffer, or at or beyond the end, then the value is `nil'. The default for POSITION is point. In the following example, assume that the first character in the buffer is `@': (char-to-string (char-after 1)) => "@" -- Function: char-before &optional position This function returns the character in the current buffer immediately before position POSITION. If POSITION is out of range for this purpose, either at or before the beginning of the buffer, or beyond the end, then the value is `nil'. The default for POSITION is point. -- Function: following-char This function returns the character following point in the current buffer. This is similar to `(char-after (point))'. However, if point is at the end of the buffer, then `following-char' returns 0. Remember that point is always between characters, and the cursor normally appears over the character following point. Therefore, the character returned by `following-char' is the character the cursor is over. In this example, point is between the `a' and the `c'. ---------- Buffer: foo ---------- Gentlemen may cry ``Pea-!-ce! Peace!,'' but there is no peace. ---------- Buffer: foo ---------- (char-to-string (preceding-char)) => "a" (char-to-string (following-char)) => "c" -- Function: preceding-char This function returns the character preceding point in the current buffer. See above, under `following-char', for an example. If point is at the beginning of the buffer, `preceding-char' returns 0. -- Function: bobp This function returns `t' if point is at the beginning of the buffer. If narrowing is in effect, this means the beginning of the accessible portion of the text. See also `point-min' in *note Point::. -- Function: eobp This function returns `t' if point is at the end of the buffer. If narrowing is in effect, this means the end of accessible portion of the text. See also `point-max' in *Note Point::. -- Function: bolp This function returns `t' if point is at the beginning of a line. *Note Text Lines::. The beginning of the buffer (or of its accessible portion) always counts as the beginning of a line. -- Function: eolp This function returns `t' if point is at the end of a line. The end of the buffer (or of its accessible portion) is always considered the end of a line.