diff options
Diffstat (limited to 'specs/CH01')
| -rw-r--r-- | specs/CH01 | 2471 |
1 files changed, 2471 insertions, 0 deletions
diff --git a/specs/CH01 b/specs/CH01 new file mode 100644 index 0000000..78f128b --- /dev/null +++ b/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 |