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
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
In particular, widget programmers may
wish to conform to the convention described in Section 1.6.12
when defining class extension records.
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 6
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.
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.
13.2.1. Additional Arguments
Arguments were added to the procedure definitions for XtInitProc, XtSetValuesFunc, and XtEventHandler to provide more information and to allow event handlers to abort further
dispatching of the current event (caution
is advised!). The added arguments to XtInitProc and XtSetValuesFunc
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.
13.2.2. 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.
13.2.3. Query Geometry
A composite widget layout routine that
calls XtQueryGeometry 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.
13.2.4. unrealizeCallback Callback List
In order to provide a mechanism for
widgets to be notified when they become unrealized through a call
to XtUnrealizeWidget, 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
13.2.5. 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.
13.2.6. 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 XtConverter was incomplete.
13.2.7. KeySym Case Conversion Procedure
The specification for the XtCaseProc
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.
13.2.8. 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 accept objects field
allows a composite widget to declare that it is not prepared to
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.
13.3.1. 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".
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"
13.3.2. 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
13.3.3. Customization Resource
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.
13.3.4. 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 XtResolvePathname.
13.3.5. 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 to not 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 XtDispatchEvent. Applications that may not be dispatching
all events through XtDispatchEvent 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
is 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.
13.3.6. 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.
13.3.7. Arguments to Existing Functions
The args argument to XtAppInitialize,
XtVaAppInitialize, XtOpenDisplay, XtDisplayInitialize,
and XtInitialize were changed from Cardinal* to
int* to conform to preexisting convention and avoid otherwise
annoying typecasting in ANSI C environments.
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
13.4.1. 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, XtGetClassExtension,
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 which define a change_managed procedure which 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 XtUnmanageChildren 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
which do not make use of exact exposure region information can
indicate that the Intrinsics need not compute the region.
13.4.2. General Application Development
XtOpenApplication 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, XtAppInitialize, 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 XtToolkitInitialize may be called multiple times without penalty.
In order to optimize changes in geometry
to a set of geometry-managed children, a new interface XtChangeManagedSet,
has been added.
13.4.3. 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 (provided in printed version only) 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 XtSessionGetToken and XtSessionReturnToken.
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.
13.4.4. Geometry Management
A clarification to the specification
was made to indicate that geometry requests may include current
values along with the requested changes.
13.4.5. Event Management
In R6, 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 XtInsertEventTypeHandler
and XtRemoveEventTypeHandler. Since the mechanism to
indicate selection of extension events is specific to the extension
being used, the Intrinsics introduces XtRegislerExtensionSelector
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 XtSetEventDispatcher. The dispatcher may wish to call
XtGetKeyboardFocusWidget to determine the widget with the
current Intrinsics keyboard focus. A dispatcher, after determining
the destination widget, may use XtDispatchEventToWidget to
cause the event to be dispatched to the event handlers registered
by a specific widget.
To permit the dispatching of events for non-widget drawables, such as pixmaps which are not associated with a widget's window, XtRegisterDrawable and XtUnregisterDrawable have been added to the library. A related update was made to the description of XtWindowToWidget.
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 XtToolkitThreadInitialize, XtAppLock, XtAppUnlock, XtAppSetExitFlag, and XtAppGetExitFlag. Widget writers may also use XtProcessLock and XtProcessUnlock.
Safe handling of POSIX signals and other asynchronous notifications is now provided by use of XtAppAddSignal, XtNoticeSignal, and XtRemoveSignal.
The application can receive notification of an impending block in the Intrinsics event manager by registering interest through XtAppAddBlockHook and XtRemoveBlockHook.
the most recent event passed to XtDispatchEvent for a specified
13.4.6. 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 prepend and append to the default
search path, which controls resource database construction, by
using the new substitution string, %D.
13.4.7. 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 0x1 100FFFF), 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.
The targets of selection requests may
be parameterized, as described by the revised Inter-Client
Communication Conventions Manual. When such requests are made,
XtSetSelectionParameters is used by the requestor to specify
the target parameters, and XtGetSelectionParameters 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, XtCreateSelectionRequest,
XtCancelSelectionRequest and XtSendSelectionRequest
are used to envelope 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 XtReservePropertyAtom and XtReleasePropertyAtom
13.4.9. External Agent Hooks
External agent hooks were added for
the benefit of applications which 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. Development of one such
protocol is occurring in the Consortium's x-agent working
group for eventual review as a Consortium standard. 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 XtHooksOfDisplay, which returns the hook registration
widget, and XtGetDisplays, which returns a list of the
X displays associated with an application context.
|Contents||Previous Chapter||Next Chapter|