diff options
Diffstat (limited to 'libXt/specs/CH12.xml')
| -rw-r--r-- | libXt/specs/CH12.xml | 1166 |
1 files changed, 1166 insertions, 0 deletions
diff --git a/libXt/specs/CH12.xml b/libXt/specs/CH12.xml new file mode 100644 index 000000000..3ae6542ab --- /dev/null +++ b/libXt/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> |