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/CH12.xml | 1166 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1166 insertions(+) create mode 100644 libXt/specs/CH12.xml (limited to 'libXt/specs/CH12.xml') diff --git a/libXt/specs/CH12.xml b/libXt/specs/CH12.xml new file mode 100644 index 000000000..3ae6542ab --- /dev/null +++ b/libXt/specs/CH12.xml @@ -0,0 +1,1166 @@ + +Nonwidget Objects + + +Although widget writers are free to treat +Core +as the base class of +the widget hierarchy, there are actually three classes above it. +These classes are +Object, +RectObj +(Rectangle Object), and (unnamed), +and members of these classes +are referred to generically as objects. By convention, the term +widget refers only to objects that are a subclass of +Core, +and the term nonwidget refers to objects that are not a subclass of +Core. +In the preceding portion of this specification, the interface +descriptions indicate explicitly whether the generic widget argument +is restricted to particular subclasses of Object. Sections 12.2.5, +12.3.5, and 12.5 summarize the permissible classes of the arguments to, and +return values from, each of the Intrinsics routines. + + +Data Structures + +In order not to conflict with previous widget code, the data +structures used by nonwidget objects do not follow all the same +conventions as those for widgets. In particular, the class records +are not composed of parts but instead are complete data structures +with filler for the widget fields they do not use. This +allows the static class initializers for existing widgets to remain +unchanged. + + + + +Object Objects + +The +Object +object contains the definitions of fields common to all +objects. It encapsulates the mechanisms for resource management. +All objects and widgets are members of subclasses of +Object, +which is defined by the +ObjectClassPart +and +ObjectPart +structures. + + +ObjectClassPart Structure + +The common fields for all object classes are defined in the +ObjectClassPart +structure. All fields have the same purpose, +function, and restrictions as the corresponding fields in +CoreClassPart; +fields whose +names are objn for some integer n are not +used for Object, +but exist to pad the data structure so that it matches Core's class +record. The class record initialization must fill all +objn fields with NULL or zero as appropriate to the type. + + +typedef struct _ObjectClassPart { + WidgetClass superclass; + String class_name; + Cardinal widget_size; + XtProc class_initialize; + XtWidgetClassProc class_part_initialize; + XtEnum class_inited; + XtInitProc initialize; + XtArgsProc initialize_hook; + XtProc obj1; + XtPointer obj2; + Cardinal obj3; + XtResourceList resources; + Cardinal num_resources; + XrmClass xrm_class; + Boolean obj4; + XtEnum obj5; + Boolean obj6; + Boolean obj7; + XtWidgetProc destroy; + XtProc obj8; + XtProc obj9; + XtSetValuesFunc set_values; + XtArgsFunc set_values_hook; + XtProc obj10; + XtArgsProc get_values_hook; + XtProc obj11; + XtVersionType version; + XtPointer callback_private; + String obj12; + XtProc obj13; + XtProc obj14; + XtPointer extension; +} ObjectClassPart; + + +The extension record defined for +ObjectClassPart +with a record_type equal to +NULLQUARK +is +ObjectClassExtensionRec. + + +typedef struct { + XtPointer next_extension; See + XrmQuark record_type; See + long version; See + Cardinal record_size; See + XtAllocateProc allocate; See . + XtDeallocateProc deallocate; See . +} ObjectClassExtensionRec, *ObjectClassExtension; + + +The prototypical +ObjectClass +consists of just the +ObjectClassPart. + + +typedef struct _ObjectClassRec { + ObjectClassPart object_class; +} ObjectClassRec, *ObjectClass; + + +The predefined class record and pointer for +ObjectClassRec +are + + + +In +IntrinsicP.h: + + +extern ObjectClassRec objectClassRec; + + +In +Intrinsic.h: + + +extern WidgetClass objectClass; + + +The opaque types +Object +and +ObjectClass +and the opaque variable +objectClass +are defined for generic actions on objects. +The symbolic constant for the +ObjectClassExtension +version identifier is +XtObjectExtensionVersion +(see ). +Intrinsic.h +uses an incomplete structure definition to ensure that the +compiler catches attempts to access private data: + + +typedef struct _ObjectClassRec* ObjectClass; + + + + + +ObjectPart Structure + +The common fields for all object instances are defined in the +ObjectPart +structure. All fields have the same meaning as the +corresponding fields in +CorePart. + + +typedef struct _ObjectPart { + Widget self; + WidgetClass widget_class; + Widget parent; + Boolean being_destroyed; + XtCallbackList destroy_callbacks; + XtPointer constraints; +} ObjectPart; + + +All object instances have the +Object +fields as their first component. The prototypical type +Object +is defined with only this set of fields. +Various routines can cast object pointers, as needed, to specific +object types. + + + +In +IntrinsicP.h: + + +typedef struct _ObjectRec { + ObjectPart object; +} ObjectRec, *Object; + + +In +Intrinsic.h: + + +typedef struct _ObjectRec *Object; + + + + + +Object Resources + +The resource names, classes, and representation types specified in the +objectClassRec +resource list are: + + + + + + + + + + + Name + Class + Representation + + + + + XtNdestroyCallback + XtCCallback + XtRCallback + + + + + + + +ObjectPart Default Values + +All fields in +ObjectPart +have the same default values as the corresponding fields in +CorePart. + + + + +Object Arguments to Intrinsics Routines + +The WidgetClass arguments to the following procedures may be +objectClass +or any subclass: + + + +XtInitializeWidgetClass, +XtCreateWidget, +XtVaCreateWidget +XtIsSubclass, +XtCheckSubclass +XtGetResourceList, +XtGetConstraintResourceList + + + +The Widget arguments to the following procedures may be of class +Object +or any subclass: + + + + +, + + + + + +, +, +, +, +, +, +, + + + + + +, +XtSuperclass, +, +, +XtIsObject, +XtIsRectObj, +XtIsWidget, +XtIsComposite, +XtIsConstraint, +XtIsShell, +XtIsOverrideShell, +XtIsWMShell, +XtIsVendorShell, +XtIsTransientShell, +XtIsToplevelShell, +XtIsApplicationShell, +XtIsSessionShell + + + + +, + +(both will return +False +if argument is not a subclass of +RectObj) + + + + + +(returns the state of the nearest windowed ancestor +if class of argument is not a subclass of +Core) + + + + + + + + + + + + + + +XtParent, +, +, + + + + + + +(descendant) + + + + +, + + + + + + + + + + +, +, +, + + + + + +, +, +, + + + + + +, + + + + + +The return value of the following procedures will be of class +Object +or a subclass: + + + + +, + + + + + +XtParent + + + + + + + + + +The return value of the following procedures will be +objectClass +or a subclass: + + + + +, +XtSuperclass + + + + + + +Use of Objects + +The +Object +class exists to enable programmers to use the Intrinsics' +classing and resource-handling mechanisms for things smaller +and simpler than widgets. +Objects make obsolete many common uses of subresources as described in +Sections 9.4, 9.7.2.4, and 9.7.2.5. + + + +Composite +widget classes that wish to accept nonwidget children must +set the accepts_objects field in the +CompositeClassExtension +structure to +True. + +will otherwise generate an error message on an attempt to create a +nonwidget child. + + + +Of the classes defined by the Intrinsics, +ApplicationShell +and +SessionShell +accept nonwidget children, and the class of any nonwidget child +must not be +rectObjClass +or any subclass. The intent of allowing +Object +children of +ApplicationShell +and +SessionShell +is to provide clients a simple mechanism +for establishing the resource-naming root of an object hierarchy. + + + + + +Rectangle Objects + +The class of rectangle objects is a subclass of +Object +that represents +rectangular areas. It encapsulates the mechanisms for geometry +management and is called RectObj +to avoid conflict with the Xlib +Rectangle +data type. + + +RectObjClassPart Structure + +As with the +ObjectClassPart +structure, all fields in the +RectObjClassPart +structure have the same +purpose and function as the corresponding fields in +CoreClassPart; +fields whose names are rectn for some integer +n are not used for +RectObj, but exist to pad the data structure so that it matches +Core's +class record. The class record initialization must fill all +rectn fields with NULL or zero as appropriate to the type. + + +typedef struct _RectObjClassPart { + WidgetClass superclass; + String class_name; + Cardinal widget_size; + XtProc class_initialize; + XtWidgetClassProc class_part_initialize; + XtEnum class_inited; + XtInitProc initialize; + XtArgsProc initialize_hook; + XtProc rect1; + XtPointer rect2; + Cardinal rect3; + XtResourceList resources; + Cardinal num_resources; + XrmClass xrm_class; + Boolean rect4; + XtEnum rect5; + Boolean rect6; + Boolean rect7; + XtWidgetProc destroy; + XtWidgetProc resize; + XtExposeProc expose; + XtSetValuesFunc set_values; + XtArgsFunc set_values_hook; + XtAlmostProc set_values_almost; + XtArgsProc get_values_hook; + XtProc rect9; + XtVersionType version; + XtPointer callback_private; + String rect10; + XtGeometryHandler query_geometry; + XtProc rect11; + XtPointer extension ; +} RectObjClassPart; + + +The +RectObj +class record consists of just the +RectObjClassPart. + + +typedef struct _RectObjClassRec { + RectObjClassPart rect_class; +} RectObjClassRec, *RectObjClass; + + +The predefined class record and pointer for +RectObjClassRec +are + + + +In +Intrinsic.h: + + +extern RectObjClassRec rectObjClassRec; + + +In +Intrinsic.h: + + +extern WidgetClass rectObjClass; + + +The opaque types +RectObj +and +RectObjClass +and the opaque variable +rectObjClass +are defined for generic actions on objects +whose class is RectObj or a subclass of +RectObj. +Intrinsic.h +uses an incomplete structure definition to ensure that the compiler +catches attempts to access private data: + + +typedef struct _RectObjClassRec* RectObjClass; + + + + + +RectObjPart Structure + +In addition to the +ObjectPart +fields, +RectObj +objects have the following fields defined in the +RectObjPart +structure. All fields have the same meaning as the corresponding field in +CorePart. + + +typedef struct _RectObjPart { + Position x, y; + Dimension width, height; + Dimension border_width; + Boolean managed; + Boolean sensitive; + Boolean ancestor_sensitive; +} RectObjPart; + + +RectObj +objects have the RectObj fields immediately following the Object fields. + + +typedef struct _RectObjRec { + ObjectPart object; + RectObjPart rectangle; +} RectObjRec, *RectObj; + + +In +Intrinsic.h: + + +typedef struct _RectObjRec* RectObj; + + + + + +RectObj Resources + +The resource names, classes, and representation types that are specified in the +rectObjClassRec +resource list are: + + + + + + + + + Name + Class + Representation + + + + + XtNancestorSensitive + XtCSensitive + XtRBoolean + + + XtNborderWidth + XtCBorderWidth + XtRDimension + + + XtNheight + XtCHeight + XtRDimension + + + XtNsensitive + XtCSensitive + XtRBoolean + + + XtNwidth + XtCWidth + XtRDimension + + + XtNx + XtCPosition + XtRPosition + + + XtNy + XtCPosition + XtRPosition + + + + + + + + +RectObjPart Default Values + +All fields in +RectObjPart +have the same default values as the corresponding fields in +CorePart. + + + + +Widget Arguments to Intrinsics Routines + +The WidgetClass arguments to the following procedures may be +rectObjClass +or any subclass: + + + + +, + + + + + +The Widget arguments to the following procedures may be of class +RectObj +or any subclass: + + + + +, +, + + + + + +, + + + + + +, +, +, +, + + + + + + + + + + + + + + + + + + + + +The return value of the following procedures will be of class +RectObj +or a subclass: + + + + +, + + + + + + + +Use of Rectangle Objects + +RectObj +can be subclassed to provide widgetlike objects (sometimes +called gadgets) that do not use windows and do not have those +features that are seldom used in simple widgets. This can save memory +resources both in the server and in applications +but requires additional support code in the parent. +In the following +discussion, rectobj refers only to objects +whose class is RectObj or a subclass of +RectObj, +but not Core or a subclass of +Core. + + + +Composite +widget classes that wish to accept rectobj children must set +the accepts_objects field in the +CompositeClassExtension +extension structure to +True. + +or + +will otherwise generate an error if called to create a nonwidget child. +If the composite widget supports only children of class +RectObj +or a subclass (i.e., not of the general Object class), it +must declare an insert_child procedure and check the subclass of each +new child in that procedure. None of the classes defined by the +Intrinsics accept rectobj children. + + + +If gadgets are defined in an object set, the parent is responsible for +much more than the parent of a widget. The parent must request and handle +input events that occur for the gadget and is responsible for making +sure that when it receives an exposure event the gadget children get +drawn correctly. +Rectobj children may +have expose procedures +specified in their class records, but the parent is free to +ignore them, instead drawing the contents of the child itself. This +can potentially save graphics context switching. The precise contents +of the exposure event and region arguments to the RectObj expose +procedure are not specified by the Intrinsics; a particular rectangle object is +free to define the coordinate system origin (self-relative or +parent-relative) and whether or not the rectangle or region is assumed to +have been intersected with the visible region of the object. + + + +In general, it is expected that a composite widget that accepts +nonwidget children will document those children it is able to handle, +since a gadget cannot be viewed as a completely self-contained entity, +as can a widget. Since a particular composite widget class is usually +designed to handle nonwidget children of only a limited set of classes, it should +check the classes of newly added children in its insert_child +procedure to make sure that it can deal with them. + + + +The Intrinsics will clear areas of a parent window obscured by +rectobj children, causing exposure events, under the following +circumstances: + + + + +A rectobj child is managed or unmanaged. + + + + +In a call to + +on a rectobj child, one or more of the set_values procedures returns +True. + + + + +In a call to + +on a rectobj child, areas will +be cleared corresponding to both the old and the new child +geometries, including the border, if the geometry changes. + + + + +In a call to + +on a rectobj child, areas will be +cleared corresponding to both the old and the new child +geometries, including the border, if the geometry changes. + + + + +In a call to + +on a rectobj child, a single +rectangle will be cleared corresponding to the larger of the +old and the new child geometries if they are different. + + + + +In a call to + +(or +) +on a rectobj child with +XtQueryOnly +not set, if the manager returns +XtGeometryYes, +two rectangles will be cleared corresponding to both the old and +the new child geometries. + + + + +Stacking order is not supported for rectobj children. Composite widgets with +rectobj children are free to define any semantics desired if the child +geometries overlap, including making this an error. + + + +When a rectobj is playing the role of a widget, developers must be +reminded to avoid making assumptions about the object passed in the +Widget argument to a callback procedure. + + + + + +Undeclared Class + +The Intrinsics define an unnamed class between +RectObj +and +Core +for possible future use by the X Consortium. The only assumptions that +may be made about the unnamed class are + + + + +The core_class.superclass field of +coreWidgetClassRec +contains a pointer to the unnamed class record. + + + + +A pointer to the unnamed class record when dereferenced as an +ObjectClass +will contain a pointer to +rectObjClassRec +in its object_class.superclass field. + + + + +Except for the above, the contents of the class record for this class +and the result of an attempt to subclass or to create a widget of this +unnamed class are undefined. + + + + +Widget Arguments to Intrinsics Routines + +The WidgetClass arguments to the following procedures must be of class +Shell +or a subclass: + + + + +, +, +, +, +, + + + + + +The Widget arguments to the following procedures must be of class +Core +or any subclass: + + + + +, + + + + + +, +, +, +, +, + +, +, + + + + + + + + + + +, +, +, +, +, +, +, +, +, + + + + + + + + + + +, +XtDisplay, +, + + + + + + + + + + +, +, +, +, +, +, +, + + + + + +, + +(both destination and source) + + + + +, +, +, + + + + + +, + + + + + +, + + + + + + + + + + +, + +(subtree) + + + + + + + + + + + + + + +The Widget arguments to the following procedures must be of class +Composite +or any subclass: + + + + +, + + + + + +The Widget arguments to the following procedures must be of a subclass of +Shell: + + + + +, +, +, +, +, +, + + + + + +The return value of the following procedure will be of class +Core +or a subclass: + + + + + + + + + +The return value of the following procedures will be of a subclass of +Shell: + + + + +, +, +, +, +, + + + + + + -- cgit v1.2.3