⟦dc6f9d9c6⟧

TextFile

Info file: lispref,    -*-Text-*-
produced by texinfo-format-buffer
from file: lispref.texinfo









This file documents GNU Emacs Lisp.

This is Edition 0.1 Beta of the GNU Emacs Lisp Reference Manual, for
Emacs Version 18, with some references to Emacs Version 19.

Please read this document for review purposes.

Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA

Copyright (C) 1989 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Foundation.



▶1f◀
File: lispref  Node: Creating Buffers, Prev: The Buffer List, Up: Buffers, Next: Killing Buffers

Creating Buffers
================

  The following two functions create buffers: `get-buffer-create' may
create a buffer if it finds no existing buffer; `generate-new-buffer'
always creates a new buffer, and gives it a unique name.

  Two other functions that create buffers are
`with-output-to-temp-buffer' (*Note Temporary Displays::) and
`create-file-buffer' (*Note Visiting Files::).

* Function: get-buffer-create NAME

       This function returns a buffer named NAME.  If such a buffer
     already exists, it is returned.  If such a buffer does not exist,
     one is created and returned.  The buffer does not become the
     current buffer---this function does not change which buffer is
     current.

       It is an error if NAME is not a string.

          (get-buffer-create "foo")
               => #<buffer foo>

* Function: generate-new-buffer NAME

       This function returns a newly created, empty buffer.  If there is
     no buffer named NAME, then that is the name of the new buffer.  If
     there is a buffer with that name, then suffixes of the form `<N>'
     are tried, where N is an integer starting with 2, until a new name
     is created.

       It is an error 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>>

▶1f◀
File: lispref  Node: Killing Buffers, Prev: Creating Buffers, Up: Buffers, Next: Changing Buffers

Killing Buffers
===============

  There are two functions for killing buffers.  One is for killing a
specified buffer; it is used in both in code and interactively.  The
other is used interactivley and is for going through the list of
displayed buffers and killing particular ones.

  The `buffer-name' of a killed buffer is `nil'.  You can use this
feature when testing whether a buffer has been killed.

     (defun killed-buffer-p (buffer-or-name)
       "Return t if buffer is killed."
       (not (buffer-name buffer-or-name)))

* Command: kill-buffer BUFFER-OR-NAME

       This function kills the buffer BUFFER-OR-NAME, freeing all of its
     memory for use as space for other buffers.  (In version 18, the
     memory is not returned to the operating system.)  The function
     returns `nil'.

       A buffer which has been killed is marked specially so that you
     cannot make it current or display it.  Its name is forgotten, and
     `buffer-name' will return `nil' for it.  Killed buffers retain
     their identity, however; two distinct buffers, when killed, remain
     distinct according to `eq'.

       If the buffer is visiting a file when `kill-buffer' is called and
     the buffer has not been saved since it was last modified, the user
     is asked if he or she *really* wants to kill the buffer.  This is
     done even if `kill-buffer' is not called interactively.  To prevent
     this request for confirmation, clear the modified flag before
     calling `kill-buffer'.

          (kill-buffer "foo.unchanged")
               => nil
          (kill-buffer "foo.changed")

          ---------- Buffer: Minibuffer ----------
          Buffer foo.changed modified; kill anyway? (yes or no) yes
          ---------- Buffer: Minibuffer ----------

               => nil


▶1f◀
File: lispref  Node: Changing Buffers, Prev: Killing Buffers, Up: Buffers

Changing Buffers
================

  There are two major ways to change buffers: one way is to make it
"current", the other way is to "switch" to the buffer.

  The current buffer is the one in which editing takes place; but it is
not necessarily displayed on the screen.  You may not be able to see the
current buffer.  Programs work on the current buffer---a computer
program does not have eyes and does not look at the buffer on the
screen.

  Switching to a buffer, on the other hand, not only makes the buffer
the current buffer, which is the one in which editing takes place; it
also displays the buffer in the selected window so you can see it.
Humans must switch to a buffer they wish to work on since they have to
see what they are doing.

  Thus, directing Emacs's attention to a buffer does just one thing:
make it the current buffer; switching to a buffer does two things: make
it the current buffer, and display it on the screen.

  `switch-to-buffer' is a switch command; it changes the current buffer
(the one in which editing takes place) and displays it in the selected
window (the one with the cursor in it).

  `set-buffer' changes the current buffer, but leaves the buffer that
was displayed in the selected window still displayed.

  Note that when it comes time to get more keyboard input, or when
keyboard input is provided, the buffer displayed in the selected window
becomes the current buffer, regardless of previous calls to
`set-buffer'.  This prevents confusion: the buffer you see, when Emacs
reads a command, is the one to which your next command will apply.
*Note Command Loop::.

  However, Lisp programs should not rely on this.  Always use
`set-buffer' within a `save-excursion' that will restore the current
buffer when your program is done.  (*Note Excursions::.)  Otherwise, if
your program is used as a subroutine, the caller will get a surprise!
Here is an example: the code for the command `append-to-buffer' (with
the documentation string abridged):

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

In this function, a local variable is bound to the current buffer, and
then `save-excursion' function records the values of point, mark, and
the original buffer.  Next, the `set-buffer' function makes a new buffer
current.  `insert-buffer-substring' then copies the string from the
original buffer to the current buffer.  Because the current buffer is
not displayed in the selected window, you normally cannot see the
insertion.  To see it, you have to switch to the other buffer.

