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
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
@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.
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.
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
{
/* 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.
/* 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. */
projects / emacs.git / commitdiff