[Emacs-diffs] emacs-26 c7897c2: A few further fixes of window internals description

[Martin Rudalics]

branch: emacs-26
commit c7897c27861fd8b2690f40e77402edced6aa0ceb
Author: Martin Rudalics <address@hidden>
Commit: Martin Rudalics <address@hidden>

    A few further fixes of window internals description
    
    * doc/lispref/internals.texi (Window Internals): Add a few
    more items and clarify description of some others.
---
 doc/lispref/internals.texi |  96 +++++++++++++++++++++---------
 src/window.h               | 142 ++++++++++++++++++++++++++-------------------
 2 files changed, 150 insertions(+), 88 deletions(-)

diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index 6c9bba1..b95a15f 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -2049,45 +2049,76 @@ if that window no longer displays this buffer.
 The frame that this window is on, as a Lisp object.
 
 @item mini
-Non-zero if this window is a minibuffer window.
+Non-zero if this window is a minibuffer window, a window showing the
+minibuffer or the echo area.
+
address@hidden pseudo_window_p
address@hidden pseudo window
+Non-zero if this window is a @dfn{pseudo window}.  A pseudo window is
+either a window used to display the menu bar or the tool bar (when
+Emacs uses toolkits that don't display their own menu bar and tool
+bar) or a window showing a tooltip on a tooltip frame.  Pseudo windows
+are in general not accessible from Lisp code.
 
 @item parent
-Internally, Emacs arranges windows in a tree; each group of siblings has
-a parent window whose area includes all the siblings.  This field points
-to a window's parent, as a Lisp object.
+Internally, Emacs arranges windows in a tree; each group of siblings
+has a parent window whose area includes all the siblings.  This field
+points to the window's parent in that tree, as a Lisp object.  For the
+root window of the tree and a minibuffer window this is always
address@hidden
 
 Parent windows do not display buffers, and play little role in display
-except to shape their child windows.  Emacs Lisp programs usually have
-no access to the parent windows; they operate on the windows at the
+except to shape their child windows.  Emacs Lisp programs cannot
+directly manipulate parent windows; they operate on the windows at the
 leaves of the tree, which actually display buffers.
 
address@hidden contents
+For a leaf window and windows showing a tooltip, this is the buffer,
+as a Lisp object, that the window is displaying.  For an internal
+(``parent'') window, this is its first child window.  For a pseudo
+window showing a menu or tool bar this is @code{nil}.  It is also
address@hidden for a window that has been deleted.
+
 @item next
 @itemx prev
-The next sibling and previous sibling of this window.  @code{next} is
address@hidden if the window is the right-most or bottom-most in its group;
address@hidden is @code{nil} if it is the left-most or top-most in its
-group.  Whether the sibling is left/right or up/down is determined by
-the @code{horizontal} field: if it's non-zero, the siblings are
-arranged horizontally.
+The next and previous sibling of this window as Lisp objects.
address@hidden is @code{nil} if the window is the right-most or
+bottom-most in its group; @code{prev} is @code{nil} if it is the
+left-most or top-most in its group.  Whether the sibling is left/right
+or up/down is determined by the @code{horizontal} field of the
+sibling's parent: if it's non-zero, the siblings are arranged
+horizontally.
+
+As a special case, @code{next} of a frame's root window points to the
+frame's minibuffer window, provided this is not a minibuffer-only or
+minibuffer-less frame.  On such frames @code{prev} of the minibuffer
+window points to that frame's root window.  In any other case, the
+root window's @code{next} and the minibuffer window's (if present)
address@hidden fields are @code{nil}.
 
 @item left_col
 The left-hand edge of the window, measured in columns, relative to the
-leftmost column in the frame (column 0).
+leftmost column (column 0) of the window's native frame.
 
 @item top_line
 The top edge of the window, measured in lines, relative to the topmost
-line in the frame (line 0).
+line (line 0) of the window's native frame.
+
address@hidden pixel_left
address@hidden pixel_top
+The left-hand and top edges of this window, measured in pixels,
+relative to the top-left corner (0, 0) of the window's native frame.
 
 @item total_cols
 @itemx total_lines
-The width and height of the window, measured in columns and lines
-respectively.  The width includes the scroll bar and fringes, and/or
-the separator line on the right of the window (if any).
+The total width and height of the window, measured in columns and
+lines respectively.  The values include scroll bars and fringes,
+dividers and/or the separator line on the right of the window (if
+any).
 
address@hidden contents
-For leaf windows, this is the buffer, as a Lisp object, that the
-window is displaying.  For an internal (``parent'') window, this is
-its child window.  It can also be @code{nil}, for a pseudo-window.
address@hidden pixel_width;
address@hidden pixel_height;
+The total width and height of the window measured in pixels.
 
 @item start
 A marker pointing to the position in the buffer that is the first
