Common Desktop Environment Motif Widget Binary Compatibility Guidelines

Any widget subclass that you implement using the standard Xt APIs that rely on the size of data structures of widgets from which you have subclassed might not be compatible with any new version of Motif or the Common Desktop Environment. The reason for this is that new fields may be added to the superclasses in the new version of Motif. An example is that new fields have been added to the XmManager and XmPrimitive classes in Motif 2.0.

The incompatibility occurs because a subclass must contain compiled-in references to its instance fields that are specified relative to the start address of the widget instance. When you install a new Motif library for a widget whose superclass instance structure has been extended, the compiled-in references will point to the wrong memory location.

To avoid this difficulty, Motif provides a mechanism for defining resources and accessing widget fields that allows you to reference all fields in the instance and constraint structures relative to the start of the widget part structure, instead of the overall widget structure. (The overall widget structure includes the superclass part structure.) The mechanism resolves these relative references at run time, when the widget class is first initialized. To resolve references, it factors in the size of the widget's superclass instance structure, which it reads from the currently linked Motif library.

If you implement subclassing, you must use the Motif reference-resolving mechanism if you want your application to be binary compatible with future releases of the Common Desktop Environment.

For details regarding this Motif mechanism, consult the Motif 1.2 XmResolvePartOffsets(3x) and XmResolveAllPartOffsets(3x) man pages and the Motif 2.1 Programmer's Reference. You can find example source code in /usr/dt/examples/motif/dogs.