[Emacs-diffs] Changes to emacs/lispref/windows.texi [lexbind]

[Miles Bader]

Index: emacs/lispref/windows.texi
diff -c emacs/lispref/windows.texi:1.56.2.1 emacs/lispref/windows.texi:1.56.2.2
*** emacs/lispref/windows.texi:1.56.2.1 Fri Apr  4 01:20:42 2003
--- emacs/lispref/windows.texi  Tue Oct 14 19:10:12 2003
***************
*** 97,102 ****
--- 97,111 ----
  
  @item
  how recently the window was selected
+ 
+ @item
+ fringe settings
+ 
+ @item
+ display margins
+ 
+ @item
+ scroll-bar settings
  @end itemize
  
  @cindex multiple windows
***************
*** 149,154 ****
--- 158,164 ----
  window @var{window} remains the selected window, but occupies only
  part of its former screen area.  The rest is occupied by a newly created
  window which is returned as the value of this function.
+ This function returns the newly created window.
  
  If @var{horizontal} is address@hidden, then @var{window} splits into
  two side by side windows.  The original window @var{window} keeps the
***************
*** 291,298 ****
  This function returns address@hidden if there is only one window.  The
  argument @var{no-mini}, if address@hidden, means don't count the
  minibuffer even if it is active; otherwise, the minibuffer window is
! included, if active, in the total number of windows, which is compared
! against one.
  
  The argument @var{all-frames} specifies which frames to consider.  Here
  are the possible values and their meanings:
--- 301,307 ----
  This function returns address@hidden if there is only one window.  The
  argument @var{no-mini}, if address@hidden, means don't count the
  minibuffer even if it is active; otherwise, the minibuffer window is
! counted when it is active.
  
  The argument @var{all-frames} specifies which frames to consider.  Here
  are the possible values and their meanings:
***************
*** 401,411 ****
  which the cursor appears and to which many commands apply.
  @end defun
  
! @defun select-window window
  This function makes @var{window} the selected window.  The cursor then
  appears in @var{window} (on redisplay).  The buffer being displayed in
  @var{window} is immediately designated the current buffer.
  
  The return value is @var{window}.
  
  @example
--- 410,424 ----
  which the cursor appears and to which many commands apply.
  @end defun
  
! @defun select-window window &optional norecord
  This function makes @var{window} the selected window.  The cursor then
  appears in @var{window} (on redisplay).  The buffer being displayed in
  @var{window} is immediately designated the current buffer.
  
+ Normally @var{window}'s selected buffer is moved to the front of the
+ buffer list, but if @var{norecord} is address@hidden, the buffer list
+ order is unchanged.
+ 
  The return value is @var{window}.
  
  @example
***************
*** 418,435 ****
  @end defun
  
  @defmac save-selected-window address@hidden
! This macro records the selected window, executes @var{forms}
! in sequence, then restores the earlier selected window (unless that
! window is no longer alive).
! 
! This macro does not save or restore anything about the sizes, arrangement
! or contents of windows; therefore, if the @var{forms} change them,
! the change persists.
! 
! Each frame, at any time, has a window selected within the frame.  This
! macro saves only @emph{the} selected window; it does not save anything
! about other frames.  If the @var{forms} select some other frame and
! alter the window selected within it, the change persists.
  @end defmac
  
  @cindex finding windows
--- 431,452 ----
  @end defun
  
  @defmac save-selected-window address@hidden
! This macro records the selected window of each frame, executes
! @var{forms} in sequence, then restores the earlier selected windows.
! 
! This macro does not save or restore anything about the sizes,
! arrangement or contents of windows; therefore, if the @var{forms}
! change them, the change persists.  If the previously selected window
! of some frame is no longer live at the time of exit from this form,
! that frame's selected window is left alone.
! @end defmac
! 
! @defmac with-selected-window window address@hidden
! This macro selects @var{window} (without changing the buffer list),
! executes @var{forms} in sequence, then restores the previously
! selected window (unless that window is no longer alive).  It is similar
! to @code{save-selected-window} except that it explicitly selects
! @var{window} and that it does not alter the buffer list sequence.
  @end defmac
  
  @cindex finding windows
***************
*** 478,484 ****
  @defun get-window-with-predicate predicate &optional minibuf all-frames 
default
  This function returns a window satisfying @var{predicate}.  It cycles
  through all visible windows using @code{walk-windows} (@pxref{Cyclic
! Window Ordering}), calling @var{predicate} on each one one of them
  with that window as its argument.  The function returns the first
  window for which @var{predicate} returns a address@hidden value; if
  that never happens, it returns @var{default}.
