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