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

\s+1\fBIntrinsics and Widgets\fP\s-1
.sp 2
.nr H1 1
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.LP
.XS
\fBChapter 1 \- Intrinsics and Widgets\fP
.XE
The \*(xI and a widget set make up the \*(tk.
The \*(xI provide the base mechanisms necessary to build 
a wide variety of widget sets and application environments.
Because the \*(xI mask implementation details from the widget 
and application programmer,
the widgets and the application environments built with them are
fully extensible and support independently developed
new or extended components.
By following a small set of conventions,
widget programmers can extend their widget sets in new ways
and can have these extensions function smoothly with the existing facilities.
.LP
The \*(xI is a library package layered on top of Xlib.
As such,
the \*(xI provide mechanisms (functions and structures) for
extending the basic programming abstractions provided by the X Window System.
By providing mechanisms for intercomponent and intracomponent interactions,
the \*(xI provide the next layer of functionality from which the
widget sets are built.
.LP
Figure 1-1 illustrates this extended three-tiered X programming environment.
.LP
.ps 11
.nr PS 11
.DS 0
.TA .5i 1i 2.25i 2.75i 3i
.ta .5i 1i 2.25i 2.75i 3i
	+-----------------------------------------------+
	|				|
	|	   Application			|
	|				|
	+-----------------------------------------------+
	|		|	|	|
	|	   Widget	|	|	|
	|	   Set	|	|	|
	|		|	|	|
	|----------------------------------	|	|	|
	|	|		|	|
	|	|   Intrinsics		|	|
	|	|		|	|
	|	----------------------------------|		|
	|				|
	|	    Xlib			|
	|				|
	+-----------------------------------------------+
.DE
.LP
A typical \*(tk application is most likely to be a client of 
a given widget set, a subset of the \*(xI functions, 
and a smaller set of Xlib functions.
This is illustrated by a left-to-right viewing of Figure 1-1.
At the same time, 
a widget set is a client of both the \*(xI and Xlib,
and the \*(xI are a client of Xlib only.
This is illustrated by a top-to-bottom viewing of Figure 1-1.
.LP
For the application programmer, the \*(tk provides:
.IP \(bu 5
A consistent interface (widget set) for writing applications
.IP \(bu 5
A small set of \*(xI mechanisms that also are used in writing applications 
.LP
For the widget programmer, the \*(tk provides:
.IP \(bu 5
A set of \*(xI mechanisms for building widgets
.IP \(bu 5
An architectural model for constructing and composing widgets
.IP \(bu 5
A consistent interface (widget set) for programming
.LP
To the extent possible,
the \*(tk is policy free.
The application environment, not the \*(tk, defines, implements, and enforces:
.IP \(bu 5
Policy
.IP \(bu 5
Consistency
.IP \(bu 5
Style
.LP
Each individual widget implementation defines its own policy.
The \*(tk design allows for the development of radically differing
widget implementations.
.NH 2
Terminology
.XS
\fB\*(SN Terminology\fP
.XE
.LP
In addition to the terms already defined for X programming (see \fI\*(xL\fP),
the following terms are specific to the \*(xI and used throughout this book.
.LP
\fBApplication programmer\fP
.IN "Application programmer" "" "@DEF@"
.IP
A programmer who uses the \*(tk to produce an application user interface.
.LP
\fBClass\fP
.IN "Class" "" "@DEF@"
.IP
The general group to which a specific object belongs.
.LP
\fBClient\fP
.IN "Client" "" "@DEF@"
.IP
A function that uses a widget in an application or for composing
other widgets.
.LP
\fBInstance\fP
.IN "Instance" "" "@DEF@"
.IP
A specific widget object as opposed to a general widget class.
.LP
\fBMethod\fP
.IN "Method" "" "@DEF@"
.IP
The functions or procedures that a widget class implements.
.LP
\fBName\fP
.IN "Name" "" "@DEF@"
.IP
The name that is specific to an instance of a widget for a given client.
.LP
\fBObject\fP
.IN "Object" "" "@DEF@"
.IP
A software data abstraction consisting of private data and private and public
functions that operate on the private data.
Users of the abstraction can interact with the object only through calls
to the object's public functions.
In the \*(tk,
some of the object's public functions are called directly by the application,
while others are called indirectly when the application calls the common
\*(xI functions.
In general, if a function is common to all widgets,
an application uses a single Intrinsic function to invoke the function for all
types of widgets.
If a function is unique to a single widget type,
the widget exports the function as another ``Xt'' function.
.LP
\fBResource\fP
.IN "Resource" "" "@DEF@"
.IP
A named piece of data in a widget that can be set by a client,
by an application, or by user defaults.
.LP
\fBUser\fP
.IN "User" "" "@DEF@"
.IP
A person interacting with a workstation.
.LP
\fBWidget\fP
.IN "Widget" "" "@DEF@"
.IP
An object providing a user-interface abstraction (for example, a Scrollbar
widget).
.LP
\fBWidget class\fP
.IN "Widget class" "" "@DEF@"
.IP
The general group to which a specific widget belongs,
otherwise known as the type of the widget.
.LP
\fBWidget programmer\fP
.IN "Widget programmer" "" "@DEF@"
.IP
A programmer who adds new widgets to the \*(tk.
.NH 2
Intrinsics 
.XS
\fB\*(SN Intrinsics\fP
.XE
.LP
The \*(xI provide the base mechanisms (functions and structures)
that simplify the design of application user interfaces.
In addition,
it assists widget and application programmers by providing a commonly used set
of underlying user-interface functions to manage:
.IP \(bu 5
Toolkit initialization
\.IP \(bu 5
Widgets
.IP \(bu 5
Memory
.IP \(bu 5
Window, file, and timer events
.IP \(bu 5
Widget geometry
.IP \(bu 5
Input focus
.IP \(bu 5
Selections
.IP \(bu 5
Resources and resource conversion
.IP \(bu 5
Translation of events
.IP \(bu 5
Graphics contexts
.IP \(bu 5
Pixmaps
.IP \(bu 5
Errors and warnings
.LP
Although all \*(xI mechanisms are primarily intended for use by
widget programmers,
some are also intended for use by application programmers.
The architectural model for the \*(xI lets the widget programmer 
create new widgets by using the supplied mechanisms and/or 
by combining existing widgets.
Therefore, an application interface layers built with the \*(xI will provide
a coordinated set of widgets and composition policies.
While some of the widgets that are built with the \*(xI 
are common across a number of application domains,
others are restricted to a specific application domain.
.LP
The \*(xI are based on an architectural model that also is flexible enough to
accommodate a variety of different application interface layers.
In addition,
the supplied set of \*(xI mechanisms are:
.IP \(bu 5
Functionally complete and policy free
.IP \(bu 5
Stylistically and functionally consistent with the X Window System primitives
.IP \(bu 5
Portable across languages, computer architectures, and operating systems
.LP
Applications that use the \*(xI mechanisms
must include the following header files:
.IP \(bu 5
.Pn < X11/Intrinsic.h >
.IP \(bu 5
.Pn < X11/StringDefs.h >
.LP
In addition, they may also include:
.IP \(bu 5
.Pn < X11/Xatoms.h >
.IP \(bu 5
.Pn < X11/Shell.h >
.LP
Finally, widget implementations should include:
.IP \(bu 5
.Pn < X11/IntrinsicP.h >
instead of
.Pn < X11/Intrinsic.h >.
.LP
The applications should also include the additional headers for
each widget class that they are to use (for example,
.Pn < X11/Xaw/Label.h >
or
.Pn < X11/Xaw/Scrollbar.h >).
On a POSIX-based system, 
the \*(xI object library file is named
.PN libXt.a
and is usually referenced as \-lXt.
.NH 2
Procedures and Macros
.LP
.XS
\fB\*(SN Procedures and Macros\fP
.XE
All functions defined in this document except those specified below
may be implemented as C macros with arguments.  C applications may use
``#undef'' to remove a macro definition and ensure that the actual function
is referenced.  Any such macro will expand to a single expression which
has the same precedence as a function call and which evaluates each
of its arguments exactly once, fully protected by parentheses, so that
arbitrary expressions may be used as arguments.
.LP
The following symbols are macros which do not have function
equivalents and which may expand their arguments in a manner other
than that described above.
.LP
.IP \(bu 5
XtCheckSubclass
.IP \(bu 5
XtNew
.IP \(bu 5
XtNumber
.IP \(bu 5
XtOffsetOf
.IP \(bu 5
XtOffset
.IP \(bu 5
XtSetArg

.NH 2
Widgets
.LP
.XS
\fB\*(SN Widgets\fP
.XE
.LP
The fundamental abstraction and data type of the \*(tk is the \fIwidget\fP,
which is a combination of an X window and its associated
input and display semantics
and which is dynamically allocated and contains state information.
Some widgets display information (for example, text or graphics),
and others are merely containers for other widgets (for example, a menu box).
Some widgets are output-only and do not react to pointer or keyboard input,
and others change their display in response to input
and can invoke functions that an application has attached to them.
.LP
Every widget belongs to exactly one widget class that is statically
allocated and initialized and that contains the operations allowable on
widgets of that class.
Logically, a widget class is the procedures and data that is associated
with all widgets belonging to that class.
These procedures and data can be inherited by
subclasses.
Physically, a widget class is a pointer to a structure.
The contents of this structure are constant for all widgets of the widget
class but will vary from class to class.
(Here, constant means the class structure is initialized at compile-time
and never changed, except for a one-time class initialization
and in-place compilation of resource lists,
which takes place when the first widget of the class or subclass is created.)
For further information,
see Section 2.4.
.LP
The organization of the declarations and code for a new widget class
between a public .h file, a private .h file,
and the implementation .c file is described in Section 1.6.
The predefined widget classes adhere to these conventions.
.LP
A widget instance is composed of two parts:
.IP \(bu 5
A data structure that contains instance-specific values
.IP \(bu 5
A class structure that contains information that is applicable to
all widgets of that class
.LP
Much of the input/output of a widget (for example, fonts, colors, sizes, 
border widths, and so on) is customizable by users.
.LP
The next three sections discuss the base widget classes:
.IP \(bu 5
Core widgets
.IP \(bu 5
Composite widgets
.IP \(bu 5
Constraint widgets
.LP
The chapter ends with a discussion of widget classing.
.NH 3
Core Widgets
.XS
\*(SN Core Widgets
.XE
.LP
.IN "Core" "" "@DEF"
The 
.PN Core 
widget contains the definitions of fields common to all widgets.
All widgets are subclasses of 
.PN Core ,
which is defined by the 
.PN CoreClassPart
and 
.PN CorePart 
structures.
.NH 4
CoreClassPart Structure
.XS
\*(SN CoreClassPart Structure
.XE
.LP
The common fields for all widget classes are defined in the
.PN CoreClassPart
structure:
.LP
.IN "CoreClassPart" "" "@DEF@"
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	WidgetClass superclass;	See Section 1.6
	String class_name;	See Section 1.6
	Cardinal widget_size;	See Section 2.4
	XtProc class_initialize;	See Section 1.6
	XtWidgetClassProc class_part_initialize;	See Section 1.6
	XtEnum class_inited;	See Section 1.6
	XtInitProc initialize;	See Section 2.4
	XtArgsProc initialize_hook;	See Section 2.4
	XtRealizeProc realize;	See Section 2.4
	XtActionList actions;	See Chapter 10
	Cardinal num_actions;	See Chapter 10
	XtResourceList resources;	See Chapter 9
	Cardinal num_resources;	See Chapter 9
	XrmClass xrm_class;	Private to resource manager
	Boolean compress_motion;	See Section 7.9.1
	XtEnum compress_exposure;	See Section 7.9.3
	Boolean compress_enterleave;	See Section 7.9.2
	Boolean visible_interest;	See Section 7.10
	XtWidgetProc destroy;	See Section 2.7
	XtWidgetProc resize;	See Chapter 6
	XtExposeProc expose;	See Section 7.10
	XtSetValuesFunc set_values;	See Section 9.7
	XtArgsFunc set_values_hook;	See Section 9.7
	XtAlmostProc set_values_almost;	See Section 9.7
	XtArgsProc get_values_hook;	See Section 9.7
	XtAcceptFocusProc accept_focus;	See Section 7.3
	XtVersionType version;	See Section 1.6
	XtPointer callback_private;	Private to callbacks
	String tm_table;		See Chapter 10
	XtGeometryHandler query_geometry;	See Chapter 6
	XtStringProc display_accelerator;	See Chapter 10
	XtPointer extension;	See Section 1.6
} CoreClassPart;
.De
.LP
All widget classes have the core class fields as their first component.
The prototypical
.PN WidgetClass
is defined with only this set of fields.
Various routines can cast widget class pointers, as needed,
to specific widget class types, for example:
.LP
.IN "Core" "" "@DEF@"
.IN "WidgetClass" "" "@DEF@"
.IN "CoreWidgetClass" "" "@DEF@"
.Ds
.TA .5i 3i
.ta .5i 3i
typedef struct {
	CoreClassPart core_class;
} WidgetClassRec, *WidgetClass, CoreClassRec, *CoreWidgetClass;
.De
.LP
The predefined class record and pointer for
.PN WidgetClassRec
are:
.LP
.Ds
.TA .5i 3i
.ta .5i 3i
extern WidgetClassRec widgetClassRec;
#define coreClassRec widgetClassRec
.sp 6p
extern WidgetClass widgetClass, coreWidgetClass;
.De
.LP
The opaque types
.PN Widget
and
.PN WidgetClass
and the opaque variable
.PN widgetClass
are defined for generic actions on widgets.
.NH 4
CorePart Structure
.XS
\*(SN CorePart Structure
.XE
.LP
The common fields for all widget instances are defined in the
.PN CorePart
structure:
.LP
.IN "CorePart" "" "@DEF@"
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct _CorePart {
	Widget self;
	WidgetClass widget_class;	See Section 1.6
	Widget parent;	See Section 1.6
	XrmName xrm_name;	Private to resource manager
	Boolean being_destroyed;	See Section 2.7
	XtCallbackList destroy_callbacks;	See Section 2.7
	XtPointer constraints;	See Section 3.6
	Position x;	See Chapter 6
	Position y;	See Chapter 6
	Dimension width;	See Chapter 6
	Dimension height;	See Chapter 6
	Dimension border_width;	See Chapter 6
	Boolean managed;	See Chapter 3
	Boolean sensitive;	See Section 7.7
	Boolean ancestor_sensitive;	See Section 7.7
	XtEventTable event_table;	Private to event manager
	XtTMRec tm;	Private to translation manager
	XtTranslations accelerators;	See Chapter 10
	Pixel border_pixel;	See Section 2.5.1
	Pixmap border_pixmap;	See Section 2.5.1
	WidgetList popup_list;	See Chapter 5
	Cardinal num_popups;	See Chapter 5
	String name;	See Chapter 9
	Screen *screen;	See Section 2.5.1
	Colormap colormap;	See Section 2.5.1
	Window window;	See Section 2.5.1
	Cardinal depth;	See Section 2.5.1
	Pixel background_pixel;	See Section 2.5.1
	Pixmap background_pixmap;	See Section 2.5.1
	Boolean visible;	See Section 7.10
	Boolean mapped_when_managed;	See Chapter 3
} CorePart;
.De
.LP
All widget instances have the core fields as their first component.
The prototypical type
.PN Widget
is defined with only this set of fields.
Various routines can cast widget pointers, as needed,
to specific widget types.
.LP
.IN "Widget" "" "@DEF@"
.IN "CoreWidget" "" "@DEF@"
.sp
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	CorePart core;
} WidgetRec, *Widget, CoreRec, *CoreWidget;
.De

.NH 4
Core Resources
.LP
.XS
\fB\*(SN Core Resources\fP
.XE
.LP
.IN "CoreWidget" "Resources"
The resource names, classes and representation types specified in the
.PN Core
resource list are:
.LP
.TS
lw(1.5i) lw(1.5i) lw(2.5i) .
_
.sp 6p
Name	Class	Representation
.sp 6p
_
.sp 6p
XtNaccelerators	XtCAccelerators	XtRAcceleratorTable
XtNbackground	XtCBackground	XtRPixel
XtNbackgroundPixmap	XtCPixmap	XtRPixmap
XtNborderColor	XtCBorderColor	XtRPixel
XtNborderPixmap	XtCPixmap	XtRPixmap
XtNcolormap	XtCColormap	XtRColormap
XtNdepth	XtCDepth	XtRInt
XtNmappedWhenManaged	XtCMappedWhenManaged	XtRBoolean
XtNscreen	XtCScreen	XtRScreen
XtNtranslations	XtCTranslations	XtRTranslationTable
.sp 6p
_
.TE

.NH 4
CorePart Default Values
.XS
\*(SN CorePart Default Values
.XE
.LP
The default values for the core fields, which are filled in by the 
.PN Core
resource list and the 
.PN Core 
initialize procedure, are:
.LP
.TS
lw(1.5i) lw(4.25i) .
_
.sp 6p
Field	Default Value
.sp 6p
_
.sp 6p
self	Address of the widget structure (may not be changed)
T{
widget_class
T}	T{
widget_class argument to
.PN XtCreateWidget
(may not be changed)
T}
T{
parent
T}	T{
parent argument to
.PN XtCreateWidget
(may not be changed)
T}
T{
xrm_name
T}	T{
Encoded name argument to
.PN XtCreateWidget
(may not be changed)
T}
being_destroyed	Parent's being_destroyed value
destroy_callbacks	NULL
constraints	NULL
x	0
y	0
width	0
height	0
border_width	1
T{
managed
T}	T{
.PN False
T}
T{
sensitive
T}	T{
.PN True
T}
ancestor_sensitive	Bitwise AND of parent's sensitive & ancestor_sensitive
event_table	Initialized by the event manager
tm	Initialized by the translation manager
accelerators	NULL
T{
border_pixel	
T}	T{
.PN XtDefaultForeground
T}
border_pixmap	T{
.PN XtUnspecifiedPixmap
T}
popup_list	NULL
num_popups	0
T{
name
T}	T{
name argument to
.PN XtCreateWidget
(may not be changed)
T}
T{
screen
T}	T{
Parent's screen, top-level widget gets it from display specifier
.br
(may not be changed)
T}
colormap	Copied from parent during creation
window	NULL
depth	Parent's depth, top-level widget gets root window depth
T{
background_pixel
T}	T{
.PN XtDefaultBackground
T}
background_pixmap	T{
.PN XtUnspecifiedPixmap
T}
T{
visible
T}	T{
.PN True
T}
T{
mapped_when_managed
T}	T{
.PN True
T}
.sp 6p
_
.TE
.LP
.IN XtUnspecifiedPixmap "" "@DEF@"
.PN XtUnspecifiedPixmap
is a symbolic constant guaranteed to be unequal to
any valid Pixmap id,
.PN None ,
and
.PN ParentRelative .

.NH 3
Composite Widgets
.XS
\*(SN Composite Widgets
.XE
.LP
.IN "Composite" "" "@DEF@"
.PN Composite 
widgets are a subclass of the 
.PN Core 
widget (see Chapter 3) are intended to be containers for other widgets, 
and are defined by the
.PN CompositeClassPart
and 
.PN CompositePart
structures.
.NH 4
CompositeClassPart Structure
.XS
\*(SN CompositeClassPart Structure
.XE
.LP
In addition to the 
.PN Core 
widget class fields,
.PN Composite 
widgets have the following class fields:
.LP
.IN "CompositeClassPart" "" "@DEF@"
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	XtGeometryHandler geometry_manager;	See Chapter 6
	XtWidgetProc change_managed;	See Chapter 3
	XtWidgetProc insert_child;	See Chapter 3
	XtWidgetProc delete_child;	See Chapter 3
	XtPointer extension;	See Section 1.6
} CompositeClassPart;
.De
.LP
The extension record defined for CompositeClassPart with record_type
equal to
.PN \s-1NULLQUARK\s+1
is
.PN CompositeClassExtensionRec .
.LP
.IN "CompositeClassExtensionRec" "" "@DEF@"
.IN "CompositeClassExtension" "" "@DEF@"
.sp
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	XtPointer next_extension;	See Section 1.6.12
	XrmQuark record_type;	See Section 1.6.12
	long version;	See Section 1.6.12
	Cardinal record_size;	See Section 1.6.12
	Boolean	accepts_objects;	See Chapter 3
} CompositeClassExtensionRec, *CompositeClassExtension;
.De
.LP
.PN Composite 
widget classes have the composite fields immediately following the
core fields:
.LP
.IN "CompositeWidgetClass" "" "@DEF@"
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	CoreClassPart	core_class;
	CompositeClassPart	composite_class;
} CompositeClassRec, *CompositeWidgetClass;
.De
.LP
The predefined class record and pointer for
.PN CompositeClassRec
are:
.LP
.Ds
.TA .5i 3i
.ta .5i 3i
extern CompositeClassRec compositeClassRec;
.sp 6p
extern WidgetClass compositeWidgetClass;
.De
.LP
The opaque types
.PN CompositeWidget
and
.PN CompositeWidgetClass
and the opaque variable
.PN compositeWidgetClass
are defined for generic operations on widgets that are a subclass of
.PN CompositeWidget .
The symbolic constant for the
.PN CompositeClassExtension
version id is
.PN XtCompositeExtensionVersion
(see Section 1.6.12).

.NH 4
CompositePart Structure
.XS
\*(SN CompositePart Structure
.XE
.LP
In addition to the
.PN CorePart
fields,
.PN Composite 
widgets have the following fields defined in the
.PN CompositePart
structure:
.LP
.IN "CompositePart" "" "@DEF@"
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	WidgetList children;	See Section 1.6
	Cardinal num_children;	See Section 1.6
	Cardinal num_slots;	See Chapter 3
	XtOrderProc insert_position;	See Section 2.4
} CompositePart;
.De
.LP
.PN Composite 
widgets have the composite fields immediately following the core fields:
.LP
.IN "CompositeWidget" "" "@DEF@"
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	CorePart core;
	CompositePart composite;
} CompositeRec, *CompositeWidget;
.De
.NH 4
Composite Resources
.XS
\fB\*(SN Composite Resources\fP
.XE
.LP
.IN "CompositeWidget" "Resources"
The resource names, classes and representation types specified in
the
.PN Composite
resource list are:
.LP
.TS
lw(1.5i) lw(1.5i) lw(2.5i) .
_
.sp 6p
Name	Class	Representation
.sp 6p
_
.sp 6p
XtNchildren	XtCReadOnly	XtRWidgetList
XtNinsertPosition	XtCInsertPosition	XtRFunction
XtNnumChildren	XtCReadOnly	XtRCardinal
.sp 6p
_
.TE

.NH 4
CompositePart Default Values
.XS
\*(SN CompositePart Default Values
.XE
.LP
The default values for the composite fields,
which are filled in by the 
.PN Composite 
resource list and the 
.PN Composite 
initialize procedure, are:
.LP
.TS
l l .
_
.sp 6p
Field	Default Value
.sp 6p
_
.sp 6p
children	NULL
num_children	0
num_slots	0
insert_position	Internal function InsertAtEnd
.sp 6p
_
.TE
.LP
The children, num_children, and insert_position fields are declared
as resources;
.PN XtNinsertPosition
is a settable resource,
.PN XtNchildren
and
.PN XtNnumChildren
may be read by any client but should only be modified by the composite
widget itself.

.NH 3
Constraint Widgets
.XS
\*(SN Constraint Widgets
.XE
.LP
.IN "Constraint" "" "@DEF@"
.PN Constraint 
widgets are a subclass of the 
.PN Composite
widget (see Section 3.6) that maintain additional state
data for each child, for example, client-defined constraints on the child's
geometry.
They are defined by the
.PN ConstraintClassPart
and
.PN ConstraintPart
structures.
.NH 4
ConstraintClassPart Structure
.XS
\*(SN ConstraintClassPart Structure
.XE
.LP
In addition to the 
.PN Composite 
class fields,
.PN Constraint 
widgets have the following class fields:
.LP
.IN "ConstraintClassPart" "" "@DEF@"
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	XtResourceList resources;	See Section 3.6
	Cardinal num_resources;	See Section 3.6
	Cardinal constraint_size;	See Section 3.6
	XtInitProc initialize;	See Section 3.6
	XtWidgetProc destroy;	See Section 3.6
	XtSetValuesFunc set_values;	See Section 3.6
	XtPointer extension;	See Section 1.6
} ConstraintClassPart;
.De
.LP
The extension record defined for
.PN ConstraintClassPart
with record_type equal to
.PN \s-1NULLQUARK\s+1
is
.PN ConstraintClassExtensionRec .
.IN "ConstraintClassExtensionRec" "" "@DEF@"
.IN "ConstraintClassExtension" "" "@DEF@"
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	XtPointer next_extension;	See Section 1.6.12
	XrmQuark record_type;	See Section 1.6.12
	long version;	See Section 1.6.12
	Cardinal record_size;	See Section 1.6.12
	XtArgsProc get_values_hook;	See Section 3.6
} ConstraintClassExtensionRec, *ConstraintClassExtension;
.De
.LP
.PN Constraint 
widget classes have the constraint fields immediately following the
composite fields:
.LP
.IN "ConstraintWidgetClass" "" "@DEF@"
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	CoreClassPart	core_class;
	CompositeClassPart	composite_class;
	ConstraintClassPart	constraint_class;
} ConstraintClassRec, *ConstraintWidgetClass;
.De
.LP
The predefined class record and pointer for
.PN ConstraintClassRec
are:
.LP
.Ds
.TA .5i 3i
.ta .5i 3i
extern ConstraintClassRec constraintClassRec;
.sp 6p
extern WidgetClass constraintWidgetClass;
.De
.LP
The opaque types
.PN ConstraintWidget
and
.PN ConstraintWidgetClass
and the opaque variable
.PN constraintWidgetClass
are defined for generic operations on widgets that are a subclass of
.PN ConstraintWidgetClass .
The symbolic constant for the
.PN ConstraintClassExtension
version id is
.PN XtConstraintExtensionVersion
(see Section 1.6.12).

.NH 4
ConstraintPart Structure
.XS
\*(SN ConstraintPart Structure
.XE
.LP
In addition to the
.PN CompositePart
fields,
.PN Constraint 
widgets have the following fields defined in the
.PN ConstraintPart
structure:
.LP
.IN "ConstraintPart" "" "@DEF@"
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct { int empty; } ConstraintPart;
.De
.LP
.PN Constraint 
widgets have the constraint fields immediately following the
composite fields:
.LP
.IN "ConstraintWidget" "" "@DEF@"
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	CorePart core;
	CompositePart composite;
	ConstraintPart constraint;
} ConstraintRec, *ConstraintWidget;
.De

.NH 4
Constraint Resources
.XS
\fB\*(SN Constraint Resources\fP
.XE
.LP
The
.PN Constraint
.PN CoreClassPart
and
.PN ConstraintClassPart
resource lists are empty; no additional resources beyond those declared by
.PN Composite
are defined for
.PN Constraint .

.NH 2
Implementation-specific Datatypes
.XS
\*(SN Implementation-specific Datatypes
.XE
.LP
To increase the portability of widget and application source code
between different system environments, the \*(xI define several
datatypes whose precise representation is explicitly dependent upon,
and chosen by, each individual implementation of the Intrinsics.
.LP
These implementation-defined datatypes are:
.IN "Boolean" "" "@DEF@"
.IP \fBBoolean\fP 11
a datum that contains a zero or non-zero value.
Unless explicitly stated, clients should not assume
that the non-zero value is equal to the symbolic
value
.PN True .
.IN "Cardinal" "" "@DEF@"
.IP \fBCardinal\fP 11
an unsigned datum with a minimum range of [0..2^16-1]
.IN "Dimension" "" "@DEF@"
.IP \fBDimension\fP 11
an unsigned datum with a minimum range of [0..2^16-1]
.IN "Position" "" "@DEF@"
.IP \fBPosition\fP 11
a signed datum with a minimum range of [-2^15..2^15-1]
.IN "XtPointer" "" "@DEF@"
.IP \fBXtPointer\fP 11
a datum large enough to contain the largest of a char*, int*, function
pointer, structure pointer, or long value.  A pointer
to any type or function, or a long, may be converted
to an XtPointer and back again and the result will
compare equal to the original value.  In ANSI C
environments it is expected that XtPointer will be
defined as void*.
.IN "XtArgVal" "" "@DEF@"
.IP \fBXtArgVal\fP 11
a datum large enough to contain an XtPointer, Cardinal,
Dimension, or Position value.
.IN "XtEnum" "" "@DEF@"
.IP \fBXtEnum\fP 11
a datum large enough to encode at least 128 distinct
values, two of which are the symbolic values
.PN True
and
.PN False .
The symbolic values
.PN \s-1TRUE\s+1
and
.PN \s-1FALSE\s+1
are
also defined to be equal to
.PN True
and
.PN False ,
respectively.
.LP
In addition to these specific datatypes, the precise order of the
fields within the structure declarations for any of the instance
part records
.PN ObjectPart ,
.PN RectObjPart ,
.PN CorePart ,
.PN CompositePart ,
.PN ShellPart ,
.PN WMShellPart ,
.PN TopLevelShellPart
and
.PN ApplicationShellPart
is implementation-defined.  The
.PN ObjectPart ,
.PN RectObjPart
and
.PN CorePart
structures must be defined so that any member with the same name
appears at the same offset in
.PN ObjectRec ,
.PN RectObjRec
and
.PN CoreRec
(
.PN WidgetRec ).
No other relationship between the offsets of any two
fields may be assumed.

.NH 2
Widget Classing
.LP
.XS
\fB\*(SN Widget Classing\fP
.XE
.IN "widget_class" "" "@DEF@"
The widget_class field of a widget points to its widget class structure,
which contains information that is constant across all widgets of that class.
As a consequence, 
widget classes usually do not implement directly callable procedures;
rather, they implement procedures that are available through
their widget class structure.
These methods are invoked by generic procedures that envelop common actions 
around the procedures implemented by the widget class.
Such procedures are applicable to all widgets
of that class and also to widgets that are subclasses of that class.
.LP
All widget classes are a subclass of 
.PN Core 
and can be subclassed further.
Subclassing reduces the amount of code and declarations you write to make a
new widget class that is similar to an existing class.
For example, you do not have to describe every resource your widget uses in an
.PN XtResourceList .
Instead, you describe only the resources your widget has
that its superclass does not.
Subclasses usually inherit many of their superclass's procedures
(for example, the expose procedure or geometry handler).
.LP
Subclassing, however, can be taken too far.
If you create a subclass that inherits none of the procedures of its
superclass,
you should consider whether or not you have chosen the most
appropriate superclass.
.LP
To make good use of subclassing, 
widget declarations and naming conventions are highly stylized.
A widget consists of three files:
.IP \(bu 5
A public .h file that is used by client widgets or applications
.IP \(bu 5
A private .h file that is used by widgets that are subclasses of the widget
.IP \(bu 5
A .c file that implements the widget class
.NH 3
Widget Naming Conventions
.XS
\fB\*(SN Widget Naming Conventions\fP
.XE
.LP
The \*(xI provide a vehicle by which programmers can create
new widgets and organize a collection of widgets into an application.
To ensure that applications need not deal with as many styles of capitalization
and spelling as the number of widget classes it uses,
the following guidelines should be followed when writing new widgets:
.IP \(bu 5
Use the X naming conventions that are applicable.
For example, a record component name is all lowercase
and uses underscores (_) for compound words (for example, background_pixmap).
Type and procedure names start with uppercase and use capitalization for
compound words (for example,
.PN ArgList
or
.PN XtSetValues ).
.IP \(bu 5
A resource name is spelled identically to the field name
except that compound names use capitalization rather than underscore.
To let the compiler catch spelling errors,
each resource name should have a symbolic identifier prefixed with
.PN XtN .
For example,
the background_pixmap field has the corresponding identifier
XtNbackgroundPixmap,
which is defined as the string ``backgroundPixmap''.
Many predefined names are listed in 
.Pn < X11/StringDefs.h >.
Before you invent a new name,
you should make sure that your proposed name is not already defined
or that there is not already a name that you can use.
.IP \(bu 5
A resource class string starts with a capital letter 
and uses capitalization for compound names (for example,``BorderWidth'').
Each resource class string should have a symbolic identifier prefixed with
.PN XtC
(for example, XtCBorderWidth).
.IP \(bu 5
A resource representation string is spelled identically to the type name
(for example, ``TranslationTable'').
Each representation string should have a symbolic identifier prefixed with
.PN XtR
(for example, XtRTranslationTable).
.IP \(bu 5
New widget classes start with a capital and use uppercase for compound
words.
Given a new class name AbcXyz you should derive several names:
.RS
.IP \- 5
Partial widget instance structure name AbcXyzPart
.IP \- 5
Complete widget instance structure names AbcXyzRec and _AbcXyzRec
.IP \- 5
Widget instance pointer type name AbcXyzWidget
.IP \- 5
Partial class structure name AbcXyzClassPart
.IP \- 5
Complete class structure names AbcXyzClassRec and _AbcXyzClassRec
.IP \- 5
Class structure variable abcXyzClassRec
.IP \- 5
Class pointer variable abcXyzWidgetClass
.RE
.IP \(bu 5
Action procedures available to translation specifications should follow the
same naming conventions as procedures.
That is,
they start with a capital letter and compound names use uppercase
(for example, ``Highlight'' and ``NotifyClient'').
.LP
The symbolic identifiers \fBXtN\fP..., \fBXtC\fP... and \fBXtR\fP...
may be implemented
as macros, as global symbols, or as a mixture of the two.  The
(implicit) type of the identifier is \fBString\fP.  The pointer value itself
is not significant; clients must not assume that inequality of two
identifiers implies inequality of the resource name, class, or
representation.  Clients are also cautioned that although global
symbols permit savings in literal storage in some environments, they
also introduce the possibility of multiple definition conflicts when
applications attempt to use independently developed widgets
simultaneously.

.NH 3
Widget Subclassing in Public .h Files
.XS
\*(SN Widget Subclassing in Public .h Files
.XE
.LP
The public .h file for a widget class is imported by clients
and contains:
.IP \(bu 5
A reference to the public .h files for the superclass
.IP \(bu 5
The names and classes of the new resources that this widget adds
to its superclass.
The definitions should
have a single space between the definition name and the value and no
trailing space or comment in order to reduce the possibility of
compiler warnings from similar declarations in multiple classes.
.IP \(bu 5
The class record pointer that you use to create widget instances
.IP \(bu 5
The C type that you use to declare widget instances of this class
.IP \(bu 5
Entry points for new class methods
.LP
For example, the following is the public .h file for a possible
implementation of a Label widget:
.LP
.Ds
.TA .5i 1.75i
.ta .5i 1.75i
#ifndef LABEL_H
#define LABEL_H

/* New resources */
#define XtNjustify "justify"
#define XtNforeground "foreground"
#define XtNlabel "label"
#define XtNfont "font"
#define XtNinternalWidth "internalWidth"
#define XtNinternalHeight "internalHeight"

/* Class record pointer */
extern WidgetClass labelWidgetClass;

/* C Widget type definition */
typedef struct _LabelRec      *LabelWidget;

/* New class method entry points */
extern void Label SetText();
	/* Widget w */
	/* String text */

extern String Label GetText();
	/* Widget w */

#endif LABEL_H
.De
.LP
The conditional inclusion of the text allows the application
to include header files for different widgets without being concerned
that they already may be included as a superclass of another widget.
.LP
To accommodate operating systems with file name length restrictions,
the name of the public .h file is the first ten characters of the
widget class.
For example,
the public .h file for the 
.PN Constraint 
widget is 
.PN Constraint.h .
.NH 3
Widget Subclassing in Private .h Files
.XS
\*(SN Widget Subclassing in Private .h Files
.XE
.LP
The private .h file for a widget is imported by widget classes that are
subclasses of the widget and contains:
.IP \(bu 5
A reference to the public .h file for the class
.IP \(bu 5
A reference to the private .h file for the superclass
.IP \(bu 5
The new fields that the widget instance adds to its superclass's
widget structure
.IP \(bu 5
The complete widget instance structure for this widget
.IP \(bu 5
The new fields that this widget class adds to its superclass's
.PN Constraint
structure if the widget is a subclass of
.PN Constraint 
.IP \(bu 5
The complete
.PN Constraint
structure if the widget is a subclass of
.PN Constraint 
.IP \(bu 5
The new fields that this widget class adds to its superclass's widget class
structure
.IP \(bu 5
The complete widget class structure for this widget
.IP \(bu 5
The complete widget class extension structure for this widget, if any
.IP \(bu 5
The symbolic constant identifying the class extension version, if any
.IP \(bu 5
The name of a constant of the generic widget class structure
.IP \(bu 5
An inherit procedure for subclasses that wish to inherit a superclass 
operation for each new procedure in the widget class structure
.LP
For example, the following is the private .h file for a possible Label widget:
.LP
.Ds
.TA .5i 3i
.ta .5i 3i
#ifndef LABELP_H
#define LABELP_H

#include <X11/Label.h>

/* New representation types used by the Label widget */
#define XtRJustify "Justify"

/* New fields for the Label widget record */
typedef struct {
/* Settable resources */
	Pixel foreground;
	XFontStruct *font;
	String label;	/* text to display */
	XtJustify justify;
	Dimension internal_width;	/* # of pixels horizontal border */
	Dimension internal_height;	/* # of pixels vertical border */

/* Data derived from resources */
	GC normal_GC;
	GC gray_GC;
	Pixmap gray_pixmap;
	Position label_x;
	Position label_y;
	Dimension label_width;
	Dimension label_height;
	Cardinal label_len;
	Boolean display_sensitive;
} LabelPart;
.De
.sp
.Ds
.TA .5i 3i
.ta .5i 3i
/* Full instance record declaration */
typedef struct _LabelRec {
	CorePart core;
	LabelPart label;
} LabelRec;

/* Types for label class methods */
typedef void (*LabelSetTextProc)();
	/* Widget w */
	/* String text */

typedef String (*LabelGetTextProc)();
	/* Widget w */

/* New fields for the Label widget class record */
typedef struct {
	LabelSetTextProc set_text;
	LabelGetTextProc get_text;
	XtPointer extension;
} LabelClassPart;

/* Full class record declaration */
typedef struct _LabelClassRec {
	CoreClassPart core_class;
	LabelClassPart label_class;
} LabelClassRec;

/* Class record variable */
extern LabelClassRec labelClassRec;

#define LabelInheritSetText((LabelSetTextProc)_XtInherit)
#define LabelInheritGetText((LabelGetTextProc)_XtInherit)
#endif LABELP_H
.De
.LP
To accommodate operating systems with file name length restrictions,
the name of the private .h file is the first nine characters of the
widget class followed by a capital P.
For example,
the private .h file for the 
.PN Constraint 
widget is 
.PN ConstrainP.h .
.NH 3
Widget Subclassing in .c Files
.XS
\*(SN Widget Subclassing in .c Files
.XE
.LP
The .c file for a widget contains the structure initializer
for the class record variable,
which contains the following parts:
.IP \(bu 5
Class information (for example, superclass, class_name, widget_size,
class_initialize, and class_inited)
.IP \(bu 5
Data constants (for example, resources and num_resources, 
actions and num_actions, visible_interest, compress_motion, 
compress_exposure, and version)
.IP \(bu 5
Widget operations (for example, initialize, realize, destroy, resize,
expose, set_values, accept_focus, and any operations specific to the widget)
.LP
.IN "superclass" "" "@DEF@"
The superclass field points to the superclass
.PN WidgetClass
record.
For direct subclasses of the generic core widget,
superclass should be initialized to the address of the
.PN widgetClassRec
structure.
The superclass is used for class chaining operations and for
inheriting or enveloping a superclass's operations.
(See Sections 1.6.7, 1.6.9, and 1.6.10).
.LP
.IN "class_name" "" "@DEF@"
The class_name field contains the text name for this class (used by
the resource manager).
For example, the Label widget has the string ``Label''.
More than one widget class can share the same text class name.
.LP
.IN "widget_size" "" "@DEF@"
The widget_size field is the size of the corresponding widget structure
(not the size of the Class structure).
.LP
.IN "version" "" "@DEF@"
The version field indicates the toolkit
implementation version number and is used for
run-time consistency checking of the \*(tk and widgets in an application.
Widget writers must set it to the
implementation-defined symbolic value
.PN XtVersion
in the widget class structure initialization.
Those widget writers who believe that their widget binaries are compatible 
with other implementations of the \*(xI can put the special value
.PN XtVersionDontCheck
in the version field to disable version checking for those widgets.
If a widget needs to compile alternative code for different
revisions of the \*(xI interface definition, it may use the symbol
.PN XtSpecificationRelease ,
as described in Chapter 13.
.LP
The extension field is for future upwards compatibility.
If you add additional fields to class parts, 
all subclass structure layouts change,
requiring complete recompilation. 
To allow clients to avoid recompilation, 
an extension field at the end of each class part can point to a record 
that contains any additional class information required.
.LP
All other fields are described in their respective sections.
.LP
The following is an abbreviated version of the ``.c'' file
for the Label widget.
(The resources table is described in the Chapter 9.)
.LP
.Ds
.TA .5i 1.5i 3i
.ta .5i 1.5i 3i

/* Resources specific to Label */
static XtResource resources[] = {
	{XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel),
	   XtOffset(LabelWidget, label.foreground), XtRString, XtDefaultForeground},
	{XtNfont,  XtCFont, XtRFontStruct, sizeof(XFontStruct *),
	   XtOffset(LabelWidget, label.font),XtRString, XtDefaultFont},
	{XtNlabel,  XtCLabel, XtRString, sizeof(String),
	   XtOffset(LabelWidget, label.label), XtRString, NULL},
		.
		.
		.
}

/* Forward declarations of procedures */
static void ClassInitialize();
static void Initialize();
static void Realize();
static void SetText();
static void GetText();
	.
	.
	.
.De
.sp
.Ds
.TA .5i 2i 3i
.ta .5i 2i 3i
/* Class record constant */
LabelClassRec labelClassRec = {
  {
    /* core_class fields */
	/* superclass	*/	(WidgetClass) &coreClassRec,
	/* class_name	*/	"Label",
	/* widget_size	*/	sizeof(LabelRec),
	/* class_initialize	*/	ClassInitialize,
	/* class_part_initialize	*/	NULL,
	/* class_inited	*/	False,
	/* initialize	*/	Initialize,
	/* initialize_hook	*/	NULL,
	/* realize	*/	Realize,
	/* actions	*/	NULL,
	/* num_actions	*/	0,
	/* resources	*/	resources,
	/* num_resources	*/	XtNumber(resources),
	/* xrm_class	*/	NULLQUARK,
	/* compress_motion	*/	True,
	/* compress_exposure	*/	True,
	/* compress_enterleave	*/	True,
	/* visible_interest	*/	False,
	/* destroy	*/	NULL,
	/* resize	*/	Resize,
	/* expose	*/	Redisplay,
	/* set_values	*/	SetValues,
	/* set_values_hook	*/	NULL,
	/* set_values_almost	*/	XtInheritSetValuesAlmost,
	/* get_values_hook	*/	NULL,
	/* accept_focus	*/	NULL,
	/* version	*/	XtVersion,
	/* callback_offsets	*/	NULL,
	/* tm_table	*/	NULL,
	/* query_geometry	*/	XtInheritQueryGeometry,
	/* display_accelerator	*/	NULL,
	/* extension	*/	NULL
  },
  {
    /* Label_class fields	*/
	/* get_text	*/	GetText,
	/* set_text	*/	SetText,
	/* extension	*/	NULL
  }
};

/* Class record pointer */
WidgetClass labelWidgetClass = (WidgetClass) &labelClassRec;

/* New method access routines */
void Label SetText(w, text)
	Widget w;
	String text;
{
	Label WidgetClass lwc = (Label WidgetClass)XtClass(w);
	XtCheckSubclass(w, labelWidgetClass, NULL);
	*(lwc->label_class.set_text)(w, text)
}
/* Private procedures */
	.
	.
	.
.De
.NH 3
Widget Class and Superclass Look Up
.XS
\*(SN Widget Class and Superclass Look Up
.XE
.LP
To obtain the class of a widget, use
.PN XtClass .
.IN "XtClass" "" "@DEF@"
.FD 0
WidgetClass XtClass(\fIw\fP)
.br
      Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget.
.LP
The
.PN XtClass
function returns a pointer to the widget's class structure.
.sp
.LP
To obtain the superclass of a widget, use
.PN XtSuperclass .
.IN "XtSuperclass" "" "@DEF@"
.FD 0
WidgetClass XtSuperclass(\fIw\fP)
.br
      Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget.
.LP
The
.PN XtSuperclass
function returns a pointer to the widget's superclass class structure.
.NH 3
Widget Subclass Verification
.XS
\*(SN Widget Subclass Verification
.XE
.LP
To check the subclass that a widget belongs to, use
.PN XtIsSubclass .
.IN "XtIsSubclass" "" "@DEF@"
.FD 0
Boolean XtIsSubclass(\fIobject\fP, \fIwidget_class\fP)
.br
      Widget \fIobject\fP;
.br
      WidgetClass \fIwidget_class\fP;
.FN
.IP \fIobject\fP 1i
Specifies the object instance whose class is to be checked.  May be of class
.PN objectClass
or any subclass thereof.
.IP \fIwidget_class\fP 1i
Specifies the widget class to be tested for.
.LP
The
.PN XtIsSubclass
function returns 
.PN True 
if the class of the specified widget is equal to
or is a subclass of the specified widget class.
The specified widget can be any number of subclasses down the chain
and need not be an immediate subclass of the specified widget class.
Composite widgets that need to restrict the class of the items they
contain can use
.PN XtIsSubclass
to find out if a widget belongs to the desired class of objects.
.sp
.LP
To test if a given widget is a subclass of an \*(xI-defined
class, the \*(xI define macros or functions equivalent to
.PN XtIsSubclass
for each of the built-in classes.  These procedures are
.PN XtIsObject ,
.PN XtIsRectObj ,
.PN XtIsWidget ,
.PN XtIsComposite ,
.PN XtIsConstraint ,
.PN XtIsShell ,
.PN XtIsOverrideShell ,
.PN XtIsWMShell ,
.PN XtIsVendorShell ,
.PN XtIsTransientShell ,
.PN XtIsTopLevelShell
and
.PN XtIsApplicationShell .
.IN "XtIsObject" "" "@DEF@"
.IN "XtIsRectObj" "" "@DEF@"
.IN "XtIsWidget" "" "@DEF@"
.IN "XtIsComposite" "" "@DEF@"
.IN "XtIsConstraint" "" "@DEF@"
.IN "XtIsShell" "" "@DEF@"
.IN "XtIsOverrideShell" "" "@DEF@"
.IN "XtIsWMShell" "" "@DEF@"
.IN "XtIsVendorShell" "" "@DEF@"
.IN "XtIsTransientShell" "" "@DEF@"
.IN "XtIsTopLevelShell" "" "@DEF@"
.IN "XtIsApplicationShell" "" "@DEF@"
.LP
All of these macros and functions have the same argument description:
.FD 0
Boolean XtIs\fI<class>\fP (\fIobject\fP)
.br
      Widget \fIobject\fP;
.FN
.IP \fIobject\fP 1i
Specifies the object instance whose class is to be checked. May be of class
.PN objectClass
or any subclass thereof.
.LP
These procedures may be faster than calling
.PN XtIsSubclass
directly for the built-in classes.
.sp
.LP
To check the subclass that a widget belongs to
and generate a debugging error message, use
.PN XtCheckSubclass ,
defined in \fB<X11/IntrinsicP.h>\fP:
.IN "XtCheckSubclass" "" "@DEF@"
.FD 0
void XtCheckSubclass(\fIobject\fP, \fIwidget_class\fP, \fImessage\fP)
.br
      Widget \fIobject\fP;
.br
      WidgetClass \fIwidget_class\fP;
.br
      String \fImessage\fP;
.FN
.IP \fIobject\fP 1i
Specifies the object whose class is to be checked; it may be of class
.PN Object
or any subclass thereof.
.IP \fIwidget_class\fP 1i
Specifies the widget class for which to test.
.ds Me used
.IP \fImessage\fP 1i
Specifies the message that is to be \*(Me.
.LP
The
.PN XtCheckSubclass
macro determines if the class of the specified widget is equal to
or is a subclass of the specified widget class.
The widget can be any number of subclasses down the chain
and need not be an immediate subclass of the specified widget class.
If the specified widget is not a subclass,
.PN XtCheckSubclass
constructs an error message from the supplied message,
the widget's actual class, and the expected class and calls
.PN XtErrorMsg .
.PN XtCheckSubclass
should be used at the entry point of exported routines to ensure 
that the client has passed in a valid widget class for the exported operation.
.LP
.PN XtCheckSubclass
is only executed when the module has been compiled with the compiler symbol
DEBUG defined; otherwise, it is defined as the empty string 
and generates no code.
.NH 3
Superclass Chaining
.XS
\*(SN Superclass Chaining
.XE
.LP
.IN "Chaining" "superclass"
.IN "Chaining" "Subclass"
.IN "Superclass Chaining" "" "@DEF@
.IN "Subclass Chaining" "" "@DEF@
.IN "Inheritance"
While most fields in a widget class structure are self-contained,
some fields are linked to their corresponding field in their superclass
or subclass structures.
With a linked field,
the \*(xI access it value only after accessing its corresponding
superclass value (called downward superclass chaining) or 
before accessing its corresponding superclass value (called upward superclass
chaining).
The self-contained fields in a widget class are:
.IP \(bu 5
class_name
.IP \(bu 5
class_initialize
.IP \(bu 5
widget_size
.IP \(bu 5
realize
.IP \(bu 5
visible_interest
.IP \(bu 5
resize
.IP \(bu 5
expose
.IP \(bu 5
accept_focus
.IP \(bu 5
compress_motion
.IP \(bu 5
compress_exposure
.IP \(bu 5
compress_enterleave
.IP \(bu 5
set_values_almost
.IP \(bu 5
tm_table
.IP \(bu 5
version
.LP
The self-contained fields in
.PN Composite
widget classes are:
.IP \(bu 5
geometry_manager
.IP \(bu 5
change_managed
.IP \(bu 5
insert_child
.IP \(bu 5
delete_child
.IP \(bu 5
accepts_objects
.LP
The self-contained field in
.PN Constraint
widget classes is:
.IP \(bu 5
constraint_size
.LP
The self-contained field in
.PN Shell
widget classes is:
.IP \(bu 5
root_geometry_manager
.LP
With downward superclass chaining,
the invocation of an operation first accesses the field from the
.PN Core 
class structure, then the subclass structure, and so on down the class chain to
that widget's class structure.
These superclass-to-subclass fields are:
.IP \(bu 5
class_part_initialize
.IP \(bu 5
get_values_hook
.IP \(bu 5
initialize
.IP \(bu 5
initialize_hook
.IP \(bu 5
set_values
.IP \(bu 5
set_values_hook
.IP \(bu 5
resources
.LP
In addition, for subclasses of
.PN Constraint ,
the following fields of the
.PN ConstraintClassPart
and
.PN ConstraintClassExtensionRec
structures are chained from the
.PN Constraint
class down to the subclass:
.IP \(bu 5
resources
.IP \(bu 5
initialize
.IP \(bu 5
set_values
.IP \(bu 5
get_values_hook
.LP
With upward superclass chaining,
the invocation of an operation first accesses the field from the widget 
class structure, then the field from the superclass structure,
and so on up the class chain to the 
.PN Core
class structure.
The subclass-to-superclass fields are:
.IP \(bu 5
destroy
.IP \(bu 5
actions
.LP
For subclasses of
.PN Constraint ,
the following field of
.PN ConstraintClassPart
is chained from the subclass up to the
.PN Constraint
class structure:
.IP \(bu 5
destroy

.NH 3
Class Initialization: class_initialize and class_part_initialize Procedures
.XS
\*(SN Class Initialization: class_initialize and class_part_initialize Procedures
.XE
.LP
.IN "Class Initialization"
.IN "Initialization"
Many class records can be initialized completely at compile time.
In some cases, however,
a class may need to register type converters or perform other sorts of
one-time initialization.
.LP
Because the C language does not have initialization procedures
that are invoked automatically when a program starts up,
a widget class can declare a class_initialize procedure
that will be automatically called exactly once by the \*(tk.
A class initialization procedure pointer is of type
.PN XtProc :
.IN "class_initialize procedure" "" "@DEF@"
.IN "XtProc" "" "@DEF@"
.LP
.FD 0
typedef void (*XtProc)();
.FN
.LP
A widget class indicates that it has no class initialization procedure by
specifying NULL in the class_initialize field.
.LP
In addition to having class initializations done exactly once,
some classes need to perform additional initialization for fields in its part
of the class record.
These are performed not just for the particular class 
but for subclasses as well.
This is done in the class's class part initialization procedure,
which is stored in the class_part_initialize field.
The class_part_initialize procedure pointer is of type
.PN XtWidgetClassProc :
.IN "XtWidgetClassProc" "" "@DEF@"
.FD 0
.LP
.Ds 0
.TA .5i
.ta .5i
typedef void (*XtWidgetClassProc)(WidgetClass);
.De
.FN
.LP
During class initialization,
the class part initialization procedure for the class and all its superclasses
are called in superclass-to-subclass order on the class record.
These procedures have the responsibility of doing any dynamic initializations
necessary to their class's part of the record.
The most common is the resolution of any inherited methods defined in the
class.
For example,
if a widget class C has superclasses 
.PN Core , 
.PN Composite , 
A, and B, the class record for C first is passed to 
.PN Core 's 
class_part_initialize record.
This resolves any inherited core methods and compiles the textual
representations of the resource list and action table that are defined in the
class record.
Next, the 
.PN Composite 's 
class_part_initialize is called to initialize the
composite part of C's class record.
Finally, the class_part_initialize procedures for A, B, and C (in order)
are called.
For further information,
see Section 1.6.9.
Classes that do not define any new class fields
or that need no extra processing for them can specify NULL
in the class_part_initialize field.
.LP
All widget classes, whether they have a class initialization procedure or not,
must start with their class_inited field 
.PN False .
.LP
The first time a widget of a class is created,
.PN XtCreateWidget
ensures that the widget class and all superclasses are initialized, in
superclass to subclass order, by checking each class_inited field and
if it is 
.PN False , 
by calling the class_initialize and the class_part_initialize procedures 
for the class and all its superclasses.
The \*(xI then set the class_inited field to a non-zero value.
After the one-time initialization,
a class structure is constant.
.LP
The following provides the class initialization procedure for Label.
.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
static void ClassInitialize()
{
	XtQEleft   = XrmStringToQuark("left");
	XtQEcenter = XrmStringToQuark("center");
	XtQEright  = XrmStringToQuark("right");

	XtAddConverter(XtRString, XtRJustify, CvtStringToJustify, NULL, 0);
}
.De
.NH 3
Initializing a Widget Class
.XS
\*(SN Initializing a Widget Class
.XE
.IN "Widget" "class initialization"
.LP
A class is initialized when the first widget of that class or any
subclass is created.
To initialize a widget class without creating any widgets, use
.PN XtInitializeWidgetClass .
.IN "XtInitializeWidgetClass" "" "@DEF@"
.FD 0
void XtInitializeWidgetClass(\fIobject_class\fP)
.br
      WidgetClass \fIobject_class\fP;
.br
.FN
.IP \fIobject_class\fP 1i
Specifies the object class to initialize.  May be
.PN objectClass
or any subclass thereof.
.LP
If the specified widget class is already initialized,
.PN XtInitializeWidgetClass
returns immediately.
.LP
If the class initialization procedure registers type converters, 
these type converters are not available until the first object
of the class or subclass is created or
.PN XtInitializeWidgetClass
is called
(see Section 9.6).
.NH 3
Inheritance of Superclass Operations
.XS
\*(SN Inheritance of Superclass Operations
.XE
.LP
A widget class is free to use any of its superclass's self-contained
operations rather than implementing its own code.
The most frequently inherited operations are:
.IP \(bu 5
expose
.IP \(bu 5
realize
.IP \(bu 5
insert_child
.IP \(bu 5
delete_child
.IP \(bu 5
geometry_manager
.IP \(bu 5
set_values_almost
.LP
To inherit an operation \fIxyz\fP,
specify the constant
.PN XtInherit \fIXyz\fP
in your class record.
.LP
Every class that declares a new procedure in its widget class part must
provide for inheriting the procedure in its class_part_initialize
procedure.
(The special chained operations initialize, set_values,
and destroy declared in the 
.PN Core
record do not have inherit procedures.
Widget classes that do nothing beyond what their superclass does
specify NULL for chained procedures
in their class records.)
.LP
Inheriting works by comparing the value of the field with a known, special
value and by copying in the superclass's value for that field if a match
occurs.
This special value is usually the \*(xI internal value
.PN _XtInherit
cast to the appropriate type.
.Pn ( _XtInherit
is a procedure that issues an error message if it is actually called.)
.LP
For example, the 
.PN Composite 
class's private include file contains these definitions:
.LP
.Ds 2
.TA .25i 1.5i 3i
.ta .25i 1.5i 3i
#define XtInheritGeometryManager ((XtGeometryHandler) _XtInherit)
#define XtInheritChangeManaged ((XtWidgetProc) _XtInherit)
#define XtInheritInsertChild ((XtArgsProc) _XtInherit)
#define XtInheritDeleteChild ((XtWidgetProc) _XtInherit)
.De
.LP
The Composite's class_part_initialize procedure begins as follows:
.LP
.Ds 2
.TA .2i 1.5i 3i
.ta .2i 1.5i 3i
static void CompositeClassPartInitialize(widgetClass)
	WidgetClass widgetClass;
{
	register CompositeWidgetClass wc = (CompositeWidgetClass) widgetClass;
	CompositeWidgetClass super = (CompositeWidgetClass) wc->core_class.superclass

	if (wc->composite_class.geometry_manager == XtInheritGeometryManager) {
	    wc->composite_class.geometry_manager = super->composite_class.geometry_manager;
	}

	if (wc->composite_class.change_managed == XtInheritChangeManaged) {
	    wc->composite_class.change_managed = super->composite_class.change_managed;
	}
	.
	.
	.
.De
.LP
The inherit constants defined for 
.PN Core 
are:
.IP \(bu 5
.PN XtInheritRealize
.IP \(bu 5
.PN XtInheritResize
.IP \(bu 5
.PN XtInheritExpose
.IP \(bu 5
.PN XtInheritSetValuesAlmost
.IP \(bu 5
.PN XtInheritAcceptFocus
.IP \(bu 5
.PN XtInheritQueryGeometry
.IP \(bu 5
.PN XtInheritTranslations
.IP \(bu 5
.PN XtInheritDisplayAccelerator
.LP
The inherit constants defined for 
.PN Composite
are:
.IP \(bu 5
.PN XtInheritGeometryManager
.IP \(bu 5
.PN XtInheritChangeManaged
.IP \(bu 5
.PN XtInheritInsertChild
.IP \(bu 5
.PN XtInheritDeleteChild
.LP
The inherit constant defined for
.PN Shell
is:
.IP \(bu 5
.PN XtInheritRootGeometryManager

.NH 3
Invocation of Superclass Operations
.XS
\*(SN Invocation of Superclass Operations
.XE
.LP
A widget class sometimes explicitly needs to call a superclass operation
that usually is not chained.
For example,
a widget's expose procedure might call its superclass's expose
and then perform a little more work of its own.
.PN Composite 
classes with fixed children can implement insert_child
by first calling their superclass's insert_child procedure
.IN "insert_child procedure"
and then calling
.PN XtManageChild
to add the child to the managed list.
.LP
.NT
A class method should not use
.PN XtSuperclass
but should instead call the class method of its own specific superclass,
not the widget's superclass.
That is, it should use its own class pointers only,
not the widget's class pointers,
as the widget's class may be a subclass of the ``current''
class.
.NE
This technique is referred to as \fIenveloping\fP the superclass's operation.
.NH 3
Class Extension Records
.XS
\*(SN Class Extension Records
.XE
.IN "Widget" "class extension records"
.LP
It may be necessary at times to add new fields to already existing
widget class structures.  To permit this to be done without requiring
recompilation of all subclasses, the last field in a class part record
should be an extension pointer.  If no extension fields for a class
have yet been defined, subclasses should initialize the value of the
extension pointer to NULL.
.LP
If extension fields exist, as is the case with the
.PN Composite ,
.PN Constraint
and
.PN Shell
classes, subclasses can provide values for these fields by setting the
extension pointer for the appropriate part in their class structure to
point to a statically declared extension record containing the
additional fields.
Setting the extension field is never mandatory; code that uses fields
in the extension record must always check the extension field and take
some appropriate default action if it is NULL.
.LP
In order to permit multiple subclasses and libraries to chain extension
records from a single extension field, extension records should be
declared as a linked list and each extension record definition should
contain the following four fields at the beginning of the structure
declaration:
.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
struct {
	XtPointer next_extension;
	XrmQuark record_type;
	long version;
	Cardinal record_size;
};
.De
.IP next_extension 1.25i
Specifies the next record in the list, or NULL.
.IP record_type 1.25i
Specifies the particular structure declaration to which
each extension record instance conforms.
.IP version 1.25i
Specifies a version id symbolic constant supplied by
the definer of the structure.
.IP record_size 1.25i
Specifies the total number of bytes allocated for the
extension record.
.LP
The record_type field identifies the contents of the extension record
and is used by the definer of the record to locate its particular
extension record in the list.  Record_type is normally assigned the
result of
.PN XrmStringToQuark
for a registered string constant.  The
\*(xI reserve all record type strings beginning with the two
characters ``XT'' for future standard uses.  The value
.PN \s-1NULLQUARK\s+1
may also be used
by the class part owner in extension records attached to its own class
part extension field to identify the extension record unique to that
particular class.
.LP
The version field is an owner-defined constant which may be used to
identify binary files which have been compiled with alternate
definitions of the extension record data structure.  The private
header file for a widget class should provide a symbolic constant for
subclasses to use to initialize this field.
.LP
The record_size field value includes the four common header fields and
should normally be initialized with \fBsizeof()\fP.
.bp
