aboutsummaryrefslogtreecommitdiff
path: root/libXt/specs/CH01
diff options
context:
space:
mode:
Diffstat (limited to 'libXt/specs/CH01')
-rw-r--r--libXt/specs/CH012471
1 files changed, 2471 insertions, 0 deletions
diff --git a/libXt/specs/CH01 b/libXt/specs/CH01
new file mode 100644
index 000000000..78f128bd7
--- /dev/null
+++ b/libXt/specs/CH01
@@ -0,0 +1,2471 @@
+.\" $Xorg: CH01,v 1.3 2000/08/17 19:42:42 cpqbld Exp $
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+.\" X Consortium
+.\"
+.\" Permission is hereby granted, free of charge, to any person obtaining
+.\" a copy of this software and associated documentation files (the
+.\" "Software"), to deal in the Software without restriction, including
+.\" without limitation the rights to use, copy, modify, merge, publish,
+.\" distribute, sublicense, and/or sell copies of the Software, and to
+.\" permit persons to whom the Software is furnished to do so, subject to
+.\" the following conditions:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\"
+.\" Except as contained in this notice, the name of the X Consortium shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from the X Consortium.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+.\" Digital Equipment Corporation, Maynard, Massachusetts.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for any
+.\" purpose and without fee is hereby granted, provided that the above copyright
+.\" notice appears in all copies and that both that copyright notice and this
+.\" permission notice appear in supporting documentation, and that the name of
+.\" Digital not be used in in advertising or publicity pertaining
+.\" to distribution of the software without specific, written prior permission.
+.\" Digital makes no representations about the suitability of the
+.\" software described herein for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\"
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 1\fP\s-1
+
+\s+1\fBIntrinsics and Widgets\fP\s-1
+.sp 2
+.if \n(GS .nr nh*hl 1
+.nr H1 1
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+\fBChapter 1 \(em Intrinsics and Widgets\fP
+.XE
+The \*(xI are a programming library tailored to the special requirements
+of user interface construction within a network window system,
+specifically the X Window System.
+The \*(xI and a widget set make up an \*(tk.
+
+.NH 2
+Intrinsics
+.XS
+\fB\*(SN Intrinsics\fP
+.XE
+.LP
+The \*(xI provide the base mechanism necessary to build
+a wide variety of interoperating widget sets and application environments.
+The Intrinsics are a layer on top of Xlib, the
+C Library X Interface. They extend the
+fundamental abstractions provided by the X Window System while still
+remaining independent of any particular user interface policy or
+style.
+.LP
+The Intrinsics use object-oriented programming techniques to supply a
+consistent architecture for constructing and composing user interface
+components, known as widgets. This
+allows programmers to extend a widget set in new ways, either by
+deriving new widgets from existing ones (subclassing) or by writing
+entirely new widgets following the established conventions.
+.LP
+When the \*(xI were first conceived, the root of the object
+hierarchy was a widget class named
+Core.
+.IN "Core"
+In Release 4 of the
+\*(xI, three nonwidget superclasses were added above Core.
+These superclasses are described in Chapter 12. The name of the class
+now at the root of the Intrinsics class hierarchy is
+Object.
+.IN "Object"
+The remainder of this
+specification refers uniformly to \fIwidgets\fP and \fICore\fP
+as if they were the
+base class for all \*(xI operations. The argument descriptions
+for each Intrinsics procedure and Chapter 12 describe which operations
+are defined for the nonwidget superclasses of Core. The reader may
+determine by context whether a specific reference to \fIwidget\fP
+actually means ``widget'' or ``object.''
+
+.NH 2
+Languages
+.XS
+\fB\*(SN Languages\fP
+.XE
+.LP
+The Intrinsics are intended to be used for two programming purposes.
+Programmers writing widgets will be using most of the facilities
+provided by the
+Intrinsics to construct user interface components from the simple, such
+as buttons and scrollbars, to the complex, such as control panels and
+property sheets. Application programmers will use a much smaller subset of
+the Intrinsics procedures in combination with one or more sets of widgets to
+construct and present complete user interfaces on an X display. The
+Intrinsics
+programming interfaces primarily
+intended for application use are designed to be callable from most
+procedural programming languages. Therefore, most arguments are passed by
+reference rather than by value. The interfaces primarily
+intended for widget programmers are expected to be used principally
+from the C language. In these cases, the usual C programming
+conventions apply. In this specification, the term \fIclient\fP refers to
+any module, widget, or application that calls an Intrinsics procedure.
+.LP
+Applications that use the \*(xI mechanisms
+must include the header files
+.Pn < X11/Intrinsic.h >
+and
+.Pn < X11/StringDefs.h >,
+or their equivalent,
+and they may also include
+.Pn < X11/Xatoms.h >
+and
+.Pn < X11/Shell.h >.
+In addition, widget implementations should include
+.Pn < X11/IntrinsicP.h >
+instead of
+.Pn < X11/Intrinsic.h >.
+.LP
+The applications must also include the additional header files 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 when linking the application.
+
+.NH 2
+Procedures and Macros
+.LP
+.XS
+\fB\*(SN Procedures and Macros\fP
+.XE
+All functions defined in this specification 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 that
+has the same precedence as a function call and that 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 that do not have function
+equivalents and that may expand their arguments in a manner other
+than that described above:
+.PN XtCheckSubclass ,
+.PN XtNew ,
+.PN XtNumber ,
+.PN XtOffsetOf ,
+.PN XtOffset ,
+and
+.PN XtSetArg .
+
+.NH 2
+Widgets
+.LP
+.XS
+\fB\*(SN Widgets\fP
+.XE
+.LP
+The fundamental abstraction and data type of the \*(tk is the widget,
+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, which is statically
+allocated and initialized and which contains the operations allowable on
+widgets of that class.
+Logically, a widget class is the procedures and data 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.5.
+.LP
+The distribution of the declarations and code for a new widget class
+among a public .h file for application programmer use, a private .h file
+for widget programmer use,
+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 which contains instance-specific values.
+.IP \(bu 5
+A class structure which 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,
+or border widths) is customizable by users.
+.LP
+This chapter discusses the base widget classes,
+Core, Composite, and Constraint, and
+ends with a discussion of widget classing.
+
+.NH 3
+Core Widgets
+.XS
+\*(SN Core Widgets
+.XE
+.LP
+.IN "Core" "" "@DEF@"
+The
+Core
+widget class contains the definitions of fields common to all widgets.
+All widgets classes are subclasses of the
+Core class,
+which is defined by the
+.PN CoreClassPart
+and
+.PN CorePart
+structures.
+
+.NH 4
+CoreClassPart Structure
+.XS
+\*(SN CoreClassPart Structure
+.XE
+.LP
+All widget classes contain the fields defined in the
+.PN CoreClassPart
+structure.
+.LP
+.IN "CoreClassPart" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3.5i
+.ta .5i 3.5i
+typedef struct {
+ WidgetClass superclass; See Section 1.6
+ String class_name; See Chapter 9
+ Cardinal widget_size; See Section 1.6
+ 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.5
+ XtArgsProc initialize_hook; See Section 2.5
+ XtRealizeProc realize; See Section 2.6
+ 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
+ XtEnum compress_exposure; See Section 7.9
+ Boolean compress_enterleave; See Section 7.9
+ Boolean visible_interest; See Section 7.10
+ XtWidgetProc destroy; See Section 2.8
+ 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
+.eM
+All widget classes have the Core class fields as their first component.
+The prototypical
+.PN WidgetClass
+and
+.PN CoreWidgetClass
+are defined with only this set of fields.
+.LP
+.IN "Core"
+.IN "WidgetClass" "" "@DEF@"
+.IN "CoreWidgetClass" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+ CoreClassPart core_class;
+} WidgetClassRec, *WidgetClass, CoreClassRec, *CoreWidgetClass;
+.De
+.LP
+.eM
+Various routines can cast widget class pointers, as needed,
+to specific widget class types.
+.LP
+The single occurrences of the class record and pointer for
+creating instances of Core are
+.LP
+In
+.PN IntrinsicP.h :
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+extern WidgetClassRec widgetClassRec;
+#define coreClassRec widgetClassRec
+.De
+.LP
+.eM
+In
+.PN Intrinsic.h :
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+extern WidgetClass widgetClass, coreWidgetClass;
+.De
+.LP
+.eM
+The opaque types
+.PN Widget
+and
+.PN WidgetClass
+and the opaque variable
+.PN widgetClass
+are defined for generic actions on widgets.
+In order to make these types opaque and ensure that the compiler
+does not allow applications to access private data, the \*(xI use
+incomplete structure definitions in
+.PN Intrinsic.h :
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _WidgetClassRec *WidgetClass, *CoreWidgetClass;
+.De
+.eM
+
+.NH 4
+CorePart Structure
+.XS
+\*(SN CorePart Structure
+.XE
+.LP
+All widget instances contain the fields defined in the
+.PN CorePart
+structure.
+.LP
+.IN "CorePart" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _CorePart {
+ Widget self; Described below
+ WidgetClass widget_class; See Section 1.6
+ Widget parent; See Section 2.5
+ Boolean being_destroyed; See Section 2.8
+ XtCallbackList destroy_callbacks; See Section 2.8
+ 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
+ XtTranslations accelerators; See Chapter 10
+ Pixel border_pixel; See Section 2.6
+ Pixmap border_pixmap; See Section 2.6
+ WidgetList popup_list; See Chapter 5
+ Cardinal num_popups; See Chapter 5
+ String name; See Chapter 9
+ Screen *screen; See Section 2.6
+ Colormap colormap; See Section 2.6
+ Window window; See Section 2.6
+ Cardinal depth; See Section 2.6
+ Pixel background_pixel; See Section 2.6
+ Pixmap background_pixmap; See Section 2.6
+ Boolean visible; See Section 7.10
+ Boolean mapped_when_managed; See Chapter 3
+} CorePart;
+.De
+.LP
+.eM
+All widget instances have the Core fields as their first component.
+The prototypical type
+.PN Widget
+is defined with only this set of fields.
+.LP
+.IN "Widget" "" "@DEF@"
+.IN "CoreWidget" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+ CorePart core;
+} WidgetRec, *Widget, CoreRec, *CoreWidget;
+.De
+.LP
+.eM
+Various routines can cast widget pointers, as needed,
+to specific widget types.
+.LP
+In order to make these types opaque and ensure that the compiler
+does not allow applications to access private data, the \*(xI use
+incomplete structure definitions in
+.PN Intrinsic.h .
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _WidgetRec *Widget, *CoreWidget;
+.De
+.eM
+
+.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 coreClassRec
+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
+.LP
+Additional resources are defined for all widgets via the
+.PN objectClassRec
+and
+.PN rectObjClassRec
+resource lists; see Sections 12.2 and 12.3 for details.
+
+.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 \*(xI,
+from the resource lists, and by the initialize procedures, 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{
+\fIwidget_class\fP argument to
+.PN XtCreateWidget
+(may not be changed).
+T}
+T{
+parent
+T} T{
+\fIparent\fP argument to
+.PN XtCreateWidget
+(may not be changed).
+T}
+being_destroyed Parent's \fIbeing_destroyed\fP 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 T{
+logical AND of parent's \fIsensitive\fP and
+\fIancestor_sensitive\fP values.
+T}
+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{
+\fIname\fP argument to
+.PN XtCreateWidget
+(may not be changed).
+T}
+T{
+screen
+T} T{
+Parent's \fIscreen\fP; top-level widget gets screen from display specifier
+.br
+(may not be changed).
+T}
+colormap Parent's \fIcolormap\fP value.
+window NULL
+depth Parent's \fIdepth\fP; 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@"
+The Composite
+widget class is a subclass of the
+Core
+widget class (see Chapter 3).
+Composite widgets are intended to be containers for other widgets.
+The additional data used by composite widgets are defined by the
+.PN CompositeClassPart
+and
+.PN CompositePart
+structures.
+
+.NH 4
+CompositeClassPart Structure
+.XS
+\*(SN CompositeClassPart Structure
+.XE
+.LP
+In addition to the
+Core
+class fields,
+widgets of the Composite class have the following class fields.
+.LP
+.IN "CompositeClassPart" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3.5i
+.ta .5i 3.5i
+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
+.eM
+The extension record defined for
+.PN CompositeClassPart
+with \fIrecord_type\fP
+equal to
+.PN \s-1NULLQUARK\s+1
+is
+.PN CompositeClassExtensionRec .
+.LP
+.IN "CompositeClassExtensionRec" "" "@DEF@"
+.IN "CompositeClassExtension" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3.5i
+.ta .5i 3.5i
+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 Section 2.5.2
+ Boolean allows_change_managed_set; See Section 3.4.3
+} CompositeClassExtensionRec, *CompositeClassExtension;
+.De
+.LP
+.eM
+Composite
+classes have the Composite class fields immediately following the
+Core class fields.
+.LP
+.IN "CompositeWidgetClass" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+ CoreClassPart core_class;
+ CompositeClassPart composite_class;
+} CompositeClassRec, *CompositeWidgetClass;
+.De
+.LP
+.eM
+The single occurrences of the class record and pointer for creating
+instances of Composite are
+.LP
+In
+.PN IntrinsicP.h :
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+extern CompositeClassRec compositeClassRec;
+.De
+.LP
+.eM
+In
+.PN Intrinsic.h :
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+extern WidgetClass compositeWidgetClass;
+.De
+.LP
+.eM
+The opaque types
+.PN CompositeWidget
+and
+.PN CompositeWidgetClass
+and the opaque variable
+.PN compositeWidgetClass
+are defined for generic operations on widgets whose class
+is Composite or a subclass of Composite.
+The symbolic constant for the
+.PN CompositeClassExtension
+version identifier is
+.PN XtCompositeExtensionVersion
+(see Section 1.6.12).
+.PN Intrinsic.h
+uses an incomplete structure
+definition to ensure that the compiler catches attempts to access
+private data.
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _CompositeClassRec *CompositeWidgetClass;
+.De
+.eM
+
+.NH 4
+CompositePart Structure
+.XS
+\*(SN CompositePart Structure
+.XE
+.LP
+In addition to the
+Core instance
+fields,
+widgets of the Composite class have the following
+instance fields defined in the
+.PN CompositePart
+structure.
+.LP
+.IN "CompositePart" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+ WidgetList children; See Chapter 3
+ Cardinal num_children; See Chapter 3
+ Cardinal num_slots; See Chapter 3
+ XtOrderProc insert_position; See Section 3.2
+} CompositePart;
+.De
+.LP
+.eM
+Composite
+widgets have the Composite instance fields immediately following the Core
+instance fields.
+.LP
+.IN "CompositeWidget" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+} CompositeRec, *CompositeWidget;
+.De
+.LP
+.eM
+.PN Intrinsic.h
+uses an incomplete structure definition to ensure that the
+compiler catches attempts to access private data.
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _CompositeRec *CompositeWidget;
+.De
+.eM
+
+.NH 4
+Composite Resources
+.XS
+\fB\*(SN Composite Resources\fP
+.XE
+.LP
+.IN "CompositeWidget" "Resources"
+The resource names, classes, and representation types
+that are specified in
+the
+.PN compositeClassRec
+resource list are
+.LP
+.TS
+lw(1.5i) lw(1.5i) lw(2i) .
+_
+.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 from the
+Composite
+resource list and by the
+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 to insert at end
+.sp 6p
+_
+.TE
+.LP
+The \fIchildren\fP, \fInum_children\fP,
+and \fIinsert_position\fP fields are declared
+as resources;
+.IN XtNinsertPosition
+XtNinsertPosition
+is a settable resource,
+.IN XtNchildren
+XtNchildren
+and
+.IN XtNnumChildren
+XtNnumChildren
+may be read by any client but should only be modified by the composite
+widget class procedures.
+
+.NH 3
+Constraint Widgets
+.XS
+\*(SN Constraint Widgets
+.XE
+.LP
+.IN "Constraint" "" "@DEF@"
+The Constraint
+widget class is a subclass of the
+Composite
+widget class (see Section 3.6). Constraint
+widgets maintain additional state
+data for each child; for example, client-defined constraints on the child's
+geometry.
+The additional data used by constraint widgets are defined by the
+.PN ConstraintClassPart
+and
+.PN ConstraintPart
+structures.
+
+.NH 4
+ConstraintClassPart Structure
+.XS
+\*(SN ConstraintClassPart Structure
+.XE
+.LP
+In addition to the
+Core
+and
+Composite
+class fields,
+widgets of the Constraint class
+have the following class fields.
+.LP
+.IN "ConstraintClassPart" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+ XtResourceList resources; See Chapter 9
+ Cardinal num_resources; See Chapter 9
+ Cardinal constraint_size; See Section 3.6
+ XtInitProc initialize; See Section 3.6
+ XtWidgetProc destroy; See Section 3.6
+ XtSetValuesFunc set_values; See Section 9.7.2
+ XtPointer extension; See Section 1.6
+} ConstraintClassPart;
+.De
+.LP
+.eM
+The extension record defined for
+.PN ConstraintClassPart
+with \fIrecord_type\fP equal to
+.PN \s-1NULLQUARK\s+1
+is
+.PN ConstraintClassExtensionRec .
+.LP
+.IN "ConstraintClassExtensionRec" "" "@DEF@"
+.IN "ConstraintClassExtension" "" "@DEF@"
+.sM
+.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 9.7.1
+} ConstraintClassExtensionRec, *ConstraintClassExtension;
+.De
+.LP
+.eM
+Constraint
+classes have the Constraint class fields immediately following the
+Composite class fields.
+.LP
+.IN "ConstraintWidgetClass" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _ConstraintClassRec {
+ CoreClassPart core_class;
+ CompositeClassPart composite_class;
+ ConstraintClassPart constraint_class;
+} ConstraintClassRec, *ConstraintWidgetClass;
+.De
+.LP
+.eM
+The single occurrences of the class record and pointer for creating
+instances of Constraint are
+.LP
+In
+.PN IntrinsicP.h :
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+extern ConstraintClassRec constraintClassRec;
+.De
+.LP
+.eM
+In
+.PN Intrinsic.h :
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+extern WidgetClass constraintWidgetClass;
+.De
+.LP
+.eM
+The opaque types
+.PN ConstraintWidget
+and
+.PN ConstraintWidgetClass
+and the opaque variable
+.PN constraintWidgetClass
+are defined for generic operations on widgets
+whose class is Constraint or a subclass
+of Constraint.
+The symbolic constant for the
+.PN ConstraintClassExtension
+version identifier is
+.PN XtConstraintExtensionVersion
+(see Section 1.6.12).
+.PN Intrinsic.h
+uses an incomplete structure definition to ensure that the
+compiler catches attempts to access private data.
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _ConstraintClassRec *ConstraintWidgetClass;
+.De
+.eM
+
+.NH 4
+ConstraintPart Structure
+.XS
+\*(SN ConstraintPart Structure
+.XE
+.LP
+In addition to the
+Core
+and
+Composite instance
+fields,
+widgets of the Constraint class have the following unused
+instance fields defined in the
+.PN ConstraintPart
+structure
+.LP
+.IN "ConstraintPart" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+ int empty;
+} ConstraintPart;
+.De
+.LP
+.eM
+Constraint
+widgets have the Constraint instance fields immediately following the
+Composite instance fields.
+.LP
+.IN "ConstraintWidget" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+ CorePart core;
+ CompositePart composite;
+ ConstraintPart constraint;
+} ConstraintRec, *ConstraintWidget;
+.De
+.LP
+.eM
+.PN Intrinsic.h
+uses an incomplete structure definition to ensure that the
+compiler catches attempts to access private data.
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _ConstraintRec *ConstraintWidget;
+.De
+.eM
+
+.NH 4
+Constraint Resources
+.XS
+\fB\*(SN Constraint Resources\fP
+.XE
+.LP
+The
+.PN constraintClassRec
+\fIcore_class\fP and \fIconstraint_class resources\fP fields are NULL,
+and the \fInum_resources\fP fields are zero;
+no additional resources beyond those declared by
+the superclasses
+are defined for
+Constraint.
+
+.NH 2
+Implementation-Specific Types
+.XS
+\fB\*(SN Implementation-Specific Types\fP
+.XE
+.LP
+To increase the portability of widget and application source code
+between different system environments, the \*(xI define several
+types whose precise representation is explicitly dependent upon,
+and chosen by, each individual implementation of the \*(xI.
+.LP
+These implementation-defined types are
+.IN "Boolean" "" "@DEF@"
+.IP \fBBoolean\fP 11
+A datum that contains a zero or nonzero value.
+Unless explicitly stated, clients should not assume
+that the nonzero value is equal to the symbolic
+value
+.PN True .
+.IN "Cardinal" "" "@DEF@"
+.IP \fBCardinal\fP 11
+An unsigned integer datum with a minimum range of [0..2^16-1].
+.IN "Dimension" "" "@DEF@"
+.IP \fBDimension\fP 11
+An unsigned integer datum with a minimum range of [0..2^16-1].
+.IN "Position" "" "@DEF@"
+.IP \fBPosition\fP 11
+A signed integer 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 value may be converted
+to an
+.PN XtPointer
+and back again and the result will
+compare equal to the original value. In ANSI C
+environments it is expected that
+.PN XtPointer
+will be
+defined as void*.
+.IN "XtArgVal" "" "@DEF@"
+.IP \fBXtArgVal\fP 11
+A datum large enough to contain an
+.PN XtPointer ,
+.PN Cardinal ,
+.PN Dimension ,
+or
+.PN Position
+value.
+.IN "XtEnum" "" "@DEF@"
+.IP \fBXtEnum\fP 11
+An integer 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 types, 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. These
+structures may also have additional private
+fields internal to the implementation.
+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 relations 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 \fIwidget_class\fP 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,
+widgets usually do not implement directly callable procedures;
+rather, they implement procedures, called methods, that are available through
+their widget class structure.
+These methods are invoked by generic procedures that envelop common actions
+around the methods implemented by the widget class.
+Such procedures are applicable to all widgets
+of that class and also to widgets whose classes are subclasses of that class.
+.LP
+All widget classes are a subclass of
+Core
+and can be subclassed further.
+Subclassing reduces the amount of code and declarations
+necessary 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 superclasses' 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 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, used by client widgets or applications.
+.IP \(bu 5
+A private .h file, used by widgets whose classes
+are subclasses of the widget class.
+.IP \(bu 5
+A .c file, which implements the widget.
+
+.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 library 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
+``XtN''.
+For example,
+the \fIbackground_pixmap\fP 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 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
+``XtC''
+(for example, XtCBorderWidth).
+Many predefined classes are listed in
+.Pn < X11/StringDefs.h >.
+.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
+``XtR''
+(for example, XtRTranslationTable).
+Many predefined representation types are listed in
+.Pn < X11/StringDefs.h >.
+.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
+Additional widget instance structure part name AbcXyzPart.
+.IP \- 5
+Complete widget instance structure names AbcXyzRec and _AbcXyzRec.
+.IP \- 5
+Widget instance structure pointer type name AbcXyzWidget.
+.IP \- 5
+Additional class structure part name AbcXyzClassPart.
+.IP \- 5
+Complete class structure names AbcXyzClassRec and _AbcXyzClassRec.
+.IP \- 5
+Class structure pointer type name AbcXyzWidgetClass.
+.IP \- 5
+Class structure variable abcXyzClassRec.
+.IP \- 5
+Class structure 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 XtN..., XtC..., and XtR...
+may be implemented
+as macros, as global symbols, or as a mixture of the two. The
+(implicit) type of the identifier is
+.PN String .
+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 string. Clients should also note 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 file for the superclass.
+.IP \(bu 5
+Symbolic identifiers for
+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
+Type declarations for any new resource data types defined by the class.
+.IP \(bu 5
+The class record pointer variable used to create widget instances.
+.IP \(bu 5
+The C type that corresponds to 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 LabelSetText();
+ /* Widget w */
+ /* String text */
+
+extern String LabelGetText();
+ /* 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
+Constraint
+widget class 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
+Symbolic identifiers for any new resource representation types defined
+by the class. The definitions should have a single space between the
+definition name and the value and no trailing space or comment.
+.IP \(bu 5
+A structure part definition for
+the new fields that the widget instance adds to its superclass's
+widget structure.
+.IP \(bu 5
+The complete widget instance structure definition for this widget.
+.IP \(bu 5
+A structure part definition for
+the new fields that this widget class adds to its superclass's
+constraint
+structure if the widget class is a subclass of
+Constraint.
+.IP \(bu 5
+The complete
+constraint
+structure definition if the widget class is a subclass of
+Constraint.
+.IP \(bu 5
+Type definitions for any new procedure types used by class methods
+declared in the widget class part.
+.IP \(bu 5
+A structure part definition for
+the new fields that this widget class adds to its superclass's widget class
+structure.
+.IP \(bu 5
+The complete widget class structure definition for this widget.
+.IP \(bu 5
+The complete widget class extension structure definition
+for this widget, if any.
+.IP \(bu 5
+The symbolic constant identifying the class extension version, if any.
+.IP \(bu 5
+The name of the global class structure variable containing the generic
+class structure for this class.
+.IP \(bu 5
+An inherit constant for each new procedure in the widget class part 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; /* # pixels horizontal border */
+ Dimension internal_height; /* # 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
+Constraint
+widget class 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, \fIsuperclass\fP, \fIclass_name\fP,
+\fIwidget_size\fP,
+\fIclass_initialize\fP, and \fIclass_inited\fP).
+.IP \(bu 5
+Data constants (for example, \fIresources\fP and \fInum_resources\fP,
+\fIactions\fP and \fInum_actions\fP, \fIvisible_interest\fP,
+\fIcompress_motion\fP,
+\fIcompress_exposure\fP, and \fIversion\fP).
+.IP \(bu 5
+Widget operations (for example, \fIinitialize\fP, \fIrealize\fP, \fIdestroy\fP,
+\fIresize\fP, \fIexpose\fP, \fIset_values\fP, \fIaccept_focus\fP,
+and any new operations specific to
+the widget).
+.LP
+.IN "superclass" "" "@DEF@"
+The \fIsuperclass\fP field points to the superclass
+global class
+record, declared in the superclass private .h file.
+For direct subclasses of the generic core widget,
+\fIsuperclass\fP 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 \fIclass_name\fP field contains the text name for this class,
+which is 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.
+This string must be permanently allocated prior to or during the
+execution of the class initialization procedure and must not be
+subsequently deallocated.
+
+.LP
+.IN "widget_size" "" "@DEF@"
+The \fIwidget_size\fP field is the size of the corresponding widget
+instance structure
+(not the size of the class structure).
+.LP
+.IN "version" "" "@DEF@"
+The \fIversion\fP field indicates the toolkit
+implementation version number and is used for
+runtime 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 \fIversion\fP 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.
+Use of
+.PN XtVersion
+allows the \*(xI implementation to recognize widget binaries
+that were compiled with older implementations.
+.LP
+The \fIextension\fP field is for future upward compatibility.
+If the widget programmer adds 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 .c file also contains the declaration of the global class
+structure pointer variable used to create instances of the class.
+The following is an abbreviated version of the .c file
+for a Label widget.
+The resources table is described in 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 LabelSetText(w, text)
+ Widget w;
+ String text;
+{
+ LabelWidgetClass 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@"
+.LP
+.sM
+.FD 0
+WidgetClass XtClass(\fIw\fP)
+.br
+ Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget. \*(oI
+.LP
+.eM
+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@"
+.LP
+.sM
+.FD 0
+WidgetClass XtSuperclass(\fIw\fP)
+.br
+ Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget. \*(oI
+.LP
+.eM
+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 to which a widget belongs, use
+.PN XtIsSubclass .
+.IN "XtIsSubclass" "" "@DEF@"
+.LP
+.sM
+.FD 0
+Boolean XtIsSubclass(\fIw\fP, \fIwidget_class\fP)
+.br
+ Widget \fIw\fP;
+.br
+ WidgetClass \fIwidget_class\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget or object instance whose class is to be checked. \*(oI
+.IP \fIwidget_class\fP 1i
+Specifies the widget class for which to test. \*(oC
+.LP
+.eM
+The
+.PN XtIsSubclass
+function returns
+.PN True
+if the class of the specified widget is equal to
+or is a subclass of the specified class.
+The widget's class can be any number of subclasses down the chain
+and need not be an immediate subclass of the specified 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 belongs to 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 ,
+.PN XtIsApplicationShell ,
+and
+.PN XtIsSessionShell .
+.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@"
+.IN "XtIsSessionShell" "" "@DEF@"
+.LP
+All these macros and functions have the same argument description.
+.LP
+.sM
+.FD 0
+Boolean XtIs\fI<class>\fP (\fIw\fP)
+.br
+ Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget or object instance whose class is to be checked. \*(oI
+.LP
+.eM
+These procedures may be faster than calling
+.PN XtIsSubclass
+directly for the built-in classes.
+.sp
+.LP
+To check a widget's class
+and to generate a debugging error message, use
+.PN XtCheckSubclass ,
+defined in
+.Pn < X11/IntrinsicP.h >:
+.IN "XtCheckSubclass" "" "@DEF@"
+.LP
+.sM
+.FD 0
+void XtCheckSubclass(\fIw\fP, \fIwidget_class\fP, \fImessage\fP)
+.br
+ Widget \fIw\fP;
+.br
+ WidgetClass \fIwidget_class\fP;
+.br
+ String \fImessage\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget or object whose class is to be checked. \*(oI
+.IP \fIwidget_class\fP 1i
+Specifies the widget class for which to test. \*(oC
+.ds Me used
+.IP \fImessage\fP 1i
+Specifies the message to be used.
+.LP
+.eM
+The
+.PN XtCheckSubclass
+macro determines if the class of the specified widget is equal to
+or is a subclass of the specified class.
+The widget's class can be any number of subclasses down the chain
+and need not be an immediate subclass of the specified class.
+If the specified widget's class 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 fields in their superclass
+structures.
+With a linked field,
+the \*(xI access the field's 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 are
+.sp
+.ta 2i
+In all widget classes: \fIclass_name\fP
+.br
+ \fIclass_initialize\fP
+.br
+ \fIwidget_size\fP
+.br
+ \fIrealize\fP
+.br
+ \fIvisible_interest\fP
+.br
+ \fIresize\fP
+.br
+ \fIexpose\fP
+.br
+ \fIaccept_focus\fP
+.br
+ \fIcompress_motion\fP
+.br
+ \fIcompress_exposure\fP
+.br
+ \fIcompress_enterleave\fP
+.br
+ \fIset_values_almost\fP
+.br
+ \fItm_table\fP
+.br
+ \fIversion\fP
+.br
+ \fIallocate\fP
+.br
+ \fIdeallocate\fP
+.sp
+In Composite widget classes: \fIgeometry_manager\fP
+.br
+ \fIchange_managed\fP
+.br
+ \fIinsert_child\fP
+.br
+ \fIdelete_child\fP
+.br
+ \fIaccepts_objects\fP
+.br
+ \fIallows_change_managed_set\fP
+.sp
+In Constraint widget classes: \fIconstraint_size\fP
+.sp
+In Shell widget classes: \fIroot_geometry_manager\fP
+.sp
+.LP
+With downward superclass chaining,
+the invocation of an operation first accesses the field from the
+Object,
+RectObj,
+and
+Core
+class structures, then from the subclass structure, and so on down the class chain to
+that widget's class structure. These superclass-to-subclass fields are
+.sp
+.ta 1i
+.br
+ \fIclass_part_initialize\fP
+.br
+ \fIget_values_hook\fP
+.br
+ \fIinitialize\fP
+.br
+ \fIinitialize_hook\fP
+.br
+ \fIset_values\fP
+.br
+ \fIset_values_hook\fP
+.br
+ \fIresources\fP
+.sp
+.LP
+In addition, for subclasses of
+Constraint,
+the following fields of the
+.PN ConstraintClassPart
+and
+.PN ConstraintClassExtensionRec
+structures are chained from the
+Constraint
+class down to the subclass:
+.ta 1i
+.br
+ \fIresources\fP
+.br
+ \fIinitialize\fP
+.br
+ \fIset_values\fP
+.br
+ \fIget_values_hook\fP
+.sp
+.LP
+With upward superclass chaining,
+the invocation of an operation first accesses the field from the widget
+class structure, then from the superclass structure,
+and so on up the class chain to the
+Core,
+RectObj,
+and
+Object
+class structures.
+The subclass-to-superclass fields are
+.sp
+.ta 1i
+.br
+ \fIdestroy\fP
+.br
+ \fIactions\fP
+.sp
+.LP
+For subclasses of
+Constraint,
+the following field of
+.PN ConstraintClassPart
+is chained from the subclass up to the
+Constraint class:
+.sp
+.ta 1i
+.br
+ \fIdestroy\fP
+
+.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 or link time.
+In some cases, however,
+a class may need to register type converters or perform other sorts of
+once-only runtime 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 \*(xI.
+A class initialization procedure pointer is of type
+.PN XtProc :
+.IN "class_initialize procedure" "" "@DEF@"
+.IN "XtProc" "" "@DEF@"
+.LP
+.sM
+.FD 0
+typedef void (*XtProc)(void);
+.FN
+.LP
+.eM
+A widget class indicates that it has no class initialization procedure by
+specifying NULL in the \fIclass_initialize\fP field.
+.LP
+In addition to the class initialization that is done exactly once,
+some classes perform initialization for fields in their parts
+of the class record.
+These are performed not just for the particular class,
+but for subclasses as well, and are
+done in the class's class part initialization procedure,
+a pointer to which is stored in the \fIclass_part_initialize\fP field.
+The class_part_initialize procedure pointer is of type
+.PN XtWidgetClassProc .
+.IN "XtWidgetClassProc" "" "@DEF@"
+.LP
+.sM
+.FD 0
+typedef void (*XtWidgetClassProc)(WidgetClass);
+.br
+ WidgetClass \fIwidget_class\fP;
+.FN
+.IP \fIwidget_class\fP 1i
+Points to the class structure for the class being initialized.
+.LP
+.eM
+During class initialization,
+the class part initialization procedures 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
+Core,
+Composite,
+A, and B, the class record for C first is passed to
+Core 's
+class_part_initialize procedure.
+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, Composite's
+class_part_initialize procedure is called to initialize the
+composite part of C's class record.
+Finally, the class_part_initialize procedures for A, B, and C, in that 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 \fIclass_part_initialize\fP field.
+.LP
+All widget classes, whether they have a class initialization procedure or not,
+must start with their \fIclass_inited\fP 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 \fIclass_inited\fP 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 \fIclass_inited\fP field to a nonzero value.
+After the one-time initialization,
+a class structure is constant.
+.LP
+The following example provides the class initialization procedure for a Label class.
+.LP
+.Ds
+.TA .5i 2i
+.ta .5i 2i
+static void ClassInitialize()
+{
+ XtSetTypeConverter(XtRString, XtRJustify, CvtStringToJustify,
+ NULL, 0, XtCacheNone, NULL);
+}
+.De
+
+.NH 3
+Initializing a Widget Class
+.XS
+\fB\*(SN Initializing a Widget Class\fP
+.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@"
+.LP
+.sM
+.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
+.eM
+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
+expose
+.IP
+realize
+.IP
+insert_child
+.IP
+delete_child
+.IP
+geometry_manager
+.IP
+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 chained operations declared in Core
+and Constraint
+records are never inherited.
+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, called the inheritance constant,
+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,
+.PN CompositeP.h
+contains these definitions:
+.LP
+.Ds
+.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
+Composite's class_part_initialize procedure begins as follows:
+.LP
+.Ds
+.TA .2i 1.5i 3i
+.ta .2i 1.5i 3i
+static void CompositeClassPartInitialize(widgetClass)
+ WidgetClass widgetClass;
+{
+ 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
+Nonprocedure fields may be inherited in the same manner as procedure
+fields. The class may declare any reserved value it wishes for
+the inheritance constant for its new fields. The following inheritance
+constants are defined:
+.LP
+For Object:
+.IP
+.PN XtInheritAllocate
+.IP
+.PN XtInheritDeallocate
+.LP
+For Core:
+.IP
+.PN XtInheritRealize
+.IP
+.PN XtInheritResize
+.IP
+.PN XtInheritExpose
+.IP
+.PN XtInheritSetValuesAlmost
+.IP
+.PN XtInheritAcceptFocus
+.IP
+.PN XtInheritQueryGeometry
+.IP
+.PN XtInheritTranslations
+.IP
+.PN XtInheritDisplayAccelerator
+.LP
+For Composite:
+.IP
+.PN XtInheritGeometryManager
+.IP
+.PN XtInheritChangeManaged
+.IP
+.PN XtInheritInsertChild
+.IP
+.PN XtInheritDeleteChild
+.LP
+For Shell:
+.IP
+.PN XtInheritRootGeometryManager
+
+.NH 3
+Invocation of Superclass Operations
+.XS
+\*(SN Invocation of Superclass Operations
+.XE
+.LP
+A widget sometimes needs to call a superclass operation
+that is not chained.
+For example,
+a widget's expose procedure might call its superclass's \fIexpose\fP
+and then perform a little more work on its own.
+For example, a Composite
+class with predefined managed children can implement insert_child
+by first calling its superclass's \fIinsert_child\fP
+.IN "insert_child procedure"
+and then calling
+.PN XtManageChild
+to add the child to the managed set.
+.LP
+.NT
+A class method should not use
+.PN XtSuperclass
+but should instead call the class method of its own specific superclass
+directly through the superclass record.
+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
+class whose implementation is being referenced.
+.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 structure
+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
+Composite,
+Constraint,
+and
+Shell
+classes, subclasses can provide values for these fields by setting the
+\fIextension\fP pointer for the appropriate part in their class structure to
+point to a statically declared extension record containing the
+additional fields.
+Setting the \fIextension\fP field is never mandatory; code that uses fields
+in the extension record must always check the \fIextension\fP 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 \fIextension\fP 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
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+struct {
+ XtPointer next_extension;
+ XrmQuark record_type;
+ long version;
+ Cardinal record_size;
+};
+.De
+.IP \fInext_extension\fP 1.25i
+Specifies the next record in the list, or NULL.
+.IP \fIrecord_type\fP 1.25i
+Specifies the particular structure declaration to which
+each extension record instance conforms.
+.IP \fIversion\fP 1.25i
+Specifies a version id symbolic constant supplied by
+the definer of the structure.
+.IP \fIrecord_size\fP 1.25i
+Specifies the total number of bytes allocated for the
+extension record.
+.LP
+.eM
+The \fIrecord_type\fP 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. The
+\fIrecord_type\fP field 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 \fIversion\fP field is an owner-defined constant that may be used to
+identify binary files that have been compiled with alternate
+definitions of the remainder 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.
+The \fIrecord_size\fP field value includes the four common header fields and
+should normally be initialized with
+.PN sizeof ().
+.LP
+Any value stored in the class part extension fields of
+.PN CompositeClassPart ,
+.PN ConstraintClassPart ,
+or
+.PN ShellClassPart
+must point to an extension record conforming to this definition.
+.LP
+The \*(xI provide a utility function for widget writers to locate a
+particular class extension record in a linked list, given a widget class
+and the offset of the \fIextension\fP field in the class record.
+.LP
+To locate a class extension record, use
+.PN XtGetClassExtension .
+.IN "XtGetClassExtension" "" "@DEF@"
+.LP
+.sM
+.FD 0
+XtPointer XtGetClassExtension(\fIobject_class\fP, \fIbyte_offset\fP, \
+\fItype\fP, \fIversion\fP, \fIrecord_size\fP)
+.br
+ WidgetClass \fIobject_class\fP;
+.br
+ Cardinal \fIbyte_offset\fP;
+.br
+ XrmQuark \fItype\fP;
+.br
+ long \fIversion\fP;
+.br
+ Cardinal \fIrecord_size\fP;
+.FN
+.IP \fIobject_class\fP 1i
+Specifies the object class containing the extension list to be searched.
+.IP \fIbyte_offset\fP 1i
+Specifies the offset in bytes from the base of the
+class record of the extension field to be searched.
+.IP \fItype\fP 1i
+Specifies the record_type of the class extension to be located.
+.IP \fIversion\fP 1i
+Specifies the minimum acceptable version of the class
+extension required for a match.
+.IP \fIrecord_size\fP 1i
+Specifies the minimum acceptable length of the class
+extension record required for a match, or 0.
+.LP
+.eM
+The list of extension records at the specified offset in the specified
+object class will be searched for a match on the specified type,
+a version greater than or equal to the specified version, and a record
+size greater than or equal the specified record_size if it is nonzero.
+.PN XtGetClassExtension
+returns a pointer to a matching extension record or NULL if no match
+is found. The returned extension record must not be modified or
+freed by the caller if the caller is not the extension owner.
+.bp