# Evolution of the Intrinsics

The interfaces described by this specification have undergone several sets of revisions in the course of adoption as an X Consortium standard specification. Having now been adopted by the Consortium as a standard part of the X Window System, it is expected that this and future revisions will retain backward compatibility in the sense that fully conforming implementations of these specifications may be produced that provide source compatibility with widgets and applications written to previous Consortium standard revisions.

The Intrinsics do not place any special requirement on widget programmers to retain source or binary compatibility for their widgets as they evolve, but several conventions have been established to assist those developers who want to provide such compatibility.

In particular, widget programmers may wish to conform to the convention described in when defining class extension records.

## Determining Specification Revision Level

Widget and application developers who wish to maintain a common source pool that will build properly with implementations of the Intrinsics at different revision levels of these specifications but that take advantage of newer features added in later revisions may use the symbolic macro `XtSpecificationRelease`.

    #define XtSpecificationRelease 7

As the symbol `XtSpecificationRelease` was new to Release 4, widgets and applications desiring to build against earlier implementations should test for the presence of this symbol and assume only Release 3 interfaces if the definition is not present.

## Release 3 to Release 4 Compatibility

At the data structure level, Release 4 retains binary compatibility with Release 3 (the first X Consortium standard release) for all data structures except `WMShellPart,` `TopLevelShellPart`, and `TransientShellPart`. Release 4 changed the argument type to most procedures that now take arguments of type `XtPointer` and structure members that are now of type `XtPointer` in order to avoid potential ANSI C conformance problems. It is expected that most implementations will be binary compatible with the previous definition.

Two fields in `CoreClassPart` were changed from `Boolean` to `XtEnum` to allow implementations additional freedom in specifying the representations of each. This change should require no source modification.

### Additional Arguments

Arguments were added to the procedure definitions for , , and to provide more information and to allow event handlers to abort further dispatching of the current event (caution is advised!). The added arguments to and make the initialize_hook and set_values_hook methods obsolete, but the hooks have been retained for those widgets that used them in Release 3.

### set_values_almost Procedures

The use of the arguments by a set_values_almost procedure was poorly described in Release 3 and was inconsistent with other conventions.

The current specification for the manner in which a set_values_almost procedure returns information to the Intrinsics is not compatible with the Release 3 specification, and all widget implementations should verify that any set_values_almost procedures conform to the current interface.

No known implementation of the Intrinsics correctly implemented the Release 3 interface, so it is expected that the impact of this specification change is small.

### Query Geometry

A composite widget layout routine that calls is now expected to store the complete new geometry in the intended structure; previously the specification said “store the changes it intends to make”. Only by storing the complete geometry does the child have any way to know what other parts of the geometry may still be flexible. Existing widgets should not be affected by this, except to take advantage of the new information.

### unrealizeCallback Callback List

In order to provide a mechanism for widgets to be notified when they become unrealized through a call to , the callback list name “unrealizeCallback” has been defined by the Intrinsics. A widget class that requires notification on unrealize may declare a callback list resource by this name. No class is required to declare this resource, but any class that did so in a prior revision may find it necessary to modify the resource name if it does not wish to use the new semantics.

### Subclasses of WMShell

The formal adoption of the Inter-Client Communication Conventions Manual as an X Consortium standard has meant the addition of four fields to `WMShellPart` and one field to `TopLevelShellPart`. In deference to some widget libraries that had developed their own additional conventions to provide binary compatibility, these five new fields were added at the end of the respective data structures.

To provide more convenience for TransientShells, a field was added to the previously empty `TransientShellPart`. On some architectures the size of the part structure will not have changed as a result of this.

Any widget implementation whose class is a subclass of TopLevelShell or TransientShell must at minimum be recompiled with the new data structure declarations. Because `WMShellPart` no longer contains a contiguous `XSizeHints` data structure, a subclass that expected to do a single structure assignment of an `XSizeHints` structure to the size_hints field of `WMShellPart` must be revised, though the old fields remain at the same positions within `WMShellPart`.

### Resource Type Converters

A new interface declaration for resource type converters was defined to provide more information to converters, to support conversion cache cleanup with resource reference counting, and to allow additional procedures to be declared to free resources. The old interfaces remain (in the compatibility section), and a new set of procedures was defined that work only with the new type converter interface.