* Function: set-buffer BUFFER-OR-NAME

       This function makes BUFFER-OR-NAME the current buffer in which
     editing takes place.  However, it does not display the buffer in
     the currently selected window or in any other window.  This means
     that the user cannot necessarily see the buffer, but Lisp programs
     can work on it.

        This function returns the buffer identified by BUFFER-OR-NAME.
     It is an error if BUFFER-OR-NAME does not identify an existing
     buffer.

       The `set-buffer' function is usually written within a
     `save-excursion', so that the original buffer will be restored when
     the program is done.

* Command: switch-to-buffer BUFFER-OR-NAME &optional NORECORD

       This command makes BUFFER-OR-NAME the current buffer (the buffer
     in which editing takes place).  The command also displays the
     buffer in the selected window, which is the window with the cursor
     in it.  This means that a human can see the buffer and commands
     will apply to it.  The return value is `nil'.

       If BUFFER-OR-NAME does not identify an existing buffer, then a
     new buffer by that name is created.

       If NORECORD is non-`nil', then this buffer is not put on the
     front of the list of recently chosen buffers.  This affects the
     value of `other-buffer'.  (*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.

     (Contrast `switch-to-buffer' with `set-buffer', which makes
     BUFFER-OR-NAME the current buffer, but does not display it in the
     selected window.)

* Command: switch-to-buffer-other-window BUFFER-OR-NAME

       This function makes BUFFER-OR-NAME be the current buffer in
     another window, where editing may be done.  The other window
     becomes the selected window, with the cursor there.  If there is
     only one window, then it is split---even if that window is already
     displaying BUFFER-OR-NAME.

* Function: pop-to-buffer BUFFER-OR-NAME &optional OTHER-WINDOW

       This function makes BUFFER-OR-NAME be the current buffer (where
     editing is done) in some window that is preferably different from
     the selected window.  The ``popped-to'' window becomes the selected
     window, with the cursor in it.  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.  (*Note Splitting Windows::,
     for a description of `pop-up-windows'.

       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 be displayed in two
     windows.  On the other hand, if BUFFER-OR-NAME is the current
     buffer and OTHER-WINDOW is `nil', Emacs will stay with the same
     buffer in the same window.

       If BUFFER-OR-NAME is a string that does not name an existing
     buffer, a buffer by that name is created.

* Function: display-buffer BUFFER-OR-NAME &optional NOT-THIS-WINDOW

       This function makes BUFFER-OR-NAME appear in some window, like
     `pop-to-buffer', but it does not select that window and does not
     make the buffer current.  The selected window is unaltered by this
     function.

       If NOT-THIS-WINDOW is non-`nil' and BUFFER-OR-NAME is shown
     already in the selected window, then the buffer is displayed in a
     second window as well.  Otherwise, if BUFFER-OR-NAME is already
     shown in any window, that is good enough, so this function does
     nothing.

       If the variable `pop-up-windows' is non-`nil', windows can be
     split to display the buffer.  If there are multiple windows,
     `display-buffer' will split the largest window if it has more than
     the number of lines specified by the variable
     `split-height-threshold'.  (*Note Splitting Windows::, for a
     description of the two variables.)

       `display-buffer' returns the window displaying BUFFER-OR-NAME.

* User Option: pop-up-windows

       This global variable determines if `display-buffer' may make new
     windows.  If it is `t' and there is only one window on the screen,
     then that window is split.  If it is `nil', then `display-buffer'
     does not split the single window, but rather replaces its buffer.

* User Option: split-height-threshold

       This global variable determines when `display-buffer' may split a
     window, assuming that there are multiple windows.  `display-buffer'
     splits the largest window if it has at least this many lines.

       If there is only one window, it splits regardless of this value,
     provided `pop-up-windows' is non-`nil'.


▶1f◀
File: lispref  Node: Windows, Prev: Buffers, Up: Top, Next: Positions

Windows
*******

  This chapter describes most of the functions and variables related to
Emacs windows.  However, *Note Emacs Display::, and *Note Changing
Buffers::, for more information.

* Menu:

* Window Basics::       
* Splitting Windows::   
* Deleting Windows::    
* Selecting Windows::   
* Cyclic Window Ordering::      
* Buffers and Windows:: 
* Window Point::        
* Vertical Scrolling::  
* Horizontal Scrolling::        
* Window Size:: 
* Window Configurations::       

▶1f◀
File: lispref  Node: Window Basics, Prev: Windows, Up: Windows, Next: Splitting Windows

Window Basics
=============

  A "window" is the physical area of a terminal in which a buffer is
