xref: /xsrc/external/mit/libXt/dist/specs/CH12.xml

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

<chapter id='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>
<programlisting>
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;
</programlisting>
<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>
<programlisting>
typedef struct {
        XtPointer next_extension;        <lineannotation>See <xref linkend='Class_Extension_Records' /></lineannotation>
        XrmQuark record_type;            <lineannotation>See <xref linkend='Class_Extension_Records' /></lineannotation>
        long version;                    <lineannotation>See <xref linkend='Class_Extension_Records' /></lineannotation>
        Cardinal record_size;            <lineannotation>See <xref linkend='Class_Extension_Records' /></lineannotation>
        XtAllocateProc allocate;         <lineannotation>See <xref linkend='Widget_Instance_Allocation_The_allocate_Procedure' /></lineannotation>
        XtDeallocateProc deallocate;     <lineannotation>See <xref linkend='Widget_Instance_Deallocation_The_deallocate_Procedure' /></lineannotation>
} ObjectClassExtensionRec, *ObjectClassExtension;
</programlisting>
<para>
The prototypical
<function>ObjectClass</function>
consists of just the
<function>ObjectClassPart</function>.
</para>
<programlisting>
typedef struct _ObjectClassRec {
        ObjectClassPart object_class;
} ObjectClassRec, *ObjectClass;
</programlisting>
<para>
The predefined class record and pointer for
<function>ObjectClassRec</function>
are
</para>

<para>
In
<filename class="headerfile">IntrinsicP.h</filename>:
</para>
<programlisting>
extern ObjectClassRec objectClassRec;
</programlisting>
<para>
In
<filename class="headerfile">Intrinsic.h</filename>:
</para>
<programlisting>
extern WidgetClass objectClass;
</programlisting>
<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' />).
<filename class="headerfile">Intrinsic.h</filename>
uses an incomplete structure definition to ensure that the
compiler catches attempts to access private data:
</para>
<programlisting>
typedef struct _ObjectClassRec* ObjectClass;
</programlisting>

</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>
<programlisting>
typedef struct _ObjectPart {
        Widget          self;
        WidgetClass     widget_class;
        Widget          parent;
        Boolean         being_destroyed;
        XtCallbackList  destroy_callbacks;
        XtPointer       constraints;
} ObjectPart;
</programlisting>
<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
<filename class="headerfile">IntrinsicP.h</filename>:
</para>
<programlisting>
typedef struct _ObjectRec {
        ObjectPart object;
} ObjectRec, *Object;
</programlisting>
<para>
In
<filename class="headerfile">Intrinsic.h</filename>:
</para>
<programlisting>
typedef struct _ObjectRec *Object;
</programlisting>

</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>

<itemizedlist spacing='compact'>
<listitem>
<para>
<xref linkend='XtInitializeWidgetClass' xrefstyle='select: title'/>,
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>,
<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>
</para>
</listitem>
<listitem>
<para>
<xref linkend='XtIsSubclass' xrefstyle='select: title'/>,
<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>
</para>
</listitem>
<listitem>
<para>
<xref linkend='XtGetResourceList' xrefstyle='select: title'/>,
<xref linkend='XtGetConstraintResourceList' xrefstyle='select: title'/>
</para>
</listitem>
</itemizedlist>

<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>
<programlisting>
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;
</programlisting>
<para>
The
RectObj
class record consists of just the
<function>RectObjClassPart</function>.
</para>
<programlisting>
typedef struct _RectObjClassRec {
        RectObjClassPart rect_class;
} RectObjClassRec, *RectObjClass;
</programlisting>
<para>
The predefined class record and pointer for
<function>RectObjClassRec</function>
are
</para>

<para>
In
<filename class="headerfile">Intrinsic.h</filename>:
</para>
<programlisting>
extern RectObjClassRec rectObjClassRec;
</programlisting>
<para>
In
<filename class="headerfile">Intrinsic.h</filename>:
</para>
<programlisting>
extern WidgetClass rectObjClass;
</programlisting>
<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.
<filename class="headerfile">Intrinsic.h</filename>
uses an incomplete structure definition to ensure that the compiler
catches attempts to access private data:
</para>
<programlisting>
typedef struct _RectObjClassRec* RectObjClass;
</programlisting>

</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>
<programlisting>
typedef struct _RectObjPart {
        Position        x, y;
        Dimension       width, height;
        Dimension       border_width;
        Boolean         managed;
        Boolean         sensitive;
        Boolean         ancestor_sensitive;
} RectObjPart;
</programlisting>
<para>
RectObj
objects have the RectObj fields immediately following the Object fields.
</para>
<programlisting>
typedef struct _RectObjRec {
        ObjectPart object;
        RectObjPart rectangle;
} RectObjRec, *RectObj;
</programlisting>
<para>
In
<filename class="headerfile">Intrinsic.h</filename>:
</para>
<programlisting>
typedef struct _RectObjRec* RectObj;
</programlisting>

</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>