InfoMagic Source Code 1993 July/THE_SOURCE_CODE_CD_ROM.iso/X/mit/doc/Xt/CH13

Text File | 1991-08-27 | 16.1 KB | 487 lines

.\" $XConsortium: CH13,v 1.5 91/08/26 13:41:42 swick Exp $
.\"
.\" Copyright 1985, 1986, 1987, 1988, 1991
.\" Massachusetts Institute of Technology, Cambridge, Massachusetts,
.\" and 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
.\" M.I.T. or Digital not be used in in advertising or publicity pertaining
.\" to distribution of the software without specific, written prior permission.
.\" M.I.T and 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 \- 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 5
.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 XFILESEARCHPATH
and
.PN XUSERFILESEARCHPATH
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 to not
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 is 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.

.bp