@@ -2141,8 +2172,14 @@ in this window.
 A non-zero value means the window's buffer was modified when the
 window was last updated.
 
address@hidden vertical_scroll_bar
-This window's vertical scroll bar, a Lisp object.
address@hidden vertical_scroll_bar_type
address@hidden horizontal_scroll_bar_type
+The types of this window's vertical and horizontal scroll bars.
+
address@hidden scroll_bar_width
address@hidden scroll_bar_height
+The width of this window's vertical scroll bar and the height of this
+window's horizontal scroll bar, in pixels.
 
 @item left_margin_cols
 @itemx right_margin_cols
@@ -2226,6 +2263,14 @@ Vertical scroll amount, in pixels.  Normally, this is 0.
 @item dedicated
 address@hidden if this window is dedicated to its buffer.
 
address@hidden combination_limit
+This window's combination limit, meaningful only for a parent window.
+If this is @code{t}, then it is not allowed to delete this window and
+recombine its child windows with other siblings of this window.
+
address@hidden window_parameters
+The alist of this window's parameters.
+
 @item display_table
 The window's display table, or @code{nil} if none is specified for it.
 
@@ -2250,11 +2295,6 @@ the line number as long as the window shows that buffer.
 The column number currently displayed in this window's mode line, or
 @minus{}1 if column numbers are not being displayed.
 
address@hidden pseudo_window_p
-This is non-zero for windows that display the menu bar and the tool
-bar (when Emacs uses toolkits that don't display their own menu bar
-and tool bar).
-
 @item current_matrix
 @itemx desired_matrix
 Glyph matrices describing the current and desired display of this window.
diff --git a/src/window.h b/src/window.h
index c7f525e..96e9a9f 100644
--- a/src/window.h
+++ b/src/window.h
@@ -24,57 +24,69 @@ along with GNU Emacs.  If not, see 
<https://www.gnu.org/licenses/>.  */
 
 INLINE_HEADER_BEGIN
 
