This is ../../info/elisp, produced by makeinfo version 4.13 from
elisp.texi.

This is edition 3.0 of the GNU Emacs Lisp Reference Manual,
corresponding to Emacs version 23.4.

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999,
2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
2012  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 GNU Emacs Lisp
START-INFO-DIR-ENTRY
* Elisp: (elisp).       The Emacs Lisp Reference Manual.
END-INFO-DIR-ENTRY


File: elisp,  Node: Reverting,  Prev: Auto-Saving,  Up: Backups and Auto-Saving

26.3 Reverting
==============

If you have made extensive changes to a file and then change your mind
about them, you can get rid of them by reading in the previous version
of the file with the `revert-buffer' command.  *Note Reverting a
Buffer: (emacs)Reverting.

 -- Command: revert-buffer &optional ignore-auto noconfirm
          preserve-modes
     This command replaces the buffer text with the text of the visited
     file on disk.  This action undoes all changes since the file was
     visited or saved.

     By default, if the latest auto-save file is more recent than the
     visited file, and the argument IGNORE-AUTO is `nil',
     `revert-buffer' asks the user whether to use that auto-save
     instead.  When you invoke this command interactively, IGNORE-AUTO
     is `t' if there is no numeric prefix argument; thus, the
     interactive default is not to check the auto-save file.

     Normally, `revert-buffer' asks for confirmation before it changes
     the buffer; but if the argument NOCONFIRM is non-`nil',
     `revert-buffer' does not ask for confirmation.

     Normally, this command reinitializes the buffer's major and minor
     modes using `normal-mode'.  But if PRESERVE-MODES is non-`nil',
     the modes remain unchanged.

     Reverting tries to preserve marker positions in the buffer by
     using the replacement feature of `insert-file-contents'.  If the
     buffer contents and the file contents are identical before the
     revert operation, reverting preserves all the markers.  If they
     are not identical, reverting does change the buffer; in that case,
     it preserves the markers in the unchanged text (if any) at the
     beginning and end of the buffer.  Preserving any additional
     markers would be problematical.

   You can customize how `revert-buffer' does its work by setting the
variables described in the rest of this section.

 -- User Option: revert-without-query
     This variable holds a list of files that should be reverted without
     query.  The value is a list of regular expressions.  If the
     visited file name matches one of these regular expressions, and
     the file has changed on disk but the buffer is not modified, then
     `revert-buffer' reverts the file without asking the user for
     confirmation.

   Some major modes customize `revert-buffer' by making buffer-local
bindings for these variables:

 -- Variable: revert-buffer-function
     The value of this variable is the function to use to revert this
     buffer.  If non-`nil', it should be a function with two optional
     arguments to do the work of reverting.  The two optional arguments,
     IGNORE-AUTO and NOCONFIRM, are the arguments that `revert-buffer'
     received.  If the value is `nil', reverting works the usual way.

     Modes such as Dired mode, in which the text being edited does not
     consist of a file's contents but can be regenerated in some other
     fashion, can give this variable a buffer-local value that is a
     function to regenerate the contents.

 -- Variable: revert-buffer-insert-file-contents-function
     The value of this variable, if non-`nil', specifies the function
     to use to insert the updated contents when reverting this buffer.
     The function receives two arguments: first the file name to use;
     second, `t' if the user has asked to read the auto-save file.

     The reason for a mode to set this variable instead of
     `revert-buffer-function' is to avoid duplicating or replacing the
     rest of what `revert-buffer' does: asking for confirmation,
     clearing the undo list, deciding the proper major mode, and
     running the hooks listed below.

 -- Variable: before-revert-hook
     This normal hook is run by `revert-buffer' before inserting the
     modified contents--but only if `revert-buffer-function' is `nil'.

 -- Variable: after-revert-hook
     This normal hook is run by `revert-buffer' after inserting the
     modified contents--but only if `revert-buffer-function' is `nil'.


File: elisp,  Node: Buffers,  Next: Windows,  Prev: Backups and Auto-Saving,  Up: Top

