-This is ../info/internals.info, produced by makeinfo version 4.0 from
+This is ../info/internals.info, produced by makeinfo version 4.0b from
internals/internals.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
+File: internals.info, Node: Window Hierarchy, Next: The Window Object, Prev: Point, Up: Consoles; Devices; Frames; Windows
+
+Window Hierarchy
+================
+
+ If a frame contains multiple windows (panes), they are always created
+by splitting an existing window along the horizontal or vertical axis.
+Terminology is a bit confusing here: to "split a window horizontally"
+means to create two side-by-side windows, i.e. to make a _vertical_ cut
+in a window. Likewise, to "split a window vertically" means to create
+two windows, one above the other, by making a _horizontal_ cut.
+
+ If you split a window and then split again along the same axis, you
+will end up with a number of panes all arranged along the same axis.
+The precise way in which the splits were made should not be important,
+and this is reflected internally. Internally, all windows are arranged
+in a tree, consisting of two types of windows, "combination" windows
+(which have children, and are covered completely by those children) and
+"leaf" windows, which have no children and are visible. Every
+combination window has two or more children, all arranged along the same
+axis. There are (logically) two subtypes of windows, depending on
+whether their children are horizontally or vertically arrayed. There is
+always one root window, which is either a leaf window (if the frame
+contains only one window) or a combination window (if the frame contains
+more than one window). In the latter case, the root window will have
+two or more children, either horizontally or vertically arrayed, and
+each of those children will be either a leaf window or another
+combination window.
+
+ Here are some rules:
+
+ 1. Horizontal combination windows can never have children that are
+ horizontal combination windows; same for vertical.
+
+ 2. Only leaf windows can be split (obviously) and this splitting does
+ one of two things: (a) turns the leaf window into a combination
+ window and creates two new leaf children, or (b) turns the leaf
+ window into one of the two new leaves and creates the other leaf.
+ Rule (1) dictates which of these two outcomes happens.
+
+ 3. Every combination window must have at least two children.
+
+ 4. Leaf windows can never become combination windows. They can be
+ deleted, however. If this results in a violation of (3), the
+ parent combination window also gets deleted.
+
+ 5. All functions that accept windows must be prepared to accept
+ combination windows, and do something sane (e.g. signal an error
+ if so). Combination windows _do_ escape to the Lisp level.
+
+ 6. All windows have three fields governing their contents: these are
+ "hchild" (a list of horizontally-arrayed children), "vchild" (a
+ list of vertically-arrayed children), and "buffer" (the buffer
+ contained in a leaf window). Exactly one of these will be
+ non-`nil'. Remember that "horizontally-arrayed" means
+ "side-by-side" and "vertically-arrayed" means "one above the
+ other".
+
+ 7. Leaf windows also have markers in their `start' (the first buffer
+ position displayed in the window) and `pointm' (the window's
+ stashed value of `point'--see above) fields, while combination
+ windows have `nil' in these fields.
+
+ 8. The list of children for a window is threaded through the `next'
+ and `prev' fields of each child window.
+
+ 9. *Deleted windows can be undeleted*. This happens as a result of
+ restoring a window configuration, and is unlike frames, displays,
+ and consoles, which, once deleted, can never be restored.
+ Deleting a window does nothing except set a special `dead' bit to
+ 1 and clear out the `next', `prev', `hchild', and `vchild' fields,
+ for GC purposes.
+
+ 10. Most frames actually have two top-level windows--one for the
+ minibuffer and one (the "root") for everything else. The modeline
+ (if present) separates these two. The `next' field of the root
+ points to the minibuffer, and the `prev' field of the minibuffer
+ points to the root. The other `next' and `prev' fields are `nil',
+ and the frame points to both of these windows. Minibuffer-less
+ frames have no minibuffer window, and the `next' and `prev' of the
+ root window are `nil'. Minibuffer-only frames have no root
+ window, and the `next' of the minibuffer window is `nil' but the
+ `prev' points to itself. (#### This is an artifact that should be
+ fixed.)
+
+\1f
+File: internals.info, Node: The Window Object, Prev: Window Hierarchy, Up: Consoles; Devices; Frames; Windows
+
+The Window Object
+=================
+
+ Windows have the following accessible fields:
+
+`frame'
+ The frame that this window is on.
+
+`mini_p'
+ Non-`nil' if this window is a minibuffer window.
+
+`buffer'
+ The buffer that the window is displaying. This may change often
+ during the life of the window.
+
+`dedicated'
+ Non-`nil' if this window is dedicated to its buffer.
+
+`pointm'
+ 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.
+
+`start'
+ The position in the buffer that is the first character to be
+ displayed in the window.
+
+`force_start'
+ If this flag is non-`nil', it says that the window has been
+ scrolled explicitly by the Lisp program. This affects what the
+ next redisplay does if point is off the screen: instead of
+ scrolling the window to show the text around point, it moves point
+ to a location that is on the screen.
+
+`last_modified'
+ The `modified' field of the window's buffer, as of the last time a
+ redisplay completed in this window.
+
+`last_point'
+ The buffer's value of point, as of the last time a redisplay
+ completed in this window.
+
+`left'
+ This is the left-hand edge of the window, measured in columns.
+ (The leftmost column on the screen is column 0.)
+
+`top'
+ This is the top edge of the window, measured in lines. (The top
+ line on the screen is line 0.)
+
+`height'
+ The height of the window, measured in lines.
+
+`width'
+ The width of the window, measured in columns.
+
+`next'
+ This is the window that is the next in the chain of siblings. It
+ is `nil' in a window that is the rightmost or bottommost of a
+ group of siblings.
+
+`prev'
+ This is the window that is the previous in the chain of siblings.
+ It is `nil' in a window that is the leftmost or topmost of a group
+ of siblings.
+
+`parent'
+ Internally, XEmacs 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.
+
+ 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 leaves of the tree, which actually display buffers.
+
+`hscroll'
+ This is the number of columns that the display in the window is
+ scrolled horizontally to the left. Normally, this is 0.
+
+`use_time'
+ This is the last time that the window was selected. The function
+ `get-lru-window' uses this field.
+
+`display_table'
+ The window's display table, or `nil' if none is specified for it.
+
+`update_mode_line'
+ Non-`nil' means this window's mode line needs to be updated.
+
+`base_line_number'
+ The line number of a certain position in the buffer, or `nil'.
+ This is used for displaying the line number of point in the mode
+ line.
+
+`base_line_pos'
+ The position in the buffer for which the line number is known, or
+ `nil' meaning none is known.
+
+`region_showing'
+ If the region (or part of it) is highlighted in this window, this
+ field holds the mark position that made one end of that region.
+ Otherwise, this field is `nil'.
+
+\1f
File: internals.info, Node: The Redisplay Mechanism, Next: Extents, Prev: Consoles; Devices; Frames; Windows, Up: Top
The Redisplay Mechanism
* Redisplay Piece by Piece::
\1f
-File: internals.info, Node: Critical Redisplay Sections, Next: Line Start Cache, Up: The Redisplay Mechanism
+File: internals.info, Node: Critical Redisplay Sections, Next: Line Start Cache, Prev: The Redisplay Mechanism, Up: The Redisplay Mechanism
Critical Redisplay Sections
===========================
3. Output changes Implemented by `redisplay-output.c',
`redisplay-x.c', `redisplay-msw.c' and `redisplay-tty.c'
- Steps 1 and 2 are device-independant and relatively complex. Step 3
+ Steps 1 and 2 are device-independent and relatively complex. Step 3
is mostly device-dependent.
Determining the desired display
`display_line''s are held by each window representing the current
display and the desired display.
- The `display_line' structures are tighly tied to buffers which
+ The `display_line' structures are tightly tied to buffers which
presents a problem for redisplay as this connection is bogus for the
modeline. Hence the `display_line' generation routines are duplicated
for generating the modeline. This means that the modeline display code
* Extent Ordering:: How extents are ordered internally.
* Format of the Extent Info:: The extent information in a buffer or string.
* Zero-Length Extents:: A weird special case.
-* Mathematics of Extent Ordering:: A rigorous foundation.
+* Mathematics of Extent Ordering:: A rigorous foundation.
* Extent Fragments:: Cached information useful for redisplay.
\1f
-File: internals.info, Node: Introduction to Extents, Next: Extent Ordering, Up: Extents
+File: internals.info, Node: Introduction to Extents, Next: Extent Ordering, Prev: Extents, Up: Extents
Introduction to Extents
=======================
Extents can be zero-length, and will end up that way if their
endpoints are explicitly set that way or if their detachable property
-is nil and all the text in the extent is deleted. (The exception is
+is `nil' and all the text in the extent is deleted. (The exception is
open-open zero-length extents, which are barred from existing because
there is no sensible way to define their properties. Deletion of the
text in an open-open extent causes it to be converted into a closed-open
Glyphs are graphical elements that can be displayed in XEmacs
buffers or gutters. We use the term graphical element here in the
-broadest possible sense since glyphs can be as mundane as text to as
+broadest possible sense since glyphs can be as mundane as text or as
arcane as a native tab widget.
In XEmacs, glyphs represent the uninstantiated state of graphical
elements, i.e. they hold all the information necessary to produce an
-image on-screen but the image does not exist at this stage.
+image on-screen but the image need not exist at this stage, and multiple
+screen images can be instantiated from a single glyph.
Glyphs are lazily instantiated by calling one of the glyph
functions. This usually occurs within redisplay when `Fglyph_height' is
if we create a Pixmap, we can actually display this on multiple windows
- even though we only need a single Pixmap instance to do this. If
caching wasn't done then it would be necessary to create
-image-instances for every displayable occurrance of a glyph - and every
+image-instances for every displayable occurrence of a glyph - and every
usage - and this would be extremely memory and cpu intensive.
Widget-glyphs (a.k.a native widgets) are not cached in this way.
This is because widget-glyph image-instances on screen are toolkit
windows, and thus cannot be reused in multiple XEmacs domains. Thus
-widget-glyphs are cached on a window basis.
+widget-glyphs are cached on an XEmacs window basis.
Any action on a glyph first consults the cache before actually
instantiating a widget.
Widget-Glyphs in the X Environment
==================================
- Widget-glyphs under X make heavy use of lwlib for manipulating the
-native toolkit objects. This is primarily so that different toolkits can
-be supported for widget-glyphs, just as they are supported for features
-such as menubars etc.
-
- Lwlib is extremely poorly documented and quite hairy so here is my
-understanding of what goes on.
-
- Lwlib maintains a set of widget_instances which mirror the
-hierarchical state of Xt widgets. I think this is so that widgets can
-be updated and manipulated generically by the lwlib library. For
-instance update_one_widget_instance can cope with multiple types of
-widget and multiple types of toolkit. Each element in the widget
-hierarchy is updated from its corresponding widget_instance by walking
-the widget_instance tree recursively.
-
- This has desirable properties such as lw_modify_all_widgets which is
-called from glyphs-x.c and updates all the properties of a widget
-without having to know what the widget is or what toolkit it is from.
-Unfortunately this also has hairy properrties such as making the lwlib
-code quite complex. And of course lwlib has to know at some level what
-the widget is and how to set its properties.
+ Widget-glyphs under X make heavy use of lwlib (*note Lucid Widget
+Library::) for manipulating the native toolkit objects. This is
+primarily so that different toolkits can be supported for
+widget-glyphs, just as they are supported for features such as menubars
+etc.
\1f
File: internals.info, Node: Specifiers, Next: Menus, Prev: Glyphs, Up: Top
description.
\1f
-File: internals.info, Node: Subprocesses, Next: Interface to X Windows, Prev: Menus, Up: Top
+File: internals.info, Node: Subprocesses, Next: Interface to the X Window System, Prev: Menus, Up: Top
Subprocesses
************
it is using pipes.
\1f
-File: internals.info, Node: Interface to X Windows, Next: Index, Prev: Subprocesses, Up: Top
+File: internals.info, Node: Interface to the X Window System, Next: Index, Prev: Subprocesses, Up: Top
-Interface to X Windows
-**********************
+Interface to the X Window System
+********************************
- Not yet documented.
+ Mostly undocumented.
+
+* Menu:
+
+* Lucid Widget Library:: An interface to various widget sets.
+
+\1f
+File: internals.info, Node: Lucid Widget Library, Up: Interface to the X Window System
+
+Lucid Widget Library
+====================
+
+ Lwlib is extremely poorly documented and quite hairy. The author(s)
+blame that on X, Xt, and Motif, with some justice, but also sufficient
+hypocrisy to avoid drawing the obvious conclusion about their own work.
+
+ The Lucid Widget Library is composed of two more or less independent
+pieces. The first, as the name suggests, is a set of widgets. These
+widgets are intended to resemble and improve on widgets provided in the
+Motif toolkit but not in the Athena widgets, including menubars and
+scrollbars. Recent additions by Andy Piper integrate some "modern"
+widgets by Edward Falk, including checkboxes, radio buttons, progress
+gauges, and index tab controls (aka notebooks).
+
+ The second piece of the Lucid widget library is a generic interface
+to several toolkits for X (including Xt, the Athena widget set, and
+Motif, as well as the Lucid widgets themselves) so that core XEmacs
+code need not know which widget set has been used to build the
+graphical user interface.
+
+* Menu:
+
+* Generic Widget Interface:: The lwlib generic widget interface.
+* Scrollbars::
+* Menubars::
+* Checkboxes and Radio Buttons::
+* Progress Bars::
+* Tab Controls::
+
+\1f
+File: internals.info, Node: Generic Widget Interface, Next: Scrollbars, Up: Lucid Widget Library
+
+Generic Widget Interface
+------------------------
+
+ In general in any toolkit a widget may be a composite object. In Xt,
+all widgets have an X window that they manage, but typically a complex
+widget will have widget children, each of which manages a subwindow of
+the parent widget's X window. These children may themselves be
+composite widgets. Thus a widget is actually a tree or hierarchy of
+widgets.
+
+ For each toolkit widget, lwlib maintains a tree of `widget_values'
+which mirror the hierarchical state of Xt widgets (including Motif,
+Athena, 3D Athena, and Falk's widget sets). Each `widget_value' has
+`contents' member, which points to the head of a linked list of its
+children. The linked list of siblings is chained through the `next'
+member of `widget_value'.
+
+ +-----------+
+ | composite |
+ +-----------+
+ |
+ | contents
+ V
+ +-------+ next +-------+ next +-------+
+ | child |----->| child |----->| child |
+ +-------+ +-------+ +-------+
+ |
+ | contents
+ V
+ +-------------+ next +-------------+
+ | grand child |----->| grand child |
+ +-------------+ +-------------+
+
+ The `widget_value' hierarchy of a composite widget with two simple
+ children and one composite child.
+
+ The `widget_instance' structure maintains the inverse view of the
+tree. As for the `widget_value', siblings are chained through the
+`next' member. However, rather than naming children, the
+`widget_instance' tree links to parents.
+
+ +-----------+
+ | composite |
+ +-----------+
+ A
+ | parent
+ |
+ +-------+ next +-------+ next +-------+
+ | child |----->| child |----->| child |
+ +-------+ +-------+ +-------+
+ A
+ | parent
+ |
+ +-------------+ next +-------------+
+ | grand child |----->| grand child |
+ +-------------+ +-------------+
+
+ The `widget_value' hierarchy of a composite widget with two simple
+ children and one composite child.
+
+ This permits widgets derived from different toolkits to be updated
+and manipulated generically by the lwlib library. For instance
+`update_one_widget_instance' can cope with multiple types of widget and
+multiple types of toolkit. Each element in the widget hierarchy is
+updated from its corresponding `widget_value' by walking the
+`widget_value' tree. This has desirable properties. For example,
+`lw_modify_all_widgets' is called from `glyphs-x.c' and updates all the
+properties of a widget without having to know what the widget is or
+what toolkit it is from. Unfortunately this also has its hairy
+properties; the lwlib code quite complex. And of course lwlib has to
+know at some level what the widget is and how to set its properties.
+
+ The `widget_instance' structure also contains a pointer to the root
+of its tree. Widget instances are further confi
+
+\1f
+File: internals.info, Node: Scrollbars, Next: Menubars, Prev: Generic Widget Interface, Up: Lucid Widget Library
+
+Scrollbars
+----------
+
+\1f
+File: internals.info, Node: Menubars, Next: Checkboxes and Radio Buttons, Prev: Scrollbars, Up: Lucid Widget Library
+
+Menubars
+--------
+
+\1f
+File: internals.info, Node: Checkboxes and Radio Buttons, Next: Progress Bars, Prev: Menubars, Up: Lucid Widget Library
+
+Checkboxes and Radio Buttons
+----------------------------
+
+\1f
+File: internals.info, Node: Progress Bars, Next: Tab Controls, Prev: Checkboxes and Radio Buttons, Up: Lucid Widget Library
+
+Progress Bars
+-------------
+
+\1f
+File: internals.info, Node: Tab Controls, Prev: Progress Bars, Up: Lucid Widget Library
+
+Tab Controls
+------------
\1f
-File: internals.info, Node: Index, Prev: Interface to X Windows, Up: Top
+File: internals.info, Node: Index, Prev: Interface to the X Window System, Up: Top
Index
*****
* external widget: Modules for Interfacing with X Windows.
* flusher: Lstream Methods.
* Free Software Foundation: A History of Emacs.
-* frob block: Introduction to Allocation.
* FSF: A History of Emacs.
* FSF Emacs <1>: GNU Emacs 20.
* FSF Emacs: GNU Emacs 19.
* permanent objects: The XEmacs Object System (Abstractly Speaking).
* pi, calculating: XEmacs From the Outside.
* pseudo_closer: Lstream Methods.
-* pure space: Basic Lisp Modules.
* read syntax: The XEmacs Object System (Abstractly Speaking).
* read-eval-print: XEmacs From the Outside.
* reader: Lstream Methods.
-* record type: How Lisp Objects Are Represented in C.
* Redisplay Piece by Piece: Redisplay Piece by Piece.
* relocating allocator: Low-Level Modules.
* rename to XEmacs: XEmacs.
projects / chise / xemacs-chise.git- / blobdiff