summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMatt Dew <marcoz@osource.org>2011-10-22 00:06:11 -0600
committerMatt Dew <marcoz@osource.org>2011-10-22 00:06:11 -0600
commit90e4f5055bd72624597717ee58cd3e5396ab1042 (patch)
tree6a4a3e89fef203c8917234b441875ede9808caee
parent6b945acd5c394f4a508538eb028f129c7eaf2c69 (diff)
Updated CH09.xml
Diffstat
-rw-r--r--specs/CH09.xml3356
1 files changed, 1234 insertions, 2122 deletions
diff --git a/specs/CH09.xml b/specs/CH09.xml
index 7eaee80..7c83c40 100644
--- a/specs/CH09.xml
+++ b/specs/CH09.xml
@@ -1,61 +1,6 @@
-<!-- .\" $Xorg: CH09,v 1.3 2000/08/17 19:42:46 cpqbld Exp $ -->
-<!-- .\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994 -->
-<!-- .\" X Consortium -->
-<!-- .\" -->
-<!-- .\" Permission is hereby granted, free of charge, to any person obtaining -->
-<!-- .\" a copy of this software and associated documentation files (the -->
-<!-- .\" "Software"), to deal in the Software without restriction, including -->
-<!-- .\" without limitation the rights to use, copy, modify, merge, publish, -->
-<!-- .\" distribute, sublicense, and/or sell copies of the Software, and to -->
-<!-- .\" permit persons to whom the Software is furnished to do so, subject to -->
-<!-- .\" the following conditions: -->
-<!-- .\" -->
-<!-- .\" The above copyright notice and this permission notice shall be included -->
-<!-- .\" in all copies or substantial portions of the Software. -->
-<!-- .\" -->
-<!-- .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -->
-<!-- .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -->
-<!-- .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -->
-<!-- .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -->
-<!-- .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -->
-<!-- .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -->
-<!-- .\" OTHER DEALINGS IN THE SOFTWARE. -->
-<!-- .\" -->
-<!-- .\" Except as contained in this notice, the name of the X Consortium shall -->
-<!-- .\" not be used in advertising or otherwise to promote the sale, use or -->
-<!-- .\" other dealings in this Software without prior written authorization -->
-<!-- .\" from the X Consortium. -->
-<!-- .\" -->
-<!-- .\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994 -->
-<!-- .\" Digital Equipment Corporation, Maynard, Massachusetts. -->
-<!-- .\" -->
-<!-- .\" Permission to use, copy, modify and distribute this documentation for any -->
-<!-- .\" purpose and without fee is hereby granted, provided that the above copyright -->
-<!-- .\" notice appears in all copies and that both that copyright notice and this -->
-<!-- .\" permission notice appear in supporting documentation, and that the name of -->
-<!-- .\" Digital not be used in in advertising or publicity pertaining -->
-<!-- .\" to distribution of the software without specific, written prior permission. -->
-<!-- .\" Digital makes no representations about the suitability of the -->
-<!-- .\" software described herein for any purpose. -->
-<!-- .\" It is provided ``as is'' without express or implied warranty. -->
-<!-- .\" -->
-\&
-<!-- .sp 1 -->
-<!-- .ce 3 -->
-\s+1<function>Chapter 9</function>\s-1
-
-\s+1<function>Resource Management</function>\s-1
-<!-- .sp 2 -->
-<!-- .nr H1 9 -->
-<!-- .nr H2 0 -->
-<!-- .nr H3 0 -->
-<!-- .nr H4 0 -->
-<!-- .nr H5 0 -->
-<para>
-<!-- .LP -->
-<!-- .XS -->
-<!-- Chapter 9 \(em Resource Management -->
-<!-- .XE -->
+<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.
@@ -64,9 +9,9 @@ settable by
<function>XtCreateWidget</function>
(by naming the field in the argument list), by an
entry in a resource file (by using either the name or class), and by
-<function>XtSetValues .</function>
+<function>XtSetValues</function>.
In addition, it is readable by
-<function>XtGetValues .</function>
+<function>XtGetValues</function>.
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>).
@@ -74,28 +19,22 @@ Others can be for local bookkeeping,
and still others are derived from resources
(many graphics contexts and pixmaps).
</para>
+
<para>
-<!-- .LP -->
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
-<function>XtCreateWidget ,</function>
+<function>XtCreateWidget</function>,
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>
-<sect2 id="Resource_Lists">
+<sect1 id="Resource_Lists">
<title>Resource Lists</title>
-<!-- .XS -->
-<!-- (SN Resource Lists -->
-<!-- .XE -->
<para>
-<!-- .LP -->
-<!-- .IN "Resource Management" -->
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,
@@ -104,12 +43,7 @@ The declaration for the
<function>XtResource</function>
structure is
</para>
-<para>
-<!-- .LP -->
-<!-- .sM -->
<literallayout class="monospaced">
-<!-- .TA .5i 3i -->
-<!-- .ta .5i 3i -->
typedef struct {
String resource_name;
String resource_class;
@@ -120,26 +54,20 @@ typedef struct {
XtPointer default_addr;
} XtResource, *XtResourceList;
</literallayout>
-<!-- .IN "XtResourceList" -->
-<!-- .eM -->
-
-</para>
<para>
-<!-- .LP -->
When the resource list is specified as the
-<function>CoreClassPart ,</function>
-<function>ObjectClassPart ,</function>
-<function>RectObjClassPart ,</function>
+<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>
-<!-- .LP -->
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
@@ -149,19 +77,18 @@ 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 (xI for future standard and
+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 (xI are named in
+All resource names, classes, and types used by the Intrinsics are named in
<function>&lt; X11/StringDefs.h &gt;.</function>
-The (xI's symbolic resource names begin with
+The Intrinsics's symbolic resource names begin with
``XtN''
and are followed by the string name (for example, XtNbackgroundPixel
for backgroundPixel).
-
</para>
+
<para>
-<!-- .LP -->
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:
@@ -181,7 +108,6 @@ A resource class should be chosen to span a group of closely related fields.
</listitem>
</itemizedlist>
<para>
-<!-- .LP -->
For example,
a widget can have several pixel resources: background, foreground,
border, block cursor, pointer cursor, and so on.
@@ -192,8 +118,8 @@ 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>
-<!-- .LP -->
In this case, the background pixel should have a resource class of
``Background''
and all the other pixel entries a resource class of
@@ -201,32 +127,20 @@ and all the other pixel entries a resource class of
Then, the resource file needs only two lines to
change all pixels to ivory or darkblue:
</para>
-<para>
-<!-- .LP -->
<literallayout class="monospaced">
-<!-- .TA .5i 1.5i -->
-<!-- .ta .5i 1.5i -->
*Background: ivory
*Foreground: darkblue
</literallayout>
-</para>
<para>
-<!-- .LP -->
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>
-<para>
-<!-- .LP -->
<literallayout class="monospaced">
-<!-- .TA .5i 3i -->
-<!-- .ta .5i 3i -->
*Font: 6x13
</literallayout>
-</para>
<para>
-<!-- .LP -->
By convention,
resource classes are always spelled starting with a capital letter
to distinguish them from resource names.
@@ -234,533 +148,236 @@ Their symbolic names are preceded with
``XtC''
(for example, XtCBackground).
</para>
+
<para>
-<!-- .LP -->
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>
+<function>String</function>)
or the format of the resource default value
(almost anything, but often
-<function>String )</function>
+<function>String</function>)
to the desired
physical representation (see Section 9.6).
-The (xI define the following resource types:
+The Intrinsics define the following resource types:
+</para>
+
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<tbody>
<row>
- <entry>lw(2.5i) lw(2.5i).</entry>
- </row>
- <row>
- <entry>_</entry>
- </row>
- <row>
<entry>Resource Type</entry>
<entry>Structure or Field Type</entry>
</row>
<row>
- <entry>_</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRAcceleratorTable</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>XtAccelerators</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRAtom</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Atom</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRBitmap</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Pixmap, depth=1</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRBoolean</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Boolean</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRBool</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Bool</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRCallback</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>XtCallbackList</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRCardinal</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Cardinal</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRColor</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>XColor</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRColormap</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Colormap</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRCommandArgArray</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>String*</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRCursor</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Cursor</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRDimension</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Dimension</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRDirectoryString</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>String</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRDisplay</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Display*</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtREnum</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>XtEnum</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtREnvironmentArray</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>String*</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRFile</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>FILE*</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRFloat</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>float</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRFont</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Font</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRFontSet</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>XFontSet</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRFontStruct</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>XFontStruct*</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRFunction</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>(*)()</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRGeometry</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
- <entry>char*, format as defined by</entry>
- </row>
- <row>
- <entry><function>XParseGeometry</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
+ <entry>char*, format as defined by
+ <function>XParseGeometry</function></entry>
</row>
<row>
<entry><function>XtRGravity</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>int</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRInitialState</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>int</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRInt</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>int</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRLongBoolean</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>long</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRObject</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Object</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRPixel</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Pixel</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRPixmap</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Pixmap</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRPointer</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>XtPointer</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRPosition</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Position</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRRestartStyle</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>unsigned char</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRScreen</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Screen*</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRShort</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>short</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRSmcConn</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>XtPointer</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRString</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>String</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRStringArray</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>String*</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRStringTable</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>String*</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRTranslationTable</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>XtTranslations</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRUnsignedChar</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>unsigned char</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRVisual</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Visual*</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRWidget</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Widget</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRWidgetClass</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>WidgetClass</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRWidgetList</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>WidgetList</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRWindow</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Window</entry>
</row>
- <row>
- <entry>_</entry>
- </row>
</tbody>
</tgroup>
</informaltable>
-<!-- .sp -->
-</para>
+
<para>
-<!-- .LP -->
<function>&lt; X11/StringDefs.h &gt;</function>
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>
+<function>XtREditMode</function>,
+<function>XtRJustify</function>,
and
-<function>XtROrientation .</function>
+<function>XtROrientation</function>.
</para>
+
<para>
-<!-- .LP -->
The <emphasis remap='I'>resource_size</emphasis> field is the size of the physical representation in bytes;
you should specify it as
-<function>sizeof (<emphasis remap='I'>type</emphasis>)</function>
-so that the
+<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.
@@ -784,7 +401,7 @@ it should be a value for which the converter is guaranteed to work (for example,
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>
+<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
@@ -793,8 +410,8 @@ type stored in the resource database fails,
which can happen for various reasons (for example, a misspelled entry in a
resource file).
</para>
+
<para>
-<!-- .LP -->
Two special representation types
(XtRImmediate
and
@@ -805,7 +422,7 @@ indicates that the value in the <emphasis remap='I'>default_addr</emphasis> fiel
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>
+<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
@@ -816,21 +433,18 @@ This procedure is automatically invoked with the widget,
in which to store the result.
XtRCallProc
procedure pointers are of type
-<function>XtResourceDefaultProc .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .sM -->
+<function>XtResourceDefaultProc</function>.
</para>
-<!-- .FD 0 -->
-typedef void (*XtResourceDefaultProc)(Widget, int, XrmValue*);
-<!-- .br -->
- Widget <emphasis remap='I'>w</emphasis>;
-<!-- .br -->
- int <emphasis remap='I'>offset</emphasis>;
-<!-- .br -->
- XrmValue *<emphasis remap='I'>value</emphasis>;
-<!-- .FN -->
+
+<funcsynopsis id='XtResourceDefaultProc'>
+<funcprototype>
+<funcdef>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>
@@ -864,33 +478,27 @@ Specifies the resource value descriptor to return.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
The
<function>XtResourceDefaultProc</function>
procedure should fill in the <emphasis remap='I'>value-&gt;addr</emphasis> field with a pointer
to the resource value in its correct representation type.
-<!-- .sp -->
</para>
+
<para>
-<!-- .LP -->
To get the resource list structure for a particular class, use
-<function>XtGetResourceList .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtGetResourceList" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-void XtGetResourceList(<emphasis remap='I'>class</emphasis>, <emphasis remap='I'>resources_return</emphasis>, <emphasis remap='I'>num_resources_return</emphasis>);
-<!-- .br -->
- WidgetClass <emphasis remap='I'>class</emphasis>;
-<!-- .br -->
- XtResourceList *<emphasis remap='I'>resources_return</emphasis>;
-<!-- .br -->
- Cardinal *<emphasis remap='I'>num_resources_return</emphasis>;
-<!-- .FN -->
+<function>XtGetResourceList</function>.
+</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>
@@ -926,8 +534,6 @@ Returns the number of entries in the resource list.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
If
<function>XtGetResourceList</function>
is called before the class is initialized,
@@ -941,29 +547,23 @@ The list returned by
should be freed using
<function>XtFree</function>
when it is no longer needed.
-<!-- .sp -->
</para>
+
<para>
-<!-- .LP -->
To get the constraint resource list structure for a particular widget
class, use
-<function>XtGetConstraintResourceList .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtGetConstraintResourceList" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-void XtGetConstraintResourceList(<emphasis remap='I'>class</emphasis>, <emphasis remap='I'>resources_return</emphasis>, \
-<emphasis remap='I'>num_resources_return</emphasis>)
-<!-- .br -->
- WidgetClass <emphasis remap='I'>class</emphasis>;
-<!-- .br -->
- XtResourceList *<emphasis remap='I'>resources_return</emphasis>;
-<!-- .br -->
- Cardinal *<emphasis remap='I'>num_resources_return</emphasis>;
-<!-- .FN -->
+<function>XtGetConstraintResourceList</function>.
+</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>
@@ -999,8 +599,6 @@ Returns the number of entries in the constraint resource list.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
If
<function>XtGetConstraintResourceList</function>
is called before the widget class is
@@ -1011,7 +609,7 @@ 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>
+<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
@@ -1019,10 +617,9 @@ The list returned by
should be freed using
<function>XtFree</function>
when it is no longer needed.
-<!-- .sp -->
</para>
+
<para>
-<!-- .LP -->
The routines
<function>XtSetValues</function>
and
@@ -1030,15 +627,11 @@ and
also use the resource list to set and get widget state;
see Sections 9.7.1 and 9.7.2.
</para>
+
<para>
-<!-- .LP -->
Here is an abbreviated version of a possible resource list for a Label widget:
</para>
-<para>
-<!-- .LP -->
<literallayout class="monospaced">
-<!-- .TA .5i 1.5i 3i -->
-<!-- .ta .5i 1.5i 3i -->
/* Resources specific to Label */
static XtResource resources[] = {
{XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel),
@@ -1052,9 +645,7 @@ static XtResource resources[] = {
.
}
</literallayout>
-</para>
<para>
-<!-- .LP -->
The complete resource name for a field of a widget instance is the
concatenation of the application shell name (from
<function>XtAppCreateShell ),</function>
@@ -1070,31 +661,26 @@ 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>
-</sect2>
-<sect2 id="Byte_Offset_Calculations">
+</sect1>
+
+<sect1 id="Byte_Offset_Calculations">
<title>Byte Offset Calculations</title>
-<!-- .XS -->
-<!-- (SN Byte Offset Calculations -->
-<!-- .XE -->
<para>
-<!-- .LP -->
To determine the byte offset of a field within a structure type, use
-<function>XtOffsetOf .</function>
+<function>XtOffsetOf</function>.
</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtOffsetOf" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-Cardinal XtOffsetOf(<emphasis remap='I'>structure_type</emphasis>, <emphasis remap='I'>field_name</emphasis>)
-<!-- .br -->
- <emphasis remap='I'>Type structure_type</emphasis>;
-<!-- .br -->
- <emphasis remap='I'>Field field_name</emphasis>;
-<!-- .FN -->
+
+<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>
@@ -1118,35 +704,29 @@ Specifies the name of a member within the structure.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
The
<function>XtOffsetOf</function>
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
-<function>XtOffset ,</function>
+<function>XtOffset</function>,
which serves the same function.
-
</para>
+
<para>
-<!-- .LP -->
To determine the byte offset of a field within a structure pointer type, use
-<function>XtOffset .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtOffset" "" "@DEF@" -->
-<!-- .sM -->
+<function>XtOffset</function>.
</para>
-<!-- .FD 0 -->
-Cardinal XtOffset(<emphasis remap='I'>pointer_type</emphasis>, <emphasis remap='I'>field_name</emphasis>)
-<!-- .br -->
- <emphasis remap='I'>Type pointer_type</emphasis>;
-<!-- .br -->
- <emphasis remap='I'>Field field_name</emphasis>;
-<!-- .FN -->
+
+<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>
@@ -1170,8 +750,6 @@ Specifies the name of a member within the structure.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
The
<function>XtOffset</function>
macro expands to a constant expression that gives the
@@ -1180,20 +758,13 @@ of the structure. It may be used to statically initialize
resource lists.
<function>XtOffset</function>
is less portable than
-<function>XtOffsetOf .</function>
-
+<function>XtOffsetOf</function>.
</para>
-</sect2>
-<sect2 id="Superclass_to_Subclass_Chaining_of_Resource_Lists">
+</sect1>
+
+<sect1 id="Superclass_to_Subclass_Chaining_of_Resource_Lists">
<title>Superclass-to-Subclass Chaining of Resource Lists</title>
-<!-- .XS -->
-<!-- (SN Superclass-to-Subclass Chaining of Resource Lists -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<!-- .IN "Inheritance" -->
-<!-- .IN "Superclass Chaining" -->
-<!-- .IN "Chaining" -->
+<para>
The
<function>XtCreateWidget</function>
function gets resources as a superclass-to-subclass chained operation.
@@ -1201,13 +772,13 @@ That is, the resources specified in the
<function>objectClass</function>
resource list are fetched,
then those in
-<function>rectObjClass ,</function>
+<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>
-<!-- .LP -->
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.
@@ -1230,65 +801,49 @@ 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>
-<!-- .LP -->
-<!-- .IN "class_initialize procedure" -->
-<!-- .IN "Widget" "class initialization" -->
-Also at class initialization time, the (xI produce an
+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 (xI may
+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>
-</sect2>
-<sect2 id="Subresources">
+</sect1>
+
+<sect1 id="Subresources">
<title>Subresources</title>
-<!-- .XS -->
-<!-- (SN Subresources -->
-<!-- .XE -->
<para>
-<!-- .LP -->
A widget does not do anything to retrieve its own resources;
instead,
<function>XtCreateWidget</function>
does this automatically before calling the class initialize procedure.
</para>
+
<para>
-<!-- .LP -->
Some widgets have subparts that are not widgets but for which the widget
would like to fetch resources.
Such widgets call
<function>XtGetSubresources</function>
to accomplish this.
</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtGetSubresources" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-void XtGetSubresources(<emphasis remap='I'>w</emphasis>, <emphasis remap='I'>base</emphasis>, <emphasis remap='I'>name</emphasis>, <emphasis remap='I'>class</emphasis>, \
-<emphasis remap='I'>resources</emphasis>, <emphasis remap='I'>num_resources</emphasis>, <emphasis remap='I'>args</emphasis>, <emphasis remap='I'>num_args</emphasis>)
-<!-- .br -->
- Widget <emphasis remap='I'>w</emphasis>;
-<!-- .br -->
- XtPointer <emphasis remap='I'>base</emphasis>;
-<!-- .br -->
- String <emphasis remap='I'>name</emphasis>;
-<!-- .br -->
- String <emphasis remap='I'>class</emphasis>;
-<!-- .br -->
- XtResourceList <emphasis remap='I'>resources</emphasis>;
-<!-- .br -->
- Cardinal <emphasis remap='I'>num_resources</emphasis>;
-<!-- .br -->
- ArgList <emphasis remap='I'>args</emphasis>;
-<!-- .br -->
- Cardinal <emphasis remap='I'>num_args</emphasis>;
-<!-- .FN -->
+
+<funcsynopsis id='XtGetSubresources'>
+<funcprototype>
+<funcdef>void <function>XtGetSubresources</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>String <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>
@@ -1297,7 +852,7 @@ void XtGetSubresources(<emphasis remap='I'>w</emphasis>, <emphasis remap='I'>bas
<listitem>
<para>
Specifies the object used to qualify the subpart resource name and
-class. (oI
+class. Must be of class Object or any subclass thereof.
</para>
</listitem>
</varlistentry>
@@ -1374,8 +929,6 @@ Specifies the number of entries in the argument list.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
The
<function>XtGetSubresources</function>
function constructs a name and class list from the application name and class,
@@ -1389,8 +942,8 @@ If <emphasis remap='I'>args</emphasis> is NULL,
However, if <emphasis remap='I'>num_args</emphasis> is zero,
the argument list is not referenced.
</para>
+
<para>
-<!-- .LP -->
<function>XtGetSubresources</function>
may overwrite the specified resource list with an
equivalent representation in an internal format, which optimizes access
@@ -1403,34 +956,25 @@ 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.
-<!-- .sp -->
</para>
+
<para>
-<!-- .LP -->
To fetch resources for widget subparts using varargs lists, use
-<function>XtVaGetSubresources .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtVaGetSubresources" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-void XtVaGetSubresources(<emphasis remap='I'>w</emphasis>, <emphasis remap='I'>base</emphasis>, <emphasis remap='I'>name</emphasis>, <emphasis remap='I'>class</emphasis>, \
-<emphasis remap='I'>resources</emphasis>, <emphasis remap='I'>num_resources</emphasis>, ...)
-<!-- .br -->
- Widget <emphasis remap='I'>w</emphasis>;
-<!-- .br -->
- XtPointer <emphasis remap='I'>base</emphasis>;
-<!-- .br -->
- String <emphasis remap='I'>name</emphasis>;
-<!-- .br -->
- String <emphasis remap='I'>class</emphasis>;
-<!-- .br -->
- XtResourceList <emphasis remap='I'>resources</emphasis>;
-<!-- .br -->
- Cardinal <emphasis remap='I'>num_resources</emphasis>;
-<!-- .FN -->
+<function>XtVaGetSubresources</function>.
+</para>
+
+<funcsynopsis id='XtVaGetSubresources'>
+<funcprototype>
+<funcdef>void <function>XtVaGetSubresources</function></funcdef>
+ <paramdef>Widget <parameter>w</parameter></paramdef>
+ <paramdef>XtPointer <parameter>base</parameter></paramdef>
+ <paramdef>String <parameter>name</parameter></paramdef>
+ <paramdef>String <parameter>class</parameter></paramdef>
+ <paramdef>XtResourceList <parameter>resources</parameter></paramdef>
+ <paramdef>Cardinal <parameter>num_resources</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
<variablelist>
<varlistentry>
<term>
@@ -1439,7 +983,7 @@ void XtVaGetSubresources(<emphasis remap='I'>w</emphasis>, <emphasis remap='I'>b
<listitem>
<para>
Specifies the object used to qualify the subpart resource name and
-class. (oI
+class. Must be of class Object or any subclass thereof.
</para>
</listitem>
</varlistentry>
@@ -1507,48 +1051,34 @@ resource specifications.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
<function>XtVaGetSubresources</function>
is identical in function to
<function>XtGetSubresources</function>
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="Obtaining_Application_Resources">
+</sect1>
+
+<sect1 id="Obtaining_Application_Resources">
<title>Obtaining Application Resources</title>
-<!-- .XS -->
-<!-- <function>(SN Obtaining Application Resources</function> -->
-<!-- .XE -->
<para>
-<!-- .LP -->
To retrieve resources that are not specific to a widget
but apply to the overall application, use
-<function>XtGetApplicationResources .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtGetApplicationResources" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-void XtGetApplicationResources(<emphasis remap='I'>w</emphasis>, <emphasis remap='I'>base</emphasis>, <emphasis remap='I'>resources</emphasis>, \
-<emphasis remap='I'>num_resources</emphasis>, <emphasis remap='I'>args</emphasis>, <emphasis remap='I'>num_args</emphasis>)
-<!-- .br -->
- Widget <emphasis remap='I'>w</emphasis>;
-<!-- .br -->
- XtPointer <emphasis remap='I'>base</emphasis>;
-<!-- .br -->
- XtResourceList <emphasis remap='I'>resources</emphasis>;
-<!-- .br -->
- Cardinal <emphasis remap='I'>num_resources</emphasis>;
-<!-- .br -->
- ArgList <emphasis remap='I'>args</emphasis>;
-<!-- .br -->
- Cardinal <emphasis remap='I'>num_args</emphasis>;
-<!-- .FN -->
+<function>XtGetApplicationResources</function>.
+</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>
@@ -1557,7 +1087,7 @@ void XtGetApplicationResources(<emphasis remap='I'>w</emphasis>, <emphasis remap
<listitem>
<para>
Specifies the object that identifies the resource database to search
-(the database is that associated with the display for this object). (oI
+(the database is that associated with the display for this object). Must be of class Object or any subclass thereof.
</para>
</listitem>
</varlistentry>
@@ -1614,8 +1144,6 @@ Specifies the number of entries in the argument list.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
The
<function>XtGetApplicationResources</function>
function first uses the passed object,
@@ -1638,8 +1166,8 @@ 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>
-<!-- .LP -->
<function>XtGetApplicationResources</function>
may overwrite the specified resource list
with an equivalent representation in an internal format, which
@@ -1649,30 +1177,23 @@ modify the list contents after the call if the same list is to be
used again. Any per-display resources fetched by
<function>XtGetApplicationResources</function>
will not be freed from the resource cache until the display is closed.
-<!-- .sp -->
</para>
+
<para>
-<!-- .LP -->
To retrieve resources for the overall application using varargs lists, use
-<function>XtVaGetApplicationResources .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtVaGetApplicationResources" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-void XtVaGetApplicationResources(<emphasis remap='I'>w</emphasis>, <emphasis remap='I'>base</emphasis>, <emphasis remap='I'>resources</emphasis>, \
-<emphasis remap='I'>num_resources</emphasis>, ...)
-<!-- .br -->
- Widget <emphasis remap='I'>w</emphasis>;
-<!-- .br -->
- XtPointer <emphasis remap='I'>base</emphasis>;
-<!-- .br -->
- XtResourceList <emphasis remap='I'>resources</emphasis>;
-<!-- .br -->
- Cardinal <emphasis remap='I'>num_resources</emphasis>;
-<!-- .FN -->
+<function>XtVaGetApplicationResources</function>.
+</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>
+</funcprototype>
+</funcsynopsis>
+
<variablelist>
<varlistentry>
<term>
@@ -1681,7 +1202,7 @@ void XtVaGetApplicationResources(<emphasis remap='I'>w</emphasis>, <emphasis rem
<listitem>
<para>
Specifies the object that identifies the resource database to search
-(the database is that associated with the display for this object). (oI
+(the database is that associated with the display for this object). Must be of class Object or any subclass thereof.
</para>
</listitem>
</varlistentry>
@@ -1729,26 +1250,20 @@ resource specifications.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
<function>XtVaGetApplicationResources</function>
is identical in function to
<function>XtGetApplicationResources</function>
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="Resource_Conversions">
+</sect1>
+
+<sect1 id="Resource_Conversions">
<title>Resource Conversions</title>
-<!-- .XS -->
-<!-- (SN Resource Conversions -->
-<!-- .XE -->
<para>
-<!-- .LP -->
-The (xI provide a mechanism for registering representation converters that
+The Intrinsics provide a mechanism for registering representation converters that
are automatically invoked by the resource-fetching routines.
-The (xI additionally provide and register several commonly used converters.
+The Intrinsics additionally provide and register several commonly used converters.
This resource conversion mechanism serves several purposes:
</para>
<itemizedlist>
@@ -1772,18 +1287,13 @@ 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>
-<sect3 id="Predefined_Resource_Converters">
+<sect2 id="Predefined_Resource_Converters">
<title>Predefined Resource Converters</title>
-<!-- .XS -->
-<!-- (SN Predefined Resource Converters -->
-<!-- .XE -->
<para>
-<!-- .LP -->
-The (xI define all the representations used in the
+The Intrinsics define all the representations used in the
Object,
RectObj,
Core,
@@ -1792,459 +1302,144 @@ Constraint,
and
Shell
widget classes.
-The (xI register the following resource converters that accept
+The Intrinsics register the following resource converters that accept
input values of representation type
-<function>XtRString .</function>
+<function>XtRString</function>.
</para>
-<para>
-<!-- .LP -->
+
<informaltable>
- <tgroup cols='4' align='center'>
+ <tgroup cols='3' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>
- <colspec colname='c4'/>
<tbody>
<row>
- <entry>lw(1.7i) lw(2.4i) lw(1.5i) .</entry>
- </row>
- <row>
- <entry>_</entry>
- </row>
- <row>
<entry>Target Representation</entry>
<entry>Converter Name</entry>
<entry>Additional Args</entry>
</row>
<row>
- <entry>_</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRAcceleratorTable</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToAcceleratorTable</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRAtom</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToAtom</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Display*</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRBoolean</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToBoolean</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRBool</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToBool</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRCommandArgArray</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToCommandArgArray</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRCursor</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToCursor</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Display*</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRDimension</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToDimension</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRDirectoryString</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToDirectoryString</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRDisplay</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToDisplay</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRFile</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToFile</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRFloat</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToFloat</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRFont</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToFont</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Display*</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRFontSet</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToFontSet</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Display*, String <emphasis remap='I'>locale</emphasis></entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRFontStruct</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToFontStruct</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Display*</entry>
</row>
<row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRGravity</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToGravity</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRInitialState</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToInitialState</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRInt</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToInt</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRPixel</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToPixel</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>colorConvertArgs</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRPosition</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToPosition</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRRestartStyle</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToRestartStyle</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRShort</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToShort</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRTranslationTable</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToTranslationTable</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRUnsignedChar</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToUnsignedChar</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRVisual</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtStringToVisual</function></entry>
- </row>
- <row>
- <entry>T}</entry>
<entry>Screen*, Cardinal <emphasis remap='I'>depth</emphasis></entry>
</row>
- <row>
- <entry>_</entry>
- </row>
</tbody>
</tgroup>
</informaltable>
-</para>
<para>
-<!-- .LP -->
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>
-<!-- .IN "XtDefaultBackground" "" "@DEF@" -->
-<!-- .IN "XtDefaultForeground" "" "@DEF@" -->
+<function>XtDefaultBackground</function>.
They evaluate to the black and white pixel values of the widget's screen,
respectively.
-<!-- .IN "Resources" "reverseVideo" -->
If the application resource reverseVideo is
-<function>True ,</function>
+<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>
-<!-- .IN "XtDefaultFont" "" "@DEF@" -->
-<!-- .IN "Resources" "xtDefaultFont" -->
and evaluate this in the following manner:
</para>
<itemizedlist>
@@ -2279,16 +1474,13 @@ for example, "-*-*-*-R-*-*-*-120-*-*-*-*-ISO8859-1".)
<para>
If no suitable ISO8859-1 font can be found, issue a warning message
and return
-<function>False .</function>
+<function>False</function>.
</para>
</listitem>
</itemizedlist>
<para>
-<!-- .LP -->
The String-to-FontSet converter recognizes the constant
<function>XtDefaultFontSet</function>
-<!-- .IN "XtDefaultFontSet" "" "@DEF@" -->
-<!-- .IN "Resources" "xtDefaultFontSet" -->
and evaluate this in the following manner:
</para>
<itemizedlist>
@@ -2322,42 +1514,41 @@ for example, "-*-*-*-R-*-*-*-120-*-*-*-*".)
<para>
If no suitable font set can be created, issue a warning message
and return
-<function>False .</function>
+<function>False</function>.
</para>
</listitem>
</itemizedlist>
<para>
-<!-- .LP -->
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 (xI register the String-to-FontSet converter with
+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>
-<!-- .LP -->
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'>(xL</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>
+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>
+<function>StaticGravity</function>.
Alphabetic case is not significant in the conversion.
</para>
+
<para>
-<!-- .LP -->
The String-to-CommandArgArray conversion parses a String into an
array of strings.
White space characters separate elements of the command line.
@@ -2365,33 +1556,32 @@ 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>
-<!-- .LP -->
-<!-- .IN "XtCurrentDirectory" "" "@DEF@" -->
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>
-<!-- .LP -->
The String-to-RestartStyle conversion accepts the values
-<function>RestartIfRunning ,</function>
-<function>RestartAnyway ,</function>
-<function>RestartImmediately ,</function>
+<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>
-<!-- .LP -->
The String-to-InitialState conversion accepts the values
<function>NormalState</function>
or
<function>IconicState</function>
-as defined by the <emphasis remap='I'>(xC</emphasis>.
+as defined by the <emphasis remap='I'>Inter-Client Communication Conventions Manual.</emphasis>.
</para>
+
<para>
-<!-- .LP -->
The String-to-Visual conversion calls
<function>XMatchVisualInfo</function>
using the
@@ -2402,404 +1592,174 @@ to specify any resource of type
after the depth resource.
The allowed string values are the visual class names defined in <emphasis remap='I'>(xP</emphasis>,
Section 8;
-<function>StaticGray ,</function>
-<function>StaticColor ,</function>
-<function>TrueColor ,</function>
-<function>GrayScale ,</function>
-<function>PseudoColor ,</function>
+<function>StaticGray</function>,
+<function>StaticColor</function>,
+<function>TrueColor</function>,
+<function>GrayScale</function>,
+<function>PseudoColor</function>,
and
-<function>DirectColor .</function>
-
+<function>DirectColor</function>.
</para>
+
<para>
-<!-- .LP -->
-The (xI register the following resource converter that accepts
+The Intrinsics register the following resource converter that accepts
an input value of representation type
-<function>XtRColor .</function>
+<function>XtRColor</function>.
</para>
-<para>
-<!-- .LP -->
+
<informaltable>
- <tgroup cols='4' align='center'>
+ <tgroup cols='3' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>
- <colspec colname='c4'/>
<tbody>
<row>
- <entry>lw(1.5i) lw(2.25i) lw(1.5i) .</entry>
- </row>
- <row>
- <entry>_</entry>
- </row>
- <row>
<entry>Target Representation</entry>
<entry>Converter Name</entry>
<entry>Additional Args</entry>
</row>
<row>
- <entry>_</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRPixel</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtColorToPixel</function></entry>
</row>
- <row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>_</entry>
- </row>
</tbody>
</tgroup>
</informaltable>
-</para>
<para>
-<!-- .LP -->
-The (xI register the following resource converters that accept
+The Intrinsics register the following resource converters that accept
input values of representation type
-<function>XtRInt .</function>
+<function>XtRInt</function>.
</para>
-<para>
-<!-- .LP -->
+
<informaltable>
- <tgroup cols='4' align='center'>
+ <tgroup cols='3' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>
- <colspec colname='c4'/>
<tbody>
<row>
- <entry>lw(1.5i) lw(2.25i) lw(1.5i) .</entry>
- </row>
- <row>
- <entry>_</entry>
- </row>
- <row>
<entry>Target Representation</entry>
<entry>Converter Name</entry>
<entry>Additional Args</entry>
</row>
<row>
- <entry>_</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRBoolean</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtIntToBoolean</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRBool</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtIntToBool</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRColor</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtIntToColor</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>colorConvertArgs</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRDimension</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtIntToDimension</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRFloat</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtIntToFloat</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRFont</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtIntToFont</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRPixel</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtIntToPixel</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRPixmap</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtIntToPixmap</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRPosition</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtIntToPosition</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRShort</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtIntToShort</function></entry>
</row>
<row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRUnsignedChar</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtIntToUnsignedChar</function></entry>
</row>
- <row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>_</entry>
- </row>
</tbody>
</tgroup>
</informaltable>
-</para>
<para>
-<!-- .LP -->
-The (xI register the following resource converter that accepts
+The Intrinsics register the following resource converter that accepts
an input value of representation type
-<function>XtRPixel .</function>
+<function>XtRPixel</function>.
</para>
-<para>
-<!-- .LP -->
+
<informaltable>
- <tgroup cols='4' align='center'>
+ <tgroup cols='3' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>
- <colspec colname='c4'/>
<tbody>
<row>
- <entry>lw(1.5i) lw(2.25i) lw(1.5i) .</entry>
- </row>
- <row>
- <entry>_</entry>
- </row>
- <row>
<entry>Target Representation</entry>
<entry>Converter Name</entry>
<entry>Additional Args</entry>
</row>
<row>
- <entry>_</entry>
- </row>
- <row>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtRColor</function></entry>
- </row>
- <row>
- <entry>T}</entry>
- <entry>T{</entry>
- </row>
- <row>
<entry><function>XtCvtPixelToColor</function></entry>
</row>
- <row>
- <entry>T}</entry>
- </row>
- <row>
- <entry>_</entry>
- </row>
</tbody>
</tgroup>
</informaltable>
+</sect2>
-</para>
-</sect3>
-<sect3 id="New_Resource_Converters">
+<sect2 id="New_Resource_Converters">
<title>New Resource Converters</title>
-<!-- .XS -->
-<!-- (SN New Resource Converters -->
-<!-- .XE -->
<para>
-<!-- .LP -->
Type converters use pointers to
<function>XrmValue</function>
structures (defined in
<function>&lt; X11/Xresource.h &gt;;</function>
-see Section 15.4 in <emphasis remap='I'>(xL</emphasis>)
+see Section 15.4 in <emphasis remap='I'>Xlib — C Language X Interface.</emphasis>)
for input and output values.
</para>
-<para>
-<!-- .LP -->
-<!-- .sM -->
<literallayout class="monospaced">
-<!-- .TA .5i 3i -->
-<!-- .ta .5i 3i -->
typedef struct {
unsigned int size;
XPointer addr;
} XrmValue, *XrmValuePtr;
</literallayout>
-</para>
<para>
-<!-- .LP -->
-<!-- .eM -->
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>
+<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>
-<!-- .LP -->
A resource converter procedure pointer is of type
-<function>XtTypeConverter .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtTypeConverter" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-typedef Boolean (*XtTypeConverter)(Display*, XrmValue*, Cardinal*,
- XrmValue*, XrmValue*, XtPointer*);
-<!-- .br -->
- Display *<emphasis remap='I'>display</emphasis>;
-<!-- .br -->
- XrmValue *<emphasis remap='I'>args</emphasis>;
-<!-- .br -->
- Cardinal *<emphasis remap='I'>num_args</emphasis>;
-<!-- .br -->
- XrmValue *<emphasis remap='I'>from</emphasis>;
-<!-- .br -->
- XrmValue *<emphasis remap='I'>to</emphasis>;
-<!-- .br -->
- XtPointer *<emphasis remap='I'>converter_data</emphasis>;
-<!-- .FN -->
+<function>XtTypeConverter</function>.
+</para>
+
+<funcsynopsis id='XtTypeConverter'>
+<funcprototype>
+<funcdef>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>
@@ -2870,14 +1830,12 @@ with this conversion.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
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>
-<!-- .LP -->
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
@@ -2896,26 +1854,25 @@ 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>
+<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 (xI.
+when the resource is freed by the Intrinsics.
</para>
+
<para>
-<!-- .LP -->
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
-<function>XtAppWarningMsg .</function>
-
+<function>XtAppWarningMsg</function>.
</para>
+
<para>
-<!-- .LP -->
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.
@@ -2924,41 +1881,36 @@ 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>
-<!-- .LP -->
Note that if an address is written into <emphasis remap='I'>to-&gt;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,
-<function>XtGetApplicationResources ,</function>
+<function>XtGetApplicationResources</function>,
or
<function>XtGetSubresources</function>
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>
-<!-- .LP -->
The following is an example of a converter that takes a
<function>string</function>
and converts it to a
-<function>Pixel .</function>
+<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 (xI that the converted value is
+still required to inform the Intrinsics that the converted value is
a function of the particular display (and colormap).
</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-<!-- .TA .3i .7i 1i 1.3i 1.7i 2i 4i -->
-<!-- .ta .3i .7i 1i 1.3i 1.7i 2i 4i -->
+<literallayout class="monospaced">
#define done(type, value) \\
{ \\
if (toVal-&gt;addr != NULL) { \\
@@ -2971,12 +1923,11 @@ a function of the particular display (and colormap).
else { \\
static type static_val; \\
static_val = (value); \\
- toVal-&gt;addr = (XPointer)&static_val; \\
+ toVal-&gt;addr = (XPointer)&amp;static_val; \\
} \\
toVal-&gt;size = sizeof(type); \\
return True; \\
}
-
static Boolean CvtStringToPixel(dpy, args, num_args, fromVal, toVal, converter_data)
Display *dpy;
XrmValue *args;
@@ -2990,16 +1941,13 @@ static Boolean CvtStringToPixel(dpy, args, num_args, fromVal, toVal, converter_d
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));
@@ -3008,11 +1956,8 @@ static Boolean CvtStringToPixel(dpy, args, num_args, fromVal, toVal, converter_d
*closure_ret = False;
done(Pixel, BlackPixelOfScreen(screen));
}
-
-
status = XAllocNamedColor(DisplayOfScreen(screen), colormap, (char*)fromVal-&gt;addr,
- &screenColor, &exactColor);
-
+ &amp;screenColor, &amp;exactColor);
if (status == 0) {
String params[1];
Cardinal num_params = 1;
@@ -3020,18 +1965,17 @@ static Boolean CvtStringToPixel(dpy, args, num_args, fromVal, toVal, converter_d
XtAppWarningMsg(XtDisplayToApplicationContext(dpy),
"noColormap", "cvtStringToPixel", "XtToolkitError",
"Cannot allocate colormap entry for \\"%s\\"", params,\
- &num_params);
+ &amp;num_params);
*converter_data = (char *) False;
return False;
} else {
*converter_data = (char *) True;
- done(Pixel, &screenColor.pixel);
+ done(Pixel, &amp;screenColor.pixel);
}
}
</literallayout>
-</para>
+
<para>
-<!-- .LP -->
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,
@@ -3040,41 +1984,33 @@ 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>
+<function>XtDefaultForeground</function>,
+<function>XtDefaultBackground</function>,
and
-<function>XtDefaultFont .</function>
-<!-- .sp -->
+<function>XtDefaultFont</function>.
</para>
+
<para>
-<!-- .LP -->
-To allow the (xI to deallocate resources produced by type
+To allow the Intrinsics to deallocate resources produced by type
converters, a resource destructor procedure may also be provided.
</para>
+
<para>
-<!-- .LP -->
A resource destructor procedure pointer is of type
-<function>XtDestructor .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtDestructor" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-typedef void (*XtDestructor) (XtAppContext, XrmValue*, XtPointer, XrmValue*, \
-Cardinal*);
-<!-- .br -->
- XtAppContext <emphasis remap='I'>app</emphasis>;
-<!-- .br -->
- XrmValue *<emphasis remap='I'>to</emphasis>;
-<!-- .br -->
- XtPointer <emphasis remap='I'>converter_data</emphasis>;
-<!-- .br -->
- XrmValue *<emphasis remap='I'>args</emphasis>;
-<!-- .br -->
- Cardinal *<emphasis remap='I'>num_args</emphasis>;
-<!-- .FN -->
+<function>XtDestructor</function>.
+</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>
@@ -3129,41 +2065,31 @@ Specifies the number of entries in <emphasis remap='I'>args</emphasis>.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
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>
-</sect3>
-<sect3 id="Issuing_Conversion_Warnings">
+</sect2>
+
+<sect2 id="Issuing_Conversion_Warnings">
<title>Issuing Conversion Warnings</title>
-<!-- .XS -->
-<!-- (SN Issuing Conversion Warnings -->
-<!-- .XE -->
<para>
-<!-- .LP -->
The
<function>XtDisplayStringConversionWarning</function>
procedure is a convenience routine for resource type converters
that convert from string values.
</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtDisplayStringConversionWarning" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-void XtDisplayStringConversionWarning(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>from_value</emphasis>, \
-<emphasis remap='I'>to_type</emphasis>)
-<!-- .br -->
- Display *<emphasis remap='I'>display</emphasis>;
-<!-- .br -->
- String <emphasis remap='I'>from_value</emphasis>, <emphasis remap='I'>to_type</emphasis>;
-<!-- .FN -->
+
+<funcsynopsis id='XtDisplayStringConversionWarning'>
+<funcprototype>
+<funcdef>void <function>XtDisplayStringConversionWarning</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>String <parameter>from_value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
<variablelist>
<varlistentry>
<term>
@@ -3197,8 +2123,6 @@ Specifies the target representation type requested.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
The
<function>XtDisplayStringConversionWarning</function>
procedure issues a warning message using
@@ -3207,31 +2131,28 @@ 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>
-<!-- .LP -->
To issue other types of warning or error messages, the type converter
should use
<function>XtAppWarningMsg</function>
or
-<function>XtAppErrorMsg .</function>
-<!-- .sp -->
+<function>XtAppErrorMsg</function>.
</para>
+
<para>
-<!-- .LP -->
To retrieve the application context associated with a given
display connection, use
-<function>XtDisplayToApplicationContext .</function>
+<function>XtDisplayToApplicationContext</function>.
</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtDisplayToApplicationContext" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-XtAppContext XtDisplayToApplicationContext( <emphasis remap='I'>display</emphasis> )
-<!-- .br -->
- Display *<emphasis remap='I'>display</emphasis>;
-<!-- .FN -->
+
+<funcsynopsis id='XtDisplayToApplicationContext'>
+<funcprototype>
+<funcdef>XtAppContext <function>XtDisplayToApplicationContext</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
<variablelist>
<varlistentry>
<term>
@@ -3245,51 +2166,559 @@ Specifies an open and initialized display connection.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
The
<function>XtDisplayToApplicationContext</function>
function returns the application
context in which the specified <emphasis remap='I'>display</emphasis> was initialized. If the
-display is not known to the (xI, an error message is issued.
-
+display is not known to the Intrinsics, an error message is issued.
</para>
-</sect3>
-<sect3 id="Registering_a_New_Resource_Converter">
+</sect2>
+
+<sect2 id="Registering_a_New_Resource_Converter">
<title>Registering a New Resource Converter</title>
-<!-- .XS -->
-<!-- <function>(SN Registering a New Resource Converter</function> -->
-<!-- .XE -->
<para>
-<!-- .LP -->
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>
+via an <function>XtCacheType</function>
+argument. </para>
+
+<literallayout class="monospaced">
+typedef int XtCacheType;
+</literallayout>
+
+<para>
+An <function>XtCacheType</function>
+field may contain one of the following values:
</para>
+
<para>
-<!-- .LP -->
-<!-- .IN "XtCacheType" "" "@DEF@" -->
-argument.
-<!-- .sM -->
+<function>XtCacheNone</function>
+</para>
+<itemizedlist>
+ <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>
+ <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>
+ <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
+<function>XtCloseDisplay</function>
+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
+<function>XtCreateWidget</function>,
+<function>XtCreateManagedWidget</function>,
+<function>XtGetApplicationResources</function>,
+and
+<function>XtGetSubresources</function>
+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
+<function>XtSetTypeConverter</function>,
+and to register a type converter in a single application context, use
+<function>XtAppSetTypeConverter</function>.
+</para>
+
+<funcsynopsis id='XtSetTypeConverter'>
+<funcprototype>
+<funcdef>void <function>XtSetTypeConverter</function></funcdef>
+ <paramdef>String <parameter>from_type</parameter></paramdef>
+ <paramdef>String <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> <function>XtAppSetTypeConverter</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>String <parameter>from_type</parameter></paramdef>
+ <paramdef>String <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>
+<function>XtSetTypeConverter</function>
+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.
+<function>XtAppSetTypeConverter</function>
+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
+<function>&lt; X11/Intrinsic.h &gt;.</function>
+</para>
<literallayout class="monospaced">
-typedef int XtCacheType;
+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;
</literallayout>
+<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 Chapter 12).
+<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
+<function>XtConvertArgProc</function>.
</para>
+
+<funcsynopsis id='XtConvertArgProc'>
+<funcprototype>
+<funcdef>typedef void <function>(*XtConvertArgProc)</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_2'>
+<title>Issuing Conversion Warnings</title>
+<para>
+The
+<function>XtDisplayStringConversionWarning</function>
+procedure is a convenience routine for resource type converters
+that convert from string values.
+</para>
+
+<funcsynopsis id='XtDisplayStringConversionWarning_2'>
+<funcprototype>
+<funcdef>void <function>XtDisplayStringConversionWarning</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>String <parameter>from_value</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>
-<!-- .LP -->
-<!-- .eM -->
-An
-<function>XtCacheType</function>
+The
+<function>XtDisplayStringConversionWarning</function>
+procedure issues a warning message using
+<function>XtAppWarningMsg</function>
+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
+<function>XtAppWarningMsg</function>
+or
+<function>XtAppErrorMsg</function>.
+</para>
+
+<para>
+To retrieve the application context associated with a given
+display connection, use
+<function>XtDisplayToApplicationContext</function>.
+</para>
+
+<funcsynopsis id='XtDisplayToApplicationContext_2'>
+<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
+<function>XtDisplayToApplicationContext</function>
+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_2'>
+<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>
+
+<literallayout class="monospaced">
+typedef int XtCacheType;
+</literallayout>
+
+<para>
+An <function>XtCacheType</function>
field may contain one of the following values:
-<!-- .br -->
-<!-- .sp -->
</para>
+
<para>
-<!-- .LP -->
<function>XtCacheNone</function>
-<!-- .IN "XtCacheNone" "" "@DEF@" -->
</para>
<itemizedlist>
<listitem>
@@ -3298,15 +2727,11 @@ 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.
-<!-- .br -->
-<!-- .sp -->
</para>
</listitem>
</itemizedlist>
<para>
-<!-- .LP -->
<function>XtCacheAll</function>
-<!-- .IN "XtCacheAll" "" "@DEF@" -->
</para>
<itemizedlist>
<listitem>
@@ -3314,15 +2739,11 @@ each time the converted value is required.
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.
-<!-- .br -->
-<!-- .sp -->
</para>
</listitem>
</itemizedlist>
<para>
-<!-- .LP -->
<function>XtCacheByDisplay</function>
-<!-- .IN "XtCacheByDisplay" "" "@DEF@" -->
</para>
<itemizedlist>
<listitem>
@@ -3339,56 +2760,43 @@ the value will be removed from the conversion cache.
</listitem>
</itemizedlist>
<para>
-<!-- .LP -->
The qualifier
<function>XtCacheRefCount</function>
-<!-- .IN "XtCacheRefCount" "" "@DEF@" -->
may be ORed with any of the above values. If
<function>XtCacheRefCount</function>
is specified, calls to
-<function>XtCreateWidget ,</function>
-<function>XtCreateManagedWidget ,</function>
-<function>XtGetApplicationResources ,</function>
+<function>XtCreateWidget</function>,
+<function>XtCreateManagedWidget</function>,
+<function>XtGetApplicationResources</function>,
and
<function>XtGetSubresources</function>
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>
-<!-- .LP -->
To register a type converter for all application contexts in a
process, use
-<function>XtSetTypeConverter ,</function>
+<function>XtSetTypeConverter</function>,
and to register a type converter in a single application context, use
-<function>XtAppSetTypeConverter .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtSetTypeConverter" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-void XtSetTypeConverter(<emphasis remap='I'>from_type</emphasis>, <emphasis remap='I'>to_type</emphasis>, <emphasis remap='I'>converter</emphasis>, \
-<emphasis remap='I'>convert_args</emphasis>, <emphasis remap='I'>num_args</emphasis>,
- <emphasis remap='I'>cache_type</emphasis>, <emphasis remap='I'>destructor</emphasis>)
-<!-- .br -->
- String <emphasis remap='I'>from_type</emphasis>;
-<!-- .br -->
- String <emphasis remap='I'>to_type</emphasis>;
-<!-- .br -->
- XtTypeConverter <emphasis remap='I'>converter</emphasis>;
-<!-- .br -->
- XtConvertArgList <emphasis remap='I'>convert_args</emphasis>;
-<!-- .br -->
- Cardinal <emphasis remap='I'>num_args</emphasis>;
-<!-- .br -->
- XtCacheType <emphasis remap='I'>cache_type</emphasis>;
-<!-- .br -->
- XtDestructor <emphasis remap='I'>destructor</emphasis>;
-<!-- .FN -->
+<function>XtAppSetTypeConverter</function>.
+</para>
+
+<funcsynopsis id='XtSetTypeConverter_2'>
+<funcprototype>
+<funcdef>void <function>XtSetTypeConverter</function></funcdef>
+ <paramdef>String <parameter>from_type</parameter></paramdef>
+ <paramdef>String <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>
@@ -3465,31 +2873,21 @@ required to deallocate resources produced by the converter.
</listitem>
</varlistentry>
</variablelist>
-<para>
-<!-- .LP -->
-<!-- .IN "XtAppSetTypeConverter" "" "@DEF@" -->
-</para>
-<!-- .FD 0 -->
-void XtAppSetTypeConverter(<emphasis remap='I'>app_context</emphasis>, <emphasis remap='I'>from_type</emphasis>, <emphasis remap='I'>to_type</emphasis>, \
-<emphasis remap='I'>converter</emphasis>, <emphasis remap='I'>convert_args</emphasis>,
- <emphasis remap='I'>num_args</emphasis>, <emphasis remap='I'>cache_type</emphasis>, <emphasis remap='I'>destructor</emphasis>)
-<!-- .br -->
- XtAppContext <emphasis remap='I'>app_context</emphasis>;
-<!-- .br -->
- String <emphasis remap='I'>from_type</emphasis>;
-<!-- .br -->
- String <emphasis remap='I'>to_type</emphasis>;
-<!-- .br -->
- XtTypeConverter <emphasis remap='I'>converter</emphasis>;
-<!-- .br -->
- XtConvertArgList <emphasis remap='I'>convert_args</emphasis>;
-<!-- .br -->
- Cardinal <emphasis remap='I'>num_args</emphasis>;
-<!-- .br -->
- XtCacheType <emphasis remap='I'>cache_type</emphasis>;
-<!-- .br -->
- XtDestructor <emphasis remap='I'>destructor</emphasis>;
-<!-- .FN -->
+
+<funcsynopsis id='XtAppSetTypeConverter_2'>
+<funcprototype>
+<funcdef> <function>XtAppSetTypeConverter</function></funcdef>
+ <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
+ <paramdef>String <parameter>from_type</parameter></paramdef>
+ <paramdef>String <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>
@@ -3577,8 +2975,6 @@ required to deallocate resources produced by the converter.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
<function>XtSetTypeConverter</function>
registers the specified type converter and
destructor in all application contexts created by the calling process,
@@ -3588,12 +2984,11 @@ 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.
-<!-- .sp -->
</para>
+
<para>
-<!-- .LP -->
For the few type converters that need additional arguments,
-the (xI conversion mechanism provides a method of specifying
+the Intrinsics conversion mechanism provides a method of specifying
how these arguments should be computed.
The enumerated type
<function>XtAddressMode</function>
@@ -3603,12 +2998,7 @@ specify how each argument is derived.
These are defined in
<function>&lt; X11/Intrinsic.h &gt;.</function>
</para>
-<para>
-<!-- .LP -->
-<!-- .sM -->
<literallayout class="monospaced">
-<!-- .TA .5i 2.5i -->
-<!-- .ta .5i 2.5i -->
typedef enum {
/* address mode parameter representation */
XtAddress, /* address */
@@ -3619,41 +3009,31 @@ typedef enum {
XtWidgetBaseOffset, /* offset */
XtProcedureArg /* procedure to call */
} XtAddressMode;
-<!-- .sp -->
typedef struct {
XtAddressMode address_mode;
XtPointer address_id;
Cardinal size;
} XtConvertArgRec, *XtConvertArgList;
</literallayout>
-<!-- .eM -->
-</para>
<para>
-<!-- .LP -->
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>
-<!-- .IN "XtAddress" "" "@DEF@" -->
causes <emphasis remap='I'>address_id</emphasis> to be interpreted as the address of the data.
<function>XtBaseOffset</function>
-<!-- .IN "XtBaseOffset" "" "@DEF@" -->
causes <emphasis remap='I'>address_id</emphasis> to be interpreted as the offset from the widget base.
<function>XtImmediate</function>
-<!-- .IN "XtImmediate" "" "@DEF@" -->
causes <emphasis remap='I'>address_id</emphasis> to be interpreted as a constant.
<function>XtResourceString</function>
-<!-- .IN "XtResourceString" "" "@DEF@" -->
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>
-<!-- .IN "XtResourceQuark" "" "@DEF@" -->
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>
-<!-- .IN "XtWidgetBaseOffset" "" "@DEF@" -->
is similar to
<function>XtBaseOffset</function>
except that it
@@ -3662,28 +3042,23 @@ of a subclass of
Core
(see Chapter 12).
<function>XtProcedureArg</function>
-<!-- .IN "XtProcedureArg" "" "@DEF@" -->
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
-<function>XtConvertArgProc .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtConvertArgProc" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-typedef void (*XtConvertArgProc)(Widget, Cardinal*, XrmValue*);
-<!-- .br -->
- Widget <emphasis remap='I'>object</emphasis>;
-<!-- .br -->
- Cardinal *<emphasis remap='I'>size</emphasis>;
-<!-- .br -->
- XrmValue *<emphasis remap='I'>value</emphasis>;
-<!-- .FN -->
+<function>XtConvertArgProc</function>.
+</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>
@@ -3695,7 +3070,7 @@ Passes the object for which the resource is being
converted, or NULL if the converter was invoked by
<function>XtCallConverter</function>
or
-<function>XtDirectConvert .</function>
+<function>XtDirectConvert</function>.
</para>
</listitem>
</varlistentry>
@@ -3706,7 +3081,7 @@ or
<listitem>
<para>
Passes a pointer to the <emphasis remap='I'>size</emphasis> field from the
-<function>XtConvertArgRec .</function>
+<function>XtConvertArgRec</function>.
</para>
</listitem>
</varlistentry>
@@ -3723,51 +3098,42 @@ must store the conversion argument.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
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 <emphasis remap='I'>value</emphasis>.
</para>
+
<para>
-<!-- .LP -->
In order to permit reentrancy, the
<function>XtConvertArgProc</function>
should return the address of storage whose lifetime is no shorter than the
lifetime of <emphasis remap='I'>object</emphasis>. If <emphasis remap='I'>object</emphasis> 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 (xI do not
+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>
-<!-- .LP -->
The following example illustrates how to register the CvtStringToPixel
routine given earlier:
</para>
-<para>
-<!-- .LP -->
<literallayout class="monospaced">
-<!-- .TA .2i 3i -->
-<!-- .ta .2i 3i -->
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);
</literallayout>
-</para>
<para>
-<!-- .LP -->
The conversion argument descriptors
<function>colorConvertArgs</function>
and
<function>screenConvertArg</function>
-are predefined by the (xI. Both take the
+are predefined by the Intrinsics. Both take the
values from the closest windowed ancestor if the object is not of a
subclass of
Core.
@@ -3778,8 +3144,8 @@ descriptor puts the widget's <emphasis remap='I'>screen</emphasis> field into <e
descriptor puts the widget's <emphasis remap='I'>screen</emphasis> field into <emphasis remap='I'>args</emphasis>[0],
and the widget's <emphasis remap='I'>colormap</emphasis> field into <emphasis remap='I'>args</emphasis>[1].
</para>
+
<para>
-<!-- .LP -->
Conversion routines should not just put a descriptor for the address of the
base of the widget into <emphasis remap='I'>args</emphasis>[0], and use that in the routine.
They should pass in the actual values on which the conversion depends.
@@ -3788,90 +3154,75 @@ 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>
-<!-- .LP -->
If any conversion arguments of type
-<function>XtBaseOffset ,</function>
-<function>XtResourceString ,</function>
-<function>XtResourceQuark ,</function>
+<function>XtBaseOffset</function>,
+<function>XtResourceString</function>,
+<function>XtResourceQuark</function>,
and
<function>XtWidgetBaseOffset</function>
are specified for conversions performed by
-<function>XtGetApplicationResources ,</function>
-<function>XtGetSubresources ,</function>
-<function>XtVaGetApplicationResources ,</function>
+<function>XtGetApplicationResources</function>,
+<function>XtGetSubresources</function>,
+<function>XtVaGetApplicationResources</function>,
or
-<function>XtVaGetSubresources ,</function>
+<function>XtVaGetSubresources</function>,
the arguments are
computed with respect to the specified widget, not the base address or
resource list specified in the call.
</para>
+
<para>
-<!-- .LP -->
If the
<function>XtConvertArgProc</function>
modifies the resource database,
the changes affect any in-progress widget creation,
-<function>XtGetApplicationResources ,</function>
+<function>XtGetApplicationResources</function>,
or
<function>XtGetSubresources</function>
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>
-</sect3>
-<sect3 id="Resource_Converter_Invocation">
+</sect2>
+
+<sect2 id="Resource_Converter_Invocation">
<title>Resource Converter Invocation</title>
-<!-- .XS -->
-<!-- <function>(SN Resource Converter Invocation</function> -->
-<!-- .XE -->
<para>
-<!-- .LP -->
All resource-fetching routines (for example,
-<function>XtGetSubresources ,</function>
-<function>XtGetApplicationResources ,</function>
+<function>XtGetSubresources</function>,
+<function>XtGetApplicationResources</function>,
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.
-<!-- .sp -->
</para>
+
<para>
-<!-- .LP -->
To invoke explicit resource conversions, use
<function>XtConvertAndStore</function>
or
-<function>XtCallConverter .</function>
+<function>XtCallConverter</function>.
</para>
-<para>
-<!-- .LP -->
-<!-- .sM -->
<literallayout class="monospaced">
typedef XtPointer XtCacheRef;
</literallayout>
-<!-- .IN "XtCallConverter" "" "@DEF@" -->
-</para>
-<!-- .FD 0 -->
-Boolean XtCallConverter(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>converter</emphasis>, \
-<emphasis remap='I'>conversion_args</emphasis>, <emphasis remap='I'>num_args</emphasis>, <emphasis remap='I'>from</emphasis>, <emphasis remap='I'>to_in_out</emphasis>,
- <emphasis remap='I'>cache_ref_return</emphasis>)
-<!-- .br -->
- Display* <emphasis remap='I'>display</emphasis>;
-<!-- .br -->
- XtTypeConverter <emphasis remap='I'>converter</emphasis>;
-<!-- .br -->
- XrmValuePtr <emphasis remap='I'>conversion_args</emphasis>;
-<!-- .br -->
- Cardinal <emphasis remap='I'>num_args</emphasis>;
-<!-- .br -->
- XrmValuePtr <emphasis remap='I'>from</emphasis>;
-<!-- .br -->
- XrmValuePtr <emphasis remap='I'>to_in_out</emphasis>;
-<!-- .br -->
- XtCacheRef *<emphasis remap='I'>cache_ref_return</emphasis>;
-<!-- .FN -->
+
+<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>
@@ -3946,8 +3297,6 @@ Returns a conversion cache id.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
The
<function>XtCallConverter</function>
function looks up the
@@ -3956,7 +3305,7 @@ the display and, if the converter was not registered or was registered
with cache type
<function>XtCacheAll</function>
or
-<function>XtCacheByDisplay ,</function>
+<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
@@ -3969,24 +3318,24 @@ otherwise it checks the size specified in the <emphasis remap='I'>to</emphasis>
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-&gt;addr</emphasis>, stores the cache size into <emphasis remap='I'>to-&gt;size</emphasis>, and returns
-<function>True .</function>
+<function>True</function>.
If the size specified in the <emphasis remap='I'>to</emphasis> argument is smaller than the size stored
in the cache,
<function>XtCallConverter</function>
copies the cache size into <emphasis remap='I'>to-&gt;size</emphasis> and returns
-<function>False .</function>
+<function>False</function>.
If the converter was registered with cache type
<function>XtCacheNone</function>
or no value was found in the conversion cache,
<function>XtCallConverter</function>
calls the converter, and if it was not registered with cache type
-<function>XtCacheNone ,</function>
+<function>XtCacheNone</function>,
enters the result in the cache.
<function>XtCallConverter</function>
then returns what the converter returned.
</para>
+
<para>
-<!-- .LP -->
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
@@ -3998,28 +3347,24 @@ the converted value is no longer required. The <emphasis remap='I'>cache_ref_re
argument should be
NULL if the caller is unwilling or unable to store the
value.
-<!-- .sp -->
</para>
+
<para>
-<!-- .LP -->
To explicitly decrement the reference counts for resources obtained
from
-<function>XtCallConverter ,</function>
+<function>XtCallConverter</function>,
use
-<function>XtAppReleaseCacheRefs .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtAppReleaseCacheRefs" "" "@DEF@" -->
-<!-- .sM -->
+<function>XtAppReleaseCacheRefs</function>.
</para>
-<!-- .FD 0 -->
-void XtAppReleaseCacheRefs(<emphasis remap='I'>app_context</emphasis>, <emphasis remap='I'>refs</emphasis>)
-<!-- .br -->
- XtAppContext <emphasis remap='I'>app_context</emphasis>;
-<!-- .br -->
- XtCacheRef *<emphasis remap='I'>refs</emphasis>;
-<!-- .FN -->
+
+<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>
@@ -4043,8 +3388,6 @@ Specifies the list of cache references to be released.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
<function>XtAppReleaseCacheRefs</function>
decrements the reference count for the
conversion entries identified by the <emphasis remap='I'>refs</emphasis> argument.
@@ -4054,31 +3397,26 @@ pointer to a NULL-terminated list of
values. If any reference
count reaches zero, the destructor, if any, will be called and
the resource removed from the conversion cache.
-<!-- .sp -->
</para>
+
<para>
-<!-- .LP -->
As a convenience to clients needing to explicitly decrement reference
-counts via a callback function, the (xI define two callback
+counts via a callback function, the Intrinsics define two callback
procedures,
<function>XtCallbackReleaseCacheRef</function>
and
-<function>XtCallbackReleaseCacheRefList .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtCallbackReleaseCacheRef" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-void XtCallbackReleaseCacheRef(<emphasis remap='I'>object</emphasis>, <emphasis remap='I'>client_data</emphasis>, <emphasis remap='I'>call_data</emphasis>)
-<!-- .br -->
- Widget <emphasis remap='I'>object</emphasis>;
-<!-- .br -->
- XtPointer <emphasis remap='I'>client_data</emphasis>;
-<!-- .br -->
- XtPointer <emphasis remap='I'>call_data</emphasis>;
-<!-- .FN -->
+<function>XtCallbackReleaseCacheRefList</function>.
+</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>
@@ -4112,8 +3450,6 @@ Is ignored.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
This callback procedure may be added to a callback list to release a
previously returned
<function>XtCacheRef</function>
@@ -4121,22 +3457,18 @@ 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>
-<para>
-<!-- .LP -->
-<!-- .IN "XtCallbackReleaseCacheRefList" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-void XtCallbackReleaseCacheRefList(<emphasis remap='I'>object</emphasis>, <emphasis remap='I'>client_data</emphasis>, <emphasis remap='I'>call_data</emphasis>)
-<!-- .br -->
- Widget <emphasis remap='I'>object</emphasis>;
-<!-- .br -->
- XtPointer <emphasis remap='I'>client_data</emphasis>;
-<!-- .br -->
- XtPointer <emphasis remap='I'>call_data</emphasis>;
-<!-- .FN -->
+<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>
@@ -4170,8 +3502,6 @@ Is ignored.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
This callback procedure may be added to a callback list to release a
list of previously returned
<function>XtCacheRef</function>
@@ -4180,33 +3510,25 @@ callback, the callback <emphasis remap='I'>client_data</emphasis> argument must
pointer to a NULL-terminated list of
<function>XtCacheRef</function>
values.
-<!-- .sp -->
</para>
+
<para>
-<!-- .LP -->
To lookup and call a resource converter, copy the resulting value,
and free a cached resource when a widget is destroyed, use
-<function>XtConvertAndStore .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtConvertAndStore" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-Boolean XtConvertAndStore(<emphasis remap='I'>object</emphasis>, <emphasis remap='I'>from_type</emphasis>, <emphasis remap='I'>from</emphasis>, \
-<emphasis remap='I'>to_type</emphasis>, <emphasis remap='I'>to_in_out</emphasis>)
-<!-- .br -->
- Widget <emphasis remap='I'>object</emphasis>;
-<!-- .br -->
- String <emphasis remap='I'>from_type</emphasis>;
-<!-- .br -->
- XrmValuePtr <emphasis remap='I'>from</emphasis>;
-<!-- .br -->
- String <emphasis remap='I'>to_type</emphasis>;
-<!-- .br -->
- XrmValuePtr <emphasis remap='I'>to_in_out</emphasis>;
-<!-- .FN -->
+<function>XtConvertAndStore</function>.
+</para>
+
+<funcsynopsis id='XtConvertAndStore'>
+<funcprototype>
+<funcdef>Boolean <function>XtConvertAndStore</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+ <paramdef>String <parameter>from_type</parameter></paramdef>
+ <paramdef>XrmValuePtr <parameter>from</parameter></paramdef>
+ <paramdef>String <parameter>to_type</parameter></paramdef>
+ <paramdef>XrmValuePtr <parameter>to_in_out</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
<variablelist>
<varlistentry>
<term>
@@ -4215,7 +3537,7 @@ Boolean XtConvertAndStore(<emphasis remap='I'>object</emphasis>, <emphasis remap
<listitem>
<para>
Specifies the object to use for additional arguments, if any are needed,
-and the destroy callback list. (oI
+and the destroy callback list. Must be of class Object or any subclass thereof.
</para>
</listitem>
</varlistentry>
@@ -4262,8 +3584,6 @@ will be returned.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
The
<function>XtConvertAndStore</function>
function looks up the type converter registered
@@ -4275,7 +3595,7 @@ needed, and then calls
if an old-style converter was registered with
<function>XtAddConverter</function>
or
-<function>XtAppAddConverter ;</function>
+<function>XtAppAddConverter</function>;
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
@@ -4291,24 +3611,23 @@ size of the converted data.
If the conversion succeeds,
<function>XtConvertAndStore</function>
returns
-<function>True ;</function>
+<function>True</function>;
otherwise, it returns
-<function>False .</function>
+<function>False</function>.
</para>
+
<para>
-<!-- .LP -->
<function>XtConvertAndStore</function>
adds
<function>XtCallbackReleaseCacheRef</function>
-<!-- .IN "destroyCallback" -->
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>
-<!-- .LP -->
<function>XtCreateWidget</function>
performs processing equivalent to
<function>XtConvertAndStore</function>
@@ -4318,20 +3637,19 @@ 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>
-<!-- .LP -->
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,
-<!-- .IN "XtNinitialResourcesPersistent" "" "@DEF@" -->
class
XtCInitialResourcesPersistent.
</para>
+
<para>
-<!-- .LP -->
When
<function>XtCreateWidget</function>
is called, if this resource is not specified as
@@ -4340,62 +3658,48 @@ 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>
+<function>True</function>;
thus clients that expect to destroy one or
more objects and want resources deallocated must explicitly specify
<function>False</function>
for
-<!-- .IN XtNinitialResourcesPersistent -->
XtNinitialResourcesPersistent.
</para>
+
<para>
-<!-- .LP -->
The resources are still freed and destructors called when
<function>XtCloseDisplay</function>
is called if the conversion was registered as
-<function>XtCacheByDisplay .</function>
-
+<function>XtCacheByDisplay</function>.
</para>
-</sect3>
</sect2>
-<sect2 id="Reading_and_Writing_Widget_State">
+</sect1>
+
+<sect1 id="Reading_and_Writing_Widget_State">
<title>Reading and Writing Widget State</title>
-<!-- .XS -->
-<!-- <function>(SN Reading and Writing Widget State</function> -->
-<!-- .XE -->
<para>
-<!-- .LP -->
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>
-<sect3 id="Obtaining_Widget_State">
+<sect2 id="Obtaining_Widget_State">
<title>Obtaining Widget State</title>
-<!-- .XS -->
-<!-- <function>(SN Obtaining Widget State</function> -->
-<!-- .XE -->
<para>
-<!-- .LP -->
To retrieve the current values of resources associated with a
widget instance, use
-<function>XtGetValues .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtGetValues" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-void XtGetValues(<emphasis remap='I'>object</emphasis>, <emphasis remap='I'>args</emphasis>, <emphasis remap='I'>num_args</emphasis>)
-<!-- .br -->
- Widget <emphasis remap='I'>object</emphasis>;
-<!-- .br -->
- ArgList <emphasis remap='I'>args</emphasis>;
-<!-- .br -->
- Cardinal <emphasis remap='I'>num_args</emphasis>;
-<!-- .FN -->
+<function>XtGetValues</function>.
+</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>
@@ -4403,7 +3707,7 @@ void XtGetValues(<emphasis remap='I'>object</emphasis>, <emphasis remap='I'>args
</term>
<listitem>
<para>
-Specifies the object whose resource values are to be returned. (oI
+Specifies the object whose resource values are to be returned. Must be of class Object or any subclass thereof.
</para>
</listitem>
</varlistentry>
@@ -4432,8 +3736,6 @@ Specifies the number of entries in the argument list.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
The
<function>XtGetValues</function>
function starts with the resources specified for the Object class
@@ -4442,13 +3744,12 @@ The <emphasis remap='I'>value</emphasis> field of a passed argument list must co
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
-(xI-defined resources, the following lifetimes apply:
+Intrinsics-defined resources, the following lifetimes apply:
</para>
<itemizedlist>
<listitem>
<para>
Not valid following any operation that modifies the resource:
-<!-- .RS -->
</para>
</listitem>
<listitem>
@@ -4459,45 +3760,39 @@ XtNchildren resource of composite widgets.
<listitem>
<para>
All resources of representation type XtRCallback.
-<!-- .RE -->
</para>
</listitem>
<listitem>
<para>
Remain valid at least until the widget is destroyed:
-<!-- .RS -->
</para>
</listitem>
<listitem>
<para>
XtNaccelerators, XtNtranslations.
-<!-- .RE -->
</para>
</listitem>
<listitem>
<para>
Remain valid until the Display is closed:
-<!-- .RS -->
</para>
</listitem>
<listitem>
<para>
XtNscreen.
-<!-- .RE -->
</para>
</listitem>
</itemizedlist>
<para>
-<!-- .LP -->
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>
-<!-- .LP -->
If the class of the object's parent is a subclass of
-<function>constraintWidgetClass ,</function>
+<function>constraintWidgetClass</function>,
<function>XtGetValues</function>
then fetches the values for any constraint resources requested.
It starts with the constraint resources specified for
@@ -4506,55 +3801,50 @@ 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.
-<!-- .IN "get_values_hook procedure" -->
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
-<function>XtGetValues .</function>
+<function>XtGetValues</function>.
Finally, if the object's parent is a
subclass of
-<function>constraintWidgetClass ,</function>
+<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
-<function>\s-1NULLQUARK\s+1 ,</function>
+<function>\s-1NULLQUARK\s+1</function>,
and if the <emphasis remap='I'>get_values_hook</emphasis> field in the extension record is non-NULL,
<function>XtGetValues</function>
calls the get_values_hook procedures in superclass-to-subclass order.
This permits a Constraint parent to provide
nonresource data via
-<function>XtGetValues .</function>
+<function>XtGetValues</function>.
</para>
+
<para>
-<!-- .LP -->
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 (xI-defined object classes copy
+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.
-
-<!-- .sp -->
</para>
+
<para>
-<!-- .LP -->
To retrieve the current values of resources associated with a widget
instance using varargs lists, use
-<function>XtVaGetValues .</function>
+<function>XtVaGetValues</function>.
</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtVaGetValues" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-void XtVaGetValues(<emphasis remap='I'>object</emphasis>, ...)
-<!-- .br -->
- Widget <emphasis remap='I'>object</emphasis>;
-<!-- .FN -->
+
+<funcsynopsis id='XtVaGetValues'>
+<funcprototype>
+<funcdef>void <function>XtVaGetValues</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
<variablelist>
<varlistentry>
<term>
@@ -4562,7 +3852,7 @@ void XtVaGetValues(<emphasis remap='I'>object</emphasis>, ...)
</term>
<listitem>
<para>
-Specifies the object whose resource values are to be returned. (oI
+Specifies the object whose resource values are to be returned. Must be of class Object or any subclass thereof.
</para>
</listitem>
</varlistentry>
@@ -4579,8 +3869,6 @@ be returned.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
<function>XtVaGetValues</function>
is identical in function to
<function>XtGetValues</function>
@@ -4596,35 +3884,27 @@ specifies the representation desired by the caller and <emphasis remap='I'>the</
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>
-<sect4 id="Widget_Subpart_Resource_Data_The_get_values_hook_Procedure">
+<sect3 id="Widget_Subpart_Resource_Data_The_get_values_hook_Procedure">
<title>Widget Subpart Resource Data: The get_values_hook Procedure</title>
-<!-- .XS -->
-<!-- (SN Widget Subpart Resource Data: The get_values_hook Procedure -->
-<!-- .XE -->
<para>
-<!-- .LP -->
Widgets that have subparts can return resource values from them through
<function>XtGetValues</function>
by supplying a get_values_hook procedure.
The get_values_hook procedure pointer is of type
-<function>XtArgsProc .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "get_values_hook procedure" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-typedef void (*XtArgsProc)(Widget, ArgList, Cardinal*);
-<!-- .br -->
- Widget <emphasis remap='I'>w</emphasis>;
-<!-- .br -->
- ArgList <emphasis remap='I'>args</emphasis>;
-<!-- .br -->
- Cardinal *<emphasis remap='I'>num_args</emphasis>;
-<!-- .FN -->
+<function>XtArgsProc</function>.
+</para>
+
+<funcsynopsis id='XtArgsProc'>
+<funcprototype>
+<funcdef>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>
@@ -4645,7 +3925,7 @@ Specifies the widget whose subpart resource values are to be retrieved.
Specifies the argument list that was passed to
<function>XtGetValues</function>
or the transformed varargs list passed to
-<function>XtVaGetValues .</function>
+<function>XtVaGetValues</function>.
</para>
</listitem>
</varlistentry>
@@ -4661,47 +3941,33 @@ Specifies the number of entries in the argument list.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
The widget with subpart resources should call
<function>XtGetSubvalues</function>
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>
-</sect4>
-<sect4 id="Widget_Subpart_State">
+</sect3>
+<sect3 id="Widget_Subpart_State">
<title>Widget Subpart State</title>
-<!-- .XS -->
-<!-- (SN Widget Subpart State -->
-<!-- .XE -->
<para>
-<!-- .LP -->
To retrieve the current values of subpart resource data associated with a
widget instance, use
-<function>XtGetSubvalues .</function>
+<function>XtGetSubvalues</function>.
For a discussion of subpart resources,
see Section 9.4.
</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtGetSubvalues" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-void XtGetSubvalues(<emphasis remap='I'>base</emphasis>, <emphasis remap='I'>resources</emphasis>, <emphasis remap='I'>num_resources</emphasis>, \
-<emphasis remap='I'>args</emphasis>, <emphasis remap='I'>num_args</emphasis>)
-<!-- .br -->
- XtPointer <emphasis remap='I'>base</emphasis>;
-<!-- .br -->
- XtResourceList <emphasis remap='I'>resources</emphasis>;
-<!-- .br -->
- Cardinal <emphasis remap='I'>num_resources</emphasis>;
-<!-- .br -->
- ArgList <emphasis remap='I'>args</emphasis>;
-<!-- .br -->
- Cardinal <emphasis remap='I'>num_args</emphasis>;
-<!-- .FN -->
+
+<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>
@@ -4758,8 +4024,6 @@ Specifies the number of entries in the argument list.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
The
<function>XtGetSubvalues</function>
function obtains resource values from the structure identified by <emphasis remap='I'>base</emphasis>.
@@ -4769,29 +4033,23 @@ 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.
-
-<!-- .sp -->
</para>
+
<para>
-<!-- .LP -->
To retrieve the current values of subpart resources associated with
a widget instance using varargs lists, use
-<function>XtVaGetSubvalues .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtVaGetSubvalues" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-void XtVaGetSubvalues(<emphasis remap='I'>base</emphasis>, <emphasis remap='I'>resources</emphasis>, <emphasis remap='I'>num_resources</emphasis>, ...)
-<!-- .br -->
- XtPointer <emphasis remap='I'>base</emphasis>;
-<!-- .br -->
- XtResourceList <emphasis remap='I'>resources</emphasis>;
-<!-- .br -->
- Cardinal <emphasis remap='I'>num_resources</emphasis>;
-<!-- .FN -->
+<function>XtVaGetSubvalues</function>.
+</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>
+</funcprototype>
+</funcsynopsis>
+
<variablelist>
<varlistentry>
<term>
@@ -4838,8 +4096,6 @@ values are to be stored.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
<function>XtVaGetSubvalues</function>
is identical in function to
<function>XtGetSubvalues</function>
@@ -4848,40 +4104,32 @@ with the
in Section 2.5.1.
<function>XtVaTypedArg</function>
is not supported for
-<function>XtVaGetSubvalues .</function>
+<function>XtVaGetSubvalues</function>.
If
<function>XtVaTypedArg</function>
is specified in the list, a warning message is issued
and the entry is then ignored.
-
</para>
-</sect4>
</sect3>
-<sect3 id="Setting_Widget_State">
+</sect2>
+
+<sect2 id="Setting_Widget_State">
<title>Setting Widget State</title>
-<!-- .XS -->
-<!-- <function>(SN Setting Widget State</function> -->
-<!-- .XE -->
<para>
-<!-- .LP -->
To modify the current values of resources associated with a widget
instance, use
-<function>XtSetValues .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtSetValues" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-void XtSetValues(<emphasis remap='I'>object</emphasis>, <emphasis remap='I'>args</emphasis>, <emphasis remap='I'>num_args</emphasis>)
-<!-- .br -->
- Widget <emphasis remap='I'>object</emphasis>;
-<!-- .br -->
- ArgList <emphasis remap='I'>args</emphasis>;
-<!-- .br -->
- Cardinal <emphasis remap='I'>num_args</emphasis>;
-<!-- .FN -->
+<function>XtSetValues</function>.
+</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>
@@ -4889,7 +4137,7 @@ void XtSetValues(<emphasis remap='I'>object</emphasis>, <emphasis remap='I'>args
</term>
<listitem>
<para>
-Specifies the object whose resources are to be modified. (oI
+Specifies the object whose resources are to be modified. Must be of class Object or any subclass thereof.
</para>
</listitem>
</varlistentry>
@@ -4916,8 +4164,6 @@ Specifies the number of entries in the argument list.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
The
<function>XtSetValues</function>
function starts with the resources specified for the
@@ -4928,17 +4174,16 @@ specified in the argument list.
<function>XtSetValues</function>
then calls the set_values procedures for the object in superclass-to-subclass
order.
-<!-- .IN "set_values_hook procedure" -->
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
-<function>XtSetValues .</function>
+<function>XtSetValues</function>.
</para>
+
<para>
-<!-- .LP -->
If the class of the object's parent is a subclass of
-<function>constraintWidgetClass ,</function>
+<function>constraintWidgetClass</function>,
<function>XtSetValues</function>
also updates the object's constraints.
It starts with the constraint resources specified for
@@ -4955,8 +4200,8 @@ 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>
-<!-- .LP -->
If the object is of a subclass of
RectObj,
<function>XtSetValues</function>
@@ -4966,20 +4211,20 @@ If any geometry changes are required,
<function>XtSetValues</function>
restores the original geometry and makes the request on behalf of the widget.
If the geometry manager returns
-<function>XtGeometryYes ,</function>
+<function>XtGeometryYes</function>,
<function>XtSetValues</function>
calls the object's resize procedure.
If the geometry manager returns
-<function>XtGeometryDone ,</function>
+<function>XtGeometryDone</function>,
<function>XtSetValues</function>
continues, as the object's resize procedure should have been called
by the geometry manager.
If the geometry manager returns
-<function>XtGeometryNo ,</function>
+<function>XtGeometryNo</function>,
<function>XtSetValues</function>
ignores the geometry request and continues.
If the geometry manager returns
-<function>XtGeometryAlmost ,</function>
+<function>XtGeometryAlmost</function>,
<function>XtSetValues</function>
calls the set_values_almost procedure,
which determines what should be done.
@@ -4987,33 +4232,30 @@ which determines what should be done.
then repeats this process,
deciding once more whether the geometry manager should be called.
</para>
+
<para>
-<!-- .LP -->
Finally, if any of the set_values procedures returned
-<function>True ,</function>
+<function>True</function>,
and the widget is realized,
<function>XtSetValues</function>
causes the widget's expose procedure to be invoked by calling
<function>XClearArea</function>
on the widget's window.
-<!-- .sp -->
</para>
+
<para>
-<!-- .LP -->
To modify the current values of resources associated with a widget
instance using varargs lists, use
-<function>XtVaSetValues .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtVaSetValues" "" "@DEF@" -->
-<!-- .sM -->
+<function>XtVaSetValues</function>.
</para>
-<!-- .FD 0 -->
-void XtVaSetValues(<emphasis remap='I'>object</emphasis>, ...)
-<!-- .br -->
- Widget <emphasis remap='I'>object</emphasis>;
-<!-- .FN -->
+
+<funcsynopsis id='XtVaSetValues'>
+<funcprototype>
+<funcdef>void <function>XtVaSetValues</function></funcdef>
+ <paramdef>Widget <parameter>object</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
<variablelist>
<varlistentry>
<term>
@@ -5021,7 +4263,7 @@ void XtVaSetValues(<emphasis remap='I'>object</emphasis>, ...)
</term>
<listitem>
<para>
-Specifies the object whose resources are to be modified. (oI
+Specifies the object whose resources are to be modified. Must be of class Object or any subclass thereof.
</para>
</listitem>
</varlistentry>
@@ -5038,44 +4280,31 @@ contain the resources to be modified and their new values.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
<function>XtVaSetValues</function>
is identical in function to
<function>XtSetValues</function>
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>
-<sect4 id="Widget_State_The_set_values_Procedure">
+<sect3 id="Widget_State_The_set_values_Procedure">
<title>Widget State: The set_values Procedure</title>
-<!-- .XS -->
-<!-- (SN Widget State: The set_values Procedure -->
-<!-- .XE -->
<para>
-<!-- .LP -->
The set_values procedure pointer in a widget class is of type
-<function>XtSetValuesFunc .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtSetValuesFunc" "" "@DEF@" -->
-<!-- .IN "set_values procedure" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-typedef Boolean (*XtSetValuesFunc)(Widget, Widget, Widget, ArgList, Cardinal*);
-<!-- .br -->
- Widget <emphasis remap='I'>current</emphasis>;
-<!-- .br -->
- Widget <emphasis remap='I'>request</emphasis>;
-<!-- .br -->
- Widget <emphasis remap='I'>new</emphasis>;
-<!-- .br -->
- ArgList <emphasis remap='I'>args</emphasis>;
-<!-- .br -->
- Cardinal *<emphasis remap='I'>num_args</emphasis>;
-<!-- .FN -->
+<function>XtSetValuesFunc</function>.
+</para>
+
+<funcsynopsis id='XtSetValuesFunc'>
+<funcprototype>
+<funcdef>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>
@@ -5120,7 +4349,7 @@ Specifies the widget with the new values that are actually allowed.
Specifies the argument list passed to
<function>XtSetValues</function>
or the transformed argument list passed to
-<function>XtVaSetValues .</function>
+<function>XtVaSetValues</function>.
</para>
</listitem>
</varlistentry>
@@ -5136,8 +4365,6 @@ Specifies the number of entries in the argument list.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
The set_values procedure should recompute any field
derived from resources that are changed
(for example, many GCs depend on foreground and background pixels).
@@ -5145,15 +4372,15 @@ 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>
-<!-- .LP -->
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>
-<!-- .LP -->
Sometimes a subclass may want to overwrite values filled in by its
superclass.
In particular, size calculations of a superclass are often
@@ -5161,8 +4388,8 @@ incorrect for a subclass, and, in this case,
the subclass must modify or recalculate fields declared
and computed by its superclass.
</para>
+
<para>
-<!-- .LP -->
As an example,
a subclass can visually surround its superclass display.
In this case, the width and height calculated by the superclass set_values
@@ -5174,8 +4401,8 @@ 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>
-<!-- .LP -->
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,
@@ -5188,8 +4415,8 @@ unless it must resolve conflicts between the <emphasis remap='I'>current</emphas
Any changes the widget needs to make, including geometry changes,
should be made in the <emphasis remap='I'>new</emphasis> widget.
</para>
+
<para>
-<!-- .LP -->
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.
@@ -5200,8 +4427,8 @@ 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>
-<!-- .LP -->
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;
@@ -5209,20 +4436,20 @@ 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>
-<!-- .LP -->
-Before calling the set_values procedures, the (xI modify the
+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>
-<!-- .LP -->
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>
+<function>True</function>;
the X server will eventually generate an
<function>Expose</function>
event, if necessary.
@@ -5231,58 +4458,47 @@ After calling all the set_values procedures,
forces a redisplay by calling
<function>XClearArea</function>
if any of the set_values procedures returned
-<function>True .</function>
+<function>True</function>.
Therefore, a set_values procedure should not try to do its own redisplaying.
</para>
+
<para>
-<!-- .LP -->
Set_values procedures should not do any work in response to changes in
geometry because
<function>XtSetValues</function>
eventually will perform a geometry request, and that request might be denied.
If the widget actually changes size in response to a
call to
-<function>XtSetValues ,</function>
+<function>XtSetValues</function>,
its resize procedure is called.
Widgets should do any geometry-related work in their resize procedure.
</para>
+
<para>
-<!-- .LP -->
Note that it is permissible to call
<function>XtSetValues</function>
before a widget is realized.
Therefore, the set_values procedure must not assume that the widget is realized.
-
</para>
-</sect4>
-<sect4 id="Widget_State_The_set_values_almost_Procedure">
+</sect3>
+<sect3 id="Widget_State_The_set_values_almost_Procedure">
<title>Widget State: The set_values_almost Procedure</title>
-<!-- .XS -->
-<!-- (SN Widget State: The set_values_almost Procedure -->
-<!-- .XE -->
<para>
-<!-- .LP -->
The set_values_almost procedure pointer in the widget class record is of type
-<function>XtAlmostProc .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "set_values_almost procedure" "" "@DEF@" -->
-<!-- .IN "XtAlmostProc" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-typedef void (*XtAlmostProc)(Widget, Widget, XtWidgetGeometry*, \
-XtWidgetGeometry*);
-<!-- .br -->
- Widget <emphasis remap='I'>old</emphasis>;
-<!-- .br -->
- Widget <emphasis remap='I'>new</emphasis>;
-<!-- .br -->
- XtWidgetGeometry *<emphasis remap='I'>request</emphasis>;
-<!-- .br -->
- XtWidgetGeometry *<emphasis remap='I'>reply</emphasis>;
-<!-- .FN -->
+<function>XtAlmostProc</function>.
+</para>
+
+<funcsynopsis id='XtAlmostProc'>
+<funcprototype>
+<funcdef>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>
@@ -5327,14 +4543,12 @@ to be returned.
<para>
Specifies the compromise geometry that was returned by the geometry
manager with
-<function>XtGeometryAlmost .</function>
+<function>XtGeometryAlmost</function>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
Most classes inherit the set_values_almost procedure from their superclass by
specifying
<function>XtInheritSetValuesAlmost</function>
@@ -5344,8 +4558,8 @@ set_values_almost procedure in
<function>rectObjClass</function>
accepts the compromise suggested.
</para>
+
<para>
-<!-- .LP -->
The set_values_almost procedure is called when a client tries to set a widget's
geometry by means of a call to
<function>XtSetValues</function>
@@ -5379,19 +4593,13 @@ argument; to terminate the geometry negotiation and retain the
original geometry, the procedure must set <emphasis remap='I'>request-&gt;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>
-</sect4>
-<sect4 id="Widget_State_The_ConstraintClassPart_set_values_Procedure">
+</sect3>
+<sect3 id="Widget_State_The_ConstraintClassPart_set_values_Procedure">
<title>Widget State: The ConstraintClassPart set_values Procedure</title>
-<!-- .XS -->
-<!-- (SN Widget State: The ConstraintClassPart set_values Procedure -->
-<!-- .XE -->
-<!-- .IN "set_values procedure" -->
<para>
-<!-- .LP -->
The constraint set_values procedure pointer is of type
-<function>XtSetValuesFunc .</function>
+<function>XtSetValuesFunc</function>.
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.
@@ -5399,8 +4607,8 @@ A class can specify NULL for the <emphasis remap='I'>set_values</emphasis> field
<function>ConstraintPart</function>
if it need not compute anything.
</para>
+
<para>
-<!-- .LP -->
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.
@@ -5408,41 +4616,29 @@ 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>
-</sect4>
-<sect4 id="Widget_Subpart_State">
+</sect3>
+<sect3 id='Widget_Subpart_State_2'>
<title>Widget Subpart State</title>
-<!-- .XS -->
-<!-- (SN Widget Subpart State -->
-<!-- .XE -->
<para>
-<!-- .LP -->
To set the current values of subpart resources associated with a
widget instance, use
-<function>XtSetSubvalues .</function>
+<function>XtSetSubvalues</function>.
For a discussion of subpart resources,
see Section 9.4.
</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtSetSubvalues" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-void XtSetSubvalues(<emphasis remap='I'>base</emphasis>, <emphasis remap='I'>resources</emphasis>, <emphasis remap='I'>num_resources</emphasis>, \
-<emphasis remap='I'>args</emphasis>, <emphasis remap='I'>num_args</emphasis>)
-<!-- .br -->
- XtPointer <emphasis remap='I'>base</emphasis>;
-<!-- .br -->
- XtResourceList <emphasis remap='I'>resources</emphasis>;
-<!-- .br -->
- Cardinal <emphasis remap='I'>num_resources</emphasis>;
-<!-- .br -->
- ArgList <emphasis remap='I'>args</emphasis>;
-<!-- .br -->
- Cardinal <emphasis remap='I'>num_args</emphasis>;
-<!-- .FN -->
+
+<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>
@@ -5498,35 +4694,28 @@ Specifies the number of entries in the argument list.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
The
<function>XtSetSubvalues</function>
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.
-<!-- .sp -->
</para>
+
<para>
-<!-- .LP -->
To set the current values of subpart resources associated with
a widget instance using varargs lists, use
-<function>XtVaSetSubvalues .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "XtVaSetSubvalues" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-void XtVaSetSubvalues(<emphasis remap='I'>base</emphasis>, <emphasis remap='I'>resources</emphasis>, <emphasis remap='I'>num_resources</emphasis>, ...)
-<!-- .br -->
- XtPointer <emphasis remap='I'>base</emphasis>;
-<!-- .br -->
- XtResourceList <emphasis remap='I'>resources</emphasis>;
-<!-- .br -->
- Cardinal <emphasis remap='I'>num_resources</emphasis>;
-<!-- .FN -->
+<function>XtVaSetSubvalues</function>.
+</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>
+</funcprototype>
+</funcsynopsis>
+
<variablelist>
<varlistentry>
<term>
@@ -5572,8 +4761,6 @@ contain the resources to be modified and their new values.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
<function>XtVaSetSubvalues</function>
is identical in function to
<function>XtSetSubvalues</function>
@@ -5581,48 +4768,39 @@ with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</e
described in Section 2.5.1.
<function>XtVaTypedArg</function>
is not supported for
-<function>XtVaSetSubvalues .</function>
+<function>XtVaSetSubvalues</function>.
If an entry containing
<function>XtVaTypedArg</function>
is specified in the list, a warning message is issued
and the entry is ignored.
-
</para>
-</sect4>
-<sect4 id="Widget_Subpart_Resource_Data_The_set_values_hook_Procedure">
+</sect3>
+
+<sect3 id='Widget_Subpart_Resource_Data_The_set_values_hook_Procedure'>
<title>Widget Subpart Resource Data: The set_values_hook Procedure</title>
-<!-- .XS -->
-<!-- (SN Widget Subpart Resource Data: The set_values_hook Procedure -->
-<!-- .XE -->
-<!-- .IN "set_values_hook procedure" -->
-<!-- .NT -->
+<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.
-<!-- .NE -->
+</para>
+</note>
<para>
-<!-- .LP -->
Widgets that have a subpart can set the subpart resource values through
<function>XtSetValues</function>
by supplying a set_values_hook procedure.
The set_values_hook procedure pointer in a widget class is of type
-<function>XtArgsFunc .</function>
-</para>
-<para>
-<!-- .LP -->
-<!-- .IN "set_values_hook procedure" "" "@DEF@" -->
-<!-- .IN "XtArgsFunc" "" "@DEF@" -->
-<!-- .sM -->
-</para>
-<!-- .FD 0 -->
-typedef Boolean (*XtArgsFunc)(Widget, Arglist, Cardinal*);
-<!-- .br -->
- Widget <emphasis remap='I'>w</emphasis>;
-<!-- .br -->
- Arglist <emphasis remap='I'>args</emphasis>;
-<!-- .br -->
- Cardinal *<emphasis remap='I'>num_args</emphasis>;
-<!-- .FN -->
+<function>XtArgsFunc</function>.
+</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>
@@ -5643,7 +4821,7 @@ Specifies the widget whose subpart resource values are to be changed.
Specifies the argument list that was passed to
<function>XtSetValues</function>
or the transformed varargs list passed to
-<function>XtVaSetValues .</function>
+<function>XtVaSetValues</function>.
</para>
</listitem>
</varlistentry>
@@ -5659,79 +4837,13 @@ Specifies the number of entries in the argument list.
</varlistentry>
</variablelist>
<para>
-<!-- .LP -->
-<!-- .eM -->
The widget with subpart resources may call
<function>XtSetValues</function>
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.
-<!-- .bp -->
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
</para>
-</sect4>
</sect3>
</sect2>
+</sect1>
</chapter>
-</book>
generated by cgit v1.2.3 (git 2.39.1) at 2024-05-14 02:33:54 +0000