In the now obsolete old type converter interface, converters are reminded that they must return the size of the converted value as well as its address. The example indicated this, but the description of was incomplete.

### KeySym Case Conversion Procedure

The specification for the function type has been changed to match the Release 3 implementation, which included necessary additional information required by the function (a pointer to the display connection), and corrects the argument type of the source KeySym parameter. No known implementation of the Intrinsics implemented the previously documented interface.

### Nonwidget Objects

Formal support for nonwidget objects is new to Release 4. A prototype implementation was latent in at least one Release 3 implementation of the Intrinsics, but the specification has changed somewhat. The most significant change is the requirement for a composite widget to declare the `CompositeClassExtension` record with the accepts_objects field set to `True` in order to permit a client to create a nonwidget child.

The addition of this extension field ensures that composite widgets written under Release 3 will not encounter unexpected errors if an application attempts to create a nonwidget child. In Release 4 there is no requirement that all composite widgets implement the extra functionality required to manage windowless children, so the accepts_objects field allows a composite widget to declare that it is not prepared to do so.

## Release 4 to Release 5 Compatibility

At the data structure level, Release 5 retains complete binary compatibility with Release 4. The specification of the `ObjectPart`, `RectObjPart`, `CorePart`, `CompositePart`, `ShellPart`, `WMShellPart`, `TopLevelShellPart`, and `ApplicationShellPart` instance records was made less strict to permit implementations to add internal fields to these structures. Any implementation that chooses to do so would, of course, force a recompilation. The Xlib specification for `XrmValue` and `XrmOptionDescRec` was updated to use a new type, `XPointer`, for the addr and value fields, respectively, to avoid ANSI C conformance problems. The definition of `XPointer` is binary compatible with the previous implementation.

### baseTranslations Resource

A new pseudo-resource, XtNbaseTranslations, was defined to permit application developers to specify translation tables in application defaults files while still giving end users the ability to augment or override individual event sequences. This change will affect only those applications that wish to take advantage of the new functionality or those widgets that may have previously defined a resource named “baseTranslations”.

Applications wishing to take advantage of the new functionality would change their application defaults file, e.g., from

            app.widget.translations:         value
    to
            app.widget.baseTranslations:     value

If it is important to the application to preserve complete compatibility of the defaults file between different versions of the application running under Release 4 and Release 5, the full translations can be replicated in both the “translations” and the “baseTranslations” resource.

### Resource File Search Path

The current specification allows implementations greater flexibility in defining the directory structure used to hold the application class and per-user application defaults files. Previous specifications required the substitution strings to appear in the default path in a certain order, preventing sites from collecting all the files for a specific application together in one directory. The Release 5 specification allows the default path to specify the substitution strings in any order within a single path entry. Users will need to pay close attention to the documentation for the specific implementation to know where to find these files and how to specify their own XFILESEARCHPATH and XUSERFILESEARCHPATH values when overriding the system defaults.

### Customization Resource

supports a new substitution string, %C, for specifying separate application class resource files according to arbitrary user-specified categories. The primary motivation for this addition was separate monochrome and color application class defaults files. The substitution value is obtained by querying the current resource database for the application resource name “customization”, class “Customization”. Any application that previously used this resource name and class will need to be aware of the possibly conflicting semantics.

### Per-Screen Resource Database

To allow a user to specify separate preferences for each screen of a display, a per-screen resource specification string has been added and multiple resource databases are created; one for each screen. This will affect any application that modified the (formerly unique) resource database associated with the display subsequent to the Intrinsics database initialization. Such applications will need to be aware of the particular screen on which each shell widget is to be created.

Although the wording of the specification changed substantially in the description of the process by which the resource database(s) is initialized, the net effect is the same as in prior releases with the exception of the added per-screen resource specification and the new customization substitution string in .

### Internationalization of Applications

Internationalization as defined by ANSI is a technology that allows support of an application in a single locale. In adding support for internationalization to the Intrinsics the restrictions of this model have been followed. In particular, the new Intrinsics interfaces are designed not to preclude an application from using other alternatives. For this reason, no Intrinsics routine makes a call to establish the locale. However, a convenience routine to establish the locale at initialize time has been provided, in the form of a default procedure that must be explicitly installed if the application desires ANSI C locale behavior.

