home *** CD-ROM | disk | FTP | other *** search
Text File | 1991-08-27 | 59.8 KB | 2,307 lines |
- .\" $XConsortium: CH01,v 1.7 91/08/27 09:59:12 swick Exp $
- .\"
- .\" Copyright 1985, 1986, 1987, 1988, 1991
- .\" Massachusetts Institute of Technology, Cambridge, Massachusetts,
- .\" and 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
- .\" M.I.T. or Digital not be used in in advertising or publicity pertaining
- .\" to distribution of the software without specific, written prior permission.
- .\" M.I.T and 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
- .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 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 Intrinsica 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 \fIwidget or object\fP.
-
- .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 which
- 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,
- border widths, and so on) 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.
- .bp
-
- .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@"
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- 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
- 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" "" "@DEF@"
- .IN "WidgetClass" "" "@DEF@"
- .IN "CoreWidgetClass" "" "@DEF@"
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct {
- CoreClassPart core_class;
- } WidgetClassRec, *WidgetClass, CoreClassRec, *CoreWidgetClass;
- .De
- .LP
- 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
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- extern WidgetClassRec widgetClassRec;
- #define coreClassRec widgetClassRec
- .De
- .LP
- In
- .PN Intrinsic.h :
- .LP
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- 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.
- 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
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct _WidgetClassRec *WidgetClass, *CoreWidgetClass;
- .De
-
- .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@"
- .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 Setcion 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
- 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@"
- .sp
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct {
- CorePart core;
- } WidgetRec, *Widget, CoreRec, *CoreWidget;
- .De
- .LP
- 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
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct _WidgetRec *Widget, *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 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 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@"
- .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
- 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@"
- .sp
- .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 Chapter 3
- } CompositeClassExtensionRec, *CompositeClassExtension;
- .De
- .LP
- Composite
- classes have the Composite class fields immediately following the
- Core class 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 single occurrences of the class record and pointer for creating
- instances of Composite are
- .LP
- In
- .PN IntrinsicP.h :
- .LP
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- extern CompositeClassRec compositeClassRec;
- .De
- .LP
- In
- .PN Intrinsic.h :
- .LP
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- 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 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
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct _CompositeClassRec *CompositeWidgetClass;
- .De
-
- .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@"
- .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
- Composite
- widgets have the Composite instance fields immediately following the Core
- instance fields.
- .LP
- .IN "CompositeWidget" "" "@DEF@"
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct {
- CorePart core;
- CompositePart composite;
- } CompositeRec, *CompositeWidget;
- .De
- .LP
- .PN Intrinsic.h
- uses an incomplete structure definition to ensure that the
- compiler catches attempts to access private data.
- .LP
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct _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
- 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@"
- .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
- The extension record defined for
- .PN ConstraintClassPart
- with \fIrecord_type\fP 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 9.7.1
- } ConstraintClassExtensionRec, *ConstraintClassExtension;
- .De
- .LP
- Constraint
- classes have the Constraint class fields immediately following the
- Composite class fields.
- .LP
- .IN "ConstraintWidgetClass" "" "@DEF@"
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct _ConstraintClassRec {
- CoreClassPart core_class;
- CompositeClassPart composite_class;
- ConstraintClassPart constraint_class;
- } ConstraintClassRec, *ConstraintWidgetClass;
- .De
- .LP
- The single occurrences of the class record and pointer for creating
- instances of Constraint are
- .LP
- In
- .PN IntrinsicP.h :
- .LP
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- extern ConstraintClassRec constraintClassRec;
- .De
- .LP
- In
- .PN Intrinsic.h :
- .LP
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- 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
- 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
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct _ConstraintClassRec *ConstraintWidgetClass;
- .De
-
- .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@"
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct { int empty; } ConstraintPart;
- .De
- .LP
- Constraint
- widgets have the Constraint instance fields immediately following the
- Composite instance fields.
- .LP
- .IN "ConstraintWidget" "" "@DEF@"
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct {
- CorePart core;
- CompositePart composite;
- ConstraintPart constraint;
- } ConstraintRec, *ConstraintWidget;
- .De
- .LP
- .PN Intrinsic.h
- uses an incomplete structure definition to ensure that the
- compiler catches attempts to access private data.
- .LP
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct _ConstraintRec *ConstraintWidget;
- .De
-
- .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 lower case
- and uses underscores (_) for compound words (for example, background_pixmap).
- Type and procedure names start with upper case 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 upper case 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 upper case
- (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;
- {
- 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. \*(oI
- .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. \*(oI
- .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 to which a widget belongs, use
- .PN XtIsSubclass .
- .IN "XtIsSubclass" "" "@DEF@"
- .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
- 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
- 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 these macros and functions have the same argument description.
- .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
- 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@"
- .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
- 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
- .sp
- In Composite widget classes: \fIgeometry_manager\fP
- .br
- \fIchange_managed\fP
- .br
- \fIinsert_child\fP
- .br
- \fIdelete_child\fP
- .br
- \fIaccepts_objects\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
- .FD 0
- typedef void (*XtProc)(void);
- .FN
- .LP
- 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@"
- .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
- 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@"
- .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
- 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 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
- .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 \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.
- .bp
-