27 Buffers
**********

A "buffer" is a Lisp object containing text to be edited.  Buffers are
used to hold the contents of files that are being visited; there may
also be buffers that are not visiting files.  While several buffers may
exist at one time, only one buffer is designated the "current buffer"
at any time.  Most editing commands act on the contents of the current
buffer.  Each buffer, including the current buffer, may or may not be
displayed in any windows.

* Menu:

* Buffer Basics::       What is a buffer?
* Current Buffer::      Designating a buffer as current
                          so that primitives will access its contents.
* Buffer Names::        Accessing and changing buffer names.
* Buffer File Name::    The buffer file name indicates which file is visited.
* Buffer Modification:: A buffer is "modified" if it needs to be saved.
* Modification Time::   Determining whether the visited file was changed
                         ``behind Emacs's back''.
* Read Only Buffers::   Modifying text is not allowed in a read-only buffer.
* The Buffer List::     How to look at all the existing buffers.
* Creating Buffers::    Functions that create buffers.
* Killing Buffers::     Buffers exist until explicitly killed.
* Indirect Buffers::    An indirect buffer shares text with some other buffer.
* Swapping Text::       Swapping text between two buffers.
* Buffer Gap::          The gap in the buffer.


File: elisp,  Node: Buffer Basics,  Next: Current Buffer,  Up: Buffers

27.1 Buffer Basics
==================

A "buffer" is a Lisp object containing text to be edited.  Buffers are
used to hold the contents of files that are being visited; there may
also be buffers that are not visiting files.  Although several buffers
normally exist, only one buffer is designated the "current buffer" at
any time.  Most editing commands act on the contents of the current
buffer.  Each buffer, including the current buffer, may or may not be
displayed in any windows.

Buffers in Emacs editing are objects that have distinct names and hold
text that can be edited.  Buffers appear to Lisp programs as a special
data type.  You can think of the contents of a buffer as a string that
you can extend; insertions and deletions may occur in any part of the
buffer.  *Note Text::.

   A Lisp buffer object contains numerous pieces of information.  Some
of this information is directly accessible to the programmer through
variables, while other information is accessible only through
special-purpose functions.  For example, the visited file name is
directly accessible through a variable, while the value of point is
accessible only through a primitive function.

   Buffer-specific information that is directly accessible is stored in
"buffer-local" variable bindings, which are variable values that are
effective only in a particular buffer.  This feature allows each buffer
to override the values of certain variables.  Most major modes override
variables such as `fill-column' or `comment-column' in this way.  For
more information about buffer-local variables and functions related to
them, see *note Buffer-Local Variables::.

   For functions and variables related to visiting files in buffers, see
*note Visiting Files:: and *note Saving Buffers::.  For functions and
variables related to the display of buffers in windows, see *note
Buffers and Windows::.

 -- Function: bufferp object
     This function returns `t' if OBJECT is a buffer, `nil' otherwise.


File: elisp,  Node: Current Buffer,  Next: Buffer Names,  Prev: Buffer Basics,  Up: Buffers

27.2 The Current Buffer
=======================

There are, in general, many buffers in an Emacs session.  At any time,
one of them is designated the "current buffer"--the buffer in which
most editing takes place.  Most of the primitives for examining or
changing text operate implicitly on the current buffer (*note Text::).

   Normally, the buffer displayed in the selected window is the current
