-This is Info file ../info/internals.info, produced by Makeinfo version
-1.68 from the input file internals/internals.texi.
+This is ../info/internals.info, produced by makeinfo version 4.0b from
+internals/internals.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
-* Internals: (internals). XEmacs Internals Manual.
+* Internals: (internals). XEmacs Internals Manual.
END-INFO-DIR-ENTRY
Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun
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
===========================
information. The second thing we can do is be smart about invalidating
the cache.
- TODO - Be smart about invalidating the cache. Potential places:
+ TODO--Be smart about invalidating the cache. Potential places:
* Insertions at end-of-line which don't cause line-wraps do not
alter the starting positions of any display lines. These types of
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
=======================
An extent-info structure consists of a list of the buffer or string's
extents and a "stack of extents" that lists all of the extents over a
particular position. The stack-of-extents info is used for
-optimization purposes - it basically caches some info that might be
+optimization purposes--it basically caches some info that might be
expensive to compute. Certain otherwise hard computations are easy
given the stack of extents over a particular position, and if the stack
of extents over a nearby position is known (because it was calculated
A list of extents is maintained as a double gap array: one gap array
is ordered by start index (the "display order") and the other is
ordered by end index (the "e-order"). Note that positions in an extent
-list should logically be conceived of as referring *to* a particular
+list should logically be conceived of as referring _to_ a particular
extent (as is the norm in programs) rather than sitting between two
extents. Note also that callers of these functions should not be aware
of the fact that the extent list is implemented as an array, except for
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
range; this is equivalent to treating a point P as the range [P,
P].
- * In the case of an *extent* overlapping a point or range, the extent
+ * In the case of an _extent_ overlapping a point or range, the extent
is normally treated as having closed endpoints. This applies
consistently in the discussion of stacks of extents and such below.
Note that this definition of overlap is not necessarily consistent
An extent fragment is a structure that holds data about the run that
contains a particular buffer position (if the buffer position is at the
-junction of two runs, the run after the position is used) - the
+junction of two runs, the run after the position is used)--the
beginning and end of the run, a list of all of the extents in that run,
the "merged face" that results from merging all of the faces
corresponding to those extents, the begin and end glyphs at the
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
called. Instantiation causes an image-instance to be created and
-cached. This cache is on a device basis for all glyphs except
-glyph-widgets, and on a window basis for glyph widgets. The caching is
-done by `image_instantiate' and is necessary because it is generally
-possible to display an image-instance in multiple domains. For instance
-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
+cached. This cache is on a per-device basis for all glyphs except
+widget-glyphs, and on a per-window basis for widgets-glyphs. The
+caching is done by `image_instantiate' and is necessary because it is
+generally possible to display an image-instance in multiple domains.
+For instance 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 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 MS-WIndows Environment
+Glyph Instantiation
+===================
+
+ Glyph instantiation is a hairy topic and requires some explanation.
+The guts of glyph instantiation is contained within
+`image_instantiate'. A glyph contains an image which is a specifier.
+When a glyph function - for instance `Fglyph_height' - asks for a
+property of the glyph that can only be determined from its instantiated
+state, then the glyph image is instantiated and an image instance
+created. The instantiation process is governed by the specifier code
+and goes through a series of steps:
+
+ * Validation. Instantiation of image instances happens dynamically -
+ often within the guts of redisplay. Thus it is often not feasible
+ to catch instantiator errors at instantiation time. Instead the
+ instantiator is validated at the time it is added to the image
+ specifier. This function is defined by `image_validate' and at a
+ simple level validates keyword value pairs.
+
+ * Duplication. The specifier code by default takes a copy of the
+ instantiator. This is reasonable for most specifiers but in the
+ case of widget-glyphs can be problematic, since some of the
+ properties in the instantiator - for instance callbacks - could
+ cause infinite recursion in the copying process. Thus the image
+ code defines a function - `image_copy_instantiator' - which will
+ selectively copy values. This is controlled by the way that a
+ keyword is defined either using `IIFORMAT_VALID_KEYWORD' or
+ `IIFORMAT_VALID_NONCOPY_KEYWORD'. Note that the image caching and
+ redisplay code relies on instantiator copying to ensure that
+ current and new instantiators are actually different rather than
+ referring to the same thing.
+
+ * Normalization. Once the instantiator has been copied it must be
+ converted into a form that is viable at instantiation time. This
+ can involve no changes at all, but typically involves things like
+ converting file names to the actual data. This function is defined
+ by `image_going_to_add' and `normalize_image_instantiator'.
+
+ * Instantiation. When an image instance is actually required for
+ display it is instantiated using `image_instantiate'. This
+ involves calling instantiate methods that are specific to the type
+ of image being instantiated.
+
+ The final instantiation phase also involves a number of steps. In
+order to understand these we need to describe a number of concepts.
+
+ An image is instantiated in a "domain", where a domain can be any
+one of a device, frame, window or image-instance. The domain gives the
+image-instance context and identity and properties that affect the
+appearance of the image-instance may be different for the same glyph
+instantiated in different domains. An example is the face used to
+display the image-instance.
+
+ Although an image is instantiated in a particular domain the
+instantiation domain is not necessarily the domain in which the
+image-instance is cached. For example a pixmap can be instantiated in a
+window be actually be cached on a per-device basis. The domain in which
+the image-instance is actually cached is called the "governing-domain".
+A governing-domain is currently either a device or a window.
+Widget-glyphs and text-glyphs have a window as a governing-domain, all
+other image-instances have a device as the governing-domain. The
+governing domain for an image-instance is determined using the
+governing_domain image-instance method.
+
+Widget-Glyphs
+=============
+
+Widget-Glyphs in the MS-Windows Environment
===========================================
To Do
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.
+ 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.
Lwlib is extremely poorly documented and quite hairy so here is my
understanding of what goes on.
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
+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
+Unfortunately this also has hairy properties 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.
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: Index, Prev: Interface to X Windows, Up: Top
+File: internals.info, Node: Lucid Widget Library, Up: Interface to the X Window System
-Index
-*****
+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:
-* Amdahl Corporation: XEmacs.
-* Andreessen, Marc: XEmacs.
-* asynchronous subprocesses: Modules for Interfacing with the Operating System.
-* Baur, Steve: XEmacs.
-* Benson, Eric: Lucid Emacs.
-* bridge, playing: XEmacs From the Outside.
-* Buchholz, Martin: XEmacs.
-* Bufbyte: Character-Related Data Types.
-* Bufpos: Character-Related Data Types.
-* Bytecount: Character-Related Data Types.
-* bytecount_to_charcount: Working With Character and Byte Positions.
-* Bytind: Character-Related Data Types.
-* C vs. Lisp: The Lisp Language.
-* caller-protects (GCPRO rule): Writing Lisp Primitives.
-* case table: Modules for Other Aspects of the Lisp Interpreter and Object System.
-* Charcount: Character-Related Data Types.
-* charcount_to_bytecount: Working With Character and Byte Positions.
-* charptr_emchar: Working With Character and Byte Positions.
-* charptr_n_addr: Working With Character and Byte Positions.
-* closer: Lstream Methods.
-* closure: The XEmacs Object System (Abstractly Speaking).
-* Coding for Mule: Coding for Mule.
-* Common Lisp: The Lisp Language.
-* compact_string_chars: compact_string_chars.
-* conservative garbage collection: GCPROing.
-* copy-on-write: General Coding Rules.
-* critical redisplay sections: Critical Redisplay Sections.
-* DEC_CHARPTR: Working With Character and Byte Positions.
-* Devin, Matthieu: Lucid Emacs.
-* display order of extents: Mathematics of Extent Ordering.
-* dynamic array: Low-Level Modules.
-* dynamic scoping: The Lisp Language.
-* dynamic types: The Lisp Language.
-* Emchar: Character-Related Data Types.
-* Energize: Lucid Emacs.
-* Epoch <1>: XEmacs.
-* Epoch: Lucid Emacs.
-* Extbyte: Character-Related Data Types.
-* Extcount: Character-Related Data Types.
-* extent fragment: Extent Fragments.
-* extent mathematics: Mathematics of Extent Ordering.
-* extent ordering: Mathematics of Extent Ordering.
-* extents, display order: Mathematics of Extent Ordering.
-* 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.
-* garbage collection: Garbage Collection.
-* garbage collection protection: Writing Lisp Primitives.
-* garbage collection step by step: Garbage Collection - Step by Step.
-* garbage collection, conservative: GCPROing.
-* garbage collection, invocation: Invocation.
-* garbage_collect_1: garbage_collect_1.
-* gc_sweep: gc_sweep.
-* GNU Emacs 19: GNU Emacs 19.
-* GNU Emacs 20: GNU Emacs 20.
-* Gosling, James <1>: The Lisp Language.
-* Gosling, James: Through Version 18.
-* Great Usenet Renaming: Through Version 18.
-* Hackers (Steven Levy): A History of Emacs.
-* hierarchy of windows: Window Hierarchy.
-* history of Emacs: A History of Emacs.
-* Illinois, University of: XEmacs.
-* INC_CHARPTR: Working With Character and Byte Positions.
-* interactive: Modules for Standard Editing Operations.
-* interning: The XEmacs Object System (Abstractly Speaking).
-* ITS (Incompatible Timesharing System): A History of Emacs.
-* Java: The Lisp Language.
-* Java vs. Lisp: The Lisp Language.
-* Jones, Kyle: XEmacs.
-* Kaplan, Simon: XEmacs.
-* Levy, Steven: A History of Emacs.
-* line start cache: Line Start Cache.
-* Lisp vs. C: The Lisp Language.
-* Lisp vs. Java: The Lisp Language.
-* lstream: Modules for Interfacing with the File System.
-* Lstream_close: Lstream Functions.
-* Lstream_fgetc: Lstream Functions.
-* Lstream_flush: Lstream Functions.
-* Lstream_fputc: Lstream Functions.
-* Lstream_fungetc: Lstream Functions.
-* Lstream_getc: Lstream Functions.
-* Lstream_new: Lstream Functions.
-* Lstream_putc: Lstream Functions.
-* Lstream_read: Lstream Functions.
-* Lstream_reopen: Lstream Functions.
-* Lstream_rewind: Lstream Functions.
-* Lstream_set_buffering: Lstream Functions.
-* Lstream_ungetc: Lstream Functions.
-* Lstream_unread: Lstream Functions.
-* Lstream_write: Lstream Functions.
-* Lucid Emacs: Lucid Emacs.
-* Lucid Inc.: Lucid Emacs.
-* mark and sweep: Garbage Collection.
-* mark method <1>: lrecords.
-* mark method: Modules for Other Aspects of the Lisp Interpreter and Object System.
-* mark_object: mark_object.
-* marker: Lstream Methods.
-* mathematics of extents: Mathematics of Extent Ordering.
-* MAX_EMCHAR_LEN: Working With Character and Byte Positions.
-* merging attempts: XEmacs.
-* MIT: A History of Emacs.
-* Mlynarik, Richard: GNU Emacs 19.
-* MULE merged XEmacs appears: XEmacs.
-* NAS: Modules for Interfacing with the Operating System.
-* native sound: Modules for Interfacing with the Operating System.
-* network connections: Modules for Interfacing with the Operating System.
-* network sound: Modules for Interfacing with the Operating System.
-* Niksic, Hrvoje: XEmacs.
-* pane: Modules for the Basic Displayable Lisp Objects.
-* 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.
-* rewinder: Lstream Methods.
-* RMS: A History of Emacs.
-* scanner: Modules for Other Aspects of the Lisp Interpreter and Object System.
-* scoping, dynamic: The Lisp Language.
-* seekable_p: Lstream Methods.
-* selections: Modules for Interfacing with X Windows.
-* set_charptr_emchar: Working With Character and Byte Positions.
-* Sexton, Harlan: Lucid Emacs.
-* sound, native: Modules for Interfacing with the Operating System.
-* sound, network: Modules for Interfacing with the Operating System.
-* SPARCWorks: XEmacs.
-* Stallman, Richard: A History of Emacs.
-* subprocesses, asynchronous: Modules for Interfacing with the Operating System.
-* subprocesses, synchronous: Modules for Interfacing with the Operating System.
-* Sun Microsystems: XEmacs.
-* sweep_bit_vectors_1: sweep_bit_vectors_1.
-* sweep_lcrecords_1: sweep_lcrecords_1.
-* sweep_strings: sweep_strings.
-* synchronous subprocesses: Modules for Interfacing with the Operating System.
-* taxes, doing: XEmacs From the Outside.
-* TECO: A History of Emacs.
-* temporary objects: The XEmacs Object System (Abstractly Speaking).
-* Thompson, Chuck: XEmacs.
-* types, dynamic: The Lisp Language.
-* University of Illinois: XEmacs.
-* Win-Emacs: XEmacs.
-* window (in Emacs): Modules for the Basic Displayable Lisp Objects.
-* window hierarchy: Window Hierarchy.
-* window point internals: The Window Object.
-* Wing, Ben: XEmacs.
-* writer: Lstream Methods.
-* XEmacs: XEmacs.
-* XEmacs goes it alone: XEmacs.
-* Zawinski, Jamie: Lucid Emacs.
+* 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
+------------
projects / chise / xemacs-chise.git- / blobdiff