DocsTable of Contents
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 the section called “Class Extension Records” 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.
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.
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.
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.
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
semantics.
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.
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.
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.
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.
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.
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.
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.
XtResolvePathname
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.
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.
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
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 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.
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.
The args argument to
XtAppInitialize,
XtVaAppInitialize,
*XtOpenDisplay,
XtDisplayInitialize,
and
XtInitialize
were changed from
Cardinal*
to int* to conform to pre-existing 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 of this.
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 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
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 that do not make use of exact
exposure region information can indicate that the Intrinsics need not
compute the region.
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.
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
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.
A clarification to the specification was made to indicate that geometry requests may include current values along with the requested changes.
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
XtInsertEventTypeHandler
and
XtRemoveEventTypeHandler.
Since the mechanism to indicate selection of extension events is specific
to the extension being used, the Intrinsics introduces
XtRegisterExtensionSelector,
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 nonwidget drawables, such as pixmaps that 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.
XtLastEventProcessed
returns the most recent event passed to
XtDispatchEvent
for a specified display.
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.
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.
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 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
XtReservePropertyAtom
and
XtReleasePropertyAtom.
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
XtHooksOfDisplay,
which returns the hook registration widget, and
XtGetDisplays,
which returns a list of the X displays associated with an application context.