2472 lines
63 KiB
Plaintext
2472 lines
63 KiB
Plaintext
.\" $Xorg: CH01,v 1.3 2000/08/17 19:42:42 cpqbld Exp $
|
|
.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
|
|
.\" X Consortium
|
|
.\"
|
|
.\" Permission is hereby granted, free of charge, to any person obtaining
|
|
.\" a copy of this software and associated documentation files (the
|
|
.\" "Software"), to deal in the Software without restriction, including
|
|
.\" without limitation the rights to use, copy, modify, merge, publish,
|
|
.\" distribute, sublicense, and/or sell copies of the Software, and to
|
|
.\" permit persons to whom the Software is furnished to do so, subject to
|
|
.\" the following conditions:
|
|
.\"
|
|
.\" The above copyright notice and this permission notice shall be included
|
|
.\" in all copies or substantial portions of the Software.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
|
|
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
|
|
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
|
.\" OTHER DEALINGS IN THE SOFTWARE.
|
|
.\"
|
|
.\" Except as contained in this notice, the name of the X Consortium shall
|
|
.\" not be used in advertising or otherwise to promote the sale, use or
|
|
.\" other dealings in this Software without prior written authorization
|
|
.\" from the X Consortium.
|
|
.\"
|
|
.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
|
|
.\" Digital Equipment Corporation, Maynard, Massachusetts.
|
|
.\"
|
|
.\" Permission to use, copy, modify and distribute this documentation for any
|
|
.\" purpose and without fee is hereby granted, provided that the above copyright
|
|
.\" notice appears in all copies and that both that copyright notice and this
|
|
.\" permission notice appear in supporting documentation, and that the name of
|
|
.\" Digital not be used in in advertising or publicity pertaining
|
|
.\" to distribution of the software without specific, written prior permission.
|
|
.\" Digital makes no representations about the suitability of the
|
|
.\" software described herein for any purpose.
|
|
.\" It is provided ``as is'' without express or implied warranty.
|
|
.\"
|
|
\&
|
|
.sp 1
|
|
.ce 3
|
|
\s+1\fBChapter 1\fP\s-1
|
|
|
|
\s+1\fBIntrinsics and Widgets\fP\s-1
|
|
.sp 2
|
|
.if \n(GS .nr nh*hl 1
|
|
.nr H1 1
|
|
.nr H2 0
|
|
.nr H3 0
|
|
.nr H4 0
|
|
.nr H5 0
|
|
.LP
|
|
.XS
|
|
\fBChapter 1 \(em Intrinsics and Widgets\fP
|
|
.XE
|
|
The \*(xI are a programming library tailored to the special requirements
|
|
of user interface construction within a network window system,
|
|
specifically the X Window System.
|
|
The \*(xI and a widget set make up an \*(tk.
|
|
|
|
.NH 2
|
|
Intrinsics
|
|
.XS
|
|
\fB\*(SN Intrinsics\fP
|
|
.XE
|
|
.LP
|
|
The \*(xI provide the base mechanism necessary to build
|
|
a wide variety of interoperating widget sets and application environments.
|
|
The Intrinsics are a layer on top of Xlib, the
|
|
C Library X Interface. They extend the
|
|
fundamental abstractions provided by the X Window System while still
|
|
remaining independent of any particular user interface policy or
|
|
style.
|
|
.LP
|
|
The Intrinsics use object-oriented programming techniques to supply a
|
|
consistent architecture for constructing and composing user interface
|
|
components, known as widgets. This
|
|
allows programmers to extend a widget set in new ways, either by
|
|
deriving new widgets from existing ones (subclassing) or by writing
|
|
entirely new widgets following the established conventions.
|
|
.LP
|
|
When the \*(xI were first conceived, the root of the object
|
|
hierarchy was a widget class named
|
|
Core.
|
|
.IN "Core"
|
|
In Release 4 of the
|
|
\*(xI, three nonwidget superclasses were added above Core.
|
|
These superclasses are described in Chapter 12. The name of the class
|
|
now at the root of the Intrinsics class hierarchy is
|
|
Object.
|
|
.IN "Object"
|
|
The remainder of this
|
|
specification refers uniformly to \fIwidgets\fP and \fICore\fP
|
|
as if they were the
|
|
base class for all \*(xI operations. The argument descriptions
|
|
for each Intrinsics procedure and Chapter 12 describe which operations
|
|
are defined for the nonwidget superclasses of Core. The reader may
|
|
determine by context whether a specific reference to \fIwidget\fP
|
|
actually means ``widget'' or ``object.''
|
|
|
|
.NH 2
|
|
Languages
|
|
.XS
|
|
\fB\*(SN Languages\fP
|
|
.XE
|
|
.LP
|
|
The Intrinsics are intended to be used for two programming purposes.
|
|
Programmers writing widgets will be using most of the facilities
|
|
provided by the
|
|
Intrinsics to construct user interface components from the simple, such
|
|
as buttons and scrollbars, to the complex, such as control panels and
|
|
property sheets. Application programmers will use a much smaller subset of
|
|
the Intrinsics procedures in combination with one or more sets of widgets to
|
|
construct and present complete user interfaces on an X display. The
|
|
Intrinsics
|
|
programming interfaces primarily
|
|
intended for application use are designed to be callable from most
|
|
procedural programming languages. Therefore, most arguments are passed by
|
|
reference rather than by value. The interfaces primarily
|
|
intended for widget programmers are expected to be used principally
|
|
from the C language. In these cases, the usual C programming
|
|
conventions apply. In this specification, the term \fIclient\fP refers to
|
|
any module, widget, or application that calls an Intrinsics procedure.
|
|
.LP
|
|
Applications that use the \*(xI mechanisms
|
|
must include the header files
|
|
.Pn < X11/Intrinsic.h >
|
|
and
|
|
.Pn < X11/StringDefs.h >,
|
|
or their equivalent,
|
|
and they may also include
|
|
.Pn < X11/Xatoms.h >
|
|
and
|
|
.Pn < X11/Shell.h >.
|
|
In addition, widget implementations should include
|
|
.Pn < X11/IntrinsicP.h >
|
|
instead of
|
|
.Pn < X11/Intrinsic.h >.
|
|
.LP
|
|
The applications must also include the additional header files for
|
|
each widget class that they are to use (for example,
|
|
.Pn < X11/Xaw/Label.h >
|
|
or
|
|
.Pn < X11/Xaw/Scrollbar.h >).
|
|
On a POSIX-based system,
|
|
the \*(xI object library file is named
|
|
.PN libXt.a
|
|
and is usually referenced as \-lXt when linking the application.
|
|
|
|
.NH 2
|
|
Procedures and Macros
|
|
.LP
|
|
.XS
|
|
\fB\*(SN Procedures and Macros\fP
|
|
.XE
|
|
All functions defined in this specification except those specified below
|
|
may be implemented as C macros with arguments. C applications may use
|
|
``#undef'' to remove a macro definition and ensure that the actual function
|
|
is referenced. Any such macro will expand to a single expression that
|
|
has the same precedence as a function call and that evaluates each
|
|
of its arguments exactly once, fully protected by parentheses, so that
|
|
arbitrary expressions may be used as arguments.
|
|
.LP
|
|
The following symbols are macros that do not have function
|
|
equivalents and that may expand their arguments in a manner other
|
|
than that described above:
|
|
.PN XtCheckSubclass ,
|
|
.PN XtNew ,
|
|
.PN XtNumber ,
|
|
.PN XtOffsetOf ,
|
|
.PN XtOffset ,
|
|
and
|
|
.PN XtSetArg .
|
|
|
|
.NH 2
|
|
Widgets
|
|
.LP
|
|
.XS
|
|
\fB\*(SN Widgets\fP
|
|
.XE
|
|
.LP
|
|
The fundamental abstraction and data type of the \*(tk is the widget,
|
|
which is a combination of an X window and its associated
|
|
input and display semantics
|
|
and which is dynamically allocated and contains state information.
|
|
Some widgets display information (for example, text or graphics),
|
|
and others are merely containers for other widgets (for example, a menu box).
|
|
Some widgets are output-only and do not react to pointer or keyboard input,
|
|
and others change their display in response to input
|
|
and can invoke functions that an application has attached to them.
|
|
.LP
|
|
Every widget belongs to exactly one widget class, which is statically
|
|
allocated and initialized and which contains the operations allowable on
|
|
widgets of that class.
|
|
Logically, a widget class is the procedures and data associated
|
|
with all widgets belonging to that class.
|
|
These procedures and data can be inherited by
|
|
subclasses.
|
|
Physically, a widget class is a pointer to a structure.
|
|
The contents of this structure are constant for all widgets of the widget
|
|
class but will vary from class to class.
|
|
(Here, ``constant'' means the class structure is initialized at compile time
|
|
and never changed, except for a one-time class initialization
|
|
and in-place compilation of resource lists,
|
|
which takes place when the first widget of the class or subclass is created.)
|
|
For further information,
|
|
see Section 2.5.
|
|
.LP
|
|
The distribution of the declarations and code for a new widget class
|
|
among a public .h file for application programmer use, a private .h file
|
|
for widget programmer use,
|
|
and the implementation .c file is described in Section 1.6.
|
|
The predefined widget classes adhere to these conventions.
|
|
.LP
|
|
A widget instance is composed of two parts:
|
|
.IP \(bu 5
|
|
A data structure which contains instance-specific values.
|
|
.IP \(bu 5
|
|
A class structure which contains information that is applicable to
|
|
all widgets of that class.
|
|
.LP
|
|
Much of the input/output of a widget (for example, fonts, colors, sizes,
|
|
or border widths) is customizable by users.
|
|
.LP
|
|
This chapter discusses the base widget classes,
|
|
Core, Composite, and Constraint, and
|
|
ends with a discussion of widget classing.
|
|
|
|
.NH 3
|
|
Core Widgets
|
|
.XS
|
|
\*(SN Core Widgets
|
|
.XE
|
|
.LP
|
|
.IN "Core" "" "@DEF"
|
|
The
|
|
Core
|
|
widget class contains the definitions of fields common to all widgets.
|
|
All widgets classes are subclasses of the
|
|
Core class,
|
|
which is defined by the
|
|
.PN CoreClassPart
|
|
and
|
|
.PN CorePart
|
|
structures.
|
|
|
|
.NH 4
|
|
CoreClassPart Structure
|
|
.XS
|
|
\*(SN CoreClassPart Structure
|
|
.XE
|
|
.LP
|
|
All widget classes contain the fields defined in the
|
|
.PN CoreClassPart
|
|
structure.
|
|
.LP
|
|
.IN "CoreClassPart" "" "@DEF@"
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3.5i
|
|
.ta .5i 3.5i
|
|
typedef struct {
|
|
WidgetClass superclass; See Section 1.6
|
|
String class_name; See Chapter 9
|
|
Cardinal widget_size; See Section 1.6
|
|
XtProc class_initialize; See Section 1.6
|
|
XtWidgetClassProc class_part_initialize; See Section 1.6
|
|
XtEnum class_inited; See Section 1.6
|
|
XtInitProc initialize; See Section 2.5
|
|
XtArgsProc initialize_hook; See Section 2.5
|
|
XtRealizeProc realize; See Section 2.6
|
|
XtActionList actions; See Chapter 10
|
|
Cardinal num_actions; See Chapter 10
|
|
XtResourceList resources; See Chapter 9
|
|
Cardinal num_resources; See Chapter 9
|
|
XrmClass xrm_class; Private to resource manager
|
|
Boolean compress_motion; See Section 7.9
|
|
XtEnum compress_exposure; See Section 7.9
|
|
Boolean compress_enterleave; See Section 7.9
|
|
Boolean visible_interest; See Section 7.10
|
|
XtWidgetProc destroy; See Section 2.8
|
|
XtWidgetProc resize; See Chapter 6
|
|
XtExposeProc expose; See Section 7.10
|
|
XtSetValuesFunc set_values; See Section 9.7
|
|
XtArgsFunc set_values_hook; See Section 9.7
|
|
XtAlmostProc set_values_almost; See Section 9.7
|
|
XtArgsProc get_values_hook; See Section 9.7
|
|
XtAcceptFocusProc accept_focus; See Section 7.3
|
|
XtVersionType version; See Section 1.6
|
|
XtPointer callback_private; Private to callbacks
|
|
String tm_table; See Chapter 10
|
|
XtGeometryHandler query_geometry; See Chapter 6
|
|
XtStringProc display_accelerator; See Chapter 10
|
|
XtPointer extension; See Section 1.6
|
|
} CoreClassPart;
|
|
.De
|
|
.LP
|
|
.eM
|
|
All widget classes have the Core class fields as their first component.
|
|
The prototypical
|
|
.PN WidgetClass
|
|
and
|
|
.PN CoreWidgetClass
|
|
are defined with only this set of fields.
|
|
.LP
|
|
.IN "Core" "" "@DEF@"
|
|
.IN "WidgetClass" "" "@DEF@"
|
|
.IN "CoreWidgetClass" "" "@DEF@"
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct {
|
|
CoreClassPart core_class;
|
|
} WidgetClassRec, *WidgetClass, CoreClassRec, *CoreWidgetClass;
|
|
.De
|
|
.LP
|
|
.eM
|
|
Various routines can cast widget class pointers, as needed,
|
|
to specific widget class types.
|
|
.LP
|
|
The single occurrences of the class record and pointer for
|
|
creating instances of Core are
|
|
.LP
|
|
In
|
|
.PN IntrinsicP.h :
|
|
.LP
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
extern WidgetClassRec widgetClassRec;
|
|
#define coreClassRec widgetClassRec
|
|
.De
|
|
.LP
|
|
.eM
|
|
In
|
|
.PN Intrinsic.h :
|
|
.LP
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
extern WidgetClass widgetClass, coreWidgetClass;
|
|
.De
|
|
.LP
|
|
.eM
|
|
The opaque types
|
|
.PN Widget
|
|
and
|
|
.PN WidgetClass
|
|
and the opaque variable
|
|
.PN widgetClass
|
|
are defined for generic actions on widgets.
|
|
In order to make these types opaque and ensure that the compiler
|
|
does not allow applications to access private data, the \*(xI use
|
|
incomplete structure definitions in
|
|
.PN Intrinsic.h :
|
|
.LP
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct _WidgetClassRec *WidgetClass, *CoreWidgetClass;
|
|
.De
|
|
.eM
|
|
|
|
.NH 4
|
|
CorePart Structure
|
|
.XS
|
|
\*(SN CorePart Structure
|
|
.XE
|
|
.LP
|
|
All widget instances contain the fields defined in the
|
|
.PN CorePart
|
|
structure.
|
|
.LP
|
|
.IN "CorePart" "" "@DEF@"
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct _CorePart {
|
|
Widget self; Described below
|
|
WidgetClass widget_class; See Section 1.6
|
|
Widget parent; See Section 2.5
|
|
Boolean being_destroyed; See Section 2.8
|
|
XtCallbackList destroy_callbacks; See Section 2.8
|
|
XtPointer constraints; See Section 3.6
|
|
Position x; See Chapter 6
|
|
Position y; See Chapter 6
|
|
Dimension width; See Chapter 6
|
|
Dimension height; See Chapter 6
|
|
Dimension border_width; See Chapter 6
|
|
Boolean managed; See Chapter 3
|
|
Boolean sensitive; See Section 7.7
|
|
Boolean ancestor_sensitive; See Section 7.7
|
|
XtTranslations accelerators; See Chapter 10
|
|
Pixel border_pixel; See Section 2.6
|
|
Pixmap border_pixmap; See Section 2.6
|
|
WidgetList popup_list; See Chapter 5
|
|
Cardinal num_popups; See Chapter 5
|
|
String name; See Chapter 9
|
|
Screen *screen; See Section 2.6
|
|
Colormap colormap; See Section 2.6
|
|
Window window; See Section 2.6
|
|
Cardinal depth; See Section 2.6
|
|
Pixel background_pixel; See Section 2.6
|
|
Pixmap background_pixmap; See Section 2.6
|
|
Boolean visible; See Section 7.10
|
|
Boolean mapped_when_managed; See Chapter 3
|
|
} CorePart;
|
|
.De
|
|
.LP
|
|
.eM
|
|
All widget instances have the Core fields as their first component.
|
|
The prototypical type
|
|
.PN Widget
|
|
is defined with only this set of fields.
|
|
.LP
|
|
.IN "Widget" "" "@DEF@"
|
|
.IN "CoreWidget" "" "@DEF@"
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct {
|
|
CorePart core;
|
|
} WidgetRec, *Widget, CoreRec, *CoreWidget;
|
|
.De
|
|
.LP
|
|
.eM
|
|
Various routines can cast widget pointers, as needed,
|
|
to specific widget types.
|
|
.LP
|
|
In order to make these types opaque and ensure that the compiler
|
|
does not allow applications to access private data, the \*(xI use
|
|
incomplete structure definitions in
|
|
.PN Intrinsic.h .
|
|
.LP
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct _WidgetRec *Widget, *CoreWidget;
|
|
.De
|
|
.eM
|
|
|
|
.NH 4
|
|
Core Resources
|
|
.LP
|
|
.XS
|
|
\fB\*(SN Core Resources\fP
|
|
.XE
|
|
.LP
|
|
.IN "CoreWidget" "Resources"
|
|
The resource names, classes, and representation types specified in the
|
|
.PN coreClassRec
|
|
resource list are
|
|
.LP
|
|
.TS
|
|
lw(1.5i) lw(1.5i) lw(2.5i) .
|
|
_
|
|
.sp 6p
|
|
Name Class Representation
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
XtNaccelerators XtCAccelerators XtRAcceleratorTable
|
|
XtNbackground XtCBackground XtRPixel
|
|
XtNbackgroundPixmap XtCPixmap XtRPixmap
|
|
XtNborderColor XtCBorderColor XtRPixel
|
|
XtNborderPixmap XtCPixmap XtRPixmap
|
|
XtNcolormap XtCColormap XtRColormap
|
|
XtNdepth XtCDepth XtRInt
|
|
XtNmappedWhenManaged XtCMappedWhenManaged XtRBoolean
|
|
XtNscreen XtCScreen XtRScreen
|
|
XtNtranslations XtCTranslations XtRTranslationTable
|
|
.sp 6p
|
|
_
|
|
.TE
|
|
.LP
|
|
Additional resources are defined for all widgets via the
|
|
.PN objectClassRec
|
|
and
|
|
.PN rectObjClassRec
|
|
resource lists; see Sections 12.2 and 12.3 for details.
|
|
|
|
.NH 4
|
|
CorePart Default Values
|
|
.XS
|
|
\*(SN CorePart Default Values
|
|
.XE
|
|
.LP
|
|
The default values for the Core fields, which are filled in by the \*(xI,
|
|
from the resource lists, and by the initialize procedures, are
|
|
.LP
|
|
.TS
|
|
lw(1.5i) lw(4.25i) .
|
|
_
|
|
.sp 6p
|
|
Field Default Value
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
self Address of the widget structure (may not be changed).
|
|
T{
|
|
widget_class
|
|
T} T{
|
|
\fIwidget_class\fP argument to
|
|
.PN XtCreateWidget
|
|
(may not be changed).
|
|
T}
|
|
T{
|
|
parent
|
|
T} T{
|
|
\fIparent\fP argument to
|
|
.PN XtCreateWidget
|
|
(may not be changed).
|
|
T}
|
|
being_destroyed Parent's \fIbeing_destroyed\fP value.
|
|
destroy_callbacks NULL
|
|
constraints NULL
|
|
x 0
|
|
y 0
|
|
width 0
|
|
height 0
|
|
border_width 1
|
|
T{
|
|
managed
|
|
T} T{
|
|
.PN False
|
|
T}
|
|
T{
|
|
sensitive
|
|
T} T{
|
|
.PN True
|
|
T}
|
|
ancestor_sensitive T{
|
|
logical AND of parent's \fIsensitive\fP and
|
|
\fIancestor_sensitive\fP values.
|
|
T}
|
|
accelerators NULL
|
|
T{
|
|
border_pixel
|
|
T} T{
|
|
.PN XtDefaultForeground
|
|
T}
|
|
border_pixmap T{
|
|
.PN XtUnspecifiedPixmap
|
|
T}
|
|
popup_list NULL
|
|
num_popups 0
|
|
T{
|
|
name
|
|
T} T{
|
|
\fIname\fP argument to
|
|
.PN XtCreateWidget
|
|
(may not be changed).
|
|
T}
|
|
T{
|
|
screen
|
|
T} T{
|
|
Parent's \fIscreen\fP; top-level widget gets screen from display specifier
|
|
.br
|
|
(may not be changed).
|
|
T}
|
|
colormap Parent's \fIcolormap\fP value.
|
|
window NULL
|
|
depth Parent's \fIdepth\fP; top-level widget gets root window depth.
|
|
T{
|
|
background_pixel
|
|
T} T{
|
|
.PN XtDefaultBackground
|
|
T}
|
|
background_pixmap T{
|
|
.PN XtUnspecifiedPixmap
|
|
T}
|
|
T{
|
|
visible
|
|
T} T{
|
|
.PN True
|
|
T}
|
|
T{
|
|
mapped_when_managed
|
|
T} T{
|
|
.PN True
|
|
T}
|
|
.sp 6p
|
|
_
|
|
.TE
|
|
.LP
|
|
.IN XtUnspecifiedPixmap "" "@DEF@"
|
|
.PN XtUnspecifiedPixmap
|
|
is a symbolic constant guaranteed to be unequal to
|
|
any valid Pixmap id,
|
|
.PN None ,
|
|
and
|
|
.PN ParentRelative .
|
|
|
|
.NH 3
|
|
Composite Widgets
|
|
.XS
|
|
\*(SN Composite Widgets
|
|
.XE
|
|
.LP
|
|
.IN "Composite" "" "@DEF@"
|
|
The Composite
|
|
widget class is a subclass of the
|
|
Core
|
|
widget class (see Chapter 3).
|
|
Composite widgets are intended to be containers for other widgets.
|
|
The additional data used by composite widgets are defined by the
|
|
.PN CompositeClassPart
|
|
and
|
|
.PN CompositePart
|
|
structures.
|
|
|
|
.NH 4
|
|
CompositeClassPart Structure
|
|
.XS
|
|
\*(SN CompositeClassPart Structure
|
|
.XE
|
|
.LP
|
|
In addition to the
|
|
Core
|
|
class fields,
|
|
widgets of the Composite class have the following class fields.
|
|
.LP
|
|
.IN "CompositeClassPart" "" "@DEF@"
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3.5i
|
|
.ta .5i 3.5i
|
|
typedef struct {
|
|
XtGeometryHandler geometry_manager; See Chapter 6
|
|
XtWidgetProc change_managed; See Chapter 3
|
|
XtWidgetProc insert_child; See Chapter 3
|
|
XtWidgetProc delete_child; See Chapter 3
|
|
XtPointer extension; See Section 1.6
|
|
} CompositeClassPart;
|
|
.De
|
|
.LP
|
|
.eM
|
|
The extension record defined for
|
|
.PN CompositeClassPart
|
|
with \fIrecord_type\fP
|
|
equal to
|
|
.PN \s-1NULLQUARK\s+1
|
|
is
|
|
.PN CompositeClassExtensionRec .
|
|
.LP
|
|
.IN "CompositeClassExtensionRec" "" "@DEF@"
|
|
.IN "CompositeClassExtension" "" "@DEF@"
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3.5i
|
|
.ta .5i 3.5i
|
|
typedef struct {
|
|
XtPointer next_extension; See Section 1.6.12
|
|
XrmQuark record_type; See Section 1.6.12
|
|
long version; See Section 1.6.12
|
|
Cardinal record_size; See Section 1.6.12
|
|
Boolean accepts_objects; See Section 2.5.2
|
|
Boolean allows_change_managed_set; See Section 3.4.3
|
|
} CompositeClassExtensionRec, *CompositeClassExtension;
|
|
.De
|
|
.LP
|
|
.eM
|
|
Composite
|
|
classes have the Composite class fields immediately following the
|
|
Core class fields.
|
|
.LP
|
|
.IN "CompositeWidgetClass" "" "@DEF@"
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct {
|
|
CoreClassPart core_class;
|
|
CompositeClassPart composite_class;
|
|
} CompositeClassRec, *CompositeWidgetClass;
|
|
.De
|
|
.LP
|
|
.eM
|
|
The single occurrences of the class record and pointer for creating
|
|
instances of Composite are
|
|
.LP
|
|
In
|
|
.PN IntrinsicP.h :
|
|
.LP
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
extern CompositeClassRec compositeClassRec;
|
|
.De
|
|
.LP
|
|
.eM
|
|
In
|
|
.PN Intrinsic.h :
|
|
.LP
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
extern WidgetClass compositeWidgetClass;
|
|
.De
|
|
.LP
|
|
.eM
|
|
The opaque types
|
|
.PN CompositeWidget
|
|
and
|
|
.PN CompositeWidgetClass
|
|
and the opaque variable
|
|
.PN compositeWidgetClass
|
|
are defined for generic operations on widgets whose class
|
|
is Composite or a subclass of Composite.
|
|
The symbolic constant for the
|
|
.PN CompositeClassExtension
|
|
version identifier is
|
|
.PN XtCompositeExtensionVersion
|
|
(see Section 1.6.12).
|
|
.PN Intrinsic.h
|
|
uses an incomplete structure
|
|
definition to ensure that the compiler catches attempts to access
|
|
private data.
|
|
.LP
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct _CompositeClassRec *CompositeWidgetClass;
|
|
.De
|
|
.eM
|
|
|
|
.NH 4
|
|
CompositePart Structure
|
|
.XS
|
|
\*(SN CompositePart Structure
|
|
.XE
|
|
.LP
|
|
In addition to the
|
|
Core instance
|
|
fields,
|
|
widgets of the Composite class have the following
|
|
instance fields defined in the
|
|
.PN CompositePart
|
|
structure.
|
|
.LP
|
|
.IN "CompositePart" "" "@DEF@"
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct {
|
|
WidgetList children; See Chapter 3
|
|
Cardinal num_children; See Chapter 3
|
|
Cardinal num_slots; See Chapter 3
|
|
XtOrderProc insert_position; See Section 3.2
|
|
} CompositePart;
|
|
.De
|
|
.LP
|
|
.eM
|
|
Composite
|
|
widgets have the Composite instance fields immediately following the Core
|
|
instance fields.
|
|
.LP
|
|
.IN "CompositeWidget" "" "@DEF@"
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct {
|
|
CorePart core;
|
|
CompositePart composite;
|
|
} CompositeRec, *CompositeWidget;
|
|
.De
|
|
.LP
|
|
.eM
|
|
.PN Intrinsic.h
|
|
uses an incomplete structure definition to ensure that the
|
|
compiler catches attempts to access private data.
|
|
.LP
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct _CompositeRec *CompositeWidget;
|
|
.De
|
|
.eM
|
|
|
|
.NH 4
|
|
Composite Resources
|
|
.XS
|
|
\fB\*(SN Composite Resources\fP
|
|
.XE
|
|
.LP
|
|
.IN "CompositeWidget" "Resources"
|
|
The resource names, classes, and representation types
|
|
that are specified in
|
|
the
|
|
.PN compositeClassRec
|
|
resource list are
|
|
.LP
|
|
.TS
|
|
lw(1.5i) lw(1.5i) lw(2i) .
|
|
_
|
|
.sp 6p
|
|
Name Class Representation
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
XtNchildren XtCReadOnly XtRWidgetList
|
|
XtNinsertPosition XtCInsertPosition XtRFunction
|
|
XtNnumChildren XtCReadOnly XtRCardinal
|
|
.sp 6p
|
|
_
|
|
.TE
|
|
|
|
.NH 4
|
|
CompositePart Default Values
|
|
.XS
|
|
\*(SN CompositePart Default Values
|
|
.XE
|
|
.LP
|
|
The default values for the Composite fields,
|
|
which are filled in from the
|
|
Composite
|
|
resource list and by the
|
|
Composite
|
|
initialize procedure, are
|
|
.LP
|
|
.TS
|
|
l l .
|
|
_
|
|
.sp 6p
|
|
Field Default Value
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
children NULL
|
|
num_children 0
|
|
num_slots 0
|
|
insert_position Internal function to insert at end
|
|
.sp 6p
|
|
_
|
|
.TE
|
|
.LP
|
|
The \fIchildren\fP, \fInum_children\fP,
|
|
and \fIinsert_position\fP fields are declared
|
|
as resources;
|
|
.IN XtNinsertPosition
|
|
XtNinsertPosition
|
|
is a settable resource,
|
|
.IN XtNchildren
|
|
XtNchildren
|
|
and
|
|
.IN XtNnumChildren
|
|
XtNnumChildren
|
|
may be read by any client but should only be modified by the composite
|
|
widget class procedures.
|
|
|
|
.NH 3
|
|
Constraint Widgets
|
|
.XS
|
|
\*(SN Constraint Widgets
|
|
.XE
|
|
.LP
|
|
.IN "Constraint" "" "@DEF@"
|
|
The Constraint
|
|
widget class is a subclass of the
|
|
Composite
|
|
widget class (see Section 3.6). Constraint
|
|
widgets maintain additional state
|
|
data for each child; for example, client-defined constraints on the child's
|
|
geometry.
|
|
The additional data used by constraint widgets are defined by the
|
|
.PN ConstraintClassPart
|
|
and
|
|
.PN ConstraintPart
|
|
structures.
|
|
|
|
.NH 4
|
|
ConstraintClassPart Structure
|
|
.XS
|
|
\*(SN ConstraintClassPart Structure
|
|
.XE
|
|
.LP
|
|
In addition to the
|
|
Core
|
|
and
|
|
Composite
|
|
class fields,
|
|
widgets of the Constraint class
|
|
have the following class fields.
|
|
.LP
|
|
.IN "ConstraintClassPart" "" "@DEF@"
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct {
|
|
XtResourceList resources; See Chapter 9
|
|
Cardinal num_resources; See Chapter 9
|
|
Cardinal constraint_size; See Section 3.6
|
|
XtInitProc initialize; See Section 3.6
|
|
XtWidgetProc destroy; See Section 3.6
|
|
XtSetValuesFunc set_values; See Section 9.7.2
|
|
XtPointer extension; See Section 1.6
|
|
} ConstraintClassPart;
|
|
.De
|
|
.LP
|
|
.eM
|
|
The extension record defined for
|
|
.PN ConstraintClassPart
|
|
with \fIrecord_type\fP equal to
|
|
.PN \s-1NULLQUARK\s+1
|
|
is
|
|
.PN ConstraintClassExtensionRec .
|
|
.LP
|
|
.IN "ConstraintClassExtensionRec" "" "@DEF@"
|
|
.IN "ConstraintClassExtension" "" "@DEF@"
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct {
|
|
XtPointer next_extension; See Section 1.6.12
|
|
XrmQuark record_type; See Section 1.6.12
|
|
long version; See Section 1.6.12
|
|
Cardinal record_size; See Section 1.6.12
|
|
XtArgsProc get_values_hook; See Section 9.7.1
|
|
} ConstraintClassExtensionRec, *ConstraintClassExtension;
|
|
.De
|
|
.LP
|
|
.eM
|
|
Constraint
|
|
classes have the Constraint class fields immediately following the
|
|
Composite class fields.
|
|
.LP
|
|
.IN "ConstraintWidgetClass" "" "@DEF@"
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct _ConstraintClassRec {
|
|
CoreClassPart core_class;
|
|
CompositeClassPart composite_class;
|
|
ConstraintClassPart constraint_class;
|
|
} ConstraintClassRec, *ConstraintWidgetClass;
|
|
.De
|
|
.LP
|
|
.eM
|
|
The single occurrences of the class record and pointer for creating
|
|
instances of Constraint are
|
|
.LP
|
|
In
|
|
.PN IntrinsicP.h :
|
|
.LP
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
extern ConstraintClassRec constraintClassRec;
|
|
.De
|
|
.LP
|
|
.eM
|
|
In
|
|
.PN Intrinsic.h :
|
|
.LP
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
extern WidgetClass constraintWidgetClass;
|
|
.De
|
|
.LP
|
|
.eM
|
|
The opaque types
|
|
.PN ConstraintWidget
|
|
and
|
|
.PN ConstraintWidgetClass
|
|
and the opaque variable
|
|
.PN constraintWidgetClass
|
|
are defined for generic operations on widgets
|
|
whose class is Constraint or a subclass
|
|
of Constraint.
|
|
The symbolic constant for the
|
|
.PN ConstraintClassExtension
|
|
version identifier is
|
|
.PN XtConstraintExtensionVersion
|
|
(see Section 1.6.12).
|
|
.PN Intrinsic.h
|
|
uses an incomplete structure definition to ensure that the
|
|
compiler catches attempts to access private data.
|
|
.LP
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct _ConstraintClassRec *ConstraintWidgetClass;
|
|
.De
|
|
.eM
|
|
|
|
.NH 4
|
|
ConstraintPart Structure
|
|
.XS
|
|
\*(SN ConstraintPart Structure
|
|
.XE
|
|
.LP
|
|
In addition to the
|
|
Core
|
|
and
|
|
Composite instance
|
|
fields,
|
|
widgets of the Constraint class have the following unused
|
|
instance fields defined in the
|
|
.PN ConstraintPart
|
|
structure
|
|
.LP
|
|
.IN "ConstraintPart" "" "@DEF@"
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct {
|
|
int empty;
|
|
} ConstraintPart;
|
|
.De
|
|
.LP
|
|
.eM
|
|
Constraint
|
|
widgets have the Constraint instance fields immediately following the
|
|
Composite instance fields.
|
|
.LP
|
|
.IN "ConstraintWidget" "" "@DEF@"
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct {
|
|
CorePart core;
|
|
CompositePart composite;
|
|
ConstraintPart constraint;
|
|
} ConstraintRec, *ConstraintWidget;
|
|
.De
|
|
.LP
|
|
.eM
|
|
.PN Intrinsic.h
|
|
uses an incomplete structure definition to ensure that the
|
|
compiler catches attempts to access private data.
|
|
.LP
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct _ConstraintRec *ConstraintWidget;
|
|
.De
|
|
.eM
|
|
|
|
.NH 4
|
|
Constraint Resources
|
|
.XS
|
|
\fB\*(SN Constraint Resources\fP
|
|
.XE
|
|
.LP
|
|
The
|
|
.PN constraintClassRec
|
|
\fIcore_class\fP and \fIconstraint_class resources\fP fields are NULL,
|
|
and the \fInum_resources\fP fields are zero;
|
|
no additional resources beyond those declared by
|
|
the superclasses
|
|
are defined for
|
|
Constraint.
|
|
|
|
.NH 2
|
|
Implementation-Specific Types
|
|
.XS
|
|
\fB\*(SN Implementation-Specific Types\fP
|
|
.XE
|
|
.LP
|
|
To increase the portability of widget and application source code
|
|
between different system environments, the \*(xI define several
|
|
types whose precise representation is explicitly dependent upon,
|
|
and chosen by, each individual implementation of the \*(xI.
|
|
.LP
|
|
These implementation-defined types are
|
|
.IN "Boolean" "" "@DEF@"
|
|
.IP \fBBoolean\fP 11
|
|
A datum that contains a zero or nonzero value.
|
|
Unless explicitly stated, clients should not assume
|
|
that the nonzero value is equal to the symbolic
|
|
value
|
|
.PN True .
|
|
.IN "Cardinal" "" "@DEF@"
|
|
.IP \fBCardinal\fP 11
|
|
An unsigned integer datum with a minimum range of [0..2^16-1].
|
|
.IN "Dimension" "" "@DEF@"
|
|
.IP \fBDimension\fP 11
|
|
An unsigned integer datum with a minimum range of [0..2^16-1].
|
|
.IN "Position" "" "@DEF@"
|
|
.IP \fBPosition\fP 11
|
|
A signed integer datum with a minimum range of [-2^15..2^15-1].
|
|
.IN "XtPointer" "" "@DEF@"
|
|
.IP \fBXtPointer\fP 11
|
|
A datum large enough to contain the largest of a char*, int*, function
|
|
pointer, structure pointer, or long value. A pointer
|
|
to any type or function, or a long value may be converted
|
|
to an
|
|
.PN XtPointer
|
|
and back again and the result will
|
|
compare equal to the original value. In ANSI C
|
|
environments it is expected that
|
|
.PN XtPointer
|
|
will be
|
|
defined as void*.
|
|
.IN "XtArgVal" "" "@DEF@"
|
|
.IP \fBXtArgVal\fP 11
|
|
A datum large enough to contain an
|
|
.PN XtPointer ,
|
|
.PN Cardinal ,
|
|
.PN Dimension ,
|
|
or
|
|
.PN Position
|
|
value.
|
|
.IN "XtEnum" "" "@DEF@"
|
|
.IP \fBXtEnum\fP 11
|
|
An integer datum large enough to encode at least 128 distinct
|
|
values, two of which are the symbolic values
|
|
.PN True
|
|
and
|
|
.PN False .
|
|
The symbolic values
|
|
.PN \s-1TRUE\s+1
|
|
and
|
|
.PN \s-1FALSE\s+1
|
|
are
|
|
also defined to be equal to
|
|
.PN True
|
|
and
|
|
.PN False ,
|
|
respectively.
|
|
.LP
|
|
In addition to these specific types, the precise order of the
|
|
fields within the structure declarations for any of the instance
|
|
part records
|
|
.PN ObjectPart ,
|
|
.PN RectObjPart ,
|
|
.PN CorePart ,
|
|
.PN CompositePart ,
|
|
.PN ShellPart ,
|
|
.PN WMShellPart ,
|
|
.PN TopLevelShellPart ,
|
|
and
|
|
.PN ApplicationShellPart
|
|
is implementation-defined. These
|
|
structures may also have additional private
|
|
fields internal to the implementation.
|
|
The
|
|
.PN ObjectPart ,
|
|
.PN RectObjPart ,
|
|
and
|
|
.PN CorePart
|
|
structures must be defined so that any member with the same name
|
|
appears at the same offset in
|
|
.PN ObjectRec ,
|
|
.PN RectObjRec ,
|
|
and
|
|
.PN CoreRec
|
|
.Pn ( WidgetRec ).
|
|
No other relations between the offsets of any two
|
|
fields may be assumed.
|
|
|
|
.NH 2
|
|
Widget Classing
|
|
.LP
|
|
.XS
|
|
\fB\*(SN Widget Classing\fP
|
|
.XE
|
|
.IN "widget_class" "" "@DEF@"
|
|
The \fIwidget_class\fP field of a widget points to its widget class structure,
|
|
which contains information that is constant across all widgets of that class.
|
|
As a consequence,
|
|
widgets usually do not implement directly callable procedures;
|
|
rather, they implement procedures, called methods, that are available through
|
|
their widget class structure.
|
|
These methods are invoked by generic procedures that envelop common actions
|
|
around the methods implemented by the widget class.
|
|
Such procedures are applicable to all widgets
|
|
of that class and also to widgets whose classes are subclasses of that class.
|
|
.LP
|
|
All widget classes are a subclass of
|
|
Core
|
|
and can be subclassed further.
|
|
Subclassing reduces the amount of code and declarations
|
|
necessary to make a
|
|
new widget class that is similar to an existing class.
|
|
For example, you do not have to describe every resource your widget uses in an
|
|
.PN XtResourceList .
|
|
Instead, you describe only the resources your widget has
|
|
that its superclass does not.
|
|
Subclasses usually inherit many of their superclasses' procedures
|
|
(for example, the expose procedure or geometry handler).
|
|
.LP
|
|
Subclassing, however, can be taken too far.
|
|
If you create a subclass that inherits none of the procedures of its
|
|
superclass,
|
|
you should consider whether you have chosen the most
|
|
appropriate superclass.
|
|
.LP
|
|
To make good use of subclassing,
|
|
widget declarations and naming conventions are highly stylized.
|
|
A widget consists of three files:
|
|
.IP \(bu 5
|
|
A public .h file, used by client widgets or applications.
|
|
.IP \(bu 5
|
|
A private .h file, used by widgets whose classes
|
|
are subclasses of the widget class.
|
|
.IP \(bu 5
|
|
A .c file, which implements the widget.
|
|
|
|
.NH 3
|
|
Widget Naming Conventions
|
|
.XS
|
|
\fB\*(SN Widget Naming Conventions\fP
|
|
.XE
|
|
.LP
|
|
The \*(xI provide a vehicle by which programmers can create
|
|
new widgets and organize a collection of widgets into an application.
|
|
To ensure that applications need not deal with as many styles of capitalization
|
|
and spelling as the number of widget classes it uses,
|
|
the following guidelines should be followed when writing new widgets:
|
|
.IP \(bu 5
|
|
Use the X library naming conventions that are applicable.
|
|
For example, a record component name is all lowercase
|
|
and uses underscores (_) for compound words (for example, background_pixmap).
|
|
Type and procedure names start with uppercase and use capitalization for
|
|
compound words (for example,
|
|
.PN ArgList
|
|
or
|
|
.PN XtSetValues ).
|
|
.IP \(bu 5
|
|
A resource name is spelled identically to the field name
|
|
except that compound names use capitalization rather than underscore.
|
|
To let the compiler catch spelling errors,
|
|
each resource name should have a symbolic identifier prefixed with
|
|
``XtN''.
|
|
For example,
|
|
the \fIbackground_pixmap\fP field has the corresponding identifier
|
|
XtNbackgroundPixmap,
|
|
which is defined as the string ``backgroundPixmap''.
|
|
Many predefined names are listed in
|
|
.Pn < X11/StringDefs.h >.
|
|
Before you invent a new name,
|
|
you should make sure there is not already a name that you can use.
|
|
.IP \(bu 5
|
|
A resource class string starts with a capital letter
|
|
and uses capitalization for compound names (for example,``BorderWidth'').
|
|
Each resource class string should have a symbolic identifier prefixed with
|
|
``XtC''
|
|
(for example, XtCBorderWidth).
|
|
Many predefined classes are listed in
|
|
.Pn < X11/StringDefs.h >.
|
|
.IP \(bu 5
|
|
A resource representation string is spelled identically to the type name
|
|
(for example, ``TranslationTable'').
|
|
Each representation string should have a symbolic identifier prefixed with
|
|
``XtR''
|
|
(for example, XtRTranslationTable).
|
|
Many predefined representation types are listed in
|
|
.Pn < X11/StringDefs.h >.
|
|
.IP \(bu 5
|
|
New widget classes start with a capital and use uppercase for compound
|
|
words.
|
|
Given a new class name AbcXyz, you should derive several names:
|
|
.RS
|
|
.IP \- 5
|
|
Additional widget instance structure part name AbcXyzPart.
|
|
.IP \- 5
|
|
Complete widget instance structure names AbcXyzRec and _AbcXyzRec.
|
|
.IP \- 5
|
|
Widget instance structure pointer type name AbcXyzWidget.
|
|
.IP \- 5
|
|
Additional class structure part name AbcXyzClassPart.
|
|
.IP \- 5
|
|
Complete class structure names AbcXyzClassRec and _AbcXyzClassRec.
|
|
.IP \- 5
|
|
Class structure pointer type name AbcXyzWidgetClass.
|
|
.IP \- 5
|
|
Class structure variable abcXyzClassRec.
|
|
.IP \- 5
|
|
Class structure pointer variable abcXyzWidgetClass.
|
|
.RE
|
|
.IP \(bu 5
|
|
Action procedures available to translation specifications should follow the
|
|
same naming conventions as procedures.
|
|
That is,
|
|
they start with a capital letter, and compound names use uppercase
|
|
(for example, ``Highlight'' and ``NotifyClient'').
|
|
.LP
|
|
The symbolic identifiers XtN..., XtC..., and XtR...
|
|
may be implemented
|
|
as macros, as global symbols, or as a mixture of the two. The
|
|
(implicit) type of the identifier is
|
|
.PN String .
|
|
The pointer value itself
|
|
is not significant; clients must not assume that inequality of two
|
|
identifiers implies inequality of the resource name, class, or
|
|
representation string. Clients should also note that although global
|
|
symbols permit savings in literal storage in some environments, they
|
|
also introduce the possibility of multiple definition conflicts when
|
|
applications attempt to use independently developed widgets
|
|
simultaneously.
|
|
|
|
.NH 3
|
|
Widget Subclassing in Public .h Files
|
|
.XS
|
|
\*(SN Widget Subclassing in Public .h Files
|
|
.XE
|
|
.LP
|
|
The public .h file for a widget class is imported by clients
|
|
and contains
|
|
.IP \(bu 5
|
|
A reference to the public .h file for the superclass.
|
|
.IP \(bu 5
|
|
Symbolic identifiers for
|
|
the names and classes of the new resources that this widget adds
|
|
to its superclass.
|
|
The definitions should
|
|
have a single space between the definition name and the value and no
|
|
trailing space or comment in order to reduce the possibility of
|
|
compiler warnings from similar declarations in multiple classes.
|
|
.IP \(bu 5
|
|
Type declarations for any new resource data types defined by the class.
|
|
.IP \(bu 5
|
|
The class record pointer variable used to create widget instances.
|
|
.IP \(bu 5
|
|
The C type that corresponds to widget instances of this class.
|
|
.IP \(bu 5
|
|
Entry points for new class methods.
|
|
.LP
|
|
For example, the following is the public .h file for a possible
|
|
implementation of a Label widget:
|
|
.LP
|
|
.Ds
|
|
.TA .5i 1.75i
|
|
.ta .5i 1.75i
|
|
#ifndef LABEL_H
|
|
#define LABEL_H
|
|
|
|
/* New resources */
|
|
#define XtNjustify "justify"
|
|
#define XtNforeground "foreground"
|
|
#define XtNlabel "label"
|
|
#define XtNfont "font"
|
|
#define XtNinternalWidth "internalWidth"
|
|
#define XtNinternalHeight "internalHeight"
|
|
|
|
/* Class record pointer */
|
|
extern WidgetClass labelWidgetClass;
|
|
|
|
/* C Widget type definition */
|
|
typedef struct _LabelRec *LabelWidget;
|
|
|
|
/* New class method entry points */
|
|
extern void LabelSetText();
|
|
/* Widget w */
|
|
/* String text */
|
|
|
|
extern String LabelGetText();
|
|
/* Widget w */
|
|
|
|
#endif LABEL_H
|
|
.De
|
|
.LP
|
|
The conditional inclusion of the text allows the application
|
|
to include header files for different widgets without being concerned
|
|
that they already may be included as a superclass of another widget.
|
|
.LP
|
|
To accommodate operating systems with file name length restrictions,
|
|
the name of the public .h file is the first ten characters of the
|
|
widget class.
|
|
For example,
|
|
the public .h file for the
|
|
Constraint
|
|
widget class is
|
|
.PN Constraint.h .
|
|
|
|
.NH 3
|
|
Widget Subclassing in Private .h Files
|
|
.XS
|
|
\*(SN Widget Subclassing in Private .h Files
|
|
.XE
|
|
.LP
|
|
The private .h file for a widget is imported by widget classes that are
|
|
subclasses of the widget and contains
|
|
.IP \(bu 5
|
|
A reference to the public .h file for the class.
|
|
.IP \(bu 5
|
|
A reference to the private .h file for the superclass.
|
|
.IP \(bu 5
|
|
Symbolic identifiers for any new resource representation types defined
|
|
by the class. The definitions should have a single space between the
|
|
definition name and the value and no trailing space or comment.
|
|
.IP \(bu 5
|
|
A structure part definition for
|
|
the new fields that the widget instance adds to its superclass's
|
|
widget structure.
|
|
.IP \(bu 5
|
|
The complete widget instance structure definition for this widget.
|
|
.IP \(bu 5
|
|
A structure part definition for
|
|
the new fields that this widget class adds to its superclass's
|
|
constraint
|
|
structure if the widget class is a subclass of
|
|
Constraint.
|
|
.IP \(bu 5
|
|
The complete
|
|
constraint
|
|
structure definition if the widget class is a subclass of
|
|
Constraint.
|
|
.IP \(bu 5
|
|
Type definitions for any new procedure types used by class methods
|
|
declared in the widget class part.
|
|
.IP \(bu 5
|
|
A structure part definition for
|
|
the new fields that this widget class adds to its superclass's widget class
|
|
structure.
|
|
.IP \(bu 5
|
|
The complete widget class structure definition for this widget.
|
|
.IP \(bu 5
|
|
The complete widget class extension structure definition
|
|
for this widget, if any.
|
|
.IP \(bu 5
|
|
The symbolic constant identifying the class extension version, if any.
|
|
.IP \(bu 5
|
|
The name of the global class structure variable containing the generic
|
|
class structure for this class.
|
|
.IP \(bu 5
|
|
An inherit constant for each new procedure in the widget class part structure.
|
|
.LP
|
|
For example, the following is the private .h file for a possible Label widget:
|
|
.LP
|
|
.Ds
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
#ifndef LABELP_H
|
|
#define LABELP_H
|
|
|
|
#include <X11/Label.h>
|
|
|
|
/* New representation types used by the Label widget */
|
|
#define XtRJustify "Justify"
|
|
|
|
/* New fields for the Label widget record */
|
|
typedef struct {
|
|
/* Settable resources */
|
|
Pixel foreground;
|
|
XFontStruct *font;
|
|
String label; /* text to display */
|
|
XtJustify justify;
|
|
Dimension internal_width; /* # pixels horizontal border */
|
|
Dimension internal_height; /* # pixels vertical border */
|
|
|
|
/* Data derived from resources */
|
|
GC normal_GC;
|
|
GC gray_GC;
|
|
Pixmap gray_pixmap;
|
|
Position label_x;
|
|
Position label_y;
|
|
Dimension label_width;
|
|
Dimension label_height;
|
|
Cardinal label_len;
|
|
Boolean display_sensitive;
|
|
} LabelPart;
|
|
.De
|
|
.sp
|
|
.Ds
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
/* Full instance record declaration */
|
|
typedef struct _LabelRec {
|
|
CorePart core;
|
|
LabelPart label;
|
|
} LabelRec;
|
|
|
|
/* Types for Label class methods */
|
|
typedef void (*LabelSetTextProc)();
|
|
/* Widget w */
|
|
/* String text */
|
|
|
|
typedef String (*LabelGetTextProc)();
|
|
/* Widget w */
|
|
|
|
/* New fields for the Label widget class record */
|
|
typedef struct {
|
|
LabelSetTextProc set_text;
|
|
LabelGetTextProc get_text;
|
|
XtPointer extension;
|
|
} LabelClassPart;
|
|
|
|
/* Full class record declaration */
|
|
typedef struct _LabelClassRec {
|
|
CoreClassPart core_class;
|
|
LabelClassPart label_class;
|
|
} LabelClassRec;
|
|
|
|
/* Class record variable */
|
|
extern LabelClassRec labelClassRec;
|
|
|
|
#define LabelInheritSetText((LabelSetTextProc)_XtInherit)
|
|
#define LabelInheritGetText((LabelGetTextProc)_XtInherit)
|
|
#endif LABELP_H
|
|
.De
|
|
.LP
|
|
To accommodate operating systems with file name length restrictions,
|
|
the name of the private .h file is the first nine characters of the
|
|
widget class followed by a capital P.
|
|
For example,
|
|
the private .h file for the
|
|
Constraint
|
|
widget class is
|
|
.PN ConstrainP.h .
|
|
|
|
.NH 3
|
|
Widget Subclassing in .c Files
|
|
.XS
|
|
\*(SN Widget Subclassing in .c Files
|
|
.XE
|
|
.LP
|
|
The .c file for a widget contains the structure initializer
|
|
for the class record variable,
|
|
which contains the following parts:
|
|
.IP \(bu 5
|
|
Class information (for example, \fIsuperclass\fP, \fIclass_name\fP,
|
|
\fIwidget_size\fP,
|
|
\fIclass_initialize\fP, and \fIclass_inited\fP).
|
|
.IP \(bu 5
|
|
Data constants (for example, \fIresources\fP and \fInum_resources\fP,
|
|
\fIactions\fP and \fInum_actions\fP, \fIvisible_interest\fP,
|
|
\fIcompress_motion\fP,
|
|
\fIcompress_exposure\fP, and \fIversion\fP).
|
|
.IP \(bu 5
|
|
Widget operations (for example, \fIinitialize\fP, \fIrealize\fP, \fIdestroy\fP,
|
|
\fIresize\fP, \fIexpose\fP, \fIset_values\fP, \fIaccept_focus\fP,
|
|
and any new operations specific to
|
|
the widget).
|
|
.LP
|
|
.IN "superclass" "" "@DEF@"
|
|
The \fIsuperclass\fP field points to the superclass
|
|
global class
|
|
record, declared in the superclass private .h file.
|
|
For direct subclasses of the generic core widget,
|
|
\fIsuperclass\fP should be initialized to the address of the
|
|
.PN widgetClassRec
|
|
structure.
|
|
The superclass is used for class chaining operations and for
|
|
inheriting or enveloping a superclass's operations
|
|
(see Sections 1.6.7, 1.6.9, and 1.6.10).
|
|
.LP
|
|
.IN "class_name" "" "@DEF@"
|
|
The \fIclass_name\fP field contains the text name for this class,
|
|
which is used by
|
|
the resource manager.
|
|
For example, the Label widget has the string ``Label''.
|
|
More than one widget class can share the same text class name.
|
|
This string must be permanently allocated prior to or during the
|
|
execution of the class initialization procedure and must not be
|
|
subsequently deallocated.
|
|
|
|
.LP
|
|
.IN "widget_size" "" "@DEF@"
|
|
The \fIwidget_size\fP field is the size of the corresponding widget
|
|
instance structure
|
|
(not the size of the class structure).
|
|
.LP
|
|
.IN "version" "" "@DEF@"
|
|
The \fIversion\fP field indicates the toolkit
|
|
implementation version number and is used for
|
|
runtime consistency checking of the \*(tk and widgets in an application.
|
|
Widget writers must set it to the
|
|
implementation-defined symbolic value
|
|
.PN XtVersion
|
|
in the widget class structure initialization.
|
|
Those widget writers who believe that their widget binaries are compatible
|
|
with other implementations of the \*(xI can put the special value
|
|
.PN XtVersionDontCheck
|
|
in the \fIversion\fP field to disable version checking for those widgets.
|
|
If a widget needs to compile alternative code for different
|
|
revisions of the \*(xI interface definition, it may use the symbol
|
|
.PN XtSpecificationRelease ,
|
|
as described in Chapter 13.
|
|
Use of
|
|
.PN XtVersion
|
|
allows the \*(xI implementation to recognize widget binaries
|
|
that were compiled with older implementations.
|
|
.LP
|
|
The \fIextension\fP field is for future upward compatibility.
|
|
If the widget programmer adds fields to class parts,
|
|
all subclass structure layouts change,
|
|
requiring complete recompilation.
|
|
To allow clients to avoid recompilation,
|
|
an extension field at the end of each class part can point to a record
|
|
that contains any additional class information required.
|
|
.LP
|
|
All other fields are described in their respective sections.
|
|
.LP
|
|
The .c file also contains the declaration of the global class
|
|
structure pointer variable used to create instances of the class.
|
|
The following is an abbreviated version of the .c file
|
|
for a Label widget.
|
|
The resources table is described in Chapter 9.
|
|
.LP
|
|
.Ds
|
|
.TA .5i 1.5i 3i
|
|
.ta .5i 1.5i 3i
|
|
|
|
/* Resources specific to Label */
|
|
static XtResource resources[] = {
|
|
{XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel),
|
|
XtOffset(LabelWidget, label.foreground), XtRString,
|
|
XtDefaultForeground},
|
|
{XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct *),
|
|
XtOffset(LabelWidget, label.font),XtRString,
|
|
XtDefaultFont},
|
|
{XtNlabel, XtCLabel, XtRString, sizeof(String),
|
|
XtOffset(LabelWidget, label.label), XtRString, NULL},
|
|
.
|
|
.
|
|
.
|
|
}
|
|
|
|
/* Forward declarations of procedures */
|
|
static void ClassInitialize();
|
|
static void Initialize();
|
|
static void Realize();
|
|
static void SetText();
|
|
static void GetText();
|
|
.
|
|
.
|
|
.
|
|
.De
|
|
.sp
|
|
.Ds
|
|
.TA .5i 2i 3i
|
|
.ta .5i 2i 3i
|
|
/* Class record constant */
|
|
LabelClassRec labelClassRec = {
|
|
{
|
|
/* core_class fields */
|
|
/* superclass */ (WidgetClass)&coreClassRec,
|
|
/* class_name */ "Label",
|
|
/* widget_size */ sizeof(LabelRec),
|
|
/* class_initialize */ ClassInitialize,
|
|
/* class_part_initialize */ NULL,
|
|
/* class_inited */ False,
|
|
/* initialize */ Initialize,
|
|
/* initialize_hook */ NULL,
|
|
/* realize */ Realize,
|
|
/* actions */ NULL,
|
|
/* num_actions */ 0,
|
|
/* resources */ resources,
|
|
/* num_resources */ XtNumber(resources),
|
|
/* xrm_class */ NULLQUARK,
|
|
/* compress_motion */ True,
|
|
/* compress_exposure */ True,
|
|
/* compress_enterleave */ True,
|
|
/* visible_interest */ False,
|
|
/* destroy */ NULL,
|
|
/* resize */ Resize,
|
|
/* expose */ Redisplay,
|
|
/* set_values */ SetValues,
|
|
/* set_values_hook */ NULL,
|
|
/* set_values_almost */ XtInheritSetValuesAlmost,
|
|
/* get_values_hook */ NULL,
|
|
/* accept_focus */ NULL,
|
|
/* version */ XtVersion,
|
|
/* callback_offsets */ NULL,
|
|
/* tm_table */ NULL,
|
|
/* query_geometry */ XtInheritQueryGeometry,
|
|
/* display_accelerator */ NULL,
|
|
/* extension */ NULL
|
|
},
|
|
{
|
|
/* Label_class fields */
|
|
/* get_text */ GetText,
|
|
/* set_text */ SetText,
|
|
/* extension */ NULL
|
|
}
|
|
};
|
|
|
|
/* Class record pointer */
|
|
WidgetClass labelWidgetClass = (WidgetClass) &labelClassRec;
|
|
|
|
/* New method access routines */
|
|
void LabelSetText(w, text)
|
|
Widget w;
|
|
String text;
|
|
{
|
|
Label WidgetClass lwc = (Label WidgetClass)XtClass(w);
|
|
XtCheckSubclass(w, labelWidgetClass, NULL);
|
|
*(lwc->label_class.set_text)(w, text)
|
|
}
|
|
/* Private procedures */
|
|
.
|
|
.
|
|
.
|
|
.De
|
|
|
|
.NH 3
|
|
Widget Class and Superclass Look Up
|
|
.XS
|
|
\*(SN Widget Class and Superclass Look Up
|
|
.XE
|
|
.LP
|
|
To obtain the class of a widget, use
|
|
.PN XtClass .
|
|
.IN "XtClass" "" "@DEF@"
|
|
.LP
|
|
.sM
|
|
.FD 0
|
|
WidgetClass XtClass(\fIw\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget. \*(oI
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtClass
|
|
function returns a pointer to the widget's class structure.
|
|
.sp
|
|
.LP
|
|
To obtain the superclass of a widget, use
|
|
.PN XtSuperclass .
|
|
.IN "XtSuperclass" "" "@DEF@"
|
|
.LP
|
|
.sM
|
|
.FD 0
|
|
WidgetClass XtSuperclass(\fIw\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget. \*(oI
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtSuperclass
|
|
function returns a pointer to the widget's superclass class structure.
|
|
|
|
.NH 3
|
|
Widget Subclass Verification
|
|
.XS
|
|
\*(SN Widget Subclass Verification
|
|
.XE
|
|
.LP
|
|
To check the subclass to which a widget belongs, use
|
|
.PN XtIsSubclass .
|
|
.IN "XtIsSubclass" "" "@DEF@"
|
|
.LP
|
|
.sM
|
|
.FD 0
|
|
Boolean XtIsSubclass(\fIw\fP, \fIwidget_class\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
WidgetClass \fIwidget_class\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget or object instance whose class is to be checked. \*(oI
|
|
.IP \fIwidget_class\fP 1i
|
|
Specifies the widget class for which to test. \*(oC
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtIsSubclass
|
|
function returns
|
|
.PN True
|
|
if the class of the specified widget is equal to
|
|
or is a subclass of the specified class.
|
|
The widget's class can be any number of subclasses down the chain
|
|
and need not be an immediate subclass of the specified class.
|
|
Composite widgets that need to restrict the class of the items they
|
|
contain can use
|
|
.PN XtIsSubclass
|
|
to find out if a widget belongs to the desired class of objects.
|
|
.sp
|
|
.LP
|
|
To test if a given widget belongs to a subclass of an \*(xI-defined
|
|
class, the \*(xI define macros or functions equivalent to
|
|
.PN XtIsSubclass
|
|
for each of the built-in classes. These procedures are
|
|
.PN XtIsObject ,
|
|
.PN XtIsRectObj ,
|
|
.PN XtIsWidget ,
|
|
.PN XtIsComposite ,
|
|
.PN XtIsConstraint ,
|
|
.PN XtIsShell ,
|
|
.PN XtIsOverrideShell ,
|
|
.PN XtIsWMShell ,
|
|
.PN XtIsVendorShell ,
|
|
.PN XtIsTransientShell ,
|
|
.PN XtIsTopLevelShell ,
|
|
.PN XtIsApplicationShell ,
|
|
and
|
|
.PN XtIsSessionShell .
|
|
.IN "XtIsObject" "" "@DEF@"
|
|
.IN "XtIsRectObj" "" "@DEF@"
|
|
.IN "XtIsWidget" "" "@DEF@"
|
|
.IN "XtIsComposite" "" "@DEF@"
|
|
.IN "XtIsConstraint" "" "@DEF@"
|
|
.IN "XtIsShell" "" "@DEF@"
|
|
.IN "XtIsOverrideShell" "" "@DEF@"
|
|
.IN "XtIsWMShell" "" "@DEF@"
|
|
.IN "XtIsVendorShell" "" "@DEF@"
|
|
.IN "XtIsTransientShell" "" "@DEF@"
|
|
.IN "XtIsTopLevelShell" "" "@DEF@"
|
|
.IN "XtIsApplicationShell" "" "@DEF@"
|
|
.IN "XtIsSessionShell" "" "@DEF@"
|
|
.LP
|
|
All these macros and functions have the same argument description.
|
|
.LP
|
|
.sM
|
|
.FD 0
|
|
Boolean XtIs\fI<class>\fP (\fIw\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget or object instance whose class is to be checked. \*(oI
|
|
.LP
|
|
.eM
|
|
These procedures may be faster than calling
|
|
.PN XtIsSubclass
|
|
directly for the built-in classes.
|
|
.sp
|
|
.LP
|
|
To check a widget's class
|
|
and to generate a debugging error message, use
|
|
.PN XtCheckSubclass ,
|
|
defined in
|
|
.Pn < X11/IntrinsicP.h >:
|
|
.IN "XtCheckSubclass" "" "@DEF@"
|
|
.LP
|
|
.sM
|
|
.FD 0
|
|
void XtCheckSubclass(\fIw\fP, \fIwidget_class\fP, \fImessage\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
WidgetClass \fIwidget_class\fP;
|
|
.br
|
|
String \fImessage\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget or object whose class is to be checked. \*(oI
|
|
.IP \fIwidget_class\fP 1i
|
|
Specifies the widget class for which to test. \*(oC
|
|
.ds Me used
|
|
.IP \fImessage\fP 1i
|
|
Specifies the message to be used.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtCheckSubclass
|
|
macro determines if the class of the specified widget is equal to
|
|
or is a subclass of the specified class.
|
|
The widget's class can be any number of subclasses down the chain
|
|
and need not be an immediate subclass of the specified class.
|
|
If the specified widget's class is not a subclass,
|
|
.PN XtCheckSubclass
|
|
constructs an error message from the supplied message,
|
|
the widget's actual class, and the expected class and calls
|
|
.PN XtErrorMsg .
|
|
.PN XtCheckSubclass
|
|
should be used at the entry point of exported routines to ensure
|
|
that the client has passed in a valid widget class for the exported operation.
|
|
.LP
|
|
.PN XtCheckSubclass
|
|
is only executed when the module has been compiled with the compiler symbol
|
|
DEBUG defined; otherwise, it is defined as the empty string
|
|
and generates no code.
|
|
|
|
.NH 3
|
|
Superclass Chaining
|
|
.XS
|
|
\*(SN Superclass Chaining
|
|
.XE
|
|
.LP
|
|
.IN "Chaining" "superclass"
|
|
.IN "Chaining" "Subclass"
|
|
.IN "Superclass Chaining" "" "@DEF@"
|
|
.IN "Subclass Chaining" "" "@DEF@"
|
|
.IN "Inheritance"
|
|
While most fields in a widget class structure are self-contained,
|
|
some fields are linked to their corresponding fields in their superclass
|
|
structures.
|
|
With a linked field,
|
|
the \*(xI access the field's value only after accessing its corresponding
|
|
superclass value (called downward superclass chaining) or
|
|
before accessing its corresponding superclass value (called upward superclass
|
|
chaining). The self-contained fields are
|
|
.sp
|
|
.ta 2i
|
|
In all widget classes: \fIclass_name\fP
|
|
.br
|
|
\fIclass_initialize\fP
|
|
.br
|
|
\fIwidget_size\fP
|
|
.br
|
|
\fIrealize\fP
|
|
.br
|
|
\fIvisible_interest\fP
|
|
.br
|
|
\fIresize\fP
|
|
.br
|
|
\fIexpose\fP
|
|
.br
|
|
\fIaccept_focus\fP
|
|
.br
|
|
\fIcompress_motion\fP
|
|
.br
|
|
\fIcompress_exposure\fP
|
|
.br
|
|
\fIcompress_enterleave\fP
|
|
.br
|
|
\fIset_values_almost\fP
|
|
.br
|
|
\fItm_table\fP
|
|
.br
|
|
\fIversion\fP
|
|
.br
|
|
\fIallocate\fP
|
|
.br
|
|
\fIdeallocate\fP
|
|
.sp
|
|
In Composite widget classes: \fIgeometry_manager\fP
|
|
.br
|
|
\fIchange_managed\fP
|
|
.br
|
|
\fIinsert_child\fP
|
|
.br
|
|
\fIdelete_child\fP
|
|
.br
|
|
\fIaccepts_objects\fP
|
|
.br
|
|
\fIallows_change_managed_set\fP
|
|
.sp
|
|
In Constraint widget classes: \fIconstraint_size\fP
|
|
.sp
|
|
In Shell widget classes: \fIroot_geometry_manager\fP
|
|
.sp
|
|
.LP
|
|
With downward superclass chaining,
|
|
the invocation of an operation first accesses the field from the
|
|
Object,
|
|
RectObj,
|
|
and
|
|
Core
|
|
class structures, then from the subclass structure, and so on down the class chain to
|
|
that widget's class structure. These superclass-to-subclass fields are
|
|
.sp
|
|
.ta 1i
|
|
.br
|
|
\fIclass_part_initialize\fP
|
|
.br
|
|
\fIget_values_hook\fP
|
|
.br
|
|
\fIinitialize\fP
|
|
.br
|
|
\fIinitialize_hook\fP
|
|
.br
|
|
\fIset_values\fP
|
|
.br
|
|
\fIset_values_hook\fP
|
|
.br
|
|
\fIresources\fP
|
|
.sp
|
|
.LP
|
|
In addition, for subclasses of
|
|
Constraint,
|
|
the following fields of the
|
|
.PN ConstraintClassPart
|
|
and
|
|
.PN ConstraintClassExtensionRec
|
|
structures are chained from the
|
|
Constraint
|
|
class down to the subclass:
|
|
.ta 1i
|
|
.br
|
|
\fIresources\fP
|
|
.br
|
|
\fIinitialize\fP
|
|
.br
|
|
\fIset_values\fP
|
|
.br
|
|
\fIget_values_hook\fP
|
|
.sp
|
|
.LP
|
|
With upward superclass chaining,
|
|
the invocation of an operation first accesses the field from the widget
|
|
class structure, then from the superclass structure,
|
|
and so on up the class chain to the
|
|
Core,
|
|
RectObj,
|
|
and
|
|
Object
|
|
class structures.
|
|
The subclass-to-superclass fields are
|
|
.sp
|
|
.ta 1i
|
|
.br
|
|
\fIdestroy\fP
|
|
.br
|
|
\fIactions\fP
|
|
.sp
|
|
.LP
|
|
For subclasses of
|
|
Constraint,
|
|
the following field of
|
|
.PN ConstraintClassPart
|
|
is chained from the subclass up to the
|
|
Constraint class:
|
|
.sp
|
|
.ta 1i
|
|
.br
|
|
\fIdestroy\fP
|
|
|
|
.NH 3
|
|
Class Initialization: class_initialize and class_part_initialize Procedures
|
|
.XS
|
|
\*(SN Class Initialization: class_initialize and class_part_initialize Procedures
|
|
.XE
|
|
.LP
|
|
.IN "Class Initialization"
|
|
.IN "Initialization"
|
|
Many class records can be initialized completely at compile or link time.
|
|
In some cases, however,
|
|
a class may need to register type converters or perform other sorts of
|
|
once-only runtime initialization.
|
|
.LP
|
|
Because the C language does not have initialization procedures
|
|
that are invoked automatically when a program starts up,
|
|
a widget class can declare a class_initialize procedure
|
|
that will be automatically called exactly once by the \*(xI.
|
|
A class initialization procedure pointer is of type
|
|
.PN XtProc :
|
|
.IN "class_initialize procedure" "" "@DEF@"
|
|
.IN "XtProc" "" "@DEF@"
|
|
.LP
|
|
.sM
|
|
.FD 0
|
|
typedef void (*XtProc)(void);
|
|
.FN
|
|
.LP
|
|
.eM
|
|
A widget class indicates that it has no class initialization procedure by
|
|
specifying NULL in the \fIclass_initialize\fP field.
|
|
.LP
|
|
In addition to the class initialization that is done exactly once,
|
|
some classes perform initialization for fields in their parts
|
|
of the class record.
|
|
These are performed not just for the particular class,
|
|
but for subclasses as well, and are
|
|
done in the class's class part initialization procedure,
|
|
a pointer to which is stored in the \fIclass_part_initialize\fP field.
|
|
The class_part_initialize procedure pointer is of type
|
|
.PN XtWidgetClassProc .
|
|
.IN "XtWidgetClassProc" "" "@DEF@"
|
|
.LP
|
|
.sM
|
|
.FD 0
|
|
typedef void (*XtWidgetClassProc)(WidgetClass);
|
|
.br
|
|
WidgetClass \fIwidget_class\fP;
|
|
.FN
|
|
.IP \fIwidget_class\fP 1i
|
|
Points to the class structure for the class being initialized.
|
|
.LP
|
|
.eM
|
|
During class initialization,
|
|
the class part initialization procedures for the class and all its superclasses
|
|
are called in superclass-to-subclass order on the class record.
|
|
These procedures have the responsibility of doing any dynamic initializations
|
|
necessary to their class's part of the record.
|
|
The most common is the resolution of any inherited methods defined in the
|
|
class.
|
|
For example,
|
|
if a widget class C has superclasses
|
|
Core,
|
|
Composite,
|
|
A, and B, the class record for C first is passed to
|
|
Core 's
|
|
class_part_initialize procedure.
|
|
This resolves any inherited Core methods and compiles the textual
|
|
representations of the resource list and action table that are defined in the
|
|
class record.
|
|
Next, Composite's
|
|
class_part_initialize procedure is called to initialize the
|
|
composite part of C's class record.
|
|
Finally, the class_part_initialize procedures for A, B, and C, in that order,
|
|
are called.
|
|
For further information,
|
|
see Section 1.6.9.
|
|
Classes that do not define any new class fields
|
|
or that need no extra processing for them can specify NULL
|
|
in the \fIclass_part_initialize\fP field.
|
|
.LP
|
|
All widget classes, whether they have a class initialization procedure or not,
|
|
must start with their \fIclass_inited\fP field
|
|
.PN False .
|
|
.LP
|
|
The first time a widget of a class is created,
|
|
.PN XtCreateWidget
|
|
ensures that the widget class and all superclasses are initialized, in
|
|
superclass-to-subclass order, by checking each \fIclass_inited\fP field and,
|
|
if it is
|
|
.PN False ,
|
|
by calling the class_initialize and the class_part_initialize procedures
|
|
for the class and all its superclasses.
|
|
The \*(xI then set the \fIclass_inited\fP field to a nonzero value.
|
|
After the one-time initialization,
|
|
a class structure is constant.
|
|
.LP
|
|
The following example provides the class initialization procedure for a Label class.
|
|
.LP
|
|
.Ds
|
|
.TA .5i 2i
|
|
.ta .5i 2i
|
|
static void ClassInitialize()
|
|
{
|
|
XtSetTypeConverter(XtRString, XtRJustify, CvtStringToJustify,
|
|
NULL, 0, XtCacheNone, NULL);
|
|
}
|
|
.De
|
|
|
|
.NH 3
|
|
Initializing a Widget Class
|
|
.XS
|
|
\fB\*(SN Initializing a Widget Class\fP
|
|
.XE
|
|
.IN "Widget" "class initialization"
|
|
.LP
|
|
A class is initialized when the first widget of that class or any
|
|
subclass is created.
|
|
To initialize a widget class without creating any widgets, use
|
|
.PN XtInitializeWidgetClass .
|
|
.IN "XtInitializeWidgetClass" "" "@DEF@"
|
|
.LP
|
|
.sM
|
|
.FD 0
|
|
void XtInitializeWidgetClass(\fIobject_class\fP)
|
|
.br
|
|
WidgetClass \fIobject_class\fP;
|
|
.br
|
|
.FN
|
|
.IP \fIobject_class\fP 1i
|
|
Specifies the object class to initialize. May be
|
|
.PN objectClass
|
|
or any subclass thereof.
|
|
.LP
|
|
.eM
|
|
If the specified widget class is already initialized,
|
|
.PN XtInitializeWidgetClass
|
|
returns immediately.
|
|
.LP
|
|
If the class initialization procedure registers type converters,
|
|
these type converters are not available until the first object
|
|
of the class or subclass is created or
|
|
.PN XtInitializeWidgetClass
|
|
is called
|
|
(see Section 9.6).
|
|
|
|
.NH 3
|
|
Inheritance of Superclass Operations
|
|
.XS
|
|
\*(SN Inheritance of Superclass Operations
|
|
.XE
|
|
.LP
|
|
A widget class is free to use any of its superclass's self-contained
|
|
operations rather than implementing its own code.
|
|
The most frequently inherited operations are
|
|
.IP
|
|
expose
|
|
.IP
|
|
realize
|
|
.IP
|
|
insert_child
|
|
.IP
|
|
delete_child
|
|
.IP
|
|
geometry_manager
|
|
.IP
|
|
set_values_almost
|
|
.LP
|
|
To inherit an operation \fIxyz\fP,
|
|
specify the constant
|
|
.PN XtInherit \fIXyz\fP
|
|
in your class record.
|
|
.LP
|
|
Every class that declares a new procedure in its widget class part must
|
|
provide for inheriting the procedure in its class_part_initialize
|
|
procedure.
|
|
The chained operations declared in Core
|
|
and Constraint
|
|
records are never inherited.
|
|
Widget classes that do nothing beyond what their superclass does
|
|
specify NULL for chained procedures
|
|
in their class records.
|
|
.LP
|
|
Inheriting works by comparing the value of the field with a known, special
|
|
value and by copying in the superclass's value for that field if a match
|
|
occurs.
|
|
This special value, called the inheritance constant,
|
|
is usually the \*(xI internal value
|
|
.PN _XtInherit
|
|
cast to the appropriate type.
|
|
.PN _XtInherit
|
|
is a procedure that issues an error message if it is actually called.
|
|
.LP
|
|
For example,
|
|
.PN CompositeP.h
|
|
contains these definitions:
|
|
.LP
|
|
.Ds
|
|
.TA .25i 1.5i 3i
|
|
.ta .25i 1.5i 3i
|
|
#define XtInheritGeometryManager ((XtGeometryHandler) _XtInherit)
|
|
#define XtInheritChangeManaged ((XtWidgetProc) _XtInherit)
|
|
#define XtInheritInsertChild ((XtArgsProc) _XtInherit)
|
|
#define XtInheritDeleteChild ((XtWidgetProc) _XtInherit)
|
|
.De
|
|
.LP
|
|
Composite's class_part_initialize procedure begins as follows:
|
|
.LP
|
|
.Ds
|
|
.TA .2i 1.5i 3i
|
|
.ta .2i 1.5i 3i
|
|
static void CompositeClassPartInitialize(widgetClass)
|
|
WidgetClass widgetClass;
|
|
{
|
|
CompositeWidgetClass wc = (CompositeWidgetClass)widgetClass;
|
|
CompositeWidgetClass super = (CompositeWidgetClass)wc->core_class.superclass;
|
|
|
|
if (wc->composite_class.geometry_manager == XtInheritGeometryManager) {
|
|
wc->composite_class.geometry_manager = super->composite_class.geometry_manager;
|
|
}
|
|
|
|
if (wc->composite_class.change_managed == XtInheritChangeManaged) {
|
|
wc->composite_class.change_managed = super->composite_class.change_managed;
|
|
}
|
|
.
|
|
.
|
|
.
|
|
.De
|
|
.LP
|
|
Nonprocedure fields may be inherited in the same manner as procedure
|
|
fields. The class may declare any reserved value it wishes for
|
|
the inheritance constant for its new fields. The following inheritance
|
|
constants are defined:
|
|
.LP
|
|
For Object:
|
|
.IP
|
|
.PN XtInheritAllocate
|
|
.IP
|
|
.PN XtInheritDeallocate
|
|
.LP
|
|
For Core:
|
|
.IP
|
|
.PN XtInheritRealize
|
|
.IP
|
|
.PN XtInheritResize
|
|
.IP
|
|
.PN XtInheritExpose
|
|
.IP
|
|
.PN XtInheritSetValuesAlmost
|
|
.IP
|
|
.PN XtInheritAcceptFocus
|
|
.IP
|
|
.PN XtInheritQueryGeometry
|
|
.IP
|
|
.PN XtInheritTranslations
|
|
.IP
|
|
.PN XtInheritDisplayAccelerator
|
|
.LP
|
|
For Composite:
|
|
.IP
|
|
.PN XtInheritGeometryManager
|
|
.IP
|
|
.PN XtInheritChangeManaged
|
|
.IP
|
|
.PN XtInheritInsertChild
|
|
.IP
|
|
.PN XtInheritDeleteChild
|
|
.LP
|
|
For Shell:
|
|
.IP
|
|
.PN XtInheritRootGeometryManager
|
|
|
|
.NH 3
|
|
Invocation of Superclass Operations
|
|
.XS
|
|
\*(SN Invocation of Superclass Operations
|
|
.XE
|
|
.LP
|
|
A widget sometimes needs to call a superclass operation
|
|
that is not chained.
|
|
For example,
|
|
a widget's expose procedure might call its superclass's \fIexpose\fP
|
|
and then perform a little more work on its own.
|
|
For example, a Composite
|
|
class with predefined managed children can implement insert_child
|
|
by first calling its superclass's \fIinsert_child\fP
|
|
.IN "insert_child procedure"
|
|
and then calling
|
|
.PN XtManageChild
|
|
to add the child to the managed set.
|
|
.LP
|
|
.NT
|
|
A class method should not use
|
|
.PN XtSuperclass
|
|
but should instead call the class method of its own specific superclass
|
|
directly through the superclass record.
|
|
That is, it should use its own class pointers only,
|
|
not the widget's class pointers,
|
|
as the widget's class may be a subclass of the
|
|
class whose implementation is being referenced.
|
|
.NE
|
|
This technique is referred to as \fIenveloping\fP the superclass's operation.
|
|
|
|
.NH 3
|
|
Class Extension Records
|
|
.XS
|
|
\*(SN Class Extension Records
|
|
.XE
|
|
.IN "Widget" "class extension records"
|
|
.LP
|
|
It may be necessary at times to add new fields to already existing
|
|
widget class structures. To permit this to be done without requiring
|
|
recompilation of all subclasses, the last field in a class part structure
|
|
should be an extension pointer. If no extension fields for a class
|
|
have yet been defined, subclasses should initialize the value of the
|
|
extension pointer to NULL.
|
|
.LP
|
|
If extension fields exist, as is the case with the
|
|
Composite,
|
|
Constraint,
|
|
and
|
|
Shell
|
|
classes, subclasses can provide values for these fields by setting the
|
|
\fIextension\fP pointer for the appropriate part in their class structure to
|
|
point to a statically declared extension record containing the
|
|
additional fields.
|
|
Setting the \fIextension\fP field is never mandatory; code that uses fields
|
|
in the extension record must always check the \fIextension\fP field and take
|
|
some appropriate default action if it is NULL.
|
|
.LP
|
|
In order to permit multiple subclasses and libraries to chain extension
|
|
records from a single \fIextension\fP field, extension records should be
|
|
declared as a linked list, and each extension record definition should
|
|
contain the following four fields at the beginning of the structure
|
|
declaration:
|
|
.LP
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
struct {
|
|
XtPointer next_extension;
|
|
XrmQuark record_type;
|
|
long version;
|
|
Cardinal record_size;
|
|
};
|
|
.De
|
|
.IP \fInext_extension\fP 1.25i
|
|
Specifies the next record in the list, or NULL.
|
|
.IP \fIrecord_type\fP 1.25i
|
|
Specifies the particular structure declaration to which
|
|
each extension record instance conforms.
|
|
.IP \fIversion\fP 1.25i
|
|
Specifies a version id symbolic constant supplied by
|
|
the definer of the structure.
|
|
.IP \fIrecord_size\fP 1.25i
|
|
Specifies the total number of bytes allocated for the
|
|
extension record.
|
|
.LP
|
|
.eM
|
|
The \fIrecord_type\fP field identifies the contents of the extension record
|
|
and is used by the definer of the record to locate its particular
|
|
extension record in the list. The
|
|
\fIrecord_type\fP field is normally assigned the
|
|
result of
|
|
.PN XrmStringToQuark
|
|
for a registered string constant. The
|
|
\*(xI reserve all record type strings beginning with the two
|
|
characters ``XT'' for future standard uses. The value
|
|
.PN \s-1NULLQUARK\s+1
|
|
may also be used
|
|
by the class part owner in extension records attached to its own class
|
|
part extension field to identify the extension record unique to that
|
|
particular class.
|
|
.LP
|
|
The \fIversion\fP field is an owner-defined constant that may be used to
|
|
identify binary files that have been compiled with alternate
|
|
definitions of the remainder of the extension record data structure. The private
|
|
header file for a widget class should provide a symbolic constant for
|
|
subclasses to use to initialize this field.
|
|
The \fIrecord_size\fP field value includes the four common header fields and
|
|
should normally be initialized with
|
|
.PN sizeof ().
|
|
.LP
|
|
Any value stored in the class part extension fields of
|
|
.PN CompositeClassPart ,
|
|
.PN ConstraintClassPart ,
|
|
or
|
|
.PN ShellClassPart
|
|
must point to an extension record conforming to this definition.
|
|
.LP
|
|
The \*(xI provide a utility function for widget writers to locate a
|
|
particular class extension record in a linked list, given a widget class
|
|
and the offset of the \fIextension\fP field in the class record.
|
|
.LP
|
|
To locate a class extension record, use
|
|
.PN XtGetClassExtension .
|
|
.IN "XtGetClassExtension" "" "@DEF@"
|
|
.LP
|
|
.sM
|
|
.FD 0
|
|
XtPointer XtGetClassExtension(\fIobject_class\fP, \fIbyte_offset\fP, \
|
|
\fItype\fP, \fIversion\fP, \fIrecord_size\fP)
|
|
.br
|
|
WidgetClass \fIobject_class\fP;
|
|
.br
|
|
Cardinal \fIbyte_offset\fP;
|
|
.br
|
|
XrmQuark \fItype\fP;
|
|
.br
|
|
long \fIversion\fP;
|
|
.br
|
|
Cardinal \fIrecord_size\fP;
|
|
.FN
|
|
.IP \fIobject_class\fP 1i
|
|
Specifies the object class containing the extension list to be searched.
|
|
.IP \fIbyte_offset\fP 1i
|
|
Specifies the offset in bytes from the base of the
|
|
class record of the extension field to be searched.
|
|
.IP \fItype\fP 1i
|
|
Specifies the record_type of the class extension to be located.
|
|
.IP \fIversion\fP 1i
|
|
Specifies the minimum acceptable version of the class
|
|
extension required for a match.
|
|
.IP \fIrecord_size\fP 1i
|
|
Specifies the minimum acceptable length of the class
|
|
extension record required for a match, or 0.
|
|
.LP
|
|
.eM
|
|
The list of extension records at the specified offset in the specified
|
|
object class will be searched for a match on the specified type,
|
|
a version greater than or equal to the specified version, and a record
|
|
size greater than or equal the specified record_size if it is nonzero.
|
|
.PN XtGetClassExtension
|
|
returns a pointer to a matching extension record or NULL if no match
|
|
is found. The returned extension record must not be modified or
|
|
freed by the caller if the caller is not the extension owner.
|
|
.bp
|