Initial docbook conversion.

1 files changed, 1166 insertions, 0 deletions

diff --git a/specs/CH12.xml b/specs/CH12.xml
new file mode 100644
index 0000000..3ae6542
--- /dev/null
+++ b/specs/CH12.xml
@@ -0,0 +1,1166 @@
+<chapter id='Nonwidget_Objects'>
+<title>Nonwidget Objects</title>
+
+<para>
+Although widget writers are free to treat
+Core
+as the base class of
+the widget hierarchy, there are actually three classes above it.
+These classes are
+Object,
+RectObj
+(Rectangle Object), and (unnamed),
+and members of these classes
+are referred to generically as <emphasis remap='I'>objects</emphasis>.  By convention, the term
+<emphasis remap='I'>widget</emphasis> refers only to objects that are a subclass of
+Core,
+and the term <emphasis remap='I'>nonwidget</emphasis> refers to objects that are not a subclass of
+Core.
+In the preceding portion of this specification, the interface
+descriptions indicate explicitly whether the generic <emphasis remap='I'>widget</emphasis> argument
+is restricted to particular subclasses of Object.  Sections 12.2.5,
+12.3.5, and 12.5 summarize the permissible classes of the arguments to, and
+return values from, each of the Intrinsics routines.
+</para>
+<sect1 id="Data_Structures">
+<title>Data Structures</title>
+<para>
+In order not to conflict with previous widget code, the data
+structures used by nonwidget objects do not follow all the same
+conventions as those for widgets.  In particular, the class records
+are not composed of parts but instead are complete data structures
+with filler for the widget fields they do not use.  This
+allows the static class initializers for existing widgets to remain
+unchanged.
+</para>
+</sect1>
+
+<sect1 id="Object_Objects">
+<title>Object Objects</title>
+<para>
+The
+Object
+object contains the definitions of fields common to all
+objects.  It encapsulates the mechanisms for resource management.
+All objects and widgets are members of subclasses of
+Object,
+which is defined by the
+<function>ObjectClassPart</function>
+and
+<function>ObjectPart</function>
+structures.
+</para>
+<sect2 id="ObjectClassPart_Structure">
+<title>ObjectClassPart Structure</title>
+<para>
+The common fields for all object classes are defined in the
+<function>ObjectClassPart</function>
+structure.  All fields have the same purpose,
+function, and restrictions as the corresponding fields in
+<function>CoreClassPart</function>;
+fields whose
+names are obj<emphasis remap='I'>n</emphasis> for some integer <emphasis remap='I'>n</emphasis> are not
+used for Object,
+but exist to pad the data structure so that it matches Core's class
+record.  The class record initialization must fill all
+obj<emphasis remap='I'>n</emphasis> fields with NULL or zero as appropriate to the type.
+</para>
+<literallayout >
+typedef struct _ObjectClassPart {
+	WidgetClass superclass;
+	String class_name;
+	Cardinal widget_size;
+	XtProc class_initialize;
+	XtWidgetClassProc class_part_initialize;
+	XtEnum class_inited;
+	XtInitProc initialize;
+	XtArgsProc initialize_hook;
+	XtProc obj1;
+	XtPointer obj2;
+	Cardinal obj3;
+	XtResourceList resources;
+	Cardinal num_resources;
+	XrmClass xrm_class;
+	Boolean obj4;
+	XtEnum obj5;
+	Boolean obj6;
+	Boolean obj7;
+	XtWidgetProc destroy;
+	XtProc obj8;
+	XtProc obj9;
+	XtSetValuesFunc set_values;
+	XtArgsFunc set_values_hook;
+	XtProc obj10;
+	XtArgsProc get_values_hook;
+	XtProc obj11;
+	XtVersionType version;
+	XtPointer callback_private;
+	String obj12;
+	XtProc obj13;
+	XtProc obj14;
+	XtPointer extension;
+} ObjectClassPart;
+</literallayout>
+<para>
+The extension record defined for
+<function>ObjectClassPart</function>
+with a <emphasis remap='I'>record_type</emphasis> equal to
+<emphasis role='strong'>NULLQUARK</emphasis>
+is
+<function>ObjectClassExtensionRec</function>.
+</para>
+<literallayout >
+typedef struct {
+	XtPointer next_extension;    See <xref linkend='Class_Extension_Records' />
+	XrmQuark record_type;        See <xref linkend='Class_Extension_Records' />
+	long version;                See <xref linkend='Class_Extension_Records' />
+	Cardinal record_size;        See <xref linkend='Class_Extension_Records' />
+	XtAllocateProc allocate;     See <xref linkend='Widget_Instance_Allocation_The_allocate_Procedure' />.
+	XtDeallocateProc deallocate; See <xref linkend='Widget_Instance_Deallocation_The_deallocate_Procedure' />.
+} ObjectClassExtensionRec, *ObjectClassExtension;
+</literallayout>
+<para>
+The prototypical
+<function>ObjectClass</function>
+consists of just the
+<function>ObjectClassPart</function>.
+</para>
+<literallayout >
+typedef struct _ObjectClassRec {
+	ObjectClassPart object_class;
+} ObjectClassRec, *ObjectClass;
+</literallayout>
+<para>
+The predefined class record and pointer for
+<function>ObjectClassRec</function>
+are
+</para>
+
+<para>
+In
+<function>IntrinsicP.h</function>:
+</para>
+<literallayout >
+extern ObjectClassRec objectClassRec;
+</literallayout>
+<para>
+In
+<function>Intrinsic.h</function>:
+</para>
+<literallayout >
+extern WidgetClass objectClass;
+</literallayout>
+<para>
+The opaque types
+<function>Object</function>
+and
+<function>ObjectClass</function>
+and the opaque variable
+<function>objectClass</function>
+are defined for generic actions on objects.
+The symbolic constant for the
+<function>ObjectClassExtension</function>
+version identifier is
+<function>XtObjectExtensionVersion</function>
+(see <xref linkend='Class_Extension_Records' />).
+<function>Intrinsic.h</function>
+uses an incomplete structure definition to ensure that the
+compiler catches attempts to access private data:
+</para>
+<literallayout >
+typedef struct _ObjectClassRec* ObjectClass;
+</literallayout>
+
+</sect2>
+
+<sect2 id="ObjectPart_Structure">
+<title>ObjectPart Structure</title>
+<para>
+The common fields for all object instances are defined in the
+<function>ObjectPart</function>
+structure.  All fields have the same meaning as the
+corresponding fields in
+<function>CorePart</function>.
+</para>
+<literallayout >
+typedef struct _ObjectPart {
+	Widget self;
+	WidgetClass widget_class;
+	Widget parent;
+	Boolean being_destroyed;
+	XtCallbackList destroy_callbacks;
+	XtPointer constraints;
+} ObjectPart;
+</literallayout>
+<para>
+All object instances have the
+Object
+fields as their first component.  The prototypical type
+<function>Object</function>
+is defined with only this set of fields.
+Various routines can cast object pointers, as needed, to specific
+object types.
+</para>
+
+<para>
+In
+<function>IntrinsicP.h</function>:
+</para>
+<literallayout >
+typedef struct _ObjectRec {
+	ObjectPart object;
+} ObjectRec, *Object;
+</literallayout>
+<para>
+In
+<function>Intrinsic.h</function>:
+</para>
+<literallayout >
+typedef struct _ObjectRec *Object;
+</literallayout>
+
+</sect2>
+
+<sect2 id="Object_Resources">
+<title>Object Resources</title>
+<para>
+The resource names, classes, and representation types specified in the
+<function>objectClassRec</function>
+resource list are:
+</para>
+
+<informaltable frame='topbot'>
+  <?dbfo keep-together="always" ?>
+  <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+  <colspec colwidth='1.0*' colname='c1'/>
+  <colspec colwidth='1.0*' colname='c2'/>
+  <colspec colwidth='1.0*' colname='c3'/>
+  <thead>
+    <row rowsep='1'>
+      <entry>Name</entry>
+      <entry>Class</entry>
+      <entry>Representation</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry>XtNdestroyCallback</entry>
+      <entry>XtCCallback</entry>
+      <entry>XtRCallback</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+</sect2>
+
+<sect2 id="ObjectPart_Default_Values">
+<title>ObjectPart Default Values</title>
+<para>
+All fields in
+<function>ObjectPart</function>
+have the same default values as the corresponding fields in
+<function>CorePart</function>.
+</para>
+</sect2>
+
+<sect2 id="Object_Arguments_to_xI_Routines">
+<title>Object Arguments to Intrinsics Routines</title>
+<para>
+The WidgetClass arguments to the following procedures may be
+<function>objectClass</function>
+or any subclass:
+</para>
+
+<para>
+<emphasis role='strong'>XtInitializeWidgetClass</emphasis>,
+<emphasis role='strong'>XtCreateWidget</emphasis>,
+<emphasis role='strong'>XtVaCreateWidget</emphasis>
+<emphasis role='strong'>XtIsSubclass</emphasis>,
+<emphasis role='strong'>XtCheckSubclass</emphasis>
+<emphasis role='strong'>XtGetResourceList</emphasis>,
+<emphasis role='strong'>XtGetConstraintResourceList</emphasis>
+</para>
+
+<para>
+The Widget arguments to the following procedures may be of class
+Object
+or any subclass:
+</para>
+<itemizedlist spacing='compact'>
+  <listitem>
+    <para>
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtAddCallback' xrefstyle='select: title'/>,
+<xref linkend='XtAddCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveAllCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtCallCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtHasCallbacks' xrefstyle='select: title'/>,
+<xref linkend='XtCallCallbackList' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtClass' xrefstyle='select: title'/>,
+<function>XtSuperclass</function>,
+<xref linkend='XtIsSubclass' xrefstyle='select: title'/>,
+<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>,
+<function>XtIsObject</function>,
+<function>XtIsRectObj</function>,
+<function>XtIsWidget</function>,
+<function>XtIsComposite</function>,
+<function>XtIsConstraint</function>,
+<function>XtIsShell</function>,
+<function>XtIsOverrideShell</function>,
+<function>XtIsWMShell</function>,
+<function>XtIsVendorShell</function>,
+<function>XtIsTransientShell</function>,
+<function>XtIsToplevelShell</function>,
+<function>XtIsApplicationShell</function>,
+<function>XtIsSessionShell</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtIsManaged' xrefstyle='select: title'/>,
+<xref linkend='XtIsSensitive' xrefstyle='select: title'/>
+(both will return
+<function>False</function>
+if argument is not a subclass of
+RectObj)
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtIsRealized' xrefstyle='select: title'/>
+(returns the state of the nearest windowed ancestor
+if class of argument is not a subclass of
+Core)
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtWidgetToApplicationContext' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XtParent</function>,
+<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>,
+<xref linkend='XtScreenOfObject' xrefstyle='select: title'/>,
+<xref linkend='XtWindowOfObject' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>
+(descendant)
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtGetGC' xrefstyle='select: title'/>,
+<xref linkend='XtReleaseGC' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtName' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtSetValues' xrefstyle='select: title'/>,
+<xref linkend='XtGetValues' xrefstyle='select: title'/>,
+<xref linkend='XtVaSetValues' xrefstyle='select: title'/>,
+<xref linkend='XtVaGetValues' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtGetSubresources' xrefstyle='select: title'/>,
+<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>,
+<xref linkend='XtVaGetSubresources' xrefstyle='select: title'/>,
+<xref linkend='XtVaGetApplicationResources' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtConvert' xrefstyle='select: title'/>,
+<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+The return value of the following procedures will be of class
+Object
+or a subclass:
+</para>
+<itemizedlist spacing='compact'>
+  <listitem>
+    <para>
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XtParent</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtNameToWidget' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+The return value of the following procedures will be
+<function>objectClass</function>
+or a subclass:
+</para>
+<itemizedlist spacing='compact'>
+  <listitem>
+    <para>
+<xref linkend='XtClass' xrefstyle='select: title'/>,
+<function>XtSuperclass</function>
+    </para>
+  </listitem>
+</itemizedlist>
+</sect2>
+
+<sect2 id="Use_of_Objects">
+<title>Use of Objects</title>
+<para>
+The
+Object
+class exists to enable programmers to use the Intrinsics'
+classing and resource-handling mechanisms for things smaller
+and simpler than widgets.
+Objects make obsolete many common uses of subresources as described in
+Sections 9.4, 9.7.2.4, and 9.7.2.5.
+</para>
+
+<para>
+Composite
+widget classes that wish to accept nonwidget children must
+set the <emphasis remap='I'>accepts_objects</emphasis> field in the
+<function>CompositeClassExtension</function>
+structure to
+<function>True</function>.
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+will otherwise generate an error message on an attempt to create a
+nonwidget child.
+</para>
+
+<para>
+Of the classes defined by the Intrinsics,
+ApplicationShell
+and
+SessionShell
+accept nonwidget children, and the class of any nonwidget child
+must not be
+<function>rectObjClass</function>
+or any subclass.  The intent of allowing
+Object
+children of
+ApplicationShell
+and
+SessionShell
+is to provide clients a simple mechanism
+for establishing the resource-naming root of an object hierarchy.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Rectangle_Objects">
+<title>Rectangle Objects</title>
+<para>
+The class of rectangle objects is a subclass of
+Object
+that represents
+rectangular areas.  It encapsulates the mechanisms for geometry
+management and is called RectObj
+to avoid conflict with the Xlib
+<function>Rectangle</function>
+data type.
+</para>
+<sect2 id="RectObjClassPart_Structure">
+<title>RectObjClassPart Structure</title>
+<para>
+As with the
+<function>ObjectClassPart</function>
+structure, all fields in the
+<function>RectObjClassPart</function>
+structure have the same
+purpose and function as the corresponding fields in
+<function>CoreClassPart</function>;
+fields whose names are rect<emphasis remap='I'>n</emphasis> for some integer
+<emphasis remap='I'>n</emphasis> are not used for
+RectObj, but exist to pad the data structure so that it matches
+Core's
+class record.  The class record initialization must fill all
+rect<emphasis remap='I'>n</emphasis> fields with NULL or zero as appropriate to the type.
+</para>
+<literallayout >
+typedef struct _RectObjClassPart {
+	WidgetClass superclass;
+	String class_name;
+	Cardinal widget_size;
+	XtProc class_initialize;
+	XtWidgetClassProc class_part_initialize;
+	XtEnum class_inited;
+	XtInitProc initialize;
+	XtArgsProc initialize_hook;
+	XtProc rect1;
+	XtPointer rect2;
+	Cardinal rect3;
+	XtResourceList resources;
+	Cardinal num_resources;
+	XrmClass xrm_class;
+	Boolean rect4;
+	XtEnum rect5;
+	Boolean rect6;
+	Boolean rect7;
+	XtWidgetProc destroy;
+	XtWidgetProc resize;
+	XtExposeProc expose;
+	XtSetValuesFunc set_values;
+	XtArgsFunc set_values_hook;
+	XtAlmostProc set_values_almost;
+	XtArgsProc get_values_hook;
+	XtProc rect9;
+	XtVersionType version;
+	XtPointer callback_private;
+	String rect10;
+	XtGeometryHandler query_geometry;
+	XtProc rect11;
+	XtPointer extension ;
+} RectObjClassPart;
+</literallayout>
+<para>
+The
+RectObj
+class record consists of just the
+<function>RectObjClassPart</function>.
+</para>
+<literallayout >
+typedef struct _RectObjClassRec {
+	RectObjClassPart rect_class;
+} RectObjClassRec, *RectObjClass;
+</literallayout>
+<para>
+The predefined class record and pointer for
+<function>RectObjClassRec</function>
+are
+</para>
+
+<para>
+In
+<function>Intrinsic.h</function>:
+</para>
+<literallayout >
+extern RectObjClassRec rectObjClassRec;
+</literallayout>
+<para>
+In
+<function>Intrinsic.h</function>:
+</para>
+<literallayout >
+extern WidgetClass rectObjClass;
+</literallayout>
+<para>
+The opaque types
+<function>RectObj</function>
+and
+<function>RectObjClass</function>
+and the opaque variable
+<function>rectObjClass</function>
+are defined for generic actions on objects
+whose class is RectObj or a subclass of
+RectObj.
+<function>Intrinsic.h</function>
+uses an incomplete structure definition to ensure that the compiler
+catches attempts to access private data:
+</para>
+<literallayout >
+typedef struct _RectObjClassRec* RectObjClass;
+</literallayout>
+
+</sect2>
+
+<sect2 id="RectObjPart_Structure">
+<title>RectObjPart Structure</title>
+<para>
+In addition to the
+<function>ObjectPart</function>
+fields,
+RectObj
+objects have the following fields defined in the
+<function>RectObjPart</function>
+structure.  All fields have the same meaning as the corresponding field in
+<function>CorePart</function>.
+</para>
+<literallayout >
+typedef struct _RectObjPart {
+	Position x, y;
+	Dimension width, height;
+	Dimension border_width;
+	Boolean managed;
+	Boolean sensitive;
+	Boolean ancestor_sensitive;
+} RectObjPart;
+</literallayout>
+<para>
+RectObj
+objects have the RectObj fields immediately following the Object fields.
+</para>
+<literallayout >
+typedef struct _RectObjRec {
+	ObjectPart object;
+	RectObjPart rectangle;
+} RectObjRec, *RectObj;
+</literallayout>
+<para>
+In
+<function>Intrinsic.h</function>:
+</para>
+<literallayout >
+typedef struct _RectObjRec* RectObj;
+</literallayout>
+
+</sect2>
+
+<sect2 id="RectObj_Resources">
+<title>RectObj Resources</title>
+<para>
+The resource names, classes, and representation types that are specified in the
+<function>rectObjClassRec</function>
+resource list are:
+<informaltable frame='topbot'>
+  <?dbfo keep-together="always" ?>
+  <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+  <colspec colwidth='1.0*' colname='c1'/>
+  <colspec colwidth='1.0*' colname='c2'/>
+  <colspec colwidth='1.0*' colname='c3'/>
+  <thead>
+    <row rowsep='1'>
+      <entry>Name</entry>
+      <entry>Class</entry>
+      <entry>Representation</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry>XtNancestorSensitive</entry>
+      <entry>XtCSensitive</entry>
+      <entry>XtRBoolean</entry>
+    </row>
+    <row>
+      <entry>XtNborderWidth</entry>
+      <entry>XtCBorderWidth</entry>
+      <entry>XtRDimension</entry>
+    </row>
+    <row>
+      <entry>XtNheight</entry>
+      <entry>XtCHeight</entry>
+      <entry>XtRDimension</entry>
+    </row>
+    <row>
+      <entry>XtNsensitive</entry>
+      <entry>XtCSensitive</entry>
+      <entry>XtRBoolean</entry>
+    </row>
+    <row>
+      <entry>XtNwidth</entry>
+      <entry>XtCWidth</entry>
+      <entry>XtRDimension</entry>
+    </row>
+    <row>
+      <entry>XtNx</entry>
+      <entry>XtCPosition</entry>
+      <entry>XtRPosition</entry>
+    </row>
+    <row>
+      <entry>XtNy</entry>
+      <entry>XtCPosition</entry>
+      <entry>XtRPosition</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+</para>
+</sect2>
+
+<sect2 id="RectObjPart_Default_Values">
+<title>RectObjPart Default Values</title>
+<para>
+All fields in
+<function>RectObjPart</function>
+have the same default values as the corresponding fields in
+<function>CorePart</function>.
+</para>
+</sect2>
+
+<sect2 id="Widget_Arguments_to_xI_Routines">
+<title>Widget Arguments to Intrinsics Routines</title>
+<para>
+The WidgetClass arguments to the following procedures may be
+<function>rectObjClass</function>
+or any subclass:
+</para>
+<itemizedlist spacing='compact'>
+  <listitem>
+    <para>
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreateManagedWidget' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+The Widget arguments to the following procedures may be of class
+RectObj
+or any subclass:
+</para>
+<itemizedlist spacing='compact'>
+  <listitem>
+    <para>
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>,
+<xref linkend='XtMoveWidget' xrefstyle='select: title'/>,
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>,
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtManageChildren' xrefstyle='select: title'/>,
+<xref linkend='XtManageChild' xrefstyle='select: title'/>,
+<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>,
+<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>,
+<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtQueryGeometry' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtSetSensitive' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtTranslateCoords' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+The return value of the following procedures will be of class
+RectObj
+or a subclass:
+</para>
+<itemizedlist spacing='compact'>
+  <listitem>
+    <para>
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreateManagedWidget' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+</itemizedlist>
+</sect2>
+
+<sect2 id="Use_of_Rectangle_Objects">
+<title>Use of Rectangle Objects</title>
+<para>
+RectObj
+can be subclassed to provide widgetlike objects (sometimes
+called gadgets) that do not use windows and do not have those
+features that are seldom used in simple widgets.  This can save memory
+resources both in the server and in applications
+but requires additional support code in the parent.
+In the following
+discussion, <emphasis remap='I'>rectobj</emphasis> refers only to objects
+whose class is RectObj or a subclass of
+RectObj,
+but not Core or a subclass of
+Core.
+</para>
+
+<para>
+Composite
+widget classes that wish to accept rectobj children must set
+the <emphasis remap='I'>accepts_objects</emphasis> field in the
+<function>CompositeClassExtension</function>
+extension structure to
+<function>True</function>.
+<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
+or
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>
+will otherwise generate an error if called to create a nonwidget child.
+If the composite widget supports only children of class
+RectObj
+or a subclass (i.e., not of the general Object class), it
+must declare an insert_child procedure and check the subclass of each
+new child in that procedure.  None of the classes defined by the
+Intrinsics accept rectobj children.
+</para>
+
+<para>
+If gadgets are defined in an object set, the parent is responsible for
+much more than the parent of a widget.  The parent must request and handle
+input events that occur for the gadget and is responsible for making
+sure that when it receives an exposure event the gadget children get
+drawn correctly.
+Rectobj children may
+have expose procedures
+specified in their class records, but the parent is free to
+ignore them, instead drawing the contents of the child itself.  This
+can potentially save graphics context switching.  The precise contents
+of the exposure event and region arguments to the RectObj expose
+procedure are not specified by the Intrinsics; a particular rectangle object is
+free to define the coordinate system origin (self-relative or
+parent-relative) and whether or not the rectangle or region is assumed to
+have been intersected with the visible region of the object.
+</para>
+
+<para>
+In general, it is expected that a composite widget that accepts
+nonwidget children will document those children it is able to handle,
+since a gadget cannot be viewed as a completely self-contained entity,
+as can a widget.  Since a particular composite widget class is usually
+designed to handle nonwidget children of only a limited set of classes, it should
+check the classes of newly added children in its insert_child
+procedure to make sure that it can deal with them.
+</para>
+
+<para>
+The Intrinsics will clear areas of a parent window obscured by
+rectobj children, causing exposure events, under the following
+circumstances:
+</para>
+<itemizedlist spacing='compact'>
+  <listitem>
+    <para>
+A rectobj child is managed or unmanaged.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+In a call to
+<xref linkend='XtSetValues' xrefstyle='select: title'/>
+on a rectobj child, one or more of the set_values procedures returns
+<function>True</function>.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+In a call to
+<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>
+on a rectobj child, areas will
+be cleared corresponding to both the old and the new child
+geometries, including the border, if the geometry changes.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+In a call to
+<xref linkend='XtMoveWidget' xrefstyle='select: title'/>
+on a rectobj child, areas will be
+cleared corresponding to both the old and the new child
+geometries, including the border, if the geometry changes.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+In a call to
+<xref linkend='XtResizeWidget' xrefstyle='select: title'/>
+on a rectobj child, a single
+rectangle will be cleared corresponding to the larger of the
+old and the new child geometries if they are different.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+In a call to
+<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
+(or
+<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>)
+on a rectobj child with
+<function>XtQueryOnly</function>
+not set, if the manager returns
+<function>XtGeometryYes</function>,
+two rectangles will be cleared corresponding to both the old and
+the new child geometries.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+Stacking order is not supported for rectobj children.  Composite widgets with
+rectobj children are free to define any semantics desired if the child
+geometries overlap, including making this an error.
+</para>
+
+<para>
+When a rectobj is playing the role of a widget, developers must be
+reminded to avoid making assumptions about the object passed in the
+Widget argument to a callback procedure.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Undeclared_Class">
+<title>Undeclared Class</title>
+<para>
+The Intrinsics define an unnamed class between
+RectObj
+and
+Core
+for possible future use by the X Consortium. The only assumptions that
+may be made about the unnamed class are
+</para>
+<itemizedlist spacing='compact'>
+  <listitem>
+    <para>
+The <emphasis remap='I'>core_class.superclass</emphasis> field of
+<function>coreWidgetClassRec</function>
+contains a pointer to the unnamed class record.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A pointer to the unnamed class record when dereferenced as an
+<function>ObjectClass</function>
+will contain a pointer to
+<function>rectObjClassRec</function>
+in its <emphasis remap='I'>object_class.superclass</emphasis> field.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+Except for the above, the contents of the class record for this class
+and the result of an attempt to subclass or to create a widget of this
+unnamed class are undefined.
+</para>
+</sect1>
+
+<sect1 id="Widget_Arguments_to_Intrinsics_Routines">
+<title>Widget Arguments to Intrinsics Routines</title>
+<para>
+The WidgetClass arguments to the following procedures must be of class
+Shell
+or a subclass:
+</para>
+<itemizedlist spacing='compact'>
+  <listitem>
+    <para>
+<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreatePopupShell' xrefstyle='select: title'/>,
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>,
+<xref linkend='XtVaAppCreateShell' xrefstyle='select: title'/>,
+<xref linkend='XtOpenApplication' xrefstyle='select: title'/>,
+<xref linkend='XtVaOpenApplication' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+The Widget arguments to the following procedures must be of class
+Core
+or any subclass:
+</para>
+<itemizedlist spacing='compact'>
+  <listitem>
+    <para>
+<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreatePopupShell' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>,
+<xref linkend='XtAddRawEventHandler' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveEventHandler' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveRawEventHandler' xrefstyle='select: title'/>,
+<xref linkend='XtInsertEventHandler' xrefstyle='select: title'/>,
+<xref linkend='XtInsertRawEventHandler' xrefstyle='select: title'/>
+<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveEventTypeHandler' xrefstyle='select: title'/>,
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtRegisterDrawable' xrefstyle='select: title'/>
+<xref linkend='XtDispatchEventToWidget' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtAddGrab' xrefstyle='select: title'/>,
+<xref linkend='XtRemoveGrab' xrefstyle='select: title'/>,
+<xref linkend='XtGrabKey' xrefstyle='select: title'/>,
+<xref linkend='XtGrabKeyboard' xrefstyle='select: title'/>,
+<xref linkend='XtUngrabKey' xrefstyle='select: title'/>,
+<xref linkend='XtUngrabKeyboard' xrefstyle='select: title'/>,
+<xref linkend='XtGrabButton' xrefstyle='select: title'/>,
+<xref linkend='XtGrabPointer' xrefstyle='select: title'/>,
+<xref linkend='XtUngrabButton' xrefstyle='select: title'/>,
+<xref linkend='XtUngrabPointer' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtBuildEventMask' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtCreateWindow' xrefstyle='select: title'/>,
+<function>XtDisplay</function>,
+<xref linkend='XtScreen' xrefstyle='select: title'/>,
+<xref linkend='XtWindow' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtNameToWidget' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>,
+<xref linkend='XtOwnSelection' xrefstyle='select: title'/>,
+<xref linkend='XtDisownSelection' xrefstyle='select: title'/>,
+<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>,
+<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtInstallAccelerators' xrefstyle='select: title'/>,
+<xref linkend='XtInstallAllAccelerators' xrefstyle='select: title'/>
+(both destination and source)
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>,
+<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>,
+<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/>,
+<xref linkend='XtCallActionProc' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtMapWidget' xrefstyle='select: title'/>,
+<xref linkend='XtUnmapWidget' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>,
+<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtCallAcceptFocus' xrefstyle='select: title'/>,
+<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>
+(subtree)
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtResizeWindow' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+The Widget arguments to the following procedures must be of class
+Composite
+or any subclass:
+</para>
+<itemizedlist spacing='compact'>
+  <listitem>
+    <para>
+<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreateManagedWidget' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+The Widget arguments to the following procedures must be of a subclass of
+Shell:
+</para>
+<itemizedlist spacing='compact'>
+  <listitem>
+    <para>
+<xref linkend='XtPopdown' xrefstyle='select: title'/>,
+<xref linkend='XtCallbackPopdown' xrefstyle='select: title'/>,
+<xref linkend='XtPopup' xrefstyle='select: title'/>,
+<xref linkend='XtCallbackNone' xrefstyle='select: title'/>,
+<xref linkend='XtCallbackNonexclusive' xrefstyle='select: title'/>,
+<xref linkend='XtCallbackExclusive' xrefstyle='select: title'/>,
+<xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+The return value of the following procedure will be of class
+Core
+or a subclass:
+</para>
+<itemizedlist spacing='compact'>
+  <listitem>
+    <para>
+<xref linkend='XtWindowToWidget' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+The return value of the following procedures will be of a subclass of
+Shell:
+</para>
+<itemizedlist spacing='compact'>
+  <listitem>
+    <para>
+<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>,
+<xref linkend='XtVaAppCreateShell' xrefstyle='select: title'/>,
+<xref linkend='XtAppInitialize' xrefstyle='select: title'/>,
+<xref linkend='XtVaAppInitialize' xrefstyle='select: title'/>,
+<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>,
+<xref linkend='XtVaCreatePopupShell' xrefstyle='select: title'/>
+    </para>
+  </listitem>
+</itemizedlist>
+</sect1>
+</chapter>