--- 495,501 ----
  @defun get-window-with-predicate predicate &optional minibuf all-frames 
default
  This function returns a window satisfying @var{predicate}.  It cycles
  through all visible windows using @code{walk-windows} (@pxref{Cyclic
! Window Ordering}), calling @var{predicate} on each one of them
  with that window as its argument.  The function returns the first
  window for which @var{predicate} returns a address@hidden value; if
  that never happens, it returns @var{default}.
***************
*** 550,555 ****
--- 567,575 ----
  @item 0
  Consider all windows in all visible or iconified frames.
  
+ @item a frame
+ Consider all windows on that frame.
+ 
  @item anything else
  Consider precisely the windows in @var{window}'s frame, and no others.
  @end table
***************
*** 635,641 ****
  employ heuristics in choosing or creating a window; use these functions
  when you need complete control.
  
! @defun set-window-buffer window buffer-or-name
  This function makes @var{window} display @var{buffer-or-name} as its
  contents.  It returns @code{nil}.  This is the fundamental primitive
  for changing which buffer is displayed in a window, and all ways
--- 655,661 ----
  employ heuristics in choosing or creating a window; use these functions
  when you need complete control.
  
! @defun set-window-buffer window buffer-or-name &optional keep-margins
  This function makes @var{window} display @var{buffer-or-name} as its
  contents.  It returns @code{nil}.  This is the fundamental primitive
  for changing which buffer is displayed in a window, and all ways
***************
*** 647,652 ****
--- 667,678 ----
       @result{} nil
  @end group
  @end example
+ 
+ Normally, displaying @var{buffer} in @var{window} resets the window's
+ display margins, fringe widths, scroll bar settings, and position
+ based on the local variables of @var{buffer}.  However, if
+ @var{keep-margins} is address@hidden, the display margins and fringe
+ widths of @var{window} remain unchanged.  @xref{Fringes}.
  @end defun
  
  @defun window-buffer &optional window
***************
*** 792,797 ****
--- 818,825 ----
  switches to it in some window, preferably not the window previously
  selected.  The ``popped-to'' window becomes the selected window within
  its frame.  The return value is the buffer that was switched to.
+ If @var{buffer-or-name} is @code{nil}, that means to choose some
+ other buffer, but you don't specify which.
  
  If the variable @code{pop-up-frames} is address@hidden,
  @code{pop-to-buffer} looks for a window in any visible frame already
***************
*** 935,941 ****
  @end defopt
  
  @c Emacs 19 feature
! @defvar pop-up-frame-function
  This variable specifies how to make a new frame if @code{pop-up-frames}
  is address@hidden
  
--- 963,969 ----
  @end defopt
  
  @c Emacs 19 feature
! @defopt pop-up-frame-function
  This variable specifies how to make a new frame if @code{pop-up-frames}
  is address@hidden
  
***************
*** 944,950 ****
  function, which should return a frame.  The default value of the
  variable is a function that creates a frame using parameters from
  @code{pop-up-frame-alist}.
! @end defvar
  
  @defopt pop-up-frame-alist
  This variable holds an alist specifying frame parameters used when
--- 972,978 ----
  function, which should return a frame.  The default value of the
  variable is a function that creates a frame using parameters from
  @code{pop-up-frame-alist}.
! @end defopt
  
  @defopt pop-up-frame-alist
  This variable holds an alist specifying frame parameters used when
***************
*** 976,981 ****
--- 1004,1017 ----
  @noindent
  specifies to display a buffer named @samp{myfile} in a dedicated frame
  with specified @code{minibuffer} and @code{menu-bar-lines} parameters.
+ 
+ The list of frame parameters can also use the phony frame parameters
+ @code{same-frame} and @code{same-window}.  If the specified frame
+ parameters include @code{(same-window . @var{value})} and @var{value}
+ is address@hidden, that means to display the buffer in the current
+ selected window.  Otherwise, if they include @code{(same-frame .
+ @var{value})} and @var{value} is address@hidden, that means to display
+ the buffer in a new window in the currently selected frame.
  @end defopt
  
  @defopt special-display-regexps
***************
*** 1059,1066 ****
  other buffer.
  
  @defun window-dedicated-p window
! This function returns @code{t} if @var{window} is marked as dedicated;
! otherwise @code{nil}.
  @end defun
  
  @defun set-window-dedicated-p window flag
--- 1095,1102 ----
  other buffer.
  
  @defun window-dedicated-p window
! This function returns address@hidden if @var{window} is marked as
! dedicated; otherwise @code{nil}.
  @end defun
  
  @defun set-window-dedicated-p window flag