displayed.  But the term is also used to refer to a Lisp object.  Which
is meant should be clear from the context.

  At all times, there is at least one window displayed on the screen,
and there is exactly one window that we call the "selected window".  The
cursor is in the selected window.  The selected window's buffer is
usually the current buffer, except temporarily during a command when
`set-buffer' has been used.  (*Note Changing Buffers::.)

  For all intents and purposes, a window only exists as long as it is
displayed on the terminal.  Once removed from the display, the window is
effectively deleted and should not be used, *even though there may still
be references to it* from other Lisp objects.  (*Note Deleting
Windows::.)

  Each window has the following attributes:


   * window height

   * window width

   * window edges with respect to the screen

   * the buffer displayed

   * position within the buffer at the upper left of the window

   * how many horizontally scrolled columns

   * point

   * mark

   * position in the window circular list


  Applications use multiple windows for a variety of reasons, but most
often to give different views of the same object.  In Rmail, for
example, if you request a message header summary, you are given a second
window with the headers displayed within it.  In this window, you can
process a message by moving point to the line listing the message and
applying Rmail Summary Mode commands.

  For information about other techniques, *Note Major Modes:
(emacs)Major Modes..  Also, *Note Key Bindings: (emacs)Key Bindings..

  Use of the word `window' to refer to a view of a buffer was
established long ago in Emacs.  The metaphor was inspired by how you
look out a house window---at part (or sometimes all) of an overall view.
You see part (or sometimes all) of a buffer through an Emacs window.  In
Emacs, each window may look upon a different view, like different
windows of a house.

  The term ``window'' as used in this manual means something different
from the term as used in a window system like X.  In this manual, the
term ``window'' refers to one of several in the Emacs "screen".  In a
system like X, the screen may happen to be one window in a window
system.  Expressed another way, Emacs's windows are in a screen that may
itself be a `window' of a windowing system.

  For those familiar with windowing systems, Emacs's windows are
rectangles tiled onto the rectangle of the screen, and every portion of
the screen is part of some window.  There are no areas which do not
belong to a window, except for the minibuffer (and even it acts like a
window sometimes).  This limitation helps avoid wasting the historically
scarce resource of screen space.  It also works very well with
character-only terminals.  Because of the way in which Emacs creates new
windows and resizes them, you can't create every conceivable tiling on
an Emacs screen.  *Note Splitting Windows::.  Also, *Note Window Size::.

  *Note Emacs Display::, for functions related to the Emacs screen.

* Function: windowp OBJECT

       This function returns `t' if object is a window.

▶1f◀
File: lispref  Node: Splitting Windows, Prev: Window Basics, Up: Windows, Next: Deleting Windows

Splitting Windows
=================

  The functions described here split windows, as do two other functions,
`pop-to-buffer' and `display-buffer'.  (*Note Changing Buffers::.)

  The distinction between these functions and the `pop-to-buffer' and
`display-buffer' functions is that the latter refer specifically to
buffers, while the functions described in this section do not.  These
functions let the two ``halves'' of the split window display the
previously visible buffer in the window that was split.

  The `split-window-horizontally' and the `split-window-vertically'
functions described in this section are interfaces to the
`split-windows' function.

* Function: one-window-p &optional NO-MINI

       Returns non-`nil' if there is only one window.  Optional NO-MINI
     non-`nil' means don't count the minibuffer even if it is active.

* Command: split-window &optional WINDOW SIZE HORIZONTAL

       This function splits WINDOW into two, leaving SIZE lines in
     WINDOW (which becomes the top window), and putting the rest of the
     lines that WINDOW had into the new window.

       `split-window' returns the window created.  The original window
     remains the selected window.

       If HORIZONTAL is non-`nil', then WINDOW splits side by side,
     leaving SIZE columns in WINDOW (which becomes the left-hand
     window), and putting the rest of the columns that WINDOW had into
     the new window.

       If WINDOW is omitted, then the selected window is split.

       If SIZE is omitted, 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, WINDOW defaults to
     the selected window, and SIZE and HORIZONTAL default to `nil'.

       The following example starts with one window on a screen that is
     50 lines high by 80 columns wide; then the window is split.  (Also,
     *Note Window Point::.)

          (setq w (selected-window))
               => #<window 8 on windows.texinfo>
          (window-edges)               ; Edges in order: left--top--right--bottom
               => (0 0 80 49)

          (setq w2 (split-window w 15))   ; Returns window created
               => #<window 28 on windows.texinfo>
          (window-edges w2)
               => (0 15 80 49)  ; 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 49

           column 1   column 80

     Next, the top window is split horizontally:

          (setq w3 (split-window w 35 t))
               => #<window 32 on windows.texinfo>
          (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 49)  ; Bottom window unchanged

     Now, the screen looks like this:

               column 35
                   __________   line 0
                  |   |      |  
                  | w |  w3  |
                  |___|______|  line 15
                  |          |
                  |    w2    |
                  |__________|  line 49

           column 1   column 80

