diff options
author | Matt Dew <marcoz@osource.org> | 2011-10-24 22:02:19 -0600 |
---|---|---|
committer | Matt Dew <marcoz@osource.org> | 2011-10-24 22:02:19 -0600 |
commit | 0aeb779aa1e954d253816151559480672351da0e (patch) | |
tree | 4f0c01eafdca5f80ede79e857bbce34b786e2f88 | |
parent | 457ae7c4ca14dd0d489ad8697bda46e40cefee3f (diff) |
proofread CH01.xml; formatting not done, but tables complete
-rw-r--r-- | specs/CH01.xml | 384 |
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 <X11/Label.h> @@ -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; |