As many objects in X, particularly resource databases, now inherit the global locale when they are created, applications wishing to use the ANSI C locale model should use the new function `XtSetLanguageProc` to do so.

The internationalization additions also define event filters as a part of the Xlib Input Method specifications. The Intrinsics enable the use of event filters through additions to . Applications that may not be dispatching all events through should be reviewed in the context of this new input method mechanism.

In order to permit internationalization of error messages, the name and path of the error database file are now allowed to be implementation-dependent. No adequate standard mechanism has yet been suggested to allow the Intrinsics to locate the database from localization information supplied by the client.

The previous specification for the syntax of the language string specified by `xnlLanguage` has been dropped to avoid potential conflicts with other standards. The language string syntax is now implementation-defined. The example syntax cited is consistent with the previous specification.

### Permanently Allocated Strings

In order to permit additional memory savings, an Xlib interface was added to allow the resource manager to avoid copying certain string constants. The Intrinsics specification was updated to explicitly require the Object class_name, resource_name, resource_class, resource_type, default_type in resource tables, Core actions string field, and Constraint resource_name, resource_class, resource_type, and default_type resource fields to be permanently allocated. This explicit requirement is expected to affect only applications that may create and destroy classes on the fly.

### Arguments to Existing Functions

The args argument to , , , , and were changed from `Cardinal`* to int* to conform to pre-existing convention and avoid otherwise annoying typecasting in ANSI C environments.

## Release 5 to Release 6 Compatibility

At the data structure level, Release 6 retains binary compatibility with Release 5 for all data structures except `WMShellPart`. Three resources were added to the specification. The known implementations had unused space in the data structure, therefore on some architectures and implementations, the size of the part structure will not have changed as a result of this.

### Widget Internals

Two new widget methods for instance allocation and deallocation were added to the Object class. These new methods allow widgets to be treated as C++ objects in the C++ environment when an appropriate allocation method is specified or inherited by the widget class.

The textual descriptions of the processes of widget creation and widget destruction have been edited to provide clarification to widget writers. Widgets writers may have reason to rely on the specific order of the stages of widget creation and destruction; with that motivation, the specification now more exactly describes the process.

As a convenience, an interface to locate a widget class extension record on a linked list, , has been added.

A new option to allow bundled changes to the managed set of a Composite widget is introduced in the Composite class extension record. Widgets that define a change_managed procedure that can accommodate additions and deletions to the managed set of children in a single invocation should set allows_change_managed_set to `True` in the extension record.

The wording of the process followed by has changed slightly to better handle changes to the managed set during phase 2 destroy processing.

A new exposure event compression flag, `XtExposeNoRegion`, was added. Many widgets specify exposure compression, but either ignore the actual damage region passed to the core expose procedure or use only the cumulative bounding box data available in the event. Widgets with expose procedures that do not make use of exact exposure region information can indicate that the Intrinsics need not compute the region.

### General Application Development

is a new convenience procedure to initialize the toolkit, create an application context, open an X display connection, and create the root of the widget instance tree. It is identical to the interface it replaces, , in all respects except that it takes an additional argument specifying the widget class of the root shell to create. This interface is now the recommended one so that clients may easily become session participants. The old convenience procedures appear in the compatibility section.

The toolkit initialization function may be called multiple times without penalty.

In order to optimize changes in geometry to a set of geometry-managed children, a new interface, , has been added.

### Communication with Window and Session Managers

The revision of the Inter-Client Communication Conventions Manual as an X Consortium standard has resulted in the addition of three fields to the specification of `WMShellPart`. These are urgency, client_leader, and window_role.

The adoption of the X Session Management Protocol as an X Consortium standard has resulted in the addition of a new shell widget, `SessionShell`, and an accompanying subclass verification interface, `XtIsSessionShell`. This widget provides support for communication between an application and a session manager, as well as a window manager. In order to preserve compatibility with existing subclasses of `ApplicationShell`, the `ApplicationShell` was subclassed to create the new widget class. The session protocol requires a modal response to certain checkpointing operations by participating applications. The `SessionShell` structures the application's notification of and responses to messages from the session manager by use of various callback lists and by use of the new interfaces and . There is also a new command line argument, -xtsessionID, which facilitates the session manager in restarting applications based on the Intrinsics.

