1182 lines
35 KiB
XML
1182 lines
35 KiB
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>
|