41. Interface to the X Window System

Mostly undocumented.

41.1 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.

41.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

41.1.2 Scrollbars

41.1.3 Menubars

41.1.4 Checkboxes and Radio Buttons

41.1.5 Progress Bars

41.1.6 Tab Controls

41.2 Modules for Interfacing with X Windows

Emacs.ad.h

A file generated from ‘Emacs.ad’, which contains XEmacs-supplied fallback resources (so that XEmacs has pretty defaults).

EmacsFrame.c
EmacsFrame.h
EmacsFrameP.h

These modules implement an Xt widget class that encapsulates a frame. This is for ease in integrating with Xt. The EmacsFrame widget covers the entire X window except for the menubar; the scrollbars are positioned on top of the EmacsFrame widget.

Warning: Abandon hope, all ye who enter here. This code took an ungodly amount of time to get right, and is likely to fall apart mercilessly at the slightest change. Such is life under Xt.

EmacsManager.c
EmacsManager.h
EmacsManagerP.h

These modules implement a simple Xt manager (i.e. composite) widget class that simply lets its children set whatever geometry they want. It’s amazing that Xt doesn’t provide this standardly, but on second thought, it makes sense, considering how amazingly broken Xt is.

EmacsShell-sub.c
EmacsShell.c
EmacsShell.h
EmacsShellP.h

These modules implement two Xt widget classes that are subclasses of the TopLevelShell and TransientShell classes. This is necessary to deal with more brokenness that Xt has sadistically thrust onto the backs of developers.

xgccache.c
xgccache.h

These modules provide functions for maintenance and caching of GC’s (graphics contexts) under the X Window System. This code is junky and needs to be rewritten.

select-msw.c
select-x.c
select.c
select.h

This module provides an interface to the X Window System’s concept of selections, the standard way for X applications to communicate with each other.

xintrinsic.h
xintrinsicp.h
xmmanagerp.h
xmprimitivep.h

These header files are similar in spirit to the ‘sys*.h’ files and buffer against different implementations of Xt and Motif.

• ‘xintrinsic.h’ should be included in place of ‘<Intrinsic.h>’.
• ‘xintrinsicp.h’ should be included in place of ‘<IntrinsicP.h>’.
• ‘xmmanagerp.h’ should be included in place of ‘<XmManagerP.h>’.
• ‘xmprimitivep.h’ should be included in place of ‘<XmPrimitiveP.h>’.

ExternalClient-Xlib.c
ExternalClient.c
ExternalClient.h
ExternalClientP.h
ExternalShell.c
ExternalShell.h
ExternalShellP.h
extw-Xlib.c
extw-Xlib.h
extw-Xt.c
extw-Xt.h

These files provide the external widget interface, which allows an XEmacs frame to appear as a widget in another application. To do this, you have to configure with ‘--external-widget’.

‘ExternalShell*’ provides the server (XEmacs) side of the connection.

‘ExternalClient*’ provides the client (other application) side of the connection. These files are not compiled into XEmacs but are compiled into libraries that are then linked into your application.

‘extw-*’ is common code that is used for both the client and server.

Don’t touch this code; something is liable to break if you do.

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.