/[emacs]/emacs/lispref/windows.texi
ViewVC logotype

Diff of /emacs/lispref/windows.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.56.2.1 by miles, Fri Apr 4 06:20:42 2003 UTC revision 1.56.2.2 by miles, Tue Oct 14 23:10:12 2003 UTC
# Line 97  the mark Line 97  the mark
97    
98  @item  @item
99  how recently the window was selected  how recently the window was selected
100    
101    @item
102    fringe settings
103    
104    @item
105    display margins
106    
107    @item
108    scroll-bar settings
109  @end itemize  @end itemize
110    
111  @cindex multiple windows  @cindex multiple windows
# Line 149  This function splits @var{window} into t Line 158  This function splits @var{window} into t
158  window @var{window} remains the selected window, but occupies only  window @var{window} remains the selected window, but occupies only
159  part of its former screen area.  The rest is occupied by a newly created  part of its former screen area.  The rest is occupied by a newly created
160  window which is returned as the value of this function.  window which is returned as the value of this function.
161    This function returns the newly created window.
162    
163  If @var{horizontal} is non-@code{nil}, then @var{window} splits into  If @var{horizontal} is non-@code{nil}, then @var{window} splits into
164  two side by side windows.  The original window @var{window} keeps the  two side by side windows.  The original window @var{window} keeps the
# Line 291  You could define a simplified version of Line 301  You could define a simplified version of
301  This function returns non-@code{nil} if there is only one window.  The  This function returns non-@code{nil} if there is only one window.  The
302  argument @var{no-mini}, if non-@code{nil}, means don't count the  argument @var{no-mini}, if non-@code{nil}, means don't count the
303  minibuffer even if it is active; otherwise, the minibuffer window is  minibuffer even if it is active; otherwise, the minibuffer window is
304  included, if active, in the total number of windows, which is compared  counted when it is active.
 against one.  
