procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

A few further fixes of window internals description

Browse source 
* doc/lispref/internals.texi (Window Internals): Add a few
more items and clarify description of some others.
This commit is contained in:
Martin Rudalics 2018-12-03 09:35:33 +01:00
parent 745c9c0258
commit c7897c2786
2 changed files with 143 additions and 81 deletions

96
doc/lispref/internals.texi
View file

@ -2049,45 +2049,76 @@ if that window no longer displays this buffer.
The frame that this window is on, as a Lisp object. The frame that this window is on, as a Lisp object.
@item mini @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 @item parent
Internally, Emacs arranges windows in a tree; each group of siblings has Internally, Emacs arranges windows in a tree; each group of siblings
a parent window whose area includes all the siblings. This field points has a parent window whose area includes all the siblings. This field
to a window's parent, as a Lisp object. 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 Parent windows do not display buffers, and play little role in display
except to shape their child windows. Emacs Lisp programs usually have except to shape their child windows. Emacs Lisp programs cannot
no access to the parent windows; they operate on the windows at the directly manipulate parent windows; they operate on the windows at the
leaves of the tree, which actually display buffers. 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 @item next
@itemx prev @itemx prev
The next sibling and previous sibling of this window. @code{next} is The next and previous sibling of this window as Lisp objects.
@code{nil} if the window is the right-most or bottom-most in its group; @code{next} is @code{nil} if the window is the right-most or
@code{prev} is @code{nil} if it is the left-most or top-most in its bottom-most in its group; @code{prev} is @code{nil} if it is the
group. Whether the sibling is left/right or up/down is determined by left-most or top-most in its group. Whether the sibling is left/right
the @code{horizontal} field: if it's non-zero, the siblings are or up/down is determined by the @code{horizontal} field of the
arranged horizontally. 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 @item left_col
The left-hand edge of the window, measured in columns, relative to the 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 @item top_line
The top edge of the window, measured in lines, relative to the topmost 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 @item total_cols
@itemx total_lines @itemx total_lines
The width and height of the window, measured in columns and lines The total width and height of the window, measured in columns and
respectively. The width includes the scroll bar and fringes, and/or lines respectively. The values include scroll bars and fringes,
the separator line on the right of the window (if any). dividers and/or the separator line on the right of the window (if
any).
@item contents @item pixel_width;
For leaf windows, this is the buffer, as a Lisp object, that the @itemx pixel_height;
window is displaying. For an internal (``parent'') window, this is The total width and height of the window measured in pixels.
its child window. It can also be @code{nil}, for a pseudo-window.
@item start @item start
A marker pointing to the position in the buffer that is the first 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 A non-zero value means the window's buffer was modified when the
window was last updated. window was last updated.
@item vertical_scroll_bar @item vertical_scroll_bar_type
This window's vertical scroll bar, a Lisp object. @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 @item left_margin_cols
@itemx right_margin_cols @itemx right_margin_cols
@ -2226,6 +2263,14 @@ Vertical scroll amount, in pixels. Normally, this is 0.
@item dedicated @item dedicated
Non-@code{nil} if this window is dedicated to its buffer. 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 @item display_table
The window's display table, or @code{nil} if none is specified for it. 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 The column number currently displayed in this window's mode line, or
@minus{}1 if column numbers are not being displayed. @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 @item current_matrix
@itemx desired_matrix @itemx desired_matrix
Glyph matrices describing the current and desired display of this window. Glyph matrices describing the current and desired display of this window.

128
src/window.h
View file