buffer, but this is not always so: a Lisp program can temporarily
designate any buffer as current in order to operate on its contents,
without changing what is displayed on the screen.  The most basic
function for designating a current buffer is `set-buffer'.

 -- Function: current-buffer
     This function returns the current buffer.

          (current-buffer)
               => #<buffer buffers.texi>

 -- Function: set-buffer buffer-or-name
     This function makes BUFFER-OR-NAME the current buffer.
     BUFFER-OR-NAME must be an existing buffer or the name of an
     existing buffer.  The return value is the buffer made current.

     This function does not display the buffer in any window, so the
     user cannot necessarily see the buffer.  But Lisp programs will
     now operate on it.

   When an editing command returns to the editor command loop, Emacs
automatically calls `set-buffer' on the buffer shown in the selected
window.  This is to prevent confusion: it ensures that the buffer that
the cursor is in, when Emacs reads a command, is the buffer to which
that command applies (*note Command Loop::).  Thus, you should not use
`set-buffer' to switch visibly to a different buffer; for that, use the
functions described in *note Displaying Buffers::.

   When writing a Lisp function, do _not_ rely on this behavior of the
command loop to restore the current buffer after an operation.  Editing
commands can also be called as Lisp functions by other programs, not
just from the command loop; it is convenient for the caller if the
subroutine does not change which buffer is current (unless, of course,
that is the subroutine's purpose).

   To operate temporarily on another buffer, put the `set-buffer'
within a `save-current-buffer' form.  Here, as an example, is a
simplified version of the command `append-to-buffer':

     (defun append-to-buffer (buffer start end)
       "Append the text of the region to BUFFER."
       (interactive "BAppend to buffer: \nr")
       (let ((oldbuf (current-buffer)))
         (save-current-buffer
           (set-buffer (get-buffer-create buffer))
           (insert-buffer-substring oldbuf start end))))

Here, we bind a local variable to record the current buffer, and then
`save-current-buffer' arranges to make it current again later.  Next,
`set-buffer' makes the specified buffer current, and
`insert-buffer-substring' copies the string from the original buffer to
the specified (and now current) buffer.

   Alternatively, we can use the `with-current-buffer' macro:

     (defun append-to-buffer (buffer start end)
       "Append the text of the region to BUFFER."
       (interactive "BAppend to buffer: \nr")
       (let ((oldbuf (current-buffer)))
         (with-current-buffer (get-buffer-create buffer)
           (insert-buffer-substring oldbuf start end))))

   In either case, if the buffer appended to happens to be displayed in