The resource name and class strings defined by the Intrinsics shell widgets in `<X11/Shell.h>` are now listed in Appendix E. The addition of a new symbol for the `WMShell` wait_for_wm resource was made to bring the external symbol and the string it represents into agreement. The actual resource name string in `WMShell` has not changed. The resource representation type of the XtNwinGravity resource of the `WMShell` was changed to XtRGravity in order to register a type converter so that window gravity resource values could be specified by name.

### Geometry Management

A clarification to the specification was made to indicate that geometry requests may include current values along with the requested changes.

### Event Management

In Release 6, support is provided for registering selectors and event handlers for events generated by X protocol extensions and for dispatching those events to the appropriate widget. The new event handler registration interfaces are and . Since the mechanism to indicate selection of extension events is specific to the extension being used, the Intrinsics introduces , which allows the application to select for the events of interest. In order to change the dispatching algorithm to accommodate extension events as well as core X protocol events, the Intrinsics event dispatcher may now be replaced or enveloped by the application with . The dispatcher may wish to call to determine the widget with the current Intrinsics keyboard focus. A dispatcher, after determining the destination widget, may use to cause the event to be dispatched to the event handlers registered by a specific widget.

To permit the dispatching of events for nonwidget drawables, such as pixmaps that are not associated with a widget's window, and have been added to the library. A related update was made to the description of .

The library is now thread-safe, allowing one thread at a time to enter the library and protecting global data as necessary from concurrent use. Threaded toolkit applications are supported by the new interfaces , , , , and . Widget writers may also use and .

Safe handling of POSIX signals and other asynchronous notifications is now provided by use of , , and .

The application can receive notification of an impending block in the Intrinsics event manager by registering interest through and .

returns the most recent event passed to for a specified display.

### Resource Management

Resource converters are registered by the Intrinsics for window gravity and for three new resource types associated with session participation: RestartStyle, CommandArgArray and DirectoryString.

The file search path syntax has been extended to make it easier to include the default search path, which controls resource database construction, by using the new substitution string, %D.

### Translation Management

The default key translator now recognizes the NumLock modifier. If NumLock is on and the second keysym is a keypad keysym (a standard keysym named with a “KP” prefix or a vendor-specific keysym in the hexadecimal range 0x11000000 to 0x1100FFFF), then the default key translator will use the first keysym if Shift and/or ShiftLock is on and will use the second keysym if neither is on. Otherwise, it will ignore NumLock and apply the normal protocol semantics.

### Selections

The targets of selection requests may be parameterized, as described by the revised Inter-Client Communication Conventions Manual. When such requests are made, is used by the requestor to specify the target parameters and is used by the selection owner to retrieve the parameters. When a parameterized target is specified in the context of a bundled request for multiple targets, , , and are used to envelop the assembly of the request. When the parameters themselves are the names of properties, the Intrinsics provides support for the economical use of property atom names; see and .

### External Agent Hooks

External agent hooks were added for the benefit of applications that instrument other applications for purposes of accessibility, testing, and customization. The external agent and the application communicate by a shared protocol which is transparent to the application. The hook callbacks permit the external agent to register interest in groups or classes of toolkit activity and to be notified of the type and details of the activity as it occurs. The new interfaces related to this effort are , which returns the hook registration widget, and , which returns a list of the X displays associated with an application context.

## Release 6 to Release 7 Compatibility

### Changes During X11R6

The Toolkit was proposed in X10R4, released at the end of 1986. The X11R6 documentation was completed in mid–1994. Over most of the eleven years through X11R6.9, only minor changes were made to the specification. Some changes are documented only in the release notes:

- The X11R6.3 release notes (1997) mention one new feature (section 3.15) Xt Geometry Management Debugger, saying

  > Daniel Dardailler's “GeoTattler” code has been merged into the Xt Intrinsics library implementation. This is not a standard. If libXt is compiled with the `XT_GEO_TATTLER` symbol defined (currently there is no build configuration support to do this) then a “geoTattler” resource may be specified for any widget in an application. If the `geoTattler` resource for a widget instance is `True` then libXt will generate debugging information to stdout when the widget makes geometry change requests.

  > For example, if the resources specify:

  >     myapp*draw.XmScale.geoTattler: ON
  >     *XmScrollBar.geoTattler:ON
  >     *XmRowColumn.exit_button.geoTattler:ON

  > then geometry management debugging information will be generated for all the `XmScale` children of the widget named draw, all the XmScrollBars, and the widget named exit_button in any `XmRowColumn`.