@ -24,57 +24,69 @@ along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>. */
INLINE_HEADER_BEGIN INLINE_HEADER_BEGIN
/* Windows are allocated as if they were vectors, but then the /* Windows are allocated as if they were vectors, but then the Lisp
Lisp data type is changed to Lisp_Window. They are garbage data type is changed to Lisp_Window. They are garbage collected along
collected along with the vectors. with the vectors.
All windows in use are arranged into a tree, with pointers up and down. All windows in use are arranged into a tree, with pointers up and down.
Windows that are leaves of the tree are actually displayed Windows that are leaves of the tree are actually displayed and show
and show the contents of buffers. Windows that are not leaves the contents of buffers. Windows that are not leaves are used for
are used for representing the way groups of leaf windows are representing the way groups of leaf windows are arranged on the frame.
arranged on the frame. Leaf windows never become non-leaves. Leaf windows never become non-leaves. They are deleted only by
They are deleted only by calling delete-window on them (but calling `delete-window' on them (but this can be done implicitly).
this can be done implicitly). Combination windows can be created Non-leaf windows never become leaf windows and can be created and
and deleted at any time. 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 contents field and markers in its start A leaf window has a buffer stored in its contents field and markers in
and pointm fields. Non-leaf windows have nil in the latter two fields. its 'start' and 'pointm' fields. Non-leaf windows have nil in the
latter two fields. Non-leaf windows are either vertical or horizontal
combinations.
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 vertical combination window has children that are arranged on the frame A horizontal combination window has children that are arranged side by
one above the next. Its contents field points to the uppermost child. side. Its 'contents' field points to the leftmost child. In each
The parent field of each of the children points to the vertical child the 'next' field points to the child to the right and the 'prev'
combination window. The next field of each child points to the field points to the child to the left.
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. On each frame there are at least one and at most two windows which
Its contents field points to the leftmost child. In each child have nil as parent. The second of these, if present, is the frame's
the next field points to the child to the right and the prev field minibuffer window and shows the minibuffer or the echo area. The
points to the child to the left. 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.
The children of a vertical combination window may be leaf windows On frames which have an ordinary window and a minibuffer window,
or horizontal combination windows. The children of a horizontal 'prev' of the minibuffer window is the root window and 'next' of the
combination window may be leaf windows or vertical combination windows. 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.
At the top of the tree are two windows which have nil as parent. In Lisp parlance, leaf windows are called "live windows" and non-leaf
The second of these is minibuf_window. The first one manages all windows are called "internal windows". Together, live and internal
the frame area that is not minibuffer, and is called the root window. windows form the set of "valid windows". A window that has been
Different windows can be the root at different times; deleted is considered "dead" regardless of whether it formerly was a
initially the root window is a leaf window, but if more windows leaf or a non-leaf window. A dead window has its 'contents' field set
are created then that leaf window ceases to be root and a newly to nil.
made combination window becomes root instead.
In any case, on screens which have an ordinary window and a Frames may also contain pseudo windows, windows that are not exposed
minibuffer, prev of the minibuf window is the root window and next of directly to Lisp code. Pseudo windows are currently either used to
the root window is the minibuf window. On minibufferless screens or display the menu bar or the tool bar (when Emacs uses toolkits that
minibuffer-only screens, the root window and the minibuffer window are don't display their own menu bar and tool bar) or a tooltip in a
one and the same, so its prev and next members are nil. tooltip frame (when tooltips are not display by the toolkit). */
A dead window has its contents field set to nil. */
struct cursor_pos struct cursor_pos
{ {
@ -95,29 +107,39 @@ struct window
/* Following (to right or down) and preceding (to left or up) /* Following (to right or down) and preceding (to left or up)
child at same level of tree. Whether this is left/right or child at same level of tree. Whether this is left/right or
up/down is determined by the 'horizontal' flag, see below. up/down is determined by the parent window's 'horizontal' flag,
A minibuffer window has the frame's root window pointed by 'prev'. */ 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 next;
Lisp_Object prev; 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; Lisp_Object parent;
/* The normal size of the window. These are fractions, but we do /* The "normal" size of the window. These are fractions, but we
not use C doubles to avoid creating new Lisp_Float objects while do not use C doubles to avoid creating new Lisp_Float objects
interfacing Lisp in Fwindow_normal_size. */ while interfacing Lisp in Fwindow_normal_size. */
Lisp_Object normal_lines; Lisp_Object normal_lines;
Lisp_Object normal_cols; Lisp_Object normal_cols;
/* New sizes of the window. Note that Lisp code may set new_normal /* The new sizes of the window as proposed by the window resizing
to something beyond an integer, so C int can't be used here. */ 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_total;
Lisp_Object new_normal; Lisp_Object new_normal;
Lisp_Object new_pixel; Lisp_Object new_pixel;
/* For a leaf window: a buffer; for an internal window: a window; /* For a leaf window or a tooltip window this is the buffer shown
for a pseudo-window (such as menu bar or tool bar): nil. It is in the window; for a combination window this is the first of
a buffer for a minibuffer window as well. */ 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; Lisp_Object contents;
/* A marker pointing to where in the text to start displaying. /* 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, /* The two Lisp_Object fields below are marked in a special way,
which is why they're placed after `current_matrix'. */ 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. */ buffers previously shown in this window. */
Lisp_Object prev_buffers; Lisp_Object prev_buffers;
/* List of buffers re-shown in this window. */ /* List of buffers re-shown in this window. */