summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMatt Dew <marcoz@osource.org>2011-10-24 22:02:19 -0600
committerMatt Dew <marcoz@osource.org>2011-10-24 22:02:19 -0600
commit0aeb779aa1e954d253816151559480672351da0e (patch)
tree4f0c01eafdca5f80ede79e857bbce34b786e2f88
parent457ae7c4ca14dd0d489ad8697bda46e40cefee3f (diff)
proofread CH01.xml; formatting not done, but tables complete
-rw-r--r--specs/CH01.xml384
1 files changed, 222 insertions, 162 deletions
diff --git a/specs/CH01.xml b/specs/CH01.xml
index 92a97d2..4dab491 100644
--- a/specs/CH01.xml
+++ b/specs/CH01.xml
@@ -213,7 +213,7 @@ All widget classes contain the fields defined in the
<function>CoreClassPart</function>
structure.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct {
WidgetClass superclass; See Section 1.6
String class_name; See Chapter 9
@@ -257,7 +257,7 @@ and
<function>CoreWidgetClass</function>
are defined with only this set of fields.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct {
CoreClassPart core_class;
} WidgetClassRec, *WidgetClass, CoreClassRec, *CoreWidgetClass;
@@ -276,7 +276,7 @@ creating instances of Core are
In
<function>IntrinsicP.h</function>:
</para>
-<literallayout class="monospaced">
+<literallayout>
extern WidgetClassRec widgetClassRec;
#define coreClassRec widgetClassRec
</literallayout>
@@ -284,7 +284,7 @@ extern WidgetClassRec widgetClassRec;
In
<function>Intrinsic.h</function>:
</para>
-<literallayout class="monospaced">
+<literallayout>
extern WidgetClass widgetClass, coreWidgetClass;
</literallayout>
<para>
@@ -300,7 +300,7 @@ does not allow applications to access private data, the Intrinsics use
incomplete structure definitions in
<function>Intrinsic.h</function>:
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct _WidgetClassRec *WidgetClass, *CoreWidgetClass;
</literallayout>
</sect3>
@@ -311,7 +311,7 @@ All widget instances contain the fields defined in the
<function>CorePart</function>
structure.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct _CorePart {
Widget self; Described below
WidgetClass widget_class; See Section 1.6
@@ -349,7 +349,7 @@ The prototypical type
<function>Widget</function>
is defined with only this set of fields.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct {
CorePart core;
} WidgetRec, *Widget, CoreRec, *CoreWidget;
@@ -365,7 +365,7 @@ does not allow applications to access private data, the Intrinsics use
incomplete structure definitions in
<function>Intrinsic.h</function>.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct _WidgetRec *Widget, *CoreWidget;
</literallayout>
</sect3>
@@ -376,11 +376,11 @@ The resource names, classes, and representation types specified in the
<function>coreClassRec</function>
resource list are
</para>
-<informaltable>
+<informaltable width='100%'>
<tgroup cols='3' align='center'>
- <colspec colname='c1'/>
- <colspec colname='c2'/>
- <colspec colname='c3'/>
+ <colspec colname='c1' colwidth='1.0*'/>
+ <colspec colname='c2' colwidth='1.0*'/>
+ <colspec colname='c3' colwidth='1.0*'/>
<tbody>
<row>
<entry>Name</entry>
@@ -456,8 +456,8 @@ from the resource lists, and by the initialize procedures, are
</para>
<informaltable>
<tgroup cols='2' align='center'>
- <colspec colname='c1'/>
- <colspec colname='c2'/>
+ <colspec colname='c1' colwidth='1.0*'/>
+ <colspec colname='c2' colwidth='1.0*'/>
<tbody>
<row>
<entry>Field</entry>
@@ -619,7 +619,7 @@ Core
class fields,
widgets of the Composite class have the following class fields.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct {
XtGeometryHandler geometry_manager; See Chapter 6
XtWidgetProc change_managed; See Chapter 3
@@ -637,7 +637,7 @@ equal to
is
<function>CompositeClassExtensionRec</function>.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct {
XtPointer next_extension; See Section 1.6.12
XrmQuark record_type; See Section 1.6.12
@@ -652,7 +652,7 @@ Composite
classes have the Composite class fields immediately following the
Core class fields.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct {
CoreClassPart core_class;
CompositeClassPart composite_class;
@@ -667,14 +667,14 @@ instances of Composite are
In
<function>IntrinsicP.h</function>:
</para>
-<literallayout class="monospaced">
+<literallayout>
extern CompositeClassRec compositeClassRec;
</literallayout>
<para>
In
<function>Intrinsic.h</function>:
</para>
-<literallayout class="monospaced">
+<literallayout>
extern WidgetClass compositeWidgetClass;
</literallayout>
<para>
@@ -696,7 +696,7 @@ uses an incomplete structure
definition to ensure that the compiler catches attempts to access
private data.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct _CompositeClassRec *CompositeWidgetClass;
</literallayout>
</sect3>
@@ -711,7 +711,7 @@ instance fields defined in the
<function>CompositePart</function>
structure.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct {
WidgetList children; See Chapter 3
Cardinal num_children; See Chapter 3
@@ -724,7 +724,7 @@ Composite
widgets have the Composite instance fields immediately following the Core
instance fields.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct {
CorePart core;
CompositePart composite;
@@ -735,7 +735,7 @@ typedef struct {
uses an incomplete structure definition to ensure that the
compiler catches attempts to access private data.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct _CompositeRec *CompositeWidget;
</literallayout>
</sect3>
@@ -749,29 +749,18 @@ the
resource list are
</para>
-<para>
<informaltable>
- <tgroup cols='4' align='center'>
- <colspec colname='c1'/>
- <colspec colname='c2'/>
- <colspec colname='c3'/>
- <colspec colname='c4'/>
+ <tgroup cols='3' align='left'>
+ <colspec colname='c1' colwidth='1.0*'/>
+ <colspec colname='c2' colwidth='1.0*'/>
+ <colspec colname='c3' colwidth='1.0*'/>
<tbody>
<row>
- <entry>lw(1.5i) lw(1.5i) lw(2i) .</entry>
- </row>
- <row>
- <entry>_</entry>
- </row>
- <row>
<entry>Name</entry>
<entry>Class</entry>
<entry>Representation</entry>
</row>
<row>
- <entry>_</entry>
- </row>
- <row>
<entry>XtNchildren</entry>
<entry>XtCReadOnly</entry>
<entry>XtRWidgetList</entry>
@@ -786,13 +775,10 @@ resource list are
<entry>XtCReadOnly</entry>
<entry>XtRCardinal</entry>
</row>
- <row>
- <entry>_</entry>
- </row>
</tbody>
</tgroup>
</informaltable>
-</para>
+
</sect3>
<sect3 id="CompositePart_Default_Values">
<title>CompositePart Default Values</title>
@@ -805,19 +791,33 @@ Composite
initialize procedure, are
</para>
-<para>
-<informaltable>
- <tgroup cols='3' align='center'>
+<informaltable frame='none' pgwide='0'>
+<?dbfo table-width="50%" ?>
+ <tgroup cols='2' align='left'>
+ <colspec colname='c1' colwidth='1.0*' colsep='0'/>
+ <colspec colname='c2' colwidth='1.0*' colsep='0'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Default Value</entry>
+ </row>
+ </thead>
<tbody>
- <row>
- <entry></entry>
- <entry></entry>
- <entry></entry>
+ <row rowsep='0'>
+ <entry>children</entry><entry>NULL</entry>
+ </row>
+ <row rowsep='0'>
+ <entry>num_children</entry><entry>0</entry>
+ </row>
+ <row rowsep='0'>
+ <entry>num_slots</entry><entry>0</entry>
+ </row>
+ <row rowsep='0'>
+ <entry>insert_position</entry><entry>Internal function to insert at end</entry>
</row>
</tbody>
</tgroup>
</informaltable>
-</para>
<para>
The <emphasis remap='I'>children</emphasis>, <emphasis remap='I'>num_children</emphasis>,
@@ -861,7 +861,7 @@ class fields,
widgets of the Constraint class
have the following class fields.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct {
XtResourceList resources; See Chapter 9
Cardinal num_resources; See Chapter 9
@@ -880,7 +880,7 @@ with <emphasis remap='I'>record_type</emphasis> equal to
is
<function>ConstraintClassExtensionRec</function>.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct {
XtPointer next_extension; See Section 1.6.12
XrmQuark record_type; See Section 1.6.12
@@ -894,7 +894,7 @@ Constraint
classes have the Constraint class fields immediately following the
Composite class fields.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct _ConstraintClassRec {
CoreClassPart core_class;
CompositeClassPart composite_class;
@@ -910,14 +910,14 @@ instances of Constraint are
In
<function>IntrinsicP.h</function>:
</para>
-<literallayout class="monospaced">
+<literallayout>
extern ConstraintClassRec constraintClassRec;
</literallayout>
<para>
In
<function>Intrinsic.h</function>:
</para>
-<literallayout class="monospaced">
+<literallayout>
extern WidgetClass constraintWidgetClass;
</literallayout>
<para>
@@ -939,7 +939,7 @@ version identifier is
uses an incomplete structure definition to ensure that the
compiler catches attempts to access private data.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct _ConstraintClassRec *ConstraintWidgetClass;
</literallayout>
</sect3>
@@ -956,7 +956,7 @@ instance fields defined in the
<function>ConstraintPart</function>
structure
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct {
int empty;
} ConstraintPart;
@@ -966,7 +966,7 @@ Constraint
widgets have the Constraint instance fields immediately following the
Composite instance fields.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct {
CorePart core;
CompositePart composite;
@@ -978,7 +978,7 @@ typedef struct {
uses an incomplete structure definition to ensure that the
compiler catches attempts to access private data.
</para>
-<literallayout class="monospaced">
+<literallayout>
typedef struct _ConstraintRec *ConstraintWidget;
</literallayout>
</sect3>
@@ -1010,33 +1010,61 @@ and chosen by, each individual implementation of the Intrinsics.
<para>
These implementation-defined types are
</para>
-<itemizedlist>
- <listitem>
- <para>
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis role='bold'>Boolean</emphasis>
+ </term>
+ <listitem>
+ <para>
A datum that contains a zero or nonzero value.
Unless explicitly stated, clients should not assume
that the nonzero value is equal to the symbolic
value
<function>True</function>.
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis role='bold'>Cardinal</emphasis>
+ </term>
+ <listitem>
+ <para>
An unsigned integer datum with a minimum range of [0..2^16-1].
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis role='bold'>Dimension</emphasis>
+ </term>
+ <listitem>
+ <para>
An unsigned integer datum with a minimum range of [0..2^16-1].
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis role='bold'>Position</emphasis>
+ </term>
+ <listitem>
+ <para>
A signed integer datum with a minimum range of [-2^15..2^15-1].
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis role='bold'>XtPointer</emphasis>
+ </term>
+ <listitem>
+ <para>
A datum large enough to contain the largest of a char*, int*, function
pointer, structure pointer, or long value. A pointer
to any type or function, or a long value may be converted
@@ -1048,10 +1076,16 @@ environments it is expected that
<function>XtPointer</function>
will be
defined as void*.
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis role='bold'>XtArgVal</emphasis>
+ </term>
+ <listitem>
+ <para>
A datum large enough to contain an
<function>XtPointer</function>,
<function>Cardinal</function>,
@@ -1059,10 +1093,16 @@ A datum large enough to contain an
or
<function>Position</function>
value.
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis role='bold'>XtEnum</emphasis>
+ </term>
+ <listitem>
+ <para>
An integer datum large enough to encode at least 128 distinct
values, two of which are the symbolic values
<function>True</function>
@@ -1078,9 +1118,11 @@ also defined to be equal to
and
<function>False</function>,
respectively.
- </para>
- </listitem>
-</itemizedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
<para>
In addition to these specific types, the precise order of the
fields within the structure declarations for any of the instance
@@ -1244,44 +1286,48 @@ Given a new class name AbcXyz, you should derive several names:
</para>
</listitem>
<listitem>
- <para>
+ <itemizedlist>
+ <listitem>
+ <para>
Additional widget instance structure part name AbcXyzPart.
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
Complete widget instance structure names AbcXyzRec and _AbcXyzRec.
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
Widget instance structure pointer type name AbcXyzWidget.
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
Additional class structure part name AbcXyzClassPart.
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
Complete class structure names AbcXyzClassRec and _AbcXyzClassRec.
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
Class structure pointer type name AbcXyzWidgetClass.
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
Class structure variable abcXyzClassRec.
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
Class structure pointer variable abcXyzWidgetClass.
- </para>
+ </para>
+ </listitem>
+ </itemizedlist>
</listitem>
<listitem>
<para>
@@ -1358,7 +1404,7 @@ Entry points for new class methods.
For example, the following is the public .h file for a possible
implementation of a Label widget:
</para>
-<literallayout class="monospaced">
+<literallayout>
#ifndef LABEL_H
#define LABEL_H
/* New resources */
@@ -1495,7 +1541,7 @@ An inherit constant for each new procedure in the widget class part structure.
<para>
For example, the following is the private .h file for a possible Label widget:
</para>
-<literallayout class="monospaced">
+<literallayout>
#ifndef LABELP_H
#define LABELP_H
#include &lt;X11/Label.h&gt;
@@ -1522,7 +1568,7 @@ typedef struct {
Boolean display_sensitive;
} LabelPart;
</literallayout>
-<literallayout class="monospaced">
+<literallayout>
/* Full instance record declaration */
typedef struct _LabelRec {
CorePart core;
@@ -1668,7 +1714,7 @@ The following is an abbreviated version of the .c file
for a Label widget.
The resources table is described in Chapter 9.
</para>
-<literallayout class="monospaced">
+<literallayout>
/* Resources specific to Label */
static XtResource resources[] = {
{XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel),
@@ -1693,7 +1739,7 @@ static void GetText();
.
.
</literallayout>
-<literallayout class="monospaced">
+<literallayout>
/* Class record constant */
LabelClassRec labelClassRec = {
{
@@ -2006,32 +2052,36 @@ With a linked field,
the Intrinsics access the field's value only after accessing its corresponding
superclass value (called downward superclass chaining) or
before accessing its corresponding superclass value (called upward superclass
-chaining). The self-contained fields are
-In all widget classes: <emphasis remap='I'>class_name</emphasis>
- <emphasis remap='I'>class_initialize</emphasis>
- <emphasis remap='I'>widget_size</emphasis>
- <emphasis remap='I'>realize</emphasis>
- <emphasis remap='I'>visible_interest</emphasis>
- <emphasis remap='I'>resize</emphasis>
- <emphasis remap='I'>expose</emphasis>
- <emphasis remap='I'>accept_focus</emphasis>
- <emphasis remap='I'>compress_motion</emphasis>
- <emphasis remap='I'>compress_exposure</emphasis>
- <emphasis remap='I'>compress_enterleave</emphasis>
- <emphasis remap='I'>set_values_almost</emphasis>
- <emphasis remap='I'>tm_table</emphasis>
- <emphasis remap='I'>version</emphasis>
- <emphasis remap='I'>allocate</emphasis>
- <emphasis remap='I'>deallocate</emphasis>
+chaining). The self-contained fields are</para>
+<literallayout>
+In all widget classes: <emphasis remap='I'>class_name</emphasis>
+ <emphasis remap='I'>class_initialize</emphasis>
+ <emphasis remap='I'>widget_size</emphasis>
+ <emphasis remap='I'>realize</emphasis>
+ <emphasis remap='I'>visible_interest</emphasis>
+ <emphasis remap='I'>resize</emphasis>
+ <emphasis remap='I'>expose</emphasis>
+ <emphasis remap='I'>accept_focus</emphasis>
+ <emphasis remap='I'>compress_motion</emphasis>
+ <emphasis remap='I'>compress_exposure</emphasis>
+ <emphasis remap='I'>compress_enterleave</emphasis>
+ <emphasis remap='I'>set_values_almost</emphasis>
+ <emphasis remap='I'>tm_table</emphasis>
+ <emphasis remap='I'>version</emphasis>
+ <emphasis remap='I'>allocate</emphasis>
+ <emphasis remap='I'>deallocate</emphasis>
+
In Composite widget classes: <emphasis remap='I'>geometry_manager</emphasis>
- <emphasis remap='I'>change_managed</emphasis>
- <emphasis remap='I'>insert_child</emphasis>
- <emphasis remap='I'>delete_child</emphasis>
- <emphasis remap='I'>accepts_objects</emphasis>
- <emphasis remap='I'>allows_change_managed_set</emphasis>
-In Constraint widget classes: <emphasis remap='I'>constraint_size</emphasis>
-In Shell widget classes: <emphasis remap='I'>root_geometry_manager</emphasis>
-</para>
+ <emphasis remap='I'>change_managed</emphasis>
+ <emphasis remap='I'>insert_child</emphasis>
+ <emphasis remap='I'>delete_child</emphasis>
+ <emphasis remap='I'>accepts_objects</emphasis>
+ <emphasis remap='I'>allows_change_managed_set</emphasis>
+
+In Constraint widget classes: <emphasis remap='I'>constraint_size</emphasis>
+
+In Shell widget classes: <emphasis remap='I'>root_geometry_manager</emphasis>
+</literallayout>
<para>
With downward superclass chaining,
@@ -2042,14 +2092,16 @@ and
Core
class structures, then from the subclass structure, and so on down the class chain to
that widget's class structure. These superclass-to-subclass fields are
- <emphasis remap='I'>class_part_initialize</emphasis>
- <emphasis remap='I'>get_values_hook</emphasis>
- <emphasis remap='I'>initialize</emphasis>
- <emphasis remap='I'>initialize_hook</emphasis>
- <emphasis remap='I'>set_values</emphasis>
- <emphasis remap='I'>set_values_hook</emphasis>
- <emphasis remap='I'>resources</emphasis>
</para>
+<literallayout>
+ <emphasis remap='I'>class_part_initialize</emphasis>
+ <emphasis remap='I'>get_values_hook</emphasis>
+ <emphasis remap='I'>initialize</emphasis>
+ <emphasis remap='I'>initialize_hook</emphasis>
+ <emphasis remap='I'>set_values</emphasis>
+ <emphasis remap='I'>set_values_hook</emphasis>
+ <emphasis remap='I'>resources</emphasis>
+</literallayout>
<para>
In addition, for subclasses of
@@ -2061,11 +2113,13 @@ and
structures are chained from the
Constraint
class down to the subclass:
+</para>
+<literallayout>
<emphasis remap='I'>resources</emphasis>
<emphasis remap='I'>initialize</emphasis>
<emphasis remap='I'>set_values</emphasis>
<emphasis remap='I'>get_values_hook</emphasis>
-</para>
+</literallayout>
<para>
With upward superclass chaining,
@@ -2078,9 +2132,11 @@ and
Object
class structures.
The subclass-to-superclass fields are
+</para>
+<literallayout>
<emphasis remap='I'>destroy</emphasis>
<emphasis remap='I'>actions</emphasis>
-</para>
+</literallayout>
<para>
For subclasses of
@@ -2203,7 +2259,7 @@ a class structure is constant.
<para>
The following example provides the class initialization procedure for a Label class.
</para>
-<literallayout class="monospaced">
+<literallayout>
static void ClassInitialize()
{
XtSetTypeConverter(XtRString, XtRJustify, CvtStringToJustify,
@@ -2334,7 +2390,7 @@ For example,
<function>CompositeP.h</function>
contains these definitions:
</para>
-<literallayout class="monospaced">
+<literallayout>
#define XtInheritGeometryManager ((XtGeometryHandler) _XtInherit)
#define XtInheritChangeManaged ((XtWidgetProc) _XtInherit)
#define XtInheritInsertChild ((XtArgsProc) _XtInherit)
@@ -2343,7 +2399,7 @@ contains these definitions:
<para>
Composite's class_part_initialize procedure begins as follows:
</para>
-<literallayout class="monospaced">
+<literallayout>
static void CompositeClassPartInitialize(widgetClass)
WidgetClass widgetClass;
{
@@ -2479,6 +2535,7 @@ and then calling
to add the child to the managed set.
</para>
+<note>
<para>
A class method should not use
<function>XtSuperclass</function>
@@ -2488,6 +2545,9 @@ That is, it should use its own class pointers only,
not the widget's class pointers,
as the widget's class may be a subclass of the
class whose implementation is being referenced.
+</para>
+</note>
+<para>
This technique is referred to as <emphasis remap='I'>enveloping</emphasis> the superclass's operation.
</para>
</sect2>
@@ -2525,7 +2585,7 @@ declared as a linked list, and each extension record definition should
contain the following four fields at the beginning of the structure
declaration:
</para>
-<literallayout class="monospaced">
+<literallayout>
struct {
XtPointer next_extension;
XrmQuark record_type;