From 5f8448ef6b85a9ff72c5af4cec99183c8bb60dc6 Mon Sep 17 00:00:00 2001 From: marha Date: Tue, 10 Apr 2012 14:58:33 +0200 Subject: Updated following packages: bigreqsproto-1.1.2 fontsproto-2.1.2 recordproto-1.14.2 scrnsaverproto-1.2.2 xcmiscproto-1.2.2 libXt-1.1.3 xhost-1.0.5 kbproto-1.0.6 libXrender-0.9.7 libxkbfile-1.0.8 freetype-2.4.9 libXaw-1.0.10 libXpm-3.5.10 xproto-7.0.23 --- libXt/specs/CH01.xml | 2798 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2798 insertions(+) create mode 100644 libXt/specs/CH01.xml (limited to 'libXt/specs/CH01.xml') diff --git a/libXt/specs/CH01.xml b/libXt/specs/CH01.xml new file mode 100644 index 000000000..df2f96f81 --- /dev/null +++ b/libXt/specs/CH01.xml @@ -0,0 +1,2798 @@ + +Intrinsics and Widgets + +The Intrinsics are a programming library tailored to the special requirements +of user interface construction within a network window system, +specifically the X Window System. +The Intrinsics and a widget set make up an X Toolkit. + + +Intrinsics + +The Intrinsics 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. + + + +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. + + + +When the Intrinsics were first conceived, the root of the object +hierarchy was a widget class named +Core. +In Release 4 of the +Intrinsics, three nonwidget superclasses were added above Core. +These superclasses are described in . +The name of the class +now at the root of the Intrinsics class hierarchy is +Object. +The remainder of this +specification refers uniformly to widgets and Core +as if they were the +base class for all Intrinsics operations. The argument descriptions +for each Intrinsics procedure and +describe which operations +are defined for the nonwidget superclasses of Core. The reader may +determine by context whether a specific reference to widget +actually means ``widget'' or ``object.'' + + + + +Languages + +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 client refers to +any module, widget, or application that calls an Intrinsics procedure. + + + +Applications that use the Intrinsics mechanisms +must include the header files +<X11/Intrinsic.h> +and +<X11/StringDefs.h>, +or their equivalent, +and they may also include +<X11/Xatoms.h> +and +<X11/Shell.h>. +In addition, widget implementations should include +<X11/IntrinsicP.h> +instead of +<X11/Intrinsic.h>. + + + +The applications must also include the additional header files for +each widget class that they are to use (for example, +<X11/Xaw/Label.h> +or +<X11/Xaw/Scrollbar.h>). +On a POSIX-based system, +the Intrinsics object library file is named +libXt.a +and is usually referenced as \-lXt when linking the application. + + + + +Procedures and Macros + +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. + + + +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: +, +, +, +, +, +and +. + + + + +Widgets + +The fundamental abstraction and data type of the X Toolkit 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. + + + +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 + + + +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 +The predefined widget classes adhere to these conventions. + + + +A widget instance is composed of two parts: + + + + +A data structure which contains instance-specific values. + + + + +A class structure which contains information that is applicable to +all widgets of that class. + + + + +Much of the input/output of a widget (for example, fonts, colors, sizes, +or border widths) is customizable by users. + + + +This chapter discusses the base widget classes, +Core, Composite, and Constraint, and +ends with a discussion of widget classing. + + +Core Widgets + +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 +CoreClassPart +and +CorePart +structures. + + +CoreClassPart Structure + +All widget classes contain the fields defined in the +CoreClassPart +structure. + + +typedef struct { + WidgetClass superclass; See + String class_name; See + Cardinal widget_size; See + XtProc class_initialize; See + XtWidgetClassProc class_part_initialize; See + XtEnum class_inited; See + XtInitProc initialize; See + XtArgsProc initialize_hook; See + XtRealizeProc realize; See + XtActionList actions; See + Cardinal num_actions; See + XtResourceList resources; See + Cardinal num_resources; See + XrmClass xrm_class; Private to resource manager + Boolean compress_motion; See + XtEnum compress_exposure; See + Boolean compress_enterleave; See + Boolean visible_interest; See + XtWidgetProc destroy; See + XtWidgetProc resize; See + XtExposeProc expose; See + XtSetValuesFunc set_values; See + XtArgsFunc set_values_hook; See + XtAlmostProc set_values_almost; See + XtArgsProc get_values_hook; See + XtAcceptFocusProc accept_focus; See + XtVersionType version; See + XtPointer callback_private; Private to callbacks + String tm_table; See + XtGeometryHandler query_geometry; See + XtStringProc display_accelerator; See + XtPointer extension; See +} CoreClassPart; + + +All widget classes have the Core class fields as their first component. +The prototypical +WidgetClass +and +CoreWidgetClass +are defined with only this set of fields. + + +typedef struct { + CoreClassPart core_class; +} WidgetClassRec, *WidgetClass, CoreClassRec, *CoreWidgetClass; + + +Various routines can cast widget class pointers, as needed, +to specific widget class types. + + + +The single occurrences of the class record and pointer for +creating instances of Core are + + + +In +IntrinsicP.h: + + +extern WidgetClassRec widgetClassRec; +#define coreClassRec widgetClassRec + + +In +Intrinsic.h: + + +extern WidgetClass widgetClass, coreWidgetClass; + + +The opaque types +Widget +and +WidgetClass +and the opaque variable +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 Intrinsics use +incomplete structure definitions in +Intrinsic.h: + + +typedef struct _WidgetClassRec *WidgetClass, *CoreWidgetClass; + + + +CorePart Structure + +All widget instances contain the fields defined in the +CorePart +structure. + + +typedef struct _CorePart { + Widget self; Described below + WidgetClass widget_class; See + Widget parent; See + Boolean being_destroyed; See + XtCallbackList destroy_callbacks; + XtPointer constraints; See + Position x; See + Position y; See + Dimension width; See + Dimension height; See + Dimension border_width; See + Boolean managed; See + Boolean sensitive; See + Boolean ancestor_sensitive; See + XtTranslations accelerators; See + Pixel border_pixel; See + Pixmap border_pixmap; See + WidgetList popup_list; See + Cardinal num_popups; See + String name; See + Screen *screen; See + Colormap colormap; See + Window window; See + Cardinal depth; See + Pixel background_pixel; See + Pixmap background_pixmap; See + Boolean visible; See + Boolean mapped_when_managed; See +} CorePart; + + +All widget instances have the Core fields as their first component. +The prototypical type +Widget +is defined with only this set of fields. + + +typedef struct { + CorePart core; +} WidgetRec, *Widget, CoreRec, *CoreWidget; + + +Various routines can cast widget pointers, as needed, +to specific widget types. + + + +In order to make these types opaque and ensure that the compiler +does not allow applications to access private data, the Intrinsics use +incomplete structure definitions in +Intrinsic.h. + + +typedef struct _WidgetRec *Widget, *CoreWidget; + + + +Core Resources + +The resource names, classes, and representation types specified in the +coreClassRec +resource list are + + + + + + + + + + + Name + Class + Representation + + + + + 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 + + + + + +Additional resources are defined for all widgets via the +objectClassRec +and +rectObjClassRec +resource lists; see and for details. + + + +CorePart Default Values + +The default values for the Core fields, which are filled in by the Intrinsics, +from the resource lists, and by the initialize procedures, are + + + + + + + + + Field + Default Value + + + + + self + Address of the widget structure (may not be changed). + + + widget_class + widget_class argument to + + (may not be changed). + + + parent + parent argument to + + (may not be changed). + + + being_destroyed + Parent's being_destroyed value. + + + destroy_callbacks + NULL + + + constraints + NULL + + + x + 0 + + + y + 0 + + + width + 0 + + + height + 0 + + + border_width + 1 + + + managed + False + + + sensitive + True + + + ancestor_sensitive + logical AND of parent's sensitive and + ancestor_sensitive values. + + + accelerators + NULL + + + border_pixel + XtDefaultForeground + + + border_pixmap + XtUnspecifiedPixmap + + + popup_list + NULL + + + num_popups + 0 + + + name + name argument to + + (may not be changed). + + + screen + Parent's screen; top-level widget gets screen from display specifier + (may not be changed). + + + colormap + Parent's colormap value. + + + window + NULL + + + depth + Parent's depth; top-level widget gets root window depth. + + + background_pixel + XtDefaultBackground + + + background_pixmap + XtUnspecifiedPixmap + + + visible + True + + + mapped_when_managed + True + + + + + +XtUnspecifiedPixmap +is a symbolic constant guaranteed to be unequal to +any valid Pixmap id, +None, +and +ParentRelative. + + + + + +Composite Widgets + +The Composite +widget class is a subclass of the +Core +widget class (see ). +Composite widgets are intended to be containers for other widgets. +The additional data used by composite widgets are defined by the +CompositeClassPart +and +CompositePart +structures. + + +CompositeClassPart Structure + +In addition to the +Core +class fields, +widgets of the Composite class have the following class fields. + + +typedef struct { + XtGeometryHandler geometry_manager; See + XtWidgetProc change_managed; See + XtWidgetProc insert_child; See + XtWidgetProc delete_child; See + XtPointer extension; See +} CompositeClassPart; + + +The extension record defined for +CompositeClassPart +with record_type +equal to +NULLQUARK +is +CompositeClassExtensionRec. + + +typedef struct { + XtPointer next_extension; See + XrmQuark record_type; See + long version; See + Cardinal record_size; See + Boolean accepts_objects; See + Boolean allows_change_managed_set; See +} CompositeClassExtensionRec, *CompositeClassExtension; + + +Composite +classes have the Composite class fields immediately following the +Core class fields. + + +typedef struct { + CoreClassPart core_class; + CompositeClassPart composite_class; +} CompositeClassRec, *CompositeWidgetClass; + + +The single occurrences of the class record and pointer for creating +instances of Composite are + + + +In +IntrinsicP.h: + + +extern CompositeClassRec compositeClassRec; + + +In +Intrinsic.h: + + +extern WidgetClass compositeWidgetClass; + + +The opaque types +CompositeWidget +and +CompositeWidgetClass +and the opaque variable +compositeWidgetClass +are defined for generic operations on widgets whose class +is Composite or a subclass of Composite. +The symbolic constant for the +CompositeClassExtension +version identifier is +XtCompositeExtensionVersion +(see ). +Intrinsic.h +uses an incomplete structure +definition to ensure that the compiler catches attempts to access +private data. + + +typedef struct _CompositeClassRec *CompositeWidgetClass; + + + +CompositePart Structure + +In addition to the +Core instance +fields, +widgets of the Composite class have the following +instance fields defined in the +CompositePart +structure. + + +typedef struct { + WidgetList children; See + Cardinal num_children; See + Cardinal num_slots; See + XtOrderProc insert_position; See +} CompositePart; + + +Composite +widgets have the Composite instance fields immediately following the Core +instance fields. + + +typedef struct { + CorePart core; + CompositePart composite; +} CompositeRec, *CompositeWidget; + + +Intrinsic.h +uses an incomplete structure definition to ensure that the +compiler catches attempts to access private data. + + +typedef struct _CompositeRec *CompositeWidget; + + + +Composite Resources + +The resource names, classes, and representation types +that are specified in +the +compositeClassRec +resource list are + + + + + + + + + + + Name + Class + Representation + + + + + XtNchildren + XtCReadOnly + XtRWidgetList + + + XtNinsertPosition + XtCInsertPosition + XtRFunction + + + XtNnumChildren + XtCReadOnly + XtRCardinal + + + + + + + +CompositePart Default Values + +The default values for the Composite fields, +which are filled in from the +Composite +resource list and by the +Composite +initialize procedure, are + + + + + + + + + + + Field + Default Value + + + + + childrenNULL + + + num_children0 + + + num_slots0 + + + insert_positionInternal function to insert at end + + + + + + +The children, num_children, +and insert_position fields are declared +as resources; +XtNinsertPosition +is a settable resource, +XtNchildren +and +XtNnumChildren +may be read by any client but should only be modified by the composite +widget class procedures. + + + + + +Constraint Widgets + +The Constraint +widget class is a subclass of the +Composite +widget class (see ). 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 +ConstraintClassPart +and +ConstraintPart +structures. + + +ConstraintClassPart Structure + +In addition to the +Core +and +Composite +class fields, +widgets of the Constraint class +have the following class fields. + + +typedef struct { + XtResourceList resources; See + Cardinal num_resources; See + Cardinal constraint_size; See + XtInitProc initialize; See + XtWidgetProc destroy; See + XtSetValuesFunc set_values; See + XtPointer extension; See +} ConstraintClassPart; + + +The extension record defined for +ConstraintClassPart +with record_type equal to +NULLQUARK +is +ConstraintClassExtensionRec. + + +typedef struct { + XtPointer next_extension; See + XrmQuark record_type; See + long version; See + Cardinal record_size; See + XtArgsProc get_values_hook; See +} ConstraintClassExtensionRec, *ConstraintClassExtension; + + +Constraint +classes have the Constraint class fields immediately following the +Composite class fields. + + +typedef struct _ConstraintClassRec { + CoreClassPart core_class; + CompositeClassPart composite_class; + ConstraintClassPart constraint_class; +} ConstraintClassRec, *ConstraintWidgetClass; + + +The single occurrences of the class record and pointer for creating +instances of Constraint are + + + +In +IntrinsicP.h: + + +extern ConstraintClassRec constraintClassRec; + + +In +Intrinsic.h: + + +extern WidgetClass constraintWidgetClass; + + +The opaque types +ConstraintWidget +and +ConstraintWidgetClass +and the opaque variable +constraintWidgetClass +are defined for generic operations on widgets +whose class is Constraint or a subclass +of Constraint. +The symbolic constant for the +ConstraintClassExtension +version identifier is +XtConstraintExtensionVersion +(see ). +Intrinsic.h +uses an incomplete structure definition to ensure that the +compiler catches attempts to access private data. + + +typedef struct _ConstraintClassRec *ConstraintWidgetClass; + + + +ConstraintPart Structure + +In addition to the +Core +and +Composite instance +fields, +widgets of the Constraint class have the following unused +instance fields defined in the +ConstraintPart +structure + + +typedef struct { + int empty; +} ConstraintPart; + + +Constraint +widgets have the Constraint instance fields immediately following the +Composite instance fields. + + +typedef struct { + CorePart core; + CompositePart composite; + ConstraintPart constraint; +} ConstraintRec, *ConstraintWidget; + + +Intrinsic.h +uses an incomplete structure definition to ensure that the +compiler catches attempts to access private data. + + +typedef struct _ConstraintRec *ConstraintWidget; + + + +Constraint Resources + +The +constraintClassRec +core_class and constraint_class resources fields are NULL, +and the num_resources fields are zero; +no additional resources beyond those declared by +the superclasses +are defined for +Constraint. + + + + + + +Implementation-Specific Types + +To increase the portability of widget and application source code +between different system environments, the Intrinsics define several +types whose precise representation is explicitly dependent upon, +and chosen by, each individual implementation of the Intrinsics. + + + +These implementation-defined types are + + + + + Boolean + + + +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 +True. + + + + + + + Cardinal + + + +An unsigned integer datum with a minimum range of [0..2^16-1]. + + + + + + + Dimension + + + +An unsigned integer datum with a minimum range of [0..2^16-1]. + + + + + + + Position + + + +A signed integer datum with a minimum range of [-2^15..2^15-1]. + + + + + + + XtPointer + + + +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 +XtPointer +and back again and the result will +compare equal to the original value. In ANSI C +environments it is expected that +XtPointer +will be +defined as void*. + + + + + + + XtArgVal + + + +A datum large enough to contain an +XtPointer, +Cardinal, +Dimension, +or +Position +value. + + + + + + + XtEnum + + + +An integer datum large enough to encode at least 128 distinct +values, two of which are the symbolic values +True +and +False. +The symbolic values +TRUE +and +FALSE +are +also defined to be equal to +True +and +False, +respectively. + + + + + + +In addition to these specific types, the precise order of the +fields within the structure declarations for any of the instance +part records +ObjectPart, +RectObjPart, +CorePart, +CompositePart, +ShellPart, +WMShellPart, +TopLevelShellPart, +and +ApplicationShellPart +is implementation-defined. These +structures may also have additional private +fields internal to the implementation. +The +ObjectPart, +RectObjPart, +and +CorePart +structures must be defined so that any member with the same name +appears at the same offset in +ObjectRec, +RectObjRec, +and +CoreRec +( WidgetRec ). +No other relations between the offsets of any two +fields may be assumed. + + + + +Widget Classing + +The widget_class field of a widget points to its widget class structure, +which contains information that is constant across all widgets of that class. +As a consequence, +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. + + + +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 +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). + + + +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. + + + +To make good use of subclassing, +widget declarations and naming conventions are highly stylized. +A widget consists of three files: + + + + +A public .h file, used by client widgets or applications. + + + + +A private .h file, used by widgets whose classes +are subclasses of the widget class. + + + + +A .c file, which implements the widget. + + + + +Widget Naming Conventions + +The Intrinsics 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: + + + + +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, +ArgList +or +XtSetValues ). + + + + +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 background_pixmap field has the corresponding identifier +XtNbackgroundPixmap, +which is defined as the string ``backgroundPixmap''. +Many predefined names are listed in +<X11/StringDefs.h>. +Before you invent a new name, +you should make sure there is not already a name that you can use. + + + + +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 +<X11/StringDefs.h>. + + + + +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 +<X11/StringDefs.h>. + + + + +New widget classes start with a capital and use uppercase for compound +words. +Given a new class name AbcXyz, you should derive several names: + + + + + + +Additional widget instance structure part name AbcXyzPart. + + + + +Complete widget instance structure names AbcXyzRec and _AbcXyzRec. + + + + +Widget instance structure pointer type name AbcXyzWidget. + + + + +Additional class structure part name AbcXyzClassPart. + + + + +Complete class structure names AbcXyzClassRec and _AbcXyzClassRec. + + + + +Class structure pointer type name AbcXyzWidgetClass. + + + + +Class structure variable abcXyzClassRec. + + + + +Class structure pointer variable abcXyzWidgetClass. + + + + + + +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''). + + + + +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 +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. + + + + +Widget Subclassing in Public .h Files + +The public .h file for a widget class is imported by clients +and contains + + + + +A reference to the public .h file for the superclass. + + + + +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. + + + + +Type declarations for any new resource data types defined by the class. + + + + +The class record pointer variable used to create widget instances. + + + + +The C type that corresponds to widget instances of this class. + + + + +Entry points for new class methods. + + + + +For example, the following is the public .h file for a possible +implementation of a Label widget: + + +#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 + + +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. + + + +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 +Constraint.h. + + + + +Widget Subclassing in Private .h Files + +The private .h file for a widget is imported by widget classes that are +subclasses of the widget and contains + + + + +A reference to the public .h file for the class. + + + + +A reference to the private .h file for the superclass. + + + + +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. + + + + +A structure part definition for +the new fields that the widget instance adds to its superclass's +widget structure. + + + + +The complete widget instance structure definition for this widget. + + + + +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. + + + + +The complete +constraint +structure definition if the widget class is a subclass of +Constraint. + + + + +Type definitions for any new procedure types used by class methods +declared in the widget class part. + + + + +A structure part definition for +the new fields that this widget class adds to its superclass's widget class +structure. + + + + +The complete widget class structure definition for this widget. + + + + +The complete widget class extension structure definition +for this widget, if any. + + + + +The symbolic constant identifying the class extension version, if any. + + + + +The name of the global class structure variable containing the generic +class structure for this class. + + + + +An inherit constant for each new procedure in the widget class part structure. + + + + +For example, the following is the private .h file for a possible Label widget: + + +#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; + + +/* 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 + + +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 +ConstrainP.h. + + + + +Widget Subclassing in .c Files + +The .c file for a widget contains the structure initializer +for the class record variable, +which contains the following parts: + + + + +Class information (for example, superclass, class_name, +widget_size, +class_initialize, and class_inited). + + + + +Data constants (for example, resources and num_resources, +actions and num_actions, visible_interest, +compress_motion, +compress_exposure, and version). + + + + +Widget operations (for example, initialize, realize, destroy, +resize, expose, set_values, accept_focus, +and any new operations specific to +the widget). + + + + +The superclass field points to the superclass +global class +record, declared in the superclass private .h file. +For direct subclasses of the generic core widget, +superclass should be initialized to the address of the +widgetClassRec +structure. +The superclass is used for class chaining operations and for +inheriting or enveloping a superclass's operations +(see , +, and +. + + + +The class_name 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. + + + +The widget_size field is the size of the corresponding widget +instance structure +(not the size of the class structure). + + + +The version field indicates the toolkit +implementation version number and is used for +runtime consistency checking of the X Toolkit and widgets in an application. +Widget writers must set it to the +implementation-defined symbolic value +XtVersion +in the widget class structure initialization. +Those widget writers who believe that their widget binaries are compatible +with other implementations of the Intrinsics can put the special value +XtVersionDontCheck +in the version field to disable version checking for those widgets. +If a widget needs to compile alternative code for different +revisions of the Intrinsics interface definition, it may use the symbol +XtSpecificationRelease, +as described in . +Use of +XtVersion +allows the Intrinsics implementation to recognize widget binaries +that were compiled with older implementations. + + + +The extension 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. + + + +All other fields are described in their respective sections. + + + +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 . + + +/* 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(); + . + . + . + + +/* 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 */ + . + . + . + + + + +Widget Class and Superclass Look Up + +To obtain the class of a widget, use +. + + + + + + + WidgetClass XtClass + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + + +The + +function returns a pointer to the widget's class structure. + + + +To obtain the superclass of a widget, use +XtSuperclass. + + + + + + WidgetClass XtSuperClass + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + + +The +XtSuperclass +function returns a pointer to the widget's superclass class structure. + + + + +Widget Subclass Verification + +To check the subclass to which a widget belongs, use +. + + + + + Boolean XtIsSubclass + Widget w + WidgetClass widget_class + + + + + + + w + + + +Specifies the widget or object instance whose class is to be checked. Must be of class Object or any subclass thereof. + + + + + + widget_class + + + +Specifies the widget class for which to test. Must be objectClass or any subclass thereof. + + + + + + + +The + +function returns +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 + +to find out if a widget belongs to the desired class of objects. + + + +To test if a given widget belongs to a subclass of an Intrinsics-defined +class, the Intrinsics define macros or functions equivalent to + +for each of the built-in classes. These procedures are +XtIsObject, +XtIsRectObj, +XtIsWidget, +XtIsComposite, +XtIsConstraint, +XtIsShell, +XtIsOverrideShell, +XtIsWMShell, +XtIsVendorShell, +XtIsTransientShell, +XtIsTopLevelShell, +XtIsApplicationShell, +and +XtIsSessionShell. + + + +All these macros and functions have the same argument description. + + + + + Boolean XtIs + Widget w + + + + + + + w + + + +Specifies the widget or object instance whose class is to be checked. Must be of class Object or any subclass thereof. + + + + + + +These procedures may be faster than calling + +directly for the built-in classes. + + + +To check a widget's class +and to generate a debugging error message, use +, +defined in +<X11/IntrinsicP.h>: + + + + + void XtCheckSubclass + Widget w + WidgetClass widget_class + String message + + + + + + + w + + + +Specifies the widget or object whose class is to be checked. Must be of class Object or any subclass thereof. + + + + + + widget_class + + + +Specifies the widget class for which to test. Must be objectClass or any subclass thereof. + + + + + + message + + + +Specifies the message to be used. + + + + + + +The + +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, + +constructs an error message from the supplied message, +the widget's actual class, and the expected class and calls +. + +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. + + + + +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. + + + + +Superclass Chaining + +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 Intrinsics 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 + +In all widget classes: class_name + class_initialize + widget_size + realize + visible_interest + resize + expose + accept_focus + compress_motion + compress_exposure + compress_enterleave + set_values_almost + tm_table + version + allocate + deallocate + +In Composite widget classes: geometry_manager + change_managed + insert_child + delete_child + accepts_objects + allows_change_managed_set + +In Constraint widget classes: constraint_size + +In Shell widget classes: root_geometry_manager + + + +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 + + + class_part_initialize + get_values_hook + initialize + initialize_hook + set_values + set_values_hook + resources + + + +In addition, for subclasses of +Constraint, +the following fields of the +ConstraintClassPart +and +ConstraintClassExtensionRec +structures are chained from the +Constraint +class down to the subclass: + + + resources + initialize + set_values + get_values_hook + + + +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 + + + destroy + actions + + + +For subclasses of +Constraint, +the following field of +ConstraintClassPart +is chained from the subclass up to the +Constraint class: + destroy + + + + +Class Initialization: class_initialize and class_part_initialize Procedures + +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. + + + +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 Intrinsics. +A class initialization procedure pointer is of type +XtProc: + + + +typedef void (*XtProc)(void); + + +A widget class indicates that it has no class initialization procedure by +specifying NULL in the class_initialize field. + + + +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 class_part_initialize field. +The class_part_initialize procedure pointer is of type +XtWidgetClassProc. + + + + + void (*XtWidgetClassProc)(WidgetClass) + WidgetClass widget_class + + + + + + + widget_class + + + +Points to the class structure for the class being initialized. + + + + + +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 +Classes that do not define any new class fields +or that need no extra processing for them can specify NULL +in the class_part_initialize field. + + + +All widget classes, whether they have a class initialization procedure or not, +must start with their class_inited field +False. + + + +The first time a widget of a class is created, + +ensures that the widget class and all superclasses are initialized, in +superclass-to-subclass order, by checking each class_inited field and, +if it is +False, +by calling the class_initialize and the class_part_initialize procedures +for the class and all its superclasses. +The Intrinsics then set the class_inited field to a nonzero value. +After the one-time initialization, +a class structure is constant. + + + +The following example provides the class initialization procedure for a Label class. + + +static void ClassInitialize() +{ + XtSetTypeConverter(XtRString, XtRJustify, CvtStringToJustify, + NULL, 0, XtCacheNone, NULL); +} + + + + +Initializing a Widget Class + +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 +. + + + + + void XtInitializeWidgetClass + WidgetClass object_class + + + + + + + object_class + + + +Specifies the object class to initialize. May be +objectClass +or any subclass thereof. + + + + + + +If the specified widget class is already initialized, + +returns immediately. + + + +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 + +is called +(see ). + + + + +Inheritance of Superclass Operations + +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 + + + + +expose + + + + +realize + + + + +insert_child + + + + +delete_child + + + + +geometry_manager + + + + +set_values_almost + + + + + +To inherit an operation xyz, +specify the constant +XtInherit Xyz +in your class record. + + + +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. + + + +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 Intrinsics internal value +_XtInherit +cast to the appropriate type. +_XtInherit +is a procedure that issues an error message if it is actually called. + + + +For example, +CompositeP.h +contains these definitions: + + +#define XtInheritGeometryManager ((XtGeometryHandler) _XtInherit) +#define XtInheritChangeManaged ((XtWidgetProc) _XtInherit) +#define XtInheritInsertChild ((XtArgsProc) _XtInherit) +#define XtInheritDeleteChild ((XtWidgetProc) _XtInherit) + + +Composite's class_part_initialize procedure begins as follows: + + +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; + } + . + . + . + + +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: + + + +For Object: + + + + +XtInheritAllocate + + + + +XtInheritDeallocate + + + + +For Core: + + + + +XtInheritRealize + + + + +XtInheritResize + + + + +XtInheritExpose + + + + +XtInheritSetValuesAlmost + + + + +XtInheritAcceptFocus + + + + +XtInheritQueryGeometry + + + + +XtInheritTranslations + + + + +XtInheritDisplayAccelerator + + + + +For Composite: + + + + +XtInheritGeometryManager + + + + +XtInheritChangeManaged + + + + +XtInheritInsertChild + + + + +XtInheritDeleteChild + + + + +For Shell: + + + + +XtInheritRootGeometryManager + + + + + + +Invocation of Superclass Operations + +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 expose +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 insert_child +and then calling + +to add the child to the managed set. + + + + +A class method should not use +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. + + + +This technique is referred to as enveloping the superclass's operation. + + + + +Class Extension Records + +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. + + + +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 +extension pointer for the appropriate part in their class structure to +point to a statically declared extension record containing the +additional fields. +Setting the extension field is never mandatory; code that uses fields +in the extension record must always check the extension field and take +some appropriate default action if it is NULL. + + + +In order to permit multiple subclasses and libraries to chain extension +records from a single extension field, extension records should be +declared as a linked list, and each extension record definition should +contain the following four fields at the beginning of the structure +declaration: + + +struct { + XtPointer next_extension; + XrmQuark record_type; + long version; + Cardinal record_size; +}; + + + + + + next_extension + + + +Specifies the next record in the list, or NULL. + + + + + + record_type + + + +Specifies the particular structure declaration to which +each extension record instance conforms. + + + + + + version + + + +Specifies a version id symbolic constant supplied by +the definer of the structure. + + + + + + record_size + + + +Specifies the total number of bytes allocated for the +extension record. + + + + + + +The record_type field identifies the contents of the extension record +and is used by the definer of the record to locate its particular +extension record in the list. The +record_type field is normally assigned the +result of +XrmStringToQuark +for a registered string constant. The +Intrinsics reserve all record type strings beginning with the two +characters ``XT'' for future standard uses. The value +NULLQUARK +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. + + + +The version 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 record_size field value includes the four common header fields and +should normally be initialized with +sizeof (). + + + +Any value stored in the class part extension fields of +CompositeClassPart, +ConstraintClassPart, +or +ShellClassPart +must point to an extension record conforming to this definition. + + + +The Intrinsics 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 extension field in the class record. + + + +To locate a class extension record, use +. + + + + + XtPointer XtGetClassExtension + WidgetClass object_class + Cardinal byte_offset + XrmQuark type + long version + Cardinal record_size + + + + + + + object_class + + + +Specifies the object class containing the extension list to be searched. + + + + + + byte_offset + + + +Specifies the offset in bytes from the base of the +class record of the extension field to be searched. + + + + + + type + + + +Specifies the record_type of the class extension to be located. + + + + + + version + + + +Specifies the minimum acceptable version of the class +extension required for a match. + + + + + + record_size + + + +Specifies the minimum acceptable length of the class +extension record required for a match, or 0. + + + + + + +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. + +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. + + + + -- cgit v1.2.3