* Command: split-window-vertically SIZE

       This function splits the selected window into two, one above the
     other, leaving the selected window with SIZE lines.

       This function is simply an interface to `split-windows'.  Here is
     the complete function definition for it:

          (defun split-window-vertically (&optional arg)
            "Split selected window into two windows, one above the other.
          This window becomes the uppermost of the two, and gets
          ARG lines.  No arg means split equally."
            (interactive "P")
            (split-window nil (and arg (prefix-numeric-value arg))))

* Command: split-window-horizontally SIZE

       This function splits the selected window into two, side-by-side,
     leaving the selected window with SIZE lines.

       This function is simply an interface to split-windows.  Here is
     the complete definition for `split-window-horizontally', except
     that part of the documentation has been deleted to save space:

          (defun split-window-horizontally (&optional arg)
            "Split selected window into two windows side by side."
            (interactive "P")
            (split-window nil (and arg (prefix-numeric-value arg)) t))


▶1f◀
File: lispref  Node: Deleting Windows, Prev: Splitting Windows, Up: Windows, Next: Selecting Windows

Deleting Windows
================

  A deleted window no longer appears on the screen.  In Emacs version
18, the space it took up is divided proportionally among all siblings;
in version 19, the space is given to one adjacent sibling.

* Command: delete-window &optional WINDOW

       This function removes WINDOW from the display.  If WINDOW is
     omitted, then the selected window is deleted.  It is an error if
     there is only one window being displayed when `delete-window'
     executes.

          Warning: Erroneous information or fatal errors may result by
          using a deleted window.  You can test whether a window has
          been deleted with `(window-point WINDOW)'.

       This function returns `nil'.

       When `delete-window' is called interactively, WINDOW defaults to
     the selected window.


* Command: delete-other-windows WINDOW

       This function makes WINDOW the only window on the screen by
     deleting all the other windows.  If WINDOW is omitted, then the
     selected window is the one remaining.

       The result is `nil'.

* Command: delete-windows-on BUFFER

       This function deletes all windows showing BUFFER.  If there are
     no windows showing BUFFER, then this function does nothing.  If all
     windows are showing BUFFER (including the case where there is only
     one window), then the screen reverts to having a single window
     showing the buffer chosen by `other-buffer'.

       If there are several windows showing different buffers, then
     those showing BUFFER are removed, and the others are expanded to
     fill the void.

       The result is `nil'.

▶1f◀
File: lispref  Node: Selecting Windows, Prev: Deleting Windows, Up: Windows, Next: Cyclic Window Ordering

Selecting Windows
=================

When a window is selected, the buffer in the window becomes the current
buffer.  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

       This function makes WINDOW the selected window.  The cursor then
     appears in WINDOW (on redisplay).  The current buffer changes to
     WINDOW's buffer

       It returns WINDOW.

          (setq w (next-window))
          (select-window w)
               => #<window 65 on windows.texinfo>

  Often you want to try to select the ``best'' window.  These functions
give you a choice of criteria with which to choose.

* Function: get-lru-window

       This function returns the window least recently used or selected
     for display.  The selected window is the most recently used window.

       The selected window can be the least recently used window if it
     is the only window.  A newly created window becomes the least
     recently used window until it is selected.  The minibuffer window
     is never returned by this function.

          (get-lru-window)
               => #<window 58 on windows.texinfo>

* Function: get-largest-window

       This function returns the window with the largest area (height
     times width).  If the screen is not divided horizontally, then this
     is just the window with the most lines.

       If there are two windows of the same size, then the function
     returns the window which is first in the canonical ordering of
     windows, starting from the seleted window.  The minibuffer is never
     considered for ``largest''.

▶1f◀
File: lispref  Node: Cyclic Window Ordering, Prev: Selecting Windows, Up: Windows, Next: Buffers and Windows

Cycling Through All Windows
===========================

  The order in which windows are selected by functions such as
`next-window' depends on the order in which the screen or the windows
within the screen were split.

  If the screen (or window) was first split vertically (into windows one
above each other), and then the topmost window was split horizontally,
then the ordering is left to right in the top, and then left to right in
the next lower part of the screen, and so on.  If the screen (or window)
was first split horizontally, the ordering is top to bottom in the left
part, and so on.  Within each set of siblings, the order is left to
right, or top to bottom.

* Function: next-window WINDOW &optional MINIBUF

       This function returns the next window after WINDOW in the
     canonical ordering of windows.  The successor to that window is the
     window which would be selected by `(other-window 1)'.

       The ordering includes all the windows except perhaps the
     minibuffer.  The value of the argument MINIBUF determines whether
     the minibuffer is in the window order.

       If MINIBUF is `t', then the canonical ordering includes the
     minibuffer window even if it is not active.  If MINIBUF is neither
     `t' nor `nil', then the minibuffer window is not included even if
     it is active.  *Note Minibuffers::, for what it means for the
     minibuffer to be active.

       In the example, there are two windows in existence.  They both
     happen to be displaying the same buffer.

          (selected-window)
               => #<window 56 on windows.texinfo>
          (next-window (selected-window))
               => #<window 52 on windows.texinfo>
          (next-window (next-window (selected-window)))
               => #<window 56 on windows.texinfo>

       If WINDOW is the only window visible, then this function returns
     WINDOW.

