From c7897c27861fd8b2690f40e77402edced6aa0ceb Mon Sep 17 00:00:00 2001 From: Martin Rudalics Date: Mon, 3 Dec 2018 09:35:33 +0100 Subject: [PATCH] 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 6c9bba126e3..b95a15fec5d 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. + +@item pseudo_window_p +@cindex 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 +@code{nil}. 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. +@item 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 +@code{nil} for a window that has been deleted. + @item next @itemx prev -The next sibling and previous sibling of this window. @code{next} 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: if it's non-zero, the siblings are -arranged horizontally. +The next and previous sibling of this window as Lisp objects. +@code{next} 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) +@code{prev} 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. + +@item pixel_left +@itemx 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). -@item 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. +@item pixel_width; +@itemx 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. -@item vertical_scroll_bar -This window's vertical scroll bar, a Lisp object. +@item vertical_scroll_bar_type +@itemx horizontal_scroll_bar_type +The types of this window's vertical and horizontal scroll bars. + +@item scroll_bar_width +@itemx 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 Non-@code{nil} if this window is dedicated to its buffer. +@item 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. + +@item 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. -@item 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 c7f525e2704..96e9a9f30ea 100644 --- a/src/window.h +++ b/src/window.h @@ -24,57 +24,69 @@ along with GNU Emacs. If not, see . */ 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 triples listing + /* A list of triples listing buffers previously shown in this window. */ Lisp_Object prev_buffers; /* List of buffers re-shown in this window. */ -- 2.39.5