[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] master 665ee0a: Document atomic windows in Elisp manual (B
From: |
Martin Rudalics |
Subject: |
[Emacs-diffs] master 665ee0a: Document atomic windows in Elisp manual (Bug#18170) |
Date: |
Mon, 17 Oct 2016 06:58:15 +0000 (UTC) |
branch: master
commit 665ee0a56551ad897a9e5092ebc91728c98a2d43
Author: Martin Rudalics <address@hidden>
Commit: Martin Rudalics <address@hidden>
Document atomic windows in Elisp manual (Bug#18170)
* lisp/window.el (display-buffer-in-atom-window): If no `side'
alist entry was specified, use `below' as the doc tells.
* doc/lispref/elisp.texi (Atomic Windows): Add menu entry.
* doc/lispref/windows.texi (Atomic Windows): New section.
(Window Parameters): Update reference.
---
doc/lispref/elisp.texi | 1 +
doc/lispref/windows.texi | 137 ++++++++++++++++++++++++++++++++++++++++++++++
lisp/window.el | 2 +-
3 files changed, 139 insertions(+), 1 deletion(-)
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 1c6e059..4a1e528 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1039,6 +1039,7 @@ Windows
* Quitting Windows:: How to restore the state prior to displaying a
buffer.
* Side Windows:: Special windows on a frame's sides.
+* Atomic Windows:: Preserving parts of the window layout.
* Window Point:: Each window has its own location of point.
* Window Start and End:: Buffer positions indicating which text is
on-screen in a window.
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 8140c21..d66a944 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -34,6 +34,7 @@ is displayed in windows.
* Quitting Windows:: How to restore the state prior to displaying a
buffer.
* Side Windows:: Special windows on a frame's sides.
+* Atomic Windows:: Preserving parts of the window layout.
* Window Point:: Each window has its own location of point.
* Window Start and End:: Buffer positions indicating which text is
on-screen in a window.
@@ -3368,6 +3369,138 @@ and @kbd{M-x dired-default-directory-on-left} should
now reproduce the
frame layout sketched above.
address@hidden Atomic Windows
address@hidden Atomic Windows
address@hidden atomic windows
+
+Atomic windows are rectangular compositions of at least two live
+windows. They have the following distinctive characteristics:
+
address@hidden @bullet
address@hidden
+The function @code{split-window} (@pxref{Splitting Windows}), when
+applied to a constituent of an atomic window, will try to create the new
+window outside of the atomic window.
+
address@hidden
+The function @code{delete-window} (@pxref{Deleting Windows}), when
+applied to a constituent of an atomic window, will try to delete the
+entire atomic window instead.
+
address@hidden
+The function @code{delete-other-windows} (@pxref{Deleting Windows}),
+when applied to a constituent of an atomic window, will try to make the
+atomic window fill its frame or main window (@pxref{Side Windows}).
address@hidden itemize
+
+This means that the basic groups of functions that alter the window
+structure treat an atomic window like a live one, thus preserving the
+internal structure of the atomic window.
+
+ Atomic windows are useful to construct and preserve window layouts
+that are meaningful only when all involved buffers are shown
+simultaneously in a specific manner, such as when showing differences
+between file revisions, or the same text in different languages or
+markups. They can also be used to permanently display information
+pertinent to a specific window in bars on that window's sides.
+
address@hidden root window of atomic window
+ Atomic windows are implemented with the help of the reserved
address@hidden window parameter (@pxref{Window Parameters}) and an
+internal window (@pxref{Basic Windows}) called the root window of the
+atomic window. All windows that are part of the same atomic window have
+this root window as their common ancestor and are assigned a
address@hidden @code{window-atom} parameter.
+
+ The following function returns the root of the atomic window a
+specified window is part of:
+
address@hidden window-atom-root &optional window
+This functions returns the root of the atomic window @var{window} is a
+part of. The specified @var{window} must be a valid window and defaults
+to the selected one. It returns @code{nil} if @var{window} is not part
+of an atomic window.
address@hidden defun
+
+The most simple approach to make a new atomic window is to take an
+existing internal window and apply the following function:
+
address@hidden window-make-atom window
+This function converts @var{window} into an atomic window. The
+specified @var{window} must be an internal window. All this function
+does is to set the @code{window-atom} parameter of each descendant of
address@hidden to @code{t}.
address@hidden defun
+
+To create a new atomic window from an existing live window or to add a
+new window to an existing atomic window, the following buffer display
+action function (@pxref{Display Action Functions}) can be used:
+
address@hidden display-buffer-in-atom-window buffer alist
+This function tries to display @var{buffer} in a new window that will be
+combined with an existing window to form an atomic window. If the
+existing window is already part of an atomic window, it adds the new
+window to that atomic window.
+
+The specified @var{alist} is an association list of symbols and values.
+The following symbols have a special meaning:
+
address@hidden @code
address@hidden window
+The value of such an element specifies an existing window the new window
+shall be combined with. If it specifies an internal window, all
+children of that window become part of the atomic window too. If no
+window is specified, the new window becomes a sibling of the selected
+window. The @code{window-atom} parameter of the existing window is set
+to @code{main} provided that window is live and its @code{window-atom}
+parameter was not already set.
+
address@hidden side
+The value of such an element denotes the side of the existing window
+where the new window shall be located. Valid values are @code{below},
address@hidden, @code{above} and @code{left}. The default is
address@hidden The @code{window-atom} parameter of the new window is set
+to this value.
address@hidden table
+
+The return value is the new window, @code{nil} when creating that window
+failed.
address@hidden defun
+
+Note that the value of the @code{window-atom} parameter does not really
+matter as long as it is address@hidden The values assigned by
address@hidden just allow for easy retrieval of
+the original and the new window after that function has been applied.
+Note also that the @code{window-atom} parameter is the only window
+parameter assigned by @code{display-buffer-in-atom-window}. Further
+parameters have to be set by the application explicitly via a
address@hidden entry in @var{alist}.
+
+ The following code snippet, when applied to a single-window frame,
+first splits the selected window and makes the selected and the new
+window constituents of an atomic window with their parent as root. It
+then displays the buffer @file{*Messages*} in a new window at the
+frame's bottom and makes that new window part of the atomic window just
+created.
+
address@hidden
address@hidden
+(let ((window (split-window-right)))
+ (window-make-atom (window-parent window))
+ (display-buffer-in-atom-window
+ (get-buffer-create "*Messages*")
+ `((window . ,(window-parent window)) (window-height . 5))))
address@hidden group
address@hidden example
+
+At this moment typing @address@hidden 2}} in any window of that frame
+produces a new window at the bottom of the frame. Typing @address@hidden
+3}} instead will put the new window at the frame's right. In either
+case, typing now @address@hidden 1}} in any window of the atomic window will
+remove the new window only. Typing @address@hidden 0}} in any window of the
+atomic window will make that new window fill the frame.
+
+
@node Window Point
@section Windows and Point
@cindex window position
@@ -4716,6 +4849,10 @@ only if it still shows that buffer.
These parameters are used for implementing side windows (@pxref{Side
Windows}).
address@hidden @code{window-atom}
+This parameter is used for implementing atomic windows, see @ref{Atomic
+Windows}.
+
@item @code{min-margins}
The value of this parameter is a cons cell whose @sc{car} and @sc{cdr},
if address@hidden, specify the minimum values (in columns) for the left
diff --git a/lisp/window.el b/lisp/window.el
index dea0b25..da3691e 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -651,7 +651,7 @@ failed."
(window-combination-limit t)
(window-combination-resize 'atom)
(window (cdr (assq 'window alist)))
- (side (cdr (assq 'side alist)))
+ (side (or (cdr (assq 'side alist)) 'below))
(atom (when window (window-parameter window 'window-atom)))
root new)
(setq window (window-normalize-window window))
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] master 665ee0a: Document atomic windows in Elisp manual (Bug#18170),
Martin Rudalics <=