\&
.sp 1
.ce 3
\s+1\fBChapter 12\fP\s-1

\s+1\fBNon-widget Objects\fP\s-1
.sp 2
.nr H1 12
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.LP
.XS
Chapter 12 \- Non-widget Objects
.XE
.LP
Although widget writers are free to treat
.PN Core
as the base class of
the widget hierarchy, there are actually three classes above it.
These classes are
.PN Object ,
.PN RectObj
(Rectangle Object) and (unnamed)
and are referred to generically as ``objects''.  By convention, the term
``widget'' refers only to objects that are a subclass of
.PN Core
and the term ``non-widget'' refers to objects that are not a subclass of
.PN Core .

.NH 2
Data Structures
.XS
\*(SN Data Structures
.XE
.LP
In order not to conflict with previous widget code, the data
structures used by non-widget 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 ``holes'' in them for the widget fields that they do not use.  This
allows the static class initializers for existing widgets to remain
unchanged.

.NH 2
Object Objects
.XS
\fB\*(SN Object Objects\fP
.XE
.LP
.IN "Object" "" "@DEF@"
The
.PN Object
object contains the definitions of fields common to all
objects.  It encapsulates the mechanisms for resource management.
All objects and widgets are subclasses of
.PN Object ,
which is defined by the
.PN ObjectClassPart
and
.PN ObjectPart
structures.

.NH 3
ObjectClassPart Structure
.XS
\*(SN ObjectClassPart Structure
.XE

.LP
The common fields for all object classes are defined in the
.PN ObjectClassPart
structure.  All fields have the same purpose and
function as the corresponding fields in
.PN CoreClassPart ;
fields whose
names are obj\fI\s+1n\s-1\fP for some integer \s+1\fIn\fP\s-1 are not
used for Objects,
but exist to pad the data structure so that it matches Core's class
record.  The class record initialization must fill all
obj\fI\s+1n\s-1\fP fields with NULL or zero as appropriate to the type.

.IN "ObjectClassPart" "" "@DEF@"
.Ds 0
.TA .5i 3i
.ta .5i 3i
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;
.De
.LP
The prototypical
.PN ObjectClass
consists of just the
.PN ObjectClassPart .

.IN "ObjectClassRec" "" "@DEF@"
.IN "ObjectClass" "" "@DEF@"
.IN "objectClass" "" "@DEF@"
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct _ObjectClassRec {
	ObjectClassPart object_class;
} ObjectClassRec, *ObjectClass;
.De

The predefined class record and pointer for
.PN ObjectClassRec
are:

.LP
.Ds 0
extern ObjectClassRec objectClassRec;
extern WidgetClass objectClass;
.De
.LP
The opaque types
.PN Object
and
.PN ObjectClass
and the opaque variable
.PN objectClass
are defined for generic actions on objects.

.NH 3
ObjectPart Structure
.XS
\*(SN ObjectPart Structure
.XE

.LP
The common fields for all object instances are defined in the
.PN ObjectPart
structure.  All fields have the same meaning as the
corresponding fields in
.PN CorePart .

.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
.IN "ObjectPart" "" "@DEF@"
typedef struct _ObjectPart {
	Widget self;
	WidgetClass widget_class;
	Widget parent;
	XrmName xrm_name;
	Boolean being_destroyed;
	XtCallbackList destroy_callbacks;
	XtPointer constraints;
} ObjectPart;
.De
.LP
All object instances have the
.PN Object
fields as their first component.  The prototypical type
.PN Object
is defined with only this set of fields.
Various routines can cast object pointers, as needed, to specific
object types.

.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct _ObjectRec {
	ObjectPart object;
} ObjectRec, *Object;
.De
.IN "ObjectRec" "" "@DEF@"

.NH 3
Object Resources
.XS
\fB\*(SN Object Resources\fP
.XE
.LP
The resource names, classes and representation types specified in the
.PN Object
resource list are:
.LP
.TS
lw(1.5i) lw(1.5i) lw(2.5i) .
_
.sp 6p
Name	Class	Representation
.sp 6p
_
.sp 6p
XtNdestroyCallback	XtCCallback	XtRCallback
.sp 6p
_
.TE

.NH 3
ObjectPart Default Values
.XS
\fB\*(SN ObjectPart Default Values\fP
.XE
.LP
All fields in
.PN ObjectPart
have the same default values as the corresponding fields in
.PN CorePart .

.NH 3
Object Arguments To \*(xI Routines
.XS
\*(SN Object Arguments To \*(xI Routines
.XE
.LP
The WidgetClass arguments to the following procedures may be
.PN objectClass
or any subclass:
.sp
.IP
.PN XtInitializeWidgetClass ,
.PN XtCreateWidget ,
.PN XtVaCreateWidget
.IP
.PN XtIsSubclass ,
.PN XtCheckSubclass
.IP
.PN XtGetResourceList ,
.PN XtGetConstraintResourceList
.sp
.LP
The Widget arguments to the following procedures may be of class
.PN Object
or any subclass:
.sp
.IP
.PN XtCreateWidget ,
.PN XtVaCreateWidget
.IP
.PN XtAddCallback ,
.PN XtAddCallbacks ,
.PN XtRemoveCallback ,
.PN XtRemoveCallbacks ,
.PN XtRemoveAllCallbacks ,
.PN XtCallCallbacks ,
.PN XtHasCallbacks ,
.PN XtCallCallbackList
.IP
.PN XtClass ,
.PN XtSuperclass ,
.PN XtIsSubclass ,
.PN XtCheckSubclass ,
.PN XtIsObject ,
.PN XtIsRectObj ,
.PN XtIsWidget ,
.PN XtIsComposite ,
.PN XtIsConstraint ,
.PN XtIsShell ,
.PN XtIsOverrideShell ,
.PN XtIsWMShell ,
.PN XtIsVendorShell ,
.PN XtIsTransientShell ,
.PN XtIsToplevelShell ,
.PN XtIsApplicationShell .
.IP
.PN XtIsManaged ,
.PN XtIsSensitive
.br
(both will return
.PN False
if argument is not a subclass of
.PN RectObj )
.IP
.PN XtIsRealized
.br
(returns the state of the nearest windowed ancestor
if argument is not of a subclass of
.PN Core )
.IP
.PN XtWidgetToApplicationContext
.IP    
.PN XtDestroyWidget
.IP
.PN XtDisplayOfObject ,
.PN XtScreenOfObject ,
.PN XtWindowOfObject
.IP
.PN XtSetKeyboardFocus
(descendant)
.IP
.PN XtGetGC ,
.PN XtReleaseGC
.IP
.PN XtNameToWidget ,
.PN XtName
.IP
.PN XtSetValues ,
.PN XtGetValues ,
.PN XtVaSetValues ,
.PN XtVaGetValues ,
.PN XtGetSubvalues ,
.PN XtVaGetSubvalues
.IP
.PN XtGetSubresources ,
.PN XtGetApplicationResources ,
.PN XtVaGetSubresources ,
.PN XtVaGetApplicationResources
.IP
.PN XtConvert ,
.PN XtConvertAndStore
.sp
.LP
The return value of the following procedures will be of class
.PN Object
or a subclass:
.sp
.IP
.PN XtCreateWidget ,
.PN XtVaCreateWidget
.IP
.PN XtParent
.IP
.PN XtNameToWidget
.sp
.LP
The return value of the following procedures will be
.PN objectClass
or a subclass:
.sp
.IP
.PN XtClass ,
.PN XtSuperclass

.NH 3
Use of Objects
.XS
\fB\*(SN Use of Objects\fP
.XE
.LP
The
.PN Object
class exists to enable programmers to use the \*(xI'
classing and resource handling mechanisms for things besides widgets.
Objects obsolete many common uses of subresources as described in
sections 9.4, 9.7.2.4 and 9.7.2.5.
.LP
.PN Composite
widget classes that wish to accept non-widget children must
set the accepts_objects field in the
.PN CompositeClassExtension
structure to
.PN True .
.PN XtCreateWidget
will otherwise generate an error message on an attempt to create a
non-widget child.
.LP
Of the classes defined by the \*(xI, only
.PN ApplicationShell
accepts non-widget children, and the class of any non-widget child
must not be
.PN rectObjClass
or any subclass.  The intent of allowing
.PN Object
children of
.PN ApplicationShell
is to provide clients a simple mechanism
for establishing the resource naming root of an object hierarchy.

.NH 2
Rectangle Objects
.XS
\*(SN Rectangle Objects
.XE
.LP
Rectangle objects are a subclass of
.PN Object
that represent
rectangular areas.  They encapsulate the mechanisms for geometry
management, and are called RectObjs
.IN "RectObj" "" "@DEF@"
to avoid conflict with the Xlib
.PN Rectangle
data type.

.NH 3
RectObjClassPart Structure
.XS
\*(SN RectObjClassPart Structure
.XE
.LP
As with the
.PN ObjectClassPart
structure, all fields have the same
purpose and function as the corresponding fields in
.PN CoreClassPart ;
fields whose names are rect\fI\s+1n\s-1\fP for some integer
\fI\s+1n\s-1\fP are not used for
RectObjs but exist to pad the data structure so that it matches
.PN Core 's
class record.  The class record initialization must fill all
rect\fI\s+1n\s-1\fP fields with NULL or zero as appropriate to the type.
.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
.IN "RectObjClassPart" "" "@DEF@"
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;
.De
.LP
The
.PN RectObj
class record consists of just the
.PN RectObjClassPart :
.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
.IN "RectObjClassRec" "" "@DEF@"
.IN "RectObjClass" "" "@DEF@"
typedef struct _RectObjClassRec {
	RectObjClassPart rect_class;
} RectObjClassRec, *RectObjClass;
.De
.LP
The predefined class record and pointer for
.PN RectObjClassRec
are:
.LP
.Ds 0
extern RectObjClassRec rectObjClassRec;
extern WidgetClass rectObjClass;
.De
.LP
The opaque types
.PN RectObj
and
.PN RectObjClass
and the opaque variable
.PN rectObjClass
are defined for generic actions on objects that are a subclass of
.PN RectObj .

.NH 3
RectObjPart Structure
.XS
\*(SN RectObjPart Structure
.XE
.LP
In addition to the
.PN ObjectPart
fields,
.PN RectObj
objects have the following fields defined in the
.PN RectObjPart
structure.  All fields have the same meaning as the corresponding field in
.PN CorePart .
.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
.IN "RectObjPart" "" "@DEF@"
typedef struct _RectObjPart {
	Position x, y;
	Dimension width, height;
	Dimension border_width;
	Boolean managed;
	Boolean sensitive;
	Boolean ancestor_sensitive;
} RectObjPart;
.De
.LP
.PN RectObj
objects have the rectangle fields immediately following the object fields:
.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
.IN "RectObjRec" "" "@DEF@"
typedef struct _RectObjRec {
	ObjectPart object;
	RectObjPart rectangle;
} RectObjRec;
.De

.NH 3
RectObj Resources
.XS
\fB\*(SN RectObj Resources\fP
.XE
.LP
The resource names, classes and representation types specified in the
.PN RectObj
resource list are:
.TS
lw(1.5i) lw(1.5i) lw(2.5i) .
_
.sp 6p
Name	Class	Representation
.sp 6p
_
.sp 6p
XtNancestorSensitive	XtCSensitive	XtRBoolean
XtNborderWidth	XtCBorderWidth	XtRDimension
XtNheight	XtCHeight	XtRDimension
XtNsensitive	XtCSensitive	XtRBoolean
XtNwidth	XtCWidth	XtRDimension
XtNx	XtCPosition	XtRPosition
XtNy	XtCPosition	XtRPosition
.sp 6p
_
.TE

.NH 3
RectObjPart Default Values
.XS
\fB\*(SN RectObjPart Default Values\fP
.XE
.LP
All fields in
.PN RectObjPart
have the same default values as the corresponding fields in
.PN CorePart .

.NH 3
RectObj Arguments To \*(xI Routines
.XS
\*(SN RectObj Arguments To \*(xI Routines
.XE
.LP
The WidgetClass arguments to the following procedures may be
.PN rectObjClass
or any subclass:
.sp
.IP
.PN XtCreateManagedWidget ,
.PN XtVaCreateManagedWidget
.sp
.LP
The Widget arguments to the following procedures may be of class
.PN RectObj
or any subclass:
.sp
.IP
.PN XtConfigureWidget ,
.PN XtMoveWidget ,
.PN XtResizeWidget
.IP
.PN XtMakeGeometryRequest ,
.PN XtMakeResizeRequest
.IP
.PN XtManageChildren ,
.PN XtManageChild ,
.PN XtUnmanageChildren ,
.PN XtUnmanageChild
.IP
.PN XtQueryGeometry
.IP
.PN XtSetSensitive
.IP
.PN XtTranslateCoords
.sp
.LP
The return value of the following procedures will be of class
.PN RectObj
or a subclass:
.sp
.IP
.PN XtCreateManagedWidget ,
.PN XtVaCreateManagedWidget

.NH 3
Use of RectObjs
.XS
\*(SN Use of RectObjs
.XE
.LP
.PN RectObj
can be subclassed to provide widget-like objects (sometimes
called ``gadgets'') that do not use windows and which do not have
features often unused in simple widgets.  This can save memory
resources both in the server and in applications.  In the following
discussion, ``RectObj'' refers only to objects which are a subclass of
.PN RectObj
and are not a subclass of
.PN Core . 
.LP
.PN Composite
widget classes that wish to accept RectObj children must set
the accepts_objects field in the
.PN CompositeClassExtension
extension structure to
.PN True .
.PN XtCreateWidget
or
.PN XtCreateManagedWidget
will otherwise generate an error if called to create a non-widget child.
If the Composite widget supports only children of class
.PN RectObj
or a subclass (i.e. not general Objects), 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
\*(xI accept RectObj children.
.LP
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 expose event the gadget children get
drawn correctly. Subclasses of
.PN RectObj
have expose procedures 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 Expose event and Region arguments to the RectObj expose
procedure are not specified by the \*(xI; a particular rectangle object is
free to define the coordinate system origin (self-relative or parent-
relative) and whether or not the rectangle and/or Region is assumed to
have been intersected with the visible region of the object.
.LP
In general, it is expected that a composite widget which accepts
non-widget children will document those children it is able to handle,
since a gadget can not be viewed as a completely self-contained entity
as can a widget.  Since a particular composite widget class is usually
designed to handle gadgets 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.
.LP
The \*(xI will clear areas of a parent window obscured by
RectObj children, causing Expose events, under the following
circumstances:
.IP \(bu 5
A RectObj child is managed or unmanaged.
.IP \(bu 5
In a call to
.PN XtSetValues
on a RectObj child, one or more of the set_values procedures returns
.PN True .
.IP \(bu 5
In a call to
.PN XtConfigureWidget
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.
.IP \(bu 5
In a call to
.PN XtMoveWidget
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.
.IP \(bu 5
In a call to
.PN XtResizeWidget
on a RectObj child, an single
rectangle will be cleared corresponding to the larger of the
old and the new child geometries if they are different.
.IP \(bu 5
In a call to
.PN XtMakeGeometryRequest
(or
.PN XtMakeResizeRequest )
on a RectObj, if the manager returns
.PN XtGeometryYes
two rectangles will be cleared corresponding to both the old and
the new child geometries.
.LP
Stacking order is not supported for RectObjs.  Composite widgets with
RectObj children are free to define any semantics desired if the child
geometries overlap, including making this an error.
.LP
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.

.NH 2
Undeclared Class.
.XS
\*(SN Undeclared Class.
.XE
.LP
The \*(xI define an unnamed class between
.PN RectObj
and
.PN Core
for possible future use by the X Consortium. The only assumptions which
may be made about the unnamed class are:
.IP \(bu 5
the core_class.superclass field of the class record of
.PN CoreWidget
contains a pointer to the unnamed class record.
.IP \(bu 5
a pointer to the unnamed class record when de-referenced as an
.PN ObjectClass
will contain a pointer to the class record
of
.PN RectObj
in its object_class.superclass field.
.LP
Except for the above, the content 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.

.NH 2
Widget Arguments To \*(xI Routines
.XS
\*(SN Widget Arguments To \*(xI Routines
.XE
.LP
The WidgetClass arguments to the following procedures must be of class
.PN Shell
or a subclass:
.sp
.IP
.PN XtCreatePopupShell ,
.PN XtVaCreatePopupShell ,
.PN XtAppCreateShell
.sp
.LP
The Widget arguments to the following procedures must be of class
.PN Core
or any subclass:
.sp
.IP
.PN XtCreatePopupShell ,
.PN XtVaCreatePopupShell
.IP
.PN XtAddEventHandler ,
.PN XtAddRawEventHandler ,
.PN XtRemoveEventHandler ,
.br
.PN XtRemoveRawEventHandler ,
.PN XtInsertEventHandler ,
.PN XtInsertRawEventHandler
.IP
.PN XtAddGrab ,
.PN XtRemoveGrab ,
.PN XtGrabKey ,
.PN XtGrabKeyboard ,
.PN XtUngrabKey ,
.PN XtUngrabKeyboard ,
.PN XtGrabButton ,
.PN XtGrabPointer ,
.PN XtUngrabButton ,
.br
.PN XtUngrabPointer
.IP
.PN XtBuildEventMask
.IP
.PN XtCreateWindow ,
.PN XtDisplay ,
.PN XtScreen ,
.PN XtWindow
.IP
.PN XtGetSelectionValue ,
.PN XtGetSelectionValues ,
.PN XtOwnSelection ,
.PN XtDisownSelection ,
.PN XtGetSelectionValueIncremental ,
.PN XtGetSelectionValuesIncremental ,
.br
.PN XtGetSelectionRequest
.IP
.PN XtInstallAccelerators ,
.PN XtInstallAllAccelerators
(both destination and source)
.IP
.PN XtAugmentTranslations ,
.PN XtOverrideTranslations ,
.PN XtUninstallTranslations ,
.br
.PN XtCallActionProc
.IP
.PN XtMapWidget ,
.PN XtUnmapWidget
.IP
.PN XtRealizeWidget ,
.PN XtUnrealizeWidget
.IP
.PN XtSetMappedWhenManaged
.IP
.PN XtCallAcceptFocus ,
.PN XtSetKeyboardFocus
(subtree)
.IP
.PN XtResizeWindow
.IP
.PN XtSetWMColormapWindows
.sp
.LP
The Widget arguments to the following procedures must be of class
.PN Composite
or any subclass:
.sp
.IP
.PN XtCreateManagedWidget ,
.PN XtVaCreateManagedWidget
.sp
.LP
The Widget arguments to the following procedures must be of a subclass of
.PN Shell :
.sp
.IP
.PN XtPopdown ,
.PN XtCallbackPopdown ,
.PN XtPopup ,
.PN XtCallbackNone ,
.PN XtCallbackNonexclusive ,
.PN XtCallbackExclusive ,
.PN XtPopupSpringLoaded
.sp
.LP
The return value of the following procedure will be of class
.PN Core
or a subclass:
.sp
.IP
.PN XtWindowToWidget
.sp
.LP
The return value of the following procedures will be of a subclass of
.PN Shell :
.sp
.IP
.PN XtAppCreateShell ,
.PN XtAppInitialize ,
.PN XtCreatePopupShell ,
.PN XtVaCreatePopupShell
.bp