305    
306  The argument @var{all-frames} specifies which frames to consider.  Here  The argument @var{all-frames} specifies which frames to consider.  Here
307  are the possible values and their meanings:  are the possible values and their meanings:
# Line 401  This function returns the selected windo Line 410  This function returns the selected windo
410  which the cursor appears and to which many commands apply.  which the cursor appears and to which many commands apply.
411  @end defun  @end defun
412    
413  @defun select-window window  @defun select-window window &optional norecord
414  This function makes @var{window} the selected window.  The cursor then  This function makes @var{window} the selected window.  The cursor then
415  appears in @var{window} (on redisplay).  The buffer being displayed in  appears in @var{window} (on redisplay).  The buffer being displayed in
416  @var{window} is immediately designated the current buffer.  @var{window} is immediately designated the current buffer.
417    
418    Normally @var{window}'s selected buffer is moved to the front of the
419    buffer list, but if @var{norecord} is non-@code{nil}, the buffer list
420    order is unchanged.
421    
422  The return value is @var{window}.  The return value is @var{window}.
423    
424  @example  @example
# Line 418  The return value is @var{window}. Line 431  The return value is @var{window}.
431  @end defun  @end defun
432    
433  @defmac save-selected-window forms@dots{}  @defmac save-selected-window forms@dots{}
434  This macro records the selected window, executes @var{forms}  This macro records the selected window of each frame, executes
435  in sequence, then restores the earlier selected window (unless that  @var{forms} in sequence, then restores the earlier selected windows.
436  window is no longer alive).  
437    This macro does not save or restore anything about the sizes,
438  This macro does not save or restore anything about the sizes, arrangement  arrangement or contents of windows; therefore, if the @var{forms}
439  or contents of windows; therefore, if the @var{forms} change them,  change them, the change persists.  If the previously selected window
440  the change persists.  of some frame is no longer live at the time of exit from this form,
441    that frame's selected window is left alone.
442  Each frame, at any time, has a window selected within the frame.  This  @end defmac
443  macro saves only @emph{the} selected window; it does not save anything  
444  about other frames.  If the @var{forms} select some other frame and  @defmac with-selected-window window forms@dots{}
445  alter the window selected within it, the change persists.  This macro selects @var{window} (without changing the buffer list),
446    executes @var{forms} in sequence, then restores the previously
447    selected window (unless that window is no longer alive).  It is similar
448    to @code{save-selected-window} except that it explicitly selects
449    @var{window} and that it does not alter the buffer list sequence.
450  @end defmac  @end defmac
451    
452  @cindex finding windows  @cindex finding windows
# Line 478  consider.  See @code{get-lru-window}, ab Line 495  consider.  See @code{get-lru-window}, ab
495  @defun get-window-with-predicate predicate &optional minibuf all-frames default  @defun get-window-with-predicate predicate &optional minibuf all-frames default
496  This function returns a window satisfying @var{predicate}.  It cycles  This function returns a window satisfying @var{predicate}.  It cycles
497  through all visible windows using @code{walk-windows} (@pxref{Cyclic  through all visible windows using @code{walk-windows} (@pxref{Cyclic
498  Window Ordering}), calling @var{predicate} on each one one of them  Window Ordering}), calling @var{predicate} on each one of them
499  with that window as its argument.  The function returns the first  with that window as its argument.  The function returns the first
500  window for which @var{predicate} returns a non-@code{nil} value; if  window for which @var{predicate} returns a non-@code{nil} value; if
501  that never happens, it returns @var{default}.  that never happens, it returns @var{default}.
# Line 550  must ensure @var{window} is in a visible Line 567  must ensure @var{window} is in a visible
567  @item 0  @item 0
568  Consider all windows in all visible or iconified frames.  Consider all windows in all visible or iconified frames.
569    
570    @item a frame
571    Consider all windows on that frame.
572    
573  @item anything else  @item anything else
574  Consider precisely the windows in @var{window}'s frame, and no others.  Consider precisely the windows in @var{window}'s frame, and no others.
575  @end table  @end table
# Line 635  The functions described there are easier Line 655  The functions described there are easier
655  employ heuristics in choosing or creating a window; use these functions  employ heuristics in choosing or creating a window; use these functions
656  when you need complete control.  when you need complete control.
657    
658  @defun set-window-buffer window buffer-or-name  @defun set-window-buffer window buffer-or-name &optional keep-margins
659  This function makes @var{window} display @var{buffer-or-name} as its  This function makes @var{window} display @var{buffer-or-name} as its
660  contents.  It returns @code{nil}.  This is the fundamental primitive  contents.  It returns @code{nil}.  This is the fundamental primitive
661  for changing which buffer is displayed in a window, and all ways  for changing which buffer is displayed in a window, and all ways
# Line 647  of doing that call this function. Line 667  of doing that call this function.
667       @result{} nil       @result{} nil
668  @end group  @end group
669  @end example  @end example
670    
671    Normally, displaying @var{buffer} in @var{window} resets the window's
672    display margins, fringe widths, scroll bar settings, and position
673    based on the local variables of @var{buffer}.  However, if
674    @var{keep-margins} is non-@code{nil}, the display margins and fringe
675    widths of @var{window} remain unchanged.  @xref{Fringes}.
676  @end defun  @end defun
677    
678  @defun window-buffer &optional window  @defun window-buffer &optional window
# Line 792  This function makes @var{buffer-or-name} Line 818  This function makes @var{buffer-or-name}
818  switches to it in some window, preferably not the window previously  switches to it in some window, preferably not the window previously
819  selected.  The ``popped-to'' window becomes the selected window within  selected.  The ``popped-to'' window becomes the selected window within
820  its frame.  The return value is the buffer that was switched to.  its frame.  The return value is the buffer that was switched to.
821    If @var{buffer-or-name} is @code{nil}, that means to choose some
822    other buffer, but you don't specify which.
823    
824  If the variable @code{pop-up-frames} is non-@code{nil},  If the variable @code{pop-up-frames} is non-@code{nil},
825  @code{pop-to-buffer} looks for a window in any visible frame already  @code{pop-to-buffer} looks for a window in any visible frame already
# Line 935  splits a window or reuses one. Line 963  splits a window or reuses one.
963  @end defopt  @end defopt
964    
965  @c Emacs 19 feature  @c Emacs 19 feature
966  @defvar pop-up-frame-function  @defopt pop-up-frame-function
967  This variable specifies how to make a new frame if @code{pop-up-frames}  This variable specifies how to make a new frame if @code{pop-up-frames}
968  is non-@code{nil}.  is non-@code{nil}.
969    
# Line 944  Its value should be a function of no arg Line 972  Its value should be a function of no arg
972  function, which should return a frame.  The default value of the  function, which should return a frame.  The default value of the
973  variable is a function that creates a frame using parameters from  variable is a function that creates a frame using parameters from
974  @code{pop-up-frame-alist}.  @code{pop-up-frame-alist}.
975  @end defvar  @end defopt
976    
977  @defopt pop-up-frame-alist  @defopt pop-up-frame-alist
978  This variable holds an alist specifying frame parameters used when  This variable holds an alist specifying frame parameters used when
# Line 976  For example: Line 1004  For example:
1004  @noindent  @noindent
1005  specifies to display a buffer named @samp{myfile} in a dedicated frame  specifies to display a buffer named @samp{myfile} in a dedicated frame
1006  with specified @code{minibuffer} and @code{menu-bar-lines} parameters.  with specified @code{minibuffer} and @code{menu-bar-lines} parameters.
1007    
1008    The list of frame parameters can also use the phony frame parameters
1009    @code{same-frame} and @code{same-window}.  If the specified frame
1010    parameters include @code{(same-window . @var{value})} and @var{value}
1011    is non-@code{nil}, that means to display the buffer in the current
1012    selected window.  Otherwise, if they include @code{(same-frame .
1013    @var{value})} and @var{value} is non-@code{nil}, that means to display
1014    the buffer in a new window in the currently selected frame.
1015  @end defopt  @end defopt
1016    
1017  @defopt special-display-regexps  @defopt special-display-regexps
# Line 1059  A window can be marked as ``dedicated'' Line 1095  A window can be marked as ``dedicated''
1095  other buffer.  other buffer.
1096    
1097  @defun window-dedicated-p window  @defun window-dedicated-p window
1098  This function returns @code{t} if @var{window} is marked as dedicated;  This function returns non-@code{nil} if @var{window} is marked as
1099  otherwise @code{nil}.  dedicated; otherwise @code{nil}.
1100  @end defun  @end defun
1101    
1102  @defun set-window-dedicated-p window flag  @defun set-window-dedicated-p window flag
# Line 1314  If @var{count} is @code{nil} (or omitted Line 1350  If @var{count} is @code{nil} (or omitted
1350  is @code{next-screen-context-lines} lines less than the usable height of  is @code{next-screen-context-lines} lines less than the usable height of
1351  the window (not counting its mode line).  the window (not counting its mode line).
1352    
1353  @code{scroll-up} returns @code{nil}.  @code{scroll-up} returns @code{nil}, unless it gets an error
1354    because it can't scroll any further.
1355  @end deffn  @end deffn
1356    
1357  @deffn Command scroll-down &optional count  @deffn Command scroll-down &optional count
# Line 1326  If @var{count} is omitted or @code{nil}, Line 1363  If @var{count} is omitted or @code{nil},
1363  is @code{next-screen-context-lines} lines less than the usable height of  is @code{next-screen-context-lines} lines less than the usable height of
1364  the window (not counting its mode line).  the window (not counting its mode line).
1365    
1366  @code{scroll-down} returns @code{nil}.  @code{scroll-down} returns @code{nil}, unless it gets an error because
1367    it can't scroll any further.
1368  @end deffn  @end deffn
1369    
1370  @deffn Command scroll-other-window &optional count  @deffn Command scroll-other-window &optional count
# Line 1560  left you can scroll, but eventually all Line 1598  left you can scroll, but eventually all
1598  left edge.  left edge.
1599    
1600  @vindex auto-hscroll-mode  @vindex auto-hscroll-mode
1601    In Emacs 21, redisplay automatically alters the horizontal scrolling    If @code{auto-hscroll-mode} is set, redisplay automatically alters
1602  of a window as necessary to ensure that point is always visible, if  the horizontal scrolling of a window as necessary to ensure that point
1603  @code{auto-hscroll-mode} is set.  However, you can still set the  is always visible.  However, you can still set the horizontal
1604  horizontal scrolling value explicitly.  The value you specify serves as  scrolling value explicitly.  The value you specify serves as a lower
1605  a lower bound for automatic scrolling, i.e. automatic scrolling  bound for automatic scrolling, i.e. automatic scrolling will not
1606  will not scroll a window to a column less than the specified one.  scroll a window to a column less than the specified one.
1607    
1608  @deffn Command scroll-left &optional count  @deffn Command scroll-left &optional count
1609  This function scrolls the selected window @var{count} columns to the  This function scrolls the selected window @var{count} columns to the
# Line 1618  If @var{window} is @code{nil}, the selec Line 1656  If @var{window} is @code{nil}, the selec
1656  @end defun  @end defun
1657    
1658  @defun set-window-hscroll window columns  @defun set-window-hscroll window columns
1659  This function sets the number of columns from the left margin that  This function sets horizontal scrolling of @var{window}.  The value of
1660  @var{window} is scrolled from the value of @var{columns}.  The argument  @var{columns} specifies the amount of scrolling, in terms of columns
1661  @var{columns} should be zero or positive; if not, it is taken as zero.  from the left margin.  The argument @var{columns} should be zero or
1662  Fractional values of @var{columns} are not supported at present.  positive; if not, it is taken as zero.  Fractional values of
1663    @var{columns} are not supported at present.
1664    
1665  Note that @code{set-window-hscroll} may appear not to work if you test  Note that @code{set-window-hscroll} may appear not to work if you test
1666  it by evaluating a call with @kbd{M-:} in a simple way.  What happens  it by evaluating a call with @kbd{M-:} in a simple way.  What happens
# Line 1672  characters that separates side-by-side w Line 1711  characters that separates side-by-side w
1711  @defun window-height &optional window  @defun window-height &optional window
1712  This function returns the number of lines in @var{window}, including  This function returns the number of lines in @var{window}, including
1713  its mode line and header line, if any.  If @var{window} fills its  its mode line and header line, if any.  If @var{window} fills its
1714  entire frame except for the echo area, and there is no tool bar, this  entire frame except for the echo area, this is typically one less than
1715  is typically one less than the value of @code{frame-height} on that  the value of @code{frame-height} on that frame.
 frame.  