* Function: previous-window WINDOW

       This function returns the window preceding WINDOW in the
     canonical ordering of windows.

* Command: other-window COUNT

       This function selects the COUNT'TH next window.  If count is
     negative, then it selects the COUNT'TH previous window.

       It returns `nil'.

       When called interactively, it sets COUNT to the processed prefix
     argument.

       The canonical ordering of windows specifies the value of the
     COUNT'TH next window.

▶1f◀
File: lispref  Node: Buffers and Windows, Prev: Cyclic Window Ordering, Up: Windows, Next: Window Point

Buffers and Windows
===================

  This section describes low level functions to examine windows or to
show buffers in windows in a precisely controlled fashion.

  *Note Changing Buffers::, for related functions that find a window to
use and specify a buffer for it.  The functions described there are
easier to use than those described here.  Use those described here when
you need complete control.

* Function: set-window-buffer WINDOW BUFFER-OR-NAME

       This function makes WINDOW display BUFFER-OR-NAME as its
     contents.  It returns BUFFER-OR-NAME.

          (set-window-buffer (selected-window) "foo")
               => nil

* Function: window-buffer &optional WINDOW

       This function returns the buffer that WINDOW is displaying.  If
     WINDOW is omitted, then this function returns the buffer for the
     selected window.

          (window-buffer)
               => #<buffer windows.texinfo>

* Function: get-buffer-window BUFFER-OR-NAME

       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 window which is first
     in the canonical ordering of windows, starting from the selected
     window.

* Command: replace-buffer-in-windows BUFFER

       This function replaces BUFFER with some other buffer in all
     windows showing it.  The other buffer used is chosen with
     `other-buffer'; but in the usual applications of this function, you
     don't care which other buffer is used.

       This function returns `nil'.

▶1f◀
File: lispref  Node: Window Point, Prev: Buffers and Windows, Up: Windows, Next: Vertical Scrolling

Window Point
============

  Each window has a value of point, which is independent of the value of
point in other windows on the same buffer.

   * The window point is established when a window is first opened on a
     buffer and the initial value of the window point is set to be the
     value of the buffer's point or the window point of another window
     opened on the buffer, if such a window exists.

   * While the selected window displays the current buffer, the changing
     the value of point in the window changes the value of point in the
     buffer.

   * When the last window opened on a buffer is deleted, the value of
     point in the buffer is left set to the value of the window's point
     before the window was deleted.  *Note Positions::, for more details
     on positions.

  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 WINDOW

       This function returns the current position of the point in
     WINDOW.  For a nonselected window, this is the value the point
     would have if that window were selected.

       When WINDOW is the selected window and its buffer is also
     currently selected, the value returned is the same as `(point)'.

       It would be more strictly correct to return the `top-level' value
     of point, outside of any `save-excursion' forms.  But that is hard
     to find.

* Function: set-window-point WINDOW POSITION

       This function positions the point in WINDOW at POSITION in
     WINDOW's buffer.

* Function: window-start &optional WINDOW

       This function returns the position in the buffer displayed by
     WINDOW at which the display starts.  This is the same number that
     `(point)' returns when the cursor is positioned at the beginning of
     the top line in the window.

       If WINDOW is `nil', the selected window is used.

          (window-start)
               => 7058

* Function: set-window-start WINDOW POSITION &optional NOFORCE

       This function makes the display in WINDOW start at POSITION in
     WINDOW's buffer.  Normally the display starts at the beginning of a
     line, although this is not required.

       Point is associated with a position within the buffer, and must
     be visible.  In the case that this function completes in such a way
     that point would not be visible on the screen, Emacs moves point so
     that point is visible.  For example, if point is 1 and we attempt
     to set the start of the window at 2, then the position of point
     would be ``above'' the window, except that Emacs re-positions point
     so that it is visible.  (Point is placed in the left-most column of
     the middle line of the window.)

          ;; 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) (1+ (window-start)))

          ;; Here is what `foo' looks like after executing
          ;; the `set-window-start' expression.

          ---------- Buffer: foo ----------
          his is the contents of buffer foo.
          2
          3
          -!-4
          5
          6
          ---------- Buffer: foo ----------

               => 2

       However, when NOFORCE is non-`nil', the function does not change
     the start position or the value of point if in changing the start
     position it would move point off the screen and then re-position
     it.  In this case, the function has no effect.

       The function returns the requested starting position of the
     window, regardless of whether the NOFORCE option caused that
     position to be overruled

* Function: pos-visible-in-window-p &optional POSITION WINDOW

       This function returns `t' if POSITION is currently visible on the
     screen in WINDOW, or if POSITION is currently out of view only
     because it has been scrolled horizontally.  The function returns
     `nil' if POSITION is scrolled vertically out of view.  POSITION
     defaults to the current point; WINDOW, to the selected window.

          (pos-visible-in-window-p (point) (selected-window))

      The `pos-visible-in-window-p' function will return `t' if POSITION
     is out of view only because it has been scrolled horizontally.
     Here is how you could test whether POSITION is visible when there
     is horizontal scrolling:

          (save-excursion 
            (goto-char POSITION)
            (and 
             (>= (- (current-column) (window-hscroll WINDOW)) 0)
             (< (- (current-column) (window-hscroll WINDOW))
                (window-width WINDOW))))

