[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110804: Fix and rewrite doc on wi
|
From: |
martin rudalics |
|
Subject: |
[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110804: Fix and rewrite doc on window recombining facilities. |
|
Date: |
Wed, 07 Nov 2012 10:41:52 +0100 |
|
User-agent: |
Bazaar (2.5.0) |
------------------------------------------------------------
revno: 110804
committer: martin rudalics <address@hidden>
branch nick: emacs-24
timestamp: Wed 2012-11-07 10:41:52 +0100
message:
Fix and rewrite doc on window recombining facilities.
* window.c (Fsplit_window_internal): Set combination limit of
new parent window to t iff Vwindow_combination_limit is t;
fixing a regression introduced with the change from 2012-09-22.
(Fwindow_combination_limit, Fset_window_combination_limit): Fix
doc-strings.
* elisp.texi (Top): Add Recombining Windows to menu.
* windows.texi (Recombining Windows): New subsection.
(Splitting Windows): Rewrite text on handling of window
combinations and move it to new subsection.
modified:
doc/lispref/ChangeLog
doc/lispref/elisp.texi
doc/lispref/windows.texi
etc/NEWS
src/ChangeLog
src/window.c
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog 2012-11-07 05:22:10 +0000
+++ b/doc/lispref/ChangeLog 2012-11-07 09:41:52 +0000
@@ -1,3 +1,10 @@
+2012-11-07 Martin Rudalics <address@hidden>
+
+ * elisp.texi (Top): Add Recombining Windows to menu.
+ * windows.texi (Recombining Windows): New subsection.
+ (Splitting Windows): Rewrite text on handling of window
+ combinations and move it to new subsection.
+
2012-11-07 Chong Yidong <address@hidden>
* variables.texi (Creating Buffer-Local): Document setq-local and
=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi 2012-11-06 01:42:17 +0000
+++ b/doc/lispref/elisp.texi 2012-11-07 09:41:52 +0000
@@ -1001,6 +1001,8 @@
* Resizing Windows:: Changing the sizes of windows.
* Splitting Windows:: Splitting one window into two windows.
* Deleting Windows:: Deleting a window gives its space to other windows.
+* Recombining Windows:: Preserving the frame layout when splitting and
+ deleting windows.
* Selecting Windows:: The selected window is the one that you edit in.
* Cyclic Window Ordering:: Moving around the existing windows.
* Buffers and Windows:: Each window displays the contents of a buffer.
=== modified file 'doc/lispref/windows.texi'
--- a/doc/lispref/windows.texi 2012-11-03 10:47:03 +0000
+++ b/doc/lispref/windows.texi 2012-11-07 09:41:52 +0000
@@ -16,8 +16,10 @@
* Windows and Frames:: Relating windows to the frame they appear on.
* Window Sizes:: Accessing a window's size.
* Resizing Windows:: Changing the sizes of windows.
-* Splitting Windows:: Splitting one window into two windows.
-* Deleting Windows:: Deleting a window gives its space to other windows.
+* Splitting Windows:: Creating a new window.
+* Deleting Windows:: Removing a window from its frame.
+* Recombining Windows:: Preserving the frame layout when splitting and
+ deleting windows.
* Selecting Windows:: The selected window is the one that you edit in.
* Cyclic Window Ordering:: Moving around the existing windows.
* Buffers and Windows:: Each window displays the contents of a buffer.
@@ -587,7 +589,7 @@
The choice of which window edges this function alters depends on the
values of the option @code{window-combination-resize} and the
combination limits of the involved windows; in some cases, it may alter
-both edges. @xref{Splitting Windows}. To resize by moving only the
+both edges. @xref{Recombining Windows}. To resize by moving only the
bottom or right edge of a window, use the function
@code{adjust-window-trailing-edge}, below.
@end defun
@@ -795,222 +797,7 @@
window @var{W3}. A new internal window @var{W1} is created, becoming
the new root window.
address@hidden window-combination-resize
-If this variable is @code{nil}, @code{split-window} can only split a
-window (denoted by @var{window}) if @var{window}'s screen area is large
-enough to accommodate both itself and the new window.
-
-If this variable is @code{t}, @code{split-window} tries to resize all
-windows that are part of the same combination as @var{window}, in order
-to accommodate the new window. In particular, this may allow
address@hidden to succeed even if @var{window} is a fixed-size
-window or too small to ordinarily split. Furthermore, subsequently
-resizing or deleting @var{window} may resize all other windows in its
-combination.
-
-The default is @code{nil}. Other values are reserved for future use.
-The value of this variable is ignored when
address@hidden is address@hidden (see below).
address@hidden defopt
-
- To illustrate the effect of @code{window-combination-resize},
-consider the following window configuration:
-
address@hidden
address@hidden
- ______________________________________
- | ____________________________________ |
- || ||
- || ||
- || ||
- || ||
- ||_________________W2_________________||
- | ____________________________________ |
- || ||
- || ||
- || ||
- || ||
- ||_________________W3_________________||
- |__________________W1__________________|
-
address@hidden group
address@hidden smallexample
-
address@hidden
-If @code{window-combination-resize} is @code{nil}, splitting window
address@hidden leaves the size of @code{W2} unchanged:
-
address@hidden
address@hidden
- ______________________________________
- | ____________________________________ |
- || ||
- || ||
- || ||
- || ||
- ||_________________W2_________________||
- | ____________________________________ |
- || ||
- ||_________________W3_________________||
- | ____________________________________ |
- || ||
- ||_________________W4_________________||
- |__________________W1__________________|
-
address@hidden group
address@hidden smallexample
-
address@hidden
-If @code{window-combination-resize} is @code{t}, splitting @code{W3}
-instead leaves all three live windows with approximately the same
-height:
-
address@hidden
address@hidden
- ______________________________________
- | ____________________________________ |
- || ||
- || ||
- ||_________________W2_________________||
- | ____________________________________ |
- || ||
- || ||
- ||_________________W3_________________||
- | ____________________________________ |
- || ||
- || ||
- ||_________________W4_________________||
- |__________________W1__________________|
-
address@hidden group
address@hidden smallexample
-
address@hidden window-combination-limit
-If the value of this variable is @code{t}, the @code{split-window}
-function always creates a new internal window. If the value is
address@hidden, the new live window is allowed to share the existing
-parent window, if one exists, provided the split occurs in the same
-direction as the existing window combination (otherwise, a new
-internal window is created anyway). The default is @code{nil}. Other
-values are reserved for future use.
-
-Thus, if the value of this variable is at all times @code{t}, then at
-all times every window tree is a binary tree (a tree where each window
-except the root window has exactly one sibling).
-
-Furthermore, @code{split-window} calls
address@hidden on the newly-created internal
-window, recording the current value of this variable. This affects
-how the window tree is rearranged when the child windows are deleted
-(see below).
address@hidden defopt
-
address@hidden window combination limit
address@hidden set-window-combination-limit window limit
-This functions sets the @dfn{combination limit} of the window
address@hidden to @var{limit}. This value can be retrieved via the
-function @code{window-combination-limit}. See below for its effects;
-note that it is only meaningful for internal windows. The
address@hidden function automatically calls this function, passing
-the value of the variable @code{window-combination-limit} as
address@hidden
address@hidden defun
-
address@hidden window-combination-limit window
-This function returns the combination limit for @var{window}.
-
-The combination limit is meaningful only for an internal window. If
-it is @code{nil}, then Emacs is allowed to automatically delete
address@hidden, in response to a window deletion, in order to group the
-child windows of @var{window} with its sibling windows to form a new
-window combination. If the combination limit is @code{t}, the child
-windows of @var{window} are never automatically re-combined with its
-siblings.
address@hidden defun
-
- To illustrate the effect of @code{window-combination-limit},
-consider the following configuration (throughout this example, we will
-assume that @code{window-combination-resize} is @code{nil}):
-
address@hidden
address@hidden
- ______________________________________
- | ____________________________________ |
- || ||
- || ||
- || ||
- || ||
- || ||
- || ||
- ||_________________W2_________________||
- | ____________________________________ |
- || ||
- || ||
- ||_________________W3_________________||
- |__________________W1__________________|
-
address@hidden group
address@hidden smallexample
-
address@hidden
-If @code{window-combination-limit} is @code{nil}, splitting @code{W2}
-into two windows, one above the other, yields
-
address@hidden
address@hidden
- ______________________________________
- | ____________________________________ |
- || ||
- || ||
- ||_________________W2_________________||
- | ____________________________________ |
- || ||
- || ||
- ||_________________W4_________________||
- | ____________________________________ |
- || ||
- || ||
- ||_________________W3_________________||
- |__________________W1__________________|
-
address@hidden group
address@hidden smallexample
-
address@hidden
-The newly-created window, @code{W4}, shares the same internal window
address@hidden If @code{W4} is resized, it is allowed to resize the other
-live window, @code{W3}.
-
- If @code{window-combination-limit} is @code{t}, splitting @code{W2}
-in the initial configuration would instead have produced this:
-
address@hidden
address@hidden
- ______________________________________
- | ____________________________________ |
- || __________________________________ ||
- ||| |||
- |||________________W2________________|||
- || __________________________________ ||
- ||| |||
- |||________________W4________________|||
- ||_________________W5_________________||
- | ____________________________________ |
- || ||
- || ||
- ||_________________W3_________________||
- |__________________W1__________________|
-
address@hidden group
address@hidden smallexample
-
address@hidden
-A new internal window @code{W5} has been created; its children are
address@hidden and the new live window @code{W4}. Now, @code{W2} is the
-only sibling of @code{W4}, so resizing @code{W4} will resize
address@hidden, leaving @code{W3} unaffected.
-
- For interactive use, Emacs provides two commands which always split
+ For interactive use, Emacs provides two commands which always split
the selected window. These call @code{split-window} internally.
@deffn Command split-window-right &optional size
@@ -1063,7 +850,7 @@
adjacent sibling windows, if any. However, if the variable
@code{window-combination-resize} is address@hidden, the space is
proportionally distributed among any remaining windows in the window
-combination. @xref{Splitting Windows}.
+combination. @xref{Recombining Windows}.
The behavior of this function may be altered by the window parameters
of @var{window}, so long as the variable
@@ -1128,6 +915,353 @@
are the opposite of what they are in those other functions.
@end deffn
+
address@hidden Recombining Windows
address@hidden Recombining Windows
+
+When deleting the last sibling of a window @code{W}, its parent window
+is deleted too, with @code{W} replacing it in the window tree. This
+means that @code{W} must be recombined with its parent's siblings to
+form a new window combination (@pxref{Windows and Frames}). In some
+occasions, deleting a live window may even entail the deletion of two
+internal windows.
+
address@hidden
address@hidden
+ ______________________________________
+ | ______ ____________________________ |
+ || || __________________________ ||
+ || ||| ___________ ___________ |||
+ || |||| || ||||
+ || ||||____W6_____||_____W7____||||
+ || |||____________W4____________|||
+ || || __________________________ ||
+ || ||| |||
+ || ||| |||
+ || |||____________W5____________|||
+ ||__W2__||_____________W3_____________ |
+ |__________________W1__________________|
+
address@hidden group
address@hidden smallexample
+
address@hidden
+Deleting @code{W5} in this configuration normally causes the deletion of
address@hidden and @code{W4}. The remaining live windows @code{W2},
address@hidden and @code{W7} are recombined to form a new horizontal
+combination with parent @code{W1}.
+
+ Sometimes, however, it makes sense to not delete a parent window like
address@hidden In particular, a parent window should not be removed when it
+was used to preserve a combination embedded in a combination of the same
+type. Such embeddings make sense to assure that when you split a window
+and subsequently delete the new window, Emacs reestablishes the layout
+of the associated frame as it existed before the splitting.
+
+ Consider a scenario starting with two live windows @code{W2} and
address@hidden and their parent @code{W1}.
+
address@hidden
address@hidden
+ ______________________________________
+ | ____________________________________ |
+ || ||
+ || ||
+ || ||
+ || ||
+ || ||
+ || ||
+ ||_________________W2_________________||
+ | ____________________________________ |
+ || ||
+ || ||
+ ||_________________W3_________________||
+ |__________________W1__________________|
+
address@hidden group
address@hidden smallexample
+
address@hidden
+Split @code{W2} to make a new window @code{W4} as follows.
+
address@hidden
address@hidden
+ ______________________________________
+ | ____________________________________ |
+ || ||
+ || ||
+ ||_________________W2_________________||
+ | ____________________________________ |
+ || ||
+ || ||
+ ||_________________W4_________________||
+ | ____________________________________ |
+ || ||
+ || ||
+ ||_________________W3_________________||
+ |__________________W1__________________|
+
address@hidden group
address@hidden smallexample
+
address@hidden
+Now, when enlarging a window vertically, Emacs tries to obtain the
+corresponding space from its lower sibling, provided such a window
+exists. In our scenario, enlarging @code{W4} will steal space from
address@hidden
+
address@hidden
address@hidden
+ ______________________________________
+ | ____________________________________ |
+ || ||
+ || ||
+ ||_________________W2_________________||
+ | ____________________________________ |
+ || ||
+ || ||
+ || ||
+ || ||
+ ||_________________W4_________________||
+ | ____________________________________ |
+ ||_________________W3_________________||
+ |__________________W1__________________|
+
address@hidden group
address@hidden smallexample
+
address@hidden
+Deleting @code{W4} will now give its entire space to @code{W2},
+including the space earlier stolen from @code{W3}.
+
address@hidden
address@hidden
+ ______________________________________
+ | ____________________________________ |
+ || ||
+ || ||
+ || ||
+ || ||
+ || ||
+ || ||
+ || ||
+ || ||
+ ||_________________W2_________________||
+ | ____________________________________ |
+ ||_________________W3_________________||
+ |__________________W1__________________|
+
address@hidden group
address@hidden smallexample
+
address@hidden
+This can be counterintutive, in particular if @code{W4} were used for
+displaying a buffer only temporarily (@pxref{Temporary Displays}), and
+you want to continue working with the initial layout.
+
+The behavior can be fixed by making a new parent window when splitting
address@hidden The variable described next allows to do that.
+
address@hidden window-combination-limit
+This variable controls whether splitting a window shall make a new
+parent window. The following values are recognized:
+
address@hidden @code
address@hidden nil
+This means that the new live window is allowed to share the existing
+parent window, if one exists, provided the split occurs in the same
+direction as the existing window combination (otherwise, a new internal
+window is created anyway).
+
address@hidden window-size
+In this case @code{display-buffer} makes a new parent window if it is
+passed a @code{window-height} or @code{window-width} entry in the
address@hidden argument (@pxref{Display Action Functions}).
+
address@hidden temp-buffer
+This value causes the creation of a new parent window when a window is
+split for showing a temporary buffer (@pxref{Temporary Displays}) only.
+
address@hidden display-buffer
+This means that when @code{display-buffer} (@pxref{Choosing Window})
+splits a window it always makes a new parent window.
+
address@hidden t
+In this case a new parent window is always created when splitting a
+window. Thus, if the value of this variable is at all times @code{t},
+then at all times every window tree is a binary tree (a tree where each
+window except the root window has exactly one sibling).
address@hidden table
+
+The default is @code{nil}. Other values are reserved for future use.
+
+If, as a consequence of this variable's setting, @code{split-window}
+makes a new parent window, it also calls
address@hidden (see below) on the newly-created
+internal window. This affects how the window tree is rearranged when
+the child windows are deleted (see below).
address@hidden defopt
+
+ If @code{window-combination-limit} is @code{t}, splitting @code{W2} in
+the initial configuration of our scenario would have produced this:
+
address@hidden
address@hidden
+ ______________________________________
+ | ____________________________________ |
+ || __________________________________ ||
+ ||| |||
+ |||________________W2________________|||
+ || __________________________________ ||
+ ||| |||
+ |||________________W4________________|||
+ ||_________________W5_________________||
+ | ____________________________________ |
+ || ||
+ || ||
+ ||_________________W3_________________||
+ |__________________W1__________________|
+
address@hidden group
address@hidden smallexample
+
address@hidden
+A new internal window @code{W5} has been created; its children are
address@hidden and the new live window @code{W4}. Now, @code{W2} is the only
+sibling of @code{W4}, so enlarging @code{W4} will try to shrink
address@hidden, leaving @code{W3} unaffected. Observe that @code{W5}
+represents a vertical combination of two windows embedded in the
+vertical combination @code{W1}.
+
address@hidden window combination limit
address@hidden set-window-combination-limit window limit
+This functions sets the @dfn{combination limit} of the window
address@hidden to @var{limit}. This value can be retrieved via the
+function @code{window-combination-limit}. See below for its effects;
+note that it is only meaningful for internal windows. The
address@hidden function automatically calls this function, passing
+it @code{t} as @var{limit}, provided the value of the variable
address@hidden is @code{t} when it is called.
address@hidden defun
+
address@hidden window-combination-limit window
+This function returns the combination limit for @var{window}.
+
+The combination limit is meaningful only for an internal window. If it
+is @code{nil}, then Emacs is allowed to automatically delete
address@hidden, in response to a window deletion, in order to group the
+child windows of @var{window} with its sibling windows to form a new
+window combination. If the combination limit is @code{t}, the child
+windows of @var{window} are never automatically recombined with its
+siblings.
+
+If, in the configuration shown at the beginning of this section, the
+combination limit of @code{W4} (the parent window of @code{W6} and
address@hidden) is @code{t}, deleting @code{W5} will not implicitly delete
address@hidden too.
address@hidden defun
+
+Alternatively, the problems sketched above can be avoided by always
+resizing all windows in the same combination whenever one of its windows
+is split or deleted. This also permits to split windows that would be
+otherwise too small for such an operation.
+
address@hidden window-combination-resize
+If this variable is @code{nil}, @code{split-window} can only split a
+window (denoted by @var{window}) if @var{window}'s screen area is large
+enough to accommodate both itself and the new window.
+
+If this variable is @code{t}, @code{split-window} tries to resize all
+windows that are part of the same combination as @var{window}, in order
+to accommodate the new window. In particular, this may allow
address@hidden to succeed even if @var{window} is a fixed-size
+window or too small to ordinarily split. Furthermore, subsequently
+resizing or deleting @var{window} may resize all other windows in its
+combination.
+
+The default is @code{nil}. Other values are reserved for future use.
+The value of this variable is ignored when
address@hidden is address@hidden
address@hidden defopt
+
+ To illustrate the effect of @code{window-combination-resize}, consider
+the following frame layout.
+
address@hidden
address@hidden
+ ______________________________________
+ | ____________________________________ |
+ || ||
+ || ||
+ || ||
+ || ||
+ ||_________________W2_________________||
+ | ____________________________________ |
+ || ||
+ || ||
+ || ||
+ || ||
+ ||_________________W3_________________||
+ |__________________W1__________________|
+
address@hidden group
address@hidden smallexample
+
address@hidden
+If @code{window-combination-resize} is @code{nil}, splitting window
address@hidden leaves the size of @code{W2} unchanged:
+
address@hidden
address@hidden
+ ______________________________________
+ | ____________________________________ |
+ || ||
+ || ||
+ || ||
+ || ||
+ ||_________________W2_________________||
+ | ____________________________________ |
+ || ||
+ ||_________________W3_________________||
+ | ____________________________________ |
+ || ||
+ ||_________________W4_________________||
+ |__________________W1__________________|
+
address@hidden group
address@hidden smallexample
+
address@hidden
+If @code{window-combination-resize} is @code{t}, splitting @code{W3}
+instead leaves all three live windows with approximately the same
+height:
+
address@hidden
address@hidden
+ ______________________________________
+ | ____________________________________ |
+ || ||
+ || ||
+ ||_________________W2_________________||
+ | ____________________________________ |
+ || ||
+ || ||
+ ||_________________W3_________________||
+ | ____________________________________ |
+ || ||
+ || ||
+ ||_________________W4_________________||
+ |__________________W1__________________|
+
address@hidden group
address@hidden smallexample
+
address@hidden
+Deleting any of the live windows @code{W2}, @code{W3} or @code{W4} will
+distribute its space proportionally among the two remaining live
+windows.
+
+
@node Selecting Windows
@section Selecting Windows
@cindex selecting a window
=== modified file 'etc/NEWS'
--- a/etc/NEWS 2012-11-07 08:56:16 +0000
+++ b/etc/NEWS 2012-11-07 09:41:52 +0000
@@ -834,7 +834,7 @@
+++
*** The functions get-lru-window, get-mru-window and get-largest-window
now accept a third argument to avoid choosing the selected window.
-
++++
*** Additional values recognized for option `window-combination-limit'.
*** New macro `with-temp-buffer-window'.
=== modified file 'src/ChangeLog'
--- a/src/ChangeLog 2012-11-06 16:36:02 +0000
+++ b/src/ChangeLog 2012-11-07 09:41:52 +0000
@@ -1,3 +1,11 @@
+2012-11-07 Martin Rudalics <address@hidden>
+
+ * window.c (Fsplit_window_internal): Set combination limit of
+ new parent window to t iff Vwindow_combination_limit is t;
+ fixing a regression introduced with the change from 2012-09-22.
+ (Fwindow_combination_limit, Fset_window_combination_limit): Fix
+ doc-strings.
+
2012-11-06 Eli Zaretskii <address@hidden>
* xdisp.c (try_scrolling): Fix correction of aggressive-scroll
=== modified file 'src/window.c'
--- a/src/window.c 2012-10-18 08:27:49 +0000
+++ b/src/window.c 2012-11-07 09:41:52 +0000
@@ -600,10 +600,12 @@
DEFUN ("window-combination-limit", Fwindow_combination_limit,
Swindow_combination_limit, 1, 1, 0,
doc: /* Return combination limit of window WINDOW.
-WINDOW must be a valid window and defaults to the selected one.
-If the return value is nil, child windows of WINDOW can be recombined with
-WINDOW's siblings. A return value of t means that child windows of
-WINDOW are never \(re-)combined with WINDOW's siblings. */)
+If the return value is nil, child windows of WINDOW can be recombined
+with WINDOW's siblings. A return value of t means that child windows of
+WINDOW are never \(re-)combined with WINDOW's siblings.
+
+WINDOW must be a valid window. The return value is meaningful for
+internal windows only. */)
(Lisp_Object window)
{
return decode_valid_window (window)->combination_limit;
@@ -611,11 +613,13 @@
DEFUN ("set-window-combination-limit", Fset_window_combination_limit,
Sset_window_combination_limit, 2, 2, 0,
doc: /* Set combination limit of window WINDOW to LIMIT; return LIMIT.
-WINDOW must be a valid window and defaults to the selected one.
If LIMIT is nil, child windows of WINDOW can be recombined with WINDOW's
siblings. LIMIT t means that child windows of WINDOW are never
\(re-)combined with WINDOW's siblings. Other values are reserved for
-future use. */)
+future use.
+
+WINDOW must be a valid window. Setting the combination limit is
+meaningful for internal windows only. */)
(Lisp_Object window, Lisp_Object limit)
{
wset_combination_limit (decode_valid_window (window), limit);
@@ -3892,9 +3896,10 @@
make_parent_window (old, horflag);
p = XWINDOW (o->parent);
- /* Store t in the new parent's combination_limit slot to avoid
- that its children get merged into another window. */
- wset_combination_limit (p, Qt);
+ if (EQ (Vwindow_combination_limit, Qt))
+ /* Store t in the new parent's combination_limit slot to avoid
+ that its children get merged into another window. */
+ wset_combination_limit (p, Qt);
/* These get applied below. */
wset_new_total (p, horflag ? o->total_cols : o->total_lines);
wset_new_normal (p, new_normal);
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/emacs-24 r110804: Fix and rewrite doc on window recombining facilities.,
martin rudalics <=