***************
*** 1314,1320 ****
  is @code{next-screen-context-lines} lines less than the usable height of
  the window (not counting its mode line).
  
! @code{scroll-up} returns @code{nil}.
  @end deffn
  
  @deffn Command scroll-down &optional count
--- 1350,1357 ----
  is @code{next-screen-context-lines} lines less than the usable height of
  the window (not counting its mode line).
  
! @code{scroll-up} returns @code{nil}, unless it gets an error
! because it can't scroll any further.
  @end deffn
  
  @deffn Command scroll-down &optional count
***************
*** 1326,1332 ****
  is @code{next-screen-context-lines} lines less than the usable height of
  the window (not counting its mode line).
  
! @code{scroll-down} returns @code{nil}.
  @end deffn
  
  @deffn Command scroll-other-window &optional count
--- 1363,1370 ----
  is @code{next-screen-context-lines} lines less than the usable height of
  the window (not counting its mode line).
  
! @code{scroll-down} returns @code{nil}, unless it gets an error because
! it can't scroll any further.
  @end deffn
  
  @deffn Command scroll-other-window &optional count
***************
*** 1560,1571 ****
  left edge.
  
  @vindex auto-hscroll-mode
!   In Emacs 21, redisplay automatically alters the horizontal scrolling
! of a window as necessary to ensure that point is always visible, if
! @code{auto-hscroll-mode} is set.  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.
  
  @deffn Command scroll-left &optional count
  This function scrolls the selected window @var{count} columns to the
--- 1598,1609 ----
  left edge.
  
  @vindex auto-hscroll-mode
!   If @code{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.
  
  @deffn Command scroll-left &optional count
  This function scrolls the selected window @var{count} columns to the
***************
*** 1618,1627 ****
  @end defun
  
  @defun set-window-hscroll window columns
! This function sets the number of columns from the left margin that
! @var{window} is scrolled from the value of @var{columns}.  The argument
! @var{columns} should be zero or positive; if not, it is taken as zero.
! Fractional values of @var{columns} are not supported at present.
  
  Note that @code{set-window-hscroll} may appear not to work if you test
  it by evaluating a call with @kbd{M-:} in a simple way.  What happens
--- 1656,1666 ----
  @end defun
  
  @defun set-window-hscroll window columns
! This function sets horizontal scrolling of @var{window}.  The value of
! @var{columns} specifies the amount of scrolling, in terms of columns
! from the left margin.  The argument @var{columns} should be zero or
! positive; if not, it is taken as zero.  Fractional values of
! @var{columns} are not supported at present.
  
  Note that @code{set-window-hscroll} may appear not to work if you test
  it by evaluating a call with @kbd{M-:} in a simple way.  What happens
***************
*** 1672,1680 ****
  @defun window-height &optional window
  This function returns the number of lines in @var{window}, including
  its mode line and header line, if any.  If @var{window} fills its
! entire frame except for the echo area, and there is no tool bar, this
! is typically one less than the value of @code{frame-height} on that
! frame.
  
  If @var{window} is @code{nil}, the function uses the selected window.
  
--- 1711,1718 ----
  @defun window-height &optional window
  This function returns the number of lines in @var{window}, including
  its mode line and header line, if any.  If @var{window} fills its
! entire frame except for the echo area, this is typically one less than
! the value of @code{frame-height} on that frame.
  
  If @var{window} is @code{nil}, the function uses the selected window.
  
***************
*** 1733,1760 ****
  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.
  
! Here is the result obtained on a typical 24-line terminal with just one
! window:
  
  @example
  @group
  (window-edges (selected-window))
!      @result{} (0 0 80 23)
  @end group
  @end example
  
  @noindent
  The bottom edge is at line 23 because the last line is the echo area.
  
! If @var{window} is at the upper left corner of its frame, then
! @var{bottom} is the same as the value of @code{(window-height)},
! @var{right} is almost the same as the value of @code{(window-width)},
! and @var{top} and @var{left} are zero.  For example, the edges of the
! following window are @address@hidden 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 @samp{xxxxxxxxx}.
  
  @example
  @group
--- 1771,1812 ----
  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.
+ @end defun
  
! @defun window-inside-edges window
! This is similar to @code{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.
! @end defun
! 
! Here are the results obtained on a typical 24-line terminal with just
! one window, with menu bar enabled:
  
  @example
  @group
  (window-edges (selected-window))
!      @result{} (0 1 80 23)
! @end group
! @group
! (window-inside-edges (selected-window))
!      @result{} (0 1 80 22)
  @end group
  @end example
  
  @noindent
  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 @var{window} is at the upper left corner of its frame, and there is
! no menu bar, then @var{bottom} returned by @code{window-edges} is the
! same as the value of @code{(window-height)}, @var{right} is almost the
! same as the value of @code{(window-width)}, and @var{top} and
! @var{left} are zero.  For example, the edges of the following window
! are @address@hidden 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 @samp{xxxxxxxxx}.
  
  @example
  @group
***************
*** 1772,1778 ****
  
  In the following example, let's suppose that the frame is 7
  columns wide.  Then the edges of the left window are @address@hidden 0 4 3}}