▶1f◀
File: lispref  Node: Vertical Scrolling, Prev: Window Point, Up: Windows, Next: Horizontal Scrolling

Vertical Scrolling
==================

  Vertical scrolling changes the value returned by `window-start'; and
may change the value of `window-point' to keep it on the screen.

  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.  You can 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 argued that the converse convention be used: that the
user imagine that the text does not move but the window does.  Then
`down' commands would take you to the end of the buffer.  However, the
position of a window on your terminal does not move, and short scrolling
commands clearly do move the text up or down, so the chosen convention
makes more sense.  Repeated `down' commands bring you to the beginning
of the buffer.

* Command: scroll-up &optional COUNT

       This function scrolls text in the selected window upward COUNT
     lines.  COUNT defaults to `nil'.  If COUNT is `nil', then the
     length of the scroll is `next-screen-context-lines' lines less than
     the height of the window in usable lines.

       `scroll-up' returns `nil'.

* Command: scroll-down &optional COUNT

       This function scrolls the text in the selected window downward
     COUNT lines.  If COUNT is omitted, then the length of the scroll is
     `next-screen-context-lines' lines less than the height of the
     window in usable lines.

       `scroll-down' returns `nil'.

* Command: scroll-other-window &optional COUNT

       This function scrolls the text in the next window upward COUNT
     lines.  The next window is the one below (or to the right of) the
     current one; or the one at the top (right hand side) of the screen
     if the current one is at the bottom (left hand side).  More
     precisely, it is the window returned by `(next-window)'.

       When the minibuffer is active, this command will attempt to
     scroll the minibuffer if that is the next window.  If the
     minibuffer contains just one line, that line will be redisplayed
     after the echo area momentarily displays the message ``Beginning of
     buffer''.

     Also, see `minibuffer-scroll-window' in *Note Minibuffer Odds and
     Ends::.

* User Option: scroll-step

       The value of this variable is the number of lines Emacs should
     try scrolling a window, when point moves out of the window.  If
     this value is zero, the line that the point is on always goes to
     the center of the window after the point moves off screen.

       If scrolling by `scroll-step' would fail to bring point back on
     screen, then Emacs centers point anyway.

* User Option: next-screen-context-lines

       The value of this variable is the number of lines of continuity
     to retain when scrolling by screenfulls.  This means that when
     `scroll-up' executes, this many lines that had been visible at the
     bottom of the screen are now visible at the top of the screen.  The
     default value is `2'.

* Command: recenter &optional COUNT

       This function re-positions the text displayed in the selected
     window.  It puts the line containing point COUNT lines down from
     the top of the window and redraws only that window.  The text
     displayed in the other windows does not move.

       If COUNT is `nil', then it puts the line containing point in the
     center of the window, and redisplays the entire screen.  If COUNT
     is a non-`nil' list, then it puts the line containing point in the
     center of the window, but only redisplays as much of the window as
     necessary to position the text---only with `nil' does it redisplay
     the entire screen.

       When `recenter' is called interactively, Emacs sets COUNT to the
     unprocessed prefix argument.  Thus, typing `C-u' as the prefix sets
     the prefix argument to a non-`nil' list, while typing `C-u 4'
     positions the line four lines from the top.

       Typing `C-u 0 C-l' positions the current line at the top of the
     screen.  This action is so very handy that some people bind the
     command to a function key.  For example,

          (defun line-to-top-of-screen ()
            "Moves line point is on to top of screen.
          Replaces three keystroke sequence C-u 0 C-l."
            (interactive) 
            (recenter 0))

          ;; Bind function key PF6 on AAA terminal.
          (global-set-key "\eOF" 'line-to-top-of-screen)  

▶1f◀
File: lispref  Node: Horizontal Scrolling, Prev: Vertical Scrolling, Up: Windows, Next: Window Size

Horizontal Scrolling
====================
  
  Horizontal scrolling is not like vertical scrolling; it is implemented
at a lower level and does not change the value returned by
`window-start'.  It leaves out certain columns of the display and shows
other columns (that may have no text in them).  Usually, horizontal
scrolling starts with the leftmost column at the left edge of the
window; in this case, the columns displayed cannot be scrolled to the
right.  Columns in the display can be scrolled to the right only after
they have first been scrolled left.  There is no limit to left scrolling
except the size of the largest integer, but if you scroll farther than
the length of the longest line on the screen, you won't see anything but
emptiness.

* Command: scroll-left COUNT

       This function scrolls the selected window COUNT columns to the
     left.  It scrolls to the right if COUNT is negative.

