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
Show stats Download patch file Download diff file Expand all files Collapse all files

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.
@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.

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
/* 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.
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 contents field and markers in its start
and pointm fields. Non-leaf windows have nil in the latter two fields.
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.
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
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.
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.
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.
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.
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.
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 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.
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. */
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. */