! and the edges of the right window are @address@hidden 0 8 3}}.
  
  @example
  @group
--- 1824,1832 ----
  
  In the following example, let's suppose that the frame is 7
  columns wide.  Then the edges of the left window are @address@hidden 0 4 3}}
! and the edges of the right window are @address@hidden 0 7 3}}.
! The inside edges of the left window are @address@hidden 0 3 2}},
! and the inside edges of the right window are @address@hidden 0 7 2}},
  
  @example
  @group
***************
*** 1784,1789 ****
--- 1838,1854 ----
             0  34  7
  @end group
  @end example
+ 
+ @defun window-pixel-edges window
+ This function is like @code{window-edges} except that, on a graphical
+ display, the edge values are measured in pixels instead of in
+ character lines and columns.
+ @end defun
+ 
+ @defun window-inside-pixel-edges window
+ This function is like @code{window-inside-edges} except that, on a
+ graphical display, the edge values are measured in pixels instead of
+ in character lines and columns.
  @end defun
  
  @node Resizing Windows
***************
*** 1972,1977 ****
--- 2037,2050 ----
  have a scroll bar; positions in a scroll bar are considered outside the
  window for these purposes.
  
+ @item left-fringe
+ @itemx right-fringe
+ The coordinates are in the left or right fringe of the window.
+ 
+ @item left-margin
+ @itemx right-margin
+ The coordinates are in the left or right margin of the window.
+ 
  @item nil
  The coordinates are not in any part of @var{window}.
  @end table
***************
*** 1988,1994 ****
    A @dfn{window configuration} records the entire layout of one
  frame---all windows, their sizes, which buffers they contain, what
  part of each buffer is displayed, and the values of point and the
! mark.  It also includes the values of @code{window-min-height},
  @code{window-min-width} and @code{minibuffer-scroll-window}.  An
  exception is made for point in the selected window for the current
  buffer; its value is not saved in the window configuration.
--- 2061,2068 ----
    A @dfn{window configuration} records the entire layout of one
  frame---all windows, their sizes, which buffers they contain, what
  part of each buffer is displayed, and the values of point and the
! mark; also their fringes, margins, and scroll bar settings.  It also
! includes the values of @code{window-min-height},
  @code{window-min-width} and @code{minibuffer-scroll-window}.  An
  exception is made for point in the selected window for the current
  buffer; its value is not saved in the window configuration.
***************
*** 2044,2050 ****
  However, it does not include the value of point in the current buffer;
  use @code{save-excursion} also, if you wish to preserve that.
  
! Don't use this construct when @code{save-selected-window} is all you need.
  
  Exit from @code{save-window-excursion} always triggers execution of the
  @code{window-size-change-functions}.  (It doesn't know how to tell
--- 2118,2124 ----
  However, it does not include the value of point in the current buffer;
  use @code{save-excursion} also, if you wish to preserve that.
  
! Don't use this construct when @code{save-selected-window} is sufficient.
  
  Exit from @code{save-window-excursion} always triggers execution of the
  @code{window-size-change-functions}.  (It doesn't know how to tell
***************
*** 2103,2110 ****
  switching buffers in the window, and changing the size of the window.
  The first two actions run @code{window-scroll-functions}; the last runs
  @code{window-size-change-functions}.  The paradigmatic use of these
! hooks is in the implementation of Lazy Lock mode; see @ref{Support
! Modes, Lazy Lock, Font Lock Support Modes, emacs, The GNU Emacs Manual}.
  
  @defvar window-scroll-functions
  This variable holds a list of functions that Emacs should call before
--- 2177,2183 ----
  switching buffers in the window, and changing the size of the window.
  The first two actions run @code{window-scroll-functions}; the last runs
  @code{window-size-change-functions}.  The paradigmatic use of these
! hooks is in the implementation of Lazy Lock mode; see @file{lazy-lock.el}.
  
  @defvar window-scroll-functions
  This variable holds a list of functions that Emacs should call before
***************
*** 2168,2170 ****
--- 2241,2247 ----
  window.  The frame whose window configuration has changed is the
  selected frame when this hook runs.
  @end defvar
+ 
+ @ignore
+    arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3
+ @end ignore