-/* Windows are allocated as if they were vectors, but then the
-Lisp data type is changed to Lisp_Window.  They are garbage
-collected along with the vectors.
+/* Windows are allocated as if they were vectors, but then the Lisp
+data type is changed to Lisp_Window.  They are garbage collected along
+with the vectors.
 
 All windows in use are arranged into a tree, with pointers up and down.
 
-Windows that are leaves of the tree are actually displayed
-and show the contents of buffers.  Windows that are not leaves
-are used for representing the way groups of leaf windows are
-arranged on the frame.  Leaf windows never become non-leaves.
-They are deleted only by calling delete-window on them (but
-this can be done implicitly).  Combination windows can be created
-and deleted at any time.
-
-A leaf window has a buffer stored in contents field and markers in its start
-and pointm fields.  Non-leaf windows have nil in the latter two fields.
-
-Non-leaf windows are either vertical or horizontal combinations.
-
-A vertical combination window has children that are arranged on the frame
-one above the next.  Its contents field points to the uppermost child.
-The parent field of each of the children points to the vertical
-combination window.  The next field of each child points to the
-child below it, or is nil for the lowest child.  The prev field
-of each child points to the child above it, or is nil for the
-highest child.
-
-A horizontal combination window has children that are side by side.
-Its contents field points to the leftmost child.  In each child
-the next field points to the child to the right and the prev field
-points to the child to the left.
-
-The children of a vertical combination window may be leaf windows
-or horizontal combination windows.  The children of a horizontal
-combination window may be leaf windows or vertical combination windows.
-
-At the top of the tree are two windows which have nil as parent.
-The second of these is minibuf_window.  The first one manages all
-the frame area that is not minibuffer, and is called the root window.
-Different windows can be the root at different times;
-initially the root window is a leaf window, but if more windows
-are created then that leaf window ceases to be root and a newly
-made combination window becomes root instead.
-
-In any case, on screens which have an ordinary window and a
-minibuffer, prev of the minibuf window is the root window and next of
-the root window is the minibuf window.  On minibufferless screens or
-minibuffer-only screens, the root window and the minibuffer window are
-one and the same, so its prev and next members are nil.
-
-A dead window has its contents field set to nil.  */
+Windows that are leaves of the tree are actually displayed and show
+the contents of buffers.  Windows that are not leaves are used for
+representing the way groups of leaf windows are arranged on the frame.
+Leaf windows never become non-leaves.  They are deleted only by
+calling `delete-window' on them (but this can be done implicitly).
+Non-leaf windows never become leaf windows and can be created and
+deleted at any time by the window management code.  Non-leaf windows
+can be seen but not directly manipulated by Lisp functions.
+
+A leaf window has a buffer stored in its contents field and markers in
+its 'start' and 'pointm' fields.  Non-leaf windows have nil in the
+latter two fields.  Non-leaf windows are either vertical or horizontal
+combinations.
+
+A vertical combination window has children that are arranged on the
+frame one above the next.  Its 'contents' field points to the
+uppermost child.  The 'parent' field of each of the children points to
+the vertical combination window.  The 'next' field of each child
+points to the child below it, or is nil for the lowest child.  The
+'prev' field of each child points to the child above it, or is nil for
+the highest child.
+
+A horizontal combination window has children that are arranged side by
+side.  Its 'contents' field points to the leftmost child.  In each
+child the 'next' field points to the child to the right and the 'prev'
+field points to the child to the left.
+
+On each frame there are at least one and at most two windows which
+have nil as parent.  The second of these, if present, is the frame's
+minibuffer window and shows the minibuffer or the echo area.  The
+first one manages the remaining frame area and is called the frame's
+root window.  Different windows can be the root at different times;
+initially the root window is a leaf window, but if more windows are
+created, then that leaf window ceases to be root and a newly made
+combination window becomes the root instead.
+
+On frames which have an ordinary window and a minibuffer window,
+'prev' of the minibuffer window is the root window and 'next' of the
+root window is the minibuffer window.  On minibuffer-less frames there
+is only a root window and 'next' of the root window is nil.  On
+minibuffer-only frames, the root window and the minibuffer window are
+one and the same, so its 'prev' and 'next' members are nil.  In any
+case, 'prev' of a root window and 'next' of a minibuffer window are
+always nil.
+
+In Lisp parlance, leaf windows are called "live windows" and non-leaf
+windows are called "internal windows".  Together, live and internal
+windows form the set of "valid windows".  A window that has been
+deleted is considered "dead" regardless of whether it formerly was a
+leaf or a non-leaf window.  A dead window has its 'contents' field set
+to nil.
+
+Frames may also contain pseudo windows, windows that are not exposed
+directly to Lisp code.  Pseudo windows are currently either used to
+display the menu bar or the tool bar (when Emacs uses toolkits that
+don't display their own menu bar and tool bar) or a tooltip in a
+tooltip frame (when tooltips are not display by the toolkit).  */
 
 struct cursor_pos
 {
@@ -95,29 +107,39 @@ struct window
 
     /* Following (to right or down) and preceding (to left or up)
        child at same level of tree.  Whether this is left/right or
-       up/down is determined by the 'horizontal' flag, see below.
-       A minibuffer window has the frame's root window pointed by 'prev'.  */
+       up/down is determined by the parent window's 'horizontal' flag,
+       see below.  On a frame that is neither a minibuffer-only nor a
+       minibuffer-less frame, 'next' of the root window points to the
+       frame's minibuffer window and 'prev' of the minibuffer window
+       points to the frame's root window.  In all other cases, 'next'
+       of the root window and 'prev' of the minibuffer window, if
+       present, are nil.  'prev' of the root window and 'next' of the
+       minibuffer window are always nil.  */
     Lisp_Object next;
     Lisp_Object prev;
 
-    /* The window this one is a child of.  For a minibuffer window: nil.  */
+    /* The window this one is a child of.  For the root and a
+       minibuffer window this is always nil.  */
     Lisp_Object parent;
 
-    /* The normal size of the window.  These are fractions, but we do
-       not use C doubles to avoid creating new Lisp_Float objects while
-       interfacing Lisp in Fwindow_normal_size.  */
+    /* The "normal" size of the window.  These are fractions, but we
+       do not use C doubles to avoid creating new Lisp_Float objects
+       while interfacing Lisp in Fwindow_normal_size.  */
     Lisp_Object normal_lines;
     Lisp_Object normal_cols;
 
-    /* New sizes of the window.  Note that Lisp code may set new_normal
-       to something beyond an integer, so C int can't be used here.  */
+    /* The new sizes of the window as proposed by the window resizing
+       functions.  Note that Lisp code may set new_normal to something
+       beyond an integer, so C int can't be used here.  */
     Lisp_Object new_total;
     Lisp_Object new_normal;
     Lisp_Object new_pixel;
 
-    /* For a leaf window: a buffer; for an internal window: a window;
-       for a pseudo-window (such as menu bar or tool bar): nil.  It is
-       a buffer for a minibuffer window as well.  */
+    /* For a leaf window or a tooltip window this is the buffer shown
+       in the window; for a combination window this is the first of
+       its child windows; for a pseudo window showing the menu bar or
+       tool bar this is nil.  It is a buffer for a minibuffer window
+       as well.  */
     Lisp_Object contents;
 
     /* A marker pointing to where in the text to start displaying.
@@ -192,7 +214,7 @@ struct window
 
     /* The two Lisp_Object fields below are marked in a special way,
        which is why they're placed after `current_matrix'.  */
-    /* Alist of <buffer, window-start, window-point> triples listing
+    /* A list of <buffer, window-start, window-point> triples listing
        buffers previously shown in this window.  */
     Lisp_Object prev_buffers;
     /* List of buffers re-shown in this window.  */