* Specifiers::
* Menus::
* Subprocesses::
-* Interface to X Windows::
+* Interface to the X Window System::
* Index::
@detailmenu
When the Lisp initialization code is done, the C code enters the event
loop, and stays there for the duration of the XEmacs process. The code
-for the event loop is contained in @file{keyboard.c}, and is called
+for the event loop is contained in @file{cmdloop.c}, and is called
@code{Fcommand_loop_1()}. Note that this event loop could very well be
written in Lisp, and in fact a Lisp version exists; but apparently,
doing this makes XEmacs run noticeably slower.
tools means that a greater variety of development tools are available to
the developer.
-Almost every module contains a @code{syms_of_*()} function and a
-@code{vars_of_*()} function. The former declares any Lisp primitives
-you have defined and defines any symbols you will be using. The latter
-declares any global Lisp variables you have added and initializes global
-C variables in the module. For each such function, declare it in
-@file{symsinit.h} and make sure it's called in the appropriate place in
-@file{emacs.c}. @strong{Important}: There are stringent requirements on
-exactly what can go into these functions. See the comment in
-@file{emacs.c}. The reason for this is to avoid obscure unwanted
-interactions during initialization. If you don't follow these rules,
-you'll be sorry! If you want to do anything that isn't allowed, create
-a @code{complex_vars_of_*()} function for it. Doing this is tricky,
-though: You have to make sure your function is called at the right time
-so that all the initialization dependencies work out.
-
Every module includes @file{<config.h>} (angle brackets so that
@samp{--srcdir} works correctly; @file{config.h} may or may not be in
the same directory as the C sources) and @file{lisp.h}. @file{config.h}
@file{config.h} files. Which one will be used if you @samp{#include
"config.h"}?
+Almost every module contains a @code{syms_of_*()} function and a
+@code{vars_of_*()} function. The former declares any Lisp primitives
+you have defined and defines any symbols you will be using. The latter
+declares any global Lisp variables you have added and initializes global
+C variables in the module. @strong{Important}: There are stringent
+requirements on exactly what can go into these functions. See the
+comment in @file{emacs.c}. The reason for this is to avoid obscure
+unwanted interactions during initialization. If you don't follow these
+rules, you'll be sorry! If you want to do anything that isn't allowed,
+create a @code{complex_vars_of_*()} function for it. Doing this is
+tricky, though: you have to make sure your function is called at the
+right time so that all the initialization dependencies work out.
+
+Declare each function of these kinds in @file{symsinit.h}. Make sure
+it's called in the appropriate place in @file{emacs.c}. You never need
+to include @file{symsinit.h} directly, because it is included by
+@file{lisp.h}.
+
@strong{All global and static variables that are to be modifiable must
be declared uninitialized.} This means that you may not use the
``declare with initializer'' form for these variables, such as @code{int
Elisp. There are two sets of macros that iterate over lists.
@code{EXTERNAL_LIST_LOOP_@var{n}} should be used when the list has been
supplied by the user, and cannot be trusted to be acyclic and
-nil-terminated. A @code{malformed-list} or @code{circular-list} error
+@code{nil}-terminated. A @code{malformed-list} or @code{circular-list} error
will be generated if the list being iterated over is not entirely
kosher. @code{LIST_LOOP_@var{n}}, on the other hand, is faster and less
safe, and can be used only on trusted lists.
@example
-crt0.c
+ecrt0.c
lastfile.c
pre-crt0.c
@end example
@example
-prefix-args.c
-@end example
-
-This is actually the source for a small, self-contained program
-used during building.
-
-
-@example
universe.h
@end example
@section Basic Lisp Modules
@example
-emacsfns.h
lisp-disunion.h
lisp-union.h
lisp.h
@example
event-Xt.c
+event-msw.c
event-stream.c
event-tty.c
+events-mod.h
+gpmevent.c
+gpmevent.h
events.c
events.h
@end example
@example
-keyboard.c
+cmdloop.c
@end example
-@file{keyboard.c} contains functions that implement the actual editor
+@file{cmdloop.c} contains functions that implement the actual editor
command loop---i.e. the event loop that cyclically retrieves and
dispatches events. This code is also rather tricky, just like
@file{event-stream.c}.
@section Modules for the Basic Displayable Lisp Objects
@example
-device-ns.h
-device-stream.c
-device-stream.h
+console-msw.c
+console-msw.h
+console-stream.c
+console-stream.h
+console-tty.c
+console-tty.h
+console-x.c
+console-x.h
+console.c
+console.h
+@end example
+
+These modules implement the @dfn{console} Lisp object type. A console
+contains multiple display devices, but only one keyboard and mouse.
+Most of the time, a console will contain exactly one device.
+
+Consoles are the top of a lisp object inclusion hierarchy. Consoles
+contain devices, which contain frames, which contain windows.
+
+
+
+@example
+device-msw.c
device-tty.c
-device-tty.h
device-x.c
-device-x.h
device.c
device.h
@end example
@example
-frame-ns.h
+frame-msw.c
frame-tty.c
frame-x.c
-frame-x.h
frame.c
frame.h
@end example
@example
bitmaps.h
-glyphs-ns.h
+glyphs-eimage.c
+glyphs-msw.c
+glyphs-msw.h
+glyphs-widget.c
glyphs-x.c
glyphs-x.h
glyphs.c
@example
-objects-ns.h
+objects-msw.c
+objects-msw.h
objects-tty.c
objects-tty.h
objects-x.c
@example
+menubar-msw.c
+menubar-msw.h
menubar-x.c
menubar.c
+menubar.h
@end example
@example
+scrollbar-msw.c
+scrollbar-msw.h
scrollbar-x.c
scrollbar-x.h
scrollbar.c
@example
+toolbar-msw.c
toolbar-x.c
toolbar.c
toolbar.h
@end example
These modules decode GIF-format image files, for use with glyphs.
+These files were removed due to Unisys patent infringement concerns.
@example
redisplay-output.c
+redisplay-msw.c
redisplay-tty.c
redisplay-x.c
redisplay.c
Similar to other subsystems in XEmacs, lstreams are separated into
generic functions and a set of methods for the different types of
lstreams. @file{lstream.c} provides implementations of many different
-types of streams; others are provided, e.g., in @file{mule-coding.c}.
+types of streams; others are provided, e.g., in @file{file-coding.c}.
-@example
-msdos.c
-msdos.h
-@end example
-
-These modules are used for MS-DOS support, which does not work in
-XEmacs.
-
-
-
@node Modules for Interfacing with X Windows, Modules for Internationalization, Modules for Interfacing with the Operating System, A Summary of the Various XEmacs Modules
@section Modules for Interfacing with X Windows
@example
-xselect.c
+select-msw.c
+select-x.c
+select.c
+select.h
@end example
@cindex selections
mule-ccl.c
mule-charset.c
mule-charset.h
-mule-coding.c
-mule-coding.h
+file-coding.c
+file-coding.h
mule-mcpath.c
mule-mcpath.h
mule-wnnfns.c
just Asian languages (although they are generally the most complicated
to support). This code is still in beta.
-@file{mule-charset.*} and @file{mule-coding.*} provide the heart of the
+@file{mule-charset.*} and @file{file-coding.*} provide the heart of the
XEmacs MULE support. @file{mule-charset.*} implements the @dfn{charset}
Lisp object type, which encapsulates a character set (an ordered one- or
two-dimensional set of characters, such as US ASCII or JISX0208 Japanese
Kanji).
-@file{mule-coding.*} implements the @dfn{coding-system} Lisp object
+@file{file-coding.*} implements the @dfn{coding-system} Lisp object
type, which encapsulates a method of converting between different
encodings. An encoding is a representation of a stream of characters,
possibly from multiple character sets, using a stream of bytes or words,
@code{setq}, etc., miscellaneous @code{gui_item_...} functions,
everything related to @code{eval} (@code{Feval_buffer}, @code{call0},
...) and inside @code{Fsignal}. The latter is used to handle signals, as
-for example the ones raised by every @code{QUITE}-macro triggered after
+for example the ones raised by every @code{QUIT}-macro triggered after
pressing Ctrl-g.
@node garbage_collect_1, mark_object, Invocation, Garbage Collection - Step by Step
@itemize @bullet
@item
all constant symbols and static variables that are registered via
-@code{staticpro}@ in the array @code{staticvec}.
+@code{staticpro}@ in the dynarr @code{staticpros}.
@xref{Adding Global Lisp Variables}.
@item
all Lisp objects that are created in C functions and that must be
Our next candidates are the other objects that behave quite differently
than everything else: the strings. They consists of two parts, a
-fixed-size portion (@code{struct Lisp_string}) holding the string's
+fixed-size portion (@code{struct Lisp_String}) holding the string's
length, its property list and a pointer to the second part, and the
actual string data, which is stored in string-chars blocks comparable to
frob blocks. In this block, the data is not only freed, but also a
file. To create one of these, copy an existing model and modify as
necessary.
+ @strong{Please note:} If you define an lrecord in an external
+dynamically-loaded module, you must use @code{DECLARE_EXTERNAL_LRECORD},
+@code{DEFINE_EXTERNAL_LRECORD_IMPLEMENTATION}, and
+@code{DEFINE_EXTERNAL_LRECORD_SEQUENCE_IMPLEMENTATION} instead of the
+non-EXTERNAL forms. These macros will dynamically add new type numbers
+to the global enum that records them, whereas the non-EXTERNAL forms
+assume that the programmer has already inserted the correct type numbers
+into the enum's code at compile-time.
+
The various methods in the lrecord implementation structure are:
@enumerate
a function pointer (usually the @code{mark_object()} function), which is
used to mark an object. All Lisp objects that are contained within the
object need to be marked by applying this function to them. The mark
-method should also return a Lisp object, which should be either nil or
+method should also return a Lisp object, which should be either @code{nil} or
an object to mark. (This can be used in lieu of calling
@code{mark_object()} on the object, to reduce the recursion depth, and
consequently should be the most heavily nested sub-object, such as a
@node Dumping phase, Reloading phase, Data descriptions, Dumping
@section Dumping phase
-Dumping is done by calling the function pdump() (in alloc.c) which is
+Dumping is done by calling the function pdump() (in dumper.c) which is
invoked from Fdump_emacs (in emacs.c). This function performs a number
of tasks.
@enumerate
@item
We do not use the mark bit (which does not exist for C structures
-anyway), we use a big hash table instead.
+anyway); we use a big hash table instead.
@item
We do not use the mark function of lrecords but instead rely on the
Lisp_Object members.
@end enumerate
-This is done by @code{pdump_register_object}, which handles Lisp_Object
-variables, and pdump_register_struct which handles C structures, which
-both delegate the description management to pdump_register_sub.
+This is done by @code{pdump_register_object()}, which handles Lisp_Object
+variables, and @code{pdump_register_struct()} which handles C structures,
+which both delegate the description management to @code{pdump_register_sub()}.
The hash table doubles as a map object to pdump_entry_list_elmt (i.e.
allows us to look up a pdump_entry_list_elmt with the object it points
to). Entries are added with @code{pdump_add_entry()} and looked up with
@code{pdump_get_entry()}. There is no need for entry removal. The hash
-value is computed quite basically from the object pointer by
+value is computed quite simply from the object pointer by
@code{pdump_make_hash()}.
The roots for the marking are:
call for protected variables we do not want to dump).
@item
-the @code{pdump_wire}'d variables (@code{staticpro} is equivalent to
-@code{staticpro_nodump()} + @code{pdump_wire()}).
+the variables registered via @code{dump_add_root_object}
+(@code{staticpro()} is equivalent to @code{staticpro_nodump()} +
+@code{dump_add_root_object()}).
@item
-the @code{dumpstruct}'ed variables, which points to C structures.
+the variables registered via @code{dump_add_root_struct_ptr}, each of
+which points to a C structure.
@end enumerate
This does not include the GCPRO'ed variables, the specbinds, the
@item
the C compiler is required to adjust the size of a struct so that you
-can have an array of them next to each other. This means you can have a
+can have an array of them next to each other. This means you can have an
upper bound of the alignment requirements of a given structure by
looking at which power of two its size is a multiple.
The maximum alignment requirement we take into account is 2^8.
@code{pdump_allocate_offset()} only has to do a linear allocation,
-starting at offset 256 (this leaves room for the header and keep the
+starting at offset 256 (this leaves room for the header and keeps the
alignments happy).
@node The header, Data dumping, Address allocation, Dumping phase
@subsection The header
The next step creates the file and writes a header with a signature and
-some random informations in it (number of staticpro, number of assigned
-lrecord types, etc...). The reloc_address field, which indicates at
-which address the file should be loaded if we want to avoid post-reload
-relocation, is set to 0. It then seeks to offset 256 (base offset for
-the objects).
+some random information in it. The @code{reloc_address} field, which
+indicates at which address the file should be loaded if we want to avoid
+post-reload relocation, is set to 0. It then seeks to offset 256 (base
+offset for the objects).
@node Data dumping, Pointers dumping, The header, Dumping phase
@subsection Data dumping
@enumerate
@item
-the staticpro array
-@item
-the dumpstruct array
+the pdump_root_struct_ptrs dynarr
@item
-the lrecord_implementation_table array
+the pdump_opaques dynarr
@item
a vector of all the offsets to the objects in the file that include a
description (for faster relocation at reload time)
@item
-the pdump_wired and pdump_wired_list arrays
+the pdump_root_objects and pdump_weak_object_chains dynarrs.
@end enumerate
-For each of the arrays we write both the pointer to the variables and
+For each of the dynarrs we write both the pointer to the variables and
the relocated offset of the object they point to. Since these variables
are global, the pointers are still valid when restarting the program and
are used to regenerate the global pointers.
-The @code{pdump_wired_list} array is a special case. The variables it
-points to are the head of weak linked lists of lisp objects of the same
-type. Not all objects of this list are dumped so the relocated pointer
-we associate with them points to the first dumped object of the list, or
-Qnil if none is available. This is also the reason why they are not
-used as roots for the purpose of object enumeration.
+The @code{pdump_weak_object_chains} dynarr is a special case. The
+variables it points to are the head of weak linked lists of lisp objects
+of the same type. Not all objects of this list are dumped so the
+relocated pointer we associate with them points to the first dumped
+object of the list, or Qnil if none is available. This is also the
+reason why they are not used as roots for the purpose of object
+enumeration.
+
+Some very important information like the @code{staticpros} and
+@code{lrecord_implementations_table} are handled indirectly using
+@code{dump_add_opaque} or @code{dump_add_root_struct_ptr}.
This is the end of the dumping part.
is computed and will be used for all the relocations.
-@subsection Putting back the staticvec
-
-The staticvec array is memcpy'd from the file and the variables it
-points to are reset to the relocated objects addresses.
+@subsection Putting back the pdump_opaques
+The memory contents are restored in the obvious and trivial way.
-@subsection Putting back the dumpstructed variables
-The variables pointed to by dumpstruct in the dump phase are reset to
-the right relocated object addresses.
+@subsection Putting back the pdump_root_struct_ptrs
-
-@subsection lrecord_implementations_table
-
-The lrecord_implementations_table is reset to its dump time state and
-the right lrecord_type_index values are put in.
+The variables pointed to by pdump_root_struct_ptrs in the dump phase are
+reset to the right relocated object addresses.
@subsection Object relocation
reloc_address is equal to the file loading address.
-@subsection Putting back the pdump_wire and pdump_wire_list variables
+@subsection Putting back the pdump_root_objects and pdump_weak_object_chains
-Same as Putting back the dumpstructed variables.
+Same as Putting back the pdump_root_struct_ptrs.
@subsection Reorganize the hash tables
buffer positions in them as integers, and every time text is inserted or
deleted, these positions must be updated. In order to minimize the
amount of shuffling that needs to be done, the positions in markers and
-extents (there's one per marker, two per extent) and stored in Meminds.
+extents (there's one per marker, two per extent) are stored in Meminds.
This means that they only need to be moved when the text is physically
moved in memory; since the gap structure tries to minimize this, it also
minimizes the number of marker and extent indices that need to be
@table @code
@item name
The buffer name is a string that names the buffer. It is guaranteed to
-be unique. @xref{Buffer Names,,, lispref, XEmacs Lisp Programmer's
+be unique. @xref{Buffer Names,,, lispref, XEmacs Lisp Reference
Manual}.
@item save_modified
This field contains the time when the buffer was last saved, as an
-integer. @xref{Buffer Modification,,, lispref, XEmacs Lisp Programmer's
+integer. @xref{Buffer Modification,,, lispref, XEmacs Lisp Reference
Manual}.
@item modtime
This field contains the modification time of the visited file. It is
set when the file is written or read. Every time the buffer is written
to the file, this field is compared to the modification time of the
-file. @xref{Buffer Modification,,, lispref, XEmacs Lisp Programmer's
+file. @xref{Buffer Modification,,, lispref, XEmacs Lisp Reference
Manual}.
@item auto_save_modified
@item undo_list
This field points to the buffer's undo list. @xref{Undo,,, lispref,
-XEmacs Lisp Programmer's Manual}.
+XEmacs Lisp Reference Manual}.
@item syntax_table_v
This field contains the syntax table for the buffer. @xref{Syntax
-Tables,,, lispref, XEmacs Lisp Programmer's Manual}.
+Tables,,, lispref, XEmacs Lisp Reference Manual}.
@item downcase_table
This field contains the conversion table for converting text to lower
-case. @xref{Case Tables,,, lispref, XEmacs Lisp Programmer's Manual}.
+case. @xref{Case Tables,,, lispref, XEmacs Lisp Reference Manual}.
@item upcase_table
This field contains the conversion table for converting text to upper
-case. @xref{Case Tables,,, lispref, XEmacs Lisp Programmer's Manual}.
+case. @xref{Case Tables,,, lispref, XEmacs Lisp Reference Manual}.
@item case_canon_table
This field contains the conversion table for canonicalizing text for
case-folding search. @xref{Case Tables,,, lispref, XEmacs Lisp
-Programmer's Manual}.
+Reference Manual}.
@item case_eqv_table
This field contains the equivalence table for case-folding search.
-@xref{Case Tables,,, lispref, XEmacs Lisp Programmer's Manual}.
+@xref{Case Tables,,, lispref, XEmacs Lisp Reference Manual}.
@item display_table
This field contains the buffer's display table, or @code{nil} if it
doesn't have one. @xref{Display Tables,,, lispref, XEmacs Lisp
-Programmer's Manual}.
+Reference Manual}.
@item markers
This field contains the chain of all markers that currently point into
the buffer. Deletion of text in the buffer, and motion of the buffer's
gap, must check each of these markers and perhaps update it.
-@xref{Markers,,, lispref, XEmacs Lisp Programmer's Manual}.
+@xref{Markers,,, lispref, XEmacs Lisp Reference Manual}.
@item backed_up
This field is a flag that tells whether a backup file has been made for
@item mark
This field contains the mark for the buffer. The mark is a marker,
hence it is also included on the list @code{markers}. @xref{The Mark,,,
-lispref, XEmacs Lisp Programmer's Manual}.
+lispref, XEmacs Lisp Reference Manual}.
@item mark_active
This field is non-@code{nil} if the buffer's mark is active.
in this buffer, and their values, with the exception of local variables
that have special slots in the buffer object. (Those slots are omitted
from this table.) @xref{Buffer-Local Variables,,, lispref, XEmacs Lisp
-Programmer's Manual}.
+Reference Manual}.
@item modeline_format
This field contains a Lisp object which controls how to display the mode
line for this buffer. @xref{Modeline Format,,, lispref, XEmacs Lisp
-Programmer's Manual}.
+Reference Manual}.
@item base_buffer
This field holds the buffer's base buffer (if it is an indirect buffer),
other encoded/decoded data has been written out. This is not used for
charset CCL programs.
-REGISTER: 0..7 -- refered by RRR or rrr
+REGISTER: 0..7 -- referred by RRR or rrr
OPERATOR BIT FIELD (27-bit): XXXXXXXXXXXXXXX RRR TTTTT
TTTTT (5-bit): operator type
these are @dfn{hchild} (a list of horizontally-arrayed children),
@dfn{vchild} (a list of vertically-arrayed children), and @dfn{buffer}
(the buffer contained in a leaf window). Exactly one of
-these will be non-nil. Remember that @dfn{horizontally-arrayed}
+these will be non-@code{nil}. Remember that @dfn{horizontally-arrayed}
means ``side-by-side'' and @dfn{vertically-arrayed} means
@dfn{one above the other}.
Leaf windows also have markers in their @code{start} (the
first buffer position displayed in the window) and @code{pointm}
(the window's stashed value of @code{point}---see above) fields,
-while combination windows have nil in these fields.
+while combination windows have @code{nil} in these fields.
@item
The list of children for a window is threaded through the
@section Zero-Length 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
+are explicitly set that way or if their detachable property is @code{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
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 arcane as a native
+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
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.
+cached on an XEmacs window basis.
Any action on a glyph first consults the cache before actually
instantiating a widget.
@section 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 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.
+Widget-glyphs under X make heavy use of lwlib (@pxref{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.
@node Specifiers, Menus, Glyphs, Top
@chapter Specifiers
its argument, which is the callback function or form given in the menu's
description.
-@node Subprocesses, Interface to X Windows, Menus, Top
+@node Subprocesses, Interface to the X Window System, Menus, Top
@chapter Subprocesses
The fields of a process are:
or @code{nil} if it is using pipes.
@end table
-@node Interface to X Windows, Index , Subprocesses, Top
-@chapter Interface to X Windows
+@node Interface to the X Window System, Index, Subprocesses, Top
+@chapter Interface to the X Window System
-Not yet documented.
+Mostly undocumented.
+
+@menu
+* Lucid Widget Library:: An interface to various widget sets.
+@end menu
+
+@node Lucid Widget Library, , , Interface to the X Window System
+@section 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::
+@end menu
+
+@node Generic Widget Interface, Scrollbars, , Lucid Widget Library
+@subsection 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 @code{widget_values}
+which mirror the hierarchical state of Xt widgets (including Motif,
+Athena, 3D Athena, and Falk's widget sets). Each @code{widget_value}
+has @code{contents} member, which points to the head of a linked list of
+its children. The linked list of siblings is chained through the
+@code{next} member of @code{widget_value}.
+
+@example
+ +-----------+
+ | composite |
+ +-----------+
+ |
+ | contents
+ V
+ +-------+ next +-------+ next +-------+
+ | child |----->| child |----->| child |
+ +-------+ +-------+ +-------+
+ |
+ | contents
+ V
+ +-------------+ next +-------------+
+ | grand child |----->| grand child |
+ +-------------+ +-------------+
+
+The @code{widget_value} hierarchy of a composite widget with two simple
+children and one composite child.
+@end example
+
+The @code{widget_instance} structure maintains the inverse view of the
+tree. As for the @code{widget_value}, siblings are chained through the
+@code{next} member. However, rather than naming children, the
+@code{widget_instance} tree links to parents.
+
+@example
+ +-----------+
+ | composite |
+ +-----------+
+ A
+ | parent
+ |
+ +-------+ next +-------+ next +-------+
+ | child |----->| child |----->| child |
+ +-------+ +-------+ +-------+
+ A
+ | parent
+ |
+ +-------------+ next +-------------+
+ | grand child |----->| grand child |
+ +-------------+ +-------------+
+
+The @code{widget_value} hierarchy of a composite widget with two simple
+children and one composite child.
+@end example
+
+This permits widgets derived from different toolkits to be updated and
+manipulated generically by the lwlib library. For instance
+@code{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 @code{widget_value} by walking the
+@code{widget_value} tree. This has desirable properties. For example,
+@code{lw_modify_all_widgets} is called from @file{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 @code{widget_instance} structure also contains a pointer to the root
+of its tree. Widget instances are further confi
+
+
+@node Scrollbars, Menubars, Generic Widget Interface, Lucid Widget Library
+@subsection Scrollbars
+
+@node Menubars, Checkboxes and Radio Buttons, Scrollbars, Lucid Widget Library
+@subsection Menubars
+
+@node Checkboxes and Radio Buttons, Progress Bars, Menubars, Lucid Widget Library
+@subsection Checkboxes and Radio Buttons
+
+@node Progress Bars, Tab Controls, Checkboxes and Radio Buttons, Lucid Widget Library
+@subsection Progress Bars
+
+@node Tab Controls, , Progress Bars, Lucid Widget Library
+@subsection Tab Controls
@include index.texi
projects / chise / xemacs-chise.git / blobdiff