masscollaborationlabs/emacs
2
0
Fork 0
mirror of https://github.com/masscollaborationlabs/emacs.git synced 2025-07-17 09:25:46 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update the docs of object internals

Browse source 
* doc/lispref/internals.texi (Buffer Internals)
(Window Internals, Process Internals): Update the descriptions
of Lisp objects.
This commit is contained in:
Eli Zaretskii 2018-11-20 20:45:07 +02:00
parent d667318a7f
commit 0d59ae3f49
1 changed files with 88 additions and 60 deletions
Download patch file Download diff file Expand all files Collapse all files

148
doc/lispref/internals.texi
View file

@ -1746,7 +1746,7 @@ and form the set of subtypes of @code{Lisp_Misc}.
Below there is a description of a few subtypes of @code{Lisp_Vectorlike}. Below there is a description of a few subtypes of @code{Lisp_Vectorlike}.
Buffer object represents the text to display and edit. Window is the part Buffer object represents the text to display and edit. Window is the part
of display structure which shows the buffer or used as a container to of display structure which shows the buffer or is used as a container to
recursively place other windows on the same frame. (Do not confuse Emacs Lisp recursively place other windows on the same frame. (Do not confuse Emacs Lisp
window object with the window as an entity managed by the user interface window object with the window as an entity managed by the user interface
system like X; in Emacs terminology, the latter is called frame.) Finally, system like X; in Emacs terminology, the latter is called frame.) Finally,
@ -1773,7 +1773,8 @@ Here are some of the fields in @code{struct buffer_text}:
@table @code @table @code
@item beg @item beg
The address of the buffer contents. The address of the buffer contents. The buffer contents is a linear C
array of @code{char}, with the gap somewhere in its midst.
@item gpt @item gpt
@itemx gpt_byte @itemx gpt_byte
@ -1797,8 +1798,8 @@ buffer-modification event, and is never otherwise changed;
@code{save_modiff} contains the value of @code{modiff} the last time @code{save_modiff} contains the value of @code{modiff} the last time
the buffer was visited or saved; @code{chars_modiff} counts only the buffer was visited or saved; @code{chars_modiff} counts only
modifications to the characters in the buffer, ignoring all other modifications to the characters in the buffer, ignoring all other
kinds of changes; and @code{overlay_modiff} counts only modifications kinds of changes (such as text properties); and @code{overlay_modiff}
to the overlays. counts only modifications to the buffer's overlays.
@item beg_unchanged @item beg_unchanged
@itemx end_unchanged @itemx end_unchanged
@ -1906,13 +1907,22 @@ position.
@item name @item name
A Lisp string that names the buffer. It is guaranteed to be unique. A Lisp string that names the buffer. It is guaranteed to be unique.
@xref{Buffer Names}. @xref{Buffer Names}. This and the following fields have their names
in the C struct definition end in a @code{_} to indicate that they
should not be accessed directly, but via the @code{BVAR} macro, like
this:
@example
Lisp_Object buf_name = BVAR (buffer, name);
@end example
@item save_length @item save_length
The length of the file this buffer is visiting, when last read or The length of the file this buffer is visiting, when last read or
saved. This and other fields concerned with saving are not kept in saved. It can have 2 special values: @minus{}1 means auto-saving was
the @code{buffer_text} structure because indirect buffers are never turned off in this buffer, and @minus{}2 means don't turn off
saved. auto-saving if buffer text shrinks a lot. This and other fields
concerned with saving are not kept in the @code{buffer_text} structure
because indirect buffers are never saved.
@item directory @item directory
The directory for expanding relative file names. This is the value of The directory for expanding relative file names. This is the value of
@ -2036,37 +2046,29 @@ if that window no longer displays this buffer.
@table @code @table @code
@item frame @item frame
The frame that this window is on. The frame that this window is on, as a Lisp object.
@item mini_p @item mini
Non-@code{nil} if this window is a minibuffer window. Non-zero if this window is a minibuffer window.
@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 has
a parent window whose area includes all the siblings. This field points a parent window whose area includes all the siblings. This field points
to a window's parent. to a window's parent, as a Lisp object.
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 usually have
no access to the parent windows; they operate on the windows at the no access to the 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.
@c FIXME: These two slots and the 'buffer' slot below were replaced
@c with a single slot 'contents' on 2013-03-28. --xfq
@item hchild
@itemx vchild
These fields contain the window's leftmost child and its topmost child
respectively. @code{hchild} is used if the window is subdivided
horizontally by child windows, and @code{vchild} if it is subdivided
vertically. In a live window, only one of @code{hchild}, @code{vchild},
and @code{buffer} (q.v.@:) is non-@code{nil}.
@item next @item next
@itemx prev @itemx prev
The next sibling and previous sibling of this window. @code{next} is 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{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 @code{prev} is @code{nil} if it is the left-most or top-most in its
group. 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.
@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
@ -2082,29 +2084,35 @@ The width and height of the window, measured in columns and lines
respectively. The width includes the scroll bar and fringes, and/or respectively. The width includes the scroll bar and fringes, and/or
the separator line on the right of the window (if any). the separator line on the right of the window (if any).
@item buffer @item contents
The buffer that the window is displaying. 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 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
character displayed in the window. character (in the logical order, @pxref{Bidirectional Display})
displayed in the window.
@item pointm @item pointm
@cindex window point internals @cindex window point internals
This is the value of point in the current buffer when this window is This is the value of point in the current buffer when this window is
selected; when it is not selected, it retains its previous value. selected; when it is not selected, it retains its previous value.
@item old_pointm
The value of @code{pointm} at the last redisplay time.
@item force_start @item force_start
If this flag is non-@code{nil}, it says that the window has been If this flag is non-@code{nil}, it says that the window has been
scrolled explicitly by the Lisp program. This affects what the next scrolled explicitly by the Lisp program, and the value of the the
redisplay does if point is off the screen: instead of scrolling the window's @code{start} was set for redisplay to honor. This affects
window to show the text around point, it moves point to a location that what the next redisplay does if point is off the screen: instead of
is on the screen. scrolling the window to show the text around point, it moves point to
a location that is on the screen.
@item frozen_window_start_p @item optional_new_start
This field is set temporarily to 1 to indicate to redisplay that This is similar to @code{force_start}, but the next redisplay will
@code{start} of this window should not be changed, even if point only obey it if point stays visible.
gets invisible.
@item start_at_line_beg @item start_at_line_beg
Non-@code{nil} means current value of @code{start} was the beginning of a line Non-@code{nil} means current value of @code{start} was the beginning of a line
@ -2130,30 +2138,30 @@ The buffer's value of point, as of the last time a redisplay completed
in this window. in this window.
@item last_had_star @item last_had_star
A non-@code{nil} 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
This window's vertical scroll bar. This window's vertical scroll bar, a Lisp object.
@item left_margin_cols @item left_margin_cols
@itemx right_margin_cols @itemx right_margin_cols
The widths of the left and right margins in this window. A value of The widths of the left and right margins in this window. A value of
@code{nil} means no margin. zero means no margin.
@item left_fringe_width @item left_fringe_width
@itemx right_fringe_width @itemx right_fringe_width
The widths of the left and right fringes in this window. A value of The pixel widths of the left and right fringes in this window. A
@code{nil} or @code{t} means use the values of the frame. value of @minus{}1 means use the values of the frame.
@item fringes_outside_margins @item fringes_outside_margins
A non-@code{nil} value means the fringes outside the display margins; A non-zero value means the fringes outside the display margins;
othersize they are between the margin and the text. othersize they are between the margin and the text.
@item window_end_pos @item window_end_pos
This is computed as @code{z} minus the buffer position of the last glyph This is computed as @code{z} minus the buffer position of the last glyph
in the current matrix of the window. The value is only valid if in the current matrix of the window. The value is only valid if
@code{window_end_valid} is not @code{nil}. @code{window_end_valid} is non-zero.
@item window_end_bytepos @item window_end_bytepos
The byte position corresponding to @code{window_end_pos}. The byte position corresponding to @code{window_end_pos}.
@ -2163,16 +2171,17 @@ The window-relative vertical position of the line containing
@code{window_end_pos}. @code{window_end_pos}.
@item window_end_valid @item window_end_valid
This field is set to a non-@code{nil} value if @code{window_end_pos} is truly This field is set to a non-zero value if @code{window_end_pos} and
valid. This is @code{nil} if nontrivial redisplay is pre-empted, since in that @code{window_end_vpos} are truly valid. This is zero if nontrivial
case the display that @code{window_end_pos} was computed for did not get redisplay is pre-empted, since in that case the display that
onto the screen. @code{window_end_pos} was computed for did not get onto the screen.
@item cursor @item cursor
A structure describing where the cursor is in this window. A structure describing where the cursor is in this window.
@item last_cursor @item last_cursor_vpos
The value of @code{cursor} as of the last redisplay that finished. The window-relative vertical position of the line showing the cursor
as of the last redisplay that finished.
@item phys_cursor @item phys_cursor
A structure describing where the cursor of this window physically is. A structure describing where the cursor of this window physically is.
@ -2200,8 +2209,16 @@ the last redisplay.
This is set to 1 during redisplay when this window must be updated. This is set to 1 during redisplay when this window must be updated.
@item hscroll @item hscroll
This is the number of columns that the display in the window is scrolled This is the number of columns that the display in the window is
horizontally to the left. Normally, this is 0. scrolled horizontally to the left. Normally, this is 0. When only
the current line is hscrolled, this describes how much the current
line is scrolled.
@item min_hscroll
Minimum value of @code{hscroll}, set by the user via
@code{set-window-hscroll} (@pxref{Horizontal Scrolling}). When only
the current line is hscrolled, this describes the horizontal scrolling
of lines other than the current one.
@item vscroll @item vscroll
Vertical scroll amount, in pixels. Normally, this is 0. Vertical scroll amount, in pixels. Normally, this is 0.
@ -2213,20 +2230,30 @@ Non-@code{nil} if this window is dedicated to its buffer.
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.
@item update_mode_line @item update_mode_line
Non-@code{nil} means this window's mode line needs to be updated. Non-zero means this window's mode line needs to be updated.
@item mode_line_height
@itemx header_line_height
The height in pixels of the mode line and the header line, or
@minus{}1 if not known.
@item base_line_number @item base_line_number
The line number of a certain position in the buffer, or @code{nil}. The line number of a certain position in the buffer, or zero.
This is used for displaying the line number of point in the mode line. This is used for displaying the line number of point in the mode line.
@item base_line_pos @item base_line_pos
The position in the buffer for which the line number is known, or The position in the buffer for which the line number is known, or
@code{nil} meaning none is known. If it is a buffer, don't display zero meaning none is known. If it is @minus{}1, don't display
the line number as long as the window shows that buffer. the line number as long as the window shows that buffer.
@item column_number_displayed @item column_number_displayed
The column number currently displayed in this window's mode line, or @code{nil} The column number currently displayed in this window's mode line, or
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
@ -2243,7 +2270,7 @@ Glyph matrices describing the current and desired display of this window.
@table @code @table @code
@item name @item name
A string, the name of the process. A Lisp string, the name of the process.
@item command @item command
A list containing the command arguments that were used to start this A list containing the command arguments that were used to start this
@ -2251,10 +2278,10 @@ process. For a network or serial process, it is @code{nil} if the
process is running or @code{t} if the process is stopped. process is running or @code{t} if the process is stopped.
@item filter @item filter
A function used to accept output from the process. A Lisp function used to accept output from the process.
@item sentinel @item sentinel
A function called whenever the state of the process changes. A Lisp function called whenever the state of the process changes.
@item buffer @item buffer
The associated buffer of the process. The associated buffer of the process.
@ -2281,7 +2308,8 @@ does not ask for confirmation about killing the process.
The raw process status, as returned by the @code{wait} system call. The raw process status, as returned by the @code{wait} system call.
@item status @item status
The process status, as @code{process-status} should return it. The process status, as @code{process-status} should return it. This
is a Lisp symbol, a cons cell, or a list.
@item tick @item tick
@itemx update_tick @itemx update_tick
@ -2290,8 +2318,8 @@ needs to be reported, either by running the sentinel or by inserting a
message in the process buffer. message in the process buffer.
@item pty_flag @item pty_flag
Non-@code{nil} if communication with the subprocess uses a pty; Non-zero if communication with the subprocess uses a pty; zero if it
@code{nil} if it uses a pipe. uses a pipe.
@item infd @item infd
The file descriptor for input from the process. The file descriptor for input from the process.