Index: Makefile
===================================================================
--- Makefile (nonexistent)
+++ Makefile (revision 5)
@@ -0,0 +1,56 @@
+
+COMPONENT_TARGETS = $(HARDWARE_NOARCH)
+
+
+include ../../../../build-system/constants.mk
+
+
+url = $(DOWNLOAD_SERVER)/sources/X.org/lib/libXt
+
+versions = 1.2.1
+pkgname = libXt
+suffix = tar.bz2
+
+tarballs = $(addsuffix .$(suffix), $(addprefix $(pkgname)-, $(versions)))
+sha1s = $(addsuffix .sha1sum, $(tarballs))
+
+patches = $(CURDIR)/patches/libXt-1.2.1-docbook.patch
+
+.NOTPARALLEL: $(patches)
+
+
+BUILD_TARGETS = $(tarballs) $(sha1s) $(patches)
+
+
+include ../../../../build-system/core.mk
+
+
+.PHONY: download_clean
+
+
+$(tarballs):
+ @echo -e "\n======= Downloading source tarballs =======" ; \
+ for tarball in $(tarballs) ; do \
+ echo "$(url)/$$tarball" | xargs -n 1 -P 100 wget $(WGET_OPTIONS) - & \
+ done ; wait
+
+$(sha1s): $(tarballs)
+ @for sha in $@ ; do \
+ echo -e "\n======= Downloading '$$sha' signature =======\n" ; \
+ echo "$(url)/$$sha" | xargs -n 1 -P 100 wget $(WGET_OPTIONS) - & wait %1 ; \
+ touch $$sha ; \
+ echo -e "\n======= Check the '$$sha' sha1sum =======\n" ; \
+ sha1sum --check $$sha ; ret="$$?" ; \
+ if [ "$$ret" == "1" ]; then \
+ echo -e "\n======= ERROR: Bad '$$sha' sha1sum =======\n" ; \
+ exit 1 ; \
+ fi ; \
+ done
+
+$(patches): $(sha1s)
+ @echo -e "\n======= Create Patches =======\n" ; \
+ ( cd create-1.2.1-docbook-patch ; ./create.patch.sh ) ; \
+ echo -e "\n"
+
+download_clean:
+ @rm -f $(tarballs) $(sha1s) $(patches)
Index: create-1.2.1-docbook-patch/create.patch.sh
===================================================================
--- create-1.2.1-docbook-patch/create.patch.sh (nonexistent)
+++ create-1.2.1-docbook-patch/create.patch.sh (revision 5)
@@ -0,0 +1,15 @@
+#!/bin/sh
+
+VERSION=1.2.1
+
+tar --files-from=file.list -xjvf ../libXt-$VERSION.tar.bz2
+mv libXt-$VERSION libXt-$VERSION-orig
+
+cp -rf ./libXt-$VERSION-new ./libXt-$VERSION
+
+diff --unified -Nr libXt-$VERSION-orig libXt-$VERSION > libXt-$VERSION-docbook.patch
+
+mv libXt-$VERSION-docbook.patch ../patches
+
+rm -rf ./libXt-$VERSION
+rm -rf ./libXt-$VERSION-orig
Property changes on: create-1.2.1-docbook-patch/create.patch.sh
___________________________________________________________________
Added: svn:executable
## -0,0 +1 ##
+*
\ No newline at end of property
Index: create-1.2.1-docbook-patch/file.list
===================================================================
--- create-1.2.1-docbook-patch/file.list (nonexistent)
+++ create-1.2.1-docbook-patch/file.list (revision 5)
@@ -0,0 +1,7 @@
+libXt-1.2.1/specs/CH02.xml
+libXt-1.2.1/specs/CH04.xml
+libXt-1.2.1/specs/CH06.xml
+libXt-1.2.1/specs/CH07.xml
+libXt-1.2.1/specs/CH09.xml
+libXt-1.2.1/specs/CH10.xml
+libXt-1.2.1/specs/CH11.xml
Index: create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH02.xml
===================================================================
--- create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH02.xml (nonexistent)
+++ create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH02.xml (revision 5)
@@ -0,0 +1,4540 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<chapter id='Widget_Instantiation'>
+<title>Widget Instantiation</title>
+<para>
+A hierarchy of widget instances constitutes a widget tree.
+The shell widget returned by
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
+is the root of the widget tree instance.
+The widgets with one or more children are the intermediate nodes of that tree,
+and the widgets with no children of any kind are the leaves of the widget tree.
+With the exception of pop-up children (see <xref linkend='Pop_Up_Widgets' />),
+this widget tree instance defines the associated X Window tree.
+</para>
+
+<para>
+Widgets can be either composite or primitive.
+Both kinds of widgets can contain children,
+but the Intrinsics provide a set of management mechanisms for constructing
+and interfacing between composite widgets, their children, and
+other clients.
+</para>
+
+<para>
+Composite widgets, that is, members of the class
+<function>compositeWidgetClass</function>,
+are containers for an arbitrary,
+but widget implementation-defined, collection of children,
+which may be instantiated by the composite widget itself,
+by other clients, or by a combination of the two.
+Composite widgets also contain methods for managing the geometry (layout)
+of any child widget.
+Under unusual circumstances,
+a composite widget may have zero children,
+but it usually has at least one.
+By contrast,
+primitive widgets that contain children typically instantiate
+specific children of known classes themselves and do not expect external
+clients to do so.
+Primitive widgets also do not have general geometry management methods.
+</para>
+
+<para>
+In addition,
+the Intrinsics recursively perform many operations
+(for example, realization and destruction)
+on composite widgets and all their children.
+Primitive widgets that have children must be prepared
+to perform the recursive operations themselves on behalf of their children.
+</para>
+
+<para>
+A widget tree is manipulated by several Intrinsics functions.
+For example,
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+traverses the tree downward and recursively realizes all
+pop-up widgets and children of composite widgets.
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+traverses the tree downward and destroys all pop-up widgets
+and children of composite widgets.
+The functions that fetch and modify resources traverse the tree upward
+and determine the inheritance of resources from a widget's ancestors.
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+traverses the tree up one level and calls the geometry manager
+that is responsible for a widget child's geometry.
+</para>
+
+<para>
+To facilitate upward traversal of the widget tree,
+each widget has a pointer to its parent widget.
+The
+Shell
+widget that
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
+returns has a <emphasis remap='I'>parent</emphasis> pointer of NULL.
+</para>
+
+<para>
+To facilitate downward traversal of the widget tree,
+the <emphasis remap='I'>children</emphasis> field of
+each composite widget is a pointer to an array of child widgets,
+which includes all normal children created,
+not just the subset of children that are managed by the composite widget's
+geometry manager.
+Primitive widgets
+that instantiate children are entirely responsible for all operations
+that require downward traversal below themselves.
+In addition,
+every widget has a pointer to an array of pop-up children.
+</para>
+
+<sect1 id="Initializing_the_tk">
+<title>Initializing the X Toolkit</title>
+<para>
+Before an application can call any Intrinsics function
+other than
+<function>XtSetLanguageProc</function>
+and
+<xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/>,
+it must initialize the Intrinsics by using
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>,
+which initializes the Intrinsics internals
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>,
+which initializes the per-application state
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+or
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>,
+which initializes the per-display state
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>,
+which creates the root of a widget tree
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+Or an application can call the convenience procedure
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>,
+which combines the functions of the preceding procedures.
+An application wishing to use the ANSI C locale mechanism should call
+<function>XtSetLanguageProc</function>
+prior to calling
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>,
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>,
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>,
+or
+<xref linkend='XtAppInitialize' xrefstyle='select: title'/>.
+</para>
+
+<para>
+Multiple instances of X Toolkit applications may be implemented
+in a single address space.
+Each instance needs to be able to read
+input and dispatch events independently of any other instance.
+Further, an application instance may need multiple display connections
+to have widgets on multiple displays.
+From the application's point of view, multiple display connections
+usually are treated together as a single unit
+for purposes of event dispatching.
+To accommodate both requirements,
+the Intrinsics define application contexts,
+each of which provides the information needed to distinguish one application
+instance from another.
+The major component of an application context is a list of one or more X
+<function>Display</function>
+pointers for that application.
+The Intrinsics handle all display connections within a single application
+context simultaneously, handling input in a round-robin fashion.
+The application context type
+<function>XtAppContext</function>
+is opaque to clients.
+</para>
+
+<para>
+To initialize the Intrinsics internals, use
+<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtToolkitInitialize'>
+<funcprototype>
+ <funcdef>void <function>XtToolkitInitialize</function></funcdef>
+ <paramdef><parameter>void</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+If
+<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>
+was previously called, it returns immediately.
+When
+<xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/>
+is called before
+<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>,
+the latter is protected against
+simultaneous activation by multiple threads.
+</para>
+
+<para>
+To create an application context, use
+<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCreateApplicationContext'>
+<funcprototype>
+ <funcdef>XtAppContext <function>XtCreateApplicationContext</function></funcdef>
+ <paramdef><parameter>void</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<para>
+The
+<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>
+function returns an application context,
+which is an opaque type.
+Every application must have at least one application context.
+</para>
+
+<para>
+To destroy an application context and close any
+remaining display connections in it, use
+<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtDestroyApplicationContext'>
+<funcprototype>
+ <funcdef>void <function>XtDestroyApplicationContext</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>
+function destroys the specified application context.
+If called from within an event dispatch (for example, in a callback procedure),
+<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>
+does not destroy the application context until the dispatch is complete.
+</para>
+
+<para>
+To get the application context in which a given widget was created, use
+<xref linkend='XtWidgetToApplicationContext' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtWidgetToApplicationContext'>
+<funcprototype>
+ <funcdef>XtAppContext <function>XtWidgetToApplicationContext</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which you want the application context. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtWidgetToApplicationContext' xrefstyle='select: title'/>
+function returns the application context for the specified widget.
+</para>
+
+<para>
+To initialize a display and add it to an application context, use
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtDisplayInitialize'>
+<funcprototype>
+ <funcdef>void <function>XtDisplayInitialize</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>Display * <parameter>display</parameter></paramdef>
+ <paramdef>const char * <parameter>application_name</parameter></paramdef>
+ <paramdef>const char * <parameter>application_class</parameter></paramdef>
+ <paramdef>XrmOptionDescRec * <parameter>options</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_options</parameter></paramdef>
+ <paramdef>int * <parameter>argc</parameter></paramdef>
+ <paramdef>char ** <parameter>argv</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a previously opened display connection. Note that a single
+display connection can be in at most one application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the application instance.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class name of this application,
+which is usually the generic name for all instances of this application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies how to parse the command line for any application-specific resources.
+The <emphasis remap='I'>options</emphasis> argument is passed as a parameter to
+<function>XrmParseCommand</function>.
+For further information,
+see Parsing Command Line Options in Xlib — C Language X Interface and <xref linkend='Parsing_the_Command_Line' /> of this specification.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the options list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the number of command line parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of command line parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+function retrieves the language string to be
+used for the specified display (see <xref linkend='Finding_File_Names' />),
+calls the language procedure (if set) with that language string,
+builds the resource database for the default screen, calls the Xlib
+<function>XrmParseCommand</function>
+function to parse the command line,
+and performs other per-display initialization.
+After
+<function>XrmParseCommand</function>
+has been called,
+<emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis> contain only those parameters that
+were not in the standard option table or in the table specified by the
+<emphasis remap='I'>options</emphasis> argument.
+If the modified <emphasis remap='I'>argc</emphasis> is not zero,
+most applications simply print out the modified <emphasis remap='I'>argv</emphasis> along with a message
+listing the allowable options.
+On POSIX-based systems,
+the application name is usually the final component of <emphasis remap='I'>argv</emphasis>[0].
+If the synchronous resource is
+<function>True</function>,
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+calls the Xlib
+<function>XSynchronize</function>
+function to put Xlib into synchronous mode for this display connection
+and any others currently open in the application context.
+See <xref linkend='Loading_the_Resource_Database' />
+and <xref linkend='Parsing_the_Command_Line' />
+for details on the <emphasis remap='I'>application_name</emphasis>,
+<emphasis remap='I'>application_class</emphasis>, <emphasis remap='I'>options</emphasis>, and <emphasis remap='I'>num_options</emphasis> arguments.
+</para>
+
+<para>
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+calls
+<function>XrmSetDatabase</function>
+to associate the resource database of the default screen with the
+display before returning.
+</para>
+
+<para>
+To open a display, initialize it, and then
+add it to an application context, use
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtOpenDisplay'>
+<funcprototype>
+ <funcdef>Display *<function>XtOpenDisplay</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>const char * <parameter>display_string</parameter></paramdef>
+ <paramdef>const char * <parameter>application_name</parameter></paramdef>
+ <paramdef>const char * <parameter>application_class</parameter></paramdef>
+ <paramdef>XrmOptionDescRec * <parameter>options</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_options</parameter></paramdef>
+ <paramdef>int * <parameter>argc</parameter></paramdef>
+ <paramdef>char ** <parameter>argv</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display_string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display string, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the application instance, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class name of this application,
+which is usually the generic name for all instances of this application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies how to parse the command line for any application-specific resources.
+The options argument is passed as a parameter to
+<function>XrmParseCommand</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the options list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the number of command line parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of command line parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
+function calls
+<function>XOpenDisplay</function>
+with the specified <emphasis remap='I'>display_string</emphasis>.
+If <emphasis remap='I'>display_string</emphasis> is NULL,
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
+uses the current value of the -display option specified in <emphasis remap='I'>argv</emphasis>.
+If no display is specified in <emphasis remap='I'>argv</emphasis>,
+the user's default display is retrieved from the environment.
+On POSIX-based systems,
+this is the value of the
+<emphasis role='strong'>DISPLAY</emphasis>
+environment variable.
+</para>
+
+<para>
+If this succeeds,
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
+then calls
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+and passes it the opened display and
+the value of the -name option specified in <emphasis remap='I'>argv</emphasis> as the application name.
+If no -name option is specified
+and <emphasis remap='I'>application_name</emphasis> is
+non-NULL, <emphasis remap='I'>application_name</emphasis> is passed to
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
+If <emphasis remap='I'>application_name</emphasis> is NULL and if the environment variable
+<emphasis role='strong'>RESOURCE_NAME</emphasis>
+is set, the value of
+<emphasis role='strong'>RESOURCE_NAME</emphasis>
+is used. Otherwise, the application
+name is the name used to invoke the program. On implementations that
+conform to ANSI C Hosted Environment support, the application name will
+be <emphasis remap='I'>argv</emphasis>[0] less any directory and file type components, that is, the
+final component of <emphasis remap='I'>argv</emphasis>[0], if specified. If <emphasis remap='I'>argv</emphasis>[0] does not exist or
+is the empty string, the application name is “main”.
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
+returns the newly opened display or NULL if it failed.
+</para>
+
+<para>
+See <xref linkend='Using_the_Intrinsics_in_a_Multi_Threaded_Environment' />
+for information regarding the use of
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
+in multiple threads.
+</para>
+
+<para>
+To close a display and remove it from an application context, use
+<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCloseDisplay'>
+<funcprototype>
+ <funcdef>void <function>XtCloseDisplay</function></funcdef>
+ <paramdef>Display * <parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
+function calls
+<function>XCloseDisplay</function>
+with the specified <emphasis remap='I'>display</emphasis> as soon as it is safe to do so.
+If called from within an event dispatch (for example, a callback procedure),
+<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
+does not close the display until the dispatch is complete.
+Note that applications need only call
+<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
+if they are to continue executing after closing the display;
+otherwise, they should call
+<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>.
+</para>
+
+<para>
+See <xref linkend='Using_the_Intrinsics_in_a_Multi_Threaded_Environment' />
+for information regarding the use of
+<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
+in multiple threads.
+</para>
+</sect1>
+
+<sect1 id="Establishing_the_Locale">
+<title>Establishing the Locale</title>
+<para>
+Resource databases are specified to be created in the current process
+locale. During display initialization prior to creating the
+per-screen resource database, the Intrinsics will call out to a specified
+application procedure to set the locale according to options found on
+the command line or in the per-display resource specifications.
+</para>
+
+<para>
+The callout procedure provided by the application is of type
+<function>XtLanguageProc</function>.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>typedef String <function>(*XtLanguageProc)</function></funcdef>
+ <paramdef>Display <parameter>display</parameter></paramdef>
+ <paramdef>String <parameter>language</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the display.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>language</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the initial language value obtained from the command line
+or server per-display resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the additional client data specified in the call to
+<function>XtSetLanguageProc</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+The language procedure allows an application to set the locale to
+the value of the language resource determined by
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
+The function returns a new language string that
+will be subsequently used by
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+to establish the path for loading resource files. The returned
+string will be copied by the Intrinsics into new memory.
+</para>
+
+<para>
+Initially, no language procedure is set by the Intrinsics.
+To set the language procedure for use by
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>,
+use
+<function>XtSetLanguageProc</function>.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XtLanguageProc <function>XtSetLanguageProc</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtLanguageProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context in which the language procedure is
+to be used, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the language procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional client data to be passed to the language
+procedure when it is called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XtSetLanguageProc</function>
+sets the language procedure that will be called from
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+for all subsequent Displays initialized in the specified application
+context. If <emphasis remap='I'>app_context</emphasis> is NULL, the specified language
+procedure is registered in all application contexts created by the
+calling process, including any future application contexts that may
+be created. If <emphasis remap='I'>proc</emphasis> is NULL, a default language procedure is
+registered.
+<function>XtSetLanguageProc</function>
+returns the previously registered language procedure.
+If a language procedure has not yet been registered, the return value
+is unspecified, but if this return value is used in a subsequent call to
+<function>XtSetLanguageProc</function>,
+it will cause the default language procedure to be registered.
+</para>
+
+<para>
+The default language procedure does the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Sets the locale according to the environment. On ANSI C-based
+systems this is done by calling
+<function>setlocale</function>(
+<function>LC_ALL</function>,
+<emphasis remap='I'>language</emphasis> ).
+If an error is encountered, a warning message is issued with
+<xref linkend='XtWarning' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calls
+<function>XSupportsLocale</function>
+to verify that the current locale is supported.
+If the locale is not supported, a warning message is issued with
+<xref linkend='XtWarning' xrefstyle='select: title'/>
+and the locale is set to “C”.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calls
+<function>XSetLocaleModifiers</function>
+specifying the empty string.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Returns the value of the current locale. On ANSI C-based systems this
+is the return value from a final call to
+<function>setlocale</function>(
+<function>LC_ALL</function>,
+NULL ).
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+A client wishing to use this mechanism to establish locale can do so
+by calling
+<function>XtSetLanguageProc</function>
+prior to
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>,
+as in the following example.
+</para>
+<programlisting>
+ Widget top;
+ XtSetLanguageProc(NULL, NULL, NULL);
+ top = XtOpenApplication(...);
+ ...
+</programlisting>
+</sect1>
+
+<sect1 id="Loading_the_Resource_Database">
+<title>Loading the Resource Database</title>
+<para>
+The
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+function first determines the language
+string to be used for the specified display. It then
+creates a resource database for the default screen of the display by
+combining the following sources in order, with the entries in the
+first named source having highest precedence:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Application command line (<emphasis remap='I'>argc</emphasis>, <emphasis remap='I'>argv</emphasis>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Per-host user environment resource file on the local host.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Per-screen resource specifications from the server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Per-display resource specifications from the server or from
+the user preference file on the local host.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Application-specific user resource file on the local host.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Application-specific class resource file on the local host.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+When the resource database for a particular screen on the display
+is needed (either internally, or when
+<xref linkend='XtScreenDatabase' xrefstyle='select: title'/>
+is called),
+it is created in the following manner using the sources listed
+above in the same order:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+A temporary database, the “server resource database”, is
+created from the string returned by
+<function>XResourceManagerString</function>
+or, if
+<function>XResourceManagerString</function>
+returns NULL, the contents of a resource file in the user's home
+directory. On POSIX-based systems, the usual name for this user
+preference resource file is $HOME/<function>.Xdefaults</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If a language procedure has been set,
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+first searches the command line for the option “-xnlLanguage”, or
+for a -xrm option that specifies the xnlLanguage/XnlLanguage resource,
+as specified by Section 2.4.
+If such a resource is found, the value is assumed to be
+entirely in XPCS, the X Portable Character Set. If neither option is
+specified on the command line,
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+queries the server resource database (which is assumed to be entirely
+in XPCS) for the resource
+<emphasis remap='I'>name</emphasis><function>.xnlLanguage</function>, class <emphasis remap='I'>Class</emphasis><function>.XnlLanguage</function>
+where <emphasis remap='I'>name</emphasis>
+and <emphasis remap='I'>Class</emphasis> are the <emphasis remap='I'>application_name</emphasis> and
+<emphasis remap='I'>application_class</emphasis> specified to
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
+The language procedure is then invoked with
+the resource value if found, else the empty string. The
+string returned from the language procedure is saved for all future
+references in the Intrinsics that require the per-display language string.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The screen resource database is initialized by parsing the command
+line in the manner specified by Section 2.4.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If a language procedure has not been set,
+the initial database is then queried for the resource
+<emphasis remap='I'>name</emphasis><function>.xnlLanguage</function>, class <emphasis remap='I'>Class</emphasis><function>.XnlLanguage</function>
+as specified above.
+If this database query fails, the server resource database is
+queried; if this query also fails, the language is determined from
+the environment; on POSIX-based systems, this is done by retrieving the
+value of the
+<emphasis role='strong'>LANG</emphasis>
+environment variable. If no language string is
+found, the empty string is used.
+This language string is saved for all future references in the Intrinsics
+that require the per-display language string.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+After determining the language string, the user's environment resource
+file is then merged into the initial resource database if the file exists.
+This file is user-, host-, and process-specific and is expected to
+contain user preferences that are to override those specifications in
+the per-display and per-screen resources.
+On POSIX-based systems, the user's environment resource file name is
+specified by the value of the
+<emphasis role='strong'>XENVIRONMENT</emphasis>
+environment variable.
+If this environment variable does not exist, the user's home directory
+is searched for a file named
+<function>.Xdefaults-</function><emphasis>host</emphasis>,
+where <emphasis remap='I'>host</emphasis> is the host name of the machine on which the
+application is running.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The per-screen resource specifications are then merged into the screen
+resource database, if they exist. These specifications are the string
+returned by
+<function>XScreenResourceString</function>
+for the respective screen and are owned entirely by the user.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Next, the server resource database created earlier is merged into the
+screen resource database. The server property, and corresponding user
+preference file, are owned and constructed entirely by the user.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The application-specific user resource file from the local host is
+then merged into the screen resource database.
+This file contains user customizations and is stored
+in a directory owned by the user.
+Either the user or the application or both can store resource specifications
+in the file. Each should be prepared to find and respect entries made
+by the other.
+The file name is found by calling
+<function>XrmSetDatabase</function>
+with the current screen resource database, after preserving the
+original display-associated database, then calling
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
+with the parameters
+(<emphasis remap='I'>display</emphasis>, NULL, NULL, NULL, <emphasis remap='I'>path</emphasis>, NULL, 0, NULL),
+where <emphasis remap='I'>path</emphasis> is defined in an operating-system-specific way.
+On POSIX-based systems, <emphasis remap='I'>path</emphasis> is defined to be the value
+of the environment variable
+<emphasis role='strong'>XUSERFILESEARCHPATH</emphasis>
+if this is defined. If
+<emphasis role='strong'>XUSERFILESEARCHPATH</emphasis>
+is not defined, an implementation-dependent default value is used.
+This default value is constrained in the following manner:
+ </para>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If the environment variable
+<emphasis role='strong'>XAPPLRESDIR</emphasis>
+is not defined, the default
+<emphasis role='strong'>XUSERFILESEARCHPATH</emphasis>
+must contain at least six entries. These entries must contain
+$HOME as the directory prefix, plus the following substitutions:
+ </para>
+<programlisting>
+1. %C, %N, %L or %C, %N, %l, %t, %c
+2. %C, %N, %l
+3. %C, %N
+4. %N, %L or %N, %l, %t, %c
+5. %N, %l
+6. %N
+</programlisting>
+ <para>
+The order of these six entries within the path must be as given above.
+The order and use of substitutions within a given entry are
+implementation-dependent.
+ </para>
+ </listitem>
+ <listitem>
+ <para> If
+<emphasis role='strong'>XAPPLRESDIR</emphasis>
+is defined, the default
+<emphasis role='strong'>XUSERFILESEARCHPATH</emphasis>
+must contain at least seven entries. These entries must contain the
+following directory prefixes and substitutions:
+ </para>
+<programlisting>
+1. $XAPPLRESDIR with %C, %N, %L or %C, %N, %l, %t, %c
+2. $XAPPLRESDIR with %C, %N, %l
+3. $XAPPLRESDIR with %C, %N
+4. $XAPPLRESDIR with %N, %L or %N, %l, %t, %c
+5. $XAPPLRESDIR with %N, %l
+6. $XAPPLRESDIR with %N
+7. $HOME with %N
+</programlisting>
+ <para>
+The order of these seven entries within the path must be as given above.
+The order and use of substitutions within a given entry are
+implementation-dependent.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+Last, the application-specific class resource file from the local
+host is merged into the screen resource database.
+This file is owned by the application and is usually installed in
+a system directory when the application is installed.
+It may contain sitewide customizations specified by the system manager.
+The name of the application class resource file is found by calling
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
+with the parameters
+(<emphasis remap='I'>display</emphasis>, “app-defaults”, NULL, NULL, NULL, NULL, 0, NULL).
+This file is expected to be provided by the developer of the application
+and may be required for the application to function properly.
+A simple application that wants to be assured of having a minimal
+set of resources in the absence of its class resource file can declare
+fallback resource specifications with
+<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>.
+Note that the customization substitution string is retrieved
+dynamically by
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
+so that the resolved file name of the application class resource file
+can be affected by any of the earlier sources for the screen resource
+database, even though the contents of the class resource file have
+lowest precedence. After calling
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>,
+the original display-associated database is restored.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+To obtain the resource database for a particular screen, use
+<xref linkend='XtScreenDatabase' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtScreenDatabase'>
+<funcprototype>
+ <funcdef>XrmDatabase <function>XtScreenDatabase</function></funcdef>
+ <paramdef>Screen * <parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the screen whose resource database is to be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtScreenDatabase' xrefstyle='select: title'/>
+function returns the fully merged resource database as specified above,
+associated with the specified screen. If the specified <emphasis remap='I'>screen</emphasis>
+does not belong to a
+<function>Display</function>
+initialized by
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>,
+the results are undefined.
+</para>
+
+<para>
+To obtain the default resource database associated with a particular display, use
+<xref linkend='XtDatabase' xrefstyle='select: title'/>.
+</para>
+
+
+<funcsynopsis id='XtDatabase'>
+<funcprototype>
+ <funcdef>XrmDatabase <function>XtDatabase</function></funcdef>
+ <paramdef>Display * <parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDatabase' xrefstyle='select: title'/>
+function is equivalent to
+<function>XrmGetDatabase</function>.
+It returns the database associated with the specified display, or
+NULL if a database has not been set.
+</para>
+
+<para>
+To specify a default set of resource values that will be used to
+initialize the resource database if no application-specific class
+resource file is found (the last of the six sources listed above),
+use
+<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppSetFallbackResources'>
+<funcprototype>
+ <funcdef>void <function>XtAppSetFallbackResources</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>String * <parameter>specification_list</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context in which
+the fallback specifications will be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>specification_list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a NULL-terminated list of
+resource specifications to preload
+the database, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Each entry in <emphasis remap='I'>specification_list</emphasis> points to a string in the format of
+<function>XrmPutLineResource</function>.
+Following a call to
+<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>,
+when a resource database is being created for a particular screen and
+the Intrinsics are not able
+to find or read an application-specific class resource file according to the
+rules given above and if <emphasis remap='I'>specification_list</emphasis> is not NULL, the
+resource specifications in <emphasis remap='I'>specification_list</emphasis> will be merged
+into the screen resource database in place of the application-specific
+class resource file.
+<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>
+is not
+required to copy <emphasis remap='I'>specification_list</emphasis>; the caller must ensure that the
+contents of the list and of the strings addressed by the list remain
+valid until all displays are initialized or until
+<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>
+is called again. The value NULL for
+<emphasis remap='I'>specification_list</emphasis> removes any previous fallback resource specification
+for the application context. The intended use for fallback resources
+is to provide a minimal
+number of resources that will make the application usable (or at
+least terminate with helpful diagnostic messages) when some problem
+exists in finding and loading the application defaults file.
+</para>
+</sect1>
+
+<sect1 id="Parsing_the_Command_Line">
+<title>Parsing the Command Line</title>
+<para>
+The
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
+function first parses the command line for the following options:
+<variablelist>
+ <varlistentry>
+ <term>-display</term>
+ <listitem>
+ <para>
+Specifies the display name for
+<function>XOpenDisplay</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-name</term>
+ <listitem>
+ <para>
+Sets the resource name prefix,
+which overrides the application name passed to
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-xnllanguage</term>
+ <listitem>
+ <para>
+Specifies the initial language string for establishing locale
+and for finding application class resource files.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+
+<para>
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+has a table of standard command line options that are passed to
+<function>XrmParseCommand</function>
+for adding resources to the resource database,
+and it takes as a parameter additional
+application-specific resource abbreviations.
+The format of this table is described in Section 15.9 in <emphasis remap='I'>Xlib — C Language X Interface</emphasis>.
+</para>
+<programlisting>
+typedef enum {
+ XrmoptionNoArg, /* Value is specified in OptionDescRec.value */
+ XrmoptionIsArg, /* Value is the option string itself */
+ XrmoptionStickyArg, /* Value is characters immediately following option */
+ XrmoptionSepArg, /* Value is next argument in argv */
+ XrmoptionResArg, /* Use the next argument as input to XrmPutLineResource*/
+ XrmoptionSkipArg, /* Ignore this option and the next argument in argv */
+ XrmoptionSkipNArgs, /* Ignore this option and the next */
+ /* OptionDescRec.value arguments in argv */
+ XrmoptionSkipLine /* Ignore this option and the rest of argv */
+} XrmOptionKind;
+
+typedef struct {
+ char *option; /* Option name in argv */
+ char *specifier; /* Resource name (without application name) */
+ XrmOptionKind argKind; /* Location of the resource value */
+ XPointer value; /* Value to provide if XrmoptionNoArg */
+} XrmOptionDescRec, *XrmOptionDescList;
+</programlisting>
+<para>The standard table contains the following entries:</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='4' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <colspec colwidth='1.0*' colname='c4'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Option String</entry>
+ <entry>Resource Name</entry>
+ <entry>Argument Kind</entry>
+ <entry>Resource Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>-background</entry>
+ <entry>*background</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>-bd</entry>
+ <entry>*borderColor</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>-bg</entry>
+ <entry>*background</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>-borderwidth</entry>
+ <entry>.borderWidth</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>-bordercolor</entry>
+ <entry>*borderColor</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>-bw</entry>
+ <entry>.borderWidth</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>-display</entry>
+ <entry>.display</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>-fg</entry>
+ <entry>*foreground</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>-fn</entry>
+ <entry>*font</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>-font</entry>
+ <entry>*font</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>-foreground</entry>
+ <entry>*foreground</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>-geometry</entry>
+ <entry>.geometry</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>-iconic</entry>
+ <entry>.iconic</entry>
+ <entry>NoArg</entry>
+ <entry>"true"</entry>
+ </row>
+ <row>
+ <entry>-name</entry>
+ <entry>.name</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>-reverse</entry>
+ <entry>.reverseVideo</entry>
+ <entry>NoArg</entry>
+ <entry>"on"</entry>
+ </row>
+ <row>
+ <entry>-rv</entry>
+ <entry>.reverseVideo</entry>
+ <entry>NoArg</entry>
+ <entry>"on"</entry>
+ </row>
+ <row>
+ <entry>+rv</entry>
+ <entry>.reverseVideo</entry>
+ <entry>NoArg</entry>
+ <entry>"off"</entry>
+ </row>
+ <row>
+ <entry>-selectionTimeout</entry>
+ <entry>.selectionTimeout</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>-synchronous</entry>
+ <entry>.synchronous</entry>
+ <entry>NoArg</entry>
+ <entry>"on"</entry>
+ </row>
+ <row>
+ <entry>+synchronous</entry>
+ <entry>.synchronous</entry>
+ <entry>NoArg</entry>
+ <entry>"off"</entry>
+ </row>
+ <row>
+ <entry>-title</entry>
+ <entry>.title</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>-xnllanguage</entry>
+ <entry>.xnlLanguage</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>-xrm</entry>
+ <entry>next argument</entry>
+ <entry>ResArg</entry>
+ <entry>next argument</entry>
+ </row>
+ <row>
+ <entry>-xtsessionID</entry>
+ <entry>.sessionID</entry>
+ <entry>SepArg</entry>
+ <entry>next argument</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+Note that any unique abbreviation for an option name in the standard table
+or in the application table is accepted.
+</para>
+
+<para>
+If reverseVideo is
+<function>True</function>,
+the values of
+<function>XtDefaultForeground</function>
+and
+<function>XtDefaultBackground</function>
+are exchanged for all screens on the Display.
+</para>
+
+<para>
+The value of the synchronous resource specifies whether or not
+Xlib is put into synchronous mode. If a value is found in the resource
+database during display initialization,
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+makes a call to
+<function>XSynchronize</function>
+for all display
+connections currently open in the application context. Therefore,
+when multiple displays are initialized in the same application
+context, the most recent value specified for the synchronous resource
+is used for all displays in the application context.
+</para>
+
+<para>
+The value of the selectionTimeout resource applies to all displays
+opened in the same application context. When multiple displays are
+initialized in the same application context, the most recent value
+specified is used for all displays in the application context.
+</para>
+
+<para>
+The -xrm option provides a method of setting any resource in an application.
+The next argument should be a quoted string identical in format to a line in
+the user resource file.
+For example,
+to give a red background to all command buttons in an application named
+<function>xmh</function>,
+you can start it up as
+</para>
+<programlisting>
+xmh -xrm 'xmh*Command.background: red'
+</programlisting>
+<para>
+When it parses the command line,
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+merges the application option table with the standard option table
+before calling the Xlib
+<function>XrmParseCommand</function>
+function.
+An entry in the application table with the same name as an entry
+in the standard table overrides the standard table entry.
+If an option name is a prefix of another option name,
+both names are kept in the merged table.
+The Intrinsics reserve all option names
+beginning with the characters “-xt” for future standard uses.
+</para>
+</sect1>
+
+<sect1 id="Creating_Widgets">
+<title>Creating Widgets</title>
+<para>
+The creation of widget instances is a three-phase process:
+</para>
+
+<orderedlist>
+ <listitem>
+ <para>
+The widgets are allocated and initialized with resources
+and are optionally added to the managed subset of their parent.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+All composite widgets are notified of their managed children
+in a bottom-up traversal of the widget tree.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The widgets create X windows, which then are mapped.
+ </para>
+ </listitem>
+</orderedlist>
+<para>
+To start the first phase,
+the application calls
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+for all its widgets and adds some (usually, most or all) of its widgets
+to their respective parents' managed set by calling
+<xref linkend='XtManageChild' xrefstyle='select: title'/>.
+To avoid an O(n<superscript>2</superscript>) creation process where each composite widget
+lays itself out each time a widget is created and managed,
+parent widgets are not notified of changes in their managed set
+during this phase.
+</para>
+
+<para>
+After all widgets have been created,
+the application calls
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+with the top-level widget to execute the second and third phases.
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+first recursively traverses the widget tree in a postorder (bottom-up)
+traversal and then notifies each composite widget with one
+or more managed children by means of its change_managed procedure.
+</para>
+
+<para>
+Notifying a parent about its managed set involves geometry layout and
+possibly geometry negotiation.
+A parent deals with constraints on its size imposed from above
+(for example, when a user specifies the application window size)
+and suggestions made from below (for example,
+when a primitive child computes its preferred size).
+One difference between the two can cause geometry changes to ripple
+in both directions through the widget tree.
+The parent may force some of its children to change size and position
+and may issue geometry requests to its own parent in order to better
+accommodate all its children.
+You cannot predict where anything will go on the screen
+until this process finishes.
+</para>
+
+<para>
+Consequently, in the first and second phases,
+no X windows are actually created, because it is likely
+that they will get moved around after creation.
+This avoids unnecessary requests to the X server.
+</para>
+
+<para>
+Finally,
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+starts the third phase by making a preorder (top-down) traversal
+of the widget tree, allocates an X window to each widget by means of
+its realize procedure, and finally maps the widgets that are managed.
+</para>
+
+<sect2 id="Creating_and_Merging_Argument_Lists">
+<title>Creating and Merging Argument Lists</title>
+<para>
+Many Intrinsics functions may be passed pairs of resource names and
+values.
+These are passed as an arglist, a pointer to an array of
+<function>Arg</function>
+structures, which contains
+</para>
+<programlisting>
+typedef struct {
+ String name;
+ XtArgVal value;
+} Arg, *ArgList;
+</programlisting>
+<para>
+where
+<function>XtArgVal</function>
+is as defined in Section 1.5.
+</para>
+
+<para>
+If the size of the resource is less than or equal to the size of an
+<function>XtArgVal</function>,
+the resource value is stored directly in <emphasis remap='I'>value</emphasis>;
+otherwise, a pointer to it is stored in <emphasis remap='I'>value</emphasis>.
+</para>
+
+<para>
+To set values in an
+<function>ArgList</function>,
+use
+<xref linkend='XtSetArg' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetArg'>
+<funcprototype>
+ <funcdef>void <function>XtSetArg</function></funcdef>
+ <paramdef>Arg <parameter>arg</parameter></paramdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>XtArgVal <parameter>value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>arg</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the <emphasis remap='I'>name/value</emphasis> pair to set.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the resource.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value of the resource if it will fit in an
+<function>XtArgVal</function>,
+else the address.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtSetArg' xrefstyle='select: title'/>
+function is usually used in a highly stylized manner to
+minimize the probability of making a mistake; for example:
+</para>
+<programlisting>
+Arg args[20];
+int n;
+n = 0;
+XtSetArg(args[n], XtNheight, 100); n++;
+XtSetArg(args[n], XtNwidth, 200); n++;
+XtSetValues(widget, args, n);
+</programlisting>
+<para>
+Alternatively, an application can statically declare the argument list
+and use
+<xref linkend='XtNumber' xrefstyle='select: title'/>:
+</para>
+<programlisting>
+static Args args[] = {
+ {XtNheight, (XtArgVal) 100},
+ {XtNwidth, (XtArgVal) 200},
+};
+XtSetValues(Widget, args, XtNumber(args));
+</programlisting>
+<para>
+Note that you should not use expressions with side effects such as
+auto-increment or auto-decrement
+within the first argument to
+<xref linkend='XtSetArg' xrefstyle='select: title'/>.
+<xref linkend='XtSetArg' xrefstyle='select: title'/>
+can be implemented as a macro that evaluates the first argument twice.
+</para>
+
+<para>
+To merge two
+arglist arrays, use
+<xref linkend='XtMergeArgLists' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtMergeArgLists'>
+<funcprototype>
+ <funcdef>ArgList <function>XtMergeArgLists</function></funcdef>
+ <paramdef>ArgList <parameter>args1</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args1</parameter></paramdef>
+ <paramdef>ArgList <parameter>args2</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args2</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args1</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the first argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args1</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the first argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args2</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the second argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args2</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the second argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtMergeArgLists' xrefstyle='select: title'/>
+function allocates enough storage to hold the combined
+arglist arrays and copies them into it.
+Note that it does not check for duplicate entries.
+The length of the returned list is the sum of the lengths of the
+specified lists.
+When it is no longer needed,
+free the returned storage by using
+<xref linkend='XtFree' xrefstyle='select: title'/>.
+</para>
+
+<para>
+All Intrinsics interfaces that require
+<function>ArgList</function>
+arguments have analogs
+conforming to the ANSI C variable argument list
+(traditionally called “varargs”)
+calling convention. The name of the analog is formed by prefixing
+“Va” to the name of the corresponding
+<function>ArgList</function>
+procedure; e.g.,
+<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>.
+Each procedure named <function>XtVa</function><emphasis remap='I'>something</emphasis> takes as its
+last arguments, in place of the corresponding
+<function>ArgList</function>/
+<function>Cardinal</function>
+parameters, a variable parameter list of resource name and
+value pairs where each name is of type
+<function>String</function>
+and each value is of type
+<function>XtArgVal</function>.
+The end of the list is identified by a <emphasis remap='I'>name</emphasis> entry
+containing NULL. Developers writing in the C language wishing to pass
+resource name and value pairs to any of these interfaces may use the
+<function>ArgList</function>
+and varargs forms interchangeably.
+</para>
+
+<para>
+Two special names are defined for use only in varargs lists:
+<function>XtVaTypedArg</function>
+and
+<function>XtVaNestedList</function>.
+</para>
+<programlisting>
+#define XtVaTypedArg "XtVaTypedArg"
+</programlisting>
+<para>
+If the name
+<function>XtVaTypedArg</function>
+is specified in place of a resource
+name, then the following four arguments are interpreted as a
+<emphasis remap='I'>name/type/value/size</emphasis> tuple <emphasis remap='I'>where</emphasis> name is of type
+<function>String</function>,
+<emphasis remap='I'>type</emphasis> is of type
+<function>String</function>,
+<emphasis remap='I'>value</emphasis> is of type
+<function>XtArgVal</function>,
+and <emphasis remap='I'>size</emphasis> is of type int. When a varargs list containing
+<function>XtVaTypedArg</function>
+is processed, a resource type
+conversion (see <xref linkend='Resource_Conversions' />) is performed if necessary to convert the
+value into the format required by the associated resource. If <emphasis remap='I'>type</emphasis> is
+XtRString, then <emphasis remap='I'>value</emphasis> contains a pointer to the string and <emphasis remap='I'>size</emphasis>
+contains the number of bytes allocated, including the trailing null
+byte. If <emphasis remap='I'>type</emphasis> is not XtRString, then <emphasis remap='I'>if</emphasis> size is
+less than or equal to
+<function>sizeof</function>(<function>XtArgVal</function>), the value should be the data cast to the type
+<function>XtArgVal</function>,
+otherwise <emphasis remap='I'>value</emphasis> is a pointer to the data. If the type
+conversion fails for any reason, a warning message is issued and the
+list entry is skipped.
+</para>
+<programlisting>
+#define XtVaNestedList "XtVaNestedList"
+</programlisting>
+<para>
+If the name
+<function>XtVaNestedList</function>
+is specified in place of a resource name,
+then the following argument is interpreted as an
+<function>XtVarArgsList</function>
+value, which specifies another
+varargs list that is logically inserted into the original list at the
+point of declaration. The end of the nested list is identified with a
+name entry containing NULL. Varargs lists may nest to any depth.
+</para>
+
+<para>
+To dynamically allocate a varargs list for use with
+<function>XtVaNestedList</function>
+in multiple calls, use
+<xref linkend='XtVaCreateArgsList' xrefstyle='select: title'/>.
+</para>
+<programlisting>
+typedef XtPointer XtVarArgsList;
+</programlisting>
+
+<funcsynopsis id='XtVaCreateArgsList'>
+<funcprototype>
+ <funcdef>XtVarArgsList <function>XtVaCreateArgsList</function></funcdef>
+ <paramdef>XtPointer <parameter>unused</parameter></paramdef>
+ <paramdef> <parameter>...</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>unused</emphasis>
+ </term>
+ <listitem>
+ <para>
+This argument is not currently used and must be specified as NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies a variable parameter list of resource
+name and value pairs.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtVaCreateArgsList' xrefstyle='select: title'/>
+function allocates memory and copies its arguments into a
+single list pointer, which may be used with
+<function>XtVaNestedList</function>.
+The end of
+both lists is identified by a <emphasis remap='I'>name</emphasis> entry containing NULL. Any entries
+of type
+<function>XtVaTypedArg</function>
+are copied as specified without applying
+conversions. Data passed by reference (including Strings) are not
+copied, only the pointers themselves; the caller must ensure that the
+data remain valid for the lifetime of the created varargs list. The
+list should be freed using
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when no longer needed.
+</para>
+
+<para>
+Use of resource files and of the resource database is generally
+encouraged over lengthy arglist or varargs lists whenever possible in
+order to permit modification without recompilation.
+</para>
+</sect2>
+
+<sect2 id="Creating_a_Widget_Instance">
+<title>Creating a Widget Instance</title>
+<para>
+To create an instance of a widget, use
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCreateWidget'>
+<funcprototype>
+ <funcdef>Widget <function>XtCreateWidget</function></funcdef>
+ <paramdef>const char * <parameter>name</parameter></paramdef>
+ <paramdef>WidgetClass <parameter>object_class</parameter></paramdef>
+ <paramdef>Widget <parameter>parent</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource instance name for the created widget,
+which is used for retrieving resources
+and, for that reason, should not be the same as any other widget
+that is a child of the same parent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class pointer for the created object. Must be <emphasis role='strong'>objectClass</emphasis> or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>parent</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the parent widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list to override any other resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+function performs all the boilerplate operations of widget
+creation, doing the following in order:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Checks to see if the class_initialize procedure has been called for this class
+and for all superclasses and, if not, calls those necessary in a
+superclass-to-subclass order.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the specified class is not
+<function>coreWidgetClass</function>
+or a subclass thereof,
+and the parent's class is a subclass of
+<function>compositeWidgetClass</function>
+and either no extension record in
+the parent's composite class part extension field exists with the
+<emphasis remap='I'>record_type</emphasis>
+<emphasis role='strong'>NULLQUARK</emphasis>
+or the <emphasis remap='I'>accepts_objects</emphasis> field in the extension
+record is
+<function>False</function>,
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+issues a fatal error; see <xref linkend='Addition_of_Children_to_a_Composite_Widget_The_insert_child_Procedure' /> and <xref linkend='Nonwidget_Objects' />.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the specified class contains an extension record in the object class
+part <emphasis remap='I'>extension</emphasis> field with <emphasis remap='I'>record_type</emphasis>
+<emphasis role='strong'>NULLQUARK</emphasis>
+and the <emphasis remap='I'>allocate</emphasis> field is not NULL,
+the procedure is invoked to allocate memory
+for the widget instance. If the parent is a member of the class
+<function>constraintWidgetClass</function>,
+the procedure also allocates memory for the
+parent's constraints and stores the address of this memory into the
+<emphasis remap='I'>constraints</emphasis> field. If no allocate procedure is found, the Intrinsics
+allocate memory for the widget and, when applicable, the constraints,
+and initializes the <emphasis remap='I'>constraints</emphasis> field.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Initializes the Core nonresource data fields
+<emphasis remap='I'>self</emphasis>, <emphasis remap='I'>parent</emphasis>, <emphasis remap='I'>widget_class</emphasis>, <emphasis remap='I'>being_destroyed</emphasis>,
+<emphasis remap='I'>name</emphasis>, <emphasis remap='I'>managed</emphasis>, <emphasis remap='I'>window</emphasis>, <emphasis remap='I'>visible</emphasis>,
+<emphasis remap='I'>popup_list</emphasis>, and <emphasis remap='I'>num_popups</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Initializes the resource fields (for example, <emphasis remap='I'>background_pixel</emphasis>)
+by using the
+<function>CoreClassPart</function>
+resource lists specified for this class and all superclasses.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the parent is a member of the class
+<function>constraintWidgetClass</function>,
+initializes the resource fields of the constraints record
+by using the
+<function>ConstraintClassPart</function>
+resource lists specified for the parent's class
+and all superclasses up to
+<function>constraintWidgetClass</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calls the initialize procedures for the widget starting at the
+Object
+initialize procedure on down to the widget's initialize procedure.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the parent is a member of the class
+<function>constraintWidgetClass</function>,
+calls the
+<function>ConstraintClassPart</function>
+initialize procedures,
+starting at
+<function>constraintWidgetClass</function>
+on down to the parent's
+<function>ConstraintClassPart</function>
+initialize procedure.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the parent is a member of the class
+<function>compositeWidgetClass</function>,
+puts the widget into its parent's children list by calling its parent's
+insert_child procedure.
+For further information,
+see <xref linkend='Addition_of_Children_to_a_Composite_Widget_The_insert_child_Procedure' />.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+To create an instance of a widget using varargs lists, use
+<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaCreateWidget'>
+<funcprototype>
+ <funcdef>Widget <function>XtVaCreateWidget</function></funcdef>
+ <paramdef>const char * <parameter>name</parameter></paramdef>
+ <paramdef>WidgetClass <parameter>object_class</parameter></paramdef>
+ <paramdef>Widget <parameter>parent</parameter></paramdef>
+ <paramdef> <parameter>...</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource name for the created widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class pointer for the created object. Must be <emphasis role='strong'>objectClass</emphasis> or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>parent</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the parent widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list to override any other
+resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>
+procedure is identical in function to
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list,
+as described
+in Section 2.5.1.
+</para>
+</sect2>
+
+<sect2 id="Creating_an_Application_Shell_Instance">
+<title>Creating an Application Shell Instance</title>
+<para>
+An application can have multiple top-level widgets, each of which
+specifies a unique widget tree
+that can potentially be on different screens or displays.
+An application uses
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
+to create independent widget trees.
+</para>
+
+<funcsynopsis id='XtAppCreateShell'>
+<funcprototype>
+ <funcdef>Widget <function>XtAppCreateShell</function></funcdef>
+ <paramdef>const char * <parameter>name</parameter></paramdef>
+ <paramdef>const char * <parameter>application_class</parameter></paramdef>
+ <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
+ <paramdef>Display * <parameter>display</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the instance name of the shell widget.
+If <emphasis remap='I'>name</emphasis> is NULL,
+the application name passed to
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class string to be used in
+place of the widget <emphasis remap='I'>class_name</emphasis> string when
+<emphasis remap='I'>widget_class</emphasis> is
+<function>applicationShellWidgetClass</function>
+or a subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class for the top-level widget (e.g.,
+<function>applicationShellWidgetClass ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display for the default screen
+and for the resource database used to retrieve
+the shell widget resources.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list to override any other resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
+function
+creates a new shell widget instance as the root of a widget tree.
+The screen resource for this widget is determined by first scanning
+<emphasis remap='I'>args</emphasis> for the XtNscreen argument. If no XtNscreen argument is
+found, the resource database associated with the default screen of
+the specified display is queried for the resource <emphasis remap='I'>name</emphasis>.screen,
+class <emphasis remap='I'>Class</emphasis>.Screen where <emphasis remap='I'>Class</emphasis> is the specified
+<emphasis remap='I'>application_class</emphasis> if <emphasis remap='I'>widget_class</emphasis> is
+<function>applicationShellWidgetClass</function>
+or a subclass thereof. If <emphasis remap='I'>widget_class</emphasis> is not
+<function>applicationShellWidgetClass</function>
+or a subclass, <emphasis remap='I'>Class</emphasis> is the <emphasis remap='I'>class_name</emphasis>
+field from the
+<function>CoreClassPart</function>
+of the specified <emphasis remap='I'>widget_class</emphasis>.
+If this query fails, the default
+screen of the specified display is used. Once the screen is determined,
+the resource database associated with that screen is used to retrieve
+all remaining resources for the shell widget not specified in
+<emphasis remap='I'>args</emphasis>. The widget name and <emphasis remap='I'>Class</emphasis> as determined above are
+used as the leftmost (i.e., root) components in all fully qualified
+resource names for objects within this widget tree.
+</para>
+
+<para>
+If the specified widget class is a subclass of WMShell, the name and
+<emphasis remap='I'>Class</emphasis> as determined above will be stored into the
+<emphasis role='strong'>WM_CLASS</emphasis>
+property on the widget's window when it becomes realized.
+If the specified <emphasis remap='I'>widget_class</emphasis> is
+<function>applicationShellWidgetClass</function>
+or a subclass thereof, the
+<emphasis role='strong'>WM_COMMAND</emphasis>
+property will also be set from the values of the XtNargv and
+XtNargc resources.
+</para>
+
+<para>
+To create multiple top-level shells within a single (logical)
+application,
+you can use one of two methods:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Designate one shell as the real top-level shell and
+create the others as pop-up children of it by using
+<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Have all shells as pop-up children of an unrealized top-level shell.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The first method,
+which is best used when there is a clear choice for what is the main window,
+leads to resource specifications like the following:
+</para>
+<programlisting>
+xmail.geometry:... (the main window)
+xmail.read.geometry:... (the read window)
+xmail.compose.geometry:... (the compose window)
+</programlisting>
+<para>
+The second method,
+which is best if there is no main window,
+leads to resource specifications like the following:
+</para>
+<programlisting>
+xmail.headers.geometry:... (the headers window)
+xmail.read.geometry:... (the read window)
+xmail.compose.geometry:... (the compose window)
+</programlisting>
+<para>
+To create a top-level widget that is the root of a widget tree using
+varargs lists, use
+<xref linkend='XtVaAppCreateShell' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaAppCreateShell'>
+<funcprototype>
+ <funcdef>Widget <function>XtVaAppCreateShell</function></funcdef>
+ <paramdef>const char * <parameter>name</parameter></paramdef>
+ <paramdef>const char * <parameter>application_class</parameter></paramdef>
+ <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
+ <paramdef>Display * <parameter>display</parameter></paramdef>
+ <paramdef>...</paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the instance name of the shell widget.
+If <emphasis remap='I'>name</emphasis> is NULL,
+the application name passed to
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class string to be used in
+place of the widget <emphasis remap='I'>class_name</emphasis> string when
+<emphasis remap='I'>widget_class</emphasis> is
+<function>applicationShellWidgetClass</function>
+or a subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class for the top-level widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display for the default screen
+and for the resource database used to retrieve
+the shell widget resources.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list to override any other
+resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtVaAppCreateShell' xrefstyle='select: title'/>
+procedure is identical in function to
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as
+described in Section 2.5.1.
+</para>
+</sect2>
+
+<sect2 id="Convenience_Procedure_to_Initialize_an_Application">
+<title>Convenience Procedure to Initialize an Application</title>
+<para>
+To initialize the Intrinsics internals, create an application context,
+open and initialize a display, and create the initial root shell
+instance, an application may use
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
+or
+<xref linkend='XtVaOpenApplication' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtOpenApplication'>
+<funcprototype>
+ <funcdef>Widget <function>XtOpenApplication</function></funcdef>
+ <paramdef>XtAppContext * <parameter>app_context_return</parameter></paramdef>
+ <paramdef>const char * <parameter>application_class</parameter></paramdef>
+ <paramdef>XrmOptionDescList <parameter>options</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_options</parameter></paramdef>
+ <paramdef>int * <parameter>argc_in_out</parameter></paramdef>
+ <paramdef>char ** <parameter>argv_in_out</parameter></paramdef>
+ <paramdef>String * <parameter>fallback_resources</parameter></paramdef>
+ <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the application context, if non-NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class name of the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the command line options table.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>options</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the number of command line arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the command line arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fallback_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies resource values to be used if the application class resource
+file cannot be opened or read, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class of the widget to be created. Must be shellWidgetClass
+or a subclass.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list to override any
+other resource specifications for the created shell widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
+function calls
+<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>
+followed by
+<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>,
+then calls
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
+with <emphasis remap='I'>display_string</emphasis> NULL and
+<emphasis remap='I'>application_name</emphasis> NULL, and finally calls
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
+with <emphasis remap='I'>name</emphasis> NULL, the specified <emphasis remap='I'>widget_class</emphasis>,
+an argument list and count,
+and returns the created shell.
+The recommended <emphasis remap='I'>widget_class</emphasis> is
+<function>sessionShellWidgetClass</function>.
+The argument list and count are created by merging
+the specified <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> with a list
+containing the specified <emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis>.
+The modified <emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis> returned by
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+are returned in <emphasis remap='I'>argc_in_out</emphasis> and <emphasis remap='I'>argv_in_out</emphasis>. If
+<emphasis remap='I'>app_context_return</emphasis> is not NULL, the created application context is
+also returned. If the display specified by the command line cannot be
+opened, an error message is issued and
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
+terminates the application. If <emphasis remap='I'>fallback_resources</emphasis> is non-NULL,
+<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>
+is called with the value prior to calling
+<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaOpenApplication'>
+<funcprototype>
+ <funcdef>Widget <function>XtVaOpenApplication</function></funcdef>
+ <paramdef>XtAppContext * <parameter>app_context_return</parameter></paramdef>
+ <paramdef>const char * <parameter>application_class</parameter></paramdef>
+ <paramdef>XrmOptionDescList <parameter>options</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_options</parameter></paramdef>
+ <paramdef>int * <parameter>argc_in_out</parameter></paramdef>
+ <paramdef>char ** <parameter>argv_in_out</parameter></paramdef>
+ <paramdef>String * <parameter>fallback_resources</parameter></paramdef>
+ <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
+ <paramdef>...</paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the application context, if non-NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>application_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class name of the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the command line options table.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_options</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>options</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the number of command line arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the command line arguments array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fallback_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies resource values to be used if the application class
+resource file cannot be opened, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class of the widget to be created. Must be shellWidgetClass
+or a subclass.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list to override any other
+resource specifications for the created shell.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtVaOpenApplication' xrefstyle='select: title'/>
+procedure is identical in function to
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list,
+as described
+in Section 2.5.1.
+</para>
+</sect2>
+
+<sect2 id="Widget_Instance_Allocation_The_allocate_Procedure">
+<title>Widget Instance Allocation: The allocate Procedure</title>
+<para>
+A widget class may optionally provide an instance allocation procedure
+in the
+<function>ObjectClassExtension</function>
+record.
+</para>
+
+<para>
+When the call to create a widget includes a varargs list containing
+<function>XtVaTypedArg</function>,
+these arguments will be passed to the allocation procedure in an
+<function>XtTypedArgList</function>.
+</para>
+<programlisting>
+typedef struct {
+ String name;
+ String type;
+ XtArgVal value;
+ int size;
+} XtTypedArg, *XtTypedArgList;
+</programlisting>
+<para>
+The allocate procedure pointer in the
+<function>ObjectClassExtension</function>
+record is of type
+<xref linkend='XtAllocateProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAllocateProc'>
+<funcprototype>
+ <funcdef>typedef void <function>(*XtAllocateProc)</function></funcdef>
+ <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
+ <paramdef>Cardinal* <parameter>constraint_size</parameter></paramdef>
+ <paramdef>Cardinal* <parameter>more_bytes</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal* <parameter>num_args</parameter></paramdef>
+ <paramdef>XtTypedArgList <parameter>typed_args</parameter></paramdef>
+ <paramdef>Cardinal* <parameter>num_typed_args</parameter></paramdef>
+ <paramdef>Widget* <parameter>new_return</parameter></paramdef>
+ <paramdef>XtPointer* <parameter>more_bytes_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class of the instance to allocate.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>constraint_size</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the constraint record to allocate, or 0.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>more_bytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of auxiliary bytes of memory to allocate.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list as given in the call to create the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>typed_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of typed arguments given in the call to create the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_typed_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of typed arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>new_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a pointer to the newly allocated instance, or NULL in case of error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>more_bytes_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the auxiliary memory if it was requested, or NULL
+if requested and an error occurred; otherwise, unchanged.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+At widget allocation time, if an extension record with <emphasis remap='I'>record_type</emphasis>
+equal to
+<emphasis role='strong'>NULLQUARK</emphasis>
+is located through the object class part <emphasis remap='I'>extension</emphasis> field
+and the <emphasis remap='I'>allocate</emphasis> field is not NULL, the
+<xref linkend='XtAllocateProc' xrefstyle='select: title'/>
+will be invoked to allocate memory for the widget. If no ObjectClassPart
+extension record is declared with <emphasis remap='I'>record_type equal</emphasis> to
+<emphasis role='strong'>NULLQUARK</emphasis>,
+then
+<function>XtInheritAllocate</function>
+and
+<function>XtInheritDeallocate</function>
+are assumed.
+If no
+<xref linkend='XtAllocateProc' xrefstyle='select: title'/>
+is found, the Intrinsics will allocate memory for the widget.
+</para>
+
+<para>
+An
+<xref linkend='XtAllocateProc' xrefstyle='select: title'/>
+must perform the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Allocate memory for the widget instance and return it in <emphasis remap='I'>new_return</emphasis>.
+The memory must be at least <emphasis remap='I'>wc->core_class.widget_size</emphasis> bytes in length,
+double-word aligned.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Initialize the <emphasis remap='I'>core.constraints</emphasis> field in the instance record to NULL
+or to point to a constraint record. If <emphasis remap='I'>constraint_size</emphasis>
+is not 0, the procedure must allocate memory for the constraint record.
+The memory must be double-word aligned.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If <emphasis remap='I'>more_bytes</emphasis> is not 0, then the address of a block of memory
+at least <emphasis remap='I'>more_bytes</emphasis> in size, double-word aligned, must be
+returned in the <emphasis remap='I'>more_bytes_return</emphasis> parameter,
+or NULL to indicate an error.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+A class allocation procedure that envelops the allocation procedure of a
+superclass must rely on the enveloped procedure to perform the instance
+and constraint allocation.
+Allocation procedures should refrain from initializing fields in the
+widget record except to store pointers to newly allocated additional memory.
+Under no circumstances should an allocation procedure that envelopes
+its superclass allocation procedure modify fields in the
+instance part of any superclass.
+</para>
+</sect2>
+
+<sect2 id="Widget_Instance_Initialization_The_initialize_Procedure">
+<title>Widget Instance Initialization: The initialize Procedure</title>
+<para>
+The initialize procedure pointer in a widget class is of type
+<xref linkend='XtInitProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtInitProc'>
+<funcprototype>
+ <funcdef>typedef void <function>(*XtInitProc)</function></funcdef>
+ <paramdef>Widget <parameter>request</parameter></paramdef>
+ <paramdef>Widget <parameter>new</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal * <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a copy of the widget with resource values as requested by the
+argument list, the resource database, and the widget defaults.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>new</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget with the new values, both resource and nonresource,
+that are actually allowed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list passed by the client, for
+computing derived resource values.
+If the client created the widget using a varargs form, any resources
+specified via
+<function>XtVaTypedArg</function>
+are converted to the widget representation and the list is transformed
+into the
+<function>ArgList</function>
+format.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+An initialization procedure performs the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Allocates space for and copies any resources referenced by address
+that the client is allowed to free or modify
+after the widget has been created.
+For example,
+if a widget has a field that is a
+<function>String</function>,
+it may choose not to
+depend on the characters at that address remaining constant
+but dynamically allocate space for the string and copy it to the new space.
+Widgets that do not copy one or more resources referenced
+by address should clearly so state in their user documentation.
+<note><para>
+It is not necessary to allocate space for or to copy callback lists.
+</para></note>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Computes values for unspecified resource fields.
+For example, if <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> are zero,
+the widget should compute an appropriate width and height
+based on its other resources.
+<note><para>
+A widget may directly assign only
+its own <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> within the initialize, initialize_hook,
+set_values, and
+set_values_hook procedures; see <xref linkend='Geometry_Management' />.
+</para></note>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Computes values for uninitialized nonresource fields that are derived from
+resource fields.
+For example, graphics contexts (GCs) that the widget uses are derived from
+resources like background, foreground, and font.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+An initialization procedure also can check certain fields for
+internal consistency.
+For example, it makes no sense to specify a colormap for a depth
+that does not support that colormap.
+</para>
+
+<para>
+Initialization procedures are called in superclass-to-subclass order
+after all fields specified in the resource lists have been
+initialized. The initialize procedure does not need to examine
+<emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis>
+if all public resources are declared in the resource list.
+Most of the initialization code for a specific widget class deals with fields
+defined in that class and not with fields defined in its superclasses.
+</para>
+
+<para>
+If a subclass does not need an initialization procedure
+because it does not need to perform any of the above operations,
+it can specify NULL for the <emphasis remap='I'>initialize</emphasis> field in the class record.
+</para>
+
+<para>
+Sometimes a subclass may want to overwrite values filled in by its
+superclass.
+In particular, size calculations of a superclass often are
+incorrect for a subclass, and in this case,
+the subclass must modify or recalculate fields declared
+and computed by its superclass.
+</para>
+
+<para>
+As an example,
+a subclass can visually surround its superclass display.
+In this case, the width and height calculated by the superclass initialize
+procedure are too small and need to be incremented by the size of the surround.
+The subclass needs to know if its superclass's size was calculated by the
+superclass or was specified explicitly.
+All widgets must place themselves into whatever size is explicitly given,
+but they should compute a reasonable size if no size is requested.
+</para>
+
+<para>
+The <emphasis remap='I'>request</emphasis> and <emphasis remap='I'>new</emphasis> arguments provide the necessary information for
+a subclass to determine the difference between an explicitly specified field
+and a field computed by a superclass.
+The <emphasis remap='I'>request</emphasis> widget is a copy of the widget as initialized by the
+arglist and resource database.
+The <emphasis remap='I'>new</emphasis> widget starts with the values in the request,
+but it has been updated by all superclass initialization procedures called
+so far.
+A subclass initialize procedure can compare these two to resolve
+any potential conflicts.
+</para>
+
+<para>
+In the above example,
+the subclass with the visual surround can see
+if the <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> in the <emphasis remap='I'>request</emphasis> widget are zero.
+If so,
+it adds its surround size to the <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis>
+fields in the <emphasis remap='I'>new</emphasis> widget.
+If not, it must make do with the size originally specified.
+</para>
+
+<para>
+The <emphasis remap='I'>new</emphasis> widget will become the actual widget instance record.
+Therefore,
+the initialization procedure should do all its work on the <emphasis remap='I'>new</emphasis> widget;
+the <emphasis remap='I'>request</emphasis> widget should never be modified.
+If the initialize procedure
+needs to call any routines that operate on a widget,
+it should specify <emphasis remap='I'>new</emphasis> as the widget instance.
+</para>
+</sect2>
+
+<sect2 id="Constraint_Instance_Initialization_The_ConstraintClassPart_initialize_Procedure">
+<title>Constraint Instance Initialization: The ConstraintClassPart initialize Procedure</title>
+<para>
+The constraint initialization procedure pointer, found in the
+<function>ConstraintClassPart</function>
+<emphasis remap='I'>initialize</emphasis> field of the widget class record, is of type
+<xref linkend='XtInitProc' xrefstyle='select: title'/>.
+The values passed to the parent constraint initialization procedures
+are the same as those passed to the child's class widget initialization
+procedures.
+</para>
+
+<para>
+The <emphasis remap='I'>constraints</emphasis> field of the <emphasis remap='I'>request</emphasis> widget points to a copy of the
+constraints record as initialized by the arglist and resource database.
+</para>
+
+<para>
+The constraint initialization procedure should compute any constraint fields
+derived from constraint resources.
+It can make further changes to the <emphasis remap='I'>new</emphasis> widget to make the widget
+and any other constraint fields
+conform to the specified constraints, for example,
+changing the widget's size or position.
+</para>
+
+<para>
+If a constraint class does not need a constraint initialization procedure,
+it can specify NULL for the <emphasis remap='I'>initialize</emphasis> field of the
+<function>ConstraintClassPart</function>
+in the class record.
+</para>
+</sect2>
+
+<sect2 id="Nonwidget_Data_Initialization_The_initialize_hook_Procedure">
+<title>Nonwidget Data Initialization: The initialize_hook Procedure</title>
+<note>
+<para>
+The initialize_hook procedure is obsolete, as the same information
+is now available to the initialize procedure. The procedure has been
+retained for those widgets that used it in previous releases.
+</para>
+</note>
+
+<para>
+The initialize_hook procedure pointer is of type
+<xref linkend='XtArgsProc' xrefstyle='select: title'/>:
+</para>
+
+<funcsynopsis id='XtArgsProc'>
+<funcprototype>
+ <funcdef>typedef void <function>(*XtArgsProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal * <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list passed by the client.
+If the client created the widget using a varargs form, any resources
+specified via
+<function>XtVaTypedArg</function>
+are converted to the widget representation and the list is transformed
+into the
+<function>ArgList</function>
+format.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If this procedure is not NULL,
+it is called immediately after the corresponding initialize
+procedure or in its place if the <emphasis remap='I'>initialize</emphasis> field is NULL.
+</para>
+
+<para>
+The initialize_hook procedure allows a widget instance to initialize
+nonresource data using information from the specified argument list
+as if it were a resource.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Realizing_Widgets">
+<title>Realizing Widgets</title>
+<para>
+To realize a widget instance, use
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRealizeWidget'>
+<funcprototype>
+ <funcdef>void <function>XtRealizeWidget</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If the widget is already realized,
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+simply returns.
+Otherwise it performs the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Binds all action names in the widget's
+translation table to procedures (see <xref linkend='Action_Names_to_Procedure_Translations' />).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Makes a postorder traversal of the widget tree rooted
+at the specified widget and calls each non-NULL change_managed procedure
+of all composite widgets that have one or more managed children.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Constructs an
+<function>XSetWindowAttributes</function>
+structure filled in with information derived from the
+Core
+widget fields and calls the realize procedure for the widget,
+which adds any widget-specific attributes and creates the X window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the widget is
+not a subclass of
+<function>compositeWidgetClass</function>,
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+returns; otherwise it continues and performs the following:
+ </para>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Descends recursively to each of the widget's
+managed children and calls the realize procedures.
+Primitive widgets that instantiate children are responsible for realizing
+those children themselves.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Maps all of the managed children windows that have <emphasis remap='I'>mapped_when_managed</emphasis>
+<function>True</function>.
+If a widget is managed but <emphasis remap='I'>mapped_when_managed</emphasis> is
+<function>False</function>,
+the widget is allocated visual space but is not displayed.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+</itemizedlist>
+<para>
+If the widget is a top-level shell widget (that is, it has no parent), and
+<emphasis remap='I'>mapped_when_managed</emphasis> is
+<function>True</function>,
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+maps the widget window.
+</para>
+
+<para>
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>,
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>,
+<xref linkend='XtManageChildren' xrefstyle='select: title'/>,
+<function>XtUnmanageChildren</function>,
+<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>,
+<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>,
+and
+<function>XtDestroyWidget</function>
+maintain the following invariants:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If a composite widget is realized, then all its managed children are realized.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If a composite widget is realized, then all its managed children that have
+<emphasis remap='I'>mapped_when_managed</emphasis>
+<function>True</function>
+are mapped.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+All Intrinsics functions and all widget routines should accept
+either realized or unrealized widgets.
+When calling the realize or change_managed
+procedures for children of a composite
+widget,
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+calls the procedures in reverse order of
+appearance in the
+<function>CompositePart</function>
+<emphasis remap='I'>children</emphasis> list. By default, this
+ordering of the realize procedures will
+result in the stacking order of any newly created subwindows being
+top-to-bottom in the order of appearance on the list, and the most
+recently created child will be at the bottom.
+</para>
+
+<para>
+To check whether or not a widget has been realized, use
+<xref linkend='XtIsRealized' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtIsRealized'>
+<funcprototype>
+ <funcdef>Boolean <function>XtIsRealized</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtIsRealized' xrefstyle='select: title'/>
+function returns
+<function>True</function>
+if the widget has been realized,
+that is, if the widget has a nonzero window ID.
+If the specified object is not a widget, the state of the nearest
+widget ancestor is returned.
+</para>
+
+<para>
+Some widget procedures (for example, set_values) might wish to
+operate differently
+after the widget has been realized.
+</para>
+<sect2 id="Widget_Instance_Window_Creation_The_realize_Procedure">
+<title>Widget Instance Window Creation: The realize Procedure</title>
+<para>
+The realize procedure pointer in a widget class is of type
+<xref linkend='XtRealizeProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRealizeProc'>
+<funcprototype>
+ <funcdef>typedef void <function>(*XtRealizeProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtValueMask <parameter>value_mask</parameter></paramdef>
+ <paramdef>XSetWindowAttributes <parameter>attributes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which fields in the <emphasis remap='I'>attributes</emphasis> structure are used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>attributes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window attributes to use in the
+<function>XCreateWindow</function>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The realize procedure must create the widget's window.
+</para>
+
+<para>
+Before calling the class realize procedure, the generic
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+function fills in a mask and a corresponding
+<function>XSetWindowAttributes</function>
+structure.
+It sets the following fields in <emphasis remap='I'>attributes</emphasis> and
+corresponding bits in <emphasis remap='I'>value_mask</emphasis>
+based on information in the widget
+core
+structure:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+The <emphasis remap='I'>background_pixmap</emphasis> (or <emphasis remap='I'>background_pixel</emphasis> if <emphasis remap='I'>background_pixmap</emphasis> is
+<function>XtUnspecifiedPixmap</function>)
+is filled in from the corresponding field.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The <emphasis remap='I'>border_pixmap</emphasis> (or <emphasis remap='I'>border_pixel</emphasis> if <emphasis remap='I'>border_pixmap</emphasis> is
+<function>XtUnspecifiedPixmap</function>)
+is filled in from the corresponding field.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The <emphasis remap='I'>colormap</emphasis> is filled in from the corresponding field.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The <emphasis remap='I'>event_mask</emphasis> is filled in based on the event handlers registered,
+the event translations specified, whether the <emphasis remap='I'>expose</emphasis> field is non-NULL,
+and whether <emphasis remap='I'>visible_interest</emphasis> is
+<function>True</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The <emphasis remap='I'>bit_gravity</emphasis> is set to
+<function>NorthWestGravity</function>
+if the <emphasis remap='I'>expose</emphasis> field is NULL.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+These or any other fields in attributes and the corresponding bits in
+<emphasis remap='I'>value_mask</emphasis> can be set by the realize procedure.
+</para>
+
+<para>
+Note that because realize is not a chained operation,
+the widget class realize procedure must update the
+<function>XSetWindowAttributes</function>
+structure with all the appropriate fields from
+non-Core
+superclasses.
+</para>
+
+<para>
+A widget class can inherit its realize procedure from its superclass
+during class initialization.
+The realize procedure defined for
+<function>coreWidgetClass</function>
+calls
+<xref linkend='XtCreateWindow' xrefstyle='select: title'/>
+with the passed <emphasis remap='I'>value_mask</emphasis> and <emphasis remap='I'>attributes</emphasis>
+and with <emphasis remap='I'>window_class</emphasis> and <emphasis remap='I'>visual</emphasis> set to
+<function>CopyFromParent</function>.
+Both
+<function>compositeWidgetClass</function>
+and
+<function>constraintWidgetClass</function>
+inherit this realize procedure, and most new widget subclasses
+can do the same (see <xref linkend='Inheritance_of_Superclass_Operations' />).
+</para>
+
+<para>
+The most common noninherited realize procedures set <emphasis remap='I'>bit_gravity</emphasis> in the mask
+and attributes to the appropriate value and then create the window.
+For example, depending on its justification, Label might set <emphasis remap='I'>bit_gravity</emphasis> to
+<function>WestGravity</function>,
+<function>CenterGravity</function>,
+or
+<function>EastGravity</function>.
+Consequently, shrinking it would just move the bits appropriately,
+and no
+exposure
+event is needed for repainting.
+</para>
+
+<para>
+If a composite widget's children should be realized in an order other
+than that specified
+(to control the stacking order, for example),
+it should call
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+on its children itself in the appropriate order from within its own
+realize procedure.
+</para>
+
+<para>
+Widgets that have children and whose class is not a subclass of
+<function>compositeWidgetClass</function>
+are responsible for calling
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+on their children, usually from within the realize procedure.
+</para>
+
+<para>
+Realize procedures cannot manage or unmanage their descendants.
+</para>
+</sect2>
+
+<sect2 id="Window_Creation_Convenience_Routine">
+<title>Window Creation Convenience Routine</title>
+<para>
+Rather than call the Xlib
+<function>XCreateWindow</function>
+function explicitly, a realize procedure should normally call the Intrinsics analog
+<xref linkend='XtCreateWindow' xrefstyle='select: title'/>,
+which simplifies the creation of windows for widgets.
+</para>
+
+<funcsynopsis id='XtCreateWindow'>
+<funcprototype>
+ <funcdef>void <function>XtCreateWindow</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>unsigned int <parameter>window_class</parameter></paramdef>
+ <paramdef>Visual * <parameter>visual</parameter></paramdef>
+ <paramdef>XtValueMask <parameter>value_mask</parameter></paramdef>
+ <paramdef>XSetWindowAttributes * <parameter>attributes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that defines the additional window attributed. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>window_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Xlib window class (for example,
+<function>InputOutput</function>,
+<function>InputOnly</function>,
+or
+<function>CopyFromParent ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>visual</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the visual type (usually
+<function>CopyFromParent ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which fields in the <emphasis remap='I'>attributes</emphasis> structure are used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>attributes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window attributes to use in the
+<function>XCreateWindow</function>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtCreateWindow' xrefstyle='select: title'/>
+function calls the Xlib
+<function>XCreateWindow</function>
+function with values from the widget structure and the passed parameters.
+Then, it assigns the created window to the widget's <emphasis remap='I'>window</emphasis> field.
+</para>
+
+<para>
+<xref linkend='XtCreateWindow' xrefstyle='select: title'/>
+evaluates the following fields of the widget core
+structure: <emphasis remap='I'>depth</emphasis>, <emphasis remap='I'>screen</emphasis>, <emphasis remap='I'>parent->core.window</emphasis>, <emphasis remap='I'>x</emphasis>,
+<emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>, and
+<emphasis remap='I'>border_width</emphasis>.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Obtaining_Window_Information_from_a_Widget">
+<title>Obtaining Window Information from a Widget</title>
+<para>
+The
+Core
+widget class definition contains the screen and window ids.
+The <emphasis remap='I'>window</emphasis> field may be NULL for a while
+(see <xref linkend='Creating_Widgets' /> and <xref linkend='Realizing_Widgets' />).
+</para>
+
+<para>
+The display pointer, the parent widget, screen pointer,
+and window of a widget are available to the widget writer by means of macros
+and to the application writer by means of functions.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Display * <function>XtDisplay</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XtDisplay</function>
+returns the display pointer for the specified widget.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Widget <function>XtParent</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XtParent</function>
+returns the parent object for the specified widget. The returned object
+will be of class Object or a subclass.
+</para>
+
+<funcsynopsis id='XtScreen'>
+<funcprototype>
+ <funcdef>Screen *<function>XtScreen</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtScreen' xrefstyle='select: title'/>
+returns the screen pointer for the specified widget.
+</para>
+
+<funcsynopsis id='XtWindow'>
+<funcprototype>
+ <funcdef>Window <function>XtWindow</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtWindow' xrefstyle='select: title'/>
+returns the window of the specified widget.
+</para>
+
+<para>
+The display pointer, screen pointer, and window of a widget or
+of the closest widget ancestor of a nonwidget object are available
+by means of
+<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>,
+<xref linkend='XtScreenOfObject' xrefstyle='select: title'/>,
+and
+<xref linkend='XtWindowOfObject' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtDisplayOfObject'>
+<funcprototype>
+ <funcdef>Display *<function>XtDisplayOfObject</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>
+is identical in function to
+<function>XtDisplay</function>
+if the object is a widget; otherwise
+<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>
+returns the display
+pointer for the nearest ancestor of <emphasis remap='I'>object</emphasis> that is of class
+Widget or a subclass thereof.
+</para>
+
+<funcsynopsis id='XtScreenOfObject'>
+<funcprototype>
+ <funcdef>Screen *<function>XtScreenOfObject</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtScreenOfObject' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtScreen' xrefstyle='select: title'/>
+if the object is a widget; otherwise
+<xref linkend='XtScreenOfObject' xrefstyle='select: title'/>
+returns the screen pointer
+for the nearest ancestor of <emphasis remap='I'>object</emphasis> that is of class
+Widget or a subclass thereof.
+</para>
+
+<funcsynopsis id='XtWindowOfObject'>
+<funcprototype>
+ <funcdef>Window <function>XtWindowOfObject</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtWindowOfObject' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtWindow' xrefstyle='select: title'/>
+if the object is a widget; otherwise
+<xref linkend='XtWindowOfObject' xrefstyle='select: title'/>
+returns the window for the nearest ancestor of <emphasis remap='I'>object</emphasis> that is of class
+Widget or a subclass thereof.
+</para>
+
+<para>
+To retrieve the instance name of an object, use
+<xref linkend='XtName' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtName'>
+<funcprototype>
+ <funcdef>String <function>XtName</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object whose name is desired. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtName' xrefstyle='select: title'/>
+returns a pointer to the instance name of the specified object.
+The storage is owned by the Intrinsics and must not be modified. The
+name is not qualified by the names of any of the object's ancestors.
+</para>
+
+<para>
+Several window attributes are locally cached in the widget instance.
+Thus, they can be set by the resource manager and
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+as well as used by routines that derive structures from these values
+(for example, <emphasis remap='I'>depth</emphasis> for deriving pixmaps,
+<emphasis remap='I'>background_pixel</emphasis> for deriving GCs, and so on) or in the
+<xref linkend='XtCreateWindow' xrefstyle='select: title'/>
+call.
+</para>
+
+<para>
+The <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>, and <emphasis remap='I'>border_width</emphasis>
+window attributes are available to
+geometry managers.
+These fields are maintained synchronously inside the Intrinsics.
+When an
+<function>XConfigureWindow</function>
+is issued by the Intrinsics on the widget's window (on request of its parent),
+these values are updated immediately rather than some time later
+when the server generates a
+<function>ConfigureNotify</function>
+event.
+(In fact, most widgets do not select
+<function>SubstructureNotify</function>
+events.)
+This ensures that all geometry calculations are based on the internally
+consistent toolkit world rather than on either
+an inconsistent world updated by asynchronous
+<function>ConfigureNotify</function>
+events or a consistent, but slow, world in which geometry managers
+ask the server
+for window sizes whenever they need to lay out their managed children
+(see <xref linkend='Geometry_Management' />).
+</para>
+<sect2 id="Unrealizing_Widgets">
+<title>Unrealizing Widgets</title>
+<para>
+To destroy the windows associated with a widget and its
+non-pop-up descendants, use
+<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtUnrealizeWidget'>
+<funcprototype>
+ <funcdef>void <function>XtUnrealizeWidget</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If the widget is currently unrealized,
+<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>
+simply returns. Otherwise it performs the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Unmanages the widget if the widget is managed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Makes a postorder (child-to-parent) traversal of the widget tree
+rooted at the specified widget and, for each widget that has
+declared a callback list resource named “unrealizeCallback”, executes the
+procedures on the
+XtNunrealizeCallback
+list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Destroys the widget's window and any subwindows by calling
+<function>XDestroyWindow</function>
+with the specified widget's <emphasis remap='I'>window</emphasis> field.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+Any events in the queue or which arrive following a call to
+<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>
+will be dispatched as if the window(s) of the
+unrealized widget(s) had never existed.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Destroying_Widgets">
+<title>Destroying Widgets</title>
+<para>
+The Intrinsics provide support
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+To destroy all the pop-up children of the widget being destroyed
+and destroy all children of composite widgets.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+To remove (and unmap) the widget from its parent.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+To call the callback procedures that have been registered to trigger
+when the widget is destroyed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+To minimize the number of things a widget has to deallocate when destroyed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+To minimize the number of
+<function>XDestroyWindow</function>
+calls when destroying a widget tree.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+To destroy a widget instance, use
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>.
+</para>
+
+
+<funcsynopsis id='XtDestroyWidget'>
+<funcprototype>
+ <funcdef>void <function>XtDestroyWidget</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+function provides the only method of destroying a widget,
+including widgets that need to destroy themselves.
+It can be called at any time,
+including from an application callback routine of the widget being destroyed.
+This requires a two-phase destroy process in order to avoid dangling
+references to destroyed widgets.
+</para>
+
+<para>
+In phase 1,
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+performs the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If the <emphasis remap='I'>being_destroyed</emphasis> field of the widget is
+<function>True</function>,
+it returns immediately.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Recursively descends the widget tree and
+sets the <emphasis remap='I'>being_destroyed</emphasis> field to
+<function>True</function>
+for the widget and all normal and pop-up children.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Adds the widget to a list of widgets (the destroy list) that should be
+destroyed when it is safe to do so.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+Entries on the destroy list satisfy the invariant that
+if w2 occurs after w1 on the destroy list, then w2 is not a descendent,
+either normal or pop-up, of w1.
+</para>
+
+<para>
+Phase 2 occurs when all procedures that should execute as a result of
+the current event have been called, including all procedures registered with
+the event and translation managers,
+that is, when the current invocation of
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+is about to return, or immediately if not in
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>.
+</para>
+
+<para>
+In phase 2,
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+performs the following on each entry in the destroy list in the order
+specified:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If the widget is not a pop-up child and the widget's parent is a subclass of
+<function>compositeWidgetClass</function>,
+and if the parent is not being destroyed,
+it calls
+<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>
+on the widget and then calls the widget's parent's delete_child procedure
+(see <xref linkend='Deletion_of_Children_The_delete_child_Procedure' />).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calls the destroy callback procedures registered on the widget
+and all normal and pop-up descendants in postorder (it calls child
+callbacks before parent callbacks).
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+function then makes second traversal of the widget and all normal
+and pop-up descendants to perform the following three items on each
+widget in postorder:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If the widget is not a pop-up child and the widget's parent is a subclass of
+<function>constraintWidgetClass</function>,
+it calls the
+<function>ConstraintClassPart</function>
+destroy procedure for the parent,
+then for the parent's superclass,
+until finally it calls the
+<function>ConstraintClassPart</function>
+destroy procedure for
+<function>constraintWidgetClass</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calls the
+<function>CoreClassPart</function>
+destroy procedure declared in the widget class,
+then the destroy procedure declared in its superclass,
+until finally it calls the destroy procedure declared in the Object
+class record. Callback lists are deallocated.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the widget class object class part contains an
+<function>ObjectClassExtension</function>
+record with the record_type
+<emphasis role='strong'>NULLQUARK</emphasis>
+and the <emphasis remap='I'>deallocate</emphasis> field is not NULL,
+calls the deallocate procedure to deallocate the instance and if one
+exists, the constraint record. Otherwise, the Intrinsics will deallocate
+the widget instance record and if one exists, the constraint record.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calls
+<function>XDestroyWindow</function>
+if the specified widget is realized (that is, has an X window).
+The server recursively destroys all normal descendant windows.
+(Windows of realized pop-up Shell children, and their
+descendants, are destroyed by a shell class destroy procedure.)
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Adding_and_Removing_Destroy_Callbacks">
+<title>Adding and Removing Destroy Callbacks</title>
+<para>
+When an application needs to perform additional processing during the
+destruction of a widget,
+it should register a destroy callback procedure for the widget.
+The destroy callback procedures use the mechanism described in
+<xref linkend='Callbacks' />.
+The destroy callback list is identified by the resource name
+XtNdestroyCallback.
+</para>
+
+<para>
+For example, the following adds an application-supplied destroy callback
+procedure <emphasis remap='I'>ClientDestroy</emphasis> with client data to a widget by calling
+<xref linkend='XtAddCallback' xrefstyle='select: title'/>.
+</para>
+
+<programlisting>
+XtAddCallback(<emphasis remap='I'>w</emphasis>, XtNdestroyCallback, <emphasis remap='I'>ClientDestroy</emphasis>, <emphasis remap='I'>client_data</emphasis>)
+</programlisting>
+
+<para>
+Similarly, the following removes the application-supplied destroy callback
+procedure <emphasis remap='I'>ClientDestroy</emphasis> by calling
+<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>.
+</para>
+
+<programlisting>
+XtRemoveCallback(<emphasis remap='I'>w</emphasis>, XtNdestroyCallback, <emphasis remap='I'>ClientDestroy</emphasis>, <emphasis remap='I'>client_data</emphasis>)
+</programlisting>
+<para>
+The <emphasis remap='I'>ClientDestroy</emphasis> argument is of type
+<xref linkend='XtCallbackProc' xrefstyle='select: title'/>;
+see <xref linkend='Using_Callback_Procedure_and_Callback_List_Definitions' />.
+</para>
+</sect2>
+
+<sect2 id="Dynamic_Data_Deallocation_The_destroy_Procedure">
+<title>Dynamic Data Deallocation: The destroy Procedure</title>
+<para>
+The destroy procedure pointers in the
+<function>ObjectClassPart</function>,
+<function>RectObjClassPart</function>,
+and
+<function>CoreClassPart</function>
+structures are of type
+<xref linkend='XtWidgetProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtWidgetProc'>
+<funcprototype>
+ <funcdef>typedef void <function>XtWidgetProc</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget being destroyed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The destroy procedures are called in subclass-to-superclass order.
+Therefore, a widget's destroy procedure should deallocate only storage
+that is specific to the subclass and should ignore the storage
+allocated by any of its superclasses.
+The destroy procedure should deallocate only resources that have been
+explicitly created by the subclass.
+Any resource that was obtained from the resource database
+or passed in an argument list was not created by the widget
+and therefore should not be destroyed by it.
+If a widget does not need to deallocate any storage,
+the destroy procedure entry in its class record can be NULL.
+</para>
+
+<para>
+Deallocating storage includes, but is not limited to,
+the following steps:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Calling
+<xref linkend='XtFree' xrefstyle='select: title'/>
+on dynamic storage allocated with
+<xref linkend='XtMalloc' xrefstyle='select: title'/>,
+<xref linkend='XtCalloc' xrefstyle='select: title'/>,
+and so on.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calling
+<function>XFreePixmap</function>
+on pixmaps created with direct X calls.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calling
+<xref linkend='XtReleaseGC' xrefstyle='select: title'/>
+on GCs allocated with
+<xref linkend='XtGetGC' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calling
+<function>XFreeGC</function>
+on GCs allocated with direct X calls.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calling
+<xref linkend='XtRemoveEventHandler' xrefstyle='select: title'/>
+on event handlers added to other widgets.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calling
+<xref linkend='XtRemoveTimeOut' xrefstyle='select: title'/>
+on timers created with
+<xref linkend='XtAppAddTimeOut' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Calling
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+for each child if the widget has children
+and is not a subclass of
+<function>compositeWidgetClass</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+During destroy phase 2 for each widget, the Intrinsics remove the widget
+from the modal cascade, unregister all event handlers, remove all key,
+keyboard, button, and pointer grabs and remove all callback procedures
+registered on the widget. Any outstanding selection transfers will time out.
+</para>
+</sect2>
+
+<sect2 id="Dynamic_Constraint_Data_Deallocation_The_ConstraintClassPart_destroy_Procedure">
+<title>Dynamic Constraint Data Deallocation: The ConstraintClassPart destroy Procedure</title>
+<para>
+The constraint destroy procedure identified in the
+<function>ConstraintClassPart</function>
+<function>constraintWidgetClass</function>.
+This constraint destroy procedure pointer is of type
+<xref linkend='XtWidgetProc' xrefstyle='select: title'/>.
+The constraint destroy procedures are called in subclass-to-superclass order,
+starting at the class of the widget's parent and ending at
+<function>constraintWidgetClass</function>.
+Therefore, a parent's constraint destroy procedure should deallocate only
+storage that is specific to the constraint subclass
+and not storage allocated by any of its superclasses.
+</para>
+
+<para>
+If a parent does not need to deallocate any constraint storage,
+the constraint destroy procedure entry
+in its class record can be NULL.
+</para>
+</sect2>
+
+<sect2 id="Widget_Instance_Deallocation_The_deallocate_Procedure">
+<title>Widget Instance Deallocation: The deallocate Procedure</title>
+<para>
+The deallocate procedure pointer in the
+<function>ObjectClassExtension</function>
+record is of type
+<function>XtDeallocateProc</function>.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>typedef void <function>(*XtDeallocateProc)</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>XtPointer <parameter>more_bytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget being destroyed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>more_bytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the auxiliary memory received from the corresponding allocator
+along with the widget, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+When a widget is destroyed, if an
+<function>ObjectClassExtension</function>
+record exists in the object class part <emphasis remap='I'>extension</emphasis> field
+with <emphasis remap='I'>record_type</emphasis>
+<emphasis role='strong'>NULLQUARK</emphasis>
+and the <emphasis remap='I'>deallocate</emphasis> field is not NULL, the
+<function>XtDeallocateProc</function>
+will be called.
+If no ObjectClassPart extension record is declared with <emphasis remap='I'>record_type</emphasis>
+equal to
+<emphasis role='strong'>NULLQUARK</emphasis>,
+then
+<function>XtInheritAllocate</function>
+and
+<function>XtInheritDeallocate</function>
+are assumed.
+The responsibilities of the deallocate procedure are to deallocate the
+memory specified by <emphasis remap='I'>more_bytes</emphasis> if it is not NULL,
+to deallocate the constraints record as specified by the
+widget's <emphasis remap='I'>core.constraints</emphasis> field if it is
+not NULL, and to deallocate the widget instance itself.
+</para>
+
+<para>
+If no
+<function>XtDeallocateProc</function>
+is found, it is assumed that the Intrinsics
+originally allocated the memory and is responsible for freeing it.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Exiting_from_an_Application">
+<title>Exiting from an Application</title>
+<para>
+All X Toolkit applications should terminate
+by calling
+<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>
+and then exiting
+using the
+standard method for their operating system (typically, by calling
+<function>exit</function>
+for POSIX-based systems).
+The quickest way to make the windows disappear while exiting is to call
+<xref linkend='XtUnmapWidget' xrefstyle='select: title'/>
+on each top-level shell widget.
+The Intrinsics have no resources beyond those in the program image,
+and the X server will free its resources when its connection
+to the application is broken.
+</para>
+
+<para>
+Depending upon the widget set in use, it may be necessary to explicitly
+destroy individual widgets or widget trees with
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+before calling
+<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>
+in order to ensure that any
+required widget cleanup is properly executed. The application developer
+must refer to the widget documentation to learn if a widget needs to
+perform cleanup beyond that performed automatically by the
+operating system. If the client is a session participant
+(see <xref linkend='Session_Participation' />), then the client may wish to resign from the session
+before exiting. See <xref linkend='Resigning_from_a_Session' /> for details.
+</para>
+</sect1>
+</chapter>
Index: create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH04.xml
===================================================================
--- create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH04.xml (nonexistent)
+++ create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH04.xml (revision 5)
@@ -0,0 +1,2498 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<chapter id='Shell_Widgets'>
+<title>Shell Widgets</title>
+
+<para>
+Shell widgets hold an application's top-level widgets to allow them to
+communicate with the window manager and session manager.
+Shells have been designed to be as nearly invisible as possible.
+Clients have to create them,
+but they should never have to worry about their sizes.
+</para>
+
+<para>
+If a shell widget is resized from the outside (typically by a window manager),
+the shell widget also resizes its managed child widget automatically.
+Similarly, if the shell's child widget needs to change size,
+it can make a geometry request to the shell,
+and the shell negotiates the size change with the outer environment.
+Clients should never attempt to change the size of their shells directly.
+</para>
+
+<para>The five types of public shells are:</para>
+<variablelist>
+ <varlistentry>
+ <term>OverrideShell</term>
+ <listitem>
+ <para>
+ Used for shell windows that completely bypass the window manager
+ (for example, pop-up menu shells).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>TransientShell</term>
+ <listitem>
+ <para>Used for shell windows that have the
+ <emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
+ property set. The effect of this property is dependent upon the
+ window manager being used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>TopLevelShell</term>
+ <listitem>
+ <para>Used for normal top-level windows
+ (for example, any additional top-level widgets an application needs).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ApplicationShell</term>
+ <listitem>
+ <para>Formerly used for the single main top-level window that
+ the window manager identifies as an application instance and
+ made obsolete by SessionShell.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SessionShell</term>
+ <listitem>
+ <para>
+ Used for the single main top-level window that
+ the window manager identifies as an application instance and
+ that interacts with the session manager.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<sect1 id="Shell_Widget_Definitions">
+<title>Shell Widget Definitions</title>
+<para>
+Widgets negotiate their size and position with their parent widget,
+that is, the widget that directly contains them.
+Widgets at the top of the hierarchy do not have parent widgets.
+Instead, they must deal with the outside world.
+To provide for this,
+each top-level widget is encapsulated in a special widget, called a
+shell widget.
+</para>
+
+<para>
+Shell
+widgets, whose class is a subclass of the
+Composite class,
+encapsulate other widgets and can allow a widget to avoid the
+geometry clipping imposed by the parent-child window relationship.
+They also can provide a layer of communication with the window manager.
+</para>
+
+<para>The eight different types of shells are:</para>
+<variablelist>
+ <varlistentry>
+ <term>Shell</term>
+ <listitem>
+ <para>The base class for shell widgets; provides the
+ fields needed for all types of shells. Shell
+ is a direct subclass of
+ <emphasis role='strong'>compositeWidgetClass</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>OverrideShell</term>
+ <listitem>
+ <para>A subclass of Shell; used for shell windows that completely
+ bypass the window manager.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>WMShell</term>
+ <listitem>
+ <para>A subclass of Shell; contains fields needed by the
+ common window manager protocol.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>VendorShell</term>
+ <listitem>
+ <para>A subclass of WMShell; contains fields used by
+ vendor-specific window managers.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>TransientShell</term>
+ <listitem>
+ <para>A subclass of VendorShell; used for shell windows that
+ desire the <emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
+ property.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>TopLevelShell</term>
+ <listitem>
+ <para>A subclass of VendorShell; used for normal top-level windows.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ApplicationShell</term>
+ <listitem>
+ <para>A subclass of TopLevelShell; may be used for an application's additional
+ root windows.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SessionShell</term>
+ <listitem>
+ <para>A subclass of ApplicationShell; used for an application's
+ main root window.</para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Note that the classes
+Shell,
+WMShell,
+and
+VendorShell
+are internal and should not be instantiated or subclassed.
+Only
+OverrrideShell,
+TransientShell,
+TopLevelShell,
+ApplicationShell,
+and
+SessionShell
+are intended for public use.
+</para>
+
+<sect2 id="ShellClassPart_Definitions">
+<title>ShellClassPart Definitions</title>
+<para>
+Only the Shell
+class has additional class fields, which are all contained in the
+<function>ShellClassExtensionRec</function>.
+None of the other Shell classes have any additional class fields:
+</para>
+
+<programlisting>
+typedef struct {
+ XtPointer extension;
+} ShellClassPart, OverrideShellClassPart,
+WMShellClassPart, VendorShellClassPart, TransientShellClassPart,
+TopLevelShellClassPart, ApplicationShellClassPart, SessionShellClassPart;
+</programlisting>
+
+<para>The full Shell class record definitions are:</para>
+
+<programlisting>
+typedef struct _ShellClassRec {
+ CoreClassPart core_class;
+ CompositeClassPart composite_class;
+ ShellClassPart shell_class;
+} ShellClassRec;
+</programlisting>
+
+<programlisting>
+typedef struct { <lineannotation>See <xref linkend='Class_Extension_Records' /></lineannotation>
+ XtPointer next_extension;
+ XrmQuark record_type;
+ long version;
+ Cardinal record_size;
+ XtGeometryHandler root_geometry_manager; See below
+} ShellClassExtensionRec, *ShellClassExtension;
+</programlisting>
+
+<programlisting>
+typedef struct _OverrideShellClassRec {
+ CoreClassPart core_class;
+ CompositeClassPart composite_class;
+ ShellClassPart shell_class;
+ OverrideShellClassPart override_shell_class;
+} OverrideShellClassRec;
+</programlisting>
+
+<programlisting>
+typedef struct _WMShellClassRec {
+ CoreClassPart core_class;
+ CompositeClassPart composite_class;
+ ShellClassPart shell_class;
+ WMShellClassPart wm_shell_class;
+} WMShellClassRec;
+</programlisting>
+
+<programlisting>
+typedef struct _VendorShellClassRec {
+ CoreClassPart core_class;
+ CompositeClassPart composite_class;
+ ShellClassPart shell_class;
+ WMShellClassPart wm_shell_class;
+ VendorShellClassPart vendor_shell_class;
+} VendorShellClassRec;
+</programlisting>
+
+<programlisting>
+typedef struct _TransientShellClassRec {
+ CoreClassPart core_class;
+ CompositeClassPart composite_class;
+ ShellClassPart shell_class;
+ WMShellClassPart wm_shell_class;
+ VendorShellClassPart vendor_shell_class;
+ TransientShellClassPart transient_shell_class;
+} TransientShellClassRec;
+</programlisting>
+
+<programlisting>
+typedef struct _TopLevelShellClassRec {
+ CoreClassPart core_class;
+ CompositeClassPart composite_class;
+ ShellClassPart shell_class;
+ WMShellClassPart wm_shell_class;
+ VendorShellClassPart vendor_shell_class;
+ TopLevelShellClassPart top_level_shell_class;
+} TopLevelShellClassRec;
+</programlisting>
+
+<programlisting>
+typedef struct _ApplicationShellClassRec {
+ CoreClassPart core_class;
+ CompositeClassPart composite_class;
+ ShellClassPart shell_class;
+ WMShellClassPart wm_shell_class;
+ VendorShellClassPart vendor_shell_class;
+ TopLevelShellClassPart top_level_shell_class;
+ ApplicationShellClassPart application_shell_class;
+} ApplicationShellClassRec;
+</programlisting>
+
+<programlisting>
+typedef struct _SessionShellClassRec {
+ CoreClassPart core_class;
+ CompositeClassPart composite_class;
+ ShellClassPart shell_class;
+ WMShellClassPart wm_shell_class;
+ VendorShellClassPart vendor_shell_class;
+ TopLevelShellClassPart top_level_shell_class;
+ ApplicationShellClassPart application_shell_class;
+ SessionShellClassPart session_shell_class;
+} SessionShellClassRec;
+</programlisting>
+
+<para>
+The single occurrences of the class records and pointers for creating
+instances of shells are:
+</para>
+
+<programlisting>
+extern ShellClassRec shellClassRec;
+extern OverrideShellClassRec overrideShellClassRec;
+extern WMShellClassRec wmShellClassRec;
+extern VendorShellClassRec vendorShellClassRec;
+extern TransientShellClassRec transientShellClassRec;
+extern TopLevelShellClassRec topLevelShellClassRec;
+extern ApplicationShellClassRec applicationShellClassRec;
+extern SessionShellClassRec sessionShellClassRec;
+extern WidgetClass shellWidgetClass;
+extern WidgetClass overrideShellWidgetClass;
+extern WidgetClass wmShellWidgetClass;
+extern WidgetClass vendorShellWidgetClass;
+extern WidgetClass transientShellWidgetClass;
+extern WidgetClass topLevelShellWidgetClass;
+extern WidgetClass applicationShellWidgetClass;
+extern WidgetClass sessionShellWidgetClass;
+</programlisting>
+
+<para>
+The following opaque types and opaque variables are defined
+for generic operations on widgets whose class is a subclass of
+Shell.
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Types</entry>
+ <entry>Variables</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><emphasis role='strong'>ShellWidget</emphasis></entry>
+ <entry><emphasis role='strong'>shellWidgetClass</emphasis></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>OverrideShellWidget</emphasis></entry>
+ <entry><emphasis role='strong'>overrideShellWidgetClass</emphasis></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>WMShellWidget</emphasis></entry>
+ <entry><emphasis role='strong'>wmShellWidgetClass</emphasis></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>VendorShellWidget</emphasis></entry>
+ <entry><emphasis role='strong'>vendorShellWidgetClass</emphasis></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>TransientShellWidget</emphasis></entry>
+ <entry><emphasis role='strong'>transientShellWidgetClass</emphasis></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>TopLevelShellWidget</emphasis></entry>
+ <entry><emphasis role='strong'>topLevelShellWidgetClass</emphasis></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>ApplicationShellWidget</emphasis></entry>
+ <entry><emphasis role='strong'>applicationShellWidgetClass</emphasis></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>SessionShellWidget</emphasis></entry>
+ <entry><emphasis role='strong'>sessionShellWidgetClass</emphasis></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>ShellWidgetClass</emphasis></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>OverrideShellWidgetClass</emphasis></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>WMShellWidgetClass</emphasis></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>VendorShellWidgetClass</emphasis></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>TransientShellWidgetClass</emphasis></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>TopLevelShellWidgetClass</emphasis></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>ApplicationShellWidgetClass</emphasis></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><emphasis role='strong'>SessionShellWidgetClass</emphasis></entry>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The declarations for all Intrinsics-defined shells except
+VendorShell appear in
+<filename class="headerfile">Shell.h</filename>
+and
+<filename class="headerfile">ShellP.h</filename>.
+VendorShell has separate public and private .h files which are included by
+<filename class="headerfile">Shell.h</filename>
+and
+<filename class="headerfile">ShellP.h</filename>.
+</para>
+
+<para>
+<filename class="headerfile">Shell.h</filename>
+uses incomplete structure definitions to ensure that the
+compiler catches attempts to access private data in any of the Shell
+instance or class data structures.
+</para>
+
+<para>
+The symbolic constant for the
+<function>ShellClassExtension</function>
+version identifier is
+<function>XtShellExtensionVersion</function>
+(see <xref linkend='Class_Extension_Records' />).
+</para>
+
+<para>
+The root_geometry_manager procedure acts as
+the parent geometry manager for geometry requests made by shell
+widgets. When a shell widget calls either
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+or
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>,
+the root_geometry_manager procedure is invoked to
+negotiate the new geometry with the window manager. If the window
+manager permits the new geometry, the root_geometry_manager
+procedure should
+return
+<function>XtGeometryYes</function>;
+if the window manager denies the geometry
+request or does not change the window geometry within some timeout
+interval (equal to <emphasis remap='I'>wm_timeout</emphasis> in the case of WMShells), the
+root_geometry_manager procedure should return
+<function>XtGeometryNo</function>.
+If the window manager makes some alternative geometry change, the
+root_geometry_manager procedure may return either
+<function>XtGeometryNo</function>
+and handle the new geometry as a resize or
+<function>XtGeometryAlmost</function>
+in anticipation that the shell will accept the compromise. If the
+compromise is not accepted, the new size must then be handled as a
+resize. Subclasses of
+Shell
+that wish to provide their own
+root_geometry_manager procedures are strongly encouraged to use enveloping to
+invoke their superclass's root_geometry_manager procedure under most
+situations, as the window manager interaction may be very complex.
+</para>
+
+<para>
+If no
+<function>ShellClassPart</function>
+extension record is declared with <emphasis remap='I'>record_type</emphasis>
+equal to
+<emphasis role='strong'>NULLQUARK</emphasis>,
+then
+<function>XtInheritRootGeometryManager</function>
+is assumed.
+</para>
+</sect2>
+
+<sect2 id="ShellPart_Definition">
+<title>ShellPart Definition</title>
+<para>
+The various shell widgets have the following additional instance
+fields defined in
+their widget records:
+</para>
+
+<programlisting>
+typedef struct {
+ String geometry;
+ XtCreatePopupChildProc create_popup_child_proc;
+ XtGrabKind grab_kind;
+ Boolean spring_loaded;
+ Boolean popped_up;
+ Boolean allow_shell_resize;
+ Boolean client_specified;
+ Boolean save_under;
+ Boolean override_redirect;
+ XtCallbackList popup_callback;
+ XtCallbackList popdown_callback;
+ Visual * visual;
+} ShellPart;
+</programlisting>
+
+<programlisting>
+typedef struct {
+ int empty;
+} OverrideShellPart;
+</programlisting>
+
+<programlisting>
+typedef struct {
+ String title;
+ int wm_timeout;
+ Boolean wait_for_wm;
+ Boolean transient;
+ Boolean urgency;
+ Widget client_leader;
+ String window_role;
+ struct _OldXSizeHints {
+ long flags;
+ int x, y;
+ int width, height;
+ int min_width, min_height;
+ int max_width, max_height;
+ int width_inc, height_inc;
+ struct {
+ int x;
+ int y;
+ } min_aspect, max_aspect;
+ } size_hints;
+ XWMHints wm_hints;
+ int base_width, base_height, win_gravity;
+ Atom title_encoding;
+} WMShellPart;
+</programlisting>
+
+<programlisting>
+typedef struct {
+ int vendor_specific;
+} VendorShellPart;
+</programlisting>
+
+<programlisting>
+typedef struct {
+ Widget transient_for;
+} TransientShellPart;
+typedef struct {
+ String icon_name;
+ Boolean iconic;
+ Atom icon_name_encoding;
+} TopLevelShellPart;
+</programlisting>
+
+<programlisting>
+typedef struct {
+ char * class;
+ XrmClass xrm_class;
+ int argc;
+ char ** argv;
+} ApplicationShellPart;
+</programlisting>
+
+<programlisting>
+typedef struct {
+ SmcConn connection;
+ String session_id;
+ String * restart_command;
+ String * clone_command;
+ String * discard_command;
+ String * resign_command;
+ String * shutdown_command;
+ String * environment;
+ String current_dir;
+ String program_path;
+ unsigned char restart_style;
+ Boolean join_session;
+ XtCallbackList save_callbacks;
+ XtCallbackList interact_callbacks;
+ XtCallbackList cancel_callbacks;
+ XtCallbackList save_complete_callbacks;
+ XtCallbackList die_callbacks;
+ XtCallbackList error_callbacks;
+} SessionShellPart;
+</programlisting>
+
+<para>
+The full shell widget instance record definitions are:
+</para>
+
+<programlisting>
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ShellPart shell;
+} ShellRec, *ShellWidget;
+</programlisting>
+
+<programlisting>
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ShellPart shell;
+ OverrideShellPart override;
+} OverrideShellRec, *OverrideShellWidget;
+</programlisting>
+
+<programlisting>
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ShellPart shell;
+ WMShellPart wm;
+} WMShellRec, *WMShellWidget;
+</programlisting>
+
+<programlisting>
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ShellPart shell;
+ WMShellPart wm;
+ VendorShellPart vendor;
+} VendorShellRec, *VendorShellWidget;
+</programlisting>
+
+<programlisting>
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ShellPart shell;
+ WMShellPart wm;
+ VendorShellPart vendor;
+ TransientShellPart transient;
+} TransientShellRec, *TransientShellWidget;
+</programlisting>
+
+<programlisting>
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ShellPart shell;
+ WMShellPart wm;
+ VendorShellPart vendor;
+ TopLevelShellPart topLevel;
+} TopLevelShellRec, *TopLevelShellWidget;
+</programlisting>
+
+<programlisting>
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ShellPart shell;
+ WMShellPart wm;
+ VendorShellPart vendor;
+ TopLevelShellPart topLevel;
+ ApplicationShellPart application;
+} ApplicationShellRec, *ApplicationShellWidget;
+</programlisting>
+
+<programlisting>
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ShellPart shell;
+ WMShellPart wm;
+ VendorShellPart vendor;
+ TopLevelShellPart topLevel;
+ ApplicationShellPart application;
+ SessionShellPart session;
+} SessionShellRec, *SessionShellWidget;
+</programlisting>
+
+</sect2>
+
+<sect2 id="Shell_Resources">
+<title>Shell Resources</title>
+<para>
+The resource names, classes, and representation types specified in
+the
+<function>shellClassRec</function>
+resource list are:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNallowShellResize</entry>
+ <entry>XtCAllowShellResize</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ <row>
+ <entry>XtNcreatePopupChildProc</entry>
+ <entry>XtCCreatePopupChildProc</entry>
+ <entry>XtRFunction</entry>
+ </row>
+ <row>
+ <entry>XtNgeometry</entry>
+ <entry>XtCGeometry</entry>
+ <entry>XtRString</entry>
+ </row>
+ <row>
+ <entry>XtNoverrideRedirect</entry>
+ <entry>XtCOverrideRedirect</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ <row>
+ <entry>XtNpopdownCallback</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNpopupCallback</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNsaveUnder</entry>
+ <entry>XtCSaveUnder</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ <row>
+ <entry>XtNvisual</entry>
+ <entry>XtCVisual</entry>
+ <entry>XtRVisual</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+OverrideShell
+declares no additional resources beyond those defined by
+Shell.
+</para>
+
+<para>
+The resource names, classes, and representation types specified in
+the
+<function>wmShellClassRec</function>
+resource list are:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNbaseHeight</entry>
+ <entry>XtCBaseHeight</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNbaseWidth</entry>
+ <entry>XtCBaseWidth</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNclientLeader</entry>
+ <entry>XtCClientLeader</entry>
+ <entry>XtRWidget</entry>
+ </row>
+ <row>
+ <entry>XtNheightInc</entry>
+ <entry>XtCHeightInc</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNiconMask</entry>
+ <entry>XtCIconMask</entry>
+ <entry>XtRBitmap</entry>
+ </row>
+ <row>
+ <entry>XtNiconPixmap</entry>
+ <entry>XtCIconPixmap</entry>
+ <entry>XtRBitmap</entry>
+ </row>
+ <row>
+ <entry>XtNiconWindow</entry>
+ <entry>XtCIconWindow</entry>
+ <entry>XtRWindow</entry>
+ </row>
+ <row>
+ <entry>XtNiconX</entry>
+ <entry>XtCIconX</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNiconY</entry>
+ <entry>XtCIconY</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNinitialState</entry>
+ <entry>XtCInitialState</entry>
+ <entry>XtRInitialState</entry>
+ </row>
+ <row>
+ <entry>XtNinput</entry>
+ <entry>XtCInput</entry>
+ <entry>XtRBool</entry>
+ </row>
+ <row>
+ <entry>XtNmaxAspectX</entry>
+ <entry>XtCMaxAspectX</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNmaxAspectY</entry>
+ <entry>XtCMaxAspectY</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNmaxHeight</entry>
+ <entry>XtCMaxHeight</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNmaxWidth</entry>
+ <entry>XtCMaxWidth</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNminAspectX</entry>
+ <entry>XtCMinAspectX</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNminAspectY</entry>
+ <entry>XtCMinAspectY</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNminHeight</entry>
+ <entry>XtCMinHeight</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNminWidth</entry>
+ <entry>XtCMinWidth</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNtitle</entry>
+ <entry>XtCTitle</entry>
+ <entry>XtRString</entry>
+ </row>
+ <row>
+ <entry>XtNtitleEncoding</entry>
+ <entry>XtCTitleEncoding</entry>
+ <entry>XtRAtom</entry>
+ </row>
+ <row>
+ <entry>XtNtransient</entry>
+ <entry>XtCTransient</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ <row>
+ <entry>XtNwaitforwm, XtNwaitForWm</entry>
+ <entry>XtCWaitforwm, XtCWaitForWm</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ <row>
+ <entry>XtNwidthInc</entry>
+ <entry>XtCWidthInc</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNwindowRole</entry>
+ <entry>XtCWindowRole</entry>
+ <entry>XtRString</entry>
+ </row>
+ <row>
+ <entry>XtNwinGravity</entry>
+ <entry>XtCWinGravity</entry>
+ <entry>XtRGravity</entry>
+ </row>
+ <row>
+ <entry>XtNwindowGroup</entry>
+ <entry>XtCWindowGroup</entry>
+ <entry>XtRWindow</entry>
+ </row>
+ <row>
+ <entry>XtNwmTimeout</entry>
+ <entry>XtCWmTimeout</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNurgency</entry>
+ <entry>XtCUrgency</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The class resource list for
+VendorShell
+is implementation-defined.
+</para>
+
+<para>
+The resource names, classes, and representation types that are specified in the
+<function>transientShellClassRec</function>
+resource list are:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNtransientFor</entry>
+ <entry>XtCTransientFor</entry>
+ <entry>XtRWidget</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The resource names, classes, and representation types that are specified in the
+<function>topLevelShellClassRec</function>
+resource list are:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNiconName</entry>
+ <entry>XtCIconName</entry>
+ <entry>XtRString</entry>
+ </row>
+ <row>
+ <entry>XtNiconNameEncoding</entry>
+ <entry>XtCIconNameEncoding</entry>
+ <entry>XtRAtom</entry>
+ </row>
+ <row>
+ <entry>XtNiconic</entry>
+ <entry>XtCIconic</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The resource names, classes, and representation types that are specified in the
+<function>applicationShellClassRec</function>
+resource list are:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNargc</entry>
+ <entry>XtCArgc</entry>
+ <entry>XtRInt</entry>
+ </row>
+ <row>
+ <entry>XtNargv</entry>
+ <entry>XtCArgv</entry>
+ <entry>XtRStringArray</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The resource names, classes, and representation types that are specified
+in the
+<function>sessionShellClassRec</function>
+resource list are:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNcancelCallback</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNcloneCommand</entry>
+ <entry>XtCCloneCommand</entry>
+ <entry>XtRCommandArgArray</entry>
+ </row>
+ <row>
+ <entry>XtNconnection</entry>
+ <entry>XtCConnection</entry>
+ <entry>XtRSmcConn</entry>
+ </row>
+ <row>
+ <entry>XtNcurrentDirectory</entry>
+ <entry>XtCCurrentDirectory</entry>
+ <entry>XtRDirectoryString</entry>
+ </row>
+ <row>
+ <entry>XtNdieCallback</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNdiscardCommand</entry>
+ <entry>XtCDiscardCommand</entry>
+ <entry>XtRCommandArgArray</entry>
+ </row>
+ <row>
+ <entry>XtNenvironment</entry>
+ <entry>XtCEnvironment</entry>
+ <entry>XtREnvironmentArray</entry>
+ </row>
+ <row>
+ <entry>XtNerrorCallback</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNinteractCallback</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNjoinSession</entry>
+ <entry>XtCJoinSession</entry>
+ <entry>XtRBoolean</entry>
+ </row>
+ <row>
+ <entry>XtNprogramPath</entry>
+ <entry>XtCProgramPath</entry>
+ <entry>XtRString</entry>
+ </row>
+ <row>
+ <entry>XtNresignCommand</entry>
+ <entry>XtCResignCommand</entry>
+ <entry>XtRCommandArgArray</entry>
+ </row>
+ <row>
+ <entry>XtNrestartCommand</entry>
+ <entry>XtCRestartCommand</entry>
+ <entry>XtRCommandArgArray</entry>
+ </row>
+ <row>
+ <entry>XtNrestartStyle</entry>
+ <entry>XtCRestartStyle</entry>
+ <entry>XtRRestartStyle</entry>
+ </row>
+ <row>
+ <entry>XtNsaveCallback</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNsaveCompleteCallback</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNsessionID</entry>
+ <entry>XtCSessionID</entry>
+ <entry>XtRString</entry>
+ </row>
+ <row>
+ <entry>XtNshutdownCommand</entry>
+ <entry>XtCShutdownCommand</entry>
+ <entry>XtRCommandArgArray</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+</sect2>
+
+<sect2 id="ShellPart_Default_Values">
+<title>ShellPart Default Values</title>
+<para>
+The default values for fields common to all classes of public shells
+(filled in by the
+Shell
+resource lists and the
+Shell
+initialize procedures) are:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>geometry</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>create_popup_child_proc</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>grab_kind</entry>
+ <entry>(none)</entry>
+ </row>
+ <row>
+ <entry>spring_loaded</entry>
+ <entry>(none)</entry>
+ </row>
+ <row>
+ <entry>popped_up</entry>
+ <entry><function>False</function></entry>
+ </row>
+ <row>
+ <entry>allow_shell_resize</entry>
+ <entry><function>False</function></entry>
+ </row>
+ <row>
+ <entry>client_specified</entry>
+ <entry>(internal)</entry>
+ </row>
+ <row>
+ <entry>save_under</entry>
+ <entry><function>True</function>
+ for OverrideShell and TransientShell,
+ <emphasis role='strong'>False</emphasis>
+ otherwise</entry>
+ </row>
+ <row>
+ <entry>override_redirect</entry>
+ <entry><function>True</function>
+ for OverrideShell,
+ <function>False</function>
+ otherwise</entry>
+ </row>
+ <row>
+ <entry>popup_callback</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>popdown_callback</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>visual</entry>
+ <entry><function>CopyFromParent</function></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The <emphasis remap='I'>geometry</emphasis> field specifies the size and position
+and is usually given only on a command line or in a defaults file.
+If the <emphasis remap='I'>geometry</emphasis> field is non-NULL when
+a widget of class WMShell
+is realized, the geometry specification is parsed using
+<function>XWMGeometry</function>
+with a default geometry
+string constructed from the values of <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>,
+<emphasis remap='I'>height</emphasis>, <emphasis remap='I'>width_inc</emphasis>,
+and <emphasis remap='I'>height_inc</emphasis> and the size and position flags in the window manager
+size hints are set. If the geometry specifies an x or y position,
+then
+<function>USPosition</function>
+is set. If the geometry specifies a width or height, then
+<function>USSize</function>
+is set. Any fields in the geometry specification
+override the corresponding values in the
+Core <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, and <emphasis remap='I'>height</emphasis> fields.
+If <emphasis remap='I'>geometry</emphasis> is NULL or contains only a partial specification, then the
+Core <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, and <emphasis remap='I'>height</emphasis> fields are used and
+<function>PPosition</function>
+and
+<function>PSize</function>
+are set as appropriate.
+The geometry string is not copied by any of the Intrinsics
+Shell classes; a client specifying the string in an arglist
+or varargs list must ensure
+that the value remains valid until the shell widget is realized.
+For further information on the geometry string, see
+Parsing the Window Geometry
+in Xlib — C Language X Interface.
+</para>
+
+<para>
+The <emphasis remap='I'>create_popup_child_proc</emphasis> procedure is called by the
+<xref linkend='XtPopup' xrefstyle='select: title'/>
+procedure and may remain NULL.
+The <emphasis remap='I'>grab_kind</emphasis>, <emphasis remap='I'>spring_loaded</emphasis>,
+and <emphasis remap='I'>popped_up</emphasis> fields maintain widget
+state information as described under
+<xref linkend='XtPopup' xrefstyle='select: title'/>,
+<xref linkend='XtMenuPopup' xrefstyle='select: title'/>,
+<xref linkend='XtPopdown' xrefstyle='select: title'/>,
+and
+<xref linkend='XtMenuPopdown' xrefstyle='select: title'/>.
+The <emphasis remap='I'>allow_shell_resize</emphasis> field controls whether the widget contained
+by the shell is allowed to try to resize itself.
+If allow_shell_resize is
+<function>False</function>,
+any geometry requests made by the child will always return
+<function>XtGeometryNo</function>
+without interacting with the window manager.
+Setting <emphasis remap='I'>save_under</emphasis>
+<function>True</function>
+instructs the server to attempt
+to save the contents of windows obscured by the shell when it is mapped
+and to restore those contents automatically when the shell is unmapped.
+It is useful for pop-up menus.
+Setting <emphasis remap='I'>override_redirect</emphasis>
+<function>True</function>
+determines
+whether the window manager can intercede when the shell window
+is mapped.
+For further information on override_redirect,
+see Window Attributes in
+Xlib — C Language X Interface
+and
+Pop-up Windows and
+Redirection of Operations in the
+Inter-Client Communication Conventions Manual.
+The pop-up and pop-down callbacks are called during
+<xref linkend='XtPopup' xrefstyle='select: title'/>
+and
+<xref linkend='XtPopdown' xrefstyle='select: title'/>.
+The default value of the <emphasis remap='I'>visual</emphasis> resource is the symbolic value
+<function>CopyFromParent</function>.
+The Intrinsics do not need to query the parent's visual type when the
+default value is used; if a client using
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+to examine the visual type receives the value
+<function>CopyFromParent</function>,
+it must then use
+<function>XGetWindowAttributes</function>
+if it needs the actual visual type.
+</para>
+
+<para>
+The default values for Shell fields in
+WMShell
+and its subclasses are:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>title</entry>
+ <entry>Icon name, if specified, otherwise the application's name</entry>
+ </row>
+ <row>
+ <entry>wm_timeout</entry>
+ <entry>Five seconds, in units of milliseconds</entry>
+ </row>
+ <row>
+ <entry>wait_for_wm</entry>
+ <entry><function>True</function></entry>
+ </row>
+ <row>
+ <entry>transient</entry>
+ <entry><function>True</function>
+ for TransientShell,
+ <function>False</function>
+ otherwise</entry>
+ </row>
+ <row>
+ <entry>urgency</entry>
+ <entry><function>False</function></entry>
+ </row>
+ <row>
+ <entry>client_leader</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>window_role</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>min_width</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>min_height</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>max_width</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>max_height</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>width_inc</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>height_inc</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>min_aspect_x</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>min_aspect_y</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>max_aspect_x</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>max_aspect_y</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>input</entry>
+ <entry><function>False</function></entry>
+ </row>
+ <row>
+ <entry>initial_state</entry>
+ <entry>Normal</entry>
+ </row>
+ <row>
+ <entry>icon_pixmap</entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>icon_window</entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>icon_x</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>icon_y</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>icon_mask</entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry>window_group</entry>
+ <entry><function>XtUnspecifiedWindow</function></entry>
+ </row>
+ <row>
+ <entry>base_width</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>base_height</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>win_gravity</entry>
+ <entry><function>XtUnspecifiedShellInt</function></entry>
+ </row>
+ <row>
+ <entry>title_encoding</entry>
+ <entry>See text</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The <emphasis remap='I'>title</emphasis> and
+<emphasis remap='I'>title_encoding</emphasis> fields are stored in the
+<emphasis role='strong'>WM_NAME</emphasis>
+property on the shell's window by the WMShell realize procedure.
+If the <emphasis remap='I'>title_encoding</emphasis> field is
+<function>None</function>,
+the <emphasis remap='I'>title</emphasis> string is assumed to be in the encoding of the current
+locale and the encoding of the
+<emphasis role='strong'>WM_NAME</emphasis>
+property is set to
+<function>XStdICCTextStyle</function>.
+If a language procedure has not been set
+the default value of <emphasis remap='I'>title_encoding</emphasis> is
+<emphasis role='strong'>XA_STRING</emphasis>, otherwise the default value is
+<function>None</function>.
+The <emphasis remap='I'>wm_timeout</emphasis> field specifies, in milliseconds,
+the amount of time a shell is to wait for
+confirmation of a geometry request to the window manager.
+If none comes back within that time,
+the shell assumes the window manager is not functioning properly
+and sets <emphasis remap='I'>wait_for_wm</emphasis> to
+<function>False</function>
+(later events may reset this value).
+When <emphasis remap='I'>wait_for_wm</emphasis> is
+<function>False</function>,
+the shell does not wait for a response, but relies on asynchronous
+notification.
+If <emphasis remap='I'>transient</emphasis> is
+<function>True</function>,
+the
+<emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
+property
+will be stored on the shell window with a value as specified below.
+The interpretation of this property is specific to the window manager
+under which the application is run; see the
+Inter-Client Communication Conventions Manual
+for more details.
+</para>
+
+<para>
+The realize and set_values procedures of WMShell store the
+<emphasis role='strong'>WM_CLIENT_LEADER</emphasis>
+property on the shell window.
+When <emphasis remap='I'>client_leader</emphasis> is not NULL and the client leader widget is
+realized, the property will be created with the value of the window of the
+client leader widget.
+When <emphasis remap='I'>client_leader</emphasis> is NULL and the shell widget has a NULL parent,
+the widget's window is used as the value of the
+property.
+When <emphasis remap='I'>client_leader</emphasis> is NULL and the shell widget has a non-NULL parent,
+a search is made for the closest shell ancestor
+with a non-NULL <emphasis remap='I'>client_leader</emphasis>,
+and if none is found the shell ancestor with a NULL parent is the result.
+If the resulting widget is realized, the property is created
+with the value of the widget's window.
+</para>
+
+<para>
+When the value of <emphasis remap='I'>window_role</emphasis> is not NULL, the
+realize and set_values procedures store the
+<emphasis role='strong'>WM_WINDOW_ROLE</emphasis>
+property on the shell's window with the value of the resource.
+</para>
+
+<para>
+All other resources specify fields in the window manager hints
+and the window manager size hints.
+The realize and set_values procedures of
+WMShell
+set the corresponding flag bits in the
+hints if any of the fields contain nondefault values. In addition, if
+a flag bit is set that refers to a field with the value
+<function>XtUnspecifiedShellInt</function>,
+the value of the field is modified as follows:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Replacement</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>base_width, base_height</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>width_inc, height_inc</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>max_width, max_height</entry>
+ <entry>32767</entry>
+ </row>
+ <row>
+ <entry>min_width, min_height</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>min_aspect_x, min_aspect_y</entry>
+ <entry>-1</entry>
+ </row>
+ <row>
+ <entry>max_aspect_x, max_aspect_y</entry>
+ <entry>-1</entry>
+ </row>
+ <row>
+ <entry>icon_x, icon_y</entry>
+ <entry>-1</entry>
+ </row>
+ <row>
+ <entry>win_gravity</entry>
+ <entry>Value returned by
+ <function>XWMGeometry</function>
+ if called,
+ else <function>NorthWestGravity</function></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+If the shell widget has a non-NULL parent, then the
+realize and set_values procedures replace the value
+<function>XtUnspecifiedWindow</function>
+in the <emphasis remap='I'>window_group</emphasis> field with the window id of the root widget
+of the widget tree if the
+root widget is realized. The symbolic constant
+<function>XtUnspecifiedWindowGroup</function>
+may be used to indicate that the <emphasis remap='I'>window_group</emphasis> hint flag bit is not
+to be set. If <emphasis remap='I'>transient</emphasis> is
+<function>True</function>,
+the shell's class is not a subclass of
+TransientShell,
+and <emphasis remap='I'>window_group</emphasis> is not
+<function>XtUnspecifiedWindowGroup</function>,
+the WMShell realize and set_values procedures then store the
+<emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
+property with the value of <emphasis remap='I'>window_group</emphasis>.
+</para>
+
+<para>
+Transient
+shells have the following additional resource:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Replacement</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>transient_for</entry>
+ <entry>NULL</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The realize and set_values procedures of
+TransientShell
+store the
+<emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
+property on the shell window if <emphasis remap='I'>transient</emphasis> is
+<function>True</function>.
+If <emphasis remap='I'>transient_for</emphasis> is non-NULL and the widget specified by
+<emphasis remap='I'>transient_for</emphasis> is realized, then its window is used as the value of the
+<emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
+property; otherwise, the value of <emphasis remap='I'>window_group</emphasis> is used.
+</para>
+
+<para>
+<function>TopLevel</function>
+shells have the the following additional resources:
+</para>
+
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>icon_name</entry>
+ <entry>Shell widget's name</entry>
+ </row>
+ <row>
+ <entry>iconic</entry>
+ <entry><emphasis role='strong'>False</emphasis></entry>
+ </row>
+ <row>
+ <entry>icon_name_encoding</entry>
+ <entry>See text</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The <emphasis remap='I'>icon_name</emphasis>
+and <emphasis remap='I'>icon_name_encoding</emphasis> fields are stored in the
+<emphasis role='strong'>WM_ICON_NAME</emphasis>
+property on the shell's window by the TopLevelShell realize
+procedure.
+If the <emphasis remap='I'>icon_name_encoding</emphasis> field is
+<function>None</function>,
+the <emphasis remap='I'>icon_name</emphasis> string is assumed to be in the encoding of the
+current locale and the encoding of the
+<emphasis role='strong'>WM_ICON_NAME</emphasis>
+property is set to
+<function>XStdICCTextStyle</function>.
+If a language procedure has not been set,
+the default value of <emphasis remap='I'>icon_name_encoding</emphasis> is
+<emphasis role='strong'>XA_STRING</emphasis>, otherwise the default value is
+<function>None</function>.
+The <emphasis remap='I'>iconic</emphasis> field may be used by a client to request
+that the window manager iconify or deiconify the shell; the
+TopLevelShell
+set_values procedure will send the appropriate
+<emphasis role='strong'>WM_CHANGE_STATE</emphasis>
+message (as specified by the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>)
+if this resource is changed from
+<function>False</function>
+to
+<function>True</function>
+and will call
+<xref linkend='XtPopup' xrefstyle='select: title'/>
+specifying <emphasis remap='I'>grab_kind</emphasis> as
+<function>XtGrabNone</function>
+if <emphasis remap='I'>iconic</emphasis> is changed from
+<function>True</function>
+to
+<function>False</function>.
+The XtNiconic resource is also an alternative way to set
+the XtNinitialState resource
+to indicate that a shell should be initially displayed as an icon; the
+TopLevelShell
+initialize procedure will set <emphasis remap='I'>initial_state</emphasis> to
+<function>IconicState</function>
+if <emphasis remap='I'>iconic</emphasis> is
+<function>True</function>.
+</para>
+
+<para>
+Application
+shells have the following additional resources:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>argc</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>argv</entry>
+ <entry>NULL</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The <emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis> fields are used to initialize
+the standard property
+<emphasis role='strong'>WM_COMMAND</emphasis>. See the
+Inter-Client Communication Conventions Manual
+for more information.
+</para>
+
+<para>
+The default values for the SessionShell instance fields,
+which are filled in from the resource lists and by the
+initialize procedure, are
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>cancel_callbacks</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>clone_command</entry>
+ <entry>See text</entry>
+ </row>
+ <row>
+ <entry>connection</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>current_dir</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>die_callbacks</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>discard_command</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>environment</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>error_callbacks</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>interact_callbacks</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>join_session</entry>
+ <entry><emphasis role='strong'>True</emphasis></entry>
+ </row>
+ <row>
+ <entry>program_path</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>resign_command</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>restart_command</entry>
+ <entry>See text</entry>
+ </row>
+ <row>
+ <entry>restart_style</entry>
+ <entry><emphasis role='strong'>SmRestartIfRunning</emphasis></entry>
+ </row>
+ <row>
+ <entry>save_callbacks</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>save_complete_callbacks</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>session_id</entry>
+ <entry>NULL</entry>
+ </row>
+ <row>
+ <entry>shutdown_command</entry>
+ <entry>NULL</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The <emphasis remap='I'>connection</emphasis> field contains the session connection object or NULL
+if a session connection is not being managed by this widget.
+</para>
+
+<para>
+The <emphasis remap='I'>session_id</emphasis> is an identification assigned to the session
+participant by the session manager.
+The <emphasis remap='I'>session_id</emphasis> will be passed to the session
+manager as the client identifier of the previous session.
+When a connection is established with the session manager,
+the client id assigned by the session manager is stored
+in the <emphasis remap='I'>session_id</emphasis> field.
+When not NULL, the <emphasis remap='I'>session_id</emphasis> of the Session shell widget that
+is at the root of the widget tree of the client leader widget will be
+used to create the
+<emphasis role='strong'>SM_CLIENT_ID</emphasis>
+property on the client leader's window.
+</para>
+
+<para>
+If <emphasis remap='I'>join_session</emphasis> is
+<function>False</function>,
+the widget will not attempt to establish a
+connection to the session manager at shell creation time.
+See <xref linkend='Joining_a_Session' /> and
+<xref linkend='Resigning_from_a_Session' />
+for more information on the functionality of this resource.
+</para>
+
+<para>
+The <emphasis remap='I'>restart_command</emphasis>, <emphasis remap='I'>clone_command</emphasis>, <emphasis remap='I'>discard_command</emphasis>,
+<emphasis remap='I'>resign_command</emphasis>, <emphasis remap='I'>shutdown_command</emphasis>, <emphasis remap='I'>environment</emphasis>,
+<emphasis remap='I'>current_dir</emphasis>, <emphasis remap='I'>program_path</emphasis>, and
+<emphasis remap='I'>restart_style</emphasis> fields contain standard session properties.
+</para>
+
+<para>
+When a session connection is established or newly managed by the shell,
+the shell initialize and set_values methods check the values of the
+<emphasis remap='I'>restart_command</emphasis>,
+<emphasis remap='I'>clone_command</emphasis>,
+and <emphasis remap='I'>program_path</emphasis>
+resources. At that time, if <emphasis remap='I'>restart_command</emphasis> is NULL, the value
+of the <emphasis remap='I'>argv</emphasis> resource will be copied to <emphasis remap='I'>restart_command</emphasis>.
+Whether or not <emphasis remap='I'>restart_command</emphasis> was NULL,
+if “<emphasis>-xtsessionID</emphasis>” “<emphasis><session id></emphasis>” does not
+already appear in the <emphasis remap='I'>restart_command</emphasis>, it will be added by the
+initialize and set_values methods at the beginning of the command arguments;
+if the “<emphasis>-xtsessionID</emphasis>” argument already appears with an incorrect
+<emphasis>session id</emphasis> in the following argument, that argument
+will be replaced with the current <emphasis>session id</emphasis>.
+</para>
+
+<para>
+After this, the shell initialize and set_values procedures check the
+<emphasis remap='I'>clone_command</emphasis>. If <emphasis remap='I'>clone_command</emphasis> is NULL,
+<emphasis remap='I'>restart_command</emphasis> will be copied to <emphasis remap='I'>clone_command</emphasis>,
+except the “<emphasis>-xtsessionID</emphasis>” and following argument will not be copied.
+</para>
+
+<para>
+Finally, the shell initialize and set_values procedures check the
+<emphasis remap='I'>program_path</emphasis>. If <emphasis remap='I'>program_path</emphasis> is NULL, the
+first element of <emphasis remap='I'>restart_command</emphasis> is copied to <emphasis remap='I'>program_path</emphasis>.
+</para>
+
+<para>
+The possible values of <emphasis remap='I'>restart_style</emphasis> are
+<function>SmRestartIfRunning</function>,
+<function>SmRestartAnyway</function>,
+<function>SmRestartImmediately</function>,
+and
+<function>SmRestartNever</function>.
+A resource converter is registered for this resource;
+for the strings that it recognizes,
+see <xref linkend='Predefined_Resource_Converters' />.
+</para>
+
+<para>
+The resource type EnvironmentArray is a NULL-terminated array of
+pointers to strings;
+each string has the format “name=value”.
+The `=' character may not appear in the name,
+and the string is terminated by a null character.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Session_Participation">
+<title>Session Participation</title>
+<para>
+Applications can participate in a user's session, exchanging messages
+with the session manager as described in the
+<emphasis>X Session Management Protocol</emphasis> and the
+<emphasis remap='I'>X Session Management Library</emphasis>.
+</para>
+
+<para>
+When a widget of
+<function>sessionShellWidgetClass</function>
+or a subclass is created, the widget provides support for the application
+as a session participant and continues to provide support until the
+widget is destroyed.
+</para>
+
+<sect2 id="Joining_a_Session">
+<title>Joining a Session</title>
+<para>
+When a Session shell is created,
+if <emphasis remap='I'>connection</emphasis> is NULL,
+and if <emphasis remap='I'>join_session</emphasis> is
+<function>True</function>,
+and if <emphasis remap='I'>argv</emphasis> or <emphasis remap='I'>restart_command</emphasis> is not NULL,
+and if in POSIX environments the
+<emphasis role='strong'>SESSION_MANAGER</emphasis>
+environment variable is defined,
+the shell will attempt to establish a new connection with the session manager.
+</para>
+
+<para>
+To transfer management of an existing session connection from an
+application to the shell at widget creation time, pass the existing
+session connection ID as the <emphasis remap='I'>connection</emphasis> resource value
+when creating the Session shell,
+and if the other creation-time conditions on session participation are met,
+the widget will maintain the connection with the session manager.
+The application must ensure that only one
+Session shell manages the connection.
+</para>
+
+<para>
+In the Session shell set_values procedure,
+if <emphasis remap='I'>join_session</emphasis> changes from
+<function>False</function>
+to
+<function>True</function>
+and <emphasis remap='I'>connection</emphasis> is NULL and when in POSIX environments the
+<emphasis role='strong'>SESSION_MANAGER</emphasis>
+environment variable is defined,
+the shell will attempt to open a connection to the session manager.
+If <emphasis remap='I'>connection</emphasis> changes from NULL to non-NULL, the
+Session shell
+will take over management of that session connection and will set
+<emphasis remap='I'>join_session</emphasis> to
+<function>True</function>.
+If <emphasis remap='I'>join_session</emphasis> changes from
+<function>False</function>
+to
+<function>True</function>
+and <emphasis remap='I'>connection</emphasis> is not NULL, the
+Session shell will take over management of the session connection.
+</para>
+
+<para>
+When a successful connection has been established, <emphasis remap='I'>connection</emphasis>
+contains the session connection ID for the session participant.
+When the shell begins to manage the connection, it will call
+<xref linkend='XtAppAddInput' xrefstyle='select: title'/>
+to register the handler which watches for protocol messages
+from the session manager.
+When the attempt to connect fails, a warning message is issued
+and <emphasis remap='I'>connection</emphasis> is set to NULL.
+</para>
+
+<para>
+While the connection is being managed, if a
+<function>SaveYourself</function>,
+<function>SaveYourselfPhase2</function>,
+<function>Interact</function>,
+<function>ShutdownCancelled</function>,
+<function>SaveComplete</function>,
+or
+<function>Die</function>
+message is received from the session manager, the Session shell will
+call out to application callback procedures registered
+on the respective callback list of the Session shell and will
+send
+<function>SaveYourselfPhase2Request</function>,
+<function>InteractRequest</function>,
+<function>InteractDone</function>,
+<function>SaveYourselfDone</function>,
+and
+<function>ConnectionClosed</function>
+messages as appropriate.
+Initially, all of the client's session properties are undefined.
+When any of the session property resource values are defined or change,
+the Session shell initialize and set_values procedures
+will update the client's session property value by a
+<function>SetProperties</function>
+or a
+<function>DeleteProperties</function>
+message, as appropriate.
+The session ProcessID and UserID properties are always set by the shell
+when it is possible to determine the value of these properties.
+</para>
+</sect2>
+
+<sect2 id="Saving_Application_State">
+<title>Saving Application State</title>
+<para>
+The session manager instigates an application checkpoint by sending a
+<function>SaveYourself</function>
+request.
+Applications are responsible for saving their state in response to the
+request.
+</para>
+
+<para>
+When the
+<function>SaveYourself</function>
+request arrives, the procedures registered on the
+Session shell's save callback list are called.
+If the application does not register any save callback procedures on
+the save callback list, the shell will report to the session manager
+that the application failed to save its state.
+Each procedure on the save callback list receives a token
+in the <emphasis remap='I'>call_data</emphasis> parameter.
+</para>
+
+<para>
+The checkpoint token in the <emphasis remap='I'>call_data</emphasis> parameter is of type
+<function>XtCheckpointToken</function>.
+</para>
+
+<programlisting>
+typedef struct {
+ int save_type;
+ int interact_style;
+ Boolean shutdown;
+ Boolean fast;
+ Boolean cancel_shutdown
+ int phase;
+ int interact_dialog_type; /* return */
+ Boolean request_cancel; /* return */
+ Boolean request_next_phase; /* return */
+ Boolean save_success; /* return */
+} XtCheckpointTokenRec, *XtCheckpointToken;
+</programlisting>
+
+<para>
+The <emphasis remap='I'>save_type</emphasis>, <emphasis remap='I'>interact_style</emphasis>, <emphasis remap='I'>shutdown</emphasis>, and <emphasis remap='I'>fast</emphasis>
+fields of the token contain the parameters of the
+<function>SaveYourself</function>
+message.
+The possible values of <emphasis remap='I'>save_type</emphasis> are
+<function>SmSaveLocal</function>,
+<function>SmSaveGlobal</function>,
+and
+<function>SmSaveBoth</function>;
+these indicate the type of information to be saved.
+The possible values of <emphasis remap='I'>interact_style</emphasis> are
+<function>SmInteractStyleNone</function>,
+<function>SmInteractStyleErrors</function>,
+and
+<function>SmInteractStyleAny</function>;
+these indicate whether user interaction would be permitted
+and, if so, what kind of interaction.
+If <emphasis remap='I'>shutdown</emphasis> is
+<function>True</function>,
+the checkpoint is being performed in preparation for the end of the session.
+If <emphasis remap='I'>fast</emphasis> is
+<function>True</function>,
+the client should perform the checkpoint as quickly as possible.
+If <emphasis remap='I'>cancel_shutdown</emphasis> is
+<function>True</function>,
+a
+<function>ShutdownCancelled</function>
+message has been received for the current save operation.
+(See <xref linkend='Resigning_from_a_Session' />.)
+The <emphasis remap='I'>phase</emphasis> is used by manager clients, such as a window manager,
+to distinguish between the first and second phase of a save operation.
+The <emphasis remap='I'>phase</emphasis> will be either 1 or 2.
+The remaining fields in the checkpoint token structure are provided for
+the application to communicate with the shell.
+</para>
+
+<para>
+Upon entry to the first application save callback procedure, the return
+fields in the token have the following initial values:
+<emphasis remap='I'>interact_dialog_type</emphasis> is
+<function>SmDialogNormal</function>;
+<emphasis remap='I'>request_cancel</emphasis> is
+<function>False</function>;
+<emphasis remap='I'>request_next_phase</emphasis> is
+<function>False</function>;
+and <emphasis remap='I'>save_success</emphasis> is
+<function>True</function>.
+When a token is returned with any of the four return fields containing
+a noninitial value, and when the field is applicable, subsequent tokens
+passed to the application during the current save operation
+will always contain the noninitial value.
+</para>
+
+<para>
+The purpose of the token's <emphasis remap='I'>save_success</emphasis> field is to
+indicate the outcome of the entire operation to the
+session manager and ultimately, to the user.
+Returning
+<function>False</function>
+indicates some portion of the application state
+could not be successfully saved. If any token is returned
+to the shell with <emphasis remap='I'>save_success</emphasis>
+<function>False</function>,
+tokens subsequently received
+by the application for the current save operation will show
+<emphasis remap='I'>save_success</emphasis> as
+<function>False</function>.
+When the shell sends the final status of the checkpoint to the
+session manager, it will indicate failure to save application state
+if any token was returned with <emphasis remap='I'>save_success</emphasis>
+<function>False</function>.
+</para>
+
+<para>
+Session participants that manage and save the state of other clients
+should structure their save or interact callbacks to
+set <emphasis remap='I'>request_next_phase</emphasis> to
+<function>True</function>
+when phase is 1, which will cause the shell to send the
+<function>SaveYourselfPhase2Request</function>
+when the first phase is complete. When the
+<function>SaveYourselfPhase2</function>
+message is received, the shell will invoke the save callbacks a
+second time with <emphasis remap='I'>phase</emphasis> equal to 2.
+Manager clients should save the state of other clients
+when the callbacks are invoked the second time and <emphasis remap='I'>phase</emphasis> equal to 2.
+</para>
+
+<para>
+The application may request additional tokens while a checkpoint is under way,
+and these additional tokens must be returned by an explicit call.
+</para>
+
+<para>
+To request an additional token for a save callback response that has a
+deferred outcome, use
+<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSessionGetToken'>
+<funcprototype>
+<funcdef>XtCheckpointToken <function>XtSessionGetToken</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Session shell widget which manages session participation.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+The
+<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>
+function will return NULL if no checkpoint operation is currently under way.
+</para>
+
+<para>
+To indicate the completion of checkpoint processing including user
+interaction, the application must signal the Session shell
+by returning all tokens.
+(See <xref linkend='Interacting_with_the_User_during_a_Checkpoint' /> and
+<xref linkend='Completing_a_Save' />).
+To return a token, use
+<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSessionReturnToken'>
+<funcprototype>
+<funcdef>void <function>XtSessionReturnToken</function></funcdef>
+ <paramdef>XtCheckpointToken <parameter>token</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>token</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a token that was received as the <emphasis remap='I'>call_data</emphasis> by a procedure
+on the interact callback list or a token that was received by a call to
+<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+Tokens passed as <emphasis remap='I'>call_data</emphasis> to save callbacks are implicitly
+returned when the save callback procedure returns.
+A save callback procedure should not call
+<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>
+on the token passed in its <emphasis remap='I'>call_data</emphasis>.
+</para>
+
+<sect3 id="Requesting_Interaction">
+<title>Requesting Interaction</title>
+<para>
+When the token <emphasis remap='I'>interact_style</emphasis> allows user interaction,
+the application may
+interact with the user during the checkpoint, but must wait for permission
+to interact.
+Applications request permission to interact with the user during the
+checkpointing operation by registering a procedure on the Session
+shell's interact callback list. When all save callback procedures have
+returned, and each time a token that was granted by a call to
+<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>
+is returned, the Session shell examines the interact callback list.
+If interaction is permitted and the interact callback list is not empty,
+the shell will send an
+<function>InteractRequest</function>
+to the session manager when an interact request is not already outstanding
+for the application.
+</para>
+
+<para>
+The type of interaction dialog that will be requested is specified by
+the <emphasis remap='I'>interact_dialog_type</emphasis> field in the checkpoint token.
+The possible values for <emphasis remap='I'>interact_dialog_type</emphasis> are
+<function>SmDialogError</function>
+and
+<function>SmDialogNormal</function>.
+If a token is returned with <emphasis remap='I'>interact_dialog_type</emphasis> containing
+<function>SmDialogError</function>,
+the interact request and any subsequent interact requests will be for
+an error dialog; otherwise, the request will be for a normal dialog with
+the user.
+</para>
+
+<para>
+When a token is returned with <emphasis remap='I'>save_success</emphasis>
+<function>False</function>
+or <emphasis remap='I'>interact_dialog_type</emphasis>
+<function>SmDialogError</function>,
+tokens subsequently passed to callbacks during the same active
+<function>SaveYourself</function>
+response will reflect these changed values, indicating that
+an error condition has occurred during the checkpoint.
+</para>
+
+<para>
+The <emphasis remap='I'>request_cancel</emphasis> field is a return value for interact callbacks only.
+Upon return from a procedure on the save callback list, the value
+of the token's <emphasis remap='I'>request_cancel</emphasis> field is not examined by the shell.
+This is also true of tokens received through a call to
+<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>.
+</para>
+</sect3>
+
+<sect3 id="Interacting_with_the_User_during_a_Checkpoint">
+<title>Interacting with the User during a Checkpoint</title>
+<para>
+When the session manager grants the application's request for user interaction,
+the Session shell receives an
+<function>Interact</function>
+message.
+The procedures registered on the interact callback list are executed,
+but not as if executing a typical callback list.
+These procedures are individually executed in
+sequence, with a checkpoint token functioning as the sequencing mechanism.
+Each step in the sequence begins by removing a procedure
+from the interact callback list
+and executing it with a token passed in the <emphasis remap='I'>call_data</emphasis>.
+The interact callback will typically pop up a dialog box and return.
+When the user interaction and associated application checkpointing has
+completed, the application must return the token by calling
+<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>.
+Returning the token completes the current step and triggers the next step
+in the sequence.
+</para>
+
+<para>
+During interaction the client may request cancellation of a shutdown.
+When a token passed as <emphasis remap='I'>call_data</emphasis> to an interact procedure is returned,
+if <emphasis remap='I'>shutdown</emphasis> is
+<function>True</function>
+and <emphasis remap='I'>cancel_shutdown</emphasis> is
+<function>False</function>,
+<emphasis remap='I'>request_cancel</emphasis> indicates whether the
+application requests that the pending shutdown be cancelled.
+If <emphasis remap='I'>request_cancel</emphasis> is
+<function>True</function>,
+the field will also be
+<function>True</function>
+in any tokens subsequently granted during the checkpoint operation.
+When a token is returned requesting cancellation of
+the session shutdown, pending interact procedures will still be
+called by the Session shell.
+When all interact procedures have been removed from the interact callback
+list, executed, and the final interact token returned to the shell, an
+<function>InteractDone</function>
+message is sent to the session manager, indicating whether
+a pending session shutdown is requested to be cancelled.
+</para>
+</sect3>
+
+<sect3 id="Responding_to_a_Shutdown_Cancellation">
+<title>Responding to a Shutdown Cancellation</title>
+<para>
+Callbacks registered on the cancel callback list are invoked when the
+Session shell processes a
+<function>ShutdownCancelled</function>
+message from the session manager. This may occur during the
+processing of save callbacks, while waiting for interact permission,
+during user interaction, or after the save operation is complete and
+the application is expecting a
+<function>SaveComplete</function>
+or a
+<function>Die</function>
+message.
+The <emphasis remap='I'>call_data</emphasis> for these callbacks is NULL.
+</para>
+
+<para>
+When the shell notices that a pending shutdown has been cancelled,
+the token <emphasis remap='I'>cancel_shutdown</emphasis> field will be
+<function>True</function>
+in tokens subsequently given to the application.
+</para>
+
+<para>
+Receiving notice of a shutdown cancellation does not cancel the
+pending execution of save callbacks or interact callbacks.
+After the cancel callbacks execute, if <emphasis remap='I'>interact_style</emphasis> is not
+<function>SmInteractStyleNone</function>
+and the interact list is not empty,
+the procedures on the interact callback list will be executed
+and passed a token with <emphasis remap='I'>interact_style</emphasis>
+<function>SmInteractStyleNone</function>.
+The application should not interact with the user, and the Session shell
+will not send an
+<function>InteractDone</function>
+message.
+</para>
+</sect3>
+
+<sect3 id="Completing_a_Save">
+<title>Completing a Save</title>
+<para>
+When there is no user interaction, the shell regards the application
+as having finished saving state when all callback procedures
+on the save callback list have returned, and any additional tokens
+passed out by
+<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>
+have been returned by corresponding calls to
+<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>.
+If the save operation involved user interaction,
+the above completion conditions apply, and in addition, all requests for
+interaction have been granted or cancelled,
+and all tokens passed to interact callbacks have been returned
+through calls to
+<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>.
+If the save operation involved a manager client that requested the
+second phase, the above conditions apply to both the first and second
+phase of the save operation.
+</para>
+
+<para>
+When the application has finished saving state,
+the Session shell will report the result to the session manager by
+sending the
+<function>SaveYourselfDone</function>
+message.
+If the session is continuing, the shell will receive the
+<function>SaveComplete</function>
+message when all applications have completed saving state.
+This message indicates that applications may again allow changes
+to their state. The shell will execute the save_complete callbacks.
+The <emphasis remap='I'>call_data</emphasis> for these callbacks is NULL.
+</para>
+</sect3>
+</sect2>
+
+<sect2 id="Responding_to_a_Shutdown">
+<title>Responding to a Shutdown</title>
+<para>
+Callbacks registered on the die callback list are invoked when the
+session manager sends a
+<function>Die</function>
+message.
+The callbacks on this list should do whatever is appropriate to quit
+the application.
+Before executing procedures on the die callback list,
+the Session shell will close the connection to the session manager
+and will remove the handler that watches for protocol messages.
+The <emphasis remap='I'>call_data</emphasis> for these callbacks is NULL.
+</para>
+</sect2>
+
+<sect2 id="Resigning_from_a_Session">
+<title>Resigning from a Session</title>
+<para>
+When the Session shell widget is destroyed, the destroy method will
+close the connection to the session manager by sending a
+<function>ConnectionClosed</function>
+protocol message and will remove the input callback
+that was watching for session protocol messages.
+</para>
+
+<para>
+When
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+is used to set <emphasis remap='I'>join_session</emphasis> to
+<function>False</function>,
+the set_values method of the Session shell will close the
+connection to the session manager if one exists by sending a
+<function>ConnectionClosed</function>
+message, and <emphasis remap='I'>connection</emphasis> will be set to NULL.
+</para>
+
+<para>
+Applications that exit in response to user actions and that do not
+wait for phase 2 destroy to complete on
+the Session shell should set <emphasis remap='I'>join_session</emphasis> to
+<function>False</function>
+before exiting.
+</para>
+
+<para>
+When
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+is used to set <emphasis remap='I'>connection</emphasis> to NULL,
+the Session shell will stop managing the connection, if one exists.
+However, that session connection will not be closed.
+</para>
+
+<para>
+Applications that wish to ensure continuation of a session connection
+beyond the destruction of the shell should first retrieve the
+<emphasis remap='I'>connection</emphasis> resource value,
+then set the <emphasis remap='I'>connection</emphasis> resource to NULL,
+and then they may safely destroy the widget without losing control
+of the session connection.
+</para>
+
+<para>
+The error callback list will be called if an unrecoverable
+communications error occurs while the shell is managing the connection.
+The shell will close the connection, set <emphasis remap='I'>connection</emphasis> to NULL,
+remove the input callback, and
+call the procedures registered on the error callback list.
+The <emphasis remap='I'>call_data</emphasis> for these callbacks is NULL.
+</para>
+</sect2>
+</sect1>
+</chapter>
Index: create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH06.xml
===================================================================
--- create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH06.xml (nonexistent)
+++ create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH06.xml (revision 5)
@@ -0,0 +1,1372 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<chapter id='Geometry_Management'>
+<title>Geometry Management</title>
+
+<para>
+A widget does not directly control its size and location;
+rather, its parent is responsible for controlling them.
+Although the position of children is usually left up to their parent,
+the widgets themselves often have the best idea of their optimal sizes
+and, possibly, preferred locations.
+</para>
+
+<para>
+To resolve physical layout conflicts between sibling widgets and between
+a widget and its parent, the Intrinsics provide the geometry management mechanism.
+Almost all
+composite
+widgets have a geometry manager specified in the <emphasis remap='I'>geometry_manager</emphasis> field
+in the widget class record that is responsible for the size, position, and
+stacking order of the widget's children.
+The only exception is fixed boxes,
+which create their children themselves and can ensure that
+their children will never make a geometry request.
+</para>
+
+<sect1 id="Initiating_Geometry_Changes">
+<title>Initiating Geometry Changes</title>
+
+<para>
+Parents, children, and clients each initiate geometry changes differently.
+Because a parent has absolute control of its children's geometry,
+it changes the geometry directly by calling
+<function>XtMoveWidget</function>,
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>,
+or
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>.
+A child must ask its parent for a geometry change by calling
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+or
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>.
+An application or other client code initiates a geometry change by calling
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+on the appropriate geometry fields,
+thereby giving the widget the opportunity to modify or reject the client
+request before it gets propagated to the parent and the opportunity
+to respond appropriately to the parent's reply.
+</para>
+
+<para>
+When a widget that needs to change its size, position, border width,
+or stacking depth asks its parent's geometry manager to make the desired
+changes,
+the geometry manager can allow the request, disallow the request, or
+suggest a compromise.
+</para>
+
+<para>
+When the geometry manager is asked to change the geometry of a child,
+the geometry manager may also rearrange and resize any or all
+of the other children that it controls.
+The geometry manager can move children around freely using
+<xref linkend='XtMoveWidget' xrefstyle='select: title'/>.
+When it resizes a child (that is, changes the width, height, or
+border width) other than the one making the request,
+it should do so by calling
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>.
+The requesting child may be given special treatment; see
+<xref linkend='Child_Geometry_Management_The_geometry_manager_Procedure' />.
+It can simultaneously move and resize a child with a single call to
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>.
+</para>
+
+<para>
+Often, geometry managers find that they can satisfy a request only if
+they can reconfigure a widget that they are not in control of; in particular,
+the
+composite
+widget may want to change its own size.
+In this case,
+the geometry manager makes a request to its parent's geometry manager.
+Geometry requests can cascade this way to arbitrary depth.
+</para>
+
+<para>
+Because such cascaded arbitration of widget geometry can involve extended
+negotiation,
+windows are not actually allocated to widgets at application
+startup until all widgets are satisfied with their geometry;
+see <xref linkend='Creating_Widgets' /> and
+<xref linkend='Realizing_Widgets' />.
+</para>
+
+<note>
+<orderedlist>
+ <listitem>
+ <para>
+The Intrinsics treatment of stacking requests is deficient in several areas.
+Stacking requests for unrealized widgets are granted but will have no effect.
+In addition, there is no way to do an
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+that will generate a stacking geometry request.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+After a successful geometry request (one that returned
+<function>XtGeometryYes</function>),
+a widget does not know whether its resize procedure has been called.
+Widgets should have resize procedures that can be called more than once
+without ill effects.
+ </para>
+ </listitem>
+</orderedlist>
+</note>
+</sect1>
+
+<sect1 id="General_Geometry_Manager_Requests">
+<title>General Geometry Manager Requests</title>
+<para>
+When making a geometry request, the child specifies an
+<function>XtWidgetGeometry</function>
+structure.
+</para>
+
+<programlisting>
+typedef unsigned long XtGeometryMask;
+typedef struct {
+ XtGeometryMask request_mode;
+ Position x, y;
+ Dimension width, height;
+ Dimension border_width;
+ Widget sibling;
+ int stack_mode;
+} XtWidgetGeometry;
+</programlisting>
+
+<para>
+To make a general geometry manager request from a widget, use
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtMakeGeometryRequest'>
+<funcprototype>
+<funcdef>XtGeometryResult <function>XtMakeGeometryRequest</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>request</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>reply_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the desired widget geometry (size, position, border width,
+and stacking order).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>reply_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the allowed widget size, or may be NULL
+if the requesting widget is not interested in handling
+<function>XtGeometryAlmost</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+Depending on the condition,
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+performs the following:
+</para>
+
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If the widget is unmanaged or the widget's parent is not realized,
+it makes the changes and returns
+<function>XtGeometryYes</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the parent's class is not a subclass of
+<function>compositeWidgetClass</function>
+or the parent's <emphasis remap='I'>geometry_manager</emphasis> field is NULL,
+it issues an error.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the widget's <emphasis remap='I'>being_destroyed</emphasis> field is
+<function>True</function>,
+it returns
+<function>XtGeometryNo</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the widget <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>, and
+<emphasis remap='I'>border_width</emphasis> fields are
+all equal to the requested values,
+it returns
+<function>XtGeometryYes</function>;
+otherwise, it calls the parent's geometry_manager procedure
+with the given parameters.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the parent's geometry manager returns
+<function>XtGeometryYes</function>
+and if
+<function>XtCWQueryOnly</function>
+is not set in <emphasis remap='I'>request->request_mode</emphasis>
+and if the widget is realized,
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+calls the
+<function>XConfigureWindow</function>
+Xlib function to reconfigure the widget's window (set its size, location,
+and stacking order as appropriate).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the geometry manager returns
+<function>XtGeometryDone</function>,
+the change has been approved and actually has been done.
+In this case,
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+does no configuring and returns
+<function>XtGeometryYes</function>.
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+never returns
+<function>XtGeometryDone</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Otherwise,
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+just returns the resulting value from the parent's geometry manager.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+Children of primitive widgets are always unmanaged; therefore,
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+always returns
+<function>XtGeometryYes</function>
+when called by a child of a primitive widget.
+</para>
+
+<para>
+The return codes from geometry managers are
+</para>
+
+<programlisting>
+typedef enum {
+ XtGeometryYes,
+ XtGeometryNo,
+ XtGeometryAlmost,
+ XtGeometryDone
+} XtGeometryResult;
+</programlisting>
+
+<para>
+The <emphasis remap='I'>request_mode</emphasis> definitions are from
+<filename class="headerfile"><X11/X.h></filename>.
+</para>
+
+<informaltable frame='none'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <tbody>
+ <row>
+ <entry>#define</entry>
+ <entry><function>CWX</function></entry>
+ <entry>(1<<0)</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>CWY</function></entry>
+ <entry>(1<<1)</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>CWWidth</function></entry>
+ <entry>(1<<2)</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>CWHeight</function></entry>
+ <entry>(1<<3)</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>CWBorderWidth</function></entry>
+ <entry>(1<<4)</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>CWSibling</function></entry>
+ <entry>(1<<5)</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>CWStackMode</function></entry>
+ <entry>(1<<6)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The Intrinsics also support the following value.
+</para>
+
+<informaltable frame='none'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <tbody>
+ <row>
+ <entry>#define</entry>
+ <entry><function>XtCWQueryOnly</function></entry>
+ <entry>(1<<7)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<function>XtCWQueryOnly</function>
+indicates that the corresponding geometry request is only a query
+as to what would happen if this geometry request were made
+and that no widgets should actually be changed.
+</para>
+
+<para>
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>,
+like the
+<function>XConfigureWindow</function>
+Xlib function, uses <emphasis remap='I'>request_mode</emphasis> to determine which fields in the
+<function>XtWidgetGeometry</function>
+structure the caller wants to specify.
+</para>
+
+<para>
+The <emphasis remap='I'>stack_mode</emphasis> definitions are from
+<filename class="headerfile"><X11/X.h></filename>:
+</para>
+
+<informaltable frame='none'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <tbody>
+ <row>
+ <entry>#define</entry>
+ <entry><function>Above</function></entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>Below</function></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>TopIf</function></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>BottomIf</function></entry>
+ <entry>3</entry>
+ </row>
+ <row>
+ <entry>#define</entry>
+ <entry><function>Opposite</function></entry>
+ <entry>4</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The Intrinsics also support the following value.
+</para>
+
+<informaltable frame='none'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <tbody>
+ <row>
+ <entry>#define</entry>
+ <entry><function>XtSMDontChange</function></entry>
+ <entry>5</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+For definition and behavior of
+<function>Above</function>,
+<function>Below</function>,
+<function>TopIf</function>,
+<function>BottomIf</function>,
+and
+<function>Opposite</function>,
+BLAH
+in Xlib — C Language X Interface.
+<function>XtSMDontChange</function>
+indicates that the widget wants its current stacking order preserved.
+</para>
+</sect1>
+
+<sect1 id="Resize_Requests">
+<title>Resize Requests</title>
+<para>
+To make a simple resize request from a widget, you can use
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>
+as an alternative to
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtMakeResizeRequest'>
+<funcprototype>
+<funcdef>typedef XtGeometryResult <function>XtMakeResizeRequest</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Dimension <parameter>width</parameter></paramdef>
+ <paramdef>Dimension *<parameter>width_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the desired widget width and height.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the allowed widget width and height.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height_return</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<para>
+The
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>
+function, a simple interface to
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>,
+creates an
+<function>XtWidgetGeometry</function>
+structure and specifies that width and height should change
+by setting <emphasis remap='I'>request_mode</emphasis> to
+<function>CWWidth</function>
+<function>|</function>
+<function>CWHeight</function>.
+The geometry manager is free to modify any of the other window attributes
+(position or stacking order) to satisfy the resize request.
+If the return value is
+<function>XtGeometryAlmost</function>,
+<emphasis remap='I'>width_return</emphasis> and <emphasis remap='I'>height_return</emphasis> contain a compromise width and height.
+If these are acceptable,
+the widget should immediately call
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>
+again and request that the compromise width and height be applied.
+If the widget is not interested in
+<function>XtGeometryAlmost</function>
+replies,
+it can pass NULL for <emphasis remap='I'>width_return</emphasis> and <emphasis remap='I'>height_return</emphasis>.
+</para>
+</sect1>
+
+<sect1 id="Potential_Geometry_Changes">
+<title>Potential Geometry Changes</title>
+<para>
+Sometimes a geometry manager cannot respond to
+a geometry request from a child without first making a geometry request
+to the widget's own parent (the original requestor's grandparent).
+If the request to the grandparent would allow the parent to satisfy the
+original request,
+the geometry manager can make the intermediate geometry request
+as if it were the originator.
+On the other hand,
+if the geometry manager already has determined that the original request
+cannot be completely satisfied (for example, if it always denies
+position changes),
+it needs to tell the grandparent to respond to the intermediate request
+without actually changing the geometry
+because it does not know if the child will accept the compromise.
+To accomplish this, the geometry manager uses
+<function>XtCWQueryOnly</function>
+in the intermediate request.
+</para>
+
+<para>
+When
+<function>XtCWQueryOnly</function>
+is used, the geometry manager needs to cache
+enough information to exactly reconstruct the intermediate request.
+If the grandparent's response to the intermediate query was
+<function>XtGeometryAlmost</function>,
+the geometry manager needs to cache the entire
+reply geometry in the event the child accepts the parent's compromise.
+</para>
+
+<para>
+If the grandparent's response was
+<function>XtGeometryAlmost</function>,
+it may also be necessary to cache the entire reply geometry from
+the grandparent when
+<function>XtCWQueryOnly</function>
+is not used.
+If the geometry manager is still able to satisfy the original request,
+it may immediately accept the grandparent's compromise
+and then act on the child's request.
+If the grandparent's compromise geometry is insufficient to allow
+the child's request and if the geometry manager is willing to offer
+a different compromise to the child,
+the grandparent's compromise should not be accepted until the child
+has accepted the new compromise.
+</para>
+
+<para>
+Note that a compromise geometry returned with
+<function>XtGeometryAlmost</function>
+is guaranteed only for the next call to the same widget;
+therefore, a cache of size 1 is sufficient.
+</para>
+</sect1>
+
+<sect1 id="Child_Geometry_Management_The_geometry_manager_Procedure">
+<title>Child Geometry Management: The geometry_manager Procedure</title>
+<para>
+The geometry_manager procedure pointer in a composite widget class is of type
+<xref linkend='XtGeometryHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGeometryHandler'>
+<funcprototype>
+<funcdef>typedef XtGeometryResult *<function>XtGeometryHandler</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>request</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>geometry_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the widget making the request.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the new geometry the child desires.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>geometry_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes a geometry structure in which the geometry manager may store a
+compromise.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+A class can inherit its superclass's geometry manager during class
+initialization.
+</para>
+
+<para>
+A bit set to zero in the request's <emphasis remap='I'>request_mode</emphasis>
+field means that the child widget
+does not care about the value of the corresponding field,
+so the geometry manager can change this field as it wishes.
+A bit set to 1 means that the child wants that geometry element set
+to the value in the corresponding field.
+</para>
+
+<para>
+If the geometry manager can satisfy all changes requested
+and if
+<function>XtCWQueryOnly</function>
+is not specified,
+it updates the widget's <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>,
+and <emphasis remap='I'>border_width</emphasis> fields
+appropriately.
+Then, it returns
+<function>XtGeometryYes</function>,
+and the values pointed to by the <emphasis remap='I'>geometry_return</emphasis> argument are undefined.
+The widget's window is moved and resized automatically by
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>.
+</para>
+
+<para>
+Homogeneous composite widgets often find it convenient to treat the widget
+making the request the same as any other widget, including reconfiguring
+it using
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>
+or
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>
+as part of its layout process, unless
+<function>XtCWQueryOnly</function>
+is specified.
+If it does this,
+it should return
+<function>XtGeometryDone</function>
+to inform
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+that it does not need to do the configuration itself.
+</para>
+
+<note>
+<para>
+To remain
+compatible with layout techniques used in older widgets (before
+<function>XtGeometryDone</function>
+was added to the Intrinsics), a geometry manager should avoid using
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>
+or
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>
+on the child making
+the request because the layout process of the child may be in an
+intermediate state in which it is not prepared to handle a call to its
+resize procedure. A self-contained widget set may choose this
+alternative geometry management scheme, however, provided that it
+clearly warns widget developers of the compatibility consequences.
+</para>
+</note>
+
+<para>
+Although
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+resizes the widget's window
+(if the geometry
+manager returns
+<function>XtGeometryYes</function>),
+it does not call the widget class's resize procedure.
+The requesting widget must perform whatever
+resizing calculations are needed explicitly.
+</para>
+
+<para>
+If the geometry manager disallows the request,
+the widget cannot change its geometry.
+The values pointed to by <emphasis remap='I'>geometry_return</emphasis> are undefined,
+and the geometry manager returns
+<function>XtGeometryNo</function>.
+</para>
+
+<para>
+Sometimes the geometry manager cannot satisfy the request exactly
+but may be able to satisfy a similar request.
+That is,
+it could satisfy only a subset of the requests (for example,
+size but not position) or a lesser request
+(for example, it cannot make the child as big as the
+request but it can make the child bigger than its current size).
+In such cases,
+the geometry manager fills in the structure pointed to by
+<emphasis remap='I'>geometry_return</emphasis> with the actual changes
+it is willing to make, including an appropriate <emphasis remap='I'>request_mode</emphasis> mask, and returns
+<function>XtGeometryAlmost</function>.
+If a bit in <emphasis remap='I'>geometry_return->request_mode</emphasis> is zero,
+the geometry manager agrees not to change the corresponding value
+if <emphasis remap='I'>geometry_return</emphasis> is used immediately
+in a new request.
+If a bit is 1,
+the geometry manager does change that element to the corresponding
+value in <emphasis remap='I'>geometry_return</emphasis>.
+More bits may be set in <emphasis remap='I'>geometry_return->request_mode</emphasis>
+than in the original request if
+the geometry manager intends to change other fields should the
+child accept the compromise.
+</para>
+
+<para>
+When
+<function>XtGeometryAlmost</function>
+is returned,
+the widget must decide if the compromise suggested in <emphasis remap='I'>geometry_return</emphasis>
+is acceptable.
+If it is, the widget must not change its geometry directly;
+rather, it must make another call to
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>.
+</para>
+
+<para>
+If the next geometry request from this child uses the
+<emphasis remap='I'>geometry_return</emphasis> values filled in by the geometry manager with an
+<function>XtGeometryAlmost</function>
+return and if there have been no intervening geometry requests on
+either its parent or any of its other children,
+the geometry manager must grant the request, if possible.
+That is, if the child asks immediately with the returned geometry,
+it should get an answer of
+<function>XtGeometryYes</function>.
+However,
+dynamic behavior in
+the user's window manager may affect the final outcome.
+</para>
+
+<para>
+To return
+<function>XtGeometryYes</function>,
+the geometry manager frequently rearranges the position of other managed
+children by calling
+<xref linkend='XtMoveWidget' xrefstyle='select: title'/>.
+However, a few geometry managers may sometimes change the
+size of other managed children by calling
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>
+or
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>.
+If
+<function>XtCWQueryOnly</function>
+is specified,
+the geometry manager must return data describing
+how it would react to this geometry
+request without actually moving or resizing any widgets.
+</para>
+
+<para>
+Geometry managers must not assume that the <emphasis remap='I'>request</emphasis>
+and <emphasis remap='I'>geometry_return</emphasis> arguments point to independent storage.
+The caller is permitted to use the same field for both,
+and the geometry manager must allocate its own temporary storage,
+if necessary.
+</para>
+</sect1>
+
+<sect1 id="Widget_Placement_and_Sizing">
+<title>Widget Placement and Sizing</title>
+<para>
+To move a sibling widget of the child making the geometry request,
+the parent uses
+<xref linkend='XtMoveWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtMoveWidget'>
+<funcprototype>
+<funcdef>void <function>XtMoveWidget</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Position <parameter>x</parameter></paramdef>
+ <paramdef>Position <parameter>y</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the new widget x and y coordinates.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtMoveWidget' xrefstyle='select: title'/>
+function returns immediately if the specified geometry fields
+are the same as the old values.
+Otherwise,
+<xref linkend='XtMoveWidget' xrefstyle='select: title'/>
+writes the new <emphasis remap='I'>x</emphasis> and <emphasis remap='I'>y</emphasis> values into the object
+and, if the object is a widget and is realized, issues an Xlib
+<function>XMoveWindow</function>
+call on the widget's window.
+</para>
+
+<para>
+To resize a sibling widget of the child making the geometry request,
+the parent uses
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtResizeWidget'>
+<funcprototype>
+<funcdef>void <function>XtResizeWidget</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Dimension <parameter>width</parameter></paramdef>
+ <paramdef>Dimension <parameter>height</parameter></paramdef>
+ <paramdef>Dimension <parameter>border_width</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>border_width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the new widget size.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>
+function returns immediately if the specified geometry fields
+are the same as the old values.
+Otherwise,
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>
+writes the new <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>, and <emphasis remap='I'>border_width</emphasis> values into
+the object and, if the object is a widget and is realized, issues an
+<function>XConfigureWindow</function>
+call on the widget's window.
+</para>
+
+<para>
+If the new width or height is different from the old values,
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>
+calls the object's resize procedure to notify it of the size change.
+</para>
+
+<para>
+To move and resize the sibling widget of the child making the geometry request,
+the parent uses
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtConfigureWidget'>
+<funcprototype>
+<funcdef>void <function>XtConfigureWidget</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Position <parameter>x</parameter></paramdef>
+ <paramdef>Position <parameter>y</parameter></paramdef>
+ <paramdef>Dimension <parameter>width</parameter></paramdef>
+ <paramdef>Dimension <parameter>height</parameter></paramdef>
+ <paramdef>Dimension <parameter>border_width</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the new widget x and y coordinates.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>width</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>height</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>border_width</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the new widget size.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>
+function returns immediately if the specified new geometry fields
+are all equal to the current values.
+Otherwise,
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>
+writes the new <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>,
+and <emphasis remap='I'>border_width</emphasis> values
+into the object and, if the object is a widget and is realized, makes an Xlib
+<function>XConfigureWindow</function>
+call on the widget's window.
+</para>
+
+<para>
+If the new width or height is different from its old value,
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>
+calls the object's resize procedure to notify it of the size change;
+otherwise, it simply returns.
+</para>
+
+<para>
+To resize a child widget that already has the new values of its width,
+height, and border width, the parent uses
+<xref linkend='XtResizeWindow' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtResizeWindow'>
+<funcprototype>
+<funcdef>void <function>XtResizeWindow</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtResizeWindow' xrefstyle='select: title'/>
+function calls the
+<function>XConfigureWindow</function>
+Xlib function to make the window of the specified widget match its width,
+height, and border width.
+This request is done unconditionally because there is no
+inexpensive way to tell if these
+values match the current values.
+Note that the widget's resize procedure is not called.
+</para>
+
+<para>
+There are very few times to use
+<xref linkend='XtResizeWindow' xrefstyle='select: title'/>;
+instead, the parent should use
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>.
+</para>
+</sect1>
+
+<sect1 id="Preferred_Geometry">
+<title>Preferred Geometry</title>
+<para>
+Some parents may be willing to adjust their layouts to accommodate the
+preferred geometries of their children.
+They can use
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+to obtain the preferred geometry
+and, as they see fit, can use or ignore any portion of the response.
+</para>
+
+<para>
+To query a child widget's preferred geometry, use
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtQueryGeometry'>
+<funcprototype>
+<funcdef>XtGeometryResult <function>XtQueryGeometry</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>intended</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>preferred_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>intended</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new geometry the parent plans to give to the child, or
+NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>preferred_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the child widget's preferred geometry.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+To discover a child's preferred geometry,
+the child's parent stores the new
+geometry in the corresponding fields of
+the intended structure, sets the corresponding bits in <emphasis remap='I'>intended.request_mode</emphasis>,
+and calls
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>.
+The parent should set only those fields that are important to it so
+that the child can determine whether it may be able to attempt changes to
+other fields.
+</para>
+
+<para>
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+clears all bits in the <emphasis remap='I'>preferred_return->request_mode</emphasis>
+field and checks the
+<emphasis remap='I'>query_geometry</emphasis> field of the specified widget's class record.
+If <emphasis remap='I'>query_geometry</emphasis> is not NULL,
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+calls the query_geometry procedure and passes as arguments the
+specified widget, <emphasis remap='I'>intended</emphasis>, and <emphasis remap='I'>preferred_return</emphasis> structures.
+If the <emphasis remap='I'>intended</emphasis> argument is NULL,
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+replaces it with a pointer to an
+<function>XtWidgetGeometry</function>
+structure with <emphasis remap='I'>request_mode</emphasis> equal to zero before calling the
+query_geometry procedure.
+</para>
+
+<note>
+<para>
+If
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+is called from within a geometry_manager
+procedure for the widget that issued
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+or
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>,
+the results
+are not guaranteed to be consistent with the requested changes. The
+change request passed to the geometry manager takes precedence over
+the preferred geometry.
+</para>
+</note>
+
+<para>
+The query_geometry procedure pointer is of type
+<xref linkend='XtGeometryHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='_XtGeometryHandler'>
+<funcprototype>
+<funcdef>typedef XtGeometryResult <function>(*XtGeometryHandler)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>request</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>preferred_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the child widget whose preferred geometry is required.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the geometry changes that the parent plans to make.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>preferred_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes a structure in which the child returns its preferred geometry.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The query_geometry procedure is expected to examine the bits set in
+<emphasis remap='I'>request->request_mode</emphasis>, evaluate the preferred geometry of the widget,
+and store the result in <emphasis remap='I'>preferred_return</emphasis>
+(setting the bits in <emphasis remap='I'>preferred_return->request_mode</emphasis> corresponding
+to those geometry fields that it cares about).
+If the proposed geometry change is acceptable without modification,
+the query_geometry procedure should return
+<function>XtGeometryYes</function>.
+If at least one field in <emphasis remap='I'>preferred_return</emphasis>
+with a bit set in <emphasis remap='I'>preferred_return->request_mode</emphasis>
+is different
+from the corresponding field in <emphasis remap='I'>request</emphasis>
+or if a bit was set in <emphasis remap='I'>preferred_return->request_mode</emphasis>
+that was not set in the request,
+the query_geometry procedure should return
+<function>XtGeometryAlmost</function>.
+If the preferred geometry is identical to the current geometry,
+the query_geometry procedure should return
+<function>XtGeometryNo</function>.
+</para>
+
+<note><para>
+The query_geometry procedure may assume
+that no
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>
+or
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+is in progress
+for the specified widget; that is, it is not required to construct
+a reply consistent with the requested geometry if such a request
+were actually outstanding.
+</para></note>
+
+<para>
+After calling the query_geometry procedure
+or if the <emphasis remap='I'>query_geometry</emphasis> field is NULL,
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+examines all the unset bits in <emphasis remap='I'>preferred_return->request_mode</emphasis>
+and sets the corresponding fields in <emphasis remap='I'>preferred_return</emphasis>
+to the current values from the widget instance.
+If
+<function>CWStackMode</function>
+is not set,
+the <emphasis remap='I'>stack_mode</emphasis> field is set to
+<function>XtSMDontChange</function>.
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+returns the value returned by the query_geometry procedure or
+<function>XtGeometryYes</function>
+if the <emphasis remap='I'>query_geometry</emphasis> field is NULL.
+</para>
+
+<para>
+Therefore, the caller can interpret a return of
+<function>XtGeometryYes</function>
+as not needing to evaluate the contents of the reply and, more important,
+not needing to modify its layout plans.
+A return of
+<function>XtGeometryAlmost</function>
+means either that both the parent and the child expressed interest
+in at least one common field and the child's preference does not match
+the parent's intentions or that the child expressed interest in a field that
+the parent might need to consider.
+A return value of
+<function>XtGeometryNo</function>
+means that both the parent and the child expressed interest in a field and
+that the child suggests that the field's current value in the widget instance
+is its preferred value.
+In addition, whether or not the caller ignores the return value or the
+reply mask, it is guaranteed that the <emphasis remap='I'>preferred_return</emphasis> structure contains complete
+geometry information for the child.
+</para>
+
+<para>
+Parents are expected to call
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+in their layout routine and wherever else the information is significant
+after change_managed has been called.
+The first time it is invoked,
+the changed_managed procedure may assume that the child's current geometry
+is its preferred geometry.
+Thus, the child is still responsible for storing values
+into its own geometry during its initialize procedure.
+</para>
+</sect1>
+
+<sect1 id="Size_Change_Management_The_resize_Procedure">
+<title>Size Change Management: The resize Procedure</title>
+<para>
+A child can be resized by its parent at any time.
+Widgets usually need to know when they have changed size
+so that they can lay out their displayed data again to match the new size.
+When a parent resizes a child, it calls
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>,
+which updates the geometry fields in the widget,
+configures the window if the widget is realized,
+and calls the child's resize procedure to notify the child.
+The resize procedure pointer is of type
+<xref linkend='XtWidgetProc' xrefstyle='select: title'/>.
+</para>
+
+<para>
+If a class need not recalculate anything when a widget is resized,
+it can specify NULL for the <emphasis remap='I'>resize</emphasis> field in its class record.
+This is an unusual case and should occur only for widgets
+with very trivial display semantics.
+The resize procedure takes a widget as its only argument.
+The <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>,
+and <emphasis remap='I'>border_width</emphasis> fields of the widget contain the new values.
+The resize procedure should recalculate the layout of internal data
+as needed.
+(For example, a centered Label in a window that changes size
+should recalculate the starting position of the text.)
+The widget must obey resize as a command and must not treat it as a request.
+A widget must not issue an
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+or
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>
+call from its resize procedure.
+</para>
+</sect1>
+</chapter>
Index: create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH07.xml
===================================================================
--- create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH07.xml (nonexistent)
+++ create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH07.xml (revision 5)
@@ -0,0 +1,5001 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<chapter id='Event_Management'>
+<title>Event Management</title>
+<para>
+While Xlib allows the reading and processing of events anywhere in an application,
+widgets in the X Toolkit neither directly read events
+nor grab the server or pointer.
+Widgets register procedures that are to be called
+when an event or class of events occurs in that widget.
+</para>
+
+<para>
+A typical application consists of startup code followed by an event loop
+that reads events and dispatches them by calling
+the procedures that widgets have registered.
+The default event loop provided by the Intrinsics is
+<xref linkend='XtAppMainLoop' xrefstyle='select: title'/>.
+</para>
+
+<para>
+The event manager is a collection of functions to perform the following tasks:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Add or remove event sources other than X server events (in particular,
+timer interrupts, file input, or POSIX signals).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Query the status of event sources.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Add or remove procedures to be called when an event occurs for a particular
+widget.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Enable and
+disable the dispatching of user-initiated events (keyboard and pointer events)
+for a particular widget.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Constrain the dispatching of events to a cascade of pop-up widgets.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Register procedures to be called when specific events arrive.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Register procedures to be called when the Intrinsics will block.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Enable safe operation in a multi-threaded environment.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+Most widgets do not need to call any of the event handler functions explicitly.
+The normal interface to X events is through the higher-level
+translation manager,
+which maps sequences of X events, with modifiers, into procedure calls.
+Applications rarely use any of the event manager routines besides
+<xref linkend='XtAppMainLoop' xrefstyle='select: title'/>.
+</para>
+<sect1 id="Adding_and_Deleting_Additional_Event_Sources">
+<title>Adding and Deleting Additional Event Sources</title>
+<para>
+While most applications are driven only by X events,
+some applications need to incorporate other sources of input
+into the Intrinsics event-handling mechanism.
+The event manager provides routines to integrate notification of timer events
+and file data pending into this mechanism.
+</para>
+
+<para>
+The next section describes functions that provide input gathering from files.
+The application registers the files with the Intrinsics read routine.
+When input is pending on one of the files,
+the registered callback procedures are invoked.
+</para>
+<sect2 id="Adding_and_Removing_Input_Sources">
+<title>Adding and Removing Input Sources</title>
+<para>
+To register a new file as an input source for a given application context, use
+<xref linkend='XtAppAddInput' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppAddInput'>
+<funcprototype>
+<funcdef>XtInputId <function>XtAppAddInput</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>int <parameter>source</parameter></paramdef>
+ <paramdef>XtPointer <parameter>condition</parameter></paramdef>
+ <paramdef>XtInputCallbackProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source file descriptor on a POSIX-based system
+or other operating-system-dependent device specification.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>condition</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the mask that indicates a read, write, or exception condition
+or some other operating-system-dependent condition.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called when the condition is found.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an argument passed to the specified procedure
+when it is called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppAddInput' xrefstyle='select: title'/>
+function registers with the Intrinsics read routine a new source of events,
+which is usually file input but can also be file output.
+Note that <emphasis remap='I'>file</emphasis> should be loosely interpreted to mean any sink
+or source of data.
+<xref linkend='XtAppAddInput' xrefstyle='select: title'/>
+also specifies the conditions under which the source can generate events.
+When an event is pending on this source,
+the callback procedure is called.
+</para>
+
+<para>
+The legal values for the <emphasis remap='I'>condition</emphasis> argument are operating-system-dependent.
+On a POSIX-based system,
+<emphasis remap='I'>source</emphasis> is a file number and the condition is some union of the following:
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis role='strong'>XtInputReadMask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies that <emphasis remap='I'>proc</emphasis> is to be called when <emphasis remap='I'>source</emphasis> has data to be read.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis role='strong'>XtInputWriteMask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies that <emphasis remap='I'>proc</emphasis> is to be called when <emphasis remap='I'>source</emphasis> is ready
+for writing.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis role='strong'>XtInputExceptMask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies that <emphasis remap='I'>proc</emphasis> is to be called when <emphasis remap='I'>source</emphasis> has
+exception data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+
+<para>
+Callback procedure pointers used to handle file events are of
+type
+<xref linkend='XtInputCallbackProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtInputCallbackProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtInputCallbackProc)</function></funcdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>int *<parameter>source</parameter></paramdef>
+ <paramdef>XtInputId *<parameter>id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the client data argument that was registered for this procedure in
+<function>XtAppAddInput</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the source file descriptor generating the event.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the id returned from the corresponding
+<xref linkend='XtAppAddInput' xrefstyle='select: title'/>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+See <xref linkend='Using_the_Intrinsics_in_a_Multi_Threaded_Environment' />
+for information regarding the use of
+<xref linkend='XtAppAddInput' xrefstyle='select: title'/>
+in multiple threads.
+</para>
+
+<para>
+To discontinue a source of input, use
+<xref linkend='XtRemoveInput' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveInput'>
+<funcprototype>
+<funcdef>void <function>XtRemoveInput</function></funcdef>
+ <paramdef>XtInputId <parameter>id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the id returned from the corresponding
+<xref linkend='XtAppAddInput' xrefstyle='select: title'/>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRemoveInput' xrefstyle='select: title'/>
+function causes the Intrinsics read routine to stop watching for events
+from the file source specified by <emphasis remap='I'>id</emphasis>.
+</para>
+
+<para>
+See <xref linkend='Using_the_Intrinsics_in_a_Multi_Threaded_Environment' />
+for information regarding the use of
+<xref linkend='XtRemoveInput' xrefstyle='select: title'/>
+in multiple threads.
+</para>
+</sect2>
+
+<sect2 id="Adding_and_Removing_Blocking_Notifications">
+<title>Adding and Removing Blocking Notifications</title>
+<para>
+Occasionally it is desirable for an application to receive notification
+when the Intrinsics event manager detects no pending input from file sources
+and no pending input from X server event sources and is about to block
+in an operating system call.
+</para>
+
+<para>
+To register a hook that is called immediately prior to event blocking, use
+<xref linkend='XtAppAddBlockHook' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppAddBlockHook'>
+<funcprototype>
+<funcdef>XtBlockHookId <function>XtAppAddBlockHook</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtBlockHookProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called before blocking.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an argument passed to the specified procedure when it is called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppAddBlockHook' xrefstyle='select: title'/>
+function registers the specified procedure and returns an identifier for it.
+The hook procedure <emphasis remap='I'>proc</emphasis> is called at any time in the future when
+the Intrinsics are about to block pending some input.
+</para>
+
+<para>
+The procedure pointers used to provide notification of event blocking
+are of type
+<xref linkend='XtBlockHookProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtBlockHookProc'>
+<funcprototype>
+<funcdef>typedef void *<function>XtBlockHookProc</function></funcdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the client data argument that was registered for this procedure in
+<function>XtAppAddBlockHook</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+To discontinue the use of a procedure for blocking notification, use
+<xref linkend='XtRemoveBlockHook' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveBlockHook'>
+<funcprototype>
+<funcdef>void <function>XtRemoveBlockHook</function></funcdef>
+ <paramdef>XtBlockHookId <parameter>id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the identifier returned from the corresponding call to
+<xref linkend='XtAppAddBlockHook' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRemoveBlockHook' xrefstyle='select: title'/>
+function removes the specified procedure from the list of procedures
+that are called by the Intrinsics read routine before blocking on event sources.
+</para>
+</sect2>
+
+<sect2 id="Adding_and_Removing_Timeouts">
+<title>Adding and Removing Timeouts</title>
+<para>
+The timeout facility notifies the application or the widget
+through a callback procedure that a specified time interval has elapsed.
+Timeout values are uniquely identified by an interval id.
+</para>
+
+<para>
+To register a timeout callback, use
+<xref linkend='XtAppAddTimeOut' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppAddTimeOut'>
+<funcprototype>
+<funcdef>XtIntervalId <function>XtAppAddTimeOut</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>unsigned long <parameter>interval</parameter></paramdef>
+ <paramdef>XtTimerCallbackProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context for which the timer is to be set.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>interval</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time interval in milliseconds.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called when the time expires.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an argument passed to the specified procedure
+when it is called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppAddTimeOut' xrefstyle='select: title'/>
+function creates a timeout and returns an identifier for it.
+The timeout value is set to <emphasis remap='I'>interval</emphasis>.
+The callback procedure <emphasis remap='I'>proc</emphasis> is called when
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>
+or
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>
+is next called after the time interval elapses,
+and then the timeout is removed.
+</para>
+
+<para>
+Callback procedure pointers used with timeouts are of
+type
+<xref linkend='XtTimerCallbackProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtTimerCallbackProc'>
+<funcprototype>
+<funcdef>typedef void *<function>XtTimerCallbackProc</function></funcdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtIntervalId *<parameter>timer</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the client data argument that was registered for this procedure in
+<function>XtAppAddTimeOut</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>timer</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the id returned from the corresponding
+<xref linkend='XtAppAddTimeOut' xrefstyle='select: title'/>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+See <xref linkend='Using_the_Intrinsics_in_a_Multi_Threaded_Environment' />
+for information regarding the use of
+<xref linkend='XtAppAddTimeOut' xrefstyle='select: title'/>
+in multiple threads.
+</para>
+
+<para>
+To clear a timeout value, use
+<xref linkend='XtRemoveTimeOut' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveTimeOut'>
+<funcprototype>
+<funcdef>void <function>XtRemoveTimeOut</function></funcdef>
+ <paramdef>XtIntervalId <parameter>timer</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>timer</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the id for the timeout request to be cleared.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRemoveTimeOut' xrefstyle='select: title'/>
+function removes the pending timeout.
+Note that timeouts are automatically removed once they trigger.
+</para>
+
+<para>
+Please refer to Section 7.12 for information regarding the use of
+<xref linkend='XtRemoveTimeOut' xrefstyle='select: title'/>
+in multiple threads.
+</para>
+</sect2>
+
+<sect2 id="Adding_and_Removing_Signal_Callbacks">
+<title>Adding and Removing Signal Callbacks</title>
+<para>
+The signal facility notifies the application or the widget through a
+callback procedure that a signal or other external asynchronous event
+has occurred. The registered callback procedures are uniquely identified
+by a signal id.
+</para>
+
+<para>
+Prior to establishing a signal handler, the application or widget should
+call
+<xref linkend='XtAppAddSignal' xrefstyle='select: title'/>
+and store the resulting identifier in a place accessible to the signal
+handler. When a signal arrives, the signal handler should call
+<xref linkend='XtNoticeSignal' xrefstyle='select: title'/>
+to notify the Intrinsics that a signal has occurred. To register a signal
+callback use
+<xref linkend='XtAppAddSignal' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppAddSignal'>
+<funcprototype>
+<funcdef>XtSignalId <function>XtAppAddSignal</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtSignalCallbackProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called when the signal is noticed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an argument passed to the specified procedure when it is called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The callback procedure pointers used to handle signal events are of type
+<xref linkend='XtSignalCallbackProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSignalCallbackProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtSignalCallbackProc)</function></funcdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtSignalId *<parameter>id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the client data argument that was registered for this procedure in
+<xref linkend='XtAppAddSignal' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the id returned from the corresponding
+<xref linkend='XtAppAddSignal' xrefstyle='select: title'/>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+To notify the Intrinsics that a signal has occurred, use
+<xref linkend='XtNoticeSignal' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtNoticeSignal'>
+<funcprototype>
+<funcdef>void <function>XtNoticeSignal</function></funcdef>
+ <paramdef>XtSignalId <parameter>id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the id returned from the corresponding
+<xref linkend='XtAppAddSignal' xrefstyle='select: title'/>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+On a POSIX-based system,
+<xref linkend='XtNoticeSignal' xrefstyle='select: title'/>
+is the only Intrinsics function that can safely be called from a signal handler.
+If
+<xref linkend='XtNoticeSignal' xrefstyle='select: title'/>
+is invoked multiple times before the Intrinsics are able to invoke the
+registered callback, the callback is only called once.
+Logically, the Intrinsics maintain “pending” flag for each registered callback.
+This flag is initially
+<function>False</function>
+and is set to
+<function>True</function>
+by
+<xref linkend='XtNoticeSignal' xrefstyle='select: title'/>.
+When
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>
+or
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>
+(with a mask including
+<function>XtIMSignal</function>)
+is called, all registered callbacks with “pending”
+<function>True</function>
+are invoked and the flags are reset to
+<function>False</function>.
+</para>
+
+<para>
+If the signal handler wants to track how many times the signal has been
+raised, it can keep its own private counter. Typically the handler would
+not do any other work; the callback does the actual processing for the
+signal. The Intrinsics never block signals from being raised, so if a given
+signal can be raised multiple times before the Intrinsics can invoke the
+callback for that signal, the callback must be designed to deal with
+this. In another case, a signal might be raised just after the Intrinsics
+sets the pending flag to
+<function>False</function>
+but before the callback can get control, in which case the pending flag
+will still be
+<function>True</function>
+after the callback returns, and the Intrinsics will invoke the callback
+again, even though all of the signal raises have been handled. The
+callback must also be prepared to handle this case.
+</para>
+
+<para>
+To remove a registered signal callback, call
+<xref linkend='XtRemoveSignal' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveSignal'>
+<funcprototype>
+<funcdef>void <function>XtRemoveSignal</function></funcdef>
+ <paramdef>XtSignalId <parameter>id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the id returned by the corresponding call to
+<xref linkend='XtAppAddSignal' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The client should typically disable the source of the signal before calling
+<xref linkend='XtRemoveSignal' xrefstyle='select: title'/>.
+If the signal could have been raised again before the source was disabled
+and the client wants to process it, then after disabling the source but
+before calling
+<xref linkend='XtRemoveSignal' xrefstyle='select: title'/>
+the client can test for signals with
+<xref linkend='XtAppPending' xrefstyle='select: title'/>
+and process them by calling
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>
+with the mask
+<function>XtIMSignal</function>.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Constraining_Events_to_a_Cascade_of_Widgets">
+<title>Constraining Events to a Cascade of Widgets</title>
+<para>
+Modal widgets are widgets that, except for the input directed to them,
+lock out user input to the application.
+</para>
+
+<para>
+When a modal menu or modal dialog box is popped up using
+<xref linkend='XtPopup' xrefstyle='select: title'/>,
+user events (keyboard and pointer events) that occur outside the modal
+widget should be delivered to the modal widget or ignored.
+In no case will user events be delivered to a widget outside
+the modal widget.
+</para>
+
+<para>
+Menus can pop up submenus, and dialog boxes can pop up further dialog
+boxes to create a pop-up cascade.
+In this case,
+user events may be delivered to one of several modal widgets in the cascade.
+</para>
+
+<para>
+Display-related events should be delivered outside the modal cascade so that
+exposure events and the like keep the application's display up-to-date.
+Any event that occurs within the cascade is delivered as usual.
+The user events delivered to the most recent spring-loaded shell
+in the cascade when they occur outside the cascade are called remap events
+and are
+<function>KeyPress</function>,
+<function>KeyRelease</function>,
+<function>ButtonPress</function>,
+and
+<function>ButtonRelease</function>.
+The user events ignored when they occur outside the cascade are
+<function>MotionNotify</function>
+and
+<function>EnterNotify</function>.
+All other events are delivered normally.
+In particular, note that this is one
+way in which widgets can receive
+<function>LeaveNotify</function>
+events without first receiving
+<function>EnterNotify</function>
+events; they should be prepared to deal with
+this, typically by ignoring any unmatched
+<function>LeaveNotify</function>
+events.
+</para>
+
+<para>
+<xref linkend='XtPopup' xrefstyle='select: title'/>
+uses the
+<xref linkend='XtAddGrab' xrefstyle='select: title'/>
+and
+<xref linkend='XtRemoveGrab' xrefstyle='select: title'/>
+functions to constrain user events to a modal cascade
+and subsequently to remove a grab when the modal widget is popped down.
+</para>
+
+<para>
+To constrain or redirect user input to a modal widget, use
+<xref linkend='XtAddGrab' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAddGrab'>
+<funcprototype>
+<funcdef>void <function>XtAddGrab</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Boolean <parameter>exclusive</parameter></paramdef>
+ <paramdef>Boolean <parameter>spring_loaded</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget to add to the modal cascade. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>exclusive</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether user events should be dispatched exclusively to this widget
+or also to previous widgets in the cascade.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>spring_loaded</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether this widget was popped up because the user pressed
+a pointer button.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAddGrab' xrefstyle='select: title'/>
+function appends the widget to the modal cascade
+and checks that <emphasis remap='I'>exclusive</emphasis> is
+<function>True</function>
+if <emphasis remap='I'>spring_loaded</emphasis> is
+<function>True</function>.
+If this condition is not met,
+<xref linkend='XtAddGrab' xrefstyle='select: title'/>
+generates a warning message.
+</para>
+
+<para>
+The modal cascade is used by
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+when it tries to dispatch a user event.
+When at least one modal widget is in the widget cascade,
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+first determines if the event should be delivered.
+It starts at the most recent cascade entry and follows the cascade up to and
+including the most recent cascade entry added with the <emphasis remap='I'>exclusive</emphasis> parameter
+<function>True</function>.
+</para>
+
+<para>
+This subset of the modal cascade along with all descendants of these widgets
+comprise the active subset.
+User events that occur outside the widgets in this subset are ignored
+or remapped.
+Modal menus with submenus generally add a submenu widget to the cascade
+with <emphasis remap='I'>exclusive</emphasis>
+<function>False</function>.
+Modal dialog boxes that need to restrict user input to the most deeply nested
+dialog box add a subdialog widget to the cascade with <emphasis remap='I'>exclusive</emphasis>
+<function>True</function>.
+User events that occur within the active subset are delivered to the
+appropriate widget, which is usually a child or further descendant of the modal
+widget.
+</para>
+
+<para>
+Regardless of where in the application they occur,
+remap events are always delivered to the most recent widget in the active
+subset of the cascade registered with <emphasis remap='I'>spring_loaded</emphasis>
+<function>True</function>,
+if any such widget exists.
+If the event
+occurred in the active subset of the cascade but outside the
+spring-loaded widget, it is delivered normally before being
+delivered also to the spring-loaded widget.
+Regardless of where it is dispatched, the Intrinsics do not modify
+the contents of the event.
+</para>
+
+<para>
+To remove the redirection of user input to a modal widget, use
+<xref linkend='XtRemoveGrab' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveGrab'>
+<funcprototype>
+<funcdef>void <function>XtRemoveGrab</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget to remove from the modal cascade.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRemoveGrab' xrefstyle='select: title'/>
+function removes widgets from the modal cascade starting
+at the most recent widget up to and including the specified widget.
+It issues a warning if the specified widget is not on the modal cascade.
+</para>
+<sect2 id="Requesting_Key_and_Button_Grabs">
+<title>Requesting Key and Button Grabs</title>
+<para>
+The Intrinsics provide a set of key and button grab interfaces that
+are parallel to those provided by Xlib and that allow the Intrinsics
+to modify event dispatching when necessary. X Toolkit applications and
+widgets that need to passively grab keys or buttons or actively grab
+the keyboard or pointer should use the
+following Intrinsics routines rather than the corresponding Xlib
+routines.
+</para>
+
+<para>
+To passively grab a single key of the keyboard, use
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGrabKey'>
+<funcprototype>
+<funcdef>void <function>XtGrabKey</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>KeyCode <parameter>keycode</parameter></paramdef>
+ <paramdef>Modifiers <parameter>modifiers</parameter></paramdef>
+ <paramdef>Boolean <parameter>owner_events</parameter></paramdef>
+ <paramdef>int <parameter>pointer_mode</parameter></paramdef>
+ <paramdef>int <parameter>keyboard_mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget in whose window the key is to be grabbed. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify arguments to
+<function>XGrabKey</function>;
+see Section 12.2
+in Xlib — C Language X Interface.
+
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+calls
+<function>XGrabKey</function>
+specifying the widget's window as the grab
+window if the widget is realized. The remaining arguments are exactly
+as for
+<function>XGrabKey</function>.
+If the widget is not realized, or is later unrealized, the call to
+<function>XGrabKey</function>
+is performed (again) when
+the widget is realized and its window becomes mapped. In the future,
+if
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+is called with a
+<function>KeyPress</function>
+event matching the specified keycode and modifiers (which may be
+<function>AnyKey</function>
+or
+<function>AnyModifier</function>,
+respectively) for the
+widget's window, the Intrinsics will call
+<xref linkend='XtUngrabKeyboard' xrefstyle='select: title'/>
+with the timestamp from the
+<function>KeyPress</function>
+event if either of the following conditions is true:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+There is a modal cascade and the widget is not in
+the active subset of the cascade and the keyboard was not previously
+grabbed, or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XFilterEvent</function>
+returns
+<function>True</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+To cancel a passive key grab, use
+<xref linkend='XtUngrabKey' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtUngrabKey'>
+<funcprototype>
+<funcdef>void <function>XtUngrabKey</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>KeyCode <parameter>keycode</parameter></paramdef>
+ <paramdef>Modifiers <parameter>modifiers</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget in whose window the key was grabbed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify arguments to
+<function>XUngrabKey</function>;
+see Section 12.2
+in Xlib — C Language X Interface.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtUngrabKey' xrefstyle='select: title'/>
+procedure calls
+<function>XUngrabKey</function>
+specifying the widget's
+window as the ungrab window if the widget is realized. The remaining
+arguments are exactly as for
+<function>XUngrabKey</function>.
+If the widget is not realized,
+<xref linkend='XtUngrabKey' xrefstyle='select: title'/>
+removes a deferred
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+request, if any, for the specified widget, keycode, and modifiers.
+</para>
+
+<para>
+To actively grab the keyboard, use
+<xref linkend='XtGrabKeyboard' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGrabKeyboard'>
+<funcprototype>
+<funcdef>int <function>XtGrabKeyboard</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>Boolean <parameter>owner_events</parameter></paramdef>
+ <paramdef>int <parameter>pointer_mode</parameter></paramdef>
+ <paramdef>int <parameter>keyboard_mode</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for whose window the keyboard is to be grabbed.
+Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify arguments to
+<function>XGrabKeyboard</function>;
+see Section 12.2
+in Xlib — C Language X Interface.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If the specified widget is realized,
+<xref linkend='XtGrabKeyboard' xrefstyle='select: title'/>
+calls
+<function>XGrabKeyboard</function>
+specifying the widget's window as the grab window. The remaining
+arguments and return value are exactly as for
+<function>XGrabKeyboard</function>.
+If the widget is not realized,
+<xref linkend='XtGrabKeyboard' xrefstyle='select: title'/>
+immediately returns
+<function>GrabNotViewable</function>.
+No future automatic ungrab is implied by
+<xref linkend='XtGrabKeyboard' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To cancel an active keyboard grab, use
+<xref linkend='XtUngrabKeyboard' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtUngrabKeyboard'>
+<funcprototype>
+<funcdef>void <function>XtUngrabKeyboard</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that has the active keyboard grab.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional argument to
+<function>XUngrabKeyboard</function>;
+see Section 12.2
+in Xlib — C Language X Interface.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtUngrabKeyboard' xrefstyle='select: title'/>
+calls
+<function>XUngrabKeyboard</function>
+with the specified time.
+</para>
+
+<para>
+To passively grab a single pointer button, use
+<xref linkend='XtGrabButton' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGrabButton'>
+<funcprototype>
+<funcdef>void <function>XtGrabButton</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>int <parameter>button</parameter></paramdef>
+ <paramdef>Modifiers <parameter>modifiers</parameter></paramdef>
+ <paramdef>Boolean <parameter>owner_events</parameter></paramdef>
+ <paramdef>unsigned int <parameter>event_mask</parameter></paramdef>
+ <paramdef>int <parameter>pointer_mode</parameter></paramdef>
+ <paramdef>int <parameter>keyboard_mode</parameter></paramdef>
+ <paramdef>Window <parameter>confine_to</parameter></paramdef>
+ <paramdef>Cursor <parameter>cursor</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget in whose window the button is to be grabbed. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>button</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>confine_to</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>cursor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify arguments to
+<function>XGrabButton</function>;
+see Section 12.1
+in Xlib — C Language X Interface.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGrabButton' xrefstyle='select: title'/>
+calls
+<function>XGrabButton</function>
+specifying the widget's window as the
+grab window if the widget is realized. The remaining arguments are
+exactly as for
+<function>XGrabButton</function>.
+If the widget is not realized, or is later unrealized, the call to
+<function>XGrabButton</function>
+is performed (again)
+when the widget is realized and its window becomes mapped. In the
+future, if
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+is called with a
+<function>ButtonPress</function>
+event matching the specified button and modifiers (which may be
+<function>AnyButton</function>
+or
+<function>AnyModifier</function>,
+respectively)
+for the widget's window, the Intrinsics will call
+<xref linkend='XtUngrabPointer' xrefstyle='select: title'/>
+with the timestamp from the
+<function>ButtonPress</function>
+event if either of the following conditions is true:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+There is a modal cascade and the
+widget is not in the active subset of the cascade and the pointer was
+not previously grabbed, or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<function>XFilterEvent</function>
+returns
+<function>True</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+To cancel a passive button grab, use
+<xref linkend='XtUngrabButton' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtUngrabButton'>
+<funcprototype>
+<funcdef>void <function>XtUngrabButton</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>unsigned int <parameter>button</parameter></paramdef>
+ <paramdef>Modifiers <parameter>modifiers</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget in whose window the button was grabbed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>button</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify arguments to
+<function>XUngrabButton</function>;
+see Section 12.1
+in Xlib — C Language X Interface.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtUngrabButton' xrefstyle='select: title'/>
+procedure calls
+<function>XUngrabButton</function>
+specifying the
+widget's window as the ungrab window if the widget is realized. The
+remaining arguments are exactly as for
+<function>XUngrabButton</function>.
+If the widget is not realized,
+<xref linkend='XtUngrabButton' xrefstyle='select: title'/>
+removes a deferred
+<xref linkend='XtGrabButton' xrefstyle='select: title'/>
+request, if any, for the specified widget, button, and modifiers.
+</para>
+
+<para>
+To actively grab the pointer, use
+<xref linkend='XtGrabPointer' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGrabPointer'>
+<funcprototype>
+<funcdef>int <function>XtGrabPointer</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>Boolean <parameter>owner_events</parameter></paramdef>
+ <paramdef>unsigned int <parameter>event_mask</parameter></paramdef>
+ <paramdef>int <parameter>pointer_mode</parameter></paramdef>
+ <paramdef>int <parameter>keyboard_mode</parameter></paramdef>
+ <paramdef>Window <parameter>confine_to</parameter></paramdef>
+ <paramdef>Cursor <parameter>cursor</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for whose window the pointer is to be grabbed. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>confine_to</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>cursor</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify arguments to
+<function>XGrabPointer</function>;
+see Section 12.1
+in Xlib — C Language X Interface.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If the specified widget is realized,
+<xref linkend='XtGrabPointer' xrefstyle='select: title'/>
+calls
+<function>XGrabPointer</function>,
+specifying the widget's window as the grab window. The remaining
+arguments and return value are exactly as for
+<function>XGrabPointer</function>.
+If the widget is not realized,
+<xref linkend='XtGrabPointer' xrefstyle='select: title'/>
+immediately returns
+<function>GrabNotViewable</function>.
+No future automatic ungrab is implied by
+<xref linkend='XtGrabPointer' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To cancel an active pointer grab, use
+<xref linkend='XtUngrabPointer' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtUngrabPointer'>
+<funcprototype>
+<funcdef>void <function>XtUngrabPointer</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that has the active pointer grab.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the time argument to
+<function>XUngrabPointer</function>;
+see Section 12.1
+in Xlib — C Language X Interface.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtUngrabPointer' xrefstyle='select: title'/>
+calls
+<function>XUngrabPointer</function>
+with the specified time.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Focusing_Events_on_a_Child">
+<title>Focusing Events on a Child</title>
+<para>
+To redirect keyboard input to a normal descendant of a
+widget without calling
+<function>XSetInputFocus</function>,
+use
+<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetKeyboardFocus'>
+<funcprototype>
+<funcdef>void <function>XtSetKeyboardFocus</function></funcdef>
+ <paramdef>Widget <parameter>subtree</parameter></paramdef>
+ <paramdef>Widget <parameter>descendent</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>subtree</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the subtree of the hierarchy for which the keyboard focus is
+to be set. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>descendant</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies either the normal (non-pop-up) descendant of <emphasis remap='I'>subtree</emphasis> to which
+keyboard events are logically directed, or
+<function>None</function>.
+It is not an error to specify
+<function>None</function>
+when no input focus was previously set. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>
+causes
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+to remap keyboard events occurring within the specified subtree
+and dispatch them to the specified descendant widget or to an ancestor.
+If the descendant's class is not a subclass of Core, the descendant is
+replaced by its closest windowed ancestor.
+</para>
+
+<para>
+When there is no modal cascade, keyboard events can be dispatched
+to a widget in one of five ways. Assume the server delivered the
+event to the window for widget E (because of X input focus, key or
+keyboard grabs, or pointer position).
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If neither E nor any of E's ancestors have redirected the keyboard
+focus, or if the event activated a grab for E as specified by a call
+to
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+with any value of <emphasis remap='I'>owner_events</emphasis>, or
+if the keyboard is actively grabbed by E with <emphasis remap='I'>owner_events</emphasis>
+<function>False</function>
+via
+<xref linkend='XtGrabKeyboard' xrefstyle='select: title'/>
+or
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+on a previous key press, the event is dispatched to E.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Beginning with the ancestor of E closest to the root that has
+redirected the keyboard focus or E if no such ancestor exists, if
+the target of that focus redirection has in turn redirected the
+keyboard focus, recursively follow this focus chain to find a widget
+F that has not redirected focus.
+ </para>
+ </listitem>
+ <listitem>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If E is the final focus target widget F or a descendant of F, the
+event is dispatched to E.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If E is not F, an ancestor of F, or a descendant of F, and the event
+activated a grab for E as specified by a call to
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+for E,
+<xref linkend='XtUngrabKeyboard' xrefstyle='select: title'/>
+is called.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If E is an ancestor of F, and the event is a key press, and either
+ </para>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+E has grabbed the key with
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+and <emphasis remap='I'>owner_events</emphasis>
+<function>False</function>,
+or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+E has grabbed the key with
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+and <emphasis remap='I'>owner_events</emphasis>
+<function>True</function>,
+and the coordinates of the event are outside the rectangle specified
+by E's geometry,
+then the event is dispatched to E.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+Otherwise, define A as the closest common ancestor of E and F:
+ </para>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+If there is an active keyboard grab for any widget via either
+<xref linkend='XtGrabKeyboard' xrefstyle='select: title'/>
+or
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+on a previous key press, or
+if no widget between F and A (noninclusive) has grabbed
+the key and modifier combination with
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+and any value of <emphasis remap='I'>owner_events</emphasis>, the event is dispatched to F.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Else, the event is dispatched to the ancestor of F closest to A
+that has grabbed the key and modifier combination with
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+</itemizedlist>
+<para>
+When there is a modal cascade, if the final destination widget as
+identified above is in the active subset of the cascade, the event is
+dispatched; otherwise the event is remapped to a spring-loaded shell
+or discarded.
+Regardless of where it is dispatched, the Intrinsics do not modify
+the contents of the event.
+</para>
+
+<para>
+When <emphasis remap='I'>subtree</emphasis> or one of its descendants acquires the X input focus
+or the pointer moves into the subtree such that keyboard events would
+now be delivered to the subtree, a
+<function>FocusIn</function>
+event is generated for the descendant if
+<function>FocusChange</function>
+events have been selected by the descendant.
+Similarly, when <emphasis remap='I'>subtree</emphasis> loses the X input focus
+or the keyboard focus for one of its ancestors, a
+<function>FocusOut</function>
+event is generated for descendant if
+<function>FocusChange</function>
+events have been selected by the descendant.
+</para>
+
+<para>
+A widget tree may also actively manage the X server input focus. To
+do so, a widget class specifies an accept_focus procedure.
+</para>
+
+<para>
+The accept_focus procedure pointer is of type
+<xref linkend='XtAcceptFocusProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAcceptFocusProc'>
+<funcprototype>
+<funcdef>typedef Boolean *<function>XtAcceptFocusProc</function></funcdef>
+
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Time *<parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the X time of the event causing the accept focus.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Widgets that need the input focus can call
+<function>XSetInputFocus</function>
+explicitly, pursuant to the restrictions of the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
+To allow outside agents, such as the parent,
+to cause a widget to take the input focus,
+every widget exports an accept_focus procedure.
+The widget returns a value indicating
+whether it actually took the focus or not,
+so that the parent can give the focus to another widget.
+Widgets that need to know when they lose the input focus must use
+the Xlib focus notification mechanism explicitly
+(typically by specifying translations for
+<function>FocusIn</function>
+and
+<function>FocusOut</function>
+events).
+Widgets classes that never want the input focus should set the
+<emphasis remap='I'>accept_focus</emphasis> field to NULL.
+</para>
+
+<para>
+To call a widget's accept_focus procedure, use
+<xref linkend='XtCallAcceptFocus' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCallAcceptFocus'>
+<funcprototype>
+<funcdef>Boolean <function>XtCallAcceptFocus</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Time *<parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the X time of the event that is causing the focus change.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtCallAcceptFocus' xrefstyle='select: title'/>
+function calls the specified widget's accept_focus procedure,
+passing it the specified widget and time, and returns what the accept_focus
+procedure returns.
+If <emphasis remap='I'>accept_focus</emphasis> is NULL,
+<xref linkend='XtCallAcceptFocus' xrefstyle='select: title'/>
+returns
+<function>False</function>.
+</para>
+<sect2 id="Events_for_Drawables_That_Are_Not_a_Widget_s_Window">
+<title>Events for Drawables That Are Not a Widget's Window</title>
+<para>
+Sometimes an application must handle events for drawables that are not
+associated with widgets in its widget tree. Examples include handling
+<function>GraphicsExpose</function>
+and
+<function>NoExpose</function>
+events on Pixmaps, and handling
+<function>PropertyNotify</function>
+events on the root window.
+</para>
+
+<para>
+To register a drawable with the Intrinsics event dispatching, use
+<xref linkend='XtRegisterDrawable' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRegisterDrawable'>
+<funcprototype>
+<funcdef>void <function>XtRegisterDrawable</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Drawable <parameter>drawable</parameter></paramdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable's display.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>drawable</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable to register.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget to register the drawable for.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtRegisterDrawable' xrefstyle='select: title'/>
+associates the specified drawable with the specified widget
+so that future calls to
+<xref linkend='XtWindowToWidget' xrefstyle='select: title'/>
+with the drawable will return the widget.
+The default event dispatcher will dispatch future events that
+arrive for the drawable to the widget in the same manner as
+events that contain the widget's window.
+</para>
+
+<para>
+If the drawable is already registered with another widget, or if the
+drawable is the window of a widget in the client's widget tree, the
+results of calling
+<xref linkend='XtRegisterDrawable' xrefstyle='select: title'/>
+are undefined.
+</para>
+
+<para>
+To unregister a drawable with the Intrinsics event dispatching, use
+<xref linkend='XtUnregisterDrawable' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtUnregisterDrawable'>
+<funcprototype>
+<funcdef>void <function>XtUnregisterDrawable</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Drawable <parameter>drawable</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable's display.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>drawable</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable to unregister.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtUnregisterDrawable' xrefstyle='select: title'/>
+removes an association created with
+<xref linkend='XtRegisterDrawable' xrefstyle='select: title'/>.
+If the drawable is the window of a widget in the client's widget tree
+the results of calling
+<xref linkend='XtUnregisterDrawable' xrefstyle='select: title'/>
+are undefined.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Querying_Event_Sources">
+<title>Querying Event Sources</title>
+<para>
+The event manager provides several functions to examine and read events
+(including file and timer events) that are in the queue.
+The next three functions are Intrinsics equivalents of the
+<function>XPending</function>,
+<function>XPeekEvent</function>,
+and
+<function>XNextEvent</function>
+Xlib calls.
+</para>
+
+<para>
+To determine if there are any events on the input queue for a given application,
+use
+<xref linkend='XtAppPending' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppPending'>
+<funcprototype>
+<funcdef>XtInputMask <function>XtAppPending</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the application to check.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppPending' xrefstyle='select: title'/>
+function returns a nonzero value if there are
+events pending from the X server, timer pending, other input sources
+pending, or signal sources pending. The
+value returned is a bit mask that is the OR of
+<function>XtIMXEvent</function>,
+<function>XtIMTimer</function>,
+<function>XtIMAlternateInput</function>,
+and
+<function>XtIMSignal</function>
+(see
+<function>XtAppProcessEvent ).</function>
+If there are no events pending,
+<xref linkend='XtAppPending' xrefstyle='select: title'/>
+flushes the output buffers of each Display in the application context
+and returns zero.
+</para>
+
+<para>
+To return the event from the head of a given application's input queue
+without removing input from the queue, use
+<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppPeekEvent'>
+<funcprototype>
+<funcdef>Boolean <function>XtAppPeekEvent</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XEvent *<parameter>event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the event information to the specified event structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If there is an X event in the queue,
+<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>
+copies it into <emphasis remap='I'>event_return</emphasis> and returns
+<function>True</function>.
+If no X input is on the queue,
+<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>
+flushes the output buffers of each Display in the application context
+and blocks until some input is available
+(possibly calling some timeout callbacks in the interim).
+If the next available input is an X event,
+<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>
+fills in <emphasis remap='I'>event_return</emphasis> and returns
+<function>True</function>.
+Otherwise, the input is for an input source
+registered with
+<xref linkend='XtAppAddInput' xrefstyle='select: title'/>,
+and
+<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>
+returns
+<function>False</function>.
+The sample implementations provides XtAppPeekEvent as described. Timeout callbacks
+are called while blocking for input. If some input for an input source is
+available,
+<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>
+will return
+<function>True</function>
+without returning an event.
+</para>
+
+<para>
+To remove and return the event
+from the head of a given application's X event queue,
+use
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppNextEvent'>
+<funcprototype>
+<funcdef>void <function>XtAppNextEvent</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XEvent *<parameter>event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the event information to the specified event structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If the X event queue is empty,
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>
+flushes the X output buffers of each Display in the application context
+and waits for an X event while looking at the other input sources
+and timeout values and calling any callback procedures triggered by them.
+This wait time can be used for background processing;
+see <xref linkend='Adding_Background_Work_Procedures' />.
+</para>
+</sect1>
+
+<sect1 id="Dispatching_Events">
+<title>Dispatching Events</title>
+<para>
+The Intrinsics provide functions that dispatch events
+to widgets or other application code.
+Every client interested in X events on a widget uses
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+to register which events it is
+interested in and a procedure (event handler) to be called
+when the event happens in that window.
+The translation manager automatically registers event handlers for widgets
+that use translation tables; see <xref linkend='Translation_Management' />.
+</para>
+
+<para>
+Applications that need direct control of the processing of different types
+of input should use
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppProcessEvent'>
+<funcprototype>
+<funcdef>void <function>XtAppProcessEvent</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtInputMask <parameter>mask</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the
+application for which to process input.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies what types of events to process.
+The mask is the bitwise inclusive OR of any combination of
+<function>XtIMXEvent</function>,
+<function>XtIMTimer</function>,
+<function>XtIMAlternateInput</function>,
+and
+<function>XtIMSignal</function>.
+As a convenience,
+<filename class="headerfile">Intrinsic.h</filename>
+defines the symbolic name
+<function>XtIMAll</function>
+to be the bitwise inclusive OR of these four event types.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>
+function processes one timer, input source, signal source, or X event.
+If there is no event or input of the appropriate type to process, then
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>
+blocks until there is.
+If there is more than one type of input available to process,
+it is undefined which will get processed.
+Usually, this procedure is not called by client applications; see
+<xref linkend='XtAppMainLoop' xrefstyle='select: title'/>.
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>
+processes timer events by calling any appropriate timer callbacks,
+input sources by calling any appropriate input callbacks,
+signal source by calling any appropriate signal callbacks,
+and X events by
+calling
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>.
+</para>
+
+<para>
+When an X event is received,
+it is passed to
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>,
+which calls the appropriate event handlers
+and passes them the widget, the event, and client-specific data
+registered with each procedure.
+If no handlers for that event are registered,
+the event is ignored and the dispatcher simply returns.
+</para>
+
+<para>
+To dispatch an event returned by
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>,
+retrieved directly from the Xlib queue, or synthetically constructed,
+to any registered event filters or event handlers, call
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtDispatchEvent'>
+<funcprototype>
+<funcdef>Boolean <function>XtDispatchEvent</function></funcdef>
+ <paramdef>XEvent *<parameter>event</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the event structure to be dispatched
+to the appropriate event handlers.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+function first calls
+<function>XFilterEvent</function>
+with the <emphasis remap='I'>event</emphasis> and the window of the widget to which the
+Intrinsics intend to dispatch the event, or the event window if
+the Intrinsics would not dispatch the event to any handlers.
+If
+<function>XFilterEvent</function>
+returns
+<function>True</function>
+and the event activated a server grab as identified
+by a previous call to
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+or
+<xref linkend='XtGrabButton' xrefstyle='select: title'/>,
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+calls
+<xref linkend='XtUngrabKeyboard' xrefstyle='select: title'/>
+or
+<xref linkend='XtUngrabPointer' xrefstyle='select: title'/>
+with the timestamp from the event and immediately returns
+<function>True</function>.
+If
+<function>XFilterEvent</function>
+returns
+<function>True</function>
+and a grab was not activated,
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+just immediately returns
+<function>True</function>.
+Otherwise,
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+sends the event to the event handler functions that
+have been previously registered with the dispatch routine.
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+returns
+<function>True</function>
+if
+<function>XFilterEvent</function>
+returned
+<function>True</function>,
+or if the event was dispatched to some handler, and
+<function>False</function>
+if it found no handler to which to dispatch the event.
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+records the last timestamp in any event that
+contains a timestamp (see
+<function>XtLastTimestampProcessed</function>),
+regardless of whether it was filtered or dispatched.
+If a modal cascade is active with <emphasis remap='I'>spring_loaded</emphasis>
+<function>True</function>,
+and if the event is a remap event as defined by
+<xref linkend='XtAddGrab' xrefstyle='select: title'/>,
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+may dispatch the event a second time. If it does so,
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+will call
+<function>XFilterEvent</function>
+again with the window of the spring-loaded widget prior to the second
+dispatch, and if
+<function>XFilterEvent</function>
+returns
+<function>True</function>,
+the second dispatch will not be performed.
+</para>
+</sect1>
+
+<sect1 id="The_Application_Input_Loop">
+<title>The Application Input Loop</title>
+<para>
+To process all input from a given application in a continuous loop,
+use the convenience procedure
+<xref linkend='XtAppMainLoop' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppMainLoop'>
+<funcprototype>
+<funcdef>void <function>XtAppMainLoop</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the application.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The <xref linkend='XtAppMainLoop' xrefstyle='select: title'/>
+function processes events using
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>,
+varying the <emphasis remap='I'>mask parameter</emphasis>
+and using <xref linkend='XtAppPending' xrefstyle='select: title'/>
+to ensure that it has a chance to handle events of all types,
+i.e., X events, timer events, input events and signal sources.
+This constitutes the main loop of X Toolkit applications.
+There is nothing special about
+<xref linkend='XtAppMainLoop' xrefstyle='select: title'/>;
+it simply processes events in a conditional loop.
+At the bottom of the loop, it checks to see if the specified
+application context's destroy flag is set.
+If the flag is set, the loop breaks.
+The whole loop is enclosed between a matching
+<xref linkend='XtAppLock' xrefstyle='select: title'/>
+and
+<xref linkend='XtAppUnlock' xrefstyle='select: title'/>.
+</para>
+
+<para>
+Applications can provide their own version of this loop,
+which tests some global termination flag or tests that the number
+of top-level widgets is larger than zero before
+circling back for the next event.
+</para>
+
+<para>
+The design of
+<xref linkend='XtAppMainLoop' xrefstyle='select: title'/>
+has changed since Release 6.
+Originally it looped over calls to
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>,
+and
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>,
+but because the latter returns only after an X event
+(not for timers, signals, inputs),
+it was modified to allow any type of event to break out of the loop.
+</para>
+</sect1>
+
+<sect1 id="Setting_and_Checking_the_Sensitivity_State_of_a_Widget">
+<title>Setting and Checking the Sensitivity State of a Widget</title>
+<para>
+Many widgets have a mode in which they assume a different appearance
+(for example, are grayed out or stippled), do not respond to user events,
+and become dormant.
+</para>
+
+<para>
+When dormant,
+a widget is considered to be insensitive.
+If a widget is insensitive,
+the event manager does not dispatch any events to the widget
+with an event type of
+<function>KeyPress</function>,
+<function>KeyRelease</function>,
+<function>ButtonPress</function>,
+<function>ButtonRelease</function>,
+<function>MotionNotify</function>,
+<function>EnterNotify</function>,
+<function>LeaveNotify</function>,
+<function>FocusIn</function>,
+or
+<function>FocusOut</function>.
+</para>
+
+<para>
+A widget can be insensitive because its <emphasis remap='I'>sensitive</emphasis> field is
+<function>False</function>
+or because one of its ancestors is insensitive and thus the widget's
+<emphasis remap='I'>ancestor_sensitive</emphasis> field also is
+<function>False</function>.
+A widget can but does not need to distinguish these two cases visually.
+</para>
+
+<note>
+<para>
+Pop-up shells will have
+<emphasis remap='I'>ancestor_sensitive</emphasis>
+<function>False</function>
+if the parent was insensitive when the shell
+was created. Since
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>
+on the parent will not
+modify the resource of the pop-up child, clients are advised to include
+a resource specification of the form
+“*TransientShell.ancestorSensitive: True”
+in the application defaults resource file or to
+otherwise ensure that the parent is
+sensitive when creating pop-up shells.
+</para>
+</note>
+
+<para>
+To set the sensitivity state of a widget, use
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetSensitive'>
+<funcprototype>
+<funcdef>void <function>XtSetSensitive</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Boolean <parameter>sensitive</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>sensitive</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether the widget should receive
+keyboard, pointer, and focus events.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>
+function first calls
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+on the current widget with an argument list specifying the
+XtNsensitive resource and the new value.
+If <emphasis remap='I'>sensitive</emphasis> is
+<function>False</function>
+and the widget's class is a subclass of
+Composite,
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>
+recursively propagates the new value
+down the child tree by calling
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+on each child to set <emphasis remap='I'>ancestor_sensitive</emphasis> to
+<function>False</function>.
+If <emphasis remap='I'>sensitive</emphasis> is
+<function>True</function>
+and the widget's class is a subclass of
+Composite
+and the widget's <emphasis remap='I'>ancestor_sensitive</emphasis> field is
+<function>True</function>,
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>
+sets the <emphasis remap='I'>ancestor_sensitive</emphasis> of each child to
+<function>True</function>
+and then recursively calls
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+on each normal descendant that is now sensitive to set
+<emphasis remap='I'>ancestor_sensitive</emphasis> to
+<function>True</function>.
+</para>
+
+<para>
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>
+calls
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+to change the <emphasis remap='I'>sensitive</emphasis> and <emphasis remap='I'>ancestor_sensitive</emphasis> fields
+of each affected widget.
+Therefore, when one of these changes,
+the widget's set_values procedure should
+take whatever display actions are needed
+(for example, graying out or stippling the widget).
+</para>
+
+<para>
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>
+maintains the invariant that, if the parent has either <emphasis remap='I'>sensitive</emphasis>
+or <emphasis remap='I'>ancestor_sensitive</emphasis>
+<function>False</function>,
+then all children have <emphasis remap='I'>ancestor_sensitive</emphasis>
+<function>False</function>.
+</para>
+
+<para>
+To check the current sensitivity state of a widget,
+use
+<xref linkend='XtIsSensitive' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtIsSensitive'>
+<funcprototype>
+<funcdef>Boolean <function>XtIsSensitive</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtIsSensitive' xrefstyle='select: title'/>
+function returns
+<function>True</function>
+or
+<function>False</function>
+to indicate whether user input events are being dispatched.
+If object's class is a subclass of RectObj and
+both <emphasis remap='I'>sensitive</emphasis> and <emphasis remap='I'>ancestor_sensitive</emphasis> are
+<function>True</function>,
+<xref linkend='XtIsSensitive' xrefstyle='select: title'/>
+returns
+<function>True</function>;
+otherwise, it returns
+<function>False</function>.
+</para>
+</sect1>
+
+<sect1 id="Adding_Background_Work_Procedures">
+<title>Adding Background Work Procedures</title>
+<para>
+The Intrinsics have some limited support for background processing.
+Because most applications spend most of their time waiting for input,
+you can register an idle-time work procedure
+that is called when the toolkit would otherwise block in
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>
+or
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>.
+Work procedure pointers are of type
+<xref linkend='XtWorkProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtWorkProc'>
+<funcprototype>
+<funcdef>typedef Boolean <function>(*XtWorkProc)</function></funcdef>
+
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the client data specified when the work procedure was registered.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure should return
+<function>True</function>
+when it is done to indicate that it
+should be removed.
+If the procedure returns
+<function>False</function>,
+it will remain registered and called again when the
+application is next idle.
+Work procedures should be very judicious about how much they do.
+If they run for more than a small part of a second,
+interactive feel is likely to suffer.
+</para>
+
+<para>
+To register a work procedure for a given application, use
+<xref linkend='XtAppAddWorkProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppAddWorkProc'>
+<funcprototype>
+<funcdef>XtWorkProcId <function>XtAppAddWorkProc</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtWorkProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that identifies the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called when the application is idle.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument passed to the specified procedure
+when it is called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppAddWorkProc' xrefstyle='select: title'/>
+function adds the specified work procedure for the application identified
+by <emphasis remap='I'>app_context</emphasis>
+and returns an opaque unique identifier for this work procedure.
+Multiple work procedures can be registered,
+and the most recently added one is always the one that is called.
+However, if a work procedure adds another work procedure,
+the newly added one has lower priority than the current one.
+</para>
+
+<para>
+To remove a work procedure, either return
+<function>True</function>
+from the procedure when it is called or use
+<xref linkend='XtRemoveWorkProc' xrefstyle='select: title'/>
+outside of the procedure.
+</para>
+
+<funcsynopsis id='XtRemoveWorkProc'>
+<funcprototype>
+<funcdef>void <function>XtRemoveWorkProc</function></funcdef>
+ <paramdef>XtWorkProcId <parameter>id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which work procedure to remove.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRemoveWorkProc' xrefstyle='select: title'/>
+function explicitly removes the specified background work procedure.
+</para>
+</sect1>
+
+<sect1 id="X_Event_Filters">
+<title>X Event Filters</title>
+<para>
+The event manager provides filters that can be applied to
+specific X events.
+The filters, which screen out events that are redundant or are temporarily
+unwanted, handle
+pointer motion compression,
+enter/leave compression, and
+exposure compression.
+</para>
+<sect2 id="Pointer_Motion_Compression">
+<title>Pointer Motion Compression</title>
+<para>
+Widgets can have a hard time keeping up with a rapid stream of
+pointer motion events. Furthermore,
+they usually do not care about every motion event. To throw out
+redundant motion events, the widget class field <emphasis remap='I'>compress_motion</emphasis> should be
+<function>True</function>.
+When a request for an event would return a motion event,
+the Intrinsics check if there are any other motion events
+for the same widget immediately
+following the current one and, if so, skip all but the last of them.
+</para>
+</sect2>
+
+<sect2 id="Enter_Leave_Compression">
+<title>Enter/Leave Compression</title>
+<para>
+To throw out pairs of enter and leave events that have no intervening events,
+as can happen when the user moves the pointer across a widget
+without stopping in it,
+the widget class field <emphasis remap='I'>compress_enterleave</emphasis> should be
+<function>True</function>.
+These enter and leave events are not delivered to the client
+if they are found together in the input queue.
+</para>
+</sect2>
+
+<sect2 id="Exposure_Compression">
+<title>Exposure Compression</title>
+<para>
+Many widgets prefer to process a series of exposure events as a
+single expose region rather than as individual rectangles. Widgets
+with complex displays might use the expose region as a clip list
+in a graphics context, and widgets with simple displays might
+ignore the region entirely and redisplay their whole window or
+might get the bounding box from the region and redisplay only that
+rectangle.
+</para>
+
+<para>
+In either case, these widgets do not care about getting partial exposure events.
+The <emphasis remap='I'>compress_exposure</emphasis> field in the widget class
+structure specifies the type and number of exposure events that are
+dispatched to the widget's expose procedure. This field must be
+initialized to one of the following values:
+</para>
+
+<programlisting>
+#define XtExposeNoCompress ((XtEnum)False)
+#define XtExposeCompressSeries ((XtEnum)True)
+#define XtExposeCompressMultiple <implementation-defined>
+#define XtExposeCompressMaximal <implementation-defined>
+</programlisting>
+
+<para>
+optionally ORed with any combination of the following flags (all with
+implementation-defined values):
+<function>XtExposeGraphicsExpose</function>,
+<function>XtExposeGraphicsExposeMerged</function>,
+<function>XtExposeNoExpose</function>,
+and
+<function>XtExposeNoRegion</function>.
+</para>
+
+<para>
+If the <emphasis remap='I'>compress_exposure</emphasis> field in the widget class structure does not
+specify
+<function>XtExposeNoCompress</function>,
+the event manager calls the widget's expose procedure only
+once for a series of exposure events.
+In this case, all
+<function>Expose</function>
+or
+<function>GraphicsExpose</function>
+events are accumulated into a region.
+When the final event is received,
+the event manager replaces the rectangle in the event with the
+bounding box for the region
+and calls the widget's expose procedure,
+passing the modified exposure event and (unless
+<function>XtExposeNoRegion</function>
+is specified) the region.
+For more information on regions, see
+Section 16.5 in
+Xlib — C Language X Interface.
+</para>
+
+<para>
+The values have the following interpretation:
+</para>
+
+<para>
+<function>XtExposeNoCompress</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+No exposure compression is performed; every selected event is
+individually dispatched to the expose procedure with a <emphasis remap='I'>region</emphasis>
+argument of NULL.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<function>XtExposeCompressSeries</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Each series of exposure events is coalesced into a single event,
+which is dispatched
+when an exposure event with count equal to zero is reached.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<function>XtExposeCompressMultiple</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Consecutive series of exposure events are coalesced into a single
+event, which is dispatched
+when an exposure event with count equal to zero is reached and either
+the event queue is empty or the next event is not an exposure event
+for the same widget.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<function>XtExposeCompressMaximal</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+All expose series currently in the queue for the widget
+are coalesced into a single
+event without regard to intervening nonexposure events. If a
+partial series is in the end of the queue, the Intrinsics will
+block until the end of the series is received.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The additional flags have the following meaning:
+</para>
+
+<para>
+<function>XtExposeGraphicsExpose</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Specifies that
+<function>GraphicsExpose</function>
+events are also to be dispatched to
+the expose procedure.
+<function>GraphicsExpose</function>
+events are compressed, if specified, in the same manner as
+<function>Expose</function>
+events.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<function>XtExposeGraphicsExposeMerged</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Specifies in the case of
+<function>XtExposeCompressMultiple</function>
+and
+<function>XtExposeCompressMaximal</function>
+that series of
+<function>GraphicsExpose</function>
+and
+<function>Expose</function>
+events are to be compressed together, with the final event type
+determining the type of the event passed to the expose procedure.
+If this flag is not set, then only series of the same event type
+as the event at the head of the queue are coalesced. This flag
+also implies
+<function>XtExposeGraphicsExpose</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<function>XtExposeNoExpose</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Specifies that
+<function>NoExpose</function>
+events are also to be dispatched to the expose procedure.
+<function>NoExpose</function>
+events are never coalesced with
+other exposure events or with each other.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<function>XtExposeNoRegion</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Specifies that the final region argument passed to the expose
+procedure is NULL. The rectangle in the event will still
+contain bounding box information for the entire series of
+compressed exposure events. This option saves processing time when the
+region is not needed by the widget.
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+</sect1>
+
+<sect1 id="Widget_Exposure_and_Visibility">
+<title>Widget Exposure and Visibility</title>
+<para>
+Every primitive widget and some composite widgets display data on the screen
+by means of direct Xlib calls.
+Widgets cannot simply write to the screen and forget what they have done.
+They must keep enough state to redisplay the window or parts
+of it if a portion is obscured and then reexposed.
+</para>
+
+<sect2 id="Redisplay_of_a_Widget_The_expose_Procedure">
+<title>Redisplay of a Widget: The expose Procedure</title>
+<para>
+The expose procedure pointer in a widget class is of type
+<xref linkend='XtExposeProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtExposeProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtExposeProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XEvent *<parameter>event</parameter></paramdef>
+ <paramdef>Region <parameter>region</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget instance requiring redisplay.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the exposure event giving the rectangle requiring redisplay.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>region</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the union of all rectangles in this exposure sequence.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The redisplay of a widget upon exposure is the responsibility of the
+expose procedure in the widget's class record.
+If a widget has no display semantics,
+it can specify NULL for the <emphasis remap='I'>expose</emphasis> field.
+Many composite widgets serve only as containers for their children
+and have no expose procedure.
+</para>
+
+<note>
+<para>
+If the <emphasis remap='I'>expose</emphasis> procedure is NULL,
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+fills in a default bit gravity of
+<function>NorthWestGravity</function>
+before it calls the widget's realize procedure.
+</para>
+</note>
+
+<para>
+If the widget's <emphasis remap='I'>compress_exposure</emphasis> class field specifies
+<function>XtExposeNoCompress</function>
+or
+<function>XtExposeNoRegion</function>,
+or if the event type is
+<function>NoExpose</function>
+(see <xref linkend='Exposure_Compression' />),
+<emphasis remap='I'>region</emphasis> is NULL. If
+<function>XtExposeNoCompress</function>
+is not specified and the event type is not
+<function>NoExpose</function>,
+the event is the final event in the compressed series
+but <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, and <emphasis remap='I'>height</emphasis> contain
+the bounding box for all the compressed events.
+The region is created and destroyed by the Intrinsics, but
+the widget is permitted to modify the region contents.
+</para>
+
+<para>
+A small simple widget (for example, Label) can ignore the bounding box
+information in the event and redisplay the entire window.
+A more complicated widget (for example, Text) can use the bounding box
+information to minimize the amount of calculation and redisplay it does.
+A very complex widget uses the region as a clip list in a GC and
+ignores the event information.
+The expose procedure is not chained and is therefore
+responsible for exposure of all superclass data
+as well as its own.
+</para>
+
+<para>
+However,
+it often is possible to anticipate the display needs of several levels
+of subclassing.
+For example, rather than implement separate display procedures for
+the widgets Label, Pushbutton, and Toggle,
+you could write a single display routine in Label that uses display state
+fields like
+</para>
+<programlisting>
+Boolean invert;
+Boolean highlight;
+Dimension highlight_width;
+</programlisting>
+<para>
+Label would have <emphasis remap='I'>invert</emphasis> and <emphasis remap='I'>highlight</emphasis> always
+<function>False</function>
+and <emphasis remap='I'>highlight_width</emphasis> zero.
+Pushbutton would dynamically set <emphasis remap='I'>highlight</emphasis> and <emphasis remap='I'>highlight_width</emphasis>,
+but it would leave <emphasis remap='I'>invert</emphasis> always
+<function>False</function>.
+Finally, Toggle would dynamically set all three.
+In this case,
+the expose procedures for Pushbutton and Toggle inherit
+their superclass's expose procedure;
+see <xref linkend='Inheritance_of_Superclass_Operations' />.
+</para>
+</sect2>
+
+<sect2 id="Widget_Visibility">
+<title>Widget Visibility</title>
+<para>
+Some widgets may use substantial computing resources to produce the
+data they will display.
+However, this effort is wasted if the widget is not actually visible
+on the screen, that is, if the widget is obscured by another application
+or is iconified.
+</para>
+
+<para>
+The <emphasis remap='I'>visible</emphasis> field in the
+core
+widget structure provides a hint to the widget that it need not compute
+display data.
+This field is guaranteed to be
+<function>True</function>
+by the time an
+exposure
+event is processed if any part of the widget is visible,
+but is
+<function>False</function>
+if the widget is fully obscured.
+</para>
+
+<para>
+Widgets can use or ignore the <emphasis remap='I'>visible</emphasis> hint.
+If they ignore it,
+they should have <emphasis remap='I'>visible_interest</emphasis> in their widget class record set
+<function>False</function>.
+In such cases,
+the <emphasis remap='I'>visible</emphasis> field is initialized
+<function>True</function>
+and never changes.
+If <emphasis remap='I'>visible_interest</emphasis> is
+<function>True</function>,
+the event manager asks for
+<function>VisibilityNotify</function>
+events for the widget and sets <emphasis remap='I'>visible</emphasis> to
+<function>True</function>
+on
+<function>VisibilityUnobscured</function>
+or
+<function>VisibilityPartiallyObscured</function>
+events and
+<function>False</function>
+on
+<function>VisibilityFullyObscured</function>
+events.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="X_Event_Handlers">
+<title>X Event Handlers</title>
+<para>
+Event handlers are procedures called when specified events
+occur in a widget.
+Most widgets need not use event handlers explicitly.
+Instead, they use the Intrinsics translation manager.
+Event handler procedure pointers are of the type
+<xref linkend='XtEventHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtEventHandler'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtEventHandler)</function></funcdef>
+
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XEvent *<parameter>event</parameter></paramdef>
+ <paramdef>Boolean *<parameter>continue_to_dispatch</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which the event arrived.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies any client-specific information registered with the event handler.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the triggering event.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>continue_to_dispatch</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether the remaining event
+handlers registered for the current event
+should be called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+After receiving an event and before calling any event handlers, the
+Boolean pointed to by <emphasis remap='I'>continue_to_dispatch</emphasis> is initialized to
+<function>True</function>.
+When an event handler is called, it may decide that further processing
+of the event is not desirable and may store
+<function>False</function>
+in this Boolean, in
+which case any handlers remaining to be called for the event are
+ignored.
+</para>
+
+<para>
+The circumstances under which the Intrinsics may add event handlers
+to a widget are currently implementation-dependent. Clients must
+therefore be aware that storing
+<function>False</function>
+into the <emphasis remap='I'>continue_to_dispatch</emphasis> argument can lead to portability problems.
+</para>
+<sect2 id="Event_Handlers_That_Select_Events">
+<title>Event Handlers That Select Events</title>
+<para>
+To register an event handler procedure with the dispatch mechanism, use
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAddEventHandler'>
+<funcprototype>
+<funcdef>void <function>XtAddEventHandler</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>EventMask <parameter>event_mask</parameter></paramdef>
+ <paramdef>Boolean <parameter>nonmaskable</parameter></paramdef>
+ <paramdef>XtEventHandler <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask for which to call this procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nonmaskable</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether this procedure should be
+called on the nonmaskable events
+<function>( GraphicsExpose</function>,
+<function>NoExpose</function>,
+<function>SelectionClear</function>,
+<function>SelectionRequest</function>,
+<function>SelectionNotify</function>,
+<function>ClientMessage</function>,
+and
+<function>MappingNotify ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional data to be passed to the event handler.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+function registers a procedure with the dispatch mechanism that is
+to be called when an event that matches the mask occurs on the specified
+widget.
+Each widget has a single registered event handler list, which will
+contain any procedure/client_data pair exactly once regardless of
+the manner in which it is registered.
+If the procedure is already registered with the same <emphasis remap='I'>client_data</emphasis>
+value,
+the specified mask augments the existing mask.
+If the widget is realized,
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+calls
+<function>XSelectInput</function>,
+if necessary.
+The order in which this procedure is called relative to other handlers
+registered for the same event is not defined.
+</para>
+
+<para>
+To remove a previously registered event handler, use
+<xref linkend='XtRemoveEventHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveEventHandler'>
+<funcprototype>
+<funcdef>void <function>XtRemoveEventHandler</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>EventMask <parameter>event_mask</parameter></paramdef>
+ <paramdef>Boolean <parameter>nonmaskable</parameter></paramdef>
+ <paramdef>XtEventHandler <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which this procedure is registered. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask for which to unregister this procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nonmaskable</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether this procedure should be
+removed on the nonmaskable events
+<function>( GraphicsExpose</function>,
+<function>NoExpose</function>,
+<function>SelectionClear</function>,
+<function>SelectionRequest</function>,
+<function>SelectionNotify</function>,
+<function>ClientMessage</function>,
+and
+<function>MappingNotify ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be removed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the registered client data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRemoveEventHandler' xrefstyle='select: title'/>
+function unregisters an event handler registered with
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+or
+<xref linkend='XtInsertEventHandler' xrefstyle='select: title'/>
+for the specified events.
+The request is ignored if <emphasis remap='I'>client_data</emphasis> does not match the value given
+when the handler was registered.
+If the widget is realized and no other event handler requires the event,
+<xref linkend='XtRemoveEventHandler' xrefstyle='select: title'/>
+calls
+<function>XSelectInput</function>.
+If the specified procedure has not been registered
+or if it has been registered with a different value of <emphasis remap='I'>client_data</emphasis>,
+<xref linkend='XtRemoveEventHandler' xrefstyle='select: title'/>
+returns without reporting an error.
+</para>
+
+<para>
+To stop a procedure registered with
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+or
+<xref linkend='XtInsertEventHandler' xrefstyle='select: title'/>
+from receiving all selected events, call
+<xref linkend='XtRemoveEventHandler' xrefstyle='select: title'/>
+with an <emphasis remap='I'>event_mask</emphasis> of
+<function>XtAllEvents</function>
+and <emphasis remap='I'>nonmaskable</emphasis>
+<function>True</function>.
+The procedure will continue to receive any events
+that have been specified in calls to
+<xref linkend='XtAddRawEventHandler' xrefstyle='select: title'/>
+or
+<xref linkend='XtInsertRawEventHandler' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To register an event handler procedure that receives events before or
+after all previously registered event handlers, use
+<xref linkend='XtInsertEventHandler' xrefstyle='select: title'/>.
+</para>
+<programlisting>
+typedef enum {XtListHead, XtListTail} XtListPosition;
+</programlisting>
+
+<funcsynopsis id='XtInsertEventHandler'>
+<funcprototype>
+<funcdef>void <function>XtInsertEventHandler</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>EventMask <parameter>event_mask</parameter></paramdef>
+ <paramdef>Boolean <parameter>nonmaskable</parameter></paramdef>
+ <paramdef>XtEventHandler <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtListPosition <parameter>position</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask for which to call this procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nonmaskable</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether this procedure should be
+called on the nonmaskable events
+<function>( GraphicsExpose</function>,
+<function>NoExpose</function>,
+<function>SelectionClear</function>,
+<function>SelectionRequest</function>,
+<function>SelectionNotify</function>,
+<function>ClientMessage</function>,
+and
+<function>MappingNotify ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional data to be passed to the client's event handler.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>position</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies when the event handler is to be called
+relative to other previously registered handlers.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtInsertEventHandler' xrefstyle='select: title'/>
+is identical to
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+with the additional <emphasis remap='I'>position</emphasis> argument. If <emphasis remap='I'>position</emphasis> is
+<function>XtListHead</function>,
+the event
+handler is registered so that it is called before any event
+handlers that were previously registered for the same widget. If
+<emphasis remap='I'>position</emphasis> is
+<function>XtListTail</function>,
+the event handler is registered to be called
+after any previously registered event handlers. If the procedure is
+already registered with the same <emphasis remap='I'>client_data</emphasis> value, the specified mask
+augments the existing mask and the procedure is repositioned in
+the list.
+</para>
+</sect2>
+
+<sect2 id="Event_Handlers_That_Do_Not_Select_Events">
+<title>Event Handlers That Do Not Select Events</title>
+<para>
+On occasion,
+clients need to register an event handler procedure with the
+dispatch mechanism without explicitly
+causing the X server to select for that event.
+To do this, use
+<xref linkend='XtAddRawEventHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAddRawEventHandler'>
+<funcprototype>
+<funcdef>void <function>XtAddRawEventHandler</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>EventMask <parameter>event_mask</parameter></paramdef>
+ <paramdef>Boolean <parameter>nonmaskable</parameter></paramdef>
+ <paramdef>XtEventHandler <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask for which to call this procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nonmaskable</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether this procedure should be
+called on the nonmaskable events
+<function>( GraphicsExpose</function>,
+<function>NoExpose</function>,
+<function>SelectionClear</function>,
+<function>SelectionRequest</function>,
+<function>SelectionNotify</function>,
+<function>ClientMessage</function>,
+and
+<function>MappingNotify ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional data to be passed to the client's event handler.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAddRawEventHandler' xrefstyle='select: title'/>
+function is similar to
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+except that it does not affect the widget's event mask and never causes an
+<function>XSelectInput</function>
+for its events.
+Note that the widget might already have those mask bits set
+because of other nonraw event handlers registered on it.
+If the procedure is already registered with the same <emphasis remap='I'>client_data</emphasis>,
+the specified mask augments the existing mask.
+The order in which this procedure is called relative to other handlers
+registered for the same event is not defined.
+</para>
+
+<para>
+To remove a previously registered raw event handler, use
+<xref linkend='XtRemoveRawEventHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveRawEventHandler'>
+<funcprototype>
+<funcdef>void <function>XtRemoveRawEventHandler</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>EventMask <parameter>event_mask</parameter></paramdef>
+ <paramdef>Boolean <parameter>nonmaskable</parameter></paramdef>
+ <paramdef>XtEventHandler <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which this procedure is registered. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask for which to unregister this procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nonmaskable</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether this procedure should be
+removed on the nonmaskable events
+<function>( GraphicsExpose</function>,
+<function>NoExpose</function>,
+<function>SelectionClear</function>,
+<function>SelectionRequest</function>,
+<function>SelectionNotify</function>,
+<function>ClientMessage</function>,
+and
+<function>MappingNotify ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be registered.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the registered client data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRemoveRawEventHandler' xrefstyle='select: title'/>
+function unregisters an event handler registered with
+<xref linkend='XtAddRawEventHandler' xrefstyle='select: title'/>
+or
+<xref linkend='XtInsertRawEventHandler' xrefstyle='select: title'/>
+for the specified events without changing
+the window event mask.
+The request is ignored if <emphasis remap='I'>client_data</emphasis> does not match the value given
+when the handler was registered.
+If the specified procedure has not been registered
+or if it has been registered with a different value of <emphasis remap='I'>client_data</emphasis>,
+<xref linkend='XtRemoveRawEventHandler' xrefstyle='select: title'/>
+returns without reporting an error.
+</para>
+
+<para>
+To stop a procedure
+registered with
+<xref linkend='XtAddRawEventHandler' xrefstyle='select: title'/>
+or
+<xref linkend='XtInsertRawEventHandler' xrefstyle='select: title'/>
+from receiving all nonselected events, call
+<xref linkend='XtRemoveRawEventHandler' xrefstyle='select: title'/>
+with an <emphasis remap='I'>event_mask</emphasis> of
+<function>XtAllEvents</function>
+and <emphasis remap='I'>nonmaskable</emphasis>
+<function>True</function>.
+The procedure
+will continue to receive any events that have been specified in calls to
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+or
+<xref linkend='XtInsertEventHandler' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To register an event handler procedure that receives events before or
+after all previously registered event handlers without selecting for
+the events, use
+<xref linkend='XtInsertRawEventHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtInsertRawEventHandler'>
+<funcprototype>
+<funcdef>void <function>XtInsertRawEventHandler</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>EventMask <parameter>event_mask</parameter></paramdef>
+ <paramdef>Boolean <parameter>nonmaskable</parameter></paramdef>
+ <paramdef>XtEventHandler <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtListPosition <parameter>position</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event mask for which to call this procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nonmaskable</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether this procedure should be
+called on the nonmaskable events
+<function>( GraphicsExpose</function>,
+<function>NoExpose</function>,
+<function>SelectionClear</function>,
+<function>SelectionRequest</function>,
+<function>SelectionNotify</function>,
+<function>ClientMessage</function>,
+and
+<function>MappingNotify ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be registered.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional data to be passed to the client's event handler.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>position</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies when the event handler is to be called
+relative to other previously registered handlers.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtInsertRawEventHandler' xrefstyle='select: title'/>
+function is similar to
+<xref linkend='XtInsertEventHandler' xrefstyle='select: title'/>
+except that it does not modify the widget's event
+mask and never causes an
+<function>XSelectInput</function>
+for the specified events. If
+the procedure is already registered with the same <emphasis remap='I'>client_data</emphasis>
+value, the
+specified mask augments the existing mask and the procedure is
+repositioned in the list.
+</para>
+</sect2>
+
+<sect2 id="Current_Event_Mask">
+<title>Current Event Mask</title>
+<para>
+To retrieve the event mask for a given widget, use
+<xref linkend='XtBuildEventMask' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtBuildEventMask'>
+<funcprototype>
+<funcdef>EventMask <function>XtBuildEventMask</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtBuildEventMask' xrefstyle='select: title'/>
+function returns the event mask representing the logical OR
+of all event masks for event handlers registered on the widget with
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>
+and
+<xref linkend='XtInsertEventHandler' xrefstyle='select: title'/>
+and all event translations, including accelerators,
+installed on the widget.
+This is the same event mask stored into the
+<function>XSetWindowAttributes</function>
+structure by
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
+and sent to the server when event handlers and translations are installed or
+removed on the realized widget.
+</para>
+</sect2>
+
+<sect2 id="Event_Handlers_for_X_Protocol_Extensions">
+<title>Event Handlers for X11 Protocol Extensions</title>
+<para>
+To register an event handler procedure with the Intrinsics dispatch
+mechanism according to an event type, use
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtInsertEventTypeHandler'>
+<funcprototype>
+<funcdef>void <function>XtInsertEventTypeHandler</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>int <parameter>event_type</parameter></paramdef>
+ <paramdef>XtPointer <parameter>select_data</parameter></paramdef>
+ <paramdef>XtEventHandler <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtListPosition <parameter>position</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event type for which to call this event handler.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>select_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies data used to request events of the specified type from the server,
+or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event handler to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional data to be passed to the event handler.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>position</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies when the event handler is to be called relative to other
+previously registered handlers.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>
+registers a procedure with the
+dispatch mechanism that is to be called when an event that matches the
+specified <emphasis remap='I'>event_type</emphasis> is dispatched to the specified <emphasis remap='I'>widget</emphasis>.
+</para>
+
+<para>
+If <emphasis remap='I'>event_type</emphasis> specifies one of the core X protocol events, then
+<emphasis remap='I'>select_data</emphasis> must be a pointer to a value of type
+<function>EventMask</function>,
+indicating
+the event mask to be used to select for the desired event. This event
+mask is included in the value returned by
+<xref linkend='XtBuildEventMask' xrefstyle='select: title'/>.
+If the widget is realized,
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>
+calls
+<function>XSelectInput</function>
+if necessary. Specifying NULL for <emphasis remap='I'>select_data</emphasis> is equivalent to
+specifying a pointer to an event mask containing 0. This is similar
+to the
+<xref linkend='XtInsertRawEventHandler' xrefstyle='select: title'/>
+function.
+</para>
+
+<para>
+If <emphasis remap='I'>event_type</emphasis> specifies an extension event type, then the semantics of
+the data pointed to by <emphasis remap='I'>select_data</emphasis> are defined by the extension
+selector registered for the specified event type.
+</para>
+
+<para>
+In either case the Intrinsics are not required to copy the data
+pointed to by <emphasis remap='I'>select_data</emphasis>, so the caller must ensure that it remains
+valid as long as the event handler remains registered with this value
+of <emphasis remap='I'>select_data</emphasis>.
+</para>
+
+<para>
+The <emphasis remap='I'>position</emphasis> argument allows the client to control the order of
+invocation of event handlers registered for the same event type. If
+the client does not care about the order, it should normally specify
+<function>XtListTail</function>,
+which registers this event handler after any previously
+registered handlers for this event type.
+</para>
+
+<para>
+Each widget has a single registered event handler list, which will
+contain any procedure/client_data pair exactly once if it is
+registered with
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>,
+regardless of the manner
+in which it is registered and regardless of the value(s)
+of <emphasis remap='I'>select_data</emphasis>. If the procedure is already registered with the
+same <emphasis remap='I'>client_data</emphasis> value, the specified mask augments the existing
+mask and the procedure is repositioned in the list.
+</para>
+
+<para>
+To remove an event handler registered with
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>,
+use
+<xref linkend='XtRemoveEventTypeHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveEventTypeHandler'>
+<funcprototype>
+<funcdef>void <function>XtRemoveEventTypeHandler</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>int <parameter>event_type</parameter></paramdef>
+ <paramdef>XtPointer <parameter>select_data</parameter></paramdef>
+ <paramdef>XtEventHandler <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget for which the event handler was registered. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event type for which the handler was registered.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>select_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies data used to deselect events of the specified type
+from the server, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event handler to be removed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data with which the procedure was registered.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRemoveEventTypeHandler' xrefstyle='select: title'/>
+function unregisters an event handler
+registered with
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>
+for the specified event type.
+The request is ignored if <emphasis remap='I'>client_data</emphasis> does not match the value given
+when the handler was registered.
+</para>
+
+<para>
+If <emphasis remap='I'>event_type</emphasis> specifies one of the core X protocol events,
+<emphasis remap='I'>select_data</emphasis> must be a pointer to a value of type
+<function>EventMask, indicating the event</function>
+mask to be used to deselect for the appropriate event. If the widget
+is realized,
+<xref linkend='XtRemoveEventTypeHandler' xrefstyle='select: title'/>
+calls
+<function>XSelectInput</function>
+if necessary.
+Specifying NULL for <emphasis remap='I'>select_data</emphasis> is equivalent to specifying a pointer
+to an event mask containing 0. This is similar to the
+<xref linkend='XtRemoveRawEventHandler' xrefstyle='select: title'/>
+function.
+</para>
+
+<para>
+If <emphasis remap='I'>event_type</emphasis> specifies an extension event type, then the semantics of
+the data pointed to by <emphasis remap='I'>select_data</emphasis> are defined by the extension
+selector registered for the specified event type.
+</para>
+
+<para>
+To register a procedure to select extension events for a widget, use
+<xref linkend='XtRegisterExtensionSelector' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRegisterExtensionSelector'>
+<funcprototype>
+<funcdef>void <function>XtRegisterExtensionSelector</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>int <parameter>min_event_type</parameter></paramdef>
+ <paramdef>int <parameter>max_event_type</parameter></paramdef>
+ <paramdef>XtExtensionSelectProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display for which the extension selector is to be registered.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>min_event_type</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>max_event_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the range of event types for the extension.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the extension selector procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional data to be passed to the extension selector.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRegisterExtensionSelector' xrefstyle='select: title'/>
+function registers a procedure to arrange
+for the delivery of extension events to widgets.
+</para>
+
+<para>
+If <emphasis remap='I'>min_event_type</emphasis> and <emphasis remap='I'>max_event_type</emphasis> match the parameters
+to a previous call to
+<xref linkend='XtRegisterExtensionSelector' xrefstyle='select: title'/>
+for the same <emphasis remap='I'>display</emphasis>, then <emphasis remap='I'>proc</emphasis> and <emphasis remap='I'>client_data</emphasis>
+replace the previously
+registered values. If the range specified by <emphasis remap='I'>min_event_type</emphasis>
+and <emphasis remap='I'>max_event_type</emphasis> overlaps the range of the parameters to a
+previous call for the same display in any other way, an error results.
+</para>
+
+<para>
+When a widget is realized,
+after the <emphasis remap='I'>core.realize</emphasis> method is called,
+the Intrinsics check to see if any event
+handler specifies an event type within the range of a registered
+extension selector. If so, the Intrinsics call each such selector.
+If an event type handler is added or removed, the Intrinsics check to
+see if the event type falls within the range of a registered extension
+selector, and if it does, calls the selector. In either case the Intrinsics
+pass a list of all the widget's event types that are within the
+selector's range. The corresponding select data are also passed. The
+selector is responsible for enabling the delivery of extension events
+required by the widget.
+</para>
+
+<para>
+An extension selector is of type
+<xref linkend='XtExtensionSelectProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtExtensionSelectProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtExtensionSelectProc)</function></funcdef>
+
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>int *<parameter>event_types</parameter></paramdef>
+ <paramdef>XtPointer *<parameter>select_data</parameter></paramdef>
+ <paramdef>int <parameter>count</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that is being realized or is having
+an event handler added or removed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_types</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of event types that the widget has
+registered event handlers for.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>select_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of the select_data parameters specified in
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the <emphasis remap='I'>event_types</emphasis> and <emphasis remap='I'>select_data</emphasis>
+lists.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data with which the procedure was registered.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The <emphasis remap='I'>event_types</emphasis> and <emphasis remap='I'>select_data</emphasis> lists will always have the
+same number of elements, specified by <emphasis remap='I'>count</emphasis>.
+Each event type/select data pair represents one call to
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To register a procedure to dispatch events of a specific type within
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>,
+use
+<xref linkend='XtSetEventDispatcher' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetEventDispatcher'>
+<funcprototype>
+<funcdef>XtEventDispatchProc <function>XtSetEventDispatcher</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>int <parameter>event_type</parameter></paramdef>
+ <paramdef>XtEventDispatchProc <parameter>proc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display for which the event dispatcher is to be registered.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event type for which the dispatcher should be invoked.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event dispatcher procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtSetEventDispatcher' xrefstyle='select: title'/>
+function registers the event dispatcher procedure specified by <emphasis remap='I'>proc</emphasis>
+for events with the type <emphasis remap='I'>event_type</emphasis>. The previously registered
+dispatcher (or the default dispatcher if there was no previously registered
+dispatcher) is returned. If <emphasis remap='I'>proc</emphasis> is NULL, the default procedure is
+restored for the specified type.
+</para>
+
+<para>
+In the future, when
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+is called with an event type of <emphasis remap='I'>event_type</emphasis>, the specified <emphasis remap='I'>proc</emphasis>
+(or the default dispatcher) is invoked to determine a widget
+to which to dispatch the event.
+</para>
+
+<para>
+The default dispatcher handles the Intrinsics modal cascade and keyboard
+focus mechanisms, handles the semantics of <emphasis remap='I'>compress_enterleave</emphasis>
+and <emphasis remap='I'>compress_motion</emphasis>, and discards all extension events.
+</para>
+
+<para>
+An event dispatcher procedure pointer is of type
+<xref linkend='XtEventDispatchProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtEventDispatchProc'>
+<funcprototype>
+<funcdef>typedef Boolean <function>(*XtEventDispatchProc)</function></funcdef>
+ <paramdef>XEvent *<parameter>event</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the event to be dispatched.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The event dispatcher procedure should determine whether this event is of
+a type that should be dispatched to a widget.
+</para>
+
+<para>
+If the event should be dispatched to a widget, the event dispatcher
+procedure should determine the appropriate widget to receive the
+event, call
+<function>XFilterEvent</function>
+with the window of this widget, or
+<function>None</function>
+if the event is to be discarded, and if
+<function>XFilterEvent</function>
+returns
+<function>False</function>,
+dispatch the event to the widget using
+<xref linkend='XtDispatchEventToWidget' xrefstyle='select: title'/>.
+The procedure should return
+<function>True</function>
+if either
+<function>XFilterEvent</function>
+or
+<xref linkend='XtDispatchEventToWidget' xrefstyle='select: title'/>
+returned
+<function>True</function>
+and
+<function>False</function>
+otherwise.
+</para>
+
+<para>
+If the event should not be dispatched to a widget, the event
+dispatcher procedure should attempt to dispatch the event elsewhere as
+appropriate and return
+<function>True</function>
+if it successfully dispatched the event and
+<function>False</function>
+otherwise.
+</para>
+
+<para>
+Some dispatchers for extension events may wish to forward events
+according to the Intrinsics' keyboard focus mechanism. To determine
+which widget is the end result of keyboard event forwarding, use
+<xref linkend='XtGetKeyboardFocusWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetKeyboardFocusWidget'>
+<funcprototype>
+<funcdef>Widget <function>XtGetKeyboardFocusWidget</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget to get forwarding information for.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetKeyboardFocusWidget' xrefstyle='select: title'/>
+function returns the widget that would be the end result of keyboard
+event forwarding for a keyboard event for the specified widget.
+</para>
+
+<para>
+To dispatch an event to a specified widget, use
+<xref linkend='XtDispatchEventToWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtDispatchEventToWidget'>
+<funcprototype>
+<funcdef>Boolean <function>XtDispatchEventToWidget</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>XEvent *<parameter>event</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget to which to dispatch the event.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the event to be dispatched.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDispatchEventToWidget' xrefstyle='select: title'/>
+function scans the list of registered event handlers for the
+specified widget and calls each handler that has been registered
+for the specified event type, subject to the <emphasis remap='I'>continue_to_dispatch</emphasis>
+value returned by each handler.
+The Intrinsics behave as if event handlers were registered at the head
+of the list for
+<function>Expose</function>,
+<function>NoExpose</function>,
+<function>GraphicsExpose</function>,
+and
+<function>VisibilityNotify</function>
+events to invoke the widget's expose procedure according to the exposure
+compression rules and to update the widget's <emphasis remap='I'>visible</emphasis> field
+if <emphasis remap='I'>visible_interest</emphasis> is
+<function>True</function>.
+These internal event handlers never set <emphasis remap='I'>continue_to_dispatch</emphasis> to
+<function>False</function>.
+</para>
+
+<para>
+<xref linkend='XtDispatchEventToWidget' xrefstyle='select: title'/>
+returns
+<function>True</function>
+if any event handler was called and
+<function>False</function>
+otherwise.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Using_the_Intrinsics_in_a_Multi_Threaded_Environment">
+<title>Using the Intrinsics in a Multi-Threaded Environment</title>
+<para>
+The Intrinsics may be used in environments that offer multiple threads
+of execution within the context of a single process. A multi-threaded
+application using the Intrinsics must explicitly initialize the toolkit
+for mutually exclusive access by calling
+<xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/>.
+</para>
+<sect2 id="Initializing_a_Multi_Threaded_Intrinsics_Application">
+<title>Initializing a Multi-Threaded Intrinsics Application</title>
+<para>
+To test and initialize Intrinsics support for mutually exclusive thread
+access, call
+<xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtToolkitThreadInitialize'>
+<funcprototype>
+<funcdef>Boolean <function>XtToolkitThreadInitialize</function></funcdef>
+ <paramdef><parameter>void</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+<xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/>
+returns <function>True</function> if the Intrinsics support mutually exclusive thread
+access, otherwise it returns <function>False</function>. <xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/>
+must be called before
+<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>,
+<xref linkend='XtAppInitialize' xrefstyle='select: title'/>,
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>,
+or
+<function>XtSetLanguageProc</function>
+is called. <xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/> may be called more than once;
+however, the application writer must ensure that it is not called
+simultaneously by two or more threads.
+</para>
+</sect2>
+
+<sect2 id="Locking_tk_Data_Structures">
+<title>Locking X Toolkit Data Structures</title>
+<para>
+The Intrinsics employs two levels of locking: application context and
+process. Locking an application context ensures mutually exclusive
+access by a thread to the state associated with the application context,
+including all displays and widgets associated with it. Locking a
+process ensures mutually exclusive access by a thread to Intrinsics process
+global data.
+</para>
+
+<para>
+A client may acquire a lock multiple times and the effect is cumulative.
+The client must ensure that the lock is released an equal number of times in
+order for the lock to be acquired by another thread.
+</para>
+
+<para>
+Most application writers will have little need to use locking as the
+Intrinsics performs the necessary locking internally.
+Resource converters are an exception.
+They require the application context or process to be locked
+before the application can safely call them directly, for example:
+</para>
+<programlisting>
+ ...
+ XtAppLock(app_context);
+ XtCvtStringToPixel(dpy, args, num_args, fromVal, toVal, closure_ret);
+ XtAppUnlock(app_context);
+ ...
+</programlisting>
+<para>
+When the application relies upon
+<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>
+or a converter to provide the storage for the results of a
+conversion, the application should acquire the process lock before
+calling out and hold the lock until the results have been copied.
+</para>
+
+<para>
+Application writers who write their own
+utility functions, such as one which retrieves the being_destroyed field from
+a widget instance, must lock the application context before accessing
+widget internal data. For example:
+</para>
+<programlisting>
+#include <X11/CoreP.h>
+Boolean BeingDestroyed (Widget widget)
+{
+ Boolean ret;
+ XtAppLock(XtWidgetToApplicationContext(widget));
+ ret = widget->core.being_destroyed;
+ XtAppUnlock(XtWidgetToApplicationContext(widget));
+ return ret;
+}
+</programlisting>
+<para>
+A client that wishes to atomically call two or more Intrinsics functions
+must lock the application context. For example:
+</para>
+<programlisting>
+ ...
+ XtAppLock(XtWidgetToApplicationContext(widget));
+ XtUnmanageChild (widget1);
+ XtManageChild (widget2);
+ XtAppUnlock(XtWidgetToApplicationContext(widget));
+ ...
+</programlisting>
+<sect3 id="Locking_the_Application_Context">
+<title>Locking the Application Context</title>
+<para>
+To ensure mutual exclusion of application context, display, or
+widget internal state, use
+<function>XtAppLock.</function>
+</para>
+
+<funcsynopsis id='XtAppLock'>
+<funcprototype>
+<funcdef>void <function>XtAppLock</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context to lock.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppLock' xrefstyle='select: title'/> blocks until it is able to acquire the lock. Locking the
+application context also ensures that only the thread holding the lock
+makes Xlib calls from within Xt. An application that makes its own
+direct Xlib calls must either lock the application context around every
+call or enable thread locking in Xlib.
+</para>
+
+<para>
+To unlock a locked application context, use
+<function>XtAppUnlock.</function>
+</para>
+
+<funcsynopsis id='XtAppUnlock'>
+<funcprototype>
+<funcdef>void <function>XtAppUnlock</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context that was previously locked.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+</sect3>
+<sect3 id="Locking_the_Process">
+<title>Locking the Process</title>
+<para>
+To ensure mutual exclusion of X Toolkit process global data, a
+widget writer must use
+<function>XtProcessLock.</function>
+</para>
+
+<funcsynopsis id='XtProcessLock'>
+<funcprototype>
+<funcdef>void <function>XtProcessLock</function></funcdef>
+ <paramdef><parameter>void</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+<xref linkend='XtProcessLock' xrefstyle='select: title'/> blocks until it is able to acquire the lock.
+Widget writers may use XtProcessLock to guarantee mutually exclusive
+access to widget static data.
+</para>
+
+<para>
+To unlock a locked process, use
+<xref linkend='XtProcessUnlock' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtProcessUnlock'>
+<funcprototype>
+<funcdef>void <function>XtProcessUnlock</function></funcdef>
+ <paramdef><parameter>void</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para>
+To lock both an application context and the process at the same
+time, call
+<xref linkend='XtAppLock' xrefstyle='select: title'/>
+first and then
+<xref linkend='XtProcessLock' xrefstyle='select: title'/>.
+To release both locks, call
+<xref linkend='XtProcessUnlock' xrefstyle='select: title'/>
+first and then
+<xref linkend='XtAppUnlock' xrefstyle='select: title'/>.
+The order is important to avoid deadlock.
+</para>
+</sect3>
+</sect2>
+
+<sect2 id="Event_Management_in_a_Multi_Threaded_Environment">
+<title>Event Management in a Multi-Threaded Environment</title>
+<para>
+In a nonthreaded environment an application writer could reasonably
+assume that it is safe to exit the application from a quit callback.
+This assumption may no longer hold true in a multi-threaded environment;
+therefore it is desirable to provide a mechanism to terminate an
+event-processing loop without necessarily terminating its thread.
+</para>
+
+<para>
+To indicate that the event loop should terminate after the current
+event dispatch has completed, use
+<xref linkend='XtAppSetExitFlag' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppSetExitFlag'>
+<funcprototype>
+<funcdef>void <function>XtAppSetExitFlag</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppMainLoop' xrefstyle='select: title'/>
+tests the value of the flag and will return if the flag is <function>True</function>.
+</para>
+
+<para>
+Application writers who implement their own main loop may test the
+value of the exit flag with
+<xref linkend='XtAppGetExitFlag' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppGetExitFlag'>
+<funcprototype>
+<funcdef>Boolean <function>XtAppGetExitFlag</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppGetExitFlag' xrefstyle='select: title'/>
+will normally return <function>False</function>, indicating that event processing
+may continue. When
+<xref linkend='XtAppGetExitFlag' xrefstyle='select: title'/>
+returns <function>True</function>, the loop must terminate and return to the caller,
+which might then destroy the application context.
+</para>
+
+<para>
+Application writers should be aware that, if a thread is blocked in
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>,
+<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>,
+or
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>
+and another thread in the same application context opens a new display,
+adds an alternate input, or a timeout, any new source(s) will not
+normally be “noticed” by the blocked thread. Any new sources are
+“noticed” the next time one of these functions is called.
+</para>
+
+<para>
+The Intrinsics manage access to events on a last-in, first-out basis. If
+multiple threads in the same application context block in
+<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>,
+<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>,
+or
+<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>,
+the last thread to call one of these functions is the first
+thread to return.
+</para>
+</sect2>
+</sect1>
+</chapter>
Index: create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH09.xml
===================================================================
--- create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH09.xml (nonexistent)
+++ create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH09.xml (revision 5)
@@ -0,0 +1,4391 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<chapter id='Resource_Management'>
+<title>Resource Management</title>
+<para>
+A resource is a field in the widget record with a corresponding
+resource entry in the <emphasis remap='I'>resources</emphasis> list of the widget or any of its
+superclasses.
+This means that the field is
+settable by
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+(by naming the field in the argument list), by an
+entry in a resource file (by using either the name or class), and by
+<xref linkend='XtSetValues' xrefstyle='select: title'/>.
+In addition, it is readable by
+<xref linkend='XtGetValues' xrefstyle='select: title'/>.
+Not all fields in a widget record are resources.
+Some are for bookkeeping use by the
+generic routines (like <emphasis remap='I'>managed</emphasis> and <emphasis remap='I'>being_destroyed</emphasis>).
+Others can be for local bookkeeping,
+and still others are derived from resources
+(many graphics contexts and pixmaps).
+</para>
+
+<para>
+Widgets typically need to obtain a large set of resources at widget
+creation time.
+Some of the resources come from the argument list supplied in the call to
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>,
+some from the resource database,
+and some from the internal defaults specified by the widget.
+Resources are obtained first from the argument list,
+then from the resource database for all resources not specified
+in the argument list,
+and last, from the internal default, if needed.
+</para>
+<sect1 id="Resource_Lists">
+<title>Resource Lists</title>
+<para>
+A resource entry specifies a field in the widget,
+the textual name and class of the field that argument lists
+and external resource files use to refer to the field,
+and a default value that the field should get if no value is specified.
+The declaration for the
+<function>XtResource</function>
+structure is
+</para>
+<programlisting>
+typedef struct {
+ String resource_name;
+ String resource_class;
+ String resource_type;
+ Cardinal resource_size;
+ Cardinal resource_offset;
+ String default_type;
+ XtPointer default_addr;
+} XtResource, *XtResourceList;
+</programlisting>
+<para>
+When the resource list is specified as the
+<function>CoreClassPart</function>,
+<function>ObjectClassPart</function>,
+<function>RectObjClassPart</function>,
+or
+<function>ConstraintClassPart</function>
+<emphasis remap='I'>resources</emphasis> field, the strings pointed to by <emphasis remap='I'>resource_name</emphasis>,
+<emphasis remap='I'>resource_class</emphasis>, <emphasis remap='I'>resource_type</emphasis>, and <emphasis remap='I'>default_type</emphasis> must
+be permanently allocated prior to or during the execution of the class
+initialization procedure and must not be subsequently deallocated.
+</para>
+
+<para>
+The <emphasis remap='I'>resource_name</emphasis> field contains the name used by clients to access the field
+in the widget.
+By convention, it starts with a lowercase letter
+and is spelled exactly like the field name,
+except all underscores (_) are deleted and the next letter is replaced by its
+uppercase counterpart.
+For example, the resource name for background_pixel becomes backgroundPixel.
+Resource names beginning with the two-character
+sequence “xt”, and resource classes beginning with the two-character
+sequence “Xt” are reserved to the Intrinsics for future standard and
+implementation-dependent uses.
+Widget header files typically contain a symbolic name for each resource name.
+All resource names, classes, and types used by the Intrinsics are named in
+<filename class="headerfile"><X11/StringDefs.h></filename>.
+The Intrinsics's symbolic resource names begin with
+“XtN”
+and are followed by the string name (for example, XtNbackgroundPixel
+for backgroundPixel).
+</para>
+
+<para>
+The <emphasis remap='I'>resource_class</emphasis> field contains the class string used in resource
+specification files to identify the field.
+A resource class provides two functions:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+It isolates an application from different representations that widgets
+can use for a similar resource.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It lets you specify values for several actual resources with a single name.
+A resource class should be chosen to span a group of closely related fields.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+For example,
+a widget can have several pixel resources: background, foreground,
+border, block cursor, pointer cursor, and so on.
+Typically, the background defaults to white
+and everything else to black.
+The resource class for each of these resources in the resource list
+should be chosen so that it takes the minimal number of entries
+in the resource database to make the background ivory
+and everything else darkblue.
+</para>
+
+<para>
+In this case, the background pixel should have a resource class of
+“Background”
+and all the other pixel entries a resource class of
+“Foreground”.
+Then, the resource file needs only two lines to
+change all pixels to ivory or darkblue:
+</para>
+<programlisting>
+*Background: ivory
+*Foreground: darkblue
+</programlisting>
+<para>
+Similarly, a widget may have several font resources (such as normal and bold),
+but all fonts should have the class Font.
+Thus, changing all fonts simply requires only a single line in the
+default resource file:
+</para>
+<programlisting>
+*Font: 6x13
+</programlisting>
+<para>
+By convention,
+resource classes are always spelled starting with a capital letter
+to distinguish them from resource names.
+Their symbolic names are preceded with
+“XtC”
+(for example, XtCBackground).
+</para>
+
+<para>
+The <emphasis remap='I'>resource_type</emphasis> field gives the physical representation type of the resource
+and also encodes information about the specific usage of the field.
+By convention, it starts with an uppercase letter and is
+spelled identically to the type name of the field.
+The resource type is used when resources are fetched to
+convert from the resource database format (usually
+<function>String</function>)
+or the format of the resource default value
+(almost anything, but often
+<function>String</function>)
+to the desired
+physical representation (see <xref linkend='Resource_Conversions' />).
+The Intrinsics define the following resource types:
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Resource Type</entry>
+ <entry>Structure or Field Type</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>XtRAcceleratorTable</function></entry>
+ <entry>XtAccelerators</entry>
+ </row>
+ <row>
+ <entry><function>XtRAtom</function></entry>
+ <entry>Atom</entry>
+ </row>
+ <row>
+ <entry><function>XtRBitmap</function></entry>
+ <entry>Pixmap, depth=1</entry>
+ </row>
+ <row>
+ <entry><function>XtRBoolean</function></entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry><function>XtRBool</function></entry>
+ <entry>Bool</entry>
+ </row>
+ <row>
+ <entry><function>XtRCallback</function></entry>
+ <entry>XtCallbackList</entry>
+ </row>
+ <row>
+ <entry><function>XtRCardinal</function></entry>
+ <entry>Cardinal</entry>
+ </row>
+ <row>
+ <entry><function>XtRColor</function></entry>
+ <entry>XColor</entry>
+ </row>
+ <row>
+ <entry><function>XtRColormap</function></entry>
+ <entry>Colormap</entry>
+ </row>
+ <row>
+ <entry><function>XtRCommandArgArray</function></entry>
+ <entry>String*</entry>
+ </row>
+ <row>
+ <entry><function>XtRCursor</function></entry>
+ <entry>Cursor</entry>
+ </row>
+ <row>
+ <entry><function>XtRDimension</function></entry>
+ <entry>Dimension</entry>
+ </row>
+ <row>
+ <entry><function>XtRDirectoryString</function></entry>
+ <entry>String</entry>
+ </row>
+ <row>
+ <entry><function>XtRDisplay</function></entry>
+ <entry>Display*</entry>
+ </row>
+ <row>
+ <entry><function>XtREnum</function></entry>
+ <entry>XtEnum</entry>
+ </row>
+ <row>
+ <entry><function>XtREnvironmentArray</function></entry>
+ <entry>String*</entry>
+ </row>
+ <row>
+ <entry><function>XtRFile</function></entry>
+ <entry>FILE*</entry>
+ </row>
+ <row>
+ <entry><function>XtRFloat</function></entry>
+ <entry>float</entry>
+ </row>
+ <row>
+ <entry><function>XtRFont</function></entry>
+ <entry>Font</entry>
+ </row>
+ <row>
+ <entry><function>XtRFontSet</function></entry>
+ <entry>XFontSet</entry>
+ </row>
+ <row>
+ <entry><function>XtRFontStruct</function></entry>
+ <entry>XFontStruct*</entry>
+ </row>
+ <row>
+ <entry><function>XtRFunction</function></entry>
+ <entry>(*)(Widget)</entry>
+ </row>
+ <row>
+ <entry><function>XtRGeometry</function></entry>
+ <entry>char*, format as defined by
+ <function>XParseGeometry</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRGravity</function></entry>
+ <entry>int</entry>
+ </row>
+ <row>
+ <entry><function>XtRInitialState</function></entry>
+ <entry>int</entry>
+ </row>
+ <row>
+ <entry><function>XtRInt</function></entry>
+ <entry>int</entry>
+ </row>
+ <row>
+ <entry><function>XtRLongBoolean</function></entry>
+ <entry>long</entry>
+ </row>
+ <row>
+ <entry><function>XtRObject</function></entry>
+ <entry>Object</entry>
+ </row>
+ <row>
+ <entry><function>XtRPixel</function></entry>
+ <entry>Pixel</entry>
+ </row>
+ <row>
+ <entry><function>XtRPixmap</function></entry>
+ <entry>Pixmap</entry>
+ </row>
+ <row>
+ <entry><function>XtRPointer</function></entry>
+ <entry>XtPointer</entry>
+ </row>
+ <row>
+ <entry><function>XtRPosition</function></entry>
+ <entry>Position</entry>
+ </row>
+ <row>
+ <entry><function>XtRRestartStyle</function></entry>
+ <entry>unsigned char</entry>
+ </row>
+ <row>
+ <entry><function>XtRScreen</function></entry>
+ <entry>Screen*</entry>
+ </row>
+ <row>
+ <entry><function>XtRShort</function></entry>
+ <entry>short</entry>
+ </row>
+ <row>
+ <entry><function>XtRSmcConn</function></entry>
+ <entry>XtPointer</entry>
+ </row>
+ <row>
+ <entry><function>XtRString</function></entry>
+ <entry>String</entry>
+ </row>
+ <row>
+ <entry><function>XtRStringArray</function></entry>
+ <entry>String*</entry>
+ </row>
+ <row>
+ <entry><function>XtRStringTable</function></entry>
+ <entry>String*</entry>
+ </row>
+ <row>
+ <entry><function>XtRTranslationTable</function></entry>
+ <entry>XtTranslations</entry>
+ </row>
+ <row>
+ <entry><function>XtRUnsignedChar</function></entry>
+ <entry>unsigned char</entry>
+ </row>
+ <row>
+ <entry><function>XtRVisual</function></entry>
+ <entry>Visual*</entry>
+ </row>
+ <row>
+ <entry><function>XtRWidget</function></entry>
+ <entry>Widget</entry>
+ </row>
+ <row>
+ <entry><function>XtRWidgetClass</function></entry>
+ <entry>WidgetClass</entry>
+ </row>
+ <row>
+ <entry><function>XtRWidgetList</function></entry>
+ <entry>WidgetList</entry>
+ </row>
+ <row>
+ <entry><function>XtRWindow</function></entry>
+ <entry>Window</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<filename class="headerfile"><X11/StringDefs.h></filename>
+also defines the following resource types as a
+convenience for widgets, although they do not have any corresponding
+data type assigned:
+<function>XtREditMode</function>,
+<function>XtRJustify</function>,
+and
+<function>XtROrientation</function>.
+</para>
+
+<para>
+The <emphasis remap='I'>resource_size</emphasis> field is the size of the physical representation in bytes;
+you should specify it as
+<function>sizeof</function>(type) so that the
+compiler fills in the value.
+The <emphasis remap='I'>resource_offset</emphasis> field is the offset in bytes of the field
+within the widget.
+You should use the
+<xref linkend='XtOffsetOf' xrefstyle='select: title'/>
+macro to retrieve this value.
+The <emphasis remap='I'>default_type</emphasis> field is the representation type of the default
+resource value.
+If <emphasis remap='I'>default_type</emphasis> is different from <emphasis remap='I'>resource_type</emphasis> and the default value
+is needed,
+the resource manager invokes a conversion procedure from <emphasis remap='I'>default_type</emphasis>
+to <emphasis remap='I'>resource_type</emphasis>.
+Whenever possible,
+the default type should be identical to the resource type in order
+to minimize widget creation time.
+However, there are sometimes no values of the type that the program
+can easily specify.
+In this case,
+it should be a value for which the converter is guaranteed to work (for example,
+<function>XtDefaultForeground</function>
+for a pixel resource).
+The <emphasis remap='I'>default_addr</emphasis> field specifies the address of the default resource value.
+As a special case, if <emphasis remap='I'>default_type</emphasis> is
+<function>XtRString</function>,
+then the value in the <emphasis remap='I'>default_addr</emphasis> field is the pointer to
+the string rather than a pointer to the pointer.
+The default is used if a resource is not specified in the argument list
+or in the resource database or if the conversion from the representation
+type stored in the resource database fails,
+which can happen for various reasons (for example, a misspelled entry in a
+resource file).
+</para>
+
+<para>
+Two special representation types
+(XtRImmediate
+and
+XtRCallProc)
+are usable only as default resource types.
+XtRImmediate
+indicates that the value in the <emphasis remap='I'>default_addr</emphasis> field is the actual value of
+the resource rather than the address of the value.
+The value must be in the correct representation type for the resource,
+coerced to an
+<function>XtPointer</function>.
+No conversion is possible, since there is no source representation type.
+XtRCallProc
+indicates that the value in the <emphasis remap='I'>default_addr</emphasis> field is a procedure
+pointer.
+This procedure is automatically invoked with the widget,
+<emphasis remap='I'>resource_offset</emphasis>, and a pointer to an
+<function>XrmValue</function>
+in which to store the result.
+XtRCallProc
+procedure pointers are of type
+<xref linkend='XtResourceDefaultProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtResourceDefaultProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtResourceDefaultProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>int <parameter>offset</parameter></paramdef>
+ <paramdef>XrmValue *<parameter>value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget whose resource value is to be obtained.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>offset</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the offset of the field in the widget record.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource value descriptor to return.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtResourceDefaultProc' xrefstyle='select: title'/>
+procedure should fill in the <emphasis remap='I'>value->addr</emphasis> field with a pointer
+to the resource value in its correct representation type.
+</para>
+
+<para>
+To get the resource list structure for a particular class, use
+<xref linkend='XtGetResourceList' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetResourceList'>
+<funcprototype>
+<funcdef>void <function>XtGetResourceList</function></funcdef>
+
+ <paramdef>WidgetClass <parameter>class</parameter></paramdef>
+ <paramdef>XtResourceList *<parameter>resources_return</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_resources_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object class to be queried. It must be
+<function>objectClass</function>
+or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If
+<xref linkend='XtGetResourceList' xrefstyle='select: title'/>
+is called before the class is initialized,
+it returns the resource list as specified in the class record.
+If it is called after the class has been initialized,
+<xref linkend='XtGetResourceList' xrefstyle='select: title'/>
+returns a merged resource list that includes the resources
+for all superclasses.
+The list returned by
+<xref linkend='XtGetResourceList' xrefstyle='select: title'/>
+should be freed using
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when it is no longer needed.
+</para>
+
+<para>
+To get the constraint resource list structure for a particular widget
+class, use
+<xref linkend='XtGetConstraintResourceList' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetConstraintResourceList'>
+<funcprototype>
+<funcdef>void <function>XtGetConstraintResourceList</function></funcdef>
+ <paramdef>WidgetClass <parameter>class</parameter></paramdef>
+ <paramdef>XtResourceList *<parameter>resources_return</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_resources_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object class to be queried. It must be
+<function>objectClass</function>
+or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the constraint resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of entries in the constraint resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If
+<xref linkend='XtGetConstraintResourceList' xrefstyle='select: title'/>
+is called before the widget class is
+initialized, the resource list as specified in the widget
+class Constraint part is returned. If
+<xref linkend='XtGetConstraintResourceList' xrefstyle='select: title'/>
+is called after the widget class has been initialized, the merged
+resource list for the class and all Constraint superclasses is
+returned. If the
+specified class is not a subclass of
+<function>constraintWidgetClass</function>,
+*<emphasis remap='I'>resources_return</emphasis> is set to NULL
+and *<emphasis remap='I'>num_resources_return</emphasis> is set to zero.
+The list returned by
+<xref linkend='XtGetConstraintResourceList' xrefstyle='select: title'/>
+should be freed using
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when it is no longer needed.
+</para>
+
+<para>
+The routines
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+and
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+also use the resource list to set and get widget state;
+see <xref linkend='Obtaining_Widget_State' /> and
+<xref linkend='Setting_Widget_State' />.
+</para>
+
+<para>
+Here is an abbreviated version of a possible resource list for a Label widget:
+</para>
+<programlisting>
+/* Resources specific to Label */
+static XtResource resources[] = {
+{XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel),
+ XtOffsetOf(LabelRec, label.foreground), XtRString, XtDefaultForeground},
+{XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*),
+ XtOffsetOf(LabelRec, label.font), XtRString, XtDefaultFont},
+{XtNlabel, XtCLabel, XtRString, sizeof(String),
+ XtOffsetOf(LabelRec, label.label), XtRString, NULL},
+ .
+ .
+ .
+}
+</programlisting>
+<para>
+The complete resource name for a field of a widget instance is the
+concatenation of the application shell name (from
+<function>XtAppCreateShell</function>),
+the instance names of all the widget's parents up to the
+top of the widget tree,
+the instance name of the widget itself,
+and the resource name of the specified field of the widget.
+Similarly,
+the full resource class of a field of a widget instance is the
+concatenation of the application class (from
+<function>XtAppCreateShell</function>),
+the widget class names of all the widget's parents up to the
+top of the widget tree,
+the widget class name of the widget itself,
+and the resource class of the specified field of the widget.
+</para>
+</sect1>
+
+<sect1 id="Byte_Offset_Calculations">
+<title>Byte Offset Calculations</title>
+<para>
+To determine the byte offset of a field within a structure type, use
+<xref linkend='XtOffsetOf' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtOffsetOf'>
+<funcprototype>
+<funcdef>Cardinal <function>XtOffsetOf</function></funcdef>
+ <paramdef>Type <parameter>structure_type</parameter></paramdef>
+ <paramdef>Field <parameter>field_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>structure_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a type that is declared as a structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>field_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of a member within the structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtOffsetOf' xrefstyle='select: title'/>
+macro expands to a constant expression that gives the
+offset in bytes to the specified structure member from the beginning
+of the structure. It is normally used to statically initialize
+resource lists and is more portable than
+<xref linkend='XtOffset' xrefstyle='select: title'/>,
+which serves the same function.
+</para>
+
+<para>
+To determine the byte offset of a field within a structure pointer type, use
+<xref linkend='XtOffset' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtOffset'>
+<funcprototype>
+<funcdef>Cardinal <function>XtOffset</function></funcdef>
+ <paramdef>Type <parameter> pointer_type</parameter></paramdef>
+ <paramdef>Field <parameter> field_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pointer_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a type that is declared as a pointer to a structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>field_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of a member within the structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtOffset' xrefstyle='select: title'/>
+macro expands to a constant expression that gives the
+offset in bytes to the specified structure member from the beginning
+of the structure. It may be used to statically initialize
+resource lists.
+<xref linkend='XtOffset' xrefstyle='select: title'/>
+is less portable than
+<xref linkend='XtOffsetOf' xrefstyle='select: title'/>.
+</para>
+</sect1>
+
+<sect1 id="Superclass_to_Subclass_Chaining_of_Resource_Lists">
+<title>Superclass-to-Subclass Chaining of Resource Lists</title>
+<para>
+The
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+function gets resources as a superclass-to-subclass chained operation.
+That is, the resources specified in the
+<function>objectClass</function>
+resource list are fetched,
+then those in
+<function>rectObjClass</function>,
+and so on down to the resources specified
+for this widget's class. Within a class, resources are fetched in the order
+they are declared.
+</para>
+
+<para>
+In general, if a widget resource field is declared in a superclass,
+that field is included in the superclass's resource list and need not be
+included in the subclass's resource list.
+For example, the
+Core
+class contains a resource entry for <emphasis remap='I'>background_pixel</emphasis>.
+Consequently,
+the implementation of Label need not also have a resource entry
+for <emphasis remap='I'>background_pixel</emphasis>.
+However, a subclass,
+by specifying a resource entry for that field in its own resource list,
+can override the resource entry for any field declared in a superclass.
+This is most often done to override the defaults provided in the
+superclass with new ones.
+At class initialization time,
+resource lists for that class are scanned from the superclass down
+to the class to look for resources with the same offset.
+A matching resource in a subclass will be reordered to override
+the superclass entry.
+If reordering is necessary, a copy of the superclass resource list is made to
+avoid affecting other subclasses of the superclass.
+</para>
+
+<para>
+Also at class initialization time, the Intrinsics produce an
+internal representation of the resource list to optimize access time
+when creating widgets. In order to save memory, the Intrinsics may
+overwrite the storage allocated for the resource list in the class
+record; therefore, widgets must allocate resource lists in writable
+storage and must not access the list contents directly after the
+class_initialize procedure has returned.
+</para>
+</sect1>
+
+<sect1 id="Subresources">
+<title>Subresources</title>
+<para>
+A widget does not do anything to retrieve its own resources;
+instead,
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+does this automatically before calling the class initialize procedure.
+</para>
+
+<para>
+Some widgets have subparts that are not widgets but for which the widget
+would like to fetch resources.
+Such widgets call
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>
+to accomplish this.
+</para>
+
+<funcsynopsis id='XtGetSubresources'>
+<funcprototype>
+<funcdef>void <function>XtGetSubresources</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>const char * <parameter>name</parameter></paramdef>
+ <paramdef>const char * <parameter>class</parameter></paramdef>
+ <paramdef>XtResourceList <parameter>resources</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_resources</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object used to qualify the subpart resource name and
+class. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>base</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the base address of the subpart data structure into which the
+resources will be written.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the subpart.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class of the subpart.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource list for the subpart.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list to override any other resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>
+function constructs a name and class list from the application name and class,
+the names and classes of all the object's ancestors, and the object itself.
+Then it appends to this list the <emphasis remap='I'>name</emphasis> and <emphasis remap='I'>class</emphasis> pair passed in.
+The resources are fetched from the argument list, the resource database,
+or the default values in the resource list.
+Then they are copied into the subpart record.
+If <emphasis remap='I'>args</emphasis> is NULL,
+<emphasis remap='I'>num_args</emphasis> must be zero.
+However, if <emphasis remap='I'>num_args</emphasis> is zero,
+the argument list is not referenced.
+</para>
+
+<para>
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>
+may overwrite the specified resource list with an
+equivalent representation in an internal format, which optimizes access
+time if the list is used repeatedly. The resource list must be
+allocated in writable storage, and the caller must not modify the list
+contents after the call if the same list is to be used again.
+Resources fetched by
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>
+are reference-counted as
+if they were referenced by the specified object. Subresources might
+therefore be freed from the conversion cache and destroyed
+when the object is destroyed, but not before then.
+</para>
+
+<para>
+To fetch resources for widget subparts using varargs lists, use
+<xref linkend='XtVaGetSubresources' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaGetSubresources'>
+<funcprototype>
+<funcdef>void <function>XtVaGetSubresources</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>const char * <parameter>name</parameter></paramdef>
+ <paramdef>const char * <parameter>class</parameter></paramdef>
+ <paramdef>XtResourceList <parameter>resources</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_resources</parameter></paramdef>
+ <paramdef>...</paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object used to qualify the subpart resource name and
+class. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>base</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the base address of the subpart data structure into which the
+resources will be written.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the subpart.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the class of the subpart.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource list for the subpart.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list to override any other
+resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtVaGetSubresources' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as
+described in Section 2.5.1.
+</para>
+</sect1>
+
+<sect1 id="Obtaining_Application_Resources">
+<title>Obtaining Application Resources</title>
+<para>
+To retrieve resources that are not specific to a widget
+but apply to the overall application, use
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetApplicationResources'>
+<funcprototype>
+<funcdef>void <function>XtGetApplicationResources</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>XtResourceList <parameter>resources</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_resources</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object that identifies the resource database to search
+(the database is that associated with the display for this object). Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>base</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the base address into which
+the resource values will be written.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list to override any other resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>
+function first uses the passed object,
+which is usually an application shell widget,
+to construct a resource name and class list.
+The full name and class of the specified object (that is, including its
+ancestors, if any) is logically added to the
+front of each resource name and class.
+Then it retrieves the resources from the argument list,
+the resource database, or the resource list default values.
+After adding base to each address,
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>
+copies the resources into the addresses
+obtained by adding <emphasis remap='I'>base</emphasis> to each <emphasis remap='I'>offset</emphasis> in the resource list.
+If <emphasis remap='I'>args</emphasis> is NULL,
+<emphasis remap='I'>num_args</emphasis> must be zero.
+However, if <emphasis remap='I'>num_args</emphasis> is zero,
+the argument list is not referenced.
+The portable way to specify application resources is to declare them
+as members of a structure and pass the address of the structure
+as the <emphasis remap='I'>base</emphasis> argument.
+</para>
+
+<para>
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>
+may overwrite the specified resource list
+with an equivalent representation in an internal format, which
+optimizes access time if the list is used repeatedly. The resource
+list must be allocated in writable storage, and the caller must not
+modify the list contents after the call if the same list is to be
+used again. Any per-display resources fetched by
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>
+will not be freed from the resource cache until the display is closed.
+</para>
+
+<para>
+To retrieve resources for the overall application using varargs lists, use
+<xref linkend='XtVaGetApplicationResources' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaGetApplicationResources'>
+<funcprototype>
+<funcdef>void <function>XtVaGetApplicationResources</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>XtResourceList <parameter>resources</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_resources</parameter></paramdef>
+ <paramdef>...</paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object that identifies the resource database to search
+(the database is that associated with the display for this object). Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>base</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the base address into which
+the resource values will be written.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource list for the subpart.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list to override any other
+resource specifications.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtVaGetApplicationResources' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters
+replaced by a varargs list, as described in Section 2.5.1.
+</para>
+</sect1>
+
+<sect1 id="Resource_Conversions">
+<title>Resource Conversions</title>
+<para>
+The Intrinsics provide a mechanism for registering representation converters that
+are automatically invoked by the resource-fetching routines.
+The Intrinsics additionally provide and register several commonly used converters.
+This resource conversion mechanism serves several purposes:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+It permits user and application resource files to contain textual
+representations of nontextual values.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It allows textual or other representations of default resource values that
+are dependent on the display, screen, or colormap, and thus must be
+computed at runtime.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It caches conversion source and result data.
+Conversions that require much computation or space
+(for example, string-to-translation-table)
+or that require round-trips to the server
+(for example, string-to-font or string-to-color) are performed only once.
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Predefined_Resource_Converters">
+<title>Predefined Resource Converters</title>
+<para>
+The Intrinsics define all the representations used in the
+Object,
+RectObj,
+Core,
+Composite,
+Constraint,
+and
+Shell
+widget classes.
+The Intrinsics register the following resource converters that accept
+input values of representation type
+<function>XtRString</function>.
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='3' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='0.7*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='0.6*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Target Representation</entry>
+ <entry>Converter Name</entry>
+ <entry>Additional Args</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>XtRAcceleratorTable</function></entry>
+ <entry><function>XtCvtStringToAcceleratorTable</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRAtom</function></entry>
+ <entry><function>XtCvtStringToAtom</function></entry>
+ <entry>Display*</entry>
+ </row>
+ <row>
+ <entry><function>XtRBoolean</function></entry>
+ <entry><function>XtCvtStringToBoolean</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRBool</function></entry>
+ <entry><function>XtCvtStringToBool</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRCommandArgArray</function></entry>
+ <entry><function>XtCvtStringToCommandArgArray</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRCursor</function></entry>
+ <entry><function>XtCvtStringToCursor</function></entry>
+ <entry>Display*</entry>
+ </row>
+ <row>
+ <entry><function>XtRDimension</function></entry>
+ <entry><function>XtCvtStringToDimension</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRDirectoryString</function></entry>
+ <entry><function>XtCvtStringToDirectoryString</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRDisplay</function></entry>
+ <entry><function>XtCvtStringToDisplay</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRFile</function></entry>
+ <entry><function>XtCvtStringToFile</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRFloat</function></entry>
+ <entry><function>XtCvtStringToFloat</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRFont</function></entry>
+ <entry><function>XtCvtStringToFont</function></entry>
+ <entry>Display*</entry>
+ </row>
+ <row>
+ <entry><function>XtRFontSet</function></entry>
+ <entry><function>XtCvtStringToFontSet</function></entry>
+ <entry>Display*, String <emphasis remap='I'>locale</emphasis></entry>
+ </row>
+ <row>
+ <entry><function>XtRFontStruct</function></entry>
+ <entry><function>XtCvtStringToFontStruct</function></entry>
+ <entry>Display*</entry>
+ </row>
+ <row>
+ <entry><function>XtRGravity</function></entry>
+ <entry><function>XtCvtStringToGravity</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRInitialState</function></entry>
+ <entry><function>XtCvtStringToInitialState</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRInt</function></entry>
+ <entry><function>XtCvtStringToInt</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRPixel</function></entry>
+ <entry><function>XtCvtStringToPixel</function></entry>
+ <entry><function>colorConvertArgs</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRPosition</function></entry>
+ <entry><function>XtCvtStringToPosition</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRRestartStyle</function></entry>
+ <entry><function>XtCvtStringToRestartStyle</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRShort</function></entry>
+ <entry><function>XtCvtStringToShort</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRTranslationTable</function></entry>
+ <entry><function>XtCvtStringToTranslationTable</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRUnsignedChar</function></entry>
+ <entry><function>XtCvtStringToUnsignedChar</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRVisual</function></entry>
+ <entry><function>XtCvtStringToVisual</function></entry>
+ <entry>Screen*, Cardinal <emphasis remap='I'>depth</emphasis></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The String-to-Pixel conversion has two predefined constants that are
+guaranteed to work and contrast with each other:
+<function>XtDefaultForeground</function>
+and
+<function>XtDefaultBackground</function>.
+They evaluate to the black and white pixel values of the widget's screen,
+respectively.
+If the application resource reverseVideo is
+<function>True</function>,
+they evaluate to the white and black pixel values of the widget's screen,
+respectively.
+Similarly, the String-to-Font and String-to-FontStruct converters recognize
+the constant
+<function>XtDefaultFont</function>
+and evaluate this in the following manner:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Query the resource database for the resource whose full name
+is “xtDefaultFont”, class “XtDefaultFont” (that is, no widget
+name/class prefixes), and use a type
+<function>XtRString</function>
+value returned as the font name or a type
+<function>XtRFont</function>
+or
+<function>XtRFontStruct</function>
+value directly as the resource value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the resource database does not contain a value for xtDefaultFont,
+class XtDefaultFont, or if the returned font name cannot be
+successfully opened, an implementation-defined font in ISO8859-1
+character set encoding is opened. (One possible algorithm is to
+perform an
+<function>XListFonts</function>
+using a wildcard font name and use the first
+font in the list. This wildcard font name should be as broad as
+possible to maximize the probability of locating a useable font;
+for example, “<code>-*-*-*-R-*-*-*-120-*-*-*-*-ISO8859-1</code>”.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If no suitable ISO8859-1 font can be found, issue a warning message
+and return
+<function>False</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The String-to-FontSet converter recognizes the constant
+<function>XtDefaultFontSet</function>
+and evaluate this in the following manner:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Query the resource database for the resource whose full name
+is “xtDefaultFontSet”, class “XtDefaultFontSet” (that is, no widget
+name/class prefixes), and use a type
+<function>XtRString</function>
+value returned as the base font name list or a type
+<function>XtRFontSet</function>
+value directly as the resource value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the resource database does not contain a value for xtDefaultFontSet,
+class XtDefaultFontSet, or if a font set cannot be
+successfully created from this resource,
+an implementation-defined font set is created.
+(One possible algorithm is to
+perform an
+<function>XCreateFontSet</function>
+using a wildcard base font name.
+This wildcard base font name should be as broad as
+possible to maximize the probability of locating a useable font;
+for example, “<code>-*-*-*-R-*-*-*-120-*-*-*-*</code>”.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If no suitable font set can be created, issue a warning message
+and return
+<function>False</function>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+If a font set is created but <emphasis remap='I'>missing_charset_list</emphasis> is not
+empty, a warning is issued and the partial font set is returned.
+The Intrinsics register the String-to-FontSet converter with
+a conversion argument list that extracts the current process
+locale at the time the converter is invoked. This ensures
+that the converter is invoked again if the same conversion
+is required in a different locale.
+</para>
+
+<para>
+The String-to-Gravity conversion accepts string values that are the
+names of window and bit gravities and their numerical equivalents,
+as defined in <emphasis remap='I'>Xlib — C Language X Interface</emphasis>:
+<function>ForgetGravity</function>,
+<function>UnmapGravity</function>,
+<function>NorthWestGravity</function>,
+<function>NorthGravity</function>,
+<function>NorthEastGravity</function>,
+<function>WestGravity</function>,
+<function>CenterGravity</function>,
+<function>EastGravity</function>,
+<function>SouthWestGravity</function>,
+<function>SouthGravity</function>,
+<function>SouthEastGravity</function>,
+and
+<function>StaticGravity</function>.
+Alphabetic case is not significant in the conversion.
+</para>
+
+<para>
+The String-to-CommandArgArray conversion parses a String into an
+array of strings.
+White space characters separate elements of the command line.
+The converter recognizes the backslash character “\” as an escape
+character to allow the following white space character to be part of the
+array element.
+</para>
+
+<para>
+The String-to-DirectoryString conversion recognizes the
+string “XtCurrentDirectory” and returns the result of a call
+to the operating system to get the current directory.
+</para>
+
+<para>
+The String-to-RestartStyle conversion accepts the values
+<function>RestartIfRunning</function>,
+<function>RestartAnyway</function>,
+<function>RestartImmediately</function>,
+and
+<function>RestartNever</function>
+as defined by the <emphasis remap='I'>X Session Management Protocol</emphasis>.
+</para>
+
+<para>
+The String-to-InitialState conversion accepts the values
+<function>NormalState</function>
+or
+<function>IconicState</function>
+as defined by the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
+</para>
+
+<para>
+The String-to-Visual conversion calls
+<function>XMatchVisualInfo</function>
+using the
+<emphasis remap='I'>screen</emphasis> and <emphasis remap='I'>depth</emphasis> fields from the core part and returns the first
+matching Visual on the list. The widget resource list must be certain
+to specify any resource of type
+<function>XtRVisual</function>
+after the depth resource.
+The allowed string values are the visual class names defined in <emphasis remap='I'>X Window System Protocol</emphasis>,
+Section 8;
+<function>StaticGray</function>,
+<function>StaticColor</function>,
+<function>TrueColor</function>,
+<function>GrayScale</function>,
+<function>PseudoColor</function>,
+and
+<function>DirectColor</function>.
+</para>
+
+<para>
+The Intrinsics register the following resource converter that accepts
+an input value of representation type
+<function>XtRColor</function>.
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='3' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Target Representation</entry>
+ <entry>Converter Name</entry>
+ <entry>Additional Args</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>XtRPixel</function></entry>
+ <entry><function>XtCvtColorToPixel</function></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The Intrinsics register the following resource converters that accept
+input values of representation type
+<function>XtRInt</function>.
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='3' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Target Representation</entry>
+ <entry>Converter Name</entry>
+ <entry>Additional Args</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>XtRBoolean</function></entry>
+ <entry><function>XtCvtIntToBoolean</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRBool</function></entry>
+ <entry><function>XtCvtIntToBool</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRColor</function></entry>
+ <entry><function>XtCvtIntToColor</function></entry>
+ <entry><function>colorConvertArgs</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRDimension</function></entry>
+ <entry><function>XtCvtIntToDimension</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRFloat</function></entry>
+ <entry><function>XtCvtIntToFloat</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRFont</function></entry>
+ <entry><function>XtCvtIntToFont</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRPixel</function></entry>
+ <entry><function>XtCvtIntToPixel</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRPixmap</function></entry>
+ <entry><function>XtCvtIntToPixmap</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRPosition</function></entry>
+ <entry><function>XtCvtIntToPosition</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRShort</function></entry>
+ <entry><function>XtCvtIntToShort</function></entry>
+ </row>
+ <row>
+ <entry><function>XtRUnsignedChar</function></entry>
+ <entry><function>XtCvtIntToUnsignedChar</function></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The Intrinsics register the following resource converter that accepts
+an input value of representation type
+<function>XtRPixel</function>.
+</para>
+
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='3' align='left' rowsep='0' colsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Target Representation</entry>
+ <entry>Converter Name</entry>
+ <entry>Additional Args</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><function>XtRColor</function></entry>
+ <entry><function>XtCvtPixelToColor</function></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</sect2>
+
+<sect2 id="New_Resource_Converters">
+<title>New Resource Converters</title>
+<para>
+Type converters use pointers to
+<function>XrmValue</function>
+structures (defined in
+<filename class="headerfile"><X11/Xresource.h>;</filename>
+see Section 15.4 in
+Xlib — C Language X Interface)
+for input and output values.
+</para>
+<programlisting>
+typedef struct {
+ unsigned int size;
+ XPointer addr;
+} XrmValue, *XrmValuePtr;
+</programlisting>
+<para>
+The <emphasis remap='I'>addr</emphasis> field specifies the address of the data, and the <emphasis remap='I'>size</emphasis>
+field gives the total number of significant bytes in the data.
+For values of type
+<function>String</function>,
+<emphasis remap='I'>addr</emphasis> is the address of the first character and <emphasis remap='I'>size</emphasis>
+includes the NULL-terminating byte.
+</para>
+
+<para>
+A resource converter procedure pointer is of type
+<xref linkend='XtTypeConverter' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtTypeConverter'>
+<funcprototype>
+<funcdef>typedef Boolean <function>(*XtTypeConverter)</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>XrmValue *<parameter>args</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
+ <paramdef>XrmValue *<parameter>from</parameter></paramdef>
+ <paramdef>XrmValue *<parameter>to</parameter></paramdef>
+ <paramdef>XtPointer *<parameter>converter_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display connection with which this conversion is associated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of additional
+<function>XrmValue</function>
+arguments to the converter if additional context is needed
+to perform the conversion, or NULL.
+For example, the String-to-Font converter needs the widget's <emphasis remap='I'>display</emphasis>,
+and the String-to-Pixel converter needs the widget's <emphasis remap='I'>screen</emphasis> and <emphasis remap='I'>colormap</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>args</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value to convert.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a descriptor for a location into which to store the converted value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>converter_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a location into which the converter may
+store converter-specific data associated
+with this conversion.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The <emphasis remap='I'>display</emphasis> argument is normally used only when generating error
+messages, to identify the application context (with the function
+<function>XtDisplayToApplicationContext ).</function>
+</para>
+
+<para>
+The <emphasis remap='I'>to</emphasis> argument specifies the size and location into which the
+converter should store the converted value. If the <emphasis remap='I'>addr</emphasis> field is NULL,
+the converter should allocate appropriate storage and store the size
+and location into the <emphasis remap='I'>to</emphasis> descriptor. If the type converter allocates
+the storage, it remains under the ownership of the converter and must
+not be modified by the caller. The type converter is permitted to use
+static storage for this purpose, and therefore the caller must
+immediately copy the data upon return from the converter. If the
+<emphasis remap='I'>addr</emphasis> field is not NULL, the converter must check the <emphasis remap='I'>size</emphasis> field to
+ensure that sufficient space has been allocated before storing the
+converted value. If insufficient space is specified, the converter
+should update the <emphasis remap='I'>size</emphasis> field with the number of bytes required and
+return
+<function>False</function>
+without modifying the data at the specified location.
+If sufficient space was allocated by the caller, the converter should
+update the <emphasis remap='I'>size</emphasis> field with the number of bytes actually occupied by the
+converted value. For converted values of type
+<function>XtRString</function>,
+the size should
+include the NULL-terminating byte, if any.
+The converter may store any value in the location specified
+in <emphasis remap='I'>converter_data</emphasis>; this value will be passed to the destructor, if any,
+when the resource is freed by the Intrinsics.
+</para>
+
+<para>
+The converter must return
+<function>True</function>
+if the conversion was successful and
+<function>False</function>
+otherwise. If the conversion cannot be performed because of an
+improper source value, a warning message should also be issued with
+<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>.
+</para>
+
+<para>
+Most type converters just take the data described by the specified <emphasis remap='I'>from</emphasis>
+argument and return data by writing into the location specified in
+the <emphasis remap='I'>to</emphasis> argument.
+A few need other information, which is available in <emphasis remap='I'>args</emphasis>.
+A type converter can invoke another type converter,
+which allows differing sources that may convert into a common intermediate
+result to make maximum use of the type converter cache.
+</para>
+
+<para>
+Note that if an address is written into <emphasis remap='I'>to->addr</emphasis>, it cannot be that
+of a local variable of the converter because the data will not be
+valid after the converter returns. Static variables may be used,
+as in the following example.
+If the converter modifies the resource database,
+the changes affect any in-progress widget creation,
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>,
+or
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>
+in an implementation-defined manner; however, insertion of new entries
+or changes to existing entries is allowed and will not directly cause
+an error.
+</para>
+
+<para>
+The following is an example of a converter that takes a
+<function>string</function>
+and converts it to a
+<function>Pixel</function>.
+Note that the <emphasis remap='I'>display</emphasis> parameter is
+used only to generate error messages; the
+<function>Screen</function>
+conversion argument is
+still required to inform the Intrinsics that the converted value is
+a function of the particular display (and colormap).
+</para>
+
+<programlisting>
+#define done(type, value) \
+ { \
+ if (toVal->addr != NULL) { \
+ if (toVal->size < sizeof(type)) { \
+ toVal->size = sizeof(type); \
+ return False; \
+ } \
+ *(type*)(toVal->addr) = (value); \
+ } \
+ else { \
+ static type static_val; \
+ static_val = (value); \
+ toVal->addr = (XPointer)&static_val; \
+ } \
+ toVal->size = sizeof(type); \
+ return True; \
+ }
+
+static Boolean CvtStringToPixel(
+ Display *dpy,
+ XrmValue *args,
+ Cardinal *num_args,
+ XrmValue *fromVal,
+ XrmValue *toVal,
+ XtPointer *converter_data)
+{
+ static XColor screenColor;
+ XColor exactColor;
+ Screen *screen;
+ Colormap colormap;
+ Status status;
+
+ if (*num_args != 2)
+ XtAppWarningMsg(XtDisplayToApplicationContext(dpy),
+ "wrongParameters", "cvtStringToPixel", "XtToolkitError",
+ "String to pixel conversion needs screen and colormap arguments",
+ (String *)NULL, (Cardinal *)NULL);
+ screen = *((Screen**) args[0].addr);
+ colormap = *((Colormap *) args[1].addr);
+ if (CompareISOLatin1(str, XtDefaultBackground) == 0) {
+ *closure_ret = False;
+ done(Pixel, WhitePixelOfScreen(screen));
+ }
+ if (CompareISOLatin1(str, XtDefaultForeground) == 0) {
+ *closure_ret = False;
+ done(Pixel, BlackPixelOfScreen(screen));
+ }
+ status = XAllocNamedColor(DisplayOfScreen(screen),
+ colormap, (char*)fromVal->addr,
+ &screenColor, &exactColor);
+ if (status == 0) {
+ String params[1];
+ Cardinal num_params = 1;
+ params[0] = (String)fromVal->addr;
+ XtAppWarningMsg(XtDisplayToApplicationContext(dpy),
+ "noColormap",
+ "cvtStringToPixel",
+ "XtToolkitError",
+ "Cannot allocate colormap entry for \"%s\"",
+ params, &num_params);
+ *converter_data = (char *) False;
+ return False;
+ } else {
+ *converter_data = (char *) True;
+ done(Pixel, &screenColor.pixel);
+ }
+}
+</programlisting>
+
+<para>
+All type converters should define some set of conversion values for which they
+are guaranteed to succeed so these can be used in the resource defaults.
+This issue arises only with conversions, such as fonts and colors,
+where there is no string representation that all server implementations
+will necessarily recognize.
+For resources like these,
+the converter should define a symbolic constant
+in the same manner as
+<function>XtDefaultForeground</function>,
+<function>XtDefaultBackground</function>,
+and
+<function>XtDefaultFont</function>.
+</para>
+
+<para>
+To allow the Intrinsics to deallocate resources produced by type
+converters, a resource destructor procedure may also be provided.
+</para>
+
+<para>
+A resource destructor procedure pointer is of type
+<xref linkend='XtDestructor' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtDestructor'>
+<funcprototype>
+ <funcdef>typedef void <function>(*XtDestructor)</function></funcdef>
+ <paramdef>XtAppContext <parameter>app</parameter></paramdef>
+ <paramdef>XrmValue *<parameter>to</parameter></paramdef>
+ <paramdef>XtPointer <parameter>converter_data</parameter></paramdef>
+ <paramdef>XrmValue *<parameter>args</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an application context in which the resource is being freed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a descriptor for the resource produced by the type converter.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>converter_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the converter-specific data returned by the type converter.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional converter arguments as passed
+to the type converter when the conversion was performed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>args</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The destructor procedure is responsible for freeing the resource
+specified by the <emphasis remap='I'>to</emphasis> argument, including any auxiliary storage
+associated with that resource, but not the memory directly addressed
+by the size and location in the <emphasis remap='I'>to</emphasis> argument or the memory specified
+by <emphasis remap='I'>args</emphasis>.
+</para>
+</sect2>
+
+<sect2 id="Issuing_Conversion_Warnings">
+<title>Issuing Conversion Warnings</title>
+<para>
+The
+<xref linkend='XtDisplayStringConversionWarning' xrefstyle='select: title'/>
+procedure is a convenience routine for resource type converters
+that convert from string values.
+</para>
+
+<funcsynopsis id='XtDisplayStringConversionWarning'>
+<funcprototype>
+<funcdef>void <function>XtDisplayStringConversionWarning</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>const char * <parameter>from_value</parameter></paramdef>
+ <paramdef>const char * <parameter>to_type</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display connection with which the conversion is associated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from_value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the string that could not be converted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target representation type requested.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDisplayStringConversionWarning' xrefstyle='select: title'/>
+procedure issues a warning message using
+<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>
+with <emphasis remap='I'>name</emphasis> “conversionError”,
+<emphasis remap='I'>type</emphasis> “string”, <emphasis remap='I'>class</emphasis> “XtToolkitError”, and the default message
+“Cannot convert "<emphasis remap='I'>from_value</emphasis>" to type <emphasis remap='I'>to_type</emphasis>”.
+</para>
+
+<para>
+To issue other types of warning or error messages, the type converter
+should use
+<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>
+or
+<xref linkend='XtAppErrorMsg' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To retrieve the application context associated with a given
+display connection, use
+<xref linkend='XtDisplayToApplicationContext' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtDisplayToApplicationContext'>
+<funcprototype>
+<funcdef>XtAppContext <function>XtDisplayToApplicationContext</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an open and initialized display connection.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDisplayToApplicationContext' xrefstyle='select: title'/>
+function returns the application
+context in which the specified <emphasis remap='I'>display</emphasis> was initialized. If the
+display is not known to the Intrinsics, an error message is issued.
+</para>
+</sect2>
+
+<sect2 id="Registering_a_New_Resource_Converter">
+<title>Registering a New Resource Converter</title>
+<para>
+When registering a resource converter, the client must specify the
+manner in which the conversion cache is to be used when there are multiple
+calls to the converter. Conversion cache control is specified
+via an <function>XtCacheType</function>
+argument. </para>
+
+<programlisting>
+typedef int XtCacheType;
+</programlisting>
+
+<para>
+An <function>XtCacheType</function>
+field may contain one of the following values:
+</para>
+
+<para>
+<function>XtCacheNone</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Specifies that the results of a previous conversion
+may not be reused to satisfy any other resource
+requests; the specified converter will be called
+each time the converted value is required.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<function>XtCacheAll</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Specifies that the results of a previous conversion
+should be reused for any resource request that depends
+upon the same source value and conversion arguments.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<function>XtCacheByDisplay</function>
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Specifies that the results of a previous conversion
+should be used as for
+<function>XtCacheAll</function>
+but the destructor will be called, if specified, if
+<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
+is called
+for the display connection associated with the converted value, and
+the value will be removed from the conversion cache.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The qualifier
+<function>XtCacheRefCount</function>
+may be ORed with any of the above values. If
+<function>XtCacheRefCount</function>
+is specified, calls to
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>,
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>,
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>,
+and
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>
+that use the converted value will be counted. When a widget using the
+converted value is destroyed, the count is decremented, and, if the
+count reaches zero, the destructor procedure will be called and the
+converted value will be removed from the conversion cache.
+</para>
+
+<para>
+To register a type converter for all application contexts in a
+process, use
+<xref linkend='XtSetTypeConverter' xrefstyle='select: title'/>,
+and to register a type converter in a single application context, use
+<xref linkend='XtAppSetTypeConverter' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetTypeConverter'>
+<funcprototype>
+<funcdef>void <function>XtSetTypeConverter</function></funcdef>
+ <paramdef>const char * <parameter>from_type</parameter></paramdef>
+ <paramdef>const char * <parameter>to_type</parameter></paramdef>
+ <paramdef>XtTypeConverter <parameter>converter</parameter></paramdef>
+ <paramdef>XtConvertArgList <parameter>convert_args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+ <paramdef>XtCacheType <parameter>cache_type</parameter></paramdef>
+ <paramdef>XtDestructor <parameter>destructor</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the destination type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>converter</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource type converter procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>convert_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional conversion arguments, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>convert_args</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cache_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether or not resources produced by this
+converter are sharable or display-specific and when
+they should be freed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>destructor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a destroy procedure for resources produced by
+this conversion, or NULL if no additional action is
+required to deallocate resources produced by the converter.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<funcsynopsis id='XtAppSetTypeConverter'>
+<funcprototype>
+<funcdef>void <function>XtAppSetTypeConverter</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>const char * <parameter>from_type</parameter></paramdef>
+ <paramdef>const char * <parameter>to_type</parameter></paramdef>
+ <paramdef>XtTypeConverter <parameter>converter</parameter></paramdef>
+ <paramdef>XtConvertArgList <parameter>convert_args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+ <paramdef>XtCacheType <parameter>cache_type</parameter></paramdef>
+ <paramdef>XtDestructor <parameter>destructor</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the destination type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>converter</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource type converter procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>convert_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional conversion arguments, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>convert_args</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cache_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether or not resources produced by this
+converter are sharable or display-specific and when
+they should be freed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>destructor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a destroy procedure for resources produced by
+this conversion, or NULL if no additional action is
+required to deallocate resources produced by the converter.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtSetTypeConverter' xrefstyle='select: title'/>
+registers the specified type converter and
+destructor in all application contexts created by the calling process,
+including any future application contexts that may be created.
+<xref linkend='XtAppSetTypeConverter' xrefstyle='select: title'/>
+registers the specified type converter in the
+single application context specified. If the same <emphasis remap='I'>from_type</emphasis> and
+<emphasis remap='I'>to_type</emphasis> are specified in multiple calls to either function, the most
+recent overrides the previous ones.
+</para>
+
+<para>
+For the few type converters that need additional arguments,
+the Intrinsics conversion mechanism provides a method of specifying
+how these arguments should be computed.
+The enumerated type
+<function>XtAddressMode</function>
+and the structure
+<function>XtConvertArgRec</function>
+specify how each argument is derived.
+These are defined in
+<filename class="headerfile"><X11/Intrinsic.h></filename>.
+</para>
+<programlisting>
+typedef enum {
+ /* address mode parameter representation */
+ XtAddress, /* address */
+ XtBaseOffset, /* offset */
+ XtImmediate, /* constant */
+ XtResourceString, /* resource name string */
+ XtResourceQuark, /* resource name quark */
+ XtWidgetBaseOffset, /* offset */
+ XtProcedureArg /* procedure to call */
+} XtAddressMode;
+
+typedef struct {
+ XtAddressMode address_mode;
+ XtPointer address_id;
+ Cardinal size;
+} XtConvertArgRec, *XtConvertArgList;
+</programlisting>
+<para>
+The <emphasis remap='I'>size</emphasis> field specifies the length of the data in bytes.
+The <emphasis remap='I'>address_mode</emphasis> field specifies how the <emphasis remap='I'>address_id</emphasis> field should be
+interpreted.
+<function>XtAddress</function>
+causes <emphasis remap='I'>address_id</emphasis> to be interpreted as the address of the data.
+<function>XtBaseOffset</function>
+causes <emphasis remap='I'>address_id</emphasis> to be interpreted as the offset from the widget base.
+<function>XtImmediate</function>
+causes <emphasis remap='I'>address_id</emphasis> to be interpreted as a constant.
+<function>XtResourceString</function>
+causes <emphasis remap='I'>address_id</emphasis> to be interpreted as the name of a resource
+that is to be converted into an offset from the widget base.
+<function>XtResourceQuark</function>
+causes <emphasis remap='I'>address_id</emphasis> to be interpreted as the result of an
+<function>XrmStringToQuark</function>
+conversion on the name of a resource,
+which is to be converted into an offset from the widget base.
+<function>XtWidgetBaseOffset</function>
+is similar to
+<function>XtBaseOffset</function>
+except that it
+searches for the closest windowed ancestor if the object is not
+of a subclass of
+Core
+(see <xref linkend='Nonwidget_Objects' />).
+<function>XtProcedureArg</function>
+specifies that <emphasis remap='I'>address_id</emphasis> is a pointer to a procedure to
+be invoked to return the conversion argument. If
+<function>XtProcedureArg</function>
+is specified, <emphasis remap='I'>address_id</emphasis> must contain
+the address of a function of type
+<xref linkend='XtConvertArgProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtConvertArgProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtConvertArgProc)</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>size</parameter></paramdef>
+ <paramdef>XrmValue *<parameter>value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes the object for which the resource is being
+converted, or NULL if the converter was invoked by
+<xref linkend='XtCallConverter' xrefstyle='select: title'/> or
+<xref linkend='XtDirectConvert' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>size</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes a pointer to the size field from the XtConvertArgRec.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Passes a pointer to a descriptor into which the procedure must store the
+conversion argument.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+When invoked, the <function>XtConvertArgProc</function> procedure must derive a
+conversion argument and store the address and size of the
+argument in the location pointed to by value.
+</para>
+<para>
+In order to permit reentrancy, the <function>XtConvertArgProc</function> should
+return the address of storage whose lifetime is no shorter
+than the lifetime of object.
+If object is NULL,
+the lifetime of the conversion argument must be no shorter than the
+lifetime of the resource with which the conversion argument
+is associated. The Intrinsics do not guarantee to copy this
+storage but do guarantee not to reference it if the resource
+is removed from the conversion cache.
+</para>
+<para>
+The following example illustrates how to register the
+<function>CvtStringToPixel</function>
+routine given earlier:
+</para>
+<programlisting>
+static XtConvertArgRec colorConvertArgs[] = {
+ {XtWidgetBaseOffset,
+ (XtPointer)XtOffset(Widget, core.screen),
+ sizeof(Screen*)},
+ {XtWidgetBaseOffset,
+ (XtPointer)XtOffset(Widget, core.colormap),
+ sizeof(Colormap)}
+};
+
+XtSetTypeConverter(XtRString,
+ XtRPixel,
+ CvtStringToPixel,
+ colorConvertArgs,
+ XtNumber(colorConvertArgs),
+ XtCacheByDisplay, NULL);
+</programlisting>
+<para>
+The conversion argument descriptors colorConvertArgs and
+screenConvertArg are predefined by the Intrinsics. Both
+take the values from the closest windowed ancestor if the
+object is not of a subclass of Core. The screenConvertArg
+descriptor puts the widget’s screen field into args[0]. The
+colorConvertArgs descriptor puts the widget’s screen field
+into args[0], and the widget’s colormap field into args[1].
+</para>
+<para>
+Conversion routines should not just put a descriptor for the
+address of the base of the widget into args[0], and use that
+in the routine. They should pass in the actual values on
+which the conversion depends. By keeping the dependencies
+of the conversion procedure specific, it is more likely that
+subsequent conversions will find what they need in the conversion cache.
+This way the cache is smaller and has fewer
+and more widely applicable entries.
+</para>
+<para>
+If any conversion arguments of type
+<type>XtBaseOffset</type>,
+<type>XtResourceString</type>,
+<type>XtResourceQuark</type>,
+and
+<type>XtWidgetBaseOffset</type>
+are
+specified for conversions performed by
+<type>XtGetApplicationResources</type>,
+<type>XtGetSubresources</type>,
+<type>XtVaGetApplicationResources</type>,
+or
+<type>XtVaGetSubresources</type>,
+the arguments are computed with respect
+to the specified widget, not the base address or resource
+list specified in the call.
+</para>
+<para>
+If the <function>XtConvertArgProc</function> modifies the resource database, the
+changes affect any in-progress widget creation,
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>,
+or
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>
+in an implementation-defined manner;
+however, insertion of new entries or changes
+to existing entries are allowed and will not directly cause
+an error.
+</para>
+</sect2>
+
+<sect2 id="Resource_Converter_Invocation">
+<title>Resource Converter Invocation</title>
+<para>
+All resource-fetching routines (for example,
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>,
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>,
+and so on) call resource converters if the resource database or
+varargs list specifies a value
+that has a different representation from the desired representation or if the
+widget's default resource value representation is different from the desired
+representation.
+</para>
+
+<para>
+To invoke explicit resource conversions, use
+<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>
+or
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>.
+</para>
+<programlisting>
+typedef XtPointer XtCacheRef;
+</programlisting>
+
+<funcsynopsis id='XtCallConverter'>
+<funcprototype>
+<funcdef>Boolean <function>XtCallConverter</function></funcdef>
+ <paramdef>Display* <parameter>display</parameter></paramdef>
+ <paramdef>XtTypeConverter <parameter>converter</parameter></paramdef>
+ <paramdef>XrmValuePtr <parameter>conversion_args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+ <paramdef>XrmValuePtr <parameter>from</parameter></paramdef>
+ <paramdef>XrmValuePtr <parameter>to_in_out</parameter></paramdef>
+ <paramdef>XtCacheRef *<parameter>cache_ref_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display with which the conversion is to be associated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>converter</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the conversion procedure to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>conversion_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional conversion arguments needed
+to perform the conversion, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>conversion_args</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a descriptor for the source value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the converted value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cache_ref_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a conversion cache id.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>
+function looks up the
+specified type converter in the application context associated with
+the display and, if the converter was not registered or was registered
+with cache type
+<function>XtCacheAll</function>
+or
+<function>XtCacheByDisplay</function>,
+looks in the conversion cache to see if this conversion procedure
+has been called with the specified conversion arguments. If so, it
+checks the success status of the prior call, and if
+the conversion failed,
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>
+returns
+<function>False</function>
+immediately;
+otherwise it checks the size specified in the <emphasis remap='I'>to</emphasis> argument, and, if it is
+greater than or equal to the size stored in the cache, copies the
+information stored in the cache into the location specified by
+<emphasis remap='I'>to->addr</emphasis>, stores the cache size into <emphasis remap='I'>to->size</emphasis>, and returns
+<function>True</function>.
+If the size specified in the <emphasis remap='I'>to</emphasis> argument is smaller than the size stored
+in the cache,
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>
+copies the cache size into <emphasis remap='I'>to->size</emphasis> and returns
+<function>False</function>.
+If the converter was registered with cache type
+<function>XtCacheNone</function>
+or no value was found in the conversion cache,
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>
+calls the converter, and if it was not registered with cache type
+<function>XtCacheNone</function>,
+enters the result in the cache.
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>
+then returns what the converter returned.
+</para>
+
+<para>
+The <emphasis remap='I'>cache_ref_return</emphasis> field specifies storage allocated by the caller in which
+an opaque value will be stored. If the type converter has been
+registered with the
+<function>XtCacheRefCount</function>
+modifier and if the value returned
+in <emphasis remap='I'>cache_ref_return</emphasis> is non-NULL, then the caller should store the
+<emphasis remap='I'>cache_ref_return</emphasis> value in order to decrement the reference count when
+the converted value is no longer required. The <emphasis remap='I'>cache_ref_return</emphasis>
+argument should be
+NULL if the caller is unwilling or unable to store the
+value.
+</para>
+
+<para>
+To explicitly decrement the reference counts for resources obtained
+from
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>,
+use
+<xref linkend='XtAppReleaseCacheRefs' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppReleaseCacheRefs'>
+<funcprototype>
+<funcdef>void <function>XtAppReleaseCacheRefs</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtCacheRef *<parameter>refs</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>refs</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of cache references to be released.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppReleaseCacheRefs' xrefstyle='select: title'/>
+decrements the reference count for the
+conversion entries identified by the <emphasis remap='I'>refs</emphasis> argument.
+This argument is a
+pointer to a NULL-terminated list of
+<function>XtCacheRef</function>
+values. If any reference
+count reaches zero, the destructor, if any, will be called and
+the resource removed from the conversion cache.
+</para>
+
+<para>
+As a convenience to clients needing to explicitly decrement reference
+counts via a callback function, the Intrinsics define two callback
+procedures,
+<xref linkend='XtCallbackReleaseCacheRef' xrefstyle='select: title'/>
+and
+<xref linkend='XtCallbackReleaseCacheRefList' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCallbackReleaseCacheRef'>
+<funcprototype>
+<funcdef>void <function>XtCallbackReleaseCacheRef</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtPointer <parameter>call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object with which the resource is associated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the conversion cache entry to be released.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Is ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This callback procedure may be added to a callback list to release a
+previously returned
+<function>XtCacheRef</function>
+value. When adding the callback, the
+callback <emphasis remap='I'>client_data</emphasis> argument must be specified as the value of the
+<function>XtCacheRef</function>
+data cast to type
+<function>XtPointer</function>.
+</para>
+
+<funcsynopsis id='XtCallbackReleaseCacheRefList'>
+<funcprototype>
+<funcdef>void <function>XtCallbackReleaseCacheRefList</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtPointer <parameter>call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object with which the resources are associated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the conversion cache entries to be released.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Is ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This callback procedure may be added to a callback list to release a
+list of previously returned
+<function>XtCacheRef</function>
+values. When adding the
+callback, the callback <emphasis remap='I'>client_data</emphasis> argument must be specified as a
+pointer to a NULL-terminated list of
+<function>XtCacheRef</function>
+values.
+</para>
+
+<para>
+To lookup and call a resource converter, copy the resulting value,
+and free a cached resource when a widget is destroyed, use
+<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtConvertAndStore'>
+<funcprototype>
+<funcdef>Boolean <function>XtConvertAndStore</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>const char * <parameter>from_type</parameter></paramdef>
+ <paramdef>XrmValuePtr <parameter>from</parameter></paramdef>
+ <paramdef>const char * <parameter>to_type</parameter></paramdef>
+ <paramdef>XrmValuePtr <parameter>to_in_out</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object to use for additional arguments, if any are needed,
+and the destroy callback list. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>from</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value to be converted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the destination type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>to_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a descriptor for storage into which the converted value
+will be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>
+function looks up the type converter registered
+to convert <emphasis remap='I'>from_type</emphasis> to <emphasis remap='I'>to_type</emphasis>, computes any additional arguments
+needed, and then calls
+<xref linkend='XtCallConverter' xrefstyle='select: title'/>
+(or
+<xref linkend='XtDirectConvert' xrefstyle='select: title'/>
+if an old-style converter was registered with
+<xref linkend='XtAddConverter' xrefstyle='select: title'/>
+or
+<xref linkend='XtAppAddConverter' xrefstyle='select: title'/>;
+see Appendix C) with the <emphasis remap='I'>from</emphasis> and <emphasis remap='I'>to_in_out</emphasis> arguments. The
+<emphasis remap='I'>to_in_out</emphasis> argument specifies the size and location into which the
+converted value will be stored and is passed directly to the
+converter. If the location is specified as NULL, it will be replaced
+with a pointer to private storage and the size will be returned in the
+descriptor. The caller is expected to copy this private storage
+immediately and must not modify it in any way. If a non-NULL location
+is specified, the caller must allocate sufficient storage to hold the
+converted value and must also specify the size of that storage in the
+descriptor.
+The <emphasis remap='I'>size</emphasis> field will be modified on return to indicate the actual
+size of the converted data.
+If the conversion succeeds,
+<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>
+returns
+<function>True</function>;
+otherwise, it returns
+<function>False</function>.
+</para>
+
+<para>
+<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>
+adds
+<xref linkend='XtCallbackReleaseCacheRef' xrefstyle='select: title'/>
+to the destroyCallback list of the specified object if the conversion
+returns an
+<function>XtCacheRef</function>
+value. The resulting resource should not be referenced
+after the object has been destroyed.
+</para>
+
+<para>
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+performs processing equivalent to
+<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>
+when initializing the object instance. Because there is extra memory
+overhead required to implement reference counting, clients may
+distinguish those objects that are never destroyed before the
+application exits from those that may be destroyed and whose
+resources should be deallocated.
+</para>
+
+<para>
+To specify whether reference counting is to be enabled for the
+resources of a particular object when the object is created, the
+client can specify a value for the
+<function>Boolean</function>
+resource
+XtNinitialResourcesPersistent,
+class
+XtCInitialResourcesPersistent.
+</para>
+
+<para>
+When
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+is called, if this resource is not specified as
+<function>False</function>
+in either the arglist or the resource database, then the
+resources referenced by this object are not reference-counted, regardless of
+how the type converter may have been registered. The effective
+default value is
+<function>True</function>;
+thus clients that expect to destroy one or
+more objects and want resources deallocated must explicitly specify
+<function>False</function>
+for
+XtNinitialResourcesPersistent.
+</para>
+
+<para>
+The resources are still freed and destructors called when
+<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
+is called if the conversion was registered as
+<function>XtCacheByDisplay</function>.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Reading_and_Writing_Widget_State">
+<title>Reading and Writing Widget State</title>
+<para>
+Any resource field in a widget can be read or written by a client.
+On a write operation,
+the widget decides what changes it will actually allow and updates all
+derived fields appropriately.
+</para>
+<sect2 id="Obtaining_Widget_State">
+<title>Obtaining Widget State</title>
+<para>
+To retrieve the current values of resources associated with a
+widget instance, use
+<xref linkend='XtGetValues' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetValues'>
+<funcprototype>
+<funcdef>void <function>XtGetValues</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object whose resource values are to be returned. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list of name/address pairs that contain the
+resource names and the addresses into which the resource values are to
+be stored.
+The resource names are widget-dependent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+function starts with the resources specified for the Object class
+and proceeds down the subclass chain to the class of the object.
+The <emphasis remap='I'>value</emphasis> field of a passed argument list must contain the
+address into which to copy the contents of the corresponding
+object instance field. If the field is a pointer type, the lifetime
+of the pointed-to data is defined by the object class. For the
+Intrinsics-defined resources, the following lifetimes apply:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Not valid following any operation that modifies the resource:
+ </para>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+XtNchildren resource of composite widgets.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+All resources of representation type XtRCallback.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+Remain valid at least until the widget is destroyed:
+ </para>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+XtNaccelerators, XtNtranslations.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+Remain valid until the Display is closed:
+ </para>
+ <itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+XtNscreen.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+</itemizedlist>
+<para>
+It is the caller's responsibility
+to allocate and deallocate storage for the copied data
+according to the size of the
+resource representation type used within the object.
+</para>
+
+<para>
+If the class of the object's parent is a subclass of
+<function>constraintWidgetClass</function>,
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+then fetches the values for any constraint resources requested.
+It starts with the constraint resources specified for
+<function>constraintWidgetClass</function>
+and proceeds down the subclass chain to the parent's constraint resources.
+If the argument list contains a resource name that is not found in any of the
+resource lists searched,
+the value at the corresponding address is not modified.
+If any get_values_hook procedures in the
+object's class or superclass records are non-NULL,
+they are called in superclass-to-subclass order after
+all the resource values have been fetched by
+<xref linkend='XtGetValues' xrefstyle='select: title'/>.
+Finally, if the object's parent is a
+subclass of
+<function>constraintWidgetClass</function>,
+and if any of the parent's class or
+superclass records have declared
+<function>ConstraintClassExtension</function>
+records in
+the Constraint class part <emphasis remap='I'>extension</emphasis> field with a record type of
+<emphasis role='strong'>NULLQUARK</emphasis>,
+and if the <emphasis remap='I'>get_values_hook</emphasis> field in the extension record is non-NULL,
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+calls the get_values_hook procedures in superclass-to-subclass order.
+This permits a Constraint parent to provide
+nonresource data via
+<xref linkend='XtGetValues' xrefstyle='select: title'/>.
+</para>
+
+<para>
+Get_values_hook procedures may modify the data stored at the
+location addressed by the <emphasis remap='I'>value</emphasis> field, including (but not
+limited to) making a copy of data whose resource representation is a
+pointer. None of the Intrinsics-defined object classes copy
+data in this manner. Any operation that modifies the queried
+object resource may invalidate the pointed-to data.
+</para>
+
+<para>
+To retrieve the current values of resources associated with a widget
+instance using varargs lists, use
+<xref linkend='XtVaGetValues' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaGetValues'>
+<funcprototype>
+<funcdef>void <function>XtVaGetValues</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef><parameter>...</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object whose resource values are to be returned. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list for the resources to
+be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtVaGetValues' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis>
+and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as described in
+Section 2.5.1. All value entries in the list must specify pointers to
+storage allocated by the caller to which the resource value will be
+copied. It is the caller's responsibility to ensure that sufficient
+storage is allocated. If
+<function>XtVaTypedArg</function>
+is specified, the <emphasis remap='I'>type</emphasis> argument
+specifies the representation desired by the caller and <emphasis remap='I'>the</emphasis> size argument
+specifies the number of bytes allocated to store the result of the
+conversion. If the size is insufficient, a warning message is issued
+and the list entry is skipped.
+</para>
+<sect3 id="Widget_Subpart_Resource_Data_The_get_values_hook_Procedure">
+<title>Widget Subpart Resource Data: The get_values_hook Procedure</title>
+<para>
+Widgets that have subparts can return resource values from them through
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+by supplying a get_values_hook procedure.
+The get_values_hook procedure pointer is of type
+<xref linkend='XtArgsProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='_XtArgsProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtArgsProc)</function></funcdef>
+
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget whose subpart resource values are to be retrieved.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list that was passed to
+<xref linkend='XtGetValues' xrefstyle='select: title'/>
+or the transformed varargs list passed to
+<xref linkend='XtVaGetValues' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The widget with subpart resources should call
+<xref linkend='XtGetSubvalues' xrefstyle='select: title'/>
+in the get_values_hook procedure
+and pass in its subresource list and the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters.
+</para>
+</sect3>
+<sect3 id="Widget_Subpart_State">
+<title>Widget Subpart State</title>
+<para>
+To retrieve the current values of subpart resource data associated with a
+widget instance, use
+<xref linkend='XtGetSubvalues' xrefstyle='select: title'/>.
+For a discussion of subpart resources,
+see <xref linkend='Subresources' />.
+</para>
+
+<funcsynopsis id='XtGetSubvalues'>
+<funcprototype>
+<funcdef>void <function>XtGetSubvalues</function></funcdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>XtResourceList <parameter>resources</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_resources</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>base</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the base address of the subpart data structure for which the
+resources should be retrieved.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the subpart resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list of name/address pairs that contain the
+resource names and the addresses into which the resource values are to
+be stored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetSubvalues' xrefstyle='select: title'/>
+function obtains resource values from the structure identified by <emphasis remap='I'>base</emphasis>.
+The <emphasis remap='I'>value</emphasis> field in each argument entry must contain the address into
+which to store the corresponding resource value. It is the caller's
+responsibility to allocate and deallocate this storage according to
+the size of the resource representation type used within the subpart.
+If the argument list contains a resource name that is not found in the
+resource list, the value at the corresponding address is not modified.
+</para>
+
+<para>
+To retrieve the current values of subpart resources associated with
+a widget instance using varargs lists, use
+<xref linkend='XtVaGetSubvalues' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaGetSubvalues'>
+<funcprototype>
+<funcdef>void <function>XtVaGetSubvalues</function></funcdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>XtResourceList <parameter>resources</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_resources</parameter></paramdef>
+ <paramdef> <parameter>...</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>base</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the base address of the subpart data structure for which the
+resources should be retrieved.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the subpart resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies a variable argument list of name/address pairs that
+contain the resource names and the addresses into which the resource
+values are to be stored.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtVaGetSubvalues' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtGetSubvalues' xrefstyle='select: title'/>
+with the
+<emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as described
+in Section 2.5.1.
+<function>XtVaTypedArg</function>
+is not supported for
+<xref linkend='XtVaGetSubvalues' xrefstyle='select: title'/>.
+If
+<function>XtVaTypedArg</function>
+is specified in the list, a warning message is issued
+and the entry is then ignored.
+</para>
+</sect3>
+</sect2>
+
+<sect2 id="Setting_Widget_State">
+<title>Setting Widget State</title>
+<para>
+To modify the current values of resources associated with a widget
+instance, use
+<xref linkend='XtSetValues' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetValues'>
+<funcprototype>
+<funcdef>void <function>XtSetValues</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object whose resources are to be modified. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list of name/value pairs that contain the
+resources to be modified and their new values.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+function starts with the resources specified for the
+Object
+class fields and proceeds down the subclass chain to the object.
+At each stage, it replaces the <emphasis remap='I'>object</emphasis> resource fields with any values
+specified in the argument list.
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+then calls the set_values procedures for the object in superclass-to-subclass
+order.
+If the object has any non-NULL <emphasis remap='I'>set_values_hook</emphasis> fields,
+these are called immediately after the
+corresponding set_values procedure.
+This procedure permits subclasses to set subpart data via
+<xref linkend='XtSetValues' xrefstyle='select: title'/>.
+</para>
+
+<para>
+If the class of the object's parent is a subclass of
+<function>constraintWidgetClass</function>,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+also updates the object's constraints.
+It starts with the constraint resources specified for
+<function>constraintWidgetClass</function>
+and proceeds down the subclass chain to the parent's class.
+At each stage, it replaces the constraint resource fields with any
+values specified in the argument list.
+It then calls the constraint set_values procedures from
+<function>constraintWidgetClass</function>
+down to the parent's class.
+The constraint set_values procedures are called with widget arguments,
+as for all set_values procedures, not just the constraint records,
+so that they can make adjustments to the desired values based
+on full information about the widget. Any arguments specified that
+do not match a resource list entry are silently ignored.
+</para>
+
+<para>
+If the object is of a subclass of
+RectObj,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+determines if a geometry request is needed by comparing the old object to
+the new object.
+If any geometry changes are required,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+restores the original geometry and makes the request on behalf of the widget.
+If the geometry manager returns
+<function>XtGeometryYes</function>,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+calls the object's resize procedure.
+If the geometry manager returns
+<function>XtGeometryDone</function>,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+continues, as the object's resize procedure should have been called
+by the geometry manager.
+If the geometry manager returns
+<function>XtGeometryNo</function>,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+ignores the geometry request and continues.
+If the geometry manager returns
+<function>XtGeometryAlmost</function>,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+calls the set_values_almost procedure,
+which determines what should be done.
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+then repeats this process,
+deciding once more whether the geometry manager should be called.
+</para>
+
+<para>
+Finally, if any of the set_values procedures returned
+<function>True</function>,
+and the widget is realized,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+causes the widget's expose procedure to be invoked by calling
+<function>XClearArea</function>
+on the widget's window.
+</para>
+
+<para>
+To modify the current values of resources associated with a widget
+instance using varargs lists, use
+<xref linkend='XtVaSetValues' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaSetValues'>
+<funcprototype>
+<funcdef>void <function>XtVaSetValues</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef> <parameter>...</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object whose resources are to be modified. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list of name/value pairs that
+contain the resources to be modified and their new values.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtVaSetValues' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as
+described in Section 2.5.1.
+</para>
+<sect3 id="Widget_State_The_set_values_Procedure">
+<title>Widget State: The set_values Procedure</title>
+<para>
+The set_values procedure pointer in a widget class is of type
+<xref linkend='XtSetValuesFunc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetValuesFunc'>
+<funcprototype>
+<funcdef>typedef Boolean <function>(*XtSetValuesFunc)</function></funcdef>
+
+ <paramdef>Widget <parameter>current</parameter></paramdef>
+ <paramdef>Widget <parameter>request</parameter></paramdef>
+ <paramdef>Widget <parameter>new</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>current</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a copy of the widget as it was before the
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a copy of the widget with all values changed as asked for by the
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+call before any class set_values procedures have been called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>new</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget with the new values that are actually allowed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list passed to
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+or the transformed argument list passed to
+<xref linkend='XtVaSetValues' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The set_values procedure should recompute any field
+derived from resources that are changed
+(for example, many GCs depend on foreground and background pixels).
+If no recomputation is necessary, and if none of the resources specific to a
+subclass require the window to be redisplayed when their values are changed,
+you can specify NULL for the <emphasis remap='I'>set_values</emphasis> field in the class record.
+</para>
+
+<para>
+Like the initialize procedure,
+set_values mostly deals only with the fields defined in the subclass,
+but it has to resolve conflicts with its superclass,
+especially conflicts over width and height.
+</para>
+
+<para>
+Sometimes a subclass may want to overwrite values filled in by its
+superclass.
+In particular, size calculations of a superclass are often
+incorrect for a subclass, and, in this case,
+the subclass must modify or recalculate fields declared
+and computed by its superclass.
+</para>
+
+<para>
+As an example,
+a subclass can visually surround its superclass display.
+In this case, the width and height calculated by the superclass set_values
+procedure are too small and need to be incremented by the size of the surround.
+The subclass needs to know if its superclass's size was calculated by the
+superclass or was specified explicitly.
+All widgets must place themselves into whatever size is explicitly given,
+but they should compute a reasonable size if no size is requested.
+How does a subclass know the difference between a specified size
+and a size computed by a superclass?
+</para>
+
+<para>
+The <emphasis remap='I'>request</emphasis> and <emphasis remap='I'>new</emphasis> parameters provide the necessary information.
+The <emphasis remap='I'>request</emphasis> widget is a copy of the widget, updated as originally requested.
+The <emphasis remap='I'>new</emphasis> widget starts with the values in the request,
+but it has additionally been updated by all superclass set_values
+procedures called so far.
+A subclass set_values procedure can compare these two to resolve
+any potential conflicts.
+The set_values procedure need not refer to the <emphasis remap='I'>request</emphasis> widget
+unless it must resolve conflicts between the <emphasis remap='I'>current</emphasis> and <emphasis remap='I'>new</emphasis> widgets.
+Any changes the widget needs to make, including geometry changes,
+should be made in the <emphasis remap='I'>new</emphasis> widget.
+</para>
+
+<para>
+In the above example,
+the subclass with the visual surround can see
+if the <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> in the <emphasis remap='I'>request</emphasis> widget are zero.
+If so,
+it adds its surround size to the <emphasis remap='I'>width</emphasis> and
+<emphasis remap='I'>height</emphasis> fields in the <emphasis remap='I'>new</emphasis> widget.
+If not, it must make do with the size originally specified.
+In this case, zero is a special value defined by the class to permit
+the application to invoke this behavior.
+</para>
+
+<para>
+The <emphasis remap='I'>new</emphasis> widget is the actual widget instance record.
+Therefore,
+the set_values procedure should do all its work on the <emphasis remap='I'>new</emphasis> widget;
+the <emphasis remap='I'>request</emphasis> widget should never be modified.
+If the set_values procedure needs to call any routines that operate on
+a widget, it should specify <emphasis remap='I'>new</emphasis> as the widget instance.
+</para>
+
+<para>
+Before calling the set_values procedures, the Intrinsics modify the
+resources of the <emphasis remap='I'>request</emphasis> widget according to the contents of the arglist;
+if the widget names all its resources in the class resource list, it is
+never necessary to examine the contents of <emphasis remap='I'>args</emphasis>.
+</para>
+
+<para>
+Finally, the set_values procedure must return a Boolean that indicates whether
+the widget needs to be redisplayed.
+Note that a change in the geometry fields alone does not require
+the set_values procedure to return
+<function>True</function>;
+the X server will eventually generate an
+<function>Expose</function>
+event, if necessary.
+After calling all the set_values procedures,
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+forces a redisplay by calling
+<function>XClearArea</function>
+if any of the set_values procedures returned
+<function>True</function>.
+Therefore, a set_values procedure should not try to do its own redisplaying.
+</para>
+
+<para>
+Set_values procedures should not do any work in response to changes in
+geometry because
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+eventually will perform a geometry request, and that request might be denied.
+If the widget actually changes size in response to a
+call to
+<xref linkend='XtSetValues' xrefstyle='select: title'/>,
+its resize procedure is called.
+Widgets should do any geometry-related work in their resize procedure.
+</para>
+
+<para>
+Note that it is permissible to call
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+before a widget is realized.
+Therefore, the set_values procedure must not assume that the widget is realized.
+</para>
+</sect3>
+<sect3 id="Widget_State_The_set_values_almost_Procedure">
+<title>Widget State: The set_values_almost Procedure</title>
+<para>
+The set_values_almost procedure pointer in the widget class record is of type
+<xref linkend='XtAlmostProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAlmostProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtAlmostProc)</function></funcdef>
+
+ <paramdef>Widget <parameter>old</parameter></paramdef>
+ <paramdef>Widget <parameter>new</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>request</parameter></paramdef>
+ <paramdef>XtWidgetGeometry *<parameter>reply</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>old</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a copy of the object as it was before the
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+call.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>new</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the object instance record.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the original geometry request that was sent to the geometry
+manager that caused
+<function>XtGeometryAlmost</function>
+to be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>reply</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the compromise geometry that was returned by the geometry
+manager with
+<function>XtGeometryAlmost</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Most classes inherit the set_values_almost procedure from their superclass by
+specifying
+<function>XtInheritSetValuesAlmost</function>
+in the class initialization.
+The
+set_values_almost procedure in
+<function>rectObjClass</function>
+accepts the compromise suggested.
+</para>
+
+<para>
+The set_values_almost procedure is called when a client tries to set a widget's
+geometry by means of a call to
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+and the geometry manager cannot
+satisfy the request but instead returns
+<function>XtGeometryNo</function>
+or
+<function>XtGeometryAlmost</function>
+and a compromise geometry.
+The <emphasis remap='I'>new</emphasis> object is the actual instance record. The <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>,
+<emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>,
+and <emphasis remap='I'>border_width</emphasis> fields contain the original values as they were
+before the
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+call, and all other fields contain the new
+values. The <emphasis remap='I'>request</emphasis> parameter contains the new geometry request that
+was made to the parent. The <emphasis remap='I'>reply</emphasis> parameter contains
+<emphasis remap='I'>reply->request_mode</emphasis> equal to zero if the parent returned
+<function>XtGeometryNo</function>
+and contains the parent's compromise geometry otherwise. The
+set_values_almost procedure takes the original geometry and the
+compromise geometry and determines if the compromise is
+acceptable or whether
+to try a different compromise.
+It returns its results in the <emphasis remap='I'>request</emphasis> parameter,
+which is then sent back to the geometry manager for another try.
+To accept the compromise, the procedure must copy the contents
+of the <emphasis remap='I'>reply</emphasis> geometry into the <emphasis remap='I'>request</emphasis> geometry; to attempt an
+alternative geometry, the procedure may modify any part of the <emphasis remap='I'>request</emphasis>
+argument; to terminate the geometry negotiation and retain the
+original geometry, the procedure must set <emphasis remap='I'>request->request_mode</emphasis> to
+zero. The geometry fields of the <emphasis remap='I'>old</emphasis> and <emphasis remap='I'>new</emphasis> instances must not be modified
+directly.
+</para>
+</sect3>
+<sect3 id="Widget_State_The_ConstraintClassPart_set_values_Procedure">
+<title>Widget State: The ConstraintClassPart set_values Procedure</title>
+<para>
+The constraint set_values procedure pointer is of type
+<xref linkend='XtSetValuesFunc' xrefstyle='select: title'/>.
+The values passed to the parent's constraint set_values procedure
+are the same as those passed to the child's class
+set_values procedure.
+A class can specify NULL for the <emphasis remap='I'>set_values</emphasis> field of the
+<function>ConstraintPart</function>
+if it need not compute anything.
+</para>
+
+<para>
+The constraint set_values procedure should recompute any constraint fields
+derived from constraint resources that are changed.
+Furthermore, it may modify other widget fields as appropriate.
+For example, if a constraint for the maximum height of a widget is changed
+to a value smaller than the widget's current height,
+the constraint set_values procedure may reset the <emphasis remap='I'>height</emphasis> field in the
+widget.
+</para>
+</sect3>
+<sect3 id='Widget_Subpart_State_2'>
+<title>Widget Subpart State</title>
+<para>
+To set the current values of subpart resources associated with a
+widget instance, use
+<xref linkend='XtSetSubvalues' xrefstyle='select: title'/>.
+For a discussion of subpart resources,
+see <xref linkend='Subresources' />.
+</para>
+
+<funcsynopsis id='XtSetSubvalues'>
+<funcprototype>
+<funcdef>void <function>XtSetSubvalues</function></funcdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>XtResourceList <parameter>resources</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_resources</parameter></paramdef>
+ <paramdef>ArgList <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>base</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the base address of the subpart data structure into which the
+resources should be written.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the subpart resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list of name/value pairs that contain the
+resources to be modified and their new values.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtSetSubvalues' xrefstyle='select: title'/>
+function updates the resource fields of the structure identified by
+<emphasis remap='I'>base</emphasis>. Any specified arguments that do not match an entry in the
+resource list are silently ignored.
+</para>
+
+<para>
+To set the current values of subpart resources associated with
+a widget instance using varargs lists, use
+<xref linkend='XtVaSetSubvalues' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtVaSetSubvalues'>
+<funcprototype>
+<funcdef>void <function>XtVaSetSubvalues</function></funcdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>XtResourceList <parameter>resources</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_resources</parameter></paramdef>
+ <paramdef>...</paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>base</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the base address of the subpart data structure into which the
+resources should be written.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the subpart resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_resources</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the resource list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ ...
+ </term>
+ <listitem>
+ <para>
+Specifies the variable argument list of name/value pairs that
+contain the resources to be modified and their new values.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtVaSetSubvalues' xrefstyle='select: title'/>
+is identical in function to
+<xref linkend='XtSetSubvalues' xrefstyle='select: title'/>
+with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as
+described in Section 2.5.1.
+<function>XtVaTypedArg</function>
+is not supported for
+<xref linkend='XtVaSetSubvalues' xrefstyle='select: title'/>.
+If an entry containing
+<function>XtVaTypedArg</function>
+is specified in the list, a warning message is issued
+and the entry is ignored.
+</para>
+</sect3>
+
+<sect3 id='Widget_Subpart_Resource_Data_The_set_values_hook_Procedure'>
+<title>Widget Subpart Resource Data: The set_values_hook Procedure</title>
+<note><para>
+The set_values_hook procedure is obsolete, as the same information
+is now available to the set_values procedure. The procedure has been
+retained for those widgets that used it in versions prior to Release 4.
+</para>
+</note>
+<para>
+Widgets that have a subpart can set the subpart resource values through
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+by supplying a set_values_hook procedure.
+The set_values_hook procedure pointer in a widget class is of type
+<xref linkend='XtArgsFunc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtArgsFunc'>
+<funcprototype>
+<funcdef>typedef Boolean <function>(*XtArgsFunc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Arglist <parameter>args</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_args</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget whose subpart resource values are to be changed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument list that was passed to
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+or the transformed varargs list passed to
+<xref linkend='XtVaSetValues' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_args</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The widget with subpart resources may call
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+from the set_values_hook procedure
+and pass in its subresource list and the
+<emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters.
+</para>
+</sect3>
+</sect2>
+</sect1>
+</chapter>
Index: create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH10.xml
===================================================================
--- create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH10.xml (nonexistent)
+++ create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH10.xml (revision 5)
@@ -0,0 +1,2215 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<chapter id='Translation_Management'>
+<title>Translation Management</title>
+<para>
+Except under unusual circumstances,
+widgets do not hardwire the mapping of user events into widget behavior
+by using the event manager.
+Instead, they provide a default mapping of events into behavior
+that you can override.
+</para>
+
+<para>
+The translation manager provides an interface to specify and manage the
+mapping of X event sequences into widget-supplied functionality,
+for example, calling procedure <emphasis remap='I'>Abc</emphasis> when the <emphasis remap='I'>y</emphasis> key
+is pressed.
+</para>
+
+<para>
+The translation manager uses two kinds of tables to perform translations:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+The action tables, which are in the widget class structure,
+specify the mapping of externally available procedure name strings
+to the corresponding procedure implemented by the widget class.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A translation table, which is in the widget class structure,
+specifies the mapping of event sequences to procedure name strings.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+You can override the translation table in the class structure
+for a specific widget instance by supplying a different translation table
+for the widget instance. The resources
+XtNtranslations and XtNbaseTranslations are used to modify the class
+default translation table; see <xref linkend='Translation_Table_Management' />.
+</para>
+<sect1 id="Action_Tables">
+<title>Action Tables</title>
+<para>
+All widget class records contain an action table,
+an array of
+<function>XtActionsRec</function>
+entries.
+In addition,
+an application can register its own action tables with the translation manager
+so that the translation tables it provides to widget instances can access
+application functionality directly.
+The translation action procedure pointer is of type
+<xref linkend='XtActionProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtActionProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtActionProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XEvent *<parameter>event</parameter></paramdef>
+ <paramdef>String *<parameter>params</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_params</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that caused the action to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event that caused the action to be called.
+If the action is called after a sequence of events,
+then the last event in the sequence is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the list of strings that were specified
+in the translation table as arguments to the action, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<programlisting>
+typedef struct _XtActionsRec {
+ String string;
+ XtActionProc proc;
+} XtActionsRec, *XtActionList;
+</programlisting>
+<para>
+The <emphasis remap='I'>string</emphasis> field is the name used in translation tables to access
+the procedure.
+The <emphasis remap='I'>proc</emphasis> field is a pointer to a procedure that implements
+the functionality.
+</para>
+
+<para>
+When the action list is specified as the
+<function>CoreClassPart</function>
+<emphasis remap='I'>actions</emphasis> field, the string pointed to by <emphasis remap='I'>string</emphasis> must be
+permanently allocated prior to or during the execution of the class
+initialization procedure and must not be subsequently deallocated.
+</para>
+
+<para>
+Action procedures should not assume that the widget in which they
+are invoked is realized; an accelerator specification can cause
+an action procedure to be called for a widget that does not yet
+have a window. Widget writers should also note which of a widget's
+callback lists are invoked from action procedures and warn clients
+not to assume the widget is realized in those callbacks.
+</para>
+
+<para>
+For example, a Pushbutton widget has procedures to take the following actions:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Set the button to indicate it is activated.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Unset the button back to its normal mode.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Highlight the button borders.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Unhighlight the button borders.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Notify any callbacks that the button has been activated.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The action table for the Pushbutton widget class makes these functions
+available to translation tables written for Pushbutton or any subclass.
+The string entry is the name used in translation tables.
+The procedure entry (usually spelled identically to the string)
+is the name of the C procedure that implements that function:
+</para>
+<programlisting>
+XtActionsRec actionTable[] = {
+ {"Set", Set},
+ {"Unset", Unset},
+ {"Highlight", Highlight},
+ {"Unhighlight", Unhighlight}
+ {"Notify", Notify},
+};
+</programlisting>
+<para>
+The Intrinsics reserve all action names and parameters starting with
+the characters “Xt” for future standard enhancements. Users,
+applications, and widgets should not declare action names or pass
+parameters starting with these characters except to invoke specified
+built-in Intrinsics functions.
+</para>
+<sect2 id="Action_Table_Registration">
+<title>Action Table Registration</title>
+<para>
+The <emphasis remap='I'>actions</emphasis> and <emphasis remap='I'>num_actions</emphasis> fields of
+<function>CoreClassPart</function>
+specify the actions implemented by a widget class. These are
+automatically registered with the Intrinsics when the class is initialized
+and must be allocated in writable storage prior to Core class_part
+initialization, and never deallocated. To save memory and optimize
+access, the Intrinsics may overwrite the storage in order to compile the
+list into an internal representation.
+</para>
+
+<para>
+To declare an action table within an application
+and register it with the translation manager, use
+<xref linkend='XtAppAddActions' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppAddActions'>
+<funcprototype>
+<funcdef>void <function>XtAppAddActions</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtActionList <parameter>actions</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_actions</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>actions</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the action table to register.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_actions</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in this action table.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If more than one action is registered with the same name,
+the most recently registered action is used.
+If duplicate actions exist in an action table,
+the first is used.
+The Intrinsics register an action table containing
+<xref linkend='XtMenuPopup' xrefstyle='select: title'/>
+and
+<xref linkend='XtMenuPopdown' xrefstyle='select: title'/>
+as part of
+<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>.
+</para>
+</sect2>
+
+<sect2 id="Action_Names_to_Procedure_Translations">
+<title>Action Names to Procedure Translations</title>
+<para>
+The translation manager uses a simple algorithm to resolve the name of
+a procedure specified in a translation table into the
+actual procedure specified
+in an action table.
+When the widget
+is realized, the translation manager
+performs a search for the name in the following tables, in order:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+The widget's class and all superclass action tables, in subclass-to-superclass
+order.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The parent's class and all superclass action tables, in subclass-to-superclass
+order, then on up the ancestor tree.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The action tables registered with
+<xref linkend='XtAppAddActions' xrefstyle='select: title'/>
+and
+<xref linkend='XtAddActions' xrefstyle='select: title'/>
+from the most recently added table to the oldest table.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+As soon as it finds a name,
+the translation manager stops the search.
+If it cannot find a name,
+the translation manager generates a warning message.
+</para>
+</sect2>
+
+<sect2 id="Action_Hook_Registration">
+<title>Action Hook Registration</title>
+<para>
+An application can specify a procedure that will be called just before
+every action routine is dispatched by the translation manager. To do
+so, the application supplies a procedure pointer of type
+<xref linkend='XtActionHookProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtActionHookProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtActionHookProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>String <parameter>action_name</parameter></paramdef>
+ <paramdef>XEvent* <parameter>event</parameter></paramdef>
+ <paramdef>String* <parameter>params</parameter></paramdef>
+ <paramdef>Cardinal* <parameter>num_params</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget whose action is about to be dispatched.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application-specific closure that was passed to
+<function>XtAppAddActionHook.</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>action_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the action to be dispatched.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event argument that will be passed to the action routine.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the action parameters that will be passed to the action routine.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Action hooks should not modify any of the data pointed to by the
+arguments other than the <emphasis remap='I'>client_data</emphasis> argument.
+</para>
+
+<para>
+To add an action hook, use
+<xref linkend='XtAppAddActionHook' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppAddActionHook'>
+<funcprototype>
+<funcdef>XtActionHookId <function>XtAppAddActionHook</function></funcdef>
+ <paramdef>XtAppContext <parameter>app</parameter></paramdef>
+ <paramdef>XtActionHookProc <parameter>proc</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the action hook procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies application-specific data to be passed to the action hook.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppAddActionHook' xrefstyle='select: title'/>
+adds the specified procedure to the front of a list
+maintained in the application context. In the future, when an action
+routine is about to be invoked for any widget in this application
+context, either through the translation manager or via
+<xref linkend='XtCallActionProc' xrefstyle='select: title'/>,
+the action hook procedures will be called in reverse
+order of registration just prior to invoking the action routine.
+</para>
+
+<para>
+Action hook procedures are removed automatically and the
+<function>XtActionHookId is</function>
+destroyed when the application context in which
+they were added is destroyed.
+</para>
+
+<para>
+To remove an action hook procedure without destroying the application
+context, use
+<xref linkend='XtRemoveActionHook' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRemoveActionHook'>
+<funcprototype>
+<funcdef>void <function>XtRemoveActionHook</function></funcdef>
+ <paramdef>XtActionHookId <parameter>id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the action hook id returned by
+<xref linkend='XtAppAddActionHook' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtRemoveActionHook' xrefstyle='select: title'/>
+removes the specified action hook procedure from
+the list in which it was registered.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Translation_Tables">
+<title>Translation Tables</title>
+<para>
+All widget instance records contain a translation table,
+which is a resource with a default value specified elsewhere in the
+class record.
+A translation table specifies what action procedures are invoked for
+an event or a sequence of events.
+A translation table
+is a string containing a list of translations from an event sequence
+into one or more action procedure calls.
+The translations are separated from one another by newline characters
+(ASCII LF).
+The complete syntax of translation tables is specified in Appendix B.
+</para>
+
+<para>
+As an example, the default behavior of Pushbutton is
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Highlight on enter window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Unhighlight on exit window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Invert on left button down.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Call callbacks and reinvert on left button up.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The following illustrates Pushbutton's default translation table:
+</para>
+<programlisting>
+static String defaultTranslations =
+ "<EnterWindow>: Highlight()\n\
+ <LeaveWindow>: Unhighlight()\n\
+ <Btn1Down>: Set()\n\
+ <Btn1Up>: Notify() Unset()";
+</programlisting>
+<para>
+The <emphasis remap='I'>tm_table</emphasis> field of the
+<function>CoreClassPart</function>
+should be filled in at class initialization time with
+the string containing the class's default translations.
+If a class wants to inherit its superclass's translations,
+it can store the special value
+<function>XtInheritTranslations</function>
+into <emphasis remap='I'>tm_table</emphasis>.
+In Core's class part initialization procedure,
+the Intrinsics compile this translation table into an efficient internal form.
+Then, at widget creation time,
+this default translation table is
+combined with the XtNtranslations
+and XtNbaseTranslations resources; see
+<xref linkend='Translation_Table_Management' />.
+</para>
+
+<para>
+The resource conversion mechanism automatically compiles
+string translation tables that are specified in the resource database.
+If a client uses translation tables that are not retrieved via a
+resource conversion,
+it must compile them itself using
+<xref linkend='XtParseTranslationTable' xrefstyle='select: title'/>.
+</para>
+
+<para>
+The Intrinsics use the compiled form of the translation table to register the
+necessary events with the event manager.
+Widgets need do nothing other than specify the action and translation tables
+for events to be processed by the translation manager.
+</para>
+<sect2 id="Event_Sequences">
+<title>Event Sequences</title>
+<para>
+An event sequence is a comma-separated list of X event descriptions
+that describes a specific sequence of X events to map to a set of
+program actions.
+Each X event description consists of three parts:
+The X event type, a prefix consisting of the X modifier bits, and
+an event-specific suffix.
+</para>
+
+<para>
+Various abbreviations are supported to make translation tables easier
+to read. The events must match incoming events in left-to-right order
+to trigger the action sequence.
+</para>
+</sect2>
+
+<sect2 id="Action_Sequences">
+<title>Action Sequences</title>
+<para>
+Action sequences specify what program or widget actions to take in response to
+incoming X events. An action sequence consists of space-separated
+action procedure call specifications.
+Each action procedure call consists of the name of an action procedure and a
+parenthesized list of zero or more comma-separated
+string parameters to pass to that procedure.
+The actions are invoked in left-to-right order as specified in the
+action sequence.
+</para>
+</sect2>
+
+<sect2 id="Multi_Click_Time">
+<title>Multi-Click Time</title>
+<para>
+Translation table entries may specify actions that are taken when two
+or more identical events occur consecutively within a short time
+interval, called the multi-click time. The multi-click time value may
+be specified as an application resource with name “multiClickTime” and
+class “MultiClickTime” and may also be modified dynamically by the
+application. The multi-click time is unique for each Display value and
+is retrieved from the resource database by
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
+If no value is specified, the initial value is 200 milliseconds.
+</para>
+
+<para>
+To set the multi-click time dynamically, use
+<xref linkend='XtSetMultiClickTime' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetMultiClickTime'>
+<funcprototype>
+<funcdef>void <function>XtSetMultiClickTime</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>int <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display connection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the multi-click time in milliseconds.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtSetMultiClickTime' xrefstyle='select: title'/>
+sets the time interval used by the translation
+manager to determine when multiple events are interpreted as a
+repeated event. When a repeat count is specified in a translation
+entry, the interval between the timestamps in each pair of repeated
+events (e.g., between two
+<function>ButtonPress</function>
+events) must be less than the
+multi-click time in order for the translation actions to be taken.
+</para>
+
+<para>
+To read the multi-click time, use
+<xref linkend='XtGetMultiClickTime' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetMultiClickTime'>
+<funcprototype>
+<funcdef>int <function>XtGetMultiClickTime</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display connection.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGetMultiClickTime' xrefstyle='select: title'/>
+returns the time in milliseconds that the
+translation manager uses to determine if multiple events are to be
+interpreted as a repeated event for purposes of matching a translation
+entry containing a repeat count.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Translation_Table_Management">
+<title>Translation Table Management</title>
+<para>
+Sometimes an application needs to merge
+its own translations with a widget's translations.
+For example, a window manager provides functions to move a window.
+The window manager wishes to bind this operation to a specific
+pointer button in the title bar without the possibility of user
+override and bind it to other buttons that may be overridden by the user.
+</para>
+
+<para>
+To accomplish this,
+the window manager should first create the title bar
+and then should merge the two translation tables into
+the title bar's translations.
+One translation table contains the translations that the window manager
+wants only if the user has not specified a translation for a particular event
+or event sequence (i.e., those that may be overridden).
+The other translation table contains the translations that the
+window manager wants regardless of what the user has specified.
+</para>
+
+<para>
+Three Intrinsics functions support this merging:
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>XtParseTranslationTable</emphasis>
+ </term>
+ <listitem>
+ <para>Compiles a translation table.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>XtAugmentTranslations</emphasis>
+ </term>
+ <listitem>
+ <para>Merges a compiled translation table into a widget's
+ compiled translation table, ignoring any new translations that
+ conflict with existing translations.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>XtOverrideTranslations</emphasis>
+ </term>
+ <listitem>
+ <para>Merges a compiled translation table into a widget's
+ compiled translation table, replacing any existing translations that
+ conflict with new translations.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+To compile a translation table, use
+<xref linkend='XtParseTranslationTable' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtParseTranslationTable'>
+<funcprototype>
+<funcdef>XtTranslations <function>XtParseTranslationTable</function></funcdef>
+ <paramdef>const char * <parameter>table</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>table</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the translation table to compile.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtParseTranslationTable' xrefstyle='select: title'/>
+function compiles the translation table, provided in the format given
+in Appendix B, into an opaque internal representation
+of type
+<function>XtTranslations</function>.
+Note that if an empty translation table is required for any purpose,
+one can be obtained by calling
+<xref linkend='XtParseTranslationTable' xrefstyle='select: title'/>
+and passing an empty string.
+</para>
+
+<para>
+To merge additional translations into an existing translation table, use
+<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAugmentTranslations'>
+<funcprototype>
+<funcdef>void <function>XtAugmentTranslations</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtTranslations <parameter>translations</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget into which the new translations are to be merged. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>translations</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the compiled translation table to merge in.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>
+function merges the new translations into the existing widget
+translations, ignoring any
+<function>#replace</function>,
+<function>#augment</function>,
+or
+<function>#override</function>
+directive that may have been specified
+in the translation string. The translation table specified by
+<emphasis remap='I'>translations</emphasis> is not altered by this process.
+<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>
+logically appends the string representation of the new translations to
+the string representation of the widget's current translations and reparses
+the result with no warning messages about duplicate left-hand sides, then
+stores the result back into the widget instance; i.e.,
+if the new translations contain an event or event sequence that
+already exists in the widget's translations,
+the new translation is ignored.
+</para>
+
+<para>
+To overwrite existing translations with new translations, use
+<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtOverrideTranslations'>
+<funcprototype>
+<funcdef>void <function>XtOverrideTranslations</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtTranslations <parameter>translations</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget into which the new translations are to be merged. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>translations</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the compiled translation table to merge in.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>
+function merges the new translations into the existing widget
+translations, ignoring any
+<function>#replace</function>,
+<function>#augment</function>,
+or
+<function>#override</function>
+directive that may have been
+specified in the translation string. The translation table
+specified by <emphasis remap='I'>translations</emphasis> is not altered by this process.
+<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>
+logically appends the string representation of the widget's current
+translations to the string representation of the new translations and
+reparses the result with no warning messages about duplicate left-hand
+sides, then stores the result back into the widget instance; i.e.,
+if the new translations contain an event or event sequence that
+already exists in the widget's translations,
+the new translation overrides the widget's translation.
+</para>
+
+<para>
+To replace a widget's translations completely, use
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+on the XtNtranslations resource and specify a compiled translation table
+as the value.
+</para>
+
+<para>
+To make it possible for users to easily modify translation tables in their
+resource files,
+the string-to-translation-table resource type converter
+allows the string to specify whether the table should replace,
+augment, or override any
+existing translation table in the widget.
+To specify this,
+a pound sign (#) is given as the first character of the table
+followed by one of the keywords “replace”, “augment”, or
+“override” to indicate
+whether to replace, augment, or override the existing table.
+The replace or merge
+operation is performed during the
+Core
+instance initialization.
+Each merge operation produces a new
+translation resource value; if the original tables were shared by
+other widgets, they are unaffected. If no directive is
+specified, “#replace” is assumed.
+</para>
+
+<para>
+At instance initialization
+the XtNtranslations resource is first fetched. Then, if it was
+not specified or did not contain “#replace”, the
+resource database is searched for the resource XtNbaseTranslations.
+If XtNbaseTranslations is found, it is merged into the widget class
+translation table. Then the widget <emphasis remap='I'>translations</emphasis> field is
+merged into the result or into the class translation table if
+XtNbaseTranslations was not found. This final table is then
+stored into the widget <emphasis remap='I'>translations</emphasis> field. If the XtNtranslations
+resource specified “#replace”, no merge is done.
+If neither XtNbaseTranslations or XtNtranslations are specified,
+the class translation table is copied into the widget instance.
+</para>
+
+<para>
+To completely remove existing translations, use
+<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtUninstallTranslations'>
+<funcprototype>
+<funcdef>void <function>XtUninstallTranslations</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget from which the translations are to be removed. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/>
+function causes the entire translation table for the widget to be removed.
+</para>
+</sect1>
+
+<sect1 id="Using_Accelerators">
+<title>Using Accelerators</title>
+<para>
+It is often desirable to be able to bind events in one widget to actions in
+another.
+In particular,
+it is often useful to be able to invoke menu actions from the keyboard.
+The Intrinsics provide a facility, called accelerators, that lets you
+accomplish this.
+An accelerator table is a translation table that is bound with its
+actions in the context of a particular widget, the <emphasis remap='I'>source</emphasis> widget.
+The accelerator table can then be installed on one or more <emphasis remap='I'>destination</emphasis> widgets.
+When an event sequence in the destination widget would cause an
+accelerator action to be taken, and if the source widget is sensitive,
+the actions are executed as though triggered by the same event sequence
+in the accelerator source
+widget. The event is
+passed to the action procedure without modification. The action
+procedures used within accelerators must not assume that the source
+widget is realized nor that any fields of the event are in reference
+to the source widget's window if the widget is realized.
+</para>
+
+<para>
+Each widget instance contains that widget's exported accelerator table
+as a resource.
+Each class of widget exports a method that takes a
+displayable string representation of the accelerators
+so that widgets can display their current accelerators.
+The representation is the accelerator table in canonical
+translation table form (see Appendix B).
+The display_accelerator procedure pointer is of type
+<xref linkend='XtStringProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtStringProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtStringProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>String <parameter>string</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source widget that supplied the accelerators.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the string representation of the accelerators for this widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Accelerators can be specified in resource files,
+and the string representation is the same as for a translation table.
+However,
+the interpretation of the
+<function>#augment</function>
+and
+<function>#override</function>
+directives applies to
+what will happen when the accelerator is installed;
+that is, whether or not the accelerator translations will override the
+translations in the destination widget.
+The default is
+<function>#augment</function>,
+which means that the accelerator translations have lower priority
+than the destination translations.
+The
+<function>#replace</function>
+directive is ignored for accelerator tables.
+</para>
+
+<para>
+To parse an accelerator table, use
+<xref linkend='XtParseAcceleratorTable' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtParseAcceleratorTable'>
+<funcprototype>
+<funcdef>XtAccelerators <function>XtParseAcceleratorTable</function></funcdef>
+ <paramdef>const char * <parameter>source</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the accelerator table to compile.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtParseAcceleratorTable' xrefstyle='select: title'/>
+function compiles the accelerator table into an opaque internal representation.
+The client
+should set the XtNaccelerators resource of
+each widget that is to be activated by these translations
+to the returned value.
+</para>
+
+<para>
+To install accelerators from a widget on another widget, use
+<xref linkend='XtInstallAccelerators' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtInstallAccelerators'>
+<funcprototype>
+<funcdef>void <function>XtInstallAccelerators</function></funcdef>
+ <paramdef>Widget <parameter>destination</parameter></paramdef>
+ <paramdef>Widget <parameter>source</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>destination</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget on which the accelerators are to be installed. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget from which the accelerators are to come. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtInstallAccelerators' xrefstyle='select: title'/>
+function installs the <emphasis remap='I'>accelerators</emphasis> resource value from
+<emphasis remap='I'>source</emphasis> onto <emphasis remap='I'>destination</emphasis>
+by merging the source accelerators into the destination translations.
+If the source <emphasis remap='I'>display_accelerator</emphasis> field is non-NULL,
+<xref linkend='XtInstallAccelerators' xrefstyle='select: title'/>
+calls it with the source widget and a string representation
+of the accelerator table,
+which indicates that its accelerators have been installed
+and that it should display them appropriately.
+The string representation of the accelerator table is its
+canonical translation table representation.
+</para>
+
+<para>
+As a convenience for installing all accelerators from a widget and all its
+descendants onto one destination, use
+<xref linkend='XtInstallAllAccelerators' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtInstallAllAccelerators'>
+<funcprototype>
+<funcdef>void <function>XtInstallAllAccelerators</function></funcdef>
+ <paramdef>Widget <parameter>destination</parameter></paramdef>
+ <paramdef>Widget <parameter>source</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>destination</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget on which the accelerators are to be installed. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the root widget of the widget tree
+from which the accelerators are to come. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtInstallAllAccelerators' xrefstyle='select: title'/>
+function recursively descends the widget tree rooted at <emphasis remap='I'>source</emphasis>
+and installs the accelerators resource value
+of each widget encountered onto <emphasis remap='I'>destination</emphasis>.
+A common use is to call
+<xref linkend='XtInstallAllAccelerators' xrefstyle='select: title'/>
+and pass the application main window as the source.
+</para>
+</sect1>
+
+<sect1 id="KeyCode_to_KeySym_Conversions">
+<title>KeyCode-to-KeySym Conversions</title>
+<para>
+The translation manager provides support for automatically translating
+KeyCodes in incoming key events into KeySyms.
+KeyCode-to-KeySym translator procedure pointers are of type
+<xref linkend='XtKeyProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtKeyProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtKeyProc)</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>KeyCode <parameter>keycode</parameter></paramdef>
+ <paramdef>Modifiers <parameter>modifiers</parameter></paramdef>
+ <paramdef>Modifiers *<parameter>modifiers_return</parameter></paramdef>
+ <paramdef>KeySym *<parameter>keysym_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display that the KeyCode is from.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeyCode to translate.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the modifiers to the KeyCode.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a location in which to store
+a mask that indicates the subset of all
+modifiers that are examined by the key translator for the specified keycode.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a location in which to store the resulting KeySym.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure takes a KeyCode and modifiers and produces a KeySym.
+For any given key translator function and keyboard encoding,
+<emphasis remap='I'>modifiers_return</emphasis> will be a constant per KeyCode that indicates
+the subset of all modifiers that are examined by the key translator
+for that KeyCode.
+</para>
+
+<para>
+The KeyCode-to-KeySym translator procedure
+must be implemented such that multiple calls with the same
+<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>keycode</emphasis>, and <emphasis remap='I'>modifiers</emphasis> return the same
+result until either a new case converter, an
+<xref linkend='XtCaseProc' xrefstyle='select: title'/>,
+is installed or a
+<function>MappingNotify</function>
+event is received.
+</para>
+
+<para>
+The Intrinsics maintain tables internally to map KeyCodes to KeySyms
+for each open display. Translator procedures and other clients may
+share a single copy of this table to perform the same mapping.
+</para>
+
+<para>
+To return a pointer to the KeySym-to-KeyCode mapping table for a
+particular display, use
+<xref linkend='XtGetKeysymTable' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetKeysymTable'>
+<funcprototype>
+<funcdef>KeySym *<function>XtGetKeysymTable</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>KeyCode *<parameter>min_keycode_return</parameter></paramdef>
+ <paramdef>int *<parameter>keysyms_per_keycode_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display whose table is required.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>min_keycode_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the minimum KeyCode valid for the display.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysyms_per_keycode_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of KeySyms stored for each KeyCode.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGetKeysymTable' xrefstyle='select: title'/>
+returns a pointer to the Intrinsics' copy of the
+server's KeyCode-to-KeySym table. This table must not be modified.
+There are <emphasis remap='I'>keysyms_per_keycode_return</emphasis> KeySyms associated with each
+KeyCode, located in the table with indices starting at index
+</para>
+<programlisting>
+ (test_keycode - min_keycode_return) * keysyms_per_keycode_return
+</programlisting>
+<para>
+for KeyCode <emphasis remap='I'>test_keycode</emphasis>. Any entries that have no KeySyms associated
+with them contain the value
+<function>NoSymbol</function>.
+Clients should not cache the KeySym table but should call
+<xref linkend='XtGetKeysymTable' xrefstyle='select: title'/>
+each time the value is
+needed, as the table may change prior to dispatching each event.
+</para>
+
+<para>
+For more information on this table, see
+Section 12.7 in
+Xlib — C Language X Interface.
+</para>
+
+<para>
+To register a key translator, use
+<xref linkend='XtSetKeyTranslator' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetKeyTranslator'>
+<funcprototype>
+<funcdef>void <function>XtSetKeyTranslator</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>XtKeyProc <parameter>proc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display from which to translate the events.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to perform key translations.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtSetKeyTranslator' xrefstyle='select: title'/>
+function sets the specified procedure as the current key translator.
+The default translator is
+<function>XtTranslateKey</function>,
+an
+<xref linkend='XtKeyProc' xrefstyle='select: title'/>
+that uses the Shift, Lock, numlock, and group modifiers
+with the interpretations defined in <emphasis remap='I'>X Window System Protocol</emphasis>, Section 5.
+It is provided so that new translators can call it to get default
+KeyCode-to-KeySym translations and so that the default translator
+can be reinstalled.
+</para>
+
+<para>
+To invoke the currently registered KeyCode-to-KeySym translator,
+use
+<xref linkend='XtTranslateKeycode' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtTranslateKeycode'>
+<funcprototype>
+<funcdef>void <function>XtTranslateKeycode</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>KeyCode <parameter>keycode</parameter></paramdef>
+ <paramdef>Modifiers <parameter>modifiers</parameter></paramdef>
+ <paramdef>Modifiers *<parameter>modifiers_return</parameter></paramdef>
+ <paramdef>KeySym *<parameter>keysym_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display that the KeyCode is from.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeyCode to translate.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the modifiers to the KeyCode.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a mask that indicates the modifiers actually used
+to generate the KeySym.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the resulting KeySym.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtTranslateKeycode' xrefstyle='select: title'/>
+function passes the specified arguments
+directly to the currently registered KeyCode-to-KeySym translator.
+</para>
+
+<para>
+To handle capitalization of nonstandard KeySyms, the Intrinsics allow
+clients to register case conversion routines.
+Case converter procedure pointers are of type
+<xref linkend='XtCaseProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCaseProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtCaseProc)</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>KeySym <parameter>keysym</parameter></paramdef>
+ <paramdef>KeySym *<parameter>lower_return</parameter></paramdef>
+ <paramdef>KeySym *<parameter>upper_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display connection for which the conversion is required.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySym to convert.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>lower_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a location into which to store the lowercase equivalent for
+the KeySym.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>upper_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a location into which to store the uppercase equivalent for
+the KeySym.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If there is no case distinction,
+this procedure should store the KeySym into both return values.
+</para>
+
+<para>
+To register a case converter, use
+<xref linkend='XtRegisterCaseConverter' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRegisterCaseConverter'>
+<funcprototype>
+<funcdef>void <function>XtRegisterCaseConverter</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>XtCaseProc <parameter>proc</parameter></paramdef>
+ <paramdef>KeySym <parameter>start</parameter></paramdef>
+ <paramdef>KeySym <parameter>stop</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display from which the key events are to come.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<xref linkend='XtCaseProc' xrefstyle='select: title'/>
+to do the conversions.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>start</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the first KeySym for which this converter is valid.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>stop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the last KeySym for which this converter is valid.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRegisterCaseConverter' xrefstyle='select: title'/>
+registers the specified case converter.
+The <emphasis remap='I'>start</emphasis> and <emphasis remap='I'>stop</emphasis> arguments provide the inclusive range of KeySyms
+for which this converter is to be called.
+The new converter overrides any previous converters for KeySyms in that range.
+No interface exists to remove converters;
+you need to register an identity converter.
+When a new converter is registered,
+the Intrinsics refresh the keyboard state if necessary.
+The default converter understands case conversion for all
+Latin KeySyms defined in <emphasis remap='I'>X Window System Protocol</emphasis>, Appendix A.
+</para>
+
+<para>
+To determine uppercase and lowercase equivalents for a KeySym, use
+<xref linkend='XtConvertCase' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtConvertCase'>
+<funcprototype>
+<funcdef>void <function>XtConvertCase</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>KeySym <parameter>keysym</parameter></paramdef>
+ <paramdef>KeySym *<parameter>lower_return</parameter></paramdef>
+ <paramdef>KeySym *<parameter>upper_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display that the KeySym came from.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySym to convert.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>lower_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the lowercase equivalent of the KeySym.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>upper_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the uppercase equivalent of the KeySym.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtConvertCase' xrefstyle='select: title'/>
+function calls the appropriate converter and returns the results.
+A user-supplied
+<xref linkend='XtKeyProc' xrefstyle='select: title'/>
+may need to use this function.
+</para>
+</sect1>
+
+<sect1 id="Obtaining_a_KeySym_in_an_Action_Procedure">
+<title>Obtaining a KeySym in an Action Procedure</title>
+<para>
+When an action procedure is invoked on a
+<function>KeyPress</function>
+or
+<function>KeyRelease</function>
+event, it often has a need to retrieve the KeySym and modifiers
+corresponding to the event that caused it to be invoked. In order to
+avoid repeating the processing that was just performed by the
+Intrinsics to match the translation entry, the KeySym and modifiers
+are stored for the duration of the action procedure and are made
+available to the client.
+</para>
+
+<para>
+To retrieve the KeySym and modifiers that matched the final event
+specification in the translation table entry, use
+<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetActionKeysym'>
+<funcprototype>
+<funcdef>KeySym <function>XtGetActionKeysym</function></funcdef>
+ <paramdef>XEvent *<parameter>event</parameter></paramdef>
+ <paramdef>Modifiers *<parameter>modifiers_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the event pointer passed to the action procedure by the Intrinsics.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>modifiers_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the modifiers that caused the match, if non-NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If
+<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>
+is called after an action procedure has been
+invoked by the Intrinsics and before that action procedure returns, and
+if the event pointer has the same value as the event pointer passed to
+that action routine, and if the event is a
+<function>KeyPress</function>
+or
+<function>KeyRelease</function>
+event, then
+<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>
+returns the KeySym that matched the final
+event specification in the translation table and, if <emphasis remap='I'>modifiers_return</emphasis>
+is non-NULL, the modifier state actually used to generate this KeySym;
+otherwise, if the event is a
+<function>KeyPress</function>
+or
+<function>KeyRelease</function>
+event, then
+<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>
+calls
+<xref linkend='XtTranslateKeycode' xrefstyle='select: title'/>
+and returns the results;
+else it returns
+<function>NoSymbol</function>
+and does not examine <emphasis remap='I'>modifiers_return</emphasis>.
+</para>
+
+<para>
+Note that if an action procedure invoked by the Intrinsics
+invokes a subsequent action procedure (and so on) via
+<xref linkend='XtCallActionProc' xrefstyle='select: title'/>,
+the nested action procedure may also call
+<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>
+to retrieve the Intrinsics' KeySym and modifiers.
+</para>
+</sect1>
+
+<sect1 id="KeySym_to_KeyCode_Conversions">
+<title>KeySym-to-KeyCode Conversions</title>
+<para>
+To return the list of KeyCodes that map to a particular KeySym in
+the keyboard mapping table maintained by the Intrinsics, use
+<xref linkend='XtKeysymToKeycodeList' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtKeysymToKeycodeList'>
+<funcprototype>
+<funcdef>void <function>XtKeysymToKeycodeList</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>KeySym <parameter>keysym</parameter></paramdef>
+ <paramdef>KeyCode **<parameter>keycodes_return</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>keycount_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display whose table is required.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keysym</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the KeySym for which to search.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycodes_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a list of KeyCodes that have <emphasis remap='I'>keysym</emphasis>
+associated with them, or NULL if <emphasis remap='I'>keycount_return</emphasis> is 0.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keycount_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of KeyCodes in the keycode list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtKeysymToKeycodeList' xrefstyle='select: title'/>
+procedure returns all the KeyCodes that have <emphasis remap='I'>keysym</emphasis>
+in their entry for the keyboard mapping table associated with <emphasis remap='I'>display</emphasis>.
+For each entry in the
+table, the first four KeySyms (groups 1 and 2) are interpreted as
+specified by <emphasis remap='I'>X Window System Protocol</emphasis>, Section 5. If no KeyCodes map to the
+specified KeySym, <emphasis remap='I'>keycount_return</emphasis> is zero and *<emphasis remap='I'>keycodes_return</emphasis> is NULL.
+</para>
+
+<para>
+The caller should free the storage pointed to by <emphasis remap='I'>keycodes_return</emphasis> using
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when it is no longer useful. If the caller needs to examine
+the KeyCode-to-KeySym table for a particular KeyCode, it should call
+<xref linkend='XtGetKeysymTable' xrefstyle='select: title'/>.
+</para>
+</sect1>
+
+<sect1 id="Registering_Button_and_Key_Grabs_for_Actions">
+<title>Registering Button and Key Grabs for Actions</title>
+<para>
+To register button and key grabs for a widget's window according to the
+event bindings in the widget's translation table, use
+<xref linkend='XtRegisterGrabAction' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRegisterGrabAction'>
+<funcprototype>
+<funcdef>void <function>XtRegisterGrabAction</function></funcdef>
+ <paramdef>XtActionProc <parameter>action_proc</parameter></paramdef>
+ <paramdef>Boolean <parameter>owner_events</parameter></paramdef>
+ <paramdef>unsigned int <parameter>event_mask</parameter></paramdef>
+ <paramdef>int <parameter>pointer_mode</parameter></paramdef>
+ <paramdef>int <parameter>keyboard_mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>action_proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the action procedure to search for in translation tables.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner_events</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event_mask</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pointer_mode</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>keyboard_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify arguments to
+<xref linkend='XtGrabButton' xrefstyle='select: title'/>
+or
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtRegisterGrabAction' xrefstyle='select: title'/>
+adds the specified <emphasis remap='I'>action_proc</emphasis> to a list known to
+the translation manager. When a widget is realized, or when the
+translations of a realized widget or the accelerators installed on a
+realized widget are modified, its translation table and any installed
+accelerators are scanned for action procedures on this list.
+If any are invoked on
+<function>ButtonPress</function>
+or
+<function>KeyPress</function>
+events as the only or final event
+in a sequence, the Intrinsics will call
+<xref linkend='XtGrabButton' xrefstyle='select: title'/>
+or
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+for the widget with every button or KeyCode which maps to the
+event detail field, passing the specified <emphasis remap='I'>owner_events</emphasis>, <emphasis remap='I'>event_mask</emphasis>,
+<emphasis remap='I'>pointer_mode</emphasis>, and <emphasis remap='I'>keyboard_mode</emphasis>. For
+<function>ButtonPress</function>
+events, the modifiers
+specified in the grab are determined directly from the translation
+specification and <emphasis remap='I'>confine_to</emphasis> and <emphasis remap='I'>cursor</emphasis> are specified as
+<function>None</function>.
+For
+<function>KeyPress</function>
+events, if the translation table entry specifies colon (:) in
+the modifier list, the modifiers are determined by calling the key
+translator procedure registered for the display and calling
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+for every combination of standard modifiers which map the KeyCode to
+the specified event detail KeySym, and ORing any modifiers specified in
+the translation table entry, and <emphasis remap='I'>event_mask</emphasis> is ignored. If the
+translation table entry does not specify colon in the modifier list,
+the modifiers specified in the grab are those specified in the
+translation table entry only. For both
+<function>ButtonPress</function>
+and
+<function>KeyPress</function>
+events, don't-care modifiers are ignored unless the translation entry
+explicitly specifies “Any” in the <emphasis remap='I'>modifiers</emphasis> field.
+</para>
+
+<para>
+If the specified <emphasis remap='I'>action_proc</emphasis> is already registered for the calling
+process, the new values will replace the previously specified values
+for any widgets that become realized following the call, but existing
+grabs are not altered on currently realized widgets.
+</para>
+
+<para>
+When translations or installed accelerators are modified for a
+realized widget, any previous key or button grabs registered
+as a result of the old bindings are released if they do not appear in
+the new bindings and are not explicitly grabbed by the client with
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>
+or
+<xref linkend='XtGrabButton' xrefstyle='select: title'/>.
+</para>
+</sect1>
+
+<sect1 id="Invoking_Actions_Directly">
+<title>Invoking Actions Directly</title>
+<para>
+Normally action procedures are invoked by the Intrinsics when an
+event or event sequence arrives for a widget. To
+invoke an action procedure directly, without generating
+(or synthesizing) events, use
+<xref linkend='XtCallActionProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCallActionProc'>
+<funcprototype>
+<funcdef>void <function>XtCallActionProc</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>const char * <parameter>action</parameter></paramdef>
+ <paramdef>XEvent * <parameter>event</parameter></paramdef>
+ <paramdef>String * <parameter>params</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_params</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget in which the action is to be invoked. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>action</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the action routine.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the contents of the <emphasis remap='I'>event</emphasis> passed to the action routine.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the contents of the <emphasis remap='I'>params</emphasis> passed to the action routine.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtCallActionProc' xrefstyle='select: title'/>
+searches for the named action routine in the same
+manner and order as translation tables are bound, as described in
+Section 10.1.2, except that application action tables are searched, if
+necessary, as of the time of the call to
+<xref linkend='XtCallActionProc' xrefstyle='select: title'/>.
+If found,
+the action routine is invoked with the specified widget, event pointer,
+and parameters. It is the responsibility of the caller to ensure that
+the contents of the <emphasis remap='I'>event</emphasis>, <emphasis remap='I'>params</emphasis>, and <emphasis remap='I'>num_params</emphasis> arguments are
+appropriate for the specified action routine and, if necessary, that
+the specified widget is realized or sensitive. If the named action
+routine cannot be found,
+<xref linkend='XtCallActionProc' xrefstyle='select: title'/>
+generates a warning message and returns.
+</para>
+</sect1>
+
+<sect1 id="Obtaining_a_Widget_s_Action_List">
+<title>Obtaining a Widget's Action List</title>
+<para>
+Occasionally a subclass will require the pointers to one or more of
+its superclass's action procedures. This would be needed, for
+example, in order to envelop the superclass's action. To retrieve
+the list of action procedures registered in the superclass's
+<emphasis remap='I'>actions</emphasis> field, use
+<xref linkend='XtGetActionList' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetActionList'>
+<funcprototype>
+<funcdef>void <function>XtGetActionList</function></funcdef>
+ <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
+ <paramdef>XtActionList *<parameter>actions_return</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_actions_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget class whose actions are to be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>actions_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the action list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_actions_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of action procedures declared by the class.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGetActionList' xrefstyle='select: title'/>
+returns the action table defined by the specified
+widget class. This table does not include actions defined by the
+superclasses. If <emphasis remap='I'>widget_class</emphasis> is not initialized, or is not
+<function>coreWidgetClass</function>
+or a subclass thereof, or if the class does not define any actions,
+*<emphasis remap='I'>actions_return</emphasis> will be NULL and *<emphasis remap='I'>num_actions_return</emphasis>
+will be zero.
+If *<emphasis remap='I'>actions_return</emphasis> is non-NULL the client is responsible for freeing
+the table using
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when it is no longer needed.
+</para>
+</sect1>
+</chapter>
Index: create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH11.xml
===================================================================
--- create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH11.xml (nonexistent)
+++ create-1.2.1-docbook-patch/libXt-1.2.1-new/specs/CH11.xml (revision 5)
@@ -0,0 +1,5548 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<chapter id='Utility_Functions'>
+<title>Utility Functions</title>
+<para>
+The Intrinsics provide a number of utility functions that you can use to
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Determine the number of elements in an array.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Translate strings to widget instances.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Manage memory usage.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Share graphics contexts.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Manipulate selections.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Merge exposure events into a region.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Translate widget coordinates.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Locate a widget given a window id.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Handle errors.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set the WM_COLORMAP_WINDOWS property.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Locate files by name with string substitutions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Register callback functions for external agents.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Locate all the displays of an application context.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<sect1 id="Determining_the_Number_of_Elements_in_an_Array">
+<title>Determining the Number of Elements in an Array</title>
+<para>
+To determine the number of elements in a fixed-size array, use
+<xref linkend='XtNumber' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtNumber'>
+<funcprototype>
+<funcdef>Cardinal <function>XtNumber</function></funcdef>
+ <paramdef>ArrayType <parameter>array</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>array</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a fixed-size array of arbitrary type.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtNumber' xrefstyle='select: title'/>
+macro returns the number of elements allocated to the array.
+</para>
+</sect1>
+
+<sect1 id="Translating_Strings_to_Widget_Instances">
+<title>Translating Strings to Widget Instances</title>
+<para>
+To translate a widget name to a widget instance, use
+<xref linkend='XtNameToWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtNameToWidget'>
+<funcprototype>
+<funcdef>Widget <function>XtNameToWidget</function></funcdef>
+ <paramdef>Widget <parameter>reference</parameter></paramdef>
+ <paramdef>const char * <parameter>names</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>reference</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget from which the search is to start. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>names</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the partially qualified name of the desired widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtNameToWidget' xrefstyle='select: title'/>
+function searches for a descendant of the <emphasis remap='I'>reference</emphasis>
+widget whose name matches the specified names. The <emphasis remap='I'>names</emphasis> parameter
+specifies a simple object name or a series of simple object name
+components separated by periods or asterisks.
+<xref linkend='XtNameToWidget' xrefstyle='select: title'/>
+returns the descendant with the shortest name matching the specification
+according to the following rules, where child is either a pop-up child
+or a normal child if the widget's class is a subclass of
+Composite :
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Enumerate the object subtree rooted at the reference widget in
+breadth-first order, qualifying the name of each object with the
+names of all its ancestors up to, but not including, the reference
+widget. The ordering between children of a common parent is
+not defined.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Return the first object in the enumeration that matches the
+specified name, where each component of <emphasis remap='I'>names</emphasis> matches exactly the
+corresponding component of the qualified object name and asterisk
+matches any series of components, including none.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If no match is found, return NULL.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+Since breadth-first traversal is specified, the descendant with the
+shortest matching name (i.e., the fewest number of components), if any,
+will always be returned. However, since the order of enumeration of
+children is undefined and since the Intrinsics do not require that all
+children of a widget have unique names,
+<xref linkend='XtNameToWidget' xrefstyle='select: title'/>
+may return any
+child that matches if there are multiple objects in the subtree with
+the same name. Consecutive separators (periods or asterisks)
+including at least one asterisk are treated as a single asterisk.
+Consecutive periods are treated as a single period.
+</para>
+</sect1>
+
+<sect1 id="Managing_Memory_Usage">
+<title>Managing Memory Usage</title>
+<para>
+The Intrinsics memory management functions provide uniform checking for
+null pointers and error reporting on memory allocation errors.
+These functions are completely compatible with their standard C language
+runtime counterparts
+<function>malloc</function>,
+<function>calloc</function>,
+<function>realloc</function>,
+and
+<function>free</function>
+with the following added functionality:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtMalloc' xrefstyle='select: title'/>,
+<xref linkend='XtCalloc' xrefstyle='select: title'/>,
+and
+<xref linkend='XtRealloc' xrefstyle='select: title'/>
+give an error if there is not enough memory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtFree' xrefstyle='select: title'/>
+simply returns if passed a NULL pointer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtRealloc' xrefstyle='select: title'/>
+simply allocates new storage if passed a NULL pointer.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+See the standard C library documentation on
+<function>malloc</function>,
+<function>calloc</function>,
+<function>realloc</function>,
+and
+<function>free</function>
+for more information.
+</para>
+
+<para>
+To allocate storage, use
+<xref linkend='XtMalloc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtMalloc'>
+<funcprototype>
+<funcdef>char * <function>XtMalloc</function></funcdef>
+ <paramdef>Cardinal <parameter>size</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>size</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes desired.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtMalloc' xrefstyle='select: title'/>
+function returns a pointer to a block of storage of at least
+the specified <emphasis remap='I'>size</emphasis> bytes.
+If there is insufficient memory to allocate the new block,
+<xref linkend='XtMalloc' xrefstyle='select: title'/>
+calls
+<xref linkend='XtErrorMsg' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To allocate and initialize an array, use
+<xref linkend='XtCalloc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCalloc'>
+<funcprototype>
+<funcdef>char * <function>XtCalloc</function></funcdef>
+ <paramdef>Cardinal <parameter>num</parameter></paramdef>
+ <paramdef>Cardinal <parameter>size</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of array elements to allocate.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>size</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of each array element in bytes.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtCalloc' xrefstyle='select: title'/>
+function allocates space for the specified number of array elements
+of the specified size and initializes the space to zero.
+If there is insufficient memory to allocate the new block,
+<xref linkend='XtCalloc' xrefstyle='select: title'/>
+calls
+<xref linkend='XtErrorMsg' xrefstyle='select: title'/>.
+<xref linkend='XtCalloc' xrefstyle='select: title'/>
+returns the address of the allocated storage.
+</para>
+
+<para>
+To change the size of an allocated block of storage, use
+<xref linkend='XtRealloc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtRealloc'>
+<funcprototype>
+<funcdef>char *<function>XtRealloc</function></funcdef>
+ <paramdef>char *<parameter>ptr</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ptr</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the old storage allocated with
+<xref linkend='XtMalloc' xrefstyle='select: title'/>,
+<xref linkend='XtCalloc' xrefstyle='select: title'/>,
+or
+<xref linkend='XtRealloc' xrefstyle='select: title'/>,
+or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies number of bytes desired in new storage.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtRealloc' xrefstyle='select: title'/>
+function changes the size of a block of storage, possibly moving it.
+Then it copies the old contents (or as much as will fit) into the new block
+and frees the old block.
+If there is insufficient memory to allocate the new block,
+<xref linkend='XtRealloc' xrefstyle='select: title'/>
+calls
+<xref linkend='XtErrorMsg' xrefstyle='select: title'/>.
+If <emphasis remap='I'>ptr</emphasis> is NULL,
+<xref linkend='XtRealloc' xrefstyle='select: title'/>
+simply calls
+<xref linkend='XtMalloc' xrefstyle='select: title'/>.
+<xref linkend='XtRealloc' xrefstyle='select: title'/>
+then returns the address of the new block.
+</para>
+
+<para>
+To free an allocated block of storage, use
+<xref linkend='XtFree' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtFree'>
+<funcprototype>
+<funcdef>void <function>XtFree</function></funcdef>
+ <paramdef>char *<parameter>ptr</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ptr</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to a block of storage allocated with
+<xref linkend='XtMalloc' xrefstyle='select: title'/>,
+<xref linkend='XtCalloc' xrefstyle='select: title'/>,
+or
+<xref linkend='XtRealloc' xrefstyle='select: title'/>,
+or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtFree' xrefstyle='select: title'/>
+function returns storage, allowing it to be reused.
+If <emphasis remap='I'>ptr</emphasis> is NULL,
+<xref linkend='XtFree' xrefstyle='select: title'/>
+returns immediately.
+</para>
+
+<para>
+To allocate storage for a new instance of a type, use
+<xref linkend='XtNew' xrefstyle='select: title'/>.
+</para>
+
+
+<funcsynopsis id='XtNew'>
+<funcprototype>
+<funcdef>type <function>XtNew</function></funcdef>
+ <paramdef>type <parameter>t</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a previously declared type.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtNew' xrefstyle='select: title'/>
+returns a pointer to the allocated storage.
+If there is insufficient memory to allocate the new block,
+<xref linkend='XtNew' xrefstyle='select: title'/>
+calls
+<xref linkend='XtErrorMsg' xrefstyle='select: title'/>.
+<xref linkend='XtNew' xrefstyle='select: title'/>
+is a convenience macro that calls
+<xref linkend='XtMalloc' xrefstyle='select: title'/>
+with the following arguments specified:
+</para>
+<programlisting>
+((type *) XtMalloc((unsigned) sizeof(type)))
+</programlisting>
+<para>
+The storage allocated by
+<xref linkend='XtNew' xrefstyle='select: title'/>
+should be freed using
+<xref linkend='XtFree' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To copy an instance of a string, use
+<xref linkend='XtNewString' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtNewString'>
+<funcprototype>
+<funcdef>String <function>XtNewString</function></funcdef>
+ <paramdef>String <parameter>string</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a previously declared string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtNewString' xrefstyle='select: title'/>
+returns a pointer to the allocated storage.
+If there is insufficient memory to allocate the new block,
+<xref linkend='XtNewString' xrefstyle='select: title'/>
+calls
+<xref linkend='XtErrorMsg' xrefstyle='select: title'/>.
+<xref linkend='XtNewString' xrefstyle='select: title'/>
+is a convenience macro that calls
+<xref linkend='XtMalloc' xrefstyle='select: title'/>
+with the following arguments specified:
+</para>
+<programlisting>
+(strcpy(XtMalloc((unsigned)strlen(str) + 1), str))
+</programlisting>
+<para>
+The storage allocated by
+<xref linkend='XtNewString' xrefstyle='select: title'/>
+should be freed using
+<xref linkend='XtFree' xrefstyle='select: title'/>.
+</para>
+</sect1>
+
+<sect1 id="Sharing_Graphics_Contexts">
+<title>Sharing Graphics Contexts</title>
+<para>
+The Intrinsics provide a mechanism whereby cooperating objects can share a
+graphics context (GC), thereby reducing both the number of GCs
+created and the total number of server calls in any given application.
+The mechanism is a simple caching scheme
+and allows for clients to declare both modifiable and nonmodifiable
+fields of the shared GCs.
+</para>
+
+<para>
+To obtain a shareable GC with modifiable fields, use
+<xref linkend='XtAllocateGC' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAllocateGC'>
+<funcprototype>
+<funcdef>GC <function>XtAllocateGC</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>Cardinal <parameter>depth</parameter></paramdef>
+ <paramdef>XtGCMask <parameter>value_mask</parameter></paramdef>
+ <paramdef>XGCValues *<parameter>values</parameter></paramdef>
+ <paramdef>XtGCMask <parameter>dynamic_mask</parameter></paramdef>
+ <paramdef>XtGCMask <parameter>unused_mask</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an object, giving the screen for which the
+returned GC is valid. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>depth</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the depth for which the returned GC is valid, or 0.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies fields of the GC that are initialized from <emphasis remap='I'>values</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>values</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the values for the initialized fields.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dynamic_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies fields of the GC that will be modified by the caller.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>unused_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies fields of the GC that will not be needed by the caller.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAllocateGC' xrefstyle='select: title'/>
+function returns a shareable GC that may be
+modified by the client. The <emphasis remap='I'>screen</emphasis> field of the specified
+widget or of the nearest widget ancestor of the specified
+object and the specified <emphasis remap='I'>depth</emphasis> argument supply
+the root and drawable depths for which the GC is to be
+valid. If <emphasis remap='I'>depth</emphasis> is zero, the depth is taken from the
+<emphasis remap='I'>depth</emphasis> field of the specified widget or of the nearest
+widget ancestor of the specified object.
+</para>
+
+<para>
+The <emphasis remap='I'>value_mask</emphasis> argument specifies fields of the GC
+that are initialized with the respective member of the
+<emphasis remap='I'>values</emphasis> structure. The <emphasis remap='I'>dynamic_mask</emphasis> argument specifies fields
+that the caller intends to modify during program execution.
+The caller must ensure that the corresponding GC field is set
+prior to each use of the GC. The <emphasis remap='I'>unused_mask</emphasis> argument
+specifies fields of the GC that are of no interest to the
+caller. The caller may make no assumptions about the contents
+of any fields specified in <emphasis remap='I'>unused_mask</emphasis>. The caller may assume
+that at all times all fields not specified in either
+<emphasis remap='I'>dynamic_mask</emphasis> or <emphasis remap='I'>unused_mask</emphasis> have their default value if not
+specified in <emphasis remap='I'>value_mask</emphasis> or the value specified by <emphasis remap='I'>values</emphasis>.
+If a field is specified in both <emphasis remap='I'>value_mask</emphasis> and <emphasis remap='I'>dynamic_mask</emphasis>,
+the effect is as if it were specified only in <emphasis remap='I'>dynamic_mask</emphasis>
+and then immediately set to the value in <emphasis remap='I'>values</emphasis>. If a field
+is set in <emphasis remap='I'>unused_mask</emphasis> and also in either <emphasis remap='I'>value_mask</emphasis> or
+<emphasis remap='I'>dynamic_mask</emphasis>, the specification in <emphasis remap='I'>unused_mask</emphasis> is ignored.
+</para>
+
+<para>
+<xref linkend='XtAllocateGC' xrefstyle='select: title'/>
+tries to minimize the number of unique GCs
+created by comparing the arguments with those of previous
+calls and returning an existing GC when there are no
+conflicts.
+<xref linkend='XtAllocateGC' xrefstyle='select: title'/>
+may modify and return an existing GC if it was allocated with a
+nonzero <emphasis remap='I'>unused_mask</emphasis>.
+</para>
+
+<para>
+To obtain a shareable GC with no modifiable fields, use
+<xref linkend='XtGetGC' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetGC'>
+<funcprototype>
+<funcdef>GC <function>XtGetGC</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>XtGCMask <parameter>value_mask</parameter></paramdef>
+ <paramdef>XGCValues *<parameter>values</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an object, giving the screen and depth for which the
+returned GC is valid. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which fields of the <emphasis remap='I'>values</emphasis> structure are specified.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>values</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the actual values for this GC.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetGC' xrefstyle='select: title'/>
+function returns a shareable, read-only GC.
+The parameters to this function are the same as those for
+<function>XCreateGC</function>
+except that an Object is passed instead of a Display.
+<xref linkend='XtGetGC' xrefstyle='select: title'/>
+is equivalent to
+<xref linkend='XtAllocateGC' xrefstyle='select: title'/>
+with <emphasis remap='I'>depth</emphasis>, <emphasis remap='I'>dynamic_mask</emphasis>, and <emphasis remap='I'>unused_mask</emphasis> all zero.
+</para>
+
+<para>
+<xref linkend='XtGetGC' xrefstyle='select: title'/>
+shares only GCs in which all values in the GC returned by
+<function>XCreateGC</function>
+are the same.
+In particular, it does not use the <emphasis remap='I'>value_mask</emphasis> provided to
+determine which fields of the GC a widget considers relevant.
+The <emphasis remap='I'>value_mask</emphasis> is used only to tell the server which fields should be
+filled in from <emphasis remap='I'>values</emphasis> and which it should fill in with default values.
+</para>
+
+<para>
+To deallocate a shared GC when it is no longer needed, use
+<xref linkend='XtReleaseGC' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtReleaseGC'>
+<funcprototype>
+<funcdef>void <function>XtReleaseGC</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>GC <parameter>gc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>object</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies any object on the Display for which the GC was created. Must be of class Object or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>gc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the shared GC obtained with either
+<xref linkend='XtAllocateGC' xrefstyle='select: title'/>
+or
+<xref linkend='XtGetGC' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+References to shareable GCs are counted and a free request is generated to the
+server when the last user of a given GC releases it.
+</para>
+</sect1>
+
+<sect1 id="Managing_Selections">
+<title>Managing Selections</title>
+<para>
+Arbitrary widgets in multiple applications can communicate
+with each other by means of the Intrinsics global selection mechanism,
+which conforms to the specifications in the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
+The Intrinsics supply functions for providing and receiving selection data in
+one logical piece (atomic transfers)
+or in smaller logical segments (incremental transfers).
+</para>
+
+<para>
+The incremental interface is provided for a selection owner or
+selection requestor that cannot or prefers not to pass the selection
+value to and from the Intrinsics in a single call. For instance,
+either an application that is running on a machine with limited memory
+may not be able to store the entire selection value in memory or a
+selection owner may already have the selection value available in
+discrete chunks, and it would be more efficient not to have to
+allocate additional storage to copy the pieces contiguously. Any
+owner or requestor that prefers to deal with the selection value in
+segments can use the incremental interfaces to do so.
+The transfer between the selection owner or requestor and the Intrinsics is not
+required to match the underlying
+transport protocol between the application and the X server;
+the Intrinsics will break too large a selection
+into smaller pieces for transport if necessary
+and will coalesce a selection transmitted incrementally if the value
+was requested atomically.
+</para>
+
+<sect2 id='Setting_and_Getting_the_Selection_Timeout_Value'>
+<title>Setting and Getting the Selection Timeout Value</title>
+<para>
+To set the Intrinsics selection timeout, use
+<xref linkend='XtAppSetSelectionTimeout' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppSetSelectionTimeout'>
+<funcprototype>
+<funcdef>void <function>XtAppSetSelectionTimeout</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>unsigned long <parameter>timeout</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>timeout</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the selection timeout in milliseconds.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+To get the current selection timeout value, use
+<xref linkend='XtAppGetSelectionTimeout' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppGetSelectionTimeout'>
+<funcprototype>
+<funcdef>unsigned long <function>XtAppGetSelectionTimeout</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppGetSelectionTimeout' xrefstyle='select: title'/>
+function returns the current selection timeout value in milliseconds.
+The selection timeout is the time within which the two communicating
+applications must respond to one another.
+The initial timeout value is set by the
+selectionTimeout
+application resource as retrieved by
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
+If
+selectionTimeout
+is not specified,
+the default is five seconds.
+</para>
+</sect2>
+
+<sect2 id="Using_Atomic_Transfers">
+<title>Using Atomic Transfers</title>
+<para>
+When using atomic transfers, the owner will completely
+process one selection request at a time.
+The owner may consider each request individually,
+since there is no possibility for overlap
+between evaluation of two requests.
+</para>
+
+<sect3 id="Atomic_Transfer_Procedures">
+<title>Atomic Transfer Procedures</title>
+<para>
+The following procedures are used by the selection owner when
+providing selection data in a single unit.
+</para>
+
+<para>
+The procedure pointer specified by the owner to supply the selection
+data to the Intrinsics is of type
+<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtConvertSelectionProc'>
+<funcprototype>
+<funcdef>typedef Boolean <function>(*XtConvertSelectionProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom *<parameter>selection</parameter></paramdef>
+ <paramdef>Atom *<parameter>target</parameter></paramdef>
+ <paramdef>Atom *<parameter>type_return</parameter></paramdef>
+ <paramdef>XtPointer *<parameter>value_return</parameter></paramdef>
+ <paramdef>unsigned long *<parameter>length_return</parameter></paramdef>
+ <paramdef>int *<parameter>format_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that currently owns this selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom naming the selection requested
+(for example,
+<function>XA_PRIMARY</function>
+or
+<function>XA_SECONDARY ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target type of the selection that has been requested,
+which indicates the desired information about the selection
+(for example, File Name, Text, Window).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to an atom into which the property type of the
+converted value of the selection is to be stored.
+For instance, either File Name or Text might have property type
+<function>XA_STRING</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer into which a pointer to the converted value of the
+selection is to be stored.
+The selection owner is responsible for allocating this storage.
+If the selection owner has provided an
+<xref linkend='XtSelectionDoneProc' xrefstyle='select: title'/>
+for the selection,
+this storage is owned by the selection owner;
+otherwise, it is owned by the Intrinsics selection mechanism,
+which frees it by calling
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when it is done with it.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer into which the number of elements in <emphasis remap='I'>value_return</emphasis>,
+each of size indicated by <emphasis remap='I'>format_return</emphasis>, is to be stored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer into which the size in bits of the data elements
+of the selection value is to be stored.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure is called by the Intrinsics selection mechanism
+to get the value of a selection as a given type
+from the current selection owner.
+It returns
+<function>True</function>
+if the owner successfully converted the selection to the target type or
+<function>False</function>
+otherwise.
+If the procedure returns
+<function>False</function>,
+the values of the return arguments are undefined.
+Each
+<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/>
+should respond to target value
+<function>TARGETS</function>
+by returning a value containing the list of the targets
+into which it is
+prepared to convert the selection.
+The value returned in
+<emphasis remap='I'>format_return</emphasis> must be one of 8, 16, or 32 to allow the server to
+byte-swap the data if necessary.
+</para>
+
+<para>
+This procedure does not need to worry about responding to the
+MULTIPLE or the TIMESTAMP target values (see
+<xref linkend='Window_Creation_Convenience_Routine' />
+in the Inter-Client Communication Conventions Manual).
+A selection request with
+the MULTIPLE target type is transparently transformed into a
+series of calls to this procedure, one for each target type, and a
+selection request with the TIMESTAMP target value is answered
+automatically by the Intrinsics using the time specified in the
+call to
+<xref linkend='XtOwnSelection' xrefstyle='select: title'/>
+or
+<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To retrieve the
+<function>SelectionRequest</function>
+event that triggered the
+<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/>
+procedure, use
+<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetSelectionRequest'>
+<funcprototype>
+<funcdef>XSelectionRequestEvent *<function>XtGetSelectionRequest</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>XtRequestId <parameter>request_id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that currently owns this selection. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the selection being processed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request_id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the requestor id in the case of incremental
+selections, or NULL in the case of atomic transfers.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/>
+may be called only from within an
+<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/>
+procedure and returns a pointer to the
+<function>SelectionRequest</function>
+event that caused the conversion procedure to be invoked.
+<emphasis remap='I'>Request_id</emphasis> specifies a unique id for the individual request in the
+case that multiple incremental transfers are outstanding. For atomic
+transfers, <emphasis remap='I'>request_id</emphasis> must be specified as NULL. If no
+<function>SelectionRequest</function>
+event is being processed for the specified
+<emphasis remap='I'>widget</emphasis>, <emphasis remap='I'>selection</emphasis>, and <emphasis remap='I'>request_id</emphasis>,
+<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/>
+returns NULL.
+</para>
+
+<para>
+The procedure pointer specified by the owner when it desires
+notification upon losing ownership is of type
+<xref linkend='XtLoseSelectionProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtLoseSelectionProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtLoseSelectionProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom *<parameter>selection</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that has lost selection ownership.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom naming the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure is called by the Intrinsics selection mechanism
+to inform the specified widget that it has lost the given selection.
+Note that this procedure does not ask the widget to relinquish the
+selection ownership; it is merely informative.
+</para>
+
+<para>
+The procedure pointer specified by the owner when it desires
+notification of receipt of the data or when it manages the storage
+containing the data is of type
+<xref linkend='XtSelectionDoneProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSelectionDoneProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtSelectionDoneProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom *<parameter>selection</parameter></paramdef>
+ <paramdef>Atom *<parameter>target</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that owns the converted selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom naming the selection that was converted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target type to which the conversion was done.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure is called by the Intrinsics selection mechanism
+to inform the selection owner that a selection requestor has successfully
+retrieved a selection value.
+If the selection owner has registered an
+<xref linkend='XtSelectionDoneProc' xrefstyle='select: title'/>,
+it should expect it to be called once for each conversion that it performs,
+after the converted value has been successfully transferred
+to the requestor.
+If the selection owner has registered an
+<xref linkend='XtSelectionDoneProc' xrefstyle='select: title'/>,
+it also owns the storage containing the converted
+selection value.
+</para>
+</sect3>
+<sect3 id="Getting_the_Selection_Value">
+<title>Getting the Selection Value</title>
+<para>
+The procedure pointer specified by the requestor to receive the
+selection data from the Intrinsics is of type
+<xref linkend='XtSelectionCallbackProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSelectionCallbackProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtSelectionCallbackProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>Atom *<parameter>selection</parameter></paramdef>
+ <paramdef>Atom *<parameter>type</parameter></paramdef>
+ <paramdef>XtPointer <parameter>value</parameter></paramdef>
+ <paramdef>unsigned long *<parameter>length</parameter></paramdef>
+ <paramdef>int *<parameter>format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that requested the selection value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a value passed in by the widget when it requested the
+selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the selection that was requested.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the representation type of the selection value (for example,
+<function>XA_STRING ).</function>
+Note that it is not the target that was requested (which the client
+must remember for itself), but the type that
+is used to represent the target.
+The special symbolic constant
+<function>XT_CONVERT_FAIL</function>
+is used to indicate that the selection conversion failed because the
+selection owner did not respond within the Intrinsics selection timeout
+interval.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the selection value.
+The requesting client owns this storage and is responsible for freeing it
+by calling
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when it is done with it.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of elements in <emphasis remap='I'>value</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size in bits of the data in each element of <emphasis remap='I'>value</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure is called by the Intrinsics selection mechanism to deliver the
+requested selection to the requestor.
+</para>
+
+<para>
+If the
+<function>SelectionNotify</function>
+event returns a property of
+<function>None</function>,
+meaning the conversion has been refused because there is no owner for the
+specified selection or the owner cannot convert the selection to the
+requested target for any reason, the procedure is called with a value
+of NULL and a length of zero.
+</para>
+
+<para>
+To obtain the selection value in a single logical unit, use
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>
+or
+<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetSelectionValue'>
+<funcprototype>
+<funcdef>void <function>XtGetSelectionValue</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Atom <parameter>target</parameter></paramdef>
+ <paramdef>XtSelectionCallbackProc <parameter>callback</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the particular selection desired; for example,
+<function>XA_PRIMARY</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of information needed about the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called when the selection value
+has been obtained.
+Note that this is how the selection value is communicated back to the client.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies additional data to be passed to the specified procedure
+when it is called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the timestamp that indicates when the selection request was
+initiated.
+This should be the timestamp of the event that triggered this request;
+the value
+<function>CurrentTime</function>
+is not acceptable.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>
+function requests the value of the selection converted to
+the target type.
+The specified callback is called at some time after
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>
+is called, when the selection value is received from the X server.
+It may be called before or after
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>
+returns.
+For more information about <emphasis remap='I'>selection</emphasis>,
+<emphasis remap='I'>target</emphasis>, and
+<emphasis remap='I'>time</emphasis>, see
+Section 2.6 in the
+Inter-Client Communication Conventions Manual.
+</para>
+
+<funcsynopsis id='XtGetSelectionValues'>
+<funcprototype>
+<funcdef>void <function>XtGetSelectionValues</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Atom *<parameter>targets</parameter></paramdef>
+ <paramdef>int <parameter>count</parameter></paramdef>
+ <paramdef>XtSelectionCallbackProc <parameter>callback</parameter></paramdef>
+ <paramdef>XtPointer *<parameter>client_data</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the particular selection desired (that is, primary or secondary).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>targets</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the types of information needed about the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length of the <emphasis remap='I'>targets</emphasis> and <emphasis remap='I'>client_data</emphasis> lists.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback procedure
+to be called with each selection value obtained.
+Note that this is how the selection values are communicated back to the
+client.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of additional data values, one for each target type,
+that are passed to the callback procedure when it is called for that target.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the timestamp that indicates when the selection request was
+initiated.
+This should be the timestamp of the event that triggered this request;
+the value
+<function>CurrentTime</function>
+is not acceptable.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>
+function is similar to multiple calls to
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>
+except that it guarantees that no other client can assert ownership
+between requests and therefore that all the conversions will refer to
+the same selection value. The callback is invoked once for each
+target value with the corresponding client data.
+For more information about <emphasis remap='I'>selection</emphasis>, <emphasis remap='I'>target</emphasis>, and
+<emphasis remap='I'>time</emphasis>, see
+section 2.6
+in the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>.
+</para>
+</sect3>
+<sect3 id="Setting_the_Selection_Owner">
+<title>Setting the Selection Owner</title>
+<para>
+To set the selection owner and indicate that the selection value will
+be provided in one piece, use
+<xref linkend='XtOwnSelection' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtOwnSelection'>
+<funcprototype>
+<funcdef>Boolean <function>XtOwnSelection</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+ <paramdef>XtConvertSelectionProc <parameter>convert_proc</parameter></paramdef>
+ <paramdef>XtLoseSelectionProc <parameter>lose_selection</parameter></paramdef>
+ <paramdef>XtSelectionDoneProc <parameter>done_proc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that wishes to become the owner. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the selection (for example,
+<function>XA_PRIMARY ).</function>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the timestamp that indicates when the ownership request was
+initiated.
+This should be the timestamp of the event that triggered ownership;
+the value
+<function>CurrentTime</function>
+is not acceptable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>convert_proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called whenever a client requests the
+current value of the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>lose_selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called whenever the widget has
+lost selection ownership, or NULL if the owner is not interested in being
+called back.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>done_proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure called
+after the requestor has received the selection value, or NULL if the
+owner is not
+interested in being called back.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtOwnSelection' xrefstyle='select: title'/>
+function informs the Intrinsics selection mechanism that a
+widget wishes to own a selection.
+It returns
+<function>True</function>
+if the widget successfully becomes the owner and
+<function>False</function>
+otherwise.
+The widget may fail to become the owner if some other widget
+has asserted ownership at a time later than this widget.
+The widget can lose selection ownership either
+because some other widget asserted later ownership of the selection
+or because the widget voluntarily gave up ownership of the selection.
+The lose_selection procedure is not called
+if the widget fails to obtain selection ownership in the first place.
+</para>
+
+<para>
+If a done_proc is specified, the client owns the storage allocated
+for passing the value to the Intrinsics. If <emphasis remap='I'>done_proc</emphasis> is NULL,
+the convert_proc must allocate storage using
+<xref linkend='XtMalloc' xrefstyle='select: title'/>,
+<xref linkend='XtRealloc' xrefstyle='select: title'/>,
+or
+<xref linkend='XtCalloc' xrefstyle='select: title'/>,
+and the value specified is freed by the
+Intrinsics when the transfer is complete.
+</para>
+
+<para>
+Usually, a selection owner maintains ownership indefinitely until some
+other widget requests ownership, at which time
+the Intrinsics selection mechanism informs the previous owner that it
+has lost ownership of the selection.
+However, in response to some user actions
+(for example, when a user deletes the information selected),
+the application may wish to explicitly inform the Intrinsics
+by using
+<xref linkend='XtDisownSelection' xrefstyle='select: title'/>
+that it no longer is to be the selection owner.
+</para>
+
+<funcsynopsis id='XtDisownSelection'>
+<funcprototype>
+<funcdef>void <function>XtDisownSelection</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that wishes to relinquish ownership.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom naming the selection being given up.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the timestamp that indicates when the request to
+relinquish selection ownership was initiated.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtDisownSelection' xrefstyle='select: title'/>
+function informs the Intrinsics selection mechanism that
+the specified widget is to lose ownership of the selection.
+If the widget does not currently own the selection, either
+because it lost the selection
+or because it never had the selection to begin with,
+<xref linkend='XtDisownSelection' xrefstyle='select: title'/>
+does nothing.
+</para>
+
+<para>
+After a widget has called
+<xref linkend='XtDisownSelection' xrefstyle='select: title'/>,
+its convert procedure is not called even if a request arrives later
+with a timestamp during the period that this widget owned the selection.
+However, its done procedure is called if a conversion that started
+before the call to
+<xref linkend='XtDisownSelection' xrefstyle='select: title'/>
+finishes after the call to
+<xref linkend='XtDisownSelection' xrefstyle='select: title'/>.
+</para>
+</sect3>
+</sect2>
+
+<sect2 id="Using_Incremental_Transfers">
+<title>Using Incremental Transfers</title>
+<para>
+When using the incremental interface, an owner may have to process
+more than one selection request for the same selection, converted to
+the same target, at the same time. The incremental functions take a
+<emphasis remap='I'>request_id</emphasis> argument, which is an identifier that is guaranteed to be
+unique among all incremental requests that are active concurrently.
+</para>
+
+<para>
+For example, consider the following:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+Upon receiving a request for the selection value, the owner sends
+the first segment.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+While waiting to be called to provide the next segment value but
+before sending it, the owner receives another request from a
+different requestor for the same selection value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+To distinguish between the requests, the owner uses the request_id
+value. This allows the owner to distinguish between the first
+requestor, which is asking for the second segment, and the second
+requestor, which is asking for the first segment.
+ </para>
+ </listitem>
+</itemizedlist>
+<sect3 id="Incremental_Transfer_Procedures">
+<title>Incremental Transfer Procedures</title>
+<para>
+The following procedures are used by selection owners who wish to
+provide the selection data in multiple segments.
+</para>
+
+<para>
+The procedure pointer specified by the incremental owner to supply the
+selection data to the Intrinsics is of type
+<xref linkend='XtConvertSelectionIncrProc' xrefstyle='select: title'/>.
+</para>
+<programlisting>
+typedef XtPointer XtRequestId;
+</programlisting>
+
+<funcsynopsis id='XtConvertSelectionIncrProc'>
+<funcprototype>
+<funcdef>typedef Boolean <function>(*XtConvertSelectionIncrProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom *<parameter>selection</parameter></paramdef>
+ <paramdef>Atom *<parameter>target</parameter></paramdef>
+ <paramdef>Atom *<parameter>type_return</parameter></paramdef>
+ <paramdef>XtPointer *<parameter>value_return</parameter></paramdef>
+ <paramdef>unsigned long *<parameter>length_return</parameter></paramdef>
+ <paramdef>int *<parameter>format_return</parameter></paramdef>
+ <paramdef>unsigned long *<parameter>max_length</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>XtRequestId *<parameter>request_id</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that currently owns this selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom that names the selection requested.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of information required about the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to an atom into which the property
+type of the converted value of the selection is to be
+stored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer into which a pointer to the
+converted value of the selection is to be stored.
+The selection owner is responsible for allocating this storage.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer into which the number of elements
+in <emphasis remap='I'>value_return</emphasis>, each of size indicated by
+<emphasis remap='I'>format_return</emphasis>, is to be stored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer into which the size in bits of the
+data elements of the selection value is to be stored so that the
+server may byte-swap the data if necessary.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>max_length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the maximum number of bytes which may be
+transferred at any one time.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value passed in by the widget when it
+took ownership of the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request_id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an opaque identification for a specific request.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure is called repeatedly by the Intrinsics selection mechanism to get
+the next incremental chunk of data from a selection owner who has
+called
+<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>.
+It must return
+<function>True</function>
+if the procedure has succeeded in converting the selection data or
+<function>False</function>
+otherwise.
+On the first call with a particular request id, the owner must begin
+a new incremental transfer for the requested selection and target. On
+subsequent calls with the same request id, the owner may assume that
+the previously supplied value is no longer needed by the Intrinsics;
+that is, a fixed transfer area may be allocated and returned in <emphasis remap='I'>value_return</emphasis>
+for each segment to be transferred. This procedure should store a
+non-NULL value in <emphasis remap='I'>value_return</emphasis> and zero in <emphasis remap='I'>length_return</emphasis> to indicate that the
+entire selection has been delivered. After returning this final
+segment, the request id may be reused by the Intrinsics to begin a
+new transfer.
+</para>
+
+<para>
+To retrieve the
+<function>SelectionRequest</function>
+event that triggered the selection conversion procedure, use
+<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/>,
+described in Section 11.5.2.1.
+</para>
+
+<para>
+The procedure pointer specified by the incremental selection owner
+when it desires notification upon no longer having ownership is of
+type
+<xref linkend='XtLoseSelectionIncrProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtLoseSelectionIncrProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtLoseSelectionIncrProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom *<parameter>selection</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that has lost the selection ownership.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom that names the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value passed in by the widget when it
+took ownership of the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure, which is optional, is called by the Intrinsics to
+inform the selection owner that it no longer owns the selection.
+</para>
+
+<para>
+The procedure pointer specified by the incremental selection owner
+when it desires notification of receipt of the data or when it manages
+the storage containing the data is of type
+<xref linkend='XtSelectionDoneIncrProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSelectionDoneIncrProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtSelectionDoneIncrProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom *<parameter>selection</parameter></paramdef>
+ <paramdef>Atom *<parameter>target</parameter></paramdef>
+ <paramdef>XtRequestId *<parameter>request_id</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that owns the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom that names the selection being transferred.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target type to which the conversion was done.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request_id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an opaque identification for a specific request.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specified the value passed in by the widget when it
+took ownership of the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure, which is optional, is called by the Intrinsics after
+the requestor has retrieved the final (zero-length) segment of the
+incremental transfer to indicate that the entire transfer is complete.
+If this procedure is not specified, the Intrinsics will free only the
+final value returned by the selection owner using
+<xref linkend='XtFree' xrefstyle='select: title'/>.
+</para>
+
+<para>
+The procedure pointer specified by the incremental selection owner to
+notify it if a transfer should be terminated prematurely is of type
+<xref linkend='XtCancelConvertSelectionProc' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCancelConvertSelectionProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtCancelConvertSelectionProc)</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom *<parameter>selection</parameter></paramdef>
+ <paramdef>Atom *<parameter>target</parameter></paramdef>
+ <paramdef>XtRequestId *<parameter>request_id</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that owns the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom that names the selection being transferred.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target type to which the conversion was done.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request_id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an opaque identification for a specific request.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value passed in by the widget when it took ownership of
+the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This procedure is called by the Intrinsics when it has been determined
+by means of a timeout or other mechanism that any remaining segments
+of the selection no longer need to be transferred. Upon receiving
+this callback, the selection request is considered complete and the
+owner can free the memory and any other resources that have been
+allocated for the transfer.
+</para>
+</sect3>
+<sect3 id="Getting_the_Selection_Value_Incrementally">
+<title>Getting the Selection Value Incrementally</title>
+<para>
+To obtain the value of the selection using incremental transfers, use
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>
+or
+<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetSelectionValueIncremental'>
+<funcprototype>
+<funcdef>void <function>XtGetSelectionValueIncremental</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Atom <parameter>target</parameter></paramdef>
+ <paramdef>XtSelectionCallbackProc <parameter>selection_callback</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the particular selection desired.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of information needed
+about the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection_callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback procedure to be
+called to receive each data segment.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies client-specific data to be passed to
+the specified callback procedure when it is invoked.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the timestamp that indicates when the
+selection request was initiated. This should be the
+timestamp of the event that triggered this request;
+the value
+<function>CurrentTime</function>
+is not acceptable.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>
+function is similar to
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>
+except that the selection_callback procedure will
+be called repeatedly upon delivery of multiple segments of the
+selection value. The end of the selection value is indicated when
+<emphasis remap='I'>selection_callback</emphasis> is called with a non-NULL value of length zero,
+which must still be freed by the client. If the
+transfer of the selection is aborted in the middle of a transfer
+(for example, because of a timeout), the selection_callback procedure is
+called with a type value equal to the symbolic constant
+<function>XT_CONVERT_FAIL</function>
+so that the requestor can dispose
+of the partial selection value it has collected up until that point.
+Upon receiving
+<function>XT_CONVERT_FAIL</function>,
+the requesting client must determine
+for itself whether or not a partially completed data transfer is meaningful.
+For more information about <emphasis remap='I'>selection</emphasis>,
+<emphasis remap='I'>target</emphasis>, and
+<emphasis remap='I'>time</emphasis>, see
+Use of Selection Atoms in the
+Inter-Client Communication Conventions Manual.
+</para>
+
+<funcsynopsis id='XtGetSelectionValuesIncremental'>
+<funcprototype>
+<funcdef>void <function>XtGetSelectionValuesIncremental</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Atom *<parameter>targets</parameter></paramdef>
+ <paramdef>int <parameter>count</parameter></paramdef>
+ <paramdef>XtSelectionCallbackProc <parameter>selection_callback</parameter></paramdef>
+ <paramdef>XtPointer *<parameter>client_data</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the particular selection desired.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>targets</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the types of information needed about
+the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length of the <emphasis remap='I'>targets</emphasis> and <emphasis remap='I'>client_data</emphasis> lists.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection_callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback procedure to be called
+to receive each selection value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of client data (one for each target
+type) values that are passed to the callback procedure when
+it is invoked for the corresponding target.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the timestamp that indicates when the
+selection request was initiated. This should be the
+timestamp of the event that triggered this request;
+the value
+<function>CurrentTime</function>
+is not acceptable.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>
+function is similar to
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>
+except that it takes a list of targets and client data.
+<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>
+is equivalent to calling
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>
+successively for each <emphasis remap='I'>target/client_data</emphasis> pair except that
+<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>
+does guarantee that all the conversions will use the same selection
+value because the ownership of the selection cannot change in the
+middle of the list, as would be possible when calling
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>
+repeatedly.
+For more information about <emphasis remap='I'>selection</emphasis>, <emphasis remap='I'>target</emphasis>, and
+<emphasis remap='I'>time</emphasis>, see
+Section 2.6 in the
+Inter-Client Communication Conventions Manual.
+</para>
+</sect3>
+<sect3 id="Setting_the_Selection_Owner_for_Incremental_Transfers">
+<title>Setting the Selection Owner for Incremental Transfers</title>
+<para>
+To set the selection owner when using incremental transfers, use
+<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtOwnSelectionIncremental'>
+<funcprototype>
+<funcdef>Boolean <function>XtOwnSelectionIncremental</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+ <paramdef>XtConvertSelectionIncrProc <parameter>convert_callback</parameter></paramdef>
+ <paramdef>XtLoseSelectionIncrProc <parameter>lose_callback</parameter></paramdef>
+ <paramdef>XtSelectionDoneIncrProc <parameter>done_callback</parameter></paramdef>
+ <paramdef>XtCancelConvertSelectionProc <parameter>cancel_callback</parameter></paramdef>
+ <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that wishes to become the owner. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom that names the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the timestamp that indicates when the
+selection ownership request was initiated. This should be
+the timestamp of the event that triggered ownership; the value
+<function>CurrentTime</function>
+is not acceptable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>convert_callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called whenever
+the current value of the selection is requested.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>lose_callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called whenever
+the widget has lost selection ownership, or NULL if the
+owner is not interested in being notified.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>done_callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure called after the
+requestor has received the entire selection, or NULL if
+the owner is not interested in being notified.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>cancel_callback</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the callback procedure to be called
+when a selection request aborts because a timeout expires,
+or NULL if the owner is not interested in being notified.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the argument to be passed to each of
+the callback procedures when they are called.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>
+procedure informs the Intrinsics
+incremental selection mechanism that the specified widget wishes to
+own the selection. It returns
+<function>True</function>
+if the specified widget successfully becomes the selection owner or
+<function>False</function>
+otherwise.
+For more information about <emphasis remap='I'>selection</emphasis>, <emphasis remap='I'>target</emphasis>, and
+<emphasis remap='I'>time</emphasis>, see
+Section 2.6 in the
+Inter-Client Communication Conventions Manual.
+</para>
+
+<para>
+If a done_callback procedure is specified, the client owns the storage allocated
+for passing the value to the Intrinsics. If <emphasis remap='I'>done_callback</emphasis> is NULL,
+the convert_callback procedure must allocate storage using
+<xref linkend='XtMalloc' xrefstyle='select: title'/>,
+<xref linkend='XtRealloc' xrefstyle='select: title'/>,
+or
+<xref linkend='XtCalloc' xrefstyle='select: title'/>,
+and the final value specified is freed by the
+Intrinsics when the transfer is complete. After a selection transfer
+has started, only one of the done_callback or cancel_callback
+procedures is invoked to indicate completion of the transfer.
+</para>
+
+<para>
+The lose_callback procedure does not indicate completion of any in-progress
+transfers; it is invoked at the time a
+<function>SelectionClear</function>
+event is dispatched regardless of any active transfers, which are still
+expected to continue.
+</para>
+
+<para>
+A widget that becomes the selection owner using
+<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>
+may use
+<xref linkend='XtDisownSelection' xrefstyle='select: title'/>
+to relinquish selection ownership.
+</para>
+</sect3>
+</sect2>
+
+<sect2 id="Setting_and_Retrieving_Selection_Target_Parameters">
+<title>Setting and Retrieving Selection Target Parameters</title>
+<para>
+To specify target parameters for a selection request with a single target,
+use
+<xref linkend='XtSetSelectionParameters' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetSelectionParameters'>
+<funcprototype>
+<funcdef>void <function>XtSetSelectionParameters</function></funcdef>
+ <paramdef>Widget <parameter>requestor</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Atom <parameter>type</parameter></paramdef>
+ <paramdef>XtPointer <parameter>value</parameter></paramdef>
+ <paramdef>unsigned long <parameter>length</parameter></paramdef>
+ <paramdef>int <parameter>format</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>requestor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom that names the selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of the property in which the parameters are passed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of elements containing data in <emphasis remap='I'>value</emphasis>,
+each element of a size indicated by <emphasis remap='I'>format</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size in bits of the data in the elements of <emphasis remap='I'>value</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The specified parameters are copied and stored in a new property
+of the specified type and format on the requestor's window. To initiate
+a selection request with a target and these parameters, a subsequent
+call to
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>
+or to
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>
+specifying the same requestor widget and selection atom will generate a
+<function>ConvertSelection</function>
+request referring to the property containing the parameters. If
+<xref linkend='XtSetSelectionParameters' xrefstyle='select: title'/>
+is called more than once with the same widget and selection without
+a call to specify a request, the most recently specified parameters
+are used in the subsequent request.
+</para>
+
+<para>
+The possible values of <emphasis remap='I'>format</emphasis> are 8, 16, or 32. If the format is 8,
+the elements of <emphasis remap='I'>value</emphasis> are assumed to be sizeof(char);
+if 16, sizeof(short); if 32, sizeof(long).
+</para>
+
+<para>
+To generate a MULTIPLE
+target request with parameters for any of the multiple targets of the
+selection request, precede individual calls to
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>
+and
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>
+with corresponding individual calls to
+<xref linkend='XtSetSelectionParameters' xrefstyle='select: title'/>,
+and enclose these all within
+<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>
+and
+<function>XtSendSelectionRequest.</function>
+<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>
+and
+<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>
+cannot be used to make selection requests with parameterized targets.
+</para>
+
+<para>
+To retrieve any target parameters needed to perform a selection conversion,
+the selection owner calls
+<xref linkend='XtGetSelectionParameters' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetSelectionParameters'>
+<funcprototype>
+<funcdef>void <function>XtGetSelectionParameters</function></funcdef>
+ <paramdef>Widget <parameter>owner</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>XtRequestId <parameter>request_id</parameter></paramdef>
+ <paramdef>Atom *<parameter>type_return</parameter></paramdef>
+ <paramdef>XtPointer *<parameter>value_return</parameter></paramdef>
+ <paramdef>unsigned long *<parameter>length_return</parameter></paramdef>
+ <paramdef>int *<parameter>format_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget that owns the specified selection.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the selection being processed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>request_id</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the requestor id in the case of incremental selections,
+or NULL in the case of atomic transfers.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to an atom in which the property type
+of the parameters is stored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer into which a pointer to the parameters is to be stored.
+A NULL is stored if no parameters accompany the request.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>length_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer into which the number of data elements
+in <emphasis remap='I'>value_return</emphasis> of size indicated by <emphasis remap='I'>format_return</emphasis> are stored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer into which the size in bits of the parameter data
+in the elements of <emphasis remap='I'>value</emphasis> is stored.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGetSelectionParameters' xrefstyle='select: title'/>
+may be called only from within an
+<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/>
+or from within the first call to an
+<xref linkend='XtConvertSelectionIncrProc' xrefstyle='select: title'/>
+with a new request_id.
+</para>
+
+<para>
+It is the responsibility of the caller to free the returned parameters using
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when the parameters are no longer needed.
+</para>
+</sect2>
+
+<sect2 id="Generating_MULTIPLE_Requests">
+<title>Generating MULTIPLE Requests</title>
+<para>
+To have the Intrinsics bundle multiple calls to make selection requests into
+a single request using a <emphasis role='strong'>MULTIPLE</emphasis> target, use
+<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>
+and
+<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCreateSelectionRequest'>
+<funcprototype>
+<funcdef>void <function>XtCreateSelectionRequest</function></funcdef>
+ <paramdef>Widget <parameter>requestor</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>requestor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the particular selection desired.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+When
+<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>
+is called, subsequent calls to
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>,
+and
+<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>,
+with the requestor and selection as specified to
+<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>,
+are bundled into a single selection request with
+multiple targets. The request is made by calling
+<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSendSelectionRequest'>
+<funcprototype>
+<funcdef>void <function>XtSendSelectionRequest</function></funcdef>
+ <paramdef>Widget <parameter>requestor</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Time <parameter>time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>requestor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the particular selection desired.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>time</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the timestamp that indicates when the selection request was
+initiated. The value
+<function>CurrentTime</function>
+is not acceptable.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+When
+<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/>
+is called with a value of <emphasis remap='I'>requestor</emphasis> and <emphasis remap='I'>selection</emphasis> matching
+a previous call to
+<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>,
+a selection request is sent to the selection owner.
+If a single target request is queued, that request is made.
+If multiple targets are queued, they are bundled into a single request
+with a target of MULTIPLE using the specified timestamp.
+As the values are returned, the callbacks specified in
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>,
+and
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>
+are invoked.
+</para>
+
+<para>
+Multi-threaded applications should lock the application context before
+calling
+<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>
+and release the lock after calling
+<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/>
+to ensure that the thread assembling the request is safe from interference
+by another thread assembling a different request naming the same widget
+and selection.
+</para>
+
+<para>
+To relinquish the composition of a MULTIPLE request without sending it, use
+<xref linkend='XtCancelSelectionRequest' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtCancelSelectionRequest'>
+<funcprototype>
+<funcdef>void <function>XtCancelSelectionRequest</function></funcdef>
+ <paramdef>Widget <parameter>requestor</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>requestor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making the request. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the particular selection desired.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+When
+<xref linkend='XtCancelSelectionRequest' xrefstyle='select: title'/>
+is called, any requests queued since the last call to
+<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>
+for the same widget and selection are discarded
+and any resources reserved are released.
+A subsequent call to
+<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/>
+will not result in any request being made.
+Subsequent calls to
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>,
+or
+<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>
+will not be deferred.
+</para>
+</sect2>
+
+<sect2 id="Auxiliary_Selection_Properties">
+<title>Auxiliary Selection Properties</title>
+<para>
+Certain uses of parameterized selections require clients to name
+other window properties within a selection parameter. To permit
+reuse of temporary property names in these circumstances and
+thereby reduce the number of unique atoms created in the server,
+the Intrinsics provides two interfaces for acquiring temporary property names.
+</para>
+
+<para>
+To acquire a temporary property name atom for use in a selection
+request, the client may call
+<xref linkend='XtReservePropertyAtom' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtReservePropertyAtom'>
+<funcprototype>
+<funcdef>Atom <function>XtReservePropertyAtom</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget making a selection request.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtReservePropertyAtom' xrefstyle='select: title'/>
+returns an atom that may be used as a property name during selection
+requests involving the specified widget.
+As long as the atom remains reserved, it is unique with respect to all
+other reserved atoms for the widget.
+</para>
+
+<para>
+To return a temporary property name atom for reuse and to delete
+the property named by that atom, use
+<xref linkend='XtReleasePropertyAtom' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtReleasePropertyAtom'>
+<funcprototype>
+<funcdef>void <function>XtReleasePropertyAtom</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>atom</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget used to reserve the property name atom.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>atom</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name atom returned by
+<xref linkend='XtReservePropertyAtom' xrefstyle='select: title'/>
+that is to be released for reuse.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtReleasePropertyAtom' xrefstyle='select: title'/>
+marks the specified property name atom as
+no longer in use and ensures that any property having that name
+on the specified widget's window is deleted. If <emphasis remap='I'>atom</emphasis> does not
+specify a value returned by
+<xref linkend='XtReservePropertyAtom' xrefstyle='select: title'/>
+for the specified widget, the results are undefined.
+</para>
+</sect2>
+
+<sect2 id="Retrieving_the_Most_Recent_Timestamp">
+<title>Retrieving the Most Recent Timestamp</title>
+<para>
+To retrieve the timestamp from the most recent call to
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+that contained a timestamp, use
+<xref linkend='XtLastTimestampProcessed' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtLastTimestampProcessed'>
+<funcprototype>
+<funcdef>Time <function>XtLastTimestampProcessed</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an open display connection.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If no
+<function>KeyPress</function>,
+<function>KeyRelease</function>,
+<function>ButtonPress</function>,
+<function>ButtonRelease</function>,
+<function>MotionNotify</function>,
+<function>EnterNotify</function>,
+<function>LeaveNotify</function>,
+<function>PropertyNotify</function>,
+or
+<function>SelectionClear</function>
+event has yet been passed to
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+for the specified display,
+<xref linkend='XtLastTimestampProcessed' xrefstyle='select: title'/>
+returns zero.
+</para>
+</sect2>
+
+<sect2 id="Retrieving_the_Most_Recent_Event">
+<title>Retrieving the Most Recent Event</title>
+<para>
+To retrieve the event from the most recent call to
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+for a specific display, use
+<xref linkend='XtLastEventProcessed' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtLastEventProcessed'>
+<funcprototype>
+<funcdef>XEvent *<function>XtLastEventProcessed</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display connection from which to retrieve the event.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Returns the last event passed to
+<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
+for the specified display. Returns NULL if there is no such event.
+The client must not modify the contents of the returned event.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Merging_Exposure_Events_into_a_Region">
+<title>Merging Exposure Events into a Region</title>
+<para>
+The Intrinsics provide an
+<xref linkend='XtAddExposureToRegion' xrefstyle='select: title'/>
+utility function that merges
+<function>Expose</function>
+and
+<function>GraphicsExpose</function>
+events into a region for clients to process at once
+rather than processing individual rectangles.
+For further information about regions,
+see Manipulating Regions
+in
+Xlib — C Language X Interface.
+</para>
+
+<para>
+To merge
+<function>Expose</function>
+and
+<function>GraphicsExpose</function>
+events into a region, use
+<xref linkend='XtAddExposureToRegion' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAddExposureToRegion'>
+<funcprototype>
+<funcdef>void <function>XtAddExposureToRegion</function></funcdef>
+ <paramdef>XEvent *<parameter>event</parameter></paramdef>
+ <paramdef>Region <parameter>region</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>event</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to the
+<function>Expose</function>
+or
+<function>GraphicsExpose</function>
+event.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>region</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the region object (as defined in
+<filename class="headerfile"><X11/Xutil.h></filename>).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAddExposureToRegion' xrefstyle='select: title'/>
+function computes the union of the rectangle defined by the exposure
+event and the specified region.
+Then it stores the results back in <emphasis remap='I'>region</emphasis>.
+If the event argument is not an
+<function>Expose</function>
+or
+<function>GraphicsExpose</function>
+event,
+<xref linkend='XtAddExposureToRegion' xrefstyle='select: title'/>
+returns without an error and without modifying <emphasis remap='I'>region</emphasis>.
+</para>
+
+<para>
+This function is used by the exposure compression mechanism;
+see <xref linkend='Exposure_Compression' />
+</para>
+</sect1>
+
+<sect1 id="Translating_Widget_Coordinates">
+<title>Translating Widget Coordinates</title>
+<para>
+To translate an x-y coordinate pair from widget coordinates to root
+window absolute coordinates, use
+<xref linkend='XtTranslateCoords' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtTranslateCoords'>
+<funcprototype>
+<funcdef>void <function>XtTranslateCoords</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>Position <parameter>x</parameter></paramdef>
+ <paramdef>Position <parameter>y</parameter></paramdef>
+ <paramdef>Position *<parameter>rootx_return</parameter></paramdef>
+ <paramdef>Position *<parameter>rooty_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget. Must be of class RectObj or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>x</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>y</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the widget-relative x and y coordinates.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rootx_return</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>rooty_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the root-relative x and y coordinates.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+While
+<xref linkend='XtTranslateCoords' xrefstyle='select: title'/>
+is similar to the Xlib
+<function>XTranslateCoordinates</function>
+function, it does not generate a server request because all the required
+information already is in the widget's data structures.
+</para>
+</sect1>
+
+<sect1 id="Translating_a_Window_to_a_Widget">
+<title>Translating a Window to a Widget</title>
+<para>
+To translate a given window and display pointer into a widget instance, use
+<xref linkend='XtWindowToWidget' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtWindowToWidget'>
+<funcprototype>
+<funcdef>Widget <function>XtWindowToWidget</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Window <parameter>window</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display on which the window is defined.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>window</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable for which you want the widget.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If there is a realized widget whose window is the specified drawable on
+the specified <emphasis remap='I'>display</emphasis>,
+<xref linkend='XtWindowToWidget' xrefstyle='select: title'/>
+returns that widget.
+If not and if the drawable has been associated with a widget through
+<xref linkend='XtRegisterDrawable' xrefstyle='select: title'/>,
+<xref linkend='XtWindowToWidget' xrefstyle='select: title'/>
+returns the widget associated with the drawable. In other cases it
+returns NULL.
+</para>
+</sect1>
+
+<sect1 id="Handling_Errors">
+<title>Handling Errors</title>
+<para>
+The Intrinsics allow a client to register procedures that are called
+whenever a fatal or nonfatal error occurs.
+These facilities are intended for both error reporting and logging
+and for error correction or recovery.
+</para>
+
+<para>
+Two levels of interface are provided:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+A high-level interface that takes an error
+name and class and retrieves the error message text from
+an error resource database.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A low-level interface that takes a simple string to display.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+The high-level functions construct a string to pass to the lower-level
+interface.
+The strings may be specified in application code and are
+overridden by the contents of an external systemwide file,
+the “error database file”. The location and name of this file are
+implementation-dependent.
+</para>
+<note>
+<para>
+The application-context-specific error handling is not
+implemented on many systems, although the interfaces are
+always present.
+Most implementations will have just one set of error handlers
+for all application contexts within a process.
+If they are set for different application contexts,
+the ones registered last will prevail.
+</para>
+</note>
+
+<para>
+To obtain the error database (for example, to merge with
+an application- or widget-specific database), use
+<xref linkend='XtAppGetErrorDatabase' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppGetErrorDatabase'>
+<funcprototype> <funcdef>XrmDatabase *<function>XtAppGetErrorDatabase</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppGetErrorDatabase' xrefstyle='select: title'/>
+function returns the address of the error database.
+The Intrinsics do a lazy binding of the error database and do not merge in the
+database file until the first call to
+<xref linkend='XtAppGetErrorDatabaseText' xrefstyle='select: title'/>.
+</para>
+
+<para>
+For a complete listing of all errors and warnings
+that can be generated by the Intrinsics, see <xref linkend='Intrinsics_Error_Messages' />
+</para>
+
+<para>
+The high-level error and warning handler procedure pointers are of type
+<xref linkend='XtErrorMsgHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtErrorMsgHandler'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtErrorMsgHandler)</function></funcdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>String <parameter>type</parameter></paramdef>
+ <paramdef>String <parameter>class</parameter></paramdef>
+ <paramdef>String <parameter>defaultp</parameter></paramdef>
+ <paramdef>String *<parameter>params</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_params</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name to be concatenated with the specified type to form
+the resource name of the error message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type to be concatenated with the name to form the
+resource name of the error message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class of the error message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>defaultp</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the default message to use if no error database entry is found.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to a list of parameters to be substituted in the message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The specified name can be a general kind of error,
+like “invalidParameters” or “invalidWindow”,
+and the specified type gives extra information
+such as the name of the routine in which the error was detected.
+Standard
+<function>printf</function>
+notation is used to substitute the parameters into the message.
+</para>
+
+<para>
+An error message handler can obtain the error database text for an
+error or a warning by calling
+<xref linkend='XtAppGetErrorDatabaseText' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppGetErrorDatabaseText'>
+<funcprototype>
+<funcdef>void <function>XtAppGetErrorDatabaseText</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>const char * <parameter>name</parameter></paramdef>
+ <paramdef>const char * <parameter>type</parameter></paramdef>
+ <paramdef>const char * <parameter>class</parameter></paramdef>
+ <paramdef>const char * <parameter>default</parameter></paramdef>
+ <paramdef>char * <parameter>buffer_return</parameter></paramdef>
+ <paramdef>int <parameter>nbytes</parameter></paramdef>
+ <paramdef>XrmDatabase <parameter>database</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify the name and type concatenated to form the resource name
+of the error message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class of the error message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>default</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the default message to use if an error database entry is not found.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buffer_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer into which the error message is to be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nbytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the buffer in bytes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the alternative database to be used,
+or NULL if the application context's error database is to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<xref linkend='XtAppGetErrorDatabaseText' xrefstyle='select: title'/>
+returns the appropriate message from the error database
+or returns the specified default message if one is not found in the
+error database.
+To form the full resource name and class when querying the database,
+the <emphasis remap='I'>name</emphasis> and <emphasis remap='I'>type</emphasis> are concatenated with a single “.”
+between them and the <emphasis remap='I'>class</emphasis> is concatenated with itself with a
+single “.” if it does not already contain a “.”.
+</para>
+
+<para>
+To return the application name and class as passed to
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+for a particular Display, use
+<xref linkend='XtGetApplicationNameAndClass' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetApplicationNameAndClass'>
+<funcprototype>
+<funcdef>void <function>XtGetApplicationNameAndClass</function></funcdef>
+ <paramdef>Display* <parameter>display</parameter></paramdef>
+ <paramdef>String* <parameter>name_return</parameter></paramdef>
+ <paramdef>String* <parameter>class_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an open display connection that has been initialized with
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the application name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the application class.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGetApplicationNameAndClass' xrefstyle='select: title'/>
+returns the application name and class passed to
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+for the specified display. If the display was
+never initialized or has been closed, the result is undefined. The
+returned strings are owned by the Intrinsics and must not be modified
+or freed by the caller.
+</para>
+
+<para>
+To register a procedure to be called on fatal error conditions, use
+<xref linkend='XtAppSetErrorMsgHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppSetErrorMsgHandler'>
+<funcprototype>
+<funcdef>XtErrorMsgHandler <function>XtAppSetErrorMsgHandler</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtErrorMsgHandler <parameter>msg_handler</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>msg_handler</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new fatal error procedure, which should not return.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppSetErrorMsgHandler' xrefstyle='select: title'/>
+returns a pointer to the previously
+installed high-level fatal error handler.
+The default high-level fatal error handler provided by the Intrinsics is named
+<function>_XtDefaultErrorMsg</function>
+and constructs a string from the error resource database and calls
+<xref linkend='XtError' xrefstyle='select: title'/>.
+Fatal error message handlers should not return.
+If one does,
+subsequent Intrinsics behavior is undefined.
+</para>
+
+<para>
+To call the high-level error handler, use
+<xref linkend='XtAppErrorMsg' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppErrorMsg'>
+<funcprototype>
+<funcdef>void <function>XtAppErrorMsg</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>const char * <parameter>name</parameter></paramdef>
+ <paramdef>const char * <parameter>type</parameter></paramdef>
+ <paramdef>const char * <parameter>class</parameter></paramdef>
+ <paramdef>const char * <parameter>default</parameter></paramdef>
+ <paramdef>String * <parameter>params</parameter></paramdef>
+ <paramdef>Cardinal * <parameter>num_params</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the general kind of error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the detailed name of the error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>default</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the default message to use if an error database entry is not found.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to a list of values to be stored in the message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The Intrinsics internal errors all have class
+“XtToolkitError”.
+</para>
+
+<para>
+To register a procedure to be called on nonfatal error conditions, use
+<xref linkend='XtAppSetWarningMsgHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppSetWarningMsgHandler'>
+<funcprototype>
+<funcdef>XtErrorMsgHandler <function>XtAppSetWarningMsgHandler</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtErrorMsgHandler <parameter>msg_handler</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>msg_handler</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new nonfatal error procedure, which usually returns.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppSetWarningMsgHandler' xrefstyle='select: title'/>
+returns a pointer to the previously
+installed high-level warning handler.
+The default high-level warning handler provided by the Intrinsics is named
+<function>_XtDefaultWarningMsg</function>
+and constructs a string
+from the error resource database and calls
+<xref linkend='XtWarning' xrefstyle='select: title'/>.
+</para>
+
+<para>
+To call the installed high-level warning handler, use
+<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppWarningMsg'>
+<funcprototype>
+<funcdef>void <function>XtAppWarningMsg</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>const char * <parameter>name</parameter></paramdef>
+ <paramdef>const char * <parameter>type</parameter></paramdef>
+ <paramdef>const char * <parameter>class</parameter></paramdef>
+ <paramdef>const char * <parameter>default</parameter></paramdef>
+ <paramdef>String * <parameter>params</parameter></paramdef>
+ <paramdef>Cardinal * <parameter>num_params</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the general kind of error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the detailed name of the error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>default</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the default message to use if an error database entry is not found.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a pointer to a list of values to be stored in the message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_params</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The Intrinsics internal warnings all have class
+“XtToolkitError”.
+</para>
+
+<para>
+The low-level error and warning handler procedure pointers are of type
+<xref linkend='XtErrorHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtErrorHandler'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtErrorHandler)</function></funcdef>
+ <paramdef>String <parameter>message</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>message</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the error message.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The error handler should display the message string in some appropriate fashion.
+</para>
+
+<para>
+To register a procedure to be called on fatal error conditions, use
+<xref linkend='XtAppSetErrorHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppSetErrorHandler'>
+<funcprototype>
+<funcdef>XtErrorHandler <function>XtAppSetErrorHandler</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtErrorHandler <parameter>handler</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>handler</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new fatal error procedure, which should not return.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppSetErrorHandler' xrefstyle='select: title'/>
+returns a pointer to the previously installed
+low-level fatal error handler.
+The default low-level error handler provided by the Intrinsics is
+<function>_XtDefaultError</function>.
+On POSIX-based systems,
+it prints the message to standard error and terminates the application.
+Fatal error message handlers should not return.
+If one does,
+subsequent Intrinsics behavior is undefined.
+</para>
+
+<para>
+To call the installed fatal error procedure, use
+<xref linkend='XtAppError' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppError'>
+<funcprototype>
+<funcdef>void <function>XtAppError</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>const char * <parameter>message</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>message</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the message to be reported.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Most programs should use
+<xref linkend='XtAppErrorMsg' xrefstyle='select: title'/>,
+not
+<xref linkend='XtAppError' xrefstyle='select: title'/>,
+to provide for customization and internationalization of error messages.
+</para>
+
+<para>
+To register a procedure to be called on nonfatal error conditions, use
+<xref linkend='XtAppSetWarningHandler' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppSetWarningHandler'>
+<funcprototype>
+<funcdef>XtErrorHandler <function>XtAppSetWarningHandler</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>XtErrorHandler <parameter>handler</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>handler</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the new nonfatal error procedure, which usually returns.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtAppSetWarningHandler' xrefstyle='select: title'/>
+returns a pointer to the previously installed
+low-level warning handler.
+The default low-level warning handler provided by the Intrinsics is
+<function>_XtDefaultWarning</function>.
+On POSIX-based systems,
+it prints the message to standard error and returns to the caller.
+</para>
+
+<para>
+To call the installed nonfatal error procedure, use
+<xref linkend='XtAppWarning' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtAppWarning'>
+<funcprototype>
+<funcdef>void <function>XtAppWarning</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>const char * <parameter>message</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>message</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the nonfatal error message to be reported.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Most programs should use
+<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>,
+not
+<xref linkend='XtAppWarning' xrefstyle='select: title'/>,
+to provide for customization and internationalization of warning messages.
+</para>
+</sect1>
+
+<sect1 id="Setting_WM_COLORMAP_WINDOWS">
+<title>Setting WM_COLORMAP_WINDOWS</title>
+<para>
+A client may set the value of the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis>
+property on a widget's window by calling
+<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtSetWMColormapWindows'>
+<funcprototype>
+<funcdef>void <function>XtSetWMColormapWindows</function></funcdef>
+ <paramdef>Widget <parameter>widget</parameter></paramdef>
+ <paramdef>Widget* <parameter>list</parameter></paramdef>
+ <paramdef>Cardinal <parameter>count</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>widget</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the widget on whose window the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis>
+property is stored. Must be of class Core or any subclass thereof.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of widgets whose windows are potentially to be
+listed in the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis> property.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of widgets in <emphasis remap='I'>list</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>
+returns immediately if <emphasis remap='I'>widget</emphasis> is not realized or if <emphasis remap='I'>count</emphasis> is 0.
+Otherwise,
+<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>
+constructs an ordered list of windows
+by examining each widget in <emphasis remap='I'>list</emphasis> in turn and
+ignoring the widget if it is not realized, or
+adding the widget's window to the window list if the widget is realized
+and if its colormap resource is different from the colormap
+resources of all widgets whose windows are already on the window list.
+</para>
+
+<para>
+Finally,
+<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>
+stores the resulting window list in the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis>
+property on the specified widget's window.
+Refer to Section 4.1.8 in the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis> for details of
+the semantics of the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis> property.
+</para>
+</sect1>
+<!-- FIXME: -->
+<sect1 id="Finding_File_Names">
+<title>Finding File Names</title>
+<para>
+The Intrinsics provide procedures to look for a file by name, allowing
+string substitutions in a list of file specifications. Two
+routines are provided for this:
+<xref linkend='XtFindFile' xrefstyle='select: title'/>
+and
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>.
+<xref linkend='XtFindFile' xrefstyle='select: title'/>
+uses an arbitrary set of client-specified substitutions, and
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
+uses a set of standard substitutions corresponding
+to the <emphasis remap='I'>X/Open Portability Guide</emphasis> language localization conventions.
+Most applications should use
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>.
+</para>
+
+<para>
+A string substitution is defined by a list of
+<function>Substitution</function>
+entries.
+</para>
+<programlisting>
+typedef struct {
+ char match;
+ String substitution;
+} SubstitutionRec, *Substitution;
+</programlisting>
+<para>
+File name evaluation is handled in an operating-system-dependent
+fashion by an
+<xref linkend='XtFilePredicate' xrefstyle='select: title'/>
+procedure.
+</para>
+
+<funcsynopsis id='XtFilePredicate'>
+<funcprototype>
+<funcdef>typedef Boolean <function>(*XtFilePredicate)</function></funcdef>
+ <paramdef>String <parameter>filename</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>filename</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a potential filename.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+A file predicate procedure is called with a string that is
+potentially a file name. It should return
+<function>True</function>
+if this string specifies a file that is appropriate for the intended use and
+<function>False</function>
+otherwise.
+</para>
+
+<para>
+To search for a file using substitutions in a path list, use
+<xref linkend='XtFindFile' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtFindFile'>
+<funcprototype>
+<funcdef>char * <function>XtFindFile</function></funcdef>
+ <paramdef>const char * <parameter>path</parameter></paramdef>
+ <paramdef>Substitution <parameter>substitutions</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_substitutions</parameter></paramdef>
+ <paramdef>XtFilePredicate <parameter>predicate</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>path</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a path of file names, including substitution characters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>substitutions</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of substitutions to make into the path.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_substitutions</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of substitutions passed in.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>predicate</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a procedure called to judge each potential file name, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The <emphasis remap='I'>path</emphasis> parameter specifies a string that consists of a series of
+potential file names delimited by colons. Within each name, the
+percent character specifies a string substitution selected by the
+following character. The character sequence “%:” specifies an
+embedded colon that is not a delimiter; the sequence is replaced by a
+single colon. The character sequence “%%” specifies a percent
+character that does not introduce a substitution; the sequence is
+replaced by a single percent character. If a percent character is
+followed by any other character,
+<xref linkend='XtFindFile' xrefstyle='select: title'/>
+looks through the
+specified <emphasis remap='I'>substitutions</emphasis> for that character in the <emphasis remap='I'>match</emphasis> field
+and, if found,
+replaces the percent and match characters with the string in the
+corresponding <emphasis remap='I'>substitution</emphasis> field. A <emphasis remap='I'>substitution</emphasis> field entry of NULL
+is equivalent to a pointer to an empty string. If the operating
+system does not interpret multiple embedded name separators in the
+path (i.e., “/” in POSIX) the same way as a single separator,
+<xref linkend='XtFindFile' xrefstyle='select: title'/>
+will collapse multiple separators into a single one after performing
+all string substitutions. Except for collapsing embedded separators,
+the contents of the string substitutions are not interpreted by
+<xref linkend='XtFindFile' xrefstyle='select: title'/>
+and may therefore contain any operating-system-dependent
+characters, including additional name separators. Each resulting
+string is passed to the predicate procedure until a string is found for
+which the procedure returns
+<function>True</function>;
+this string is the return value for
+<xref linkend='XtFindFile' xrefstyle='select: title'/>.
+If no string yields a
+<function>True</function>
+return from the predicate,
+<xref linkend='XtFindFile' xrefstyle='select: title'/>
+returns NULL.
+</para>
+
+<para>
+If the <emphasis remap='I'>predicate</emphasis> parameter is NULL, an internal procedure that checks
+if the file exists, is readable, and is not a directory is used.
+</para>
+
+<para>
+It is the responsibility of the caller to free the returned string using
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when it is no longer needed.
+</para>
+
+<para>
+To search for a file using standard substitutions in a path list, use
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtResolvePathname'>
+<funcprototype>
+<funcdef>char * <function>XtResolvePathname</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>const char * <parameter>type</parameter></paramdef>
+ <paramdef>const char * <parameter>filename</parameter></paramdef>
+ <paramdef>const char * <parameter>suffix</parameter></paramdef>
+ <paramdef>const char * <parameter>path</parameter></paramdef>
+ <paramdef>Substitution <parameter>substitutions</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_substitutions</parameter></paramdef>
+ <paramdef>XtFilePredicate <parameter>predicate</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the display to use to find the language for language substitutions.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>filename</emphasis>
+ </term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>suffix</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specify values to substitute into the path.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>path</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of file specifications, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>substitutions</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of additional substitutions to make into the path, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_substitutions</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in <emphasis remap='I'>substitutions</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>predicate</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a procedure called to judge each potential file name, or NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The substitutions specified by
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
+are determined from the value of the language string retrieved by
+<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
+for the specified display.
+To set the
+language for all applications specify “*xnlLanguage: <emphasis remap='I'>lang</emphasis>” in the
+resource database.
+The format and content of the language string are
+implementation-defined. One suggested syntax is to compose
+the language string of three parts; a “language part”, a
+“territory part” and a “codeset part”. The manner in which
+this composition is accomplished is implementation-defined,
+and the Intrinsics make no interpretation of the parts other
+than to use them in substitutions as described below.
+</para>
+
+
+<para>
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
+calls
+<xref linkend='XtFindFile' xrefstyle='select: title'/>
+with the following substitutions
+in addition to any passed by the caller and returns the value returned by
+<xref linkend='XtFindFile' xrefstyle='select: title'/>:
+</para>
+<!-- PROBLEM BELOW HERE -->
+
+
+<variablelist>
+ <varlistentry>
+ <term>
+%N
+ </term>
+ <listitem>
+ <para>
+The value of the <emphasis remap='I'>filename</emphasis> parameter, or the application's
+class name if <emphasis remap='I'>filename</emphasis> is NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+%T
+ </term>
+ <listitem>
+ <para>
+The value of the <emphasis remap='I'>type</emphasis> parameter.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+%S
+ </term>
+ <listitem>
+ <para>
+The value of the <emphasis remap='I'>suffix</emphasis> parameter.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+%L
+ </term>
+ <listitem>
+ <para>
+The language string associated with the specified display.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+%l
+ </term>
+ <listitem>
+ <para>
+The language part of the display's language string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+%t
+ </term>
+ <listitem>
+ <para>
+The territory part of the display's language string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+%c
+ </term>
+ <listitem>
+ <para>
+The codeset part of the display's language string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+%C
+ </term>
+ <listitem>
+ <para>
+The customization string retrieved from the resource
+database associated with <emphasis remap='I'>display</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+%D
+ </term>
+ <listitem>
+ <para>
+The value of the implementation-specific default path.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+
+<!-- PROBLEM ABOVE HERE -->
+<para>
+If a path is passed to
+<xref linkend='XtResolvePathname' xrefstyle='select: title'/>,
+it is passed along to
+<xref linkend='XtFindFile' xrefstyle='select: title'/>.
+If the <emphasis remap='I'>path</emphasis> argument is NULL, the value of the
+<emphasis role='strong'>XFILESEARCHPATH</emphasis>
+environment variable is passed to
+<xref linkend='XtFindFile' xrefstyle='select: title'/>.
+If <emphasis role='strong'>XFILESEARCHPATH</emphasis>
+is not defined, an implementation-specific default path is used
+that contains at least six entries. These entries
+must contain the following substitutions:
+</para>
+
+
+<!-- OK PAST HERE -->
+
+<programlisting>
+1. %C, %N, %S, %T, %L or %C, %N, %S, %T, %l, %t, %c
+2. %C, %N, %S, %T, %l
+3. %C, %N, %S, %T
+4. %N, %S, %T, %L or %N, %S, %T, %l, %t, %c
+5. %N, %S, %T, %l
+6. %N, %S, %T
+</programlisting>
+
+<para>
+The order of these six entries within the path must be as given above.
+The order and use of substitutions within a given entry
+are implementation-dependent.
+If the path begins
+with a colon, it is preceded by %N%S. If the path includes two
+adjacent colons, <function>%N%S</function> is inserted between them.
+</para>
+
+<para>
+The <emphasis remap='I'>type</emphasis> parameter is intended to be a category of files, usually
+being translated into a directory in the pathname. Possible values
+might include “app-defaults”, “help”, and “bitmap”.
+</para>
+
+<para>
+The <emphasis remap='I'>suffix</emphasis> parameter is intended to be appended to the file name.
+Possible values might include “.txt”, “.dat”, and “.bm”.
+</para>
+
+<para>
+A suggested value for the default path on POSIX-based systems is
+</para>
+<programlisting>
+ /usr/lib/X11/%L/%T/%N%C%S:/usr/lib/X11/%l/%T/%N%C%S:\
+ /usr/lib/X11/%T/%N%C%S:/usr/lib/X11/%L/%T/%N%S:\
+ /usr/lib/X11/%l/%T/%N%S:/usr/lib/X11/%T/%N%S
+</programlisting>
+
+
+<para>
+Using this example, if the user has specified a language, it is
+used as a subdirectory of /usr/lib/X11 that is searched for other
+files. If the desired file is not found there, the lookup is
+tried again using just the language part of the specification. If the
+file is not there, it is looked for in /usr/lib/X11. The <emphasis remap='I'>type</emphasis>
+parameter is used as a subdirectory of the language directory or of
+/usr/lib/X11, and <emphasis remap='I'>suffix</emphasis> is appended to the file name.
+</para>
+
+<para>
+The %D substitution allows the addition of path
+elements to the implementation-specific default path, typically to
+allow additional directories to be searched without preventing
+resources in the system directories from being found. For example, a
+user installing resource files under a directory called “ourdir”
+might set
+<emphasis role='strong'>XFILESEARCHPATH</emphasis>
+to
+</para>
+<programlisting>
+ %D:ourdir/%T/%N%C:ourdir/%T/%N
+</programlisting>
+
+<para>
+The customization string is obtained by querying the resource database
+currently associated with the display (the database returned by
+<function>XrmGetDatabase</function>)
+for the resource <emphasis remap='I'>application_name</emphasis>.customization, class
+<emphasis remap='I'>application_class</emphasis>.Customization, where <emphasis remap='I'>application_name</emphasis>
+and <emphasis remap='I'>application_class</emphasis> are the values returned by
+<xref linkend='XtGetApplicationNameAndClass' xrefstyle='select: title'/>.
+If no value is specified in the database, the empty string is used.
+</para>
+
+<para>
+It is the responsibility of the caller to free the returned string using
+<xref linkend='XtFree' xrefstyle='select: title'/>
+when it is no longer needed.
+</para>
+
+
+</sect1>
+<!-- END OF FIXME -->
+<sect1 id="Hooks_for_External_Agents">
+<title>Hooks for External Agents</title>
+<para>
+Applications may register
+functions that are called at a particular control points in the Intrinsics.
+These functions are intended to be used to provide notification
+of an “X Toolkit event”, such as widget creation, to an external agent,
+such as an interactive resource editor, drag-and-drop server, or
+an aid for physically challenged users.
+The control points containing such registration hooks are identified
+in a “hook registration” object.
+</para>
+
+<para>
+To retrieve the hook registration widget, use
+<xref linkend='XtHooksOfDisplay' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtHooksOfDisplay'>
+<funcprototype>
+<funcdef>Widget <function>XtHooksOfDisplay</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the desired display.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The class of this object is a private, implementation-dependent
+subclass of
+<function>Object</function>.
+The hook object has no parent. The resources of this object are
+the callback lists for hooks and the read-only resources for getting
+a list of parentless shells. All of the callback lists are initially
+empty. When a display is closed, the hook object associated with it
+is destroyed.
+</para>
+
+<para>
+The following procedures can be called with the hook registration object
+as an argument:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtAddCallback' xrefstyle='select: title'/>,
+<xref linkend='XtAddCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveAllCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtCallCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtHasCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtCallCallbackList' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtClass' xrefstyle='select: title'/>,
+<function>XtSuperclass</function>,
+<xref linkend='XtIsSubclass' xrefstyle='select: title'/>,
+<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>,
+<function>XtIsObject</function>,
+<function>XtIsRectObj</function>,
+<function>XtIsWidget</function>,
+<function>XtIsComposite</function>,
+<function>XtIsConstraint</function>,
+<function>XtIsShell</function>,
+<function>XtIsOverrideShell</function>,
+<function>XtIsWMShell</function>,
+<function>XtIsVendorShell</function>,
+<function>XtIsTransientShell</function>,
+<function>XtIsTopLevelShell</function>,
+<function>XtIsApplicationShell</function>,
+<function>XtIsSessionShell</function>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtWidgetToApplicationContext' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtName' xrefstyle='select: title'/>,
+<function>XtParent</function>,
+<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>,
+<xref linkend='XtScreenOfObject' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtSetValues' xrefstyle='select: title'/>,
+<xref linkend='XtGetValues' xrefstyle='select: title'/>,
+<xref linkend='XtVaSetValues' xrefstyle='select: title'/>,
+<xref linkend='XtVaGetValues' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+</itemizedlist>
+
+<sect2 id="Hook_Object_Resources">
+<title>Hook Object Resources</title>
+<para>
+The resource names, classes, and representation types that are specified
+in the hook object resource list are:
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colwidth='1.0*' colname='c1'/>
+ <colspec colwidth='1.0*' colname='c2'/>
+ <colspec colwidth='1.0*' colname='c3'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Name</entry>
+ <entry>Class</entry>
+ <entry>Representation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>XtNcreateHook</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNchangeHook</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNconfigureHook</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNgeometryHook</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNdestroyHook</entry>
+ <entry>XtCCallback</entry>
+ <entry>XtRCallback</entry>
+ </row>
+ <row>
+ <entry>XtNshells</entry>
+ <entry>XtCReadOnly</entry>
+ <entry>XtRWidgetList</entry>
+ </row>
+ <row>
+ <entry>XtNnumShells</entry>
+ <entry>XtCReadOnly</entry>
+ <entry>XtRCardinal</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+</para>
+
+<para>
+Descriptions of each of these resources:
+</para>
+
+<para>
+The XtNcreateHook callback list is called from:
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>,
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>,
+<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>,
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>,
+and their corresponding varargs versions.
+</para>
+
+<para>
+The <emphasis remap='I'>call_data</emphasis> parameter in a createHook callback may be
+cast to type
+<function>XtCreateHookData</function>.
+</para>
+<programlisting>
+typedef struct {
+ String type;
+ Widget widget;
+ ArgList args;
+ Cardinal num_args;
+} XtCreateHookDataRec, *XtCreateHookData;
+</programlisting>
+<para>
+The <emphasis remap='I'>type</emphasis> is set to
+<function>XtHcreate</function>,
+<emphasis remap='I'>widget</emphasis> is the newly created widget, and <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis>
+are the arguments passed to the create function. The callbacks are
+called before returning from the create function.
+</para>
+
+<para>
+The XtNchangeHook callback list is called from:
+</para>
+<itemizedlist spacing='compact'>
+ <listitem>
+ <para>
+<xref linkend='XtSetValues' xrefstyle='select: title'/>,
+<xref linkend='XtVaSetValues' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtManageChild' xrefstyle='select: title'/>,
+<xref linkend='XtManageChildren' xrefstyle='select: title'/>,
+<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>,
+<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>,
+<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtAddCallback' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>,
+<function>XtAddCallbacks,</function>
+<xref linkend='XtRemoveCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveAllCallbacks' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>,
+<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>,
+<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>,
+<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>,
+<xref linkend='XtMapWidget' xrefstyle='select: title'/>,
+<xref linkend='XtUnmapWidget' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XtPopup' xrefstyle='select: title'/>,
+<xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>,
+<xref linkend='XtPopdown' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+The <emphasis remap='I'>call_data</emphasis> parameter in a changeHook callback may
+be cast to type
+<function>XtChangeHookData</function>.
+</para>
+<programlisting>
+typedef struct {
+ String type;
+ Widget widget;
+ XtPointer event_data;
+ Cardinal num_event_data;
+} XtChangeHookDataRec, *XtChangeHookData;
+</programlisting>
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+or
+<xref linkend='XtVaSetValues' xrefstyle='select: title'/>,
+<emphasis remap='I'>type</emphasis> is set to
+<function>XtHsetValues</function>,
+<emphasis remap='I'>widget</emphasis> is the new widget passed to the set_values procedure, and
+<emphasis remap='I'>event_data</emphasis> may be cast to type
+<function>XtChangeHookSetValuesData</function>.
+</para>
+<programlisting>
+typedef struct {
+ Widget old, req;
+ ArgList args;
+ Cardinal num_args;
+} XtChangeHookSetValuesDataRec, *XtChangeHookSetValuesData;
+</programlisting>
+<para>
+The <emphasis remap='I'>old</emphasis>, <emphasis remap='I'>req</emphasis>, <emphasis remap='I'>args</emphasis>, and <emphasis remap='I'>num_args</emphasis> are the
+parameters passed to the set_values procedure. The callbacks are called
+after the set_values and constraint set_values procedures have been called.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtManageChild' xrefstyle='select: title'/>
+or
+<xref linkend='XtManageChildren' xrefstyle='select: title'/>,
+<emphasis remap='I'>type</emphasis> is set to
+<function>XtHmanageChildren</function>,
+<emphasis remap='I'>widget</emphasis> is the parent, <emphasis remap='I'>event_data</emphasis> may be cast to type
+WidgetList and is the list of children being managed, and
+<emphasis remap='I'>num_event_data</emphasis> is the length of the widget list.
+The callbacks are called after the children have been managed.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>
+or
+<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>,
+<emphasis remap='I'>type</emphasis> is set to
+<function>XtHunmanageChildren</function>,
+<emphasis remap='I'>widget</emphasis> is the parent, <emphasis remap='I'>event_data</emphasis> may be cast to type
+WidgetList and is a list of the children being unmanaged, and
+<emphasis remap='I'>num_event_data</emphasis> is the length of the widget list.
+The callbacks are called after the children have been unmanaged.
+</para>
+
+<para>
+The changeHook callbacks are called twice as a result of a call to
+<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>,
+once after unmanaging and again after managing.
+When the callbacks are called the first time, <emphasis remap='I'>type</emphasis> is set to
+<function>XtHunmanageSet</function>,
+<emphasis remap='I'>widget</emphasis> is the parent, <emphasis remap='I'>event_data</emphasis> may be cast to type
+WidgetList and is a list of the children being unmanaged, and
+<emphasis remap='I'>num_event_data</emphasis> is the length of the widget list.
+When the callbacks are called the second time, the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHmanageSet</function>,
+<emphasis remap='I'>widget</emphasis> is the parent, <emphasis remap='I'>event_data</emphasis> may be cast to type
+WidgetList and is a list of the children being managed, and
+<emphasis remap='I'>num_event_data</emphasis> is the length of the widget list.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHrealizeWidget</function>
+and <emphasis remap='I'>widget</emphasis> is the widget being realized.
+The callbacks are called after the widget has been realized.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHunrealizeWidget</function>,
+and <emphasis remap='I'>widget</emphasis> is the widget being unrealized.
+The callbacks are called after the widget has been unrealized.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtAddCallback' xrefstyle='select: title'/>,
+<emphasis remap='I'>type</emphasis> is set to
+<function>XtHaddCallback</function>,
+<emphasis remap='I'>widget</emphasis> is the widget to which the callback is being added, and
+<emphasis remap='I'>event_data</emphasis> may be cast to type String and is the name of the
+callback being added.
+The callbacks are called after the callback has been added to the widget.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtAddCallbacks' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHaddCallbacks</function>,
+<emphasis remap='I'>widget</emphasis> is the widget to which the callbacks are being added, and
+<emphasis remap='I'>event_data</emphasis> may be cast to type String and is the name of the
+callbacks being added.
+The callbacks are called after the callbacks have been added to the widget.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHremoveCallback</function>,
+<emphasis remap='I'>widget</emphasis> is the widget from which the callback is being removed, and
+<emphasis remap='I'>event_data</emphasis> may be cast to type String and is the name of
+the callback being removed. The callbacks are called after the callback
+has been removed from the widget.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtRemoveCallbacks' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHremoveCallbacks</function>,
+<emphasis remap='I'>widget</emphasis> is the widget from which the callbacks are being removed, and
+<emphasis remap='I'>event_data</emphasis> may be cast to type String and is the name of the
+callbacks being removed. The callbacks are called after the callbacks
+have been removed from the widget.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtRemoveAllCallbacks' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHremoveAllCallbacks</function>
+and <emphasis remap='I'>widget</emphasis> is the widget from which the callbacks are being removed.
+The callbacks are called after the callbacks have been removed from the
+widget.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHaugmentTranslations</function>
+and <emphasis remap='I'>widget</emphasis> is the widget whose translations are being modified.
+The callbacks are called after the widget's translations have been
+modified.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHoverrideTranslations</function>
+and <emphasis remap='I'>widget</emphasis> is the widget whose translations are being modified.
+The callbacks are called after the widget's translations have been
+modified.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/>,
+The <emphasis remap='I'>type</emphasis> is
+<function>XtHuninstallTranslations</function>
+and <emphasis remap='I'>widget</emphasis> is the widget whose translations are being uninstalled.
+The callbacks are called after the widget's translations have been
+uninstalled.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHsetKeyboardFocus</function>
+and <emphasis remap='I'>event_data</emphasis> may be cast to type Widget and is the value of
+the descendant argument passed to <xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>. The
+callbacks are called before returning from <xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>,
+<emphasis remap='I'>type</emphasis> is set to
+<function>XtHsetWMColormapWindows</function>,
+<emphasis remap='I'>event_data</emphasis> may be cast to type WidgetList and is the value of
+the list argument passed to <xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>, and
+<emphasis remap='I'>num_event_data</emphasis> is the length of the list. The callbacks are
+called before returning from <xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHsetMappedWhenManaged</function>
+and <emphasis remap='I'>event_data</emphasis> may be cast to type Boolean and is the value of
+the mapped_when_managed argument passed to <xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>.
+The callbacks are called after setting the widget's mapped_when_managed
+field and before realizing or unrealizing the widget.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtMapWidget' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type </emphasis> is set to
+<function>XtHmapWidget</function>
+and <emphasis remap='I'>widget</emphasis> is the widget being mapped.
+The callbacks are called after mapping the widget.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtUnmapWidget' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type </emphasis> is set to
+<function>XtHunmapWidget</function>
+and <emphasis remap='I'>widget</emphasis> is the widget being unmapped.
+The callbacks are called after unmapping the widget.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtPopup' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHpopup</function>,
+<emphasis remap='I'>widget</emphasis> is the widget being popped up, and <emphasis remap='I'>event_data</emphasis> may
+be cast to type XtGrabKind and is the value of the grab_kind argument
+passed to <xref linkend='XtPopup' xrefstyle='select: title'/>.
+The callbacks are called before returning from <xref linkend='XtPopup' xrefstyle='select: title'/>.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHpopupSpringLoaded</function>
+and <emphasis remap='I'>widget</emphasis> is the widget being popped up.
+The callbacks are called
+before returning from <xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>.
+</para>
+
+<para>
+When the changeHook callbacks are called as a result of a call to
+<xref linkend='XtPopdown' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is set to
+<function>XtHpopdown</function>
+and <emphasis remap='I'>widget</emphasis> is the widget being popped down.
+The callbacks are called
+before returning from <xref linkend='XtPopdown' xrefstyle='select: title'/>.
+</para>
+
+<para>
+A widget set that exports interfaces that change application state
+without employing the Intrinsics library should invoke the change hook
+itself. This is done by:
+</para>
+
+<programlisting>
+ XtCallCallbacks(XtHooksOfDisplay(dpy), XtNchangeHook, call_data);
+</programlisting>
+<para>
+The XtNconfigureHook callback list is called any time the Intrinsics
+move, resize, or configure a widget and when
+<xref linkend='XtResizeWindow' xrefstyle='select: title'/>
+is called.
+</para>
+
+<para>
+The <emphasis remap='I'>call_data</emphasis> parameter may be cast to type
+<function>XtConfigureHookData.</function>
+</para>
+<programlisting>
+typedef struct {
+ String type;
+ Widget widget;
+ XtGeometryMask changeMask;
+ XWindowChanges changes;
+} XtConfigureHookDataRec, *XtConfigureHookData;
+</programlisting>
+<para>
+When the configureHook callbacks are called, the <emphasis remap='I'>type</emphasis> is
+<function>XtHconfigure</function>,
+<emphasis remap='I'>widget</emphasis> is the widget being configured, and <emphasis remap='I'>changeMask</emphasis> and
+<emphasis remap='I'>changes</emphasis> reflect the changes made to the widget. The callbacks
+are called after changes have been made to the widget.
+</para>
+
+<para>
+The XtNgeometryHook callback list is called from
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+and
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>
+once before and once after geometry negotiation occurs.
+</para>
+
+<para>
+The <emphasis remap='I'>call_data</emphasis> parameter may be cast to type
+<function>XtGeometryHookData</function>.
+</para>
+
+<programlisting>
+typedef struct {
+ String type;
+ Widget widget;
+ XtWidgetGeometry* request;
+ XtWidgetGeometry* reply;
+ XtGeometryResult result;
+} XtGeometryHookDataRec, *XtGeometryHookData;
+</programlisting>
+<para>
+When the geometryHook callbacks are called prior to geometry negotiation,
+the <emphasis remap='I'>type</emphasis> is
+<function>XtHpreGeometry</function>,
+<emphasis remap='I'>widget</emphasis> is the widget for which the request is being made, and
+<emphasis remap='I'>request</emphasis> is the requested geometry.
+When the geometryHook callbacks
+are called after geometry negotiation, the <emphasis remap='I'>type</emphasis> is
+<function>XtHpostGeometry</function>,
+<emphasis remap='I'>widget</emphasis> is the widget for which the request was made, <emphasis remap='I'>request</emphasis>
+is the requested geometry, <emphasis remap='I'>reply</emphasis> is the resulting geometry granted,
+and <emphasis remap='I'>result</emphasis> is the value returned from the geometry negotiation.
+</para>
+
+<para>
+The XtNdestroyHook callback list is called when a widget is destroyed.
+The <emphasis remap='I'>call_data parameter</emphasis> may be cast to type
+<function>XtDestroyHookData</function>.
+</para>
+<programlisting>
+typedef struct {
+ String type;
+ Widget widget;
+} XtDestroyHookDataRec, *XtDestroyHookData;
+</programlisting>
+<para>
+When the destroyHook callbacks are called as a result of a call to
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>,
+the <emphasis remap='I'>type</emphasis> is
+<function>XtHdestroy</function>
+and <emphasis remap='I'>widget</emphasis> is the widget being destroyed. The callbacks are
+called upon completion of phase one destroy for a widget.
+</para>
+
+<para>
+The XtNshells and XtNnumShells are read-only resources that report a
+list of all parentless shell widgets associated with a display.
+</para>
+
+<para>
+Clients who use these hooks must exercise caution in calling Intrinsics
+functions in order to avoid recursion.
+</para>
+</sect2>
+
+<sect2 id="Querying_Open_Displays">
+<title>Querying Open Displays</title>
+<para>
+To retrieve a list of the Displays associated with an application context,
+use
+<xref linkend='XtGetDisplays' xrefstyle='select: title'/>.
+</para>
+
+<funcsynopsis id='XtGetDisplays'>
+<funcprototype>
+<funcdef>void <function>XtGetDisplays</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>Display ***<parameter>dpy_return</parameter></paramdef>
+ <paramdef>Cardinal *<parameter>num_dpy_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>app_context</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dpy_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a list of open Display connections in the specified application
+context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_dpy_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the count of open Display connections in <emphasis remap='I'>dpy_return</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<xref linkend='XtGetDisplays' xrefstyle='select: title'/> may be used by an external agent to query the
+list of open displays that belong to an application context. To free
+the list of displays, use
+<xref linkend='XtFree' xrefstyle='select: title'/>.
+</para>
+</sect2>
+</sect1>
+
+</chapter>
Index: create-1.2.1-docbook-patch/libXt-1.2.1-new/specs
===================================================================
--- create-1.2.1-docbook-patch/libXt-1.2.1-new/specs (nonexistent)
+++ create-1.2.1-docbook-patch/libXt-1.2.1-new/specs (revision 5)
Property changes on: create-1.2.1-docbook-patch/libXt-1.2.1-new/specs
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Index: create-1.2.1-docbook-patch/libXt-1.2.1-new
===================================================================
--- create-1.2.1-docbook-patch/libXt-1.2.1-new (nonexistent)
+++ create-1.2.1-docbook-patch/libXt-1.2.1-new (revision 5)
Property changes on: create-1.2.1-docbook-patch/libXt-1.2.1-new
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Index: create-1.2.1-docbook-patch
===================================================================
--- create-1.2.1-docbook-patch (nonexistent)
+++ create-1.2.1-docbook-patch (revision 5)
Property changes on: create-1.2.1-docbook-patch
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Index: patches/README
===================================================================
--- patches/README (nonexistent)
+++ patches/README (revision 5)
@@ -0,0 +1,6 @@
+
+/* begin *
+
+ TODO: Leave some comment here.
+
+ * end */
Index: patches
===================================================================
--- patches (nonexistent)
+++ patches (revision 5)
Property changes on: patches
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Index: .
===================================================================
--- . (nonexistent)
+++ . (revision 5)
Property changes on: .
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Radix cross Linux
The main Radix cross Linux repository contains the build scripts of packages, which have the most complete and common functionality for desktop machines
452 Commits
2 Branches
1 Tag