- X11R6.4 (1998) added . The release notes explain that by saying

  > The X Toolkit Intrinsics library (libXt) now has IBM's Easy Resource Configuration support included.

  but goes on to say (section 14) that

  > Easy Resource Configuration is not a standard part of the X Toolkit Intrinsics (libXt). It is neither an X Consortium standard nor an X Project Team specification.

- X11R6.5 (2000) documented a bug-fix for XtAppPeekEvent in the release notes, stating that it now worked as described in the specification. It also modified the description of XtAppPeekEvent in the specification. Previously the specification stated that no known implementations behaved as specified.

- Subsequent releases X11R6.6 (2001) through X11R6.9 (2005) did not document any new or improved features.

Throughout this interval, there were undocumented fixes and improvements made to the X Toolkit Intrinsics library. The documentation was modified to fix minor errors, improve the formatting, and update version numbers.

### Changes During X11R7

X11R7 releases starting in 2005 continued this trend, converting the documentation from nroff to sgml. X11R7.7 (2012) provides the same Intrinsics specification (aside from details of formatting and version numbers) as X11R6 (1995).

The updates for this specification are a continuation of X11R7.7, because (as of April 2019) there are no plans for an X11R7.8 release.

### Converting to Standard C

The Intrinsics specification was first released with X11R3 in 1989. That was too early to take Standard C (i.e., ANSI C) into account. Because vendors generally did not provide a no-cost Standard C compiler, the X Toolkit Intrinsics library initially supported both K&R and ANSI C. The X11R5 release notes mention using gcc, with some caveats. As a result, the specification and implementation gave equal attention to both K&R and ANSI C.

This example shows how a function prototype was used in the C header files:

    extern Display *XtOpenDisplay(
    #if NeedFunctionPrototypes
        XtAppContext        /* app_context */,
        _Xconst _XtString   /* display_string */,
        _Xconst _XtString   /* application_name */,
        _Xconst _XtString   /* application_class */,
        XrmOptionDescRec*   /* options */,
        Cardinal            /* num_options */,
        int*                /* argc */,
        char**              /* argv */
    #endif
    );

The parameters for the ANSI C prototype were conditionally compiled. Used with a K&R compiler, those parameters were ignored.

