1068 lines
23 KiB
Plaintext
1068 lines
23 KiB
Plaintext
|
.\" $Xorg: CH12,v 1.3 2000/08/17 19:42:47 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 12\fP\s-1
|
||
|
|
|
||
|
|
\s+1\fBNonwidget Objects\fP\s-1
|
||
|
|
.sp 2
|
||
|
|
.nr H1 12
|
||
|
|
.nr H2 0
|
||
|
|
.nr H3 0
|
||
|
|
.nr H4 0
|
||
|
|
.nr H5 0
|
||
|
|
.LP
|
||
|
|
.XS
|
||
|
|
Chapter 12 \(em Nonwidget Objects
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
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 (\fIunnamed\fP),
|
||
|
|
and members of these classes
|
||
|
|
are referred to generically as \fIobjects\fP. By convention, the term
|
||
|
|
\fIwidget\fP refers only to objects that are a subclass of
|
||
|
|
Core,
|
||
|
|
and the term \fInonwidget\fP 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 \fIwidget\fP 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 \*(xI routines.
|
||
|
|
|
||
|
|
.NH 2
|
||
|
|
Data Structures
|
||
|
|
.XS
|
||
|
|
\*(SN Data Structures
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
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.
|
||
|
|
|
||
|
|
.NH 2
|
||
|
|
Object Objects
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Object Objects\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
.IN "Object" "" "@DEF@"
|
||
|
|
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
|
||
|
|
.PN ObjectClassPart
|
||
|
|
and
|
||
|
|
.PN ObjectPart
|
||
|
|
structures.
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
ObjectClassPart Structure
|
||
|
|
.XS
|
||
|
|
\*(SN ObjectClassPart Structure
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
The common fields for all object classes are defined in the
|
||
|
|
.PN ObjectClassPart
|
||
|
|
structure. All fields have the same purpose,
|
||
|
|
function, and restrictions as the corresponding fields in
|
||
|
|
.PN CoreClassPart ;
|
||
|
|
fields whose
|
||
|
|
names are obj\fI\s+1n\s-1\fP for some integer \s+1\fIn\fP\s-1 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
|
||
|
|
obj\fI\s+1n\s-1\fP fields with NULL or zero as appropriate to the type.
|
||
|
|
.LP
|
||
|
|
.IN "ObjectClassPart" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
.TA .5i 3i
|
||
|
|
.ta .5i 3i
|
||
|
|
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;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The extension record defined for
|
||
|
|
.PN ObjectClassPart
|
||
|
|
with a \fIrecord_type\fP equal to
|
||
|
|
.PN \s-1NULLQUARK\s+1
|
||
|
|
is
|
||
|
|
.PN ObjectClassExtensionRec .
|
||
|
|
.LP
|
||
|
|
.IN "ObjectClassExtensionRec" "" "@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
|
||
|
|
XtAllocateProc allocate; See Section 2.5.5.
|
||
|
|
XtDeallocateProc deallocate; See Section 2.8.4.
|
||
|
|
} ObjectClassExtensionRec, *ObjectClassExtension;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The prototypical
|
||
|
|
.PN ObjectClass
|
||
|
|
consists of just the
|
||
|
|
.PN ObjectClassPart .
|
||
|
|
.LP
|
||
|
|
.IN "ObjectClassRec" "" "@DEF@"
|
||
|
|
.IN "ObjectClass" "" "@DEF@"
|
||
|
|
.IN "objectClass" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
.TA .5i 3i
|
||
|
|
.ta .5i 3i
|
||
|
|
typedef struct _ObjectClassRec {
|
||
|
|
ObjectClassPart object_class;
|
||
|
|
} ObjectClassRec, *ObjectClass;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The predefined class record and pointer for
|
||
|
|
.PN ObjectClassRec
|
||
|
|
are
|
||
|
|
.LP
|
||
|
|
In
|
||
|
|
.PN IntrinsicP.h :
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
extern ObjectClassRec objectClassRec;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
In
|
||
|
|
.PN Intrinsic.h :
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
extern WidgetClass objectClass;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The opaque types
|
||
|
|
.PN Object
|
||
|
|
and
|
||
|
|
.PN ObjectClass
|
||
|
|
and the opaque variable
|
||
|
|
.PN objectClass
|
||
|
|
are defined for generic actions on objects.
|
||
|
|
The symbolic constant for the
|
||
|
|
.PN ObjectClassExtension
|
||
|
|
version identifier is
|
||
|
|
.PN XtObjectExtensionVersion
|
||
|
|
(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
|
||
|
|
typedef struct _ObjectClassRec* ObjectClass;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
ObjectPart Structure
|
||
|
|
.XS
|
||
|
|
\*(SN ObjectPart Structure
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
The common fields for all object instances are defined in the
|
||
|
|
.PN ObjectPart
|
||
|
|
structure. All fields have the same meaning as the
|
||
|
|
corresponding fields in
|
||
|
|
.PN CorePart .
|
||
|
|
.LP
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
.TA .5i 3i
|
||
|
|
.ta .5i 3i
|
||
|
|
.IN "ObjectPart" "" "@DEF@"
|
||
|
|
typedef struct _ObjectPart {
|
||
|
|
Widget self;
|
||
|
|
WidgetClass widget_class;
|
||
|
|
Widget parent;
|
||
|
|
Boolean being_destroyed;
|
||
|
|
XtCallbackList destroy_callbacks;
|
||
|
|
XtPointer constraints;
|
||
|
|
} ObjectPart;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
All object instances have the
|
||
|
|
Object
|
||
|
|
fields as their first component. The prototypical type
|
||
|
|
.PN Object
|
||
|
|
is defined with only this set of fields.
|
||
|
|
Various routines can cast object pointers, as needed, to specific
|
||
|
|
object types.
|
||
|
|
.LP
|
||
|
|
In
|
||
|
|
.PN IntrinsicP.h :
|
||
|
|
.LP
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
.TA .5i 3i
|
||
|
|
.ta .5i 3i
|
||
|
|
typedef struct _ObjectRec {
|
||
|
|
ObjectPart object;
|
||
|
|
} ObjectRec, *Object;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
.IN "ObjectRec" "" "@DEF@"
|
||
|
|
In
|
||
|
|
.PN Intrinsic.h :
|
||
|
|
.LP
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
typedef struct _ObjectRec *Object;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Object Resources
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Object Resources\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
The resource names, classes, and representation types specified in the
|
||
|
|
.PN objectClassRec
|
||
|
|
resource list are:
|
||
|
|
.LP
|
||
|
|
.TS
|
||
|
|
lw(1.5i) lw(1.5i) lw(2.5i) .
|
||
|
|
_
|
||
|
|
.sp 6p
|
||
|
|
Name Class Representation
|
||
|
|
.sp 6p
|
||
|
|
_
|
||
|
|
.sp 6p
|
||
|
|
XtNdestroyCallback XtCCallback XtRCallback
|
||
|
|
.sp 6p
|
||
|
|
_
|
||
|
|
.TE
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
ObjectPart Default Values
|
||
|
|
.XS
|
||
|
|
\fB\*(SN ObjectPart Default Values\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
All fields in
|
||
|
|
.PN ObjectPart
|
||
|
|
have the same default values as the corresponding fields in
|
||
|
|
.PN CorePart .
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Object Arguments to \*(xI Routines
|
||
|
|
.XS
|
||
|
|
\*(SN Object Arguments to \*(xI Routines
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
The WidgetClass arguments to the following procedures may be
|
||
|
|
.PN objectClass
|
||
|
|
or any subclass:
|
||
|
|
.sp
|
||
|
|
.IP
|
||
|
|
.PN XtInitializeWidgetClass ,
|
||
|
|
.PN XtCreateWidget ,
|
||
|
|
.PN XtVaCreateWidget
|
||
|
|
.IP
|
||
|
|
.PN XtIsSubclass ,
|
||
|
|
.PN XtCheckSubclass
|
||
|
|
.IP
|
||
|
|
.PN XtGetResourceList ,
|
||
|
|
.PN XtGetConstraintResourceList
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
The Widget arguments to the following procedures may be of class
|
||
|
|
Object
|
||
|
|
or any subclass:
|
||
|
|
.sp
|
||
|
|
.IP
|
||
|
|
.PN XtCreateWidget ,
|
||
|
|
.PN XtVaCreateWidget
|
||
|
|
.IP
|
||
|
|
.PN XtAddCallback ,
|
||
|
|
.PN XtAddCallbacks ,
|
||
|
|
.PN XtRemoveCallback ,
|
||
|
|
.PN XtRemoveCallbacks ,
|
||
|
|
.PN XtRemoveAllCallbacks ,
|
||
|
|
.PN XtCallCallbacks ,
|
||
|
|
.PN XtHasCallbacks ,
|
||
|
|
.PN XtCallCallbackList
|
||
|
|
.IP
|
||
|
|
.PN XtClass ,
|
||
|
|
.PN XtSuperclass ,
|
||
|
|
.PN XtIsSubclass ,
|
||
|
|
.PN XtCheckSubclass ,
|
||
|
|
.PN XtIsObject ,
|
||
|
|
.PN XtIsRectObj ,
|
||
|
|
.PN XtIsWidget ,
|
||
|
|
.PN XtIsComposite ,
|
||
|
|
.PN XtIsConstraint ,
|
||
|
|
.PN XtIsShell ,
|
||
|
|
.PN XtIsOverrideShell ,
|
||
|
|
.PN XtIsWMShell ,
|
||
|
|
.PN XtIsVendorShell ,
|
||
|
|
.PN XtIsTransientShell ,
|
||
|
|
.PN XtIsToplevelShell ,
|
||
|
|
.PN XtIsApplicationShell ,
|
||
|
|
.PN XtIsSessionShell
|
||
|
|
.IP
|
||
|
|
.PN XtIsManaged ,
|
||
|
|
.PN XtIsSensitive
|
||
|
|
.br
|
||
|
|
(both will return
|
||
|
|
.PN False
|
||
|
|
if argument is not a subclass of
|
||
|
|
RectObj)
|
||
|
|
.IP
|
||
|
|
.PN XtIsRealized
|
||
|
|
.br
|
||
|
|
(returns the state of the nearest windowed ancestor
|
||
|
|
if class of argument is not a subclass of
|
||
|
|
Core)
|
||
|
|
.IP
|
||
|
|
.PN XtWidgetToApplicationContext
|
||
|
|
.IP
|
||
|
|
.PN XtDestroyWidget
|
||
|
|
.IP
|
||
|
|
.PN XtParent ,
|
||
|
|
.PN XtDisplayOfObject ,
|
||
|
|
.PN XtScreenOfObject ,
|
||
|
|
.PN XtWindowOfObject
|
||
|
|
.IP
|
||
|
|
.PN XtSetKeyboardFocus
|
||
|
|
(descendant)
|
||
|
|
.IP
|
||
|
|
.PN XtGetGC ,
|
||
|
|
.PN XtReleaseGC
|
||
|
|
.IP
|
||
|
|
.PN XtName
|
||
|
|
.IP
|
||
|
|
.PN XtSetValues ,
|
||
|
|
.PN XtGetValues ,
|
||
|
|
.PN XtVaSetValues ,
|
||
|
|
.PN XtVaGetValues
|
||
|
|
.IP
|
||
|
|
.PN XtGetSubresources ,
|
||
|
|
.PN XtGetApplicationResources ,
|
||
|
|
.PN XtVaGetSubresources ,
|
||
|
|
.PN XtVaGetApplicationResources
|
||
|
|
.IP
|
||
|
|
.PN XtConvert ,
|
||
|
|
.PN XtConvertAndStore
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
The return value of the following procedures will be of class
|
||
|
|
Object
|
||
|
|
or a subclass:
|
||
|
|
.sp
|
||
|
|
.IP
|
||
|
|
.PN XtCreateWidget ,
|
||
|
|
.PN XtVaCreateWidget
|
||
|
|
.IP
|
||
|
|
.PN XtParent
|
||
|
|
.IP
|
||
|
|
.PN XtNameToWidget
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
The return value of the following procedures will be
|
||
|
|
.PN objectClass
|
||
|
|
or a subclass:
|
||
|
|
.sp
|
||
|
|
.IP
|
||
|
|
.PN XtClass ,
|
||
|
|
.PN XtSuperclass
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Use of Objects
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Use of Objects\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
The
|
||
|
|
Object
|
||
|
|
class exists to enable programmers to use the \*(xI'
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
Composite
|
||
|
|
widget classes that wish to accept nonwidget children must
|
||
|
|
set the \fIaccepts_objects\fP field in the
|
||
|
|
.PN CompositeClassExtension
|
||
|
|
structure to
|
||
|
|
.PN True .
|
||
|
|
.PN XtCreateWidget
|
||
|
|
will otherwise generate an error message on an attempt to create a
|
||
|
|
nonwidget child.
|
||
|
|
.LP
|
||
|
|
Of the classes defined by the \*(xI,
|
||
|
|
ApplicationShell
|
||
|
|
and
|
||
|
|
SessionShell
|
||
|
|
accept nonwidget children, and the class of any nonwidget child
|
||
|
|
must not be
|
||
|
|
.PN 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.
|
||
|
|
|
||
|
|
.NH 2
|
||
|
|
Rectangle Objects
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Rectangle Objects\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
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
|
||
|
|
.IN "RectObj" "" "@DEF@"
|
||
|
|
to avoid conflict with the Xlib
|
||
|
|
.PN Rectangle
|
||
|
|
data type.
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
RectObjClassPart Structure
|
||
|
|
.XS
|
||
|
|
\*(SN RectObjClassPart Structure
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
As with the
|
||
|
|
.PN ObjectClassPart
|
||
|
|
structure, all fields in the
|
||
|
|
.PN RectObjClassPart
|
||
|
|
structure have the same
|
||
|
|
purpose and function as the corresponding fields in
|
||
|
|
.PN CoreClassPart ;
|
||
|
|
fields whose names are rect\fI\s+1n\s-1\fP for some integer
|
||
|
|
\fI\s+1n\s-1\fP 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
|
||
|
|
rect\fI\s+1n\s-1\fP fields with NULL or zero as appropriate to the type.
|
||
|
|
.LP
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
.TA .5i 3i
|
||
|
|
.ta .5i 3i
|
||
|
|
.IN "RectObjClassPart" "" "@DEF@"
|
||
|
|
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;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
RectObj
|
||
|
|
class record consists of just the
|
||
|
|
.PN RectObjClassPart .
|
||
|
|
.LP
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
.TA .5i 3i
|
||
|
|
.ta .5i 3i
|
||
|
|
.IN "RectObjClassRec" "" "@DEF@"
|
||
|
|
.IN "RectObjClass" "" "@DEF@"
|
||
|
|
typedef struct _RectObjClassRec {
|
||
|
|
RectObjClassPart rect_class;
|
||
|
|
} RectObjClassRec, *RectObjClass;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The predefined class record and pointer for
|
||
|
|
.PN RectObjClassRec
|
||
|
|
are
|
||
|
|
.LP
|
||
|
|
In
|
||
|
|
.PN Intrinsic.h :
|
||
|
|
.LP
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
extern RectObjClassRec rectObjClassRec;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
In
|
||
|
|
.PN Intrinsic.h :
|
||
|
|
.LP
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
extern WidgetClass rectObjClass;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The opaque types
|
||
|
|
.PN RectObj
|
||
|
|
and
|
||
|
|
.PN RectObjClass
|
||
|
|
and the opaque variable
|
||
|
|
.PN rectObjClass
|
||
|
|
are defined for generic actions on objects
|
||
|
|
whose class is RectObj or a subclass of
|
||
|
|
RectObj.
|
||
|
|
.PN Intrinsic.h
|
||
|
|
uses an incomplete structure definition to ensure that the compiler
|
||
|
|
catches attempts to access private data:
|
||
|
|
.LP
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
typedef struct _RectObjClassRec* RectObjClass;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
RectObjPart Structure
|
||
|
|
.XS
|
||
|
|
\*(SN RectObjPart Structure
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
In addition to the
|
||
|
|
.PN ObjectPart
|
||
|
|
fields,
|
||
|
|
RectObj
|
||
|
|
objects have the following fields defined in the
|
||
|
|
.PN RectObjPart
|
||
|
|
structure. All fields have the same meaning as the corresponding field in
|
||
|
|
.PN CorePart .
|
||
|
|
.LP
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
.TA .5i 3i
|
||
|
|
.ta .5i 3i
|
||
|
|
.IN "RectObjPart" "" "@DEF@"
|
||
|
|
typedef struct _RectObjPart {
|
||
|
|
Position x, y;
|
||
|
|
Dimension width, height;
|
||
|
|
Dimension border_width;
|
||
|
|
Boolean managed;
|
||
|
|
Boolean sensitive;
|
||
|
|
Boolean ancestor_sensitive;
|
||
|
|
} RectObjPart;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
RectObj
|
||
|
|
objects have the RectObj fields immediately following the Object fields.
|
||
|
|
.LP
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
.TA .5i 3i
|
||
|
|
.ta .5i 3i
|
||
|
|
.IN "RectObjRec" "" "@DEF@"
|
||
|
|
typedef struct _RectObjRec {
|
||
|
|
ObjectPart object;
|
||
|
|
RectObjPart rectangle;
|
||
|
|
} RectObjRec, *RectObj;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
In
|
||
|
|
.PN Intrinsic.h :
|
||
|
|
.LP
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
typedef struct _RectObjRec* RectObj;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
RectObj Resources
|
||
|
|
.XS
|
||
|
|
\fB\*(SN RectObj Resources\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
The resource names, classes, and representation types that are specified in the
|
||
|
|
.PN rectObjClassRec
|
||
|
|
resource list are:
|
||
|
|
.TS
|
||
|
|
lw(1.5i) lw(1.5i) lw(2.5i) .
|
||
|
|
_
|
||
|
|
.sp 6p
|
||
|
|
Name Class Representation
|
||
|
|
.sp 6p
|
||
|
|
_
|
||
|
|
.sp 6p
|
||
|
|
XtNancestorSensitive XtCSensitive XtRBoolean
|
||
|
|
XtNborderWidth XtCBorderWidth XtRDimension
|
||
|
|
XtNheight XtCHeight XtRDimension
|
||
|
|
XtNsensitive XtCSensitive XtRBoolean
|
||
|
|
XtNwidth XtCWidth XtRDimension
|
||
|
|
XtNx XtCPosition XtRPosition
|
||
|
|
XtNy XtCPosition XtRPosition
|
||
|
|
.sp 6p
|
||
|
|
_
|
||
|
|
.TE
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
RectObjPart Default Values
|
||
|
|
.XS
|
||
|
|
\fB\*(SN RectObjPart Default Values\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
All fields in
|
||
|
|
.PN RectObjPart
|
||
|
|
have the same default values as the corresponding fields in
|
||
|
|
.PN CorePart .
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Widget Arguments to \*(xI Routines
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Widget Arguments to \*(xI Routines\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
The WidgetClass arguments to the following procedures may be
|
||
|
|
.PN rectObjClass
|
||
|
|
or any subclass:
|
||
|
|
.sp
|
||
|
|
.IP
|
||
|
|
.PN XtCreateManagedWidget ,
|
||
|
|
.PN XtVaCreateManagedWidget
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
The Widget arguments to the following procedures may be of class
|
||
|
|
RectObj
|
||
|
|
or any subclass:
|
||
|
|
.sp
|
||
|
|
.IP
|
||
|
|
.PN XtConfigureWidget ,
|
||
|
|
.PN XtMoveWidget ,
|
||
|
|
.PN XtResizeWidget
|
||
|
|
.IP
|
||
|
|
.PN XtMakeGeometryRequest ,
|
||
|
|
.PN XtMakeResizeRequest
|
||
|
|
.IP
|
||
|
|
.PN XtManageChildren ,
|
||
|
|
.PN XtManageChild ,
|
||
|
|
.PN XtUnmanageChildren ,
|
||
|
|
.PN XtUnmanageChild ,
|
||
|
|
.PN XtChangeManagedSet
|
||
|
|
.IP
|
||
|
|
.PN XtQueryGeometry
|
||
|
|
.IP
|
||
|
|
.PN XtSetSensitive
|
||
|
|
.IP
|
||
|
|
.PN XtTranslateCoords
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
The return value of the following procedures will be of class
|
||
|
|
RectObj
|
||
|
|
or a subclass:
|
||
|
|
.sp
|
||
|
|
.IP
|
||
|
|
.PN XtCreateManagedWidget ,
|
||
|
|
.PN XtVaCreateManagedWidget
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Use of Rectangle Objects
|
||
|
|
.XS
|
||
|
|
\*(SN Use of Rectangle Objects
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
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, \fIrectobj\fP refers only to objects
|
||
|
|
whose class is RectObj or a subclass of
|
||
|
|
RectObj,
|
||
|
|
but not Core or a subclass of
|
||
|
|
Core.
|
||
|
|
.LP
|
||
|
|
Composite
|
||
|
|
widget classes that wish to accept rectobj children must set
|
||
|
|
the \fIaccepts_objects\fP field in the
|
||
|
|
.PN CompositeClassExtension
|
||
|
|
extension structure to
|
||
|
|
.PN True .
|
||
|
|
.PN XtCreateWidget
|
||
|
|
or
|
||
|
|
.PN XtCreateManagedWidget
|
||
|
|
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
|
||
|
|
\*(xI accept rectobj children.
|
||
|
|
.LP
|
||
|
|
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 \*(xI; 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.
|
||
|
|
.LP
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
The \*(xI will clear areas of a parent window obscured by
|
||
|
|
rectobj children, causing exposure events, under the following
|
||
|
|
circumstances:
|
||
|
|
.IP \(bu 5
|
||
|
|
A rectobj child is managed or unmanaged.
|
||
|
|
.IP \(bu 5
|
||
|
|
In a call to
|
||
|
|
.PN XtSetValues
|
||
|
|
on a rectobj child, one or more of the set_values procedures returns
|
||
|
|
.PN True .
|
||
|
|
.IP \(bu 5
|
||
|
|
In a call to
|
||
|
|
.PN XtConfigureWidget
|
||
|
|
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.
|
||
|
|
.IP \(bu 5
|
||
|
|
In a call to
|
||
|
|
.PN XtMoveWidget
|
||
|
|
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.
|
||
|
|
.IP \(bu 5
|
||
|
|
In a call to
|
||
|
|
.PN XtResizeWidget
|
||
|
|
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.
|
||
|
|
.IP \(bu 5
|
||
|
|
In a call to
|
||
|
|
.PN XtMakeGeometryRequest
|
||
|
|
(or
|
||
|
|
.PN XtMakeResizeRequest )
|
||
|
|
on a rectobj child with
|
||
|
|
.PN XtQueryOnly
|
||
|
|
not set, if the manager returns
|
||
|
|
.PN XtGeometryYes ,
|
||
|
|
two rectangles will be cleared corresponding to both the old and
|
||
|
|
the new child geometries.
|
||
|
|
.LP
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
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.
|
||
|
|
|
||
|
|
.NH 2
|
||
|
|
Undeclared Class
|
||
|
|
.XS
|
||
|
|
\*(SN Undeclared Class
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
The \*(xI 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
|
||
|
|
.IP \(bu 5
|
||
|
|
The \fIcore_class.superclass\fP field of
|
||
|
|
.PN coreWidgetClassRec
|
||
|
|
contains a pointer to the unnamed class record.
|
||
|
|
.IP \(bu 5
|
||
|
|
A pointer to the unnamed class record when dereferenced as an
|
||
|
|
.PN ObjectClass
|
||
|
|
will contain a pointer to
|
||
|
|
.PN rectObjClassRec
|
||
|
|
in its \fIobject_class.superclass\fP field.
|
||
|
|
.LP
|
||
|
|
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.
|
||
|
|
|
||
|
|
.NH 2
|
||
|
|
Widget Arguments to \*(xI Routines
|
||
|
|
.XS
|
||
|
|
\*(SN Widget Arguments to \*(xI Routines
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
The WidgetClass arguments to the following procedures must be of class
|
||
|
|
Shell
|
||
|
|
or a subclass:
|
||
|
|
.sp
|
||
|
|
.IP
|
||
|
|
.PN XtCreatePopupShell ,
|
||
|
|
.PN XtVaCreatePopupShell ,
|
||
|
|
.PN XtAppCreateShell ,
|
||
|
|
.PN XtVaAppCreateShell ,
|
||
|
|
.PN XtOpenApplication ,
|
||
|
|
.PN XtVaOpenApplication
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
The Widget arguments to the following procedures must be of class
|
||
|
|
Core
|
||
|
|
or any subclass:
|
||
|
|
.sp
|
||
|
|
.IP
|
||
|
|
.PN XtCreatePopupShell ,
|
||
|
|
.PN XtVaCreatePopupShell
|
||
|
|
.IP
|
||
|
|
.PN XtAddEventHandler ,
|
||
|
|
.PN XtAddRawEventHandler ,
|
||
|
|
.PN XtRemoveEventHandler ,
|
||
|
|
.br
|
||
|
|
.PN XtRemoveRawEventHandler ,
|
||
|
|
.PN XtInsertEventHandler ,
|
||
|
|
.PN XtInsertRawEventHandler
|
||
|
|
.br
|
||
|
|
.PN XtInsertEventTypeHandler ,
|
||
|
|
.PN XtRemoveEventTypeHandler ,
|
||
|
|
.IP
|
||
|
|
.PN XtRegisterDrawable
|
||
|
|
.PN XtDispatchEventToWidget
|
||
|
|
.IP
|
||
|
|
.PN XtAddGrab ,
|
||
|
|
.PN XtRemoveGrab ,
|
||
|
|
.PN XtGrabKey ,
|
||
|
|
.PN XtGrabKeyboard ,
|
||
|
|
.PN XtUngrabKey ,
|
||
|
|
.PN XtUngrabKeyboard ,
|
||
|
|
.PN XtGrabButton ,
|
||
|
|
.PN XtGrabPointer ,
|
||
|
|
.PN XtUngrabButton ,
|
||
|
|
.br
|
||
|
|
.PN XtUngrabPointer
|
||
|
|
.IP
|
||
|
|
.PN XtBuildEventMask
|
||
|
|
.IP
|
||
|
|
.PN XtCreateWindow ,
|
||
|
|
.PN XtDisplay ,
|
||
|
|
.PN XtScreen ,
|
||
|
|
.PN XtWindow
|
||
|
|
.IP
|
||
|
|
.PN XtNameToWidget
|
||
|
|
.IP
|
||
|
|
.PN XtGetSelectionValue ,
|
||
|
|
.PN XtGetSelectionValues ,
|
||
|
|
.PN XtOwnSelection ,
|
||
|
|
.PN XtDisownSelection ,
|
||
|
|
.PN XtOwnSelectionIncremental ,
|
||
|
|
.PN XtGetSelectionValueIncremental ,
|
||
|
|
.PN XtGetSelectionValuesIncremental ,
|
||
|
|
.br
|
||
|
|
.PN XtGetSelectionRequest
|
||
|
|
.IP
|
||
|
|
.PN XtInstallAccelerators ,
|
||
|
|
.PN XtInstallAllAccelerators
|
||
|
|
(both destination and source)
|
||
|
|
.IP
|
||
|
|
.PN XtAugmentTranslations ,
|
||
|
|
.PN XtOverrideTranslations ,
|
||
|
|
.PN XtUninstallTranslations ,
|
||
|
|
.br
|
||
|
|
.PN XtCallActionProc
|
||
|
|
.IP
|
||
|
|
.PN XtMapWidget ,
|
||
|
|
.PN XtUnmapWidget
|
||
|
|
.IP
|
||
|
|
.PN XtRealizeWidget ,
|
||
|
|
.PN XtUnrealizeWidget
|
||
|
|
.IP
|
||
|
|
.PN XtSetMappedWhenManaged
|
||
|
|
.IP
|
||
|
|
.PN XtCallAcceptFocus ,
|
||
|
|
.PN XtSetKeyboardFocus
|
||
|
|
(subtree)
|
||
|
|
.IP
|
||
|
|
.PN XtResizeWindow
|
||
|
|
.IP
|
||
|
|
.PN XtSetWMColormapWindows
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
The Widget arguments to the following procedures must be of class
|
||
|
|
Composite
|
||
|
|
or any subclass:
|
||
|
|
.sp
|
||
|
|
.IP
|
||
|
|
.PN XtCreateManagedWidget ,
|
||
|
|
.PN XtVaCreateManagedWidget
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
The Widget arguments to the following procedures must be of a subclass of
|
||
|
|
Shell:
|
||
|
|
.sp
|
||
|
|
.IP
|
||
|
|
.PN XtPopdown ,
|
||
|
|
.PN XtCallbackPopdown ,
|
||
|
|
.PN XtPopup ,
|
||
|
|
.PN XtCallbackNone ,
|
||
|
|
.PN XtCallbackNonexclusive ,
|
||
|
|
.PN XtCallbackExclusive ,
|
||
|
|
.PN XtPopupSpringLoaded
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
The return value of the following procedure will be of class
|
||
|
|
Core
|
||
|
|
or a subclass:
|
||
|
|
.sp
|
||
|
|
.IP
|
||
|
|
.PN XtWindowToWidget
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
The return value of the following procedures will be of a subclass of
|
||
|
|
Shell:
|
||
|
|
.sp
|
||
|
|
.IP
|
||
|
|
.PN XtAppCreateShell ,
|
||
|
|
.PN XtVaAppCreateShell ,
|
||
|
|
.PN XtAppInitialize ,
|
||
|
|
.PN XtVaAppInitialize ,
|
||
|
|
.PN XtCreatePopupShell ,
|
||
|
|
.PN XtVaCreatePopupShell
|
||
|
|
.bp
|