some window, the next redisplay will show how its text has changed.  If
it is not displayed in any window, you will not see the change
immediately on the screen.  The command causes the buffer to become
current temporarily, but does not cause it to be displayed.

   If you make local bindings (with `let' or function arguments) for a
variable that may also have buffer-local bindings, make sure that the
same buffer is current at the beginning and at the end of the local
binding's scope.  Otherwise you might bind it in one buffer and unbind
it in another!

   Do not rely on using `set-buffer' to change the current buffer back,
because that won't do the job if a quit happens while the wrong buffer
is current.  For instance, in the previous example, it would have been
wrong to do this:

       (let ((oldbuf (current-buffer)))
         (set-buffer (get-buffer-create buffer))
         (insert-buffer-substring oldbuf start end)
         (set-buffer oldbuf))

Using `save-current-buffer' or `with-current-buffer', as we did,
correctly handles quitting, errors, and `throw', as well as ordinary
evaluation.

 -- Special Form: save-current-buffer body...
     The `save-current-buffer' special form saves the identity of the
     current buffer, evaluates the BODY forms, and finally restores
     that buffer as current.  The return value is the value of the last
     form in BODY.  The current buffer is restored even in case of an
     abnormal exit via `throw' or error (*note Nonlocal Exits::).

     If the buffer that used to be current has been killed by the time
     of exit from `save-current-buffer', then it is not made current
     again, of course.  Instead, whichever buffer was current just
     before exit remains current.

 -- Macro: with-current-buffer buffer-or-name body...
     The `with-current-buffer' macro saves the identity of the current
     buffer, makes BUFFER-OR-NAME current, evaluates the BODY forms,
     and finally restores the current buffer.  BUFFER-OR-NAME must
     specify an existing buffer or the name of an existing buffer.

     The return value is the value of the last form in BODY.  The
     current buffer is restored even in case of an abnormal exit via
     `throw' or error (*note Nonlocal Exits::).

 -- Macro: with-temp-buffer body...
     The `with-temp-buffer' macro evaluates the BODY forms with a
     temporary buffer as the current buffer.  It saves the identity of
     the current buffer, creates a temporary buffer and makes it
     current, evaluates the BODY forms, and finally restores the
     previous current buffer while killing the temporary buffer.  By
     default, undo information (*note Undo::) is not recorded in the
     buffer created by this macro (but BODY can enable that, if needed).

     The return value is the value of the last form in BODY.  You can
     return the contents of the temporary buffer by using
     `(buffer-string)' as the last form.

     The current buffer is restored even in case of an abnormal exit via
     `throw' or error (*note Nonlocal Exits::).

     See also `with-temp-file' in *note Writing to Files: Definition of
     with-temp-file.


File: elisp,  Node: Buffer Names,  Next: Buffer File Name,  Prev: Current Buffer,  Up: Buffers

27.3 Buffer Names
=================

Each buffer has a unique name, which is a string.  Many of the
functions that work on buffers accept either a buffer or a buffer name
as an argument.  Any argument called BUFFER-OR-NAME is of this sort,
and an error is signaled if it is neither a string nor a buffer.  Any
argument called BUFFER must be an actual buffer object, not a name.

   Buffers that are ephemeral and generally uninteresting to the user
have names starting with a space, so that the `list-buffers' and
`buffer-menu' commands don't mention them (but if such a buffer visits
a file, it *is* mentioned).  A name starting with space also initially
disables recording undo information; see *note Undo::.

 -- Function: buffer-name &optional buffer
     This function returns the name of BUFFER as a string.  BUFFER
     defaults to the current buffer.

     If `buffer-name' returns `nil', it means that BUFFER has been
     killed.  *Note Killing Buffers::.

          (buffer-name)
               => "buffers.texi"

          (setq foo (get-buffer "temp"))
               => #<buffer temp>
          (kill-buffer foo)
               => nil
          (buffer-name foo)
               => nil
          foo
               => #<killed buffer>

 -- Command: rename-buffer newname &optional unique
     This function renames the current buffer to NEWNAME.  An error is
     signaled if NEWNAME is not a string.

     Ordinarily, `rename-buffer' signals an error if NEWNAME is already
     in use.  However, if UNIQUE is non-`nil', it modifies NEWNAME to
     make a name that is not in use.  Interactively, you can make
     UNIQUE non-`nil' with a numeric prefix argument.  (This is how the
     command `rename-uniquely' is implemented.)

     This function returns the name actually given to the buffer.

 -- Function: get-buffer buffer-or-name
     This function returns the buffer specified by BUFFER-OR-NAME.  If
     BUFFER-OR-NAME is a string and there is no buffer with that name,
     the value is `nil'.  If BUFFER-OR-NAME is a buffer, it is returned
     as given; that is not very useful, so the argument is usually a
     name.  For example:

          (setq b (get-buffer "lewis"))
               => #<buffer lewis>
          (get-buffer b)
               => #<buffer lewis>
          (get-buffer "Frazzle-nots")
               => nil

     See also the function `get-buffer-create' in *note Creating
     Buffers::.

 -- Function: generate-new-buffer-name starting-name &optional ignore
     This function returns a name that would be unique for a new
     buffer--but does not create the buffer.  It starts with
     STARTING-NAME, and produces a name not currently in use for any
     buffer by appending a number inside of `<...>'.  It starts at 2
     and keeps incrementing the number until it is not the name of an
     existing buffer.

     If the optional second argument IGNORE is non-`nil', it should be
     a string, a potential buffer name.  It means to consider that
     potential buffer acceptable, if it is tried, even it is the name
     of an existing buffer (which would normally be rejected).  Thus, if
     buffers named `foo', `foo<2>', `foo<3>' and `foo<4>' exist,

          (generate-new-buffer-name "foo")
               => "foo<5>"
          (generate-new-buffer-name "foo" "foo<3>")
               => "foo<3>"
          (generate-new-buffer-name "foo" "foo<6>")
               => "foo<5>"

     See the related function `generate-new-buffer' in *note Creating
     Buffers::.


File: elisp,  Node: Buffer File Name,  Next: Buffer Modification,  Prev: Buffer Names,  Up: Buffers

27.4 Buffer File Name
=====================

The "buffer file name" is the name of the file that is visited in that
buffer.  When a buffer is not visiting a file, its buffer file name is
`nil'.  Most of the time, the buffer name is the same as the
nondirectory part of the buffer file name, but the buffer file name and
the buffer name are distinct and can be set independently.  *Note
Visiting Files::.

 -- Function: buffer-file-name &optional buffer
     This function returns the absolute file name of the file that
     BUFFER is visiting.  If BUFFER is not visiting any file,
     `buffer-file-name' returns `nil'.  If BUFFER is not supplied, it
     defaults to the current buffer.

          (buffer-file-name (other-buffer))
               => "/usr/user/lewis/manual/files.texi"

 -- Variable: buffer-file-name
     This buffer-local variable contains the name of the file being
     visited in the current buffer, or `nil' if it is not visiting a
     file.  It is a permanent local variable, unaffected by
     `kill-all-local-variables'.

          buffer-file-name
               => "/usr/user/lewis/manual/buffers.texi"

     It is risky to change this variable's value without doing various
     other things.  Normally it is better to use
     `set-visited-file-name' (see below); some of the things done
     there, such as changing the buffer name, are not strictly
     necessary, but others are essential to avoid confusing Emacs.

 -- Variable: buffer-file-truename
     This buffer-local variable holds the abbreviated truename of the
     file visited in the current buffer, or `nil' if no file is visited.
     It is a permanent local, unaffected by `kill-all-local-variables'.
     *Note Truenames::, and *note Definition of abbreviate-file-name::.

 -- Variable: buffer-file-number
     This buffer-local variable holds the file number and directory
     device number of the file visited in the current buffer, or `nil'
     if no file or a nonexistent file is visited.  It is a permanent
     local, unaffected by `kill-all-local-variables'.

     The value is normally a list of the form `(FILENUM DEVNUM)'.  This
     pair of numbers uniquely identifies the file among all files
     accessible on the system.  See the function `file-attributes', in
     *note File Attributes::, for more information about them.

     If `buffer-file-name' is the name of a symbolic link, then both
     numbers refer to the recursive target.

 -- Function: get-file-buffer filename
     This function returns the buffer visiting file FILENAME.  If there
     is no such buffer, it returns `nil'.  The argument FILENAME, which
     must be a string, is expanded (*note File Name Expansion::), then
     compared against the visited file names of all live buffers.  Note
     that the buffer's `buffer-file-name' must match the expansion of
     FILENAME exactly.  This function will not recognize other names
     for the same file.

          (get-file-buffer "buffers.texi")
              => #<buffer buffers.texi>

     In unusual circumstances, there can be more than one buffer
     visiting the same file name.  In such cases, this function returns
     the first such buffer in the buffer list.

 -- Function: find-buffer-visiting filename &optional predicate
     This is like `get-file-buffer', except that it can return any
     buffer visiting the file _possibly under a different name_.  That
     is, the buffer's `buffer-file-name' does not need to match the
     expansion of FILENAME exactly, it only needs to refer to the same
     file.  If PREDICATE is non-`nil', it should be a function of one
     argument, a buffer visiting FILENAME.  The buffer is only
     considered a suitable return value if PREDICATE returns non-`nil'.
     If it can not find a suitable buffer to return,
     `find-buffer-visiting' returns `nil'.

 -- Command: set-visited-file-name filename &optional no-query
          along-with-file
     If FILENAME is a non-empty string, this function changes the name
     of the file visited in the current buffer to FILENAME.  (If the
     buffer had no visited file, this gives it one.)  The _next time_
     the buffer is saved it will go in the newly-specified file.

     This command marks the buffer as modified, since it does not (as
     far as Emacs knows) match the contents of FILENAME, even if it
     matched the former visited file.  It also renames the buffer to
     correspond to the new file name, unless the new name is already in
     use.

     If FILENAME is `nil' or the empty string, that stands for "no
     visited file."  In this case, `set-visited-file-name' marks the
     buffer as having no visited file, without changing the buffer's
     modified flag.

     Normally, this function asks the user for confirmation if there
     already is a buffer visiting FILENAME.  If NO-QUERY is non-`nil',
     that prevents asking this question.  If there already is a buffer
     visiting FILENAME, and the user confirms or QUERY is non-`nil',
     this function makes the new buffer name unique by appending a
     number inside of `<...>' to FILENAME.

     If ALONG-WITH-FILE is non-`nil', that means to assume that the
     former visited file has been renamed to FILENAME.  In this case,
     the command does not change the buffer's modified flag, nor the
     buffer's recorded last file modification time as reported by
     `visited-file-modtime' (*note Modification Time::).  If
     ALONG-WITH-FILE is `nil', this function clears the recorded last
     file modification time, after which `visited-file-modtime' returns
     zero.

     When the function `set-visited-file-name' is called interactively,
     it prompts for FILENAME in the minibuffer.

 -- Variable: list-buffers-directory
     This buffer-local variable specifies a string to display in a
     buffer listing where the visited file name would go, for buffers
     that don't have a visited file name.  Dired buffers use this
     variable.


File: elisp,  Node: Buffer Modification,  Next: Modification Time,  Prev: Buffer File Name,  Up: Buffers

27.5 Buffer Modification
========================

Emacs keeps a flag called the "modified flag" for each buffer, to
record whether you have changed the text of the buffer.  This flag is
set to `t' whenever you alter the contents of the buffer, and cleared
to `nil' when you save it.  Thus, the flag shows whether there are
unsaved changes.  The flag value is normally shown in the mode line
(*note Mode Line Variables::), and controls saving (*note Saving
Buffers::) and auto-saving (*note Auto-Saving::).

   Some Lisp programs set the flag explicitly.  For example, the
function `set-visited-file-name' sets the flag to `t', because the text
does not match the newly-visited file, even if it is unchanged from the
file formerly visited.

   The functions that modify the contents of buffers are described in
*note Text::.

 -- Function: buffer-modified-p &optional buffer
     This function returns `t' if the buffer BUFFER has been modified
     since it was last read in from a file or saved, or `nil'
     otherwise.  If BUFFER is not supplied, the current buffer is
     tested.

 -- Function: set-buffer-modified-p flag
     This function marks the current buffer as modified if FLAG is
     non-`nil', or as unmodified if the flag is `nil'.

     Another effect of calling this function is to cause unconditional
     redisplay of the mode line for the current buffer.  In fact, the
     function `force-mode-line-update' works by doing this:

          (set-buffer-modified-p (buffer-modified-p))

 -- Function: restore-buffer-modified-p flag
     Like `set-buffer-modified-p', but does not force redisplay of mode
     lines.

 -- Command: not-modified &optional arg
     This command marks the current buffer as unmodified, and not
     needing to be saved.  If ARG is non-`nil', it marks the buffer as
     modified, so that it will be saved at the next suitable occasion.
     Interactively, ARG is the prefix argument.

     Don't use this function in programs, since it prints a message in
     the echo area; use `set-buffer-modified-p' (above) instead.

 -- Function: buffer-modified-tick &optional buffer
     This function returns BUFFER's modification-count.  This is a
     counter that increments every time the buffer is modified.  If
     BUFFER is `nil' (or omitted), the current buffer is used.  The
     counter can wrap around occasionally.

 -- Function: buffer-chars-modified-tick &optional buffer
     This function returns BUFFER's character-change modification-count.
     Changes to text properties leave this counter unchanged; however,
     each time text is inserted or removed from the buffer, the counter
     is reset to the value that would be returned by
     `buffer-modified-tick'.  By comparing the values returned by two
     `buffer-chars-modified-tick' calls, you can tell whether a
     character change occurred in that buffer in between the calls.  If
     BUFFER is `nil' (or omitted), the current buffer is used.


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)
               => (#<buffer buffers.texi>
                   #<buffer  *Minibuf-1*> #<buffer buffer.c>
                   #<buffer *Help*> #<buffer TAGS>)

          ;; 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")
               => #<buffer 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 `<N>' 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")
               => #<buffer bar>
          (generate-new-buffer "bar")
               => #<buffer bar<2>>
          (generate-new-buffer "bar")
               => #<buffer bar<3>>

     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 8 on windows.texi>
          (window-edges)          ; Edges in order:
               => (0 0 80 50)     ;   left-top-right-bottom

          ;; Returns window created
          (setq w2 (split-window w 15))
               => #<window 28 on windows.texi>
          (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 32 on windows.texi>
          (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)
               => #<window 65 on windows.texi>

 -- 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)
               => #<window 56 on windows.texi>
          (next-window (selected-window))
               => #<window 52 on windows.texi>
          (next-window (next-window (selected-window)))
               => #<window 56 on windows.texi>

 -- 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)
               => #<buffer windows.texi>

 -- 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 accommodate 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.

     This 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 4 on windows.texi>
          (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)
               => #<window 25 on control.texi>
          (setq w (selected-window))
               => #<window 19 on control.texi>
          (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.

     When you use `frame-parameter' to query the value of either of
     these two frame parameters, the return value is always an integer.
     When using `set-frame-parameter', passing a `nil' value imposes an
     actual default value of 8 pixels.

     The combined fringe widths must add up to an integral number of
     columns, so the actual default fringe widths for the frame, as
     reported by `frame-parameter', may be larger than what you
     specify.  Any extra width 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.)
     On toolkits that support menu titles, the title is taken from the
     prompt string of MENU if MENU is a keymap, or from the prompt
     string of the first keymap in MENU if it is a list of keymaps
     (*note Defining Menus::).

     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 <RET>
x-pointer <RET>' 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.  This is called an "excursion", and it is done
with the `save-excursion' special form.  This construct remembers the
initial identity of the current buffer, and its values of point and the
mark, and restores them after the excursion completes.  It is the
standard way to move point within one part of a program and avoid
affecting the rest of the program, and is used thousands of times in
the Lisp sources of Emacs.

   If you only need to save and restore the identity of the current
buffer, use `save-current-buffer' or `with-current-buffer' instead
(*note Current Buffer::).  If you need to save or restore window
configurations, see the forms described in *note Window
Configurations:: and in *note Frame Configurations::.

 -- Special Form: save-excursion body...
     This 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 value returned by `save-excursion' is the result of the last
     form in BODY, or `nil' if no body forms were given.

   Because `save-excursion' only saves point and mark for the buffer
that was current at the start of the excursion, any changes made to
point and/or mark in other buffers, during the excursion, will remain
in effect afterward.  This frequently leads to unintended consequences,
so the byte compiler warns if you call `set-buffer' during an excursion:

     Warning: `save-excursion' defeated by `set-buffer'

To avoid such problems, you should call `save-excursion' only after
setting the desired current buffer, as in the following example:

     (defun append-string-to-buffer (string buffer)
       "Append STRING to the end of BUFFER."
       (with-current-buffer buffer
         (save-excursion
           (goto-char (point-max))
           (insert string))))

   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::).

   *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))
          => #<marker in no buffer>

     ;; Set `m1' to point between the 99th and 100th characters
     ;;   in the current buffer:
     (set-marker m1 100)
          => #<marker at 100 in markers.texi>

     ;; Now insert one character at the beginning of the buffer:
     (goto-char (point-min))
          => 1
     (insert "Q")
          => nil

     ;; `m1' is updated appropriately.
     m1
          => #<marker at 101 in markers.texi>

     ;; Two markers that point to the same position
     ;;   are not `eq', but they are `equal'.
     (setq m2 (copy-marker m1))
          => #<marker at 101 in markers.texi>
     (eq m1 m2)
          => nil
     (equal m1 m2)
          => t

     ;; When you are finished using a marker, make it point nowhere.
     (set-marker m1 nil)
          => #<marker in no buffer>

