806 lines
27 KiB
Plaintext
806 lines
27 KiB
Plaintext
.\" $Xorg: CH13,v 1.3 2000/08/17 19:42:47 cpqbld Exp $
|
|
.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
|
|
.\" X Consortium
|
|
.\"
|
|
.\" Permission is hereby granted, free of charge, to any person obtaining
|
|
.\" a copy of this software and associated documentation files (the
|
|
.\" "Software"), to deal in the Software without restriction, including
|
|
.\" without limitation the rights to use, copy, modify, merge, publish,
|
|
.\" distribute, sublicense, and/or sell copies of the Software, and to
|
|
.\" permit persons to whom the Software is furnished to do so, subject to
|
|
.\" the following conditions:
|
|
.\"
|
|
.\" The above copyright notice and this permission notice shall be included
|
|
.\" in all copies or substantial portions of the Software.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
|
|
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
|
|
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
|
.\" OTHER DEALINGS IN THE SOFTWARE.
|
|
.\"
|
|
.\" Except as contained in this notice, the name of the X Consortium shall
|
|
.\" not be used in advertising or otherwise to promote the sale, use or
|
|
.\" other dealings in this Software without prior written authorization
|
|
.\" from the X Consortium.
|
|
.\"
|
|
.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
|
|
.\" Digital Equipment Corporation, Maynard, Massachusetts.
|
|
.\"
|
|
.\" Permission to use, copy, modify and distribute this documentation for any
|
|
.\" purpose and without fee is hereby granted, provided that the above copyright
|
|
.\" notice appears in all copies and that both that copyright notice and this
|
|
.\" permission notice appear in supporting documentation, and that the name of
|
|
.\" Digital not be used in in advertising or publicity pertaining
|
|
.\" to distribution of the software without specific, written prior permission.
|
|
.\" Digital makes no representations about the suitability of the
|
|
.\" software described herein for any purpose.
|
|
.\" It is provided ``as is'' without express or implied warranty.
|
|
.\"
|
|
\&
|
|
.sp 1
|
|
.ce 3
|
|
\s+1\fBChapter 13\fP\s-1
|
|
|
|
\s+1\fBEvolution of the \*(xI\fP\s-1
|
|
.sp 2
|
|
.nr H1 13
|
|
.nr H2 0
|
|
.nr H3 0
|
|
.nr H4 0
|
|
.nr H5 0
|
|
.LP
|
|
.XS
|
|
Chapter 13 \(em Evolution of the \*(xI
|
|
.XE
|
|
.LP
|
|
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.
|
|
.LP
|
|
The \*(xI 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.
|
|
.LP
|
|
In particular, widget programmers may wish to conform to the convention
|
|
described in Section 1.6.12 when defining class extension records.
|
|
|
|
.NH 2
|
|
Determining Specification Revision Level
|
|
.XS
|
|
\fB\*(SN Determining Specification Revision Level\fP
|
|
.XE
|
|
.LP
|
|
Widget and application developers who wish to maintain a common source
|
|
pool that will build properly with implementations of the \*(xI
|
|
at different revision levels of these specifications but that take
|
|
advantage of newer features added in later revisions may use the
|
|
symbolic macro
|
|
.PN XtSpecificationRelease .
|
|
.LP
|
|
.Ds 0
|
|
#define XtSpecificationRelease 6
|
|
.De
|
|
.IN "XtSpecificationRelease" "" "@DEF@"
|
|
.LP
|
|
As the symbol
|
|
.PN 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.
|
|
|
|
.NH 2
|
|
Release 3 to Release 4 Compatibility
|
|
.XS
|
|
\fB\*(SN Release 3 to Release 4 Compatibility\fP
|
|
.XE
|
|
.LP
|
|
At the data structure level, Release 4 retains binary compatibility
|
|
with Release 3 (the first X Consortium standard release) for all data
|
|
structures except
|
|
.PN WMShellPart,
|
|
.PN TopLevelShellPart ,
|
|
and
|
|
.PN TransientShellPart .
|
|
Release 4 changed the argument type to most procedures that now take
|
|
arguments of type
|
|
.PN XtPointer
|
|
and structure members that are now of type
|
|
.PN XtPointer
|
|
in order to avoid potential ANSI C conformance problems. It is
|
|
expected that most implementations will be binary compatible with the
|
|
previous definition.
|
|
.LP
|
|
Two fields in
|
|
.PN CoreClassPart
|
|
were changed from
|
|
.PN Boolean
|
|
to
|
|
.PN XtEnum
|
|
to allow implementations additional freedom in specifying the
|
|
representations of each. This change should require no source
|
|
modification.
|
|
|
|
.NH 3
|
|
Additional Arguments
|
|
.XS
|
|
\*(SN Additional Arguments
|
|
.XE
|
|
.LP
|
|
Arguments were added to the procedure definitions for
|
|
.PN XtInitProc ,
|
|
.PN XtSetValuesFunc ,
|
|
and
|
|
.PN 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
|
|
.PN XtInitProc
|
|
and
|
|
.PN 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.
|
|
|
|
.NH 3
|
|
set_values_almost Procedures
|
|
.XS
|
|
\*(SN set_values_almost Procedures
|
|
.XE
|
|
.LP
|
|
The use of the arguments by a set_values_almost procedure was poorly
|
|
described in Release 3 and was inconsistent with other conventions.
|
|
.LP
|
|
The current specification for the manner in which a set_values_almost
|
|
procedure returns information to the \*(xI 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.
|
|
.LP
|
|
No known implementation of the \*(xI correctly implemented the
|
|
Release 3 interface, so it is expected that the impact of this
|
|
specification change is small.
|
|
|
|
.NH 3
|
|
Query Geometry
|
|
.XS
|
|
\*(SN Query Geometry
|
|
.XE
|
|
.LP
|
|
A composite widget layout routine that calls
|
|
.PN 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.
|
|
|
|
.NH 3
|
|
unrealizeCallback Callback List
|
|
.XS
|
|
\*(SN unrealizeCallback Callback List
|
|
.XE
|
|
.LP
|
|
In order to provide a mechanism for widgets to be notified when they
|
|
become unrealized through a call to
|
|
.PN XtUnrealizeWidget ,
|
|
the callback
|
|
list name ``unrealizeCallback'' has been defined by the \*(xI. 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.
|
|
|
|
.NH 3
|
|
Subclasses of WMShell
|
|
.XS
|
|
\*(SN Subclasses of WMShell
|
|
.XE
|
|
.LP
|
|
The formal adoption of the \fI\*(xC\fP as
|
|
an X Consortium standard has meant the addition of four fields to
|
|
.PN WMShellPart
|
|
and one field to
|
|
.PN 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.
|
|
.LP
|
|
To provide more convenience for TransientShells, a field was added
|
|
to the previously empty
|
|
.PN TransientShellPart .
|
|
On some architectures the size of the part structure will not
|
|
have changed as a result of this.
|
|
.LP
|
|
Any widget implementation whose class is a subclass of
|
|
TopLevelShell
|
|
or
|
|
TransientShell
|
|
must at minimum be
|
|
recompiled with the new data structure declarations. Because
|
|
.PN WMShellPart
|
|
no longer contains a contiguous
|
|
.PN XSizeHints
|
|
data structure,
|
|
a subclass that expected to do a single structure assignment of an
|
|
.PN XSizeHints
|
|
structure to the \fIsize_hints\fP field of
|
|
.PN WMShellPart
|
|
must be revised, though the old fields remain at the same positions within
|
|
.PN WMShellPart .
|
|
|
|
.NH 3
|
|
Resource Type Converters
|
|
.XS
|
|
\*(SN Resource Type Converters
|
|
.XE
|
|
.LP
|
|
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.
|
|
.LP
|
|
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
|
|
.PN XtConverter
|
|
was incomplete.
|
|
|
|
.NH 3
|
|
KeySym Case Conversion Procedure
|
|
.XS
|
|
\*(SN KeySym Case Conversion Procedure
|
|
.XE
|
|
.LP
|
|
The specification for the
|
|
.PN 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 \*(xI
|
|
implemented the previously documented interface.
|
|
|
|
.NH 3
|
|
Nonwidget Objects
|
|
.XS
|
|
\*(SN Nonwidget Objects
|
|
.XE
|
|
.LP
|
|
Formal support for nonwidget objects is new to Release 4. A
|
|
prototype implementation was latent in at least one Release 3
|
|
implementation of the \*(xI, but the specification has changed
|
|
somewhat. The most significant change is the requirement for a
|
|
composite widget to declare the
|
|
.PN CompositeClassExtension
|
|
record with the \fIaccepts_objects\fP field set to
|
|
.PN True
|
|
in order to permit a client to create a nonwidget child.
|
|
.LP
|
|
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
|
|
\fIaccept_objects\fP field allows a composite widget to declare that it
|
|
is not prepared to do so.
|
|
|
|
.NH 2
|
|
Release 4 to Release 5 Compatibility
|
|
.XS
|
|
\fB\*(SN Release 4 to Release 5 Compatibility\fP
|
|
.XE
|
|
.LP
|
|
At the data structure level, Release 5 retains complete binary
|
|
compatibility with Release 4. The specification of the
|
|
.PN ObjectPart ,
|
|
.PN RectObjPart ,
|
|
.PN CorePart ,
|
|
.PN CompositePart ,
|
|
.PN ShellPart ,
|
|
.PN WMShellPart ,
|
|
.PN TopLevelShellPart ,
|
|
and
|
|
.PN 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
|
|
.PN XrmValue
|
|
and
|
|
.PN XrmOptionDescRec
|
|
was updated to use a new type,
|
|
.PN XPointer ,
|
|
for the \fIaddr\fP and \fIvalue\fP fields, respectively, to avoid
|
|
ANSI C conformance problems. The definition of
|
|
.PN XPointer
|
|
is binary compatible with the previous implementation.
|
|
|
|
.NH 3
|
|
baseTranslations Resource
|
|
.XS
|
|
\fB\*(SN baseTranslations Resource\fP
|
|
.XE
|
|
|
|
.LP
|
|
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''.
|
|
.LP
|
|
Applications wishing to take advantage of the new functionality
|
|
would change their application defaults file, e.g., from
|
|
.Ds
|
|
app.widget.translations: \fIvalue\fP
|
|
.DE
|
|
to
|
|
.Ds
|
|
app.widget.baseTranslations: \fIvalue\fP
|
|
.DE
|
|
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.
|
|
|
|
.NH 3
|
|
Resource File Search Path
|
|
.XS
|
|
\fB\*(SN Resource File Search Path\fP
|
|
.XE
|
|
|
|
.LP
|
|
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
|
|
.PN \s-1XFILESEARCHPATH\s+1
|
|
and
|
|
.PN \s-1XUSERFILESEARCHPATH\s+1
|
|
values when overriding the system defaults.
|
|
|
|
.NH 3
|
|
Customization Resource
|
|
.XS
|
|
\fB\*(SN Customization Resource\fP
|
|
.XE
|
|
|
|
.LP
|
|
.PN 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.
|
|
|
|
.NH 3
|
|
Per-Screen Resource Database
|
|
.XS
|
|
\fB\*(SN Per-Screen Resource Database\fP
|
|
.XE
|
|
|
|
.LP
|
|
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 \*(xI
|
|
database initialization. Such applications will need to be aware
|
|
of the particular screen on which each shell widget is to be created.
|
|
.LP
|
|
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
|
|
.PN XtResolvePathname .
|
|
|
|
.NH 3
|
|
Internationalization of Applications
|
|
.XS
|
|
\fB\*(SN Internationalization of Applications\fP
|
|
.XE
|
|
|
|
.LP
|
|
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 \*(xI
|
|
the restrictions of this model have been followed.
|
|
In particular, the new \*(xI interfaces are designed not to
|
|
preclude an application from using other alternatives.
|
|
For this reason, no \*(xI 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.
|
|
.LP
|
|
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
|
|
.PN XtSetLanguageProc
|
|
to do so.
|
|
.LP
|
|
The internationalization additions also define event filters
|
|
as a part of the Xlib Input Method specifications. The
|
|
\*(xI enable the use of event filters through additions to
|
|
.PN XtDispatchEvent .
|
|
Applications that may not be dispatching all events through
|
|
.PN XtDispatchEvent
|
|
should be reviewed in the context of this new input method mechanism.
|
|
.LP
|
|
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 \*(xI to locate the database from localization information
|
|
supplied by the client.
|
|
.LP
|
|
The previous specification for the syntax of the language string
|
|
specified by
|
|
.PN 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.
|
|
|
|
.NH 3
|
|
Permanently Allocated Strings
|
|
.XS
|
|
\*(SN Permanently Allocated Strings
|
|
.XE
|
|
|
|
.LP
|
|
In order to permit additional memory savings, an Xlib interface was
|
|
added to allow the resource manager to avoid copying certain string
|
|
constants. The \*(xI specification was updated to explicitly require
|
|
the Object \fIclass_name\fP, \fIresource_name\fP, \fIresource_class\fP,
|
|
\fIresource_type\fP, \fIdefault_type\fP in resource tables, Core \fIactions\fP
|
|
\fIstring\fP field, and Constraint \fIresource_name\fP, \fIresource_class\fP,
|
|
\fIresource_type\fP, and \fIdefault_type\fP resource fields to be
|
|
permanently allocated. This explicit requirement is expected to
|
|
affect only applications that may create and destroy classes
|
|
on the fly.
|
|
|
|
.NH 3
|
|
Arguments to Existing Functions
|
|
.XS
|
|
\fB\*(SN Arguments to Existing Functions\fP
|
|
.XE
|
|
|
|
.LP
|
|
The \fIargs\fP argument to
|
|
.PN XtAppInitialize ,
|
|
.PN XtVaAppInitialize ,
|
|
.PN XtOpenDisplay ,
|
|
.PN XtDisplayInitialize ,
|
|
and
|
|
.PN XtInitialize
|
|
were changed from
|
|
.PN Cardinal *
|
|
to int* to conform to pre-existing convention and avoid otherwise
|
|
annoying typecasting in ANSI C environments.
|
|
|
|
.NH 2
|
|
Release 5 to Release 6 Compatibility
|
|
.XS
|
|
\fB\*(SN Release 5 to Release 6 Compatibility\fP
|
|
.XE
|
|
.LP
|
|
At the data structure level, Release 6 retains binary compatibility
|
|
with Release 5 for all data structures except
|
|
.PN 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.
|
|
|
|
.NH 3
|
|
Widget Internals
|
|
.XS
|
|
\*(SN Widget Internals
|
|
.XE
|
|
.LP
|
|
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.
|
|
.LP
|
|
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.
|
|
.LP
|
|
As a convenience, an interface to locate a widget class extension
|
|
record on a linked list,
|
|
.PN XtGetClassExtension ,
|
|
has been added.
|
|
.LP
|
|
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 \fBTrue\fP in the
|
|
extension record.
|
|
.LP
|
|
The wording of the process followed by
|
|
.PN XtUnmanageChildren
|
|
has changed slightly to better handle changes to the managed set
|
|
during phase 2 destroy processing.
|
|
.LP
|
|
A new exposure event compression flag,
|
|
.PN 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 \*(xI need not
|
|
compute the region.
|
|
|
|
.NH 3
|
|
General Application Development
|
|
.XS
|
|
\*(SN General Application Development
|
|
.XE
|
|
.LP
|
|
.PN 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,
|
|
.PN 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.
|
|
.LP
|
|
The toolkit initialization function
|
|
.PN XtToolkitInitialize
|
|
may be called multiple times without penalty.
|
|
.LP
|
|
In order to optimize changes in geometry to a set of geometry-managed
|
|
children, a new interface,
|
|
.PN XtChangeManagedSet ,
|
|
has been added.
|
|
|
|
.NH 3
|
|
Communication with Window and Session Managers
|
|
.XS
|
|
\*(SN Communication with Window and Session Managers
|
|
.XE
|
|
.LP
|
|
The revision of the \fI\*(xC\fP as an X Consortium standard has resulted
|
|
in the addition of three fields to the specification of
|
|
.PN WMShellPart .
|
|
These are \fIurgency\fP, \fIclient_leader\fP, and \fIwindow_role\fP.
|
|
.LP
|
|
The adoption of the \fIX Session Management Protocol\fP as an X Consortium
|
|
standard has resulted in the addition of a new shell widget,
|
|
.PN SessionShell ,
|
|
and an accompanying subclass verification interface,
|
|
.PN 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
|
|
.PN ApplicationShell ,
|
|
the
|
|
.PN ApplicationShell
|
|
was subclassed to create the new widget class.
|
|
The session protocol requires a modal response to certain checkpointing
|
|
operations by participating applications. The
|
|
.PN 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
|
|
.PN XtSessionGetToken
|
|
and
|
|
.PN XtSessionReturnToken .
|
|
There is also a new command line argument, -xtsessionID, which facilitates
|
|
the session manager in restarting applications based on the \*(xI.
|
|
.LP
|
|
The resource name and class strings defined by the \*(xI shell
|
|
widgets in
|
|
.Pn < X11/Shell.h >
|
|
are now listed in Appendix E. The addition of a new symbol
|
|
for the
|
|
.PN WMShell
|
|
\fIwait_for_wm\fP resource was made to bring the external symbol
|
|
and the string it represents into agreement. The actual resource name
|
|
string in
|
|
.PN WMShell
|
|
has not changed.
|
|
The resource representation type of the XtNwinGravity resource of the
|
|
.PN WMShell
|
|
was changed to XtRGravity in order to register a type
|
|
converter so that window gravity resource values could be specified by name.
|
|
|
|
.NH 3
|
|
Geometry Management
|
|
.XS
|
|
\*(SN Geometry Management
|
|
.XE
|
|
.LP
|
|
A clarification to the specification was made to indicate that geometry
|
|
requests may include current values along with the requested changes.
|
|
|
|
.NH 3
|
|
Event Management
|
|
.XS
|
|
\*(SN Event Management
|
|
.XE
|
|
.LP
|
|
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
|
|
.PN XtInsertEventTypeHandler
|
|
and
|
|
.PN XtRemoveEventTypeHandler .
|
|
Since the mechanism to indicate selection of extension events is specific
|
|
to the extension being used, the \*(xI introduces
|
|
.PN 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 \*(xI event dispatcher may now be replaced or enveloped
|
|
by the application with
|
|
.PN XtSetEventDispatcher .
|
|
The dispatcher may wish to call
|
|
.PN XtGetKeyboardFocusWidget
|
|
to determine the widget with the current \*(xI keyboard focus.
|
|
A dispatcher, after determining the destination widget, may use
|
|
.PN XtDispatchEventToWidget
|
|
to cause the event to be dispatched to the event handlers registered
|
|
by a specific widget.
|
|
.LP
|
|
To permit the dispatching of events
|
|
for nonwidget drawables, such as pixmaps that are not associated
|
|
with a widget's window,
|
|
.PN XtRegisterDrawable
|
|
and
|
|
.PN XtUnregisterDrawable
|
|
have been added to the library. A related update was made to
|
|
the description of
|
|
.PN XtWindowToWidget .
|
|
.LP
|
|
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
|
|
.PN XtToolkitThreadInitialize ,
|
|
.PN XtAppLock ,
|
|
.PN XtAppUnlock ,
|
|
.PN XtAppSetExitFlag ,
|
|
and
|
|
.PN XtAppGetExitFlag .
|
|
Widget writers may also use
|
|
.PN XtProcessLock
|
|
and
|
|
.PN XtProcessUnlock .
|
|
.LP
|
|
Safe handling of POSIX signals and other asynchronous notifications
|
|
is now provided by use of
|
|
.PN XtAppAddSignal ,
|
|
.PN XtNoticeSignal ,
|
|
and
|
|
.PN XtRemoveSignal .
|
|
.LP
|
|
The application can receive notification of an impending block
|
|
in the \*(xI event manager by registering interest through
|
|
.PN XtAppAddBlockHook
|
|
and
|
|
.PN XtRemoveBlockHook .
|
|
.LP
|
|
.PN XtLastEventProcessed
|
|
returns the most recent event passed to
|
|
.PN XtDispatchEvent
|
|
for a specified display.
|
|
|
|
.NH 3
|
|
Resource Management
|
|
.XS
|
|
\*(SN Resource Management
|
|
.XE
|
|
.LP
|
|
Resource converters are registered by the \*(xI for window gravity
|
|
and for three new resource types associated with session participation:
|
|
RestartStyle, CommandArgArray and DirectoryString.
|
|
.LP
|
|
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.
|
|
|
|
.NH 3
|
|
Translation Management
|
|
.XS
|
|
\*(SN Translation Management
|
|
.XE
|
|
.LP
|
|
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.
|
|
|
|
.NH 3
|
|
Selections
|
|
.XS
|
|
\*(SN Selections
|
|
.XE
|
|
.LP
|
|
The targets of selection requests may be parameterized, as described
|
|
by the revised \fI\*(xC\fP.
|
|
When such requests are made,
|
|
.PN XtSetSelectionParameters
|
|
is used by the requestor to specify the target parameters and
|
|
.PN 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,
|
|
.PN XtCreateSelectionRequest ,
|
|
.PN XtCancelSelectionRequest ,
|
|
and
|
|
.PN XtSendSelectionRequest
|
|
are used to envelop the assembly of the request.
|
|
When the parameters themselves are the names of properties,
|
|
the \*(xI provides support for the economical use of property atom names;
|
|
see
|
|
.PN XtReservePropertyAtom
|
|
and
|
|
.PN XtReleasePropertyAtom .
|
|
|
|
.NH 3
|
|
External Agent Hooks
|
|
.XS
|
|
\*(SN External Agent Hooks
|
|
.XE
|
|
.LP
|
|
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
|
|
.PN XtHooksOfDisplay ,
|
|
which returns the hook registration widget, and
|
|
.PN XtGetDisplays ,
|
|
which returns a list of the X displays associated with an application context.
|
|
.bp
|