* Command: scroll-right COUNT

       This function scrolls the selected window COUNT columns to the
     right.  It scrolls to the left if COUNT is negative.

       Once you scroll a window as far right as it can go, trying to
     scroll any farther has no effect.

* Function: window-hscroll &optional WINDOW

       This function returns the number of columns by which WINDOW is
     scrolled from the left margin.

       When the leftmost column is at the left edge of the window, this
     function returns 0.  The value is never negative.

       If WINDOW is `nil', the selected window is used.
          (window-hscroll)
               => 0

* Function: set-window-hscroll WINDOW COLUMNS

       This function sets the number of columns from the left margin
     that WINDOW is scrolled to the value of COLUMNS.  COLUMNS should be
     zero or positive.

       The value returned is COLUMNS.

          (set-window-hscroll (selected-window)  10)
               => 10

▶1f◀
File: lispref  Node: Window Size, Prev: Horizontal Scrolling, Up: Windows, Next: Window Configurations

Window Size
===========

  The window size functions fit 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, so
enlarging one window affects all of them.

* Command: enlarge-window SIZE &optional HORIZONTAL

       This function makes the selected window SIZE lines bigger,
     stealing lines from neighboring windows.  It generally tries to
     steal equal numbers of lines from the other windows.  If a window
     from which lines are stolen shrinks below `window-min-height', then
     that window disappears.

       If HORIZONTAL is non-`nil', then this function makes WINDOW wider
     by SIZE columns, stealing columns as it does lines.  If a window
     from which lines are stolen shrinks below `window-min-width', then
     that window disappears.

       If the screen is smaller than SIZE lines (or columns), then the
     function makes the window occupy the entire height (or width) of
     the screen.

       If SIZE is negative, this function shrinks window instead by
     -SIZE.

       `enlarge-window' returns `nil'.

* Command: enlarge-window-horizontally COLUMNS

       This function makes the selected window COLUMNS wider.

       It is simply an interface to `enlarge-window'.

* Command: shrink-window SIZE &optional HORIZONTAL

       This function is the exact analog to `enlarge-window', making the
     selected window smaller by giving lines (or columns) to the other
     windows.  If the window shrinks below `window-min-height', then it
     disappears.  If SIZE is negative, it enlarges instead by -SIZE.

* Command: shrink-window-horizontally COLUMNS

       This function makes the selected window COLUMNS narrower.

       This function is simply an interface to `shrink-window'.

  The following three functions return size information about a window.

* Function: window-height &optional WINDOW

       This function returns the number of lines in WINDOW (including
     its mode line).  If WINDOW fills the entire screen, this is one
     less than what `(screen-height)' would return (since the last line
     is always reserved for the minibuffer).

       If WINDOW is `nil', the function uses the selected window.

          (window-height)
               => 49

* Function: window-width &optional WINDOW

       This function returns the number of columns in WINDOW.  If WINDOW
     fills the entire screen, this is what `(screen-width)' would
     return.

       If WINDOW is `nil', the function uses the selected window.

          (window-width)
               => 80

