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