29.1.1 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