1716    
1717  If @var{window} is @code{nil}, the function uses the selected window.  If @var{window} is @code{nil}, the function uses the selected window.
1718    
# Line 1733  its right edge value includes the width Line 1771  its right edge value includes the width
1771  the window and that neighbor.  Since the width of the window does not  the window and that neighbor.  Since the width of the window does not
1772  include this separator, the width does not usually equal the difference  include this separator, the width does not usually equal the difference
1773  between the right and left edges.  between the right and left edges.
1774    @end defun
1775    
1776  Here is the result obtained on a typical 24-line terminal with just one  @defun window-inside-edges window
1777  window:  This is similar to @code{window-edges}, but the edge values
1778    it returns include only the text area of the window.  They
1779    do not include the header line, mode line, scroll bar or
1780    vertical separator, fringes, or display margins.
1781    @end defun
1782    
1783    Here are the results obtained on a typical 24-line terminal with just
1784    one window, with menu bar enabled:
1785    
1786  @example  @example
1787  @group  @group
1788  (window-edges (selected-window))  (window-edges (selected-window))
1789       @result{} (0 0 80 23)       @result{} (0 1 80 23)
1790    @end group
1791    @group
1792    (window-inside-edges (selected-window))
1793         @result{} (0 1 80 22)
1794  @end group  @end group
1795  @end example  @end example
1796    
1797  @noindent  @noindent
1798  The bottom edge is at line 23 because the last line is the echo area.  The bottom edge is at line 23 because the last line is the echo area.
1799    The bottom inside edge is at line 22, which is the window's mode line.
1800    
1801  If @var{window} is at the upper left corner of its frame, then  If @var{window} is at the upper left corner of its frame, and there is
1802  @var{bottom} is the same as the value of @code{(window-height)},  no menu bar, then @var{bottom} returned by @code{window-edges} is the
1803  @var{right} is almost the same as the value of @code{(window-width)},  same as the value of @code{(window-height)}, @var{right} is almost the
1804  and @var{top} and @var{left} are zero.  For example, the edges of the  same as the value of @code{(window-width)}, and @var{top} and
1805  following window are @w{@samp{0 0 8 5}}.  Assuming that the frame has  @var{left} are zero.  For example, the edges of the following window
1806  more than 8 columns, the last column of the window (column 7) holds a  are @w{@samp{0 0 8 5}}.  Assuming that the frame has more than 8
1807  border rather than text.  The last row (row 4) holds the mode line,  columns, the last column of the window (column 7) holds a border
1808  shown here with @samp{xxxxxxxxx}.  rather than text.  The last row (row 4) holds the mode line, shown
1809    here with @samp{xxxxxxxxx}.
1810    
1811  @example  @example
1812  @group  @group
# Line 1772  shown here with @samp{xxxxxxxxx}. Line 1824  shown here with @samp{xxxxxxxxx}.
1824    
1825  In the following example, let's suppose that the frame is 7  In the following example, let's suppose that the frame is 7
1826  columns wide.  Then the edges of the left window are @w{@samp{0 0 4 3}}  columns wide.  Then the edges of the left window are @w{@samp{0 0 4 3}}
1827  and the edges of the right window are @w{@samp{4 0 8 3}}.  and the edges of the right window are @w{@samp{4 0 7 3}}.
1828    The inside edges of the left window are @w{@samp{0 0 3 2}},
1829    and the inside edges of the right window are @w{@samp{4 0 7 2}},
1830    
1831  @example  @example
1832  @group  @group
# Line 1784  and the edges of the right window are @w Line 1838  and the edges of the right window are @w
1838             0  34  7             0  34  7
1839  @end group  @end group
1840  @end example  @end example
1841    
1842    @defun window-pixel-edges window
1843    This function is like @code{window-edges} except that, on a graphical
1844    display, the edge values are measured in pixels instead of in
1845    character lines and columns.
1846    @end defun
1847    
1848    @defun window-inside-pixel-edges window
1849    This function is like @code{window-inside-edges} except that, on a
1850    graphical display, the edge values are measured in pixels instead of
1851    in character lines and columns.
1852  @end defun  @end defun
1853    
1854  @node Resizing Windows  @node Resizing Windows
# Line 1972  neighbor to the right.  This value occur Line 2037  neighbor to the right.  This value occur
2037  have a scroll bar; positions in a scroll bar are considered outside the  have a scroll bar; positions in a scroll bar are considered outside the
2038  window for these purposes.  window for these purposes.
2039    
2040    @item left-fringe
2041    @itemx right-fringe
2042    The coordinates are in the left or right fringe of the window.
2043    
2044    @item left-margin
2045    @itemx right-margin
2046    The coordinates are in the left or right margin of the window.
2047    
2048  @item nil  @item nil
2049  The coordinates are not in any part of @var{window}.  The coordinates are not in any part of @var{window}.
2050  @end table  @end table
# Line 1988  argument because it always uses the fram Line 2061  argument because it always uses the fram
2061    A @dfn{window configuration} records the entire layout of one    A @dfn{window configuration} records the entire layout of one
2062  frame---all windows, their sizes, which buffers they contain, what  frame---all windows, their sizes, which buffers they contain, what
2063  part of each buffer is displayed, and the values of point and the  part of each buffer is displayed, and the values of point and the
2064  mark.  It also includes the values of @code{window-min-height},  mark; also their fringes, margins, and scroll bar settings.  It also
2065    includes the values of @code{window-min-height},
2066  @code{window-min-width} and @code{minibuffer-scroll-window}.  An  @code{window-min-width} and @code{minibuffer-scroll-window}.  An
2067  exception is made for point in the selected window for the current  exception is made for point in the selected window for the current
2068  buffer; its value is not saved in the window configuration.  buffer; its value is not saved in the window configuration.
# Line 2044  that is visible.  It also includes the c Line 2118  that is visible.  It also includes the c
2118  However, it does not include the value of point in the current buffer;  However, it does not include the value of point in the current buffer;
2119  use @code{save-excursion} also, if you wish to preserve that.  use @code{save-excursion} also, if you wish to preserve that.
2120    
2121  Don't use this construct when @code{save-selected-window} is all you need.  Don't use this construct when @code{save-selected-window} is sufficient.
2122    
2123  Exit from @code{save-window-excursion} always triggers execution of the  Exit from @code{save-window-excursion} always triggers execution of the
2124  @code{window-size-change-functions}.  (It doesn't know how to tell  @code{window-size-change-functions}.  (It doesn't know how to tell
# Line 2103  There are three actions that can change Line 2177  There are three actions that can change
2177  switching buffers in the window, and changing the size of the window.  switching buffers in the window, and changing the size of the window.
2178  The first two actions run @code{window-scroll-functions}; the last runs  The first two actions run @code{window-scroll-functions}; the last runs
2179  @code{window-size-change-functions}.  The paradigmatic use of these  @code{window-size-change-functions}.  The paradigmatic use of these
2180  hooks is in the implementation of Lazy Lock mode; see @ref{Support  hooks is in the implementation of Lazy Lock mode; see @file{lazy-lock.el}.
 Modes, Lazy Lock, Font Lock Support Modes, emacs, The GNU Emacs Manual}.  
2181    
2182  @defvar window-scroll-functions  @defvar window-scroll-functions
2183  This variable holds a list of functions that Emacs should call before  This variable holds a list of functions that Emacs should call before
# Line 2168  changing the sizes of windows, or displa Line 2241  changing the sizes of windows, or displa
2241  window.  The frame whose window configuration has changed is the  window.  The frame whose window configuration has changed is the
2242  selected frame when this hook runs.  selected frame when this hook runs.
2243  @end defvar  @end defvar
2244    
2245    @ignore
2246       arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3
2247    @end ignore

Legend:
Removed from v.1.56.2.1  
changed lines
  Added in v.1.56.2.2

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26