* Function: window-edges &optional WINDOW

       This function returns a list of the edge coordinates of WINDOW.
     The order of the list is: `(LEFT TOP RIGHT BOTTOM)', all relative
     to 0, 0 at the top left corner of the screen.

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

       For example, the edges of the following window are `0 0 5 8'.
     (The mode line is shown with `xxxxxxxxx'.)

                     0    
                     _______
                  0 |       | 
                    |       |   
                    |       | 
                    xxxxxxxxx  5

                            8     

       If WINDOW fills the entire screen, then RIGHT and BOTTOM are the
     same as the values returned by `(window-width)' and
     `(window-height)' respectively.

       When the screen is split, and the window's right side is a
     separator, the value of RIGHT is the column number of the
     separator; conversely, if the window's left side is a separator,
     the value of LEFT is the column number of the separator;

       In the following example, the edges of the left window are `0 0 4
     5' and the edges of the right window are `4 0 8 5'.

                     ___ ___
                    |   |   |    
                    |   |   |    
                    |123|567|    
                    xxxxxxxxx 

       If WINDOW is `nil', the function uses the selected window.

          (window-edges (selected-window))
               => (0 0 80 49)

          (list 0 0 (window-width) (window-height))
               => (0 0 80 49)

  The following two variables constrain resizing functions to a minimum
height and width.

* User Option: window-min-height

       The value of this variable determines how short a window may
     become before it disappears.  When other windows are being
     enlarged, the window disappears when it becomes smaller than this.
     No window may be created that is smaller than this.  The absolute
     minimum height is 2 (allowing one line for the mode line, and one
     line for the buffer display); actions which change window sizes
     reset this variable to 2 if it is less than 2.

* User Option: window-min-width

       The value of this variable determines how narrow a window may
     become before it disappears.  When other windows are bing enlarged,
     the window disappears when it becomes narrower than this.  No
     window may be created that is narrower than this.  The absolute
     minimum width is 1; any value below that is ignored.

▶1f◀
File: lispref  Node: Window Configurations, Prev: Window Size, Up: Windows

Window Configurations
=====================

  Window configurations record entire screen layouts---all windows,
their sizes, which buffers they contain, what part of each buffer is
displayed, and the values of point and mark.

  Sometimes you want Emacs to restore the window configuration to some
saved past pattern.  This can be done with the following functions and
special forms.

  No one has implemented primitives to look inside of window
configurations.

* Function: current-window-configuration

       This function returns a new object representing Emacs's selected
     window configuration, namely the number of windows, their sizes and
     current buffers, which window is the selected window, and for each
     displayed buffer, where display starts, and the positions of the
     point and the mark.  An exception is made for the point in the
     current buffer, whose value is not saved.  An example of how it
     could be used with `set-window-configuration' to emulate
     `save-window-excursion' appears below with `save-window-excursion'.

* Function: set-window-configuration CONFIGURATION

       This function restores the configuration of Emacs's windows and
     buffers to the state specified by CONFIGURATION.  CONFIGURATION
     must be a value that `current-window-configuration' returned
     previously.

* Special form: save-window-excursion FORMS...

       This function executes FORMS in sequence, preserving window sizes
     and contents.  It restores each window with the same start of
     display of its buffer.  It does not restore the value of point in
     the current buffer (use `save-excursion' for that).

       This function returns the value of the final form in FORMS.

          (split-window)
               => #<window 25 on control-structure.texinfo>
          (setq w (selected-window))
               => #<window 19 on control-structure.texinfo>
          (save-window-excursion
             (delete-other-windows w)
             (switch-to-buffer "foo")
             'do-something)
               => do-something
▶1f◀
File: lispref  Node: Positions, Prev: Windows, Up: Top, Next: Markers

Positions
*********

  A "position" is a number denoting the offset of a character from the
beginning of a buffer.  The position of the first character in a buffer
is `1'.  Positions are always between two characters (or before the
first character in the buffer, or after the last character of the
buffer).  The character referred to as *at* or *after* a position is
always the one immediately following the position.

  Markers are another way to represent positions; they relocate
automatically when text is inserted or deleted so they stay with the
surrounding characters.  *Note Markers::.

* Menu:

* Point::                       Special position
* Motion::                      Changing point
* Excursions::                  Temporary motion and buffer changes
* Clipping Restrictions::       Restricting point to a region

▶1f◀
File: lispref  Node: Point, Prev: Positions, Up: Positions, Next: Motion

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, so that you can
edit at different places in it.

  Like other positions, point is always between two characters (or
before the first character in the buffer, or after the last character of
the buffer).  Many terminals display the cursor over the character that
immediately follows point; on such terminals, point is between the
character on which the cursor sits and the preceding character.

  Each buffer has a value of point, which is independent of the value of
point in other buffers.  The value of point is always between `1' and
the buffer size plus one (*Note Buffer Contents::).  If there is a
clipping restriction in effect (*Note Clipping Restrictions::), then
point is always constrained to fall between the restriction boundaries.

  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 be in different places in each window that shows a given 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 position of point in the current
     buffer, as an integer.

          (point)
               => 175

* Function: bobp

       This function returns `t' if the point is at the beginning of the
     buffer.  If a clipping restriction is in effect, this means the
     beginning of the visible text.  Also, see `point-min' in *Note
     Buffer Contents::.

* Function: eobp

       This function returns `t' if point is at the end of the buffer.
     If a clipping restriction is in effect, this means the end of
     visible text.  Also, see `point-max' in *Note Buffer Contents::.

* Function: bolp

       This function returns `t' if the point is at the beginning of a
     line.

* Function: eolp

       This function returns `t' if the point is at the end of a line.
     The end of the buffer is always considered the end of a line.

  Many functions are provided to look at the characters around point.
Three simple functions are described here.  Also, *Note Searching and
Matching::.

* Function: char-after POSITION

       This function returns the character in the current buffer at
     position POSITION.  If POSITION does not specify a character in the
     buffer, then it returns `nil'.

       (Remember that point is always between characters or before the
     first character in a buffer; therefore, on many terminals, the
     character returned by `char-after' is the character the cursor is
     over.)

       In the example, the first character in the buffer is `@'.
          (char-to-string (char-after 1))
               => "@"

* Function: following-char

       This function returns the character following point in the
     current buffer.  This is similar to `(char-after (point))'.
     However, point is the last position of the buffer, then the result
     of `following-char' is `0'.

       In this example, the point is between the `a' and the `c'.

          Gentlemen may cry ``Pe-!-ace! Peace!,'' but there is no peace.

          (char-to-string (preceding-char))
               => "a"
          (char-to-string (following-char))
               => "c"

* Function: preceding-char

        This function returns the character preceding point in the
     current buffer.  See `following-char' for an example.  If point is
     the first position of the buffer, then the result of
     `preceding-char' is `0'.

▶1f◀
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦dc6f9d9c6⟧ TextFile

Derivation

TextFile