- The X Toolkit Intrinsics library used const in just a few cases. The specification did not mention it at all.

  Over time, that was seen as a problem, partly because of gcc's warning options such as write-strings, introduced in early 1988 (released with gcc 1.27 in late 1988). Quoting from gcc 2.58's documentation (late 1993):

      `-Wwrite-strings'
           Give string constants the type `const char[LENGTH]' so that
           copying the address of one into a non-`const' `char *' pointer
           will get a warning.  These warnings will help you find at compile
           time code that can try to write into a string constant, but only
           if you have been very careful about using `const' in declarations
           and prototypes.  Otherwise, it will just be a nuisance; this is
           why we did not make `-Wall' request these warnings.

  Others did not agree that it was a nuisance. Besides the obvious advantage of improving program correctness, making a symbol “const” gave the compiler and linker a hint that the symbol could be put into the text (read-only) section, eliminating some steps needed by the linker to adjust addresses and thereby reducing the time it took to load a program into memory.

  Other gcc warning options (such as such as cast-qual) are useful for improving programs. They give similar information, because unless told otherwise, gcc would treat string values as nonwritable. Quoting from gcc 1.27:

         * GNU CC normally makes string constants read-only.  If several
           identical-looking string constants are used, GNU CC stores only
           one copy of the string.
           ...
           The best solution to these problems is to change the program to
           use `char'-array variables with initialization strings for these
           purposes instead of string constants.  But if this is not
           possible, you can use the `-fwritable-strings' flag, which
           directs GNU CC to handle string constants the same way most C
           compilers do.

  and

          `-fwritable-strings'
                Store string constants in the writable data segment and
                don't uniquize them.  This is for compatibility with old
                programs which assume they can write into string constants.
                Writing into string constants is a very bad idea;
                ``constants'' should be constant.

- Several prototypes in the implementation use the private type _XtString. The specification and implementation also used a String type without explaining when it is appropriate.

      typedef char *String;

      /* We do this in order to get "const" declarations to work right.  We
       * use _XtString instead of String so that C++ applications can
       * #define String to something else if they choose, to avoid conflicts
       * with other C++ libraries.
       */
      #define _XtString char*

  That is, the developers were providing for some workaround to allow C++ applications to use the stricter compiler checking associated with const.

- The String type is not the only type used in the prototypes for the X Toolkit Intrinsics library. Its developers were also concerned with porting the library to platforms with different size-constraints. They defined different types (used in the function prototypes) depending on whether a “wide” parameter type was appropriate:

      /* _Xt names are private to Xt implementation, do not use in client code */
      #if NeedWidePrototypes
      #define _XtBoolean	int
      #define _XtDimension	unsigned int
      #define _XtKeyCode	unsigned int
      #define _XtPosition	int
      #define _XtXtEnum	unsigned int
      #else
      #define _XtBoolean	Boolean
      #define _XtDimension	Dimension
      #define _XtKeyCode	KeyCode
      #define _XtPosition	Position
      #define _XtXtEnum	XtEnum
      #endif /* NeedWidePrototypes */

  and

      #ifdef CRAY
      typedef long		Boolean;
      typedef char*		XtArgVal;
      typedef long		XtEnum;
      #else
      typedef char		Boolean;
      typedef long		XtArgVal;
      typedef unsigned char	XtEnum;
      #endif

  In practice, wide-prototypes are rarely used, not well supported. The specification did not clarify the distinction between Bool (mentioned as a resource type) and Boolean (used in all of the data structures). The implementation used both, predominantly the latter.

Other features of Standard C were neglected in the specification because it was accommodating K&R C:

- K&R C has no void keyword. The specification used it for return-types, but not to indicate an empty parameter list. The specification also stated that void* would be used for the XtPointer type.

  The conversion to sgml lost the void return-type.

- Standard C uses an ellipsis for variable-length argument lists, e.g., for . Again, there was a conditional-compilation symbol (`NeedVarargsPrototypes`) to handle the different forms used. Here is an example:

      #if NeedVarargsPrototypes
      void
      XtVaGetApplicationResources(Widget widget, XtPointer base, XtResourceList resources, Cardinal num_resources, ...)
      #else
      /*VARARGS4*/
      void XtVaGetApplicationResources(widget, base, resources, num_resources, va_alist)
          Widget widget;
          XtPointer base;
          XtResourceList resources;
          Cardinal num_resources;
          va_dcl
      #endif

  One problem with the conditional-compilation was that it was easy to make a mistake with the order of parameters between the two forms. Developers would frequently group together parameters which used the same type, whether or not they were adjacent in the Standard C prototype.

  A comment in the X11R4 header file said that this was temporary, until function prototypes worked everywhere. That was finally removed in X11R6.7 (fourteen years later). However, the subsequent conversion to sgml lost the ellipsis from the prototypes shown in the specification.

Support for K&R C was removed from the header files in 2003 (released in X11R6.7), and from the library source in 2004 (released in X11R6.9). The wide-prototype feature is still present in 2019, but generally unused.

Removing support for K&R C did not address the issues of const. That was done in 2019:

- The String is conditionally defined, to provide compatibility with existing applications.

- If the symbol _CONST_X_STRING is defined, String is read-only as shown here.

      /*
       * As used in its function interface, the String type of libXt can be readonly.
       * But compiling libXt with this feature may require some internal changes,
       * e.g., casts and occasionally using a plain "char*".
       */
      #ifdef _CONST_X_STRING
      typedef const char *String;
      #else
      typedef char *String;
      #endif

- Applications which use the newer const feature must define _CONST_X_STRING to enable this feature.

- By default, the X Toolkit Intrinsics library uses the const feature. It has been updated to make use of the const feature for improved type-checking.

- Because the X Toolkit Intrinsics library uses const, some prototypes have been modified. For example:

  - Most of the parameters which used String are unmodified; a few (such as the argv–parameters) are actually read/write. They are now char* parameters.

    Many of the strings passed to the library are stored in widgets without reallocating a copy. Those are treated as read-only, and use the String type.

  - Each change to the documentation was verified using scripts that extracted the function prototypes and used the C compiler to check for compatibility.