2799 lines
87 KiB
XML
2799 lines
87 KiB
XML
|
<chapter id='Intrinsics_and_Widgets'>
|
||
|
<title>Intrinsics and Widgets</title>
|
||
|
<para>
|
||
|
The Intrinsics are a programming library tailored to the special requirements
|
||
|
of user interface construction within a network window system,
|
||
|
specifically the X Window System.
|
||
|
The Intrinsics and a widget set make up an X Toolkit.
|
||
|
</para>
|
||
|
<sect1 id="Intrinsics">
|
||
|
<title>Intrinsics</title>
|
||
|
<para>
|
||
|
The Intrinsics provide the base mechanism necessary to build
|
||
|
a wide variety of interoperating widget sets and application environments.
|
||
|
The Intrinsics are a layer on top of Xlib, the
|
||
|
C Library X Interface. They extend the
|
||
|
fundamental abstractions provided by the X Window System while still
|
||
|
remaining independent of any particular user interface policy or
|
||
|
style.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
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.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
When the Intrinsics were first conceived, the root of the object
|
||
|
hierarchy was a widget class named
|
||
|
Core.
|
||
|
In Release 4 of the
|
||
|
Intrinsics, three nonwidget superclasses were added above Core.
|
||
|
These superclasses are described in <xref linkend='Nonwidget_Objects' />.
|
||
|
The name of the class
|
||
|
now at the root of the Intrinsics class hierarchy is
|
||
|
Object.
|
||
|
The remainder of this
|
||
|
specification refers uniformly to <emphasis remap='I'>widgets</emphasis> and <emphasis remap='I'>Core</emphasis>
|
||
|
as if they were the
|
||
|
base class for all Intrinsics operations. The argument descriptions
|
||
|
for each Intrinsics procedure and <xref linkend='Nonwidget_Objects' />
|
||
|
describe which operations
|
||
|
are defined for the nonwidget superclasses of Core. The reader may
|
||
|
determine by context whether a specific reference to <emphasis remap='I'>widget</emphasis>
|
||
|
actually means ``widget'' or ``object.''
|
||
|
</para>
|
||
|
</sect1>
|
||
|
|
||
|
<sect1 id="Languages">
|
||
|
<title>Languages</title>
|
||
|
<para>
|
||
|
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 <emphasis remap='I'>client</emphasis> refers to
|
||
|
any module, widget, or application that calls an Intrinsics procedure.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
Applications that use the Intrinsics mechanisms
|
||
|
must include the header files
|
||
|
<function><X11/Intrinsic.h></function>
|
||
|
and
|
||
|
<function><X11/StringDefs.h></function>,
|
||
|
or their equivalent,
|
||
|
and they may also include
|
||
|
<function><X11/Xatoms.h></function>
|
||
|
and
|
||
|
<function><X11/Shell.h></function>.
|
||
|
In addition, widget implementations should include
|
||
|
<function><X11/IntrinsicP.h></function>
|
||
|
instead of
|
||
|
<function><X11/Intrinsic.h></function>.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The applications must also include the additional header files for
|
||
|
each widget class that they are to use (for example,
|
||
|
<function><X11/Xaw/Label.h></function>
|
||
|
or
|
||
|
<function><X11/Xaw/Scrollbar.h>).</function>
|
||
|
On a POSIX-based system,
|
||
|
the Intrinsics object library file is named
|
||
|
<function>libXt.a</function>
|
||
|
and is usually referenced as \-lXt when linking the application.
|
||
|
</para>
|
||
|
</sect1>
|
||
|
|
||
|
<sect1 id="Procedures_and_Macros">
|
||
|
<title>Procedures and Macros</title>
|
||
|
<para>
|
||
|
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.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
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:
|
||
|
<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>,
|
||
|
<xref linkend='XtNew' xrefstyle='select: title'/>,
|
||
|
<xref linkend='XtNumber' xrefstyle='select: title'/>,
|
||
|
<xref linkend='XtOffsetOf' xrefstyle='select: title'/>,
|
||
|
<xref linkend='XtOffset' xrefstyle='select: title'/>,
|
||
|
and
|
||
|
<xref linkend='XtSetArg' xrefstyle='select: title'/>.
|
||
|
</para>
|
||
|
</sect1>
|
||
|
|
||
|
<sect1 id="Widgets">
|
||
|
<title>Widgets</title>
|
||
|
<para>
|
||
|
The fundamental abstraction and data type of the X Toolkit is the widget,
|
||
|
which is a combination of an X window and its associated
|
||
|
input and display semantics
|
||
|
and which is dynamically allocated and contains state information.
|
||
|
Some widgets display information (for example, text or graphics),
|
||
|
and others are merely containers for other widgets (for example, a menu box).
|
||
|
Some widgets are output-only and do not react to pointer or keyboard input,
|
||
|
and others change their display in response to input
|
||
|
and can invoke functions that an application has attached to them.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
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 <xref linkend='Creating_Widgets' />
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
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 <xref linkend='Widget_Classing' />
|
||
|
The predefined widget classes adhere to these conventions.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
A widget instance is composed of two parts:
|
||
|
</para>
|
||
|
<itemizedlist spacing='compact'>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
A data structure which contains instance-specific values.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
A class structure which contains information that is applicable to
|
||
|
all widgets of that class.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</itemizedlist>
|
||
|
<para>
|
||
|
Much of the input/output of a widget (for example, fonts, colors, sizes,
|
||
|
or border widths) is customizable by users.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
This chapter discusses the base widget classes,
|
||
|
Core, Composite, and Constraint, and
|
||
|
ends with a discussion of widget classing.
|
||
|
</para>
|
||
|
<sect2 id="Core_Widgets">
|
||
|
<title>Core Widgets</title>
|
||
|
<para>
|
||
|
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
|
||
|
<function>CoreClassPart</function>
|
||
|
and
|
||
|
<function>CorePart</function>
|
||
|
structures.
|
||
|
</para>
|
||
|
<sect3 id="CoreClassPart_Structure">
|
||
|
<title>CoreClassPart Structure</title>
|
||
|
<para>
|
||
|
All widget classes contain the fields defined in the
|
||
|
<function>CoreClassPart</function>
|
||
|
structure.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct {
|
||
|
WidgetClass superclass; See <xref linkend="Widget_Classing" xrefstyle='select: label' />
|
||
|
String class_name; See <xref linkend="Resource_Management" xrefstyle='select: label' />
|
||
|
Cardinal widget_size; See <xref linkend="Widget_Classing" xrefstyle='select: label' />
|
||
|
XtProc class_initialize; See <xref linkend="Widget_Classing" xrefstyle='select: label' />
|
||
|
XtWidgetClassProc class_part_initialize; See <xref linkend="Widget_Classing" xrefstyle='select: label' />
|
||
|
XtEnum class_inited; See <xref linkend="Widget_Classing" xrefstyle='select: label' />
|
||
|
XtInitProc initialize; See <xref linkend='Creating_Widgets' xrefstyle='select: label' />
|
||
|
XtArgsProc initialize_hook; See <xref linkend='Creating_Widgets' xrefstyle='select: label' />
|
||
|
XtRealizeProc realize; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
|
||
|
XtActionList actions; See <xref linkend='Translation_Management' xrefstyle='select: label' />
|
||
|
Cardinal num_actions; See <xref linkend='Translation_Management' xrefstyle='select: label' />
|
||
|
XtResourceList resources; See <xref linkend="Resource_Management" xrefstyle='select: label' />
|
||
|
Cardinal num_resources; See <xref linkend="Resource_Management" xrefstyle='select: label' />
|
||
|
XrmClass xrm_class; Private to resource manager
|
||
|
Boolean compress_motion; See <xref linkend='X_Event_Filters' xrefstyle='select: label' />
|
||
|
XtEnum compress_exposure; See <xref linkend='X_Event_Filters' xrefstyle='select: label' />
|
||
|
Boolean compress_enterleave; See <xref linkend='X_Event_Filters' xrefstyle='select: label' />
|
||
|
Boolean visible_interest; See <xref linkend='Widget_Exposure_and_Visibility' xrefstyle='select: label' />
|
||
|
XtWidgetProc destroy; See <xref linkend='Destroying_Widgets' xrefstyle='select: label' />
|
||
|
XtWidgetProc resize; See <xref linkend='Geometry_Management' xrefstyle='select: label' />
|
||
|
XtExposeProc expose; See <xref linkend='Widget_Exposure_and_Visibility' xrefstyle='select: label' />
|
||
|
XtSetValuesFunc set_values; See <xref linkend='Reading_and_Writing_Widget_State' xrefstyle='select: label' />
|
||
|
XtArgsFunc set_values_hook; See <xref linkend='Reading_and_Writing_Widget_State' xrefstyle='select: label' />
|
||
|
XtAlmostProc set_values_almost; See <xref linkend='Reading_and_Writing_Widget_State' xrefstyle='select: label' />
|
||
|
XtArgsProc get_values_hook; See <xref linkend='Reading_and_Writing_Widget_State' xrefstyle='select: label' />
|
||
|
XtAcceptFocusProc accept_focus; See <xref linkend='Focusing_Events_on_a_Child' xrefstyle='select: label' />
|
||
|
XtVersionType version; See <xref linkend="Widget_Classing" xrefstyle='select: label' />
|
||
|
XtPointer callback_private; Private to callbacks
|
||
|
String tm_table; See <xref linkend='Translation_Management' xrefstyle='select: label' />
|
||
|
XtGeometryHandler query_geometry; See <xref linkend ='Geometry_Management' xrefstyle='select: label' />
|
||
|
XtStringProc display_accelerator; See <xref linkend='Translation_Management' xrefstyle='select: label' />
|
||
|
XtPointer extension; See <xref linkend="Widget_Classing" xrefstyle='select: label' />
|
||
|
} CoreClassPart;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
All widget classes have the Core class fields as their first component.
|
||
|
The prototypical
|
||
|
<function>WidgetClass</function>
|
||
|
and
|
||
|
<function>CoreWidgetClass</function>
|
||
|
are defined with only this set of fields.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct {
|
||
|
CoreClassPart core_class;
|
||
|
} WidgetClassRec, *WidgetClass, CoreClassRec, *CoreWidgetClass;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
Various routines can cast widget class pointers, as needed,
|
||
|
to specific widget class types.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The single occurrences of the class record and pointer for
|
||
|
creating instances of Core are
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
In
|
||
|
<function>IntrinsicP.h</function>:
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
extern WidgetClassRec widgetClassRec;
|
||
|
#define coreClassRec widgetClassRec
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
In
|
||
|
<function>Intrinsic.h</function>:
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
extern WidgetClass widgetClass, coreWidgetClass;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
The opaque types
|
||
|
<function>Widget</function>
|
||
|
and
|
||
|
<function>WidgetClass</function>
|
||
|
and the opaque variable
|
||
|
<function>widgetClass</function>
|
||
|
are defined for generic actions on widgets.
|
||
|
In order to make these types opaque and ensure that the compiler
|
||
|
does not allow applications to access private data, the Intrinsics use
|
||
|
incomplete structure definitions in
|
||
|
<function>Intrinsic.h</function>:
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct _WidgetClassRec *WidgetClass, *CoreWidgetClass;
|
||
|
</literallayout>
|
||
|
</sect3>
|
||
|
<sect3 id="CorePart_Structure">
|
||
|
<title>CorePart Structure</title>
|
||
|
<para>
|
||
|
All widget instances contain the fields defined in the
|
||
|
<function>CorePart</function>
|
||
|
structure.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct _CorePart {
|
||
|
Widget self; Described below
|
||
|
WidgetClass widget_class; See <xref linkend='Widget_Classing' xrefstyle='select: label' />
|
||
|
Widget parent; See <xref linkend='Creating_Widgets' xrefstyle='select: label' />
|
||
|
Boolean being_destroyed; See <xref linkend='Destroying_Widgets' xrefstyle='select: label' />
|
||
|
XtCallbackList destroy_callbacks; <xref linkend='Destroying_Widgets' xrefstyle='select: label' />
|
||
|
XtPointer constraints; See <xref linkend='Constrained_Composite_Widgets' xrefstyle='select: label' />
|
||
|
Position x; See <xref linkend='Geometry_Management' xrefstyle='select: label' />
|
||
|
Position y; See <xref linkend='Geometry_Management' xrefstyle='select: label' />
|
||
|
Dimension width; See <xref linkend='Geometry_Management' xrefstyle='select: label' />
|
||
|
Dimension height; See <xref linkend='Geometry_Management' xrefstyle='select: label' />
|
||
|
Dimension border_width; See <xref linkend='Geometry_Management' xrefstyle='select: label' />
|
||
|
Boolean managed; See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: label' />
|
||
|
Boolean sensitive; See <xref linkend='Setting_and_Checking_the_Sensitivity_State_of_a_Widget' xrefstyle='select: label' />
|
||
|
Boolean ancestor_sensitive; See <xref linkend='Setting_and_Checking_the_Sensitivity_State_of_a_Widget' xrefstyle='select: label' />
|
||
|
XtTranslations accelerators; See <xref linkend='Translation_Management' xrefstyle='select: label' />
|
||
|
Pixel border_pixel; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
|
||
|
Pixmap border_pixmap; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
|
||
|
WidgetList popup_list; See <xref linkend='Pop_Up_Widgets' xrefstyle='select: label' />
|
||
|
Cardinal num_popups; See <xref linkend='Pop_Up_Widgets' xrefstyle='select: label' />
|
||
|
String name; See <xref linkend='Resource_Management' xrefstyle='select: label' />
|
||
|
Screen *screen; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
|
||
|
Colormap colormap; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
|
||
|
Window window; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
|
||
|
Cardinal depth; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
|
||
|
Pixel background_pixel; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
|
||
|
Pixmap background_pixmap; See <xref linkend='Realizing_Widgets' xrefstyle='select: label' />
|
||
|
Boolean visible; See <xref linkend='Widget_Exposure_and_Visibility' xrefstyle='select: label' />
|
||
|
Boolean mapped_when_managed; See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: label' />
|
||
|
} CorePart;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
All widget instances have the Core fields as their first component.
|
||
|
The prototypical type
|
||
|
<function>Widget</function>
|
||
|
is defined with only this set of fields.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct {
|
||
|
CorePart core;
|
||
|
} WidgetRec, *Widget, CoreRec, *CoreWidget;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
Various routines can cast widget pointers, as needed,
|
||
|
to specific widget types.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
In order to make these types opaque and ensure that the compiler
|
||
|
does not allow applications to access private data, the Intrinsics use
|
||
|
incomplete structure definitions in
|
||
|
<function>Intrinsic.h</function>.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct _WidgetRec *Widget, *CoreWidget;
|
||
|
</literallayout>
|
||
|
</sect3>
|
||
|
<sect3 id="Core_Resources">
|
||
|
<title>Core Resources</title>
|
||
|
<para>
|
||
|
The resource names, classes, and representation types specified in the
|
||
|
<function>coreClassRec</function>
|
||
|
resource list are
|
||
|
</para>
|
||
|
|
||
|
<informaltable frame='topbot'>
|
||
|
<?dbfo keep-together="always" ?>
|
||
|
<tgroup cols='3' align='left' colsep='0' rowsep='0'>
|
||
|
<colspec colname='c1' colwidth='1.0*'/>
|
||
|
<colspec colname='c2' colwidth='1.0*'/>
|
||
|
<colspec colname='c3' colwidth='1.0*'/>
|
||
|
<thead>
|
||
|
<row rowsep='1'>
|
||
|
<entry>Name</entry>
|
||
|
<entry>Class</entry>
|
||
|
<entry>Representation</entry>
|
||
|
</row>
|
||
|
</thead>
|
||
|
<tbody>
|
||
|
<row>
|
||
|
<entry>XtNaccelerators</entry>
|
||
|
<entry>XtCAccelerators</entry>
|
||
|
<entry>XtRAcceleratorTable</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>XtNbackground</entry>
|
||
|
<entry>XtCBackground</entry>
|
||
|
<entry>XtRPixel</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>XtNbackgroundPixmap</entry>
|
||
|
<entry>XtCPixmap</entry>
|
||
|
<entry>XtRPixmap</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>XtNborderColor</entry>
|
||
|
<entry>XtCBorderColor</entry>
|
||
|
<entry>XtRPixel</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>XtNborderPixmap</entry>
|
||
|
<entry>XtCPixmap</entry>
|
||
|
<entry>XtRPixmap</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>XtNcolormap</entry>
|
||
|
<entry>XtCColormap</entry>
|
||
|
<entry>XtRColormap</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>XtNdepth</entry>
|
||
|
<entry>XtCDepth</entry>
|
||
|
<entry>XtRInt</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>XtNmappedWhenManaged</entry>
|
||
|
<entry>XtCMappedWhenManaged</entry>
|
||
|
<entry>XtRBoolean</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>XtNscreen</entry>
|
||
|
<entry>XtCScreen</entry>
|
||
|
<entry>XtRScreen</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>XtNtranslations</entry>
|
||
|
<entry>XtCTranslations</entry>
|
||
|
<entry>XtRTranslationTable</entry>
|
||
|
</row>
|
||
|
</tbody>
|
||
|
</tgroup>
|
||
|
</informaltable>
|
||
|
<para>
|
||
|
Additional resources are defined for all widgets via the
|
||
|
<function>objectClassRec</function>
|
||
|
and
|
||
|
<function>rectObjClassRec</function>
|
||
|
resource lists; see <xref linkend='Object_Objects' /> and <xref linkend='Rectangle_Objects' /> for details.
|
||
|
</para>
|
||
|
</sect3>
|
||
|
<sect3 id="CorePart_Default_Values">
|
||
|
<title>CorePart Default Values</title>
|
||
|
<para>
|
||
|
The default values for the Core fields, which are filled in by the Intrinsics,
|
||
|
from the resource lists, and by the initialize procedures, are
|
||
|
</para>
|
||
|
<informaltable frame='topbot'>
|
||
|
<?dbfo keep-together="always" ?>
|
||
|
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
||
|
<colspec colname='c1' colwidth='0.4*'/>
|
||
|
<colspec colname='c2' colwidth='1.0*'/>
|
||
|
<thead>
|
||
|
<row rowsep='1'>
|
||
|
<entry>Field</entry>
|
||
|
<entry>Default Value</entry>
|
||
|
</row>
|
||
|
</thead>
|
||
|
<tbody>
|
||
|
<row>
|
||
|
<entry>self</entry>
|
||
|
<entry>Address of the widget structure (may not be changed).</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>widget_class</entry>
|
||
|
<entry><emphasis remap='I'>widget_class</emphasis> argument to
|
||
|
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
|
||
|
(may not be changed).</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>parent</entry>
|
||
|
<entry><emphasis remap='I'>parent</emphasis> argument to
|
||
|
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
|
||
|
(may not be changed).</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>being_destroyed</entry>
|
||
|
<entry>Parent's <emphasis remap='I'>being_destroyed</emphasis> value.</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>destroy_callbacks</entry>
|
||
|
<entry>NULL</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>constraints</entry>
|
||
|
<entry>NULL</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>x</entry>
|
||
|
<entry>0</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>y</entry>
|
||
|
<entry>0</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>width</entry>
|
||
|
<entry>0</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>height</entry>
|
||
|
<entry>0</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>border_width</entry>
|
||
|
<entry>1</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>managed</entry>
|
||
|
<entry><function>False</function></entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>sensitive</entry>
|
||
|
<entry><function>True</function></entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>ancestor_sensitive</entry>
|
||
|
<entry>logical AND of parent's <emphasis remap='I'>sensitive</emphasis> and
|
||
|
<emphasis remap='I'>ancestor_sensitive</emphasis> values.</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>accelerators</entry>
|
||
|
<entry>NULL</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>border_pixel</entry>
|
||
|
<entry><function>XtDefaultForeground</function></entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>border_pixmap</entry>
|
||
|
<entry><function>XtUnspecifiedPixmap</function></entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>popup_list</entry>
|
||
|
<entry>NULL</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>num_popups</entry>
|
||
|
<entry>0</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>name</entry>
|
||
|
<entry><emphasis remap='I'>name</emphasis> argument to
|
||
|
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
|
||
|
(may not be changed).</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>screen</entry>
|
||
|
<entry>Parent's <emphasis remap='I'>screen</emphasis>; top-level widget gets screen from display specifier
|
||
|
(may not be changed).</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>colormap</entry>
|
||
|
<entry>Parent's <emphasis remap='I'>colormap</emphasis> value.</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>window</entry>
|
||
|
<entry>NULL</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>depth</entry>
|
||
|
<entry>Parent's <emphasis remap='I'>depth</emphasis>; top-level widget gets root window depth.</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>background_pixel</entry>
|
||
|
<entry><function>XtDefaultBackground</function></entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>background_pixmap</entry>
|
||
|
<entry><function>XtUnspecifiedPixmap</function></entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>visible</entry>
|
||
|
<entry><function>True</function></entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>mapped_when_managed</entry>
|
||
|
<entry><function>True</function></entry>
|
||
|
</row>
|
||
|
</tbody>
|
||
|
</tgroup>
|
||
|
</informaltable>
|
||
|
<para>
|
||
|
<function>XtUnspecifiedPixmap</function>
|
||
|
is a symbolic constant guaranteed to be unequal to
|
||
|
any valid Pixmap id,
|
||
|
<function>None</function>,
|
||
|
and
|
||
|
<function>ParentRelative</function>.
|
||
|
</para>
|
||
|
</sect3>
|
||
|
</sect2>
|
||
|
|
||
|
<sect2 id="Composite_Widgets">
|
||
|
<title>Composite Widgets</title>
|
||
|
<para>
|
||
|
The Composite
|
||
|
widget class is a subclass of the
|
||
|
Core
|
||
|
widget class (see <xref linkend='Composite_Widgets_and_Their_Children' />).
|
||
|
Composite widgets are intended to be containers for other widgets.
|
||
|
The additional data used by composite widgets are defined by the
|
||
|
<function>CompositeClassPart</function>
|
||
|
and
|
||
|
<function>CompositePart</function>
|
||
|
structures.
|
||
|
</para>
|
||
|
<sect3 id="CompositeClassPart_Structure">
|
||
|
<title>CompositeClassPart Structure</title>
|
||
|
<para>
|
||
|
In addition to the
|
||
|
Core
|
||
|
class fields,
|
||
|
widgets of the Composite class have the following class fields.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct {
|
||
|
XtGeometryHandler geometry_manager; See <xref linkend='Geometry_Management' xrefstyle='select: label' />
|
||
|
XtWidgetProc change_managed; See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: label' />
|
||
|
XtWidgetProc insert_child; See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: label' />
|
||
|
XtWidgetProc delete_child; See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: label' />
|
||
|
XtPointer extension; See <xref linkend='Widget_Classing' xrefstyle='select: label' />
|
||
|
} CompositeClassPart;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
The extension record defined for
|
||
|
<function>CompositeClassPart</function>
|
||
|
with <emphasis remap='I'>record_type</emphasis>
|
||
|
equal to
|
||
|
<emphasis role='strong'>NULLQUARK</emphasis>
|
||
|
is
|
||
|
<function>CompositeClassExtensionRec</function>.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct {
|
||
|
XtPointer next_extension; See <xref linkend='Class_Extension_Records' xrefstyle='select: label' />
|
||
|
XrmQuark record_type; See <xref linkend='Class_Extension_Records' xrefstyle='select: label' />
|
||
|
long version; See <xref linkend='Class_Extension_Records' xrefstyle='select: label' />
|
||
|
Cardinal record_size; See <xref linkend='Class_Extension_Records' xrefstyle='select: label' />
|
||
|
Boolean accepts_objects; See <xref linkend='Creating_a_Widget_Instance' xrefstyle='select: label' />
|
||
|
Boolean allows_change_managed_set; See <xref linkend='Bundling_Changes_to_the_Managed_Set' xrefstyle='select: label' />
|
||
|
} CompositeClassExtensionRec, *CompositeClassExtension;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
Composite
|
||
|
classes have the Composite class fields immediately following the
|
||
|
Core class fields.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct {
|
||
|
CoreClassPart core_class;
|
||
|
CompositeClassPart composite_class;
|
||
|
} CompositeClassRec, *CompositeWidgetClass;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
The single occurrences of the class record and pointer for creating
|
||
|
instances of Composite are
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
In
|
||
|
<function>IntrinsicP.h</function>:
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
extern CompositeClassRec compositeClassRec;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
In
|
||
|
<function>Intrinsic.h</function>:
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
extern WidgetClass compositeWidgetClass;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
The opaque types
|
||
|
<function>CompositeWidget</function>
|
||
|
and
|
||
|
<function>CompositeWidgetClass</function>
|
||
|
and the opaque variable
|
||
|
<function>compositeWidgetClass</function>
|
||
|
are defined for generic operations on widgets whose class
|
||
|
is Composite or a subclass of Composite.
|
||
|
The symbolic constant for the
|
||
|
<function>CompositeClassExtension</function>
|
||
|
version identifier is
|
||
|
<function>XtCompositeExtensionVersion</function>
|
||
|
(see <xref linkend='Class_Extension_Records' />).
|
||
|
<function>Intrinsic.h</function>
|
||
|
uses an incomplete structure
|
||
|
definition to ensure that the compiler catches attempts to access
|
||
|
private data.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct _CompositeClassRec *CompositeWidgetClass;
|
||
|
</literallayout>
|
||
|
</sect3>
|
||
|
<sect3 id="CompositePart_Structure">
|
||
|
<title>CompositePart Structure</title>
|
||
|
<para>
|
||
|
In addition to the
|
||
|
Core instance
|
||
|
fields,
|
||
|
widgets of the Composite class have the following
|
||
|
instance fields defined in the
|
||
|
<function>CompositePart</function>
|
||
|
structure.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct {
|
||
|
WidgetList children; See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: label' />
|
||
|
Cardinal num_children; See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: label' />
|
||
|
Cardinal num_slots; See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: label' />
|
||
|
XtOrderProc insert_position; See <xref linkend='Insertion_Order_of_Children_The_insert_position_Procedure' xrefstyle='select: label' />
|
||
|
} CompositePart;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
Composite
|
||
|
widgets have the Composite instance fields immediately following the Core
|
||
|
instance fields.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct {
|
||
|
CorePart core;
|
||
|
CompositePart composite;
|
||
|
} CompositeRec, *CompositeWidget;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
<function>Intrinsic.h</function>
|
||
|
uses an incomplete structure definition to ensure that the
|
||
|
compiler catches attempts to access private data.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct _CompositeRec *CompositeWidget;
|
||
|
</literallayout>
|
||
|
</sect3>
|
||
|
<sect3 id="Composite_Resources">
|
||
|
<title>Composite Resources</title>
|
||
|
<para>
|
||
|
The resource names, classes, and representation types
|
||
|
that are specified in
|
||
|
the
|
||
|
<function>compositeClassRec</function>
|
||
|
resource list are
|
||
|
</para>
|
||
|
|
||
|
<informaltable frame='topbot'>
|
||
|
<?dbfo keep-together="always" ?>
|
||
|
<tgroup cols='3' align='left' colsep='0' rowsep='0'>
|
||
|
<colspec colname='c1' colwidth='1.0*'/>
|
||
|
<colspec colname='c2' colwidth='1.0*'/>
|
||
|
<colspec colname='c3' colwidth='1.0*'/>
|
||
|
<thead>
|
||
|
<row rowsep='1'>
|
||
|
<entry>Name</entry>
|
||
|
<entry>Class</entry>
|
||
|
<entry>Representation</entry>
|
||
|
</row>
|
||
|
</thead>
|
||
|
<tbody>
|
||
|
<row>
|
||
|
<entry>XtNchildren</entry>
|
||
|
<entry>XtCReadOnly</entry>
|
||
|
<entry>XtRWidgetList</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>XtNinsertPosition</entry>
|
||
|
<entry>XtCInsertPosition</entry>
|
||
|
<entry>XtRFunction</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>XtNnumChildren</entry>
|
||
|
<entry>XtCReadOnly</entry>
|
||
|
<entry>XtRCardinal</entry>
|
||
|
</row>
|
||
|
</tbody>
|
||
|
</tgroup>
|
||
|
</informaltable>
|
||
|
|
||
|
</sect3>
|
||
|
<sect3 id="CompositePart_Default_Values">
|
||
|
<title>CompositePart Default Values</title>
|
||
|
<para>
|
||
|
The default values for the Composite fields,
|
||
|
which are filled in from the
|
||
|
Composite
|
||
|
resource list and by the
|
||
|
Composite
|
||
|
initialize procedure, are
|
||
|
</para>
|
||
|
|
||
|
<informaltable frame='topbot'>
|
||
|
<?dbfo keep-together="always" ?>
|
||
|
<?dbfo table-width="50%" ?>
|
||
|
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
||
|
<colspec colname='c1' colwidth='1.0*' colsep='0'/>
|
||
|
<colspec colname='c2' colwidth='1.0*' colsep='0'/>
|
||
|
<thead>
|
||
|
<row rowsep='1'>
|
||
|
<entry>Field</entry>
|
||
|
<entry>Default Value</entry>
|
||
|
</row>
|
||
|
</thead>
|
||
|
<tbody>
|
||
|
<row>
|
||
|
<entry>children</entry><entry>NULL</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>num_children</entry><entry>0</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>num_slots</entry><entry>0</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry>insert_position</entry><entry>Internal function to insert at end</entry>
|
||
|
</row>
|
||
|
</tbody>
|
||
|
</tgroup>
|
||
|
</informaltable>
|
||
|
|
||
|
<para>
|
||
|
The <emphasis remap='I'>children</emphasis>, <emphasis remap='I'>num_children</emphasis>,
|
||
|
and <emphasis remap='I'>insert_position</emphasis> fields are declared
|
||
|
as resources;
|
||
|
XtNinsertPosition
|
||
|
is a settable resource,
|
||
|
XtNchildren
|
||
|
and
|
||
|
XtNnumChildren
|
||
|
may be read by any client but should only be modified by the composite
|
||
|
widget class procedures.
|
||
|
</para>
|
||
|
</sect3>
|
||
|
</sect2>
|
||
|
|
||
|
<sect2 id="Constraint_Widgets">
|
||
|
<title>Constraint Widgets</title>
|
||
|
<para>
|
||
|
The Constraint
|
||
|
widget class is a subclass of the
|
||
|
Composite
|
||
|
widget class (see <xref linkend='Constrained_Composite_Widgets' />). 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
|
||
|
<function>ConstraintClassPart</function>
|
||
|
and
|
||
|
<function>ConstraintPart</function>
|
||
|
structures.
|
||
|
</para>
|
||
|
<sect3 id="ConstraintClassPart_Structure">
|
||
|
<title>ConstraintClassPart Structure</title>
|
||
|
<para>
|
||
|
In addition to the
|
||
|
Core
|
||
|
and
|
||
|
Composite
|
||
|
class fields,
|
||
|
widgets of the Constraint class
|
||
|
have the following class fields.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct {
|
||
|
XtResourceList resources; See <xref linkend='Resource_Management' xrefstyle='select: label' />
|
||
|
Cardinal num_resources; See <xref linkend='Resource_Management' xrefstyle='select: label' />
|
||
|
Cardinal constraint_size; See <xref linkend='Constrained_Composite_Widgets' xrefstyle='select: label' />
|
||
|
XtInitProc initialize; See <xref linkend='Constrained_Composite_Widgets' xrefstyle='select: label' />
|
||
|
XtWidgetProc destroy; See <xref linkend='Constrained_Composite_Widgets' xrefstyle='select: label' />
|
||
|
XtSetValuesFunc set_values; See <xref linkend='Setting_Widget_State' xrefstyle='select: label' />
|
||
|
XtPointer extension; See <xref linkend='Widget_Classing' xrefstyle='select: label' />
|
||
|
} ConstraintClassPart;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
The extension record defined for
|
||
|
<function>ConstraintClassPart</function>
|
||
|
with <emphasis remap='I'>record_type</emphasis> equal to
|
||
|
<emphasis role='strong'>NULLQUARK</emphasis>
|
||
|
is
|
||
|
<function>ConstraintClassExtensionRec</function>.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct {
|
||
|
XtPointer next_extension; See <xref linkend='Class_Extension_Records' xrefstyle='select: label' />
|
||
|
XrmQuark record_type; See <xref linkend='Class_Extension_Records' xrefstyle='select: label' />
|
||
|
long version; See <xref linkend='Class_Extension_Records' xrefstyle='select: label' />
|
||
|
Cardinal record_size; See <xref linkend='Class_Extension_Records' xrefstyle='select: label' />
|
||
|
XtArgsProc get_values_hook; See <xref linkend='Obtaining_Widget_State' xrefstyle='select: label' />
|
||
|
} ConstraintClassExtensionRec, *ConstraintClassExtension;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
Constraint
|
||
|
classes have the Constraint class fields immediately following the
|
||
|
Composite class fields.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct _ConstraintClassRec {
|
||
|
CoreClassPart core_class;
|
||
|
CompositeClassPart composite_class;
|
||
|
ConstraintClassPart constraint_class;
|
||
|
} ConstraintClassRec, *ConstraintWidgetClass;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
The single occurrences of the class record and pointer for creating
|
||
|
instances of Constraint are
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
In
|
||
|
<function>IntrinsicP.h</function>:
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
extern ConstraintClassRec constraintClassRec;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
In
|
||
|
<function>Intrinsic.h</function>:
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
extern WidgetClass constraintWidgetClass;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
The opaque types
|
||
|
<function>ConstraintWidget</function>
|
||
|
and
|
||
|
<function>ConstraintWidgetClass</function>
|
||
|
and the opaque variable
|
||
|
<function>constraintWidgetClass</function>
|
||
|
are defined for generic operations on widgets
|
||
|
whose class is Constraint or a subclass
|
||
|
of Constraint.
|
||
|
The symbolic constant for the
|
||
|
<function>ConstraintClassExtension</function>
|
||
|
version identifier is
|
||
|
<function>XtConstraintExtensionVersion</function>
|
||
|
(see <xref linkend='Class_Extension_Records' />).
|
||
|
<function>Intrinsic.h</function>
|
||
|
uses an incomplete structure definition to ensure that the
|
||
|
compiler catches attempts to access private data.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct _ConstraintClassRec *ConstraintWidgetClass;
|
||
|
</literallayout>
|
||
|
</sect3>
|
||
|
<sect3 id="ConstraintPart_Structure">
|
||
|
<title>ConstraintPart Structure</title>
|
||
|
<para>
|
||
|
In addition to the
|
||
|
Core
|
||
|
and
|
||
|
Composite instance
|
||
|
fields,
|
||
|
widgets of the Constraint class have the following unused
|
||
|
instance fields defined in the
|
||
|
<function>ConstraintPart</function>
|
||
|
structure
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct {
|
||
|
int empty;
|
||
|
} ConstraintPart;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
Constraint
|
||
|
widgets have the Constraint instance fields immediately following the
|
||
|
Composite instance fields.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct {
|
||
|
CorePart core;
|
||
|
CompositePart composite;
|
||
|
ConstraintPart constraint;
|
||
|
} ConstraintRec, *ConstraintWidget;
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
<function>Intrinsic.h</function>
|
||
|
uses an incomplete structure definition to ensure that the
|
||
|
compiler catches attempts to access private data.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
typedef struct _ConstraintRec *ConstraintWidget;
|
||
|
</literallayout>
|
||
|
</sect3>
|
||
|
<sect3 id="Constraint_Resources">
|
||
|
<title>Constraint Resources</title>
|
||
|
<para>
|
||
|
The
|
||
|
<function>constraintClassRec</function>
|
||
|
<emphasis remap='I'>core_class</emphasis> and <emphasis remap='I'>constraint_class resources</emphasis> fields are NULL,
|
||
|
and the <emphasis remap='I'>num_resources</emphasis> fields are zero;
|
||
|
no additional resources beyond those declared by
|
||
|
the superclasses
|
||
|
are defined for
|
||
|
Constraint.
|
||
|
</para>
|
||
|
</sect3>
|
||
|
</sect2>
|
||
|
</sect1>
|
||
|
|
||
|
<sect1 id="Implementation_Specific_Types">
|
||
|
<title>Implementation-Specific Types</title>
|
||
|
<para>
|
||
|
To increase the portability of widget and application source code
|
||
|
between different system environments, the Intrinsics define several
|
||
|
types whose precise representation is explicitly dependent upon,
|
||
|
and chosen by, each individual implementation of the Intrinsics.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
These implementation-defined types are
|
||
|
</para>
|
||
|
<variablelist>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis role='strong'>Boolean</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
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
|
||
|
<function>True</function>.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis role='strong'>Cardinal</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
An unsigned integer datum with a minimum range of [0..2^16-1].
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis role='strong'>Dimension</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
An unsigned integer datum with a minimum range of [0..2^16-1].
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis role='strong'>Position</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
A signed integer datum with a minimum range of [-2^15..2^15-1].
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis role='strong'>XtPointer</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
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
|
||
|
<function>XtPointer</function>
|
||
|
and back again and the result will
|
||
|
compare equal to the original value. In ANSI C
|
||
|
environments it is expected that
|
||
|
<function>XtPointer</function>
|
||
|
will be
|
||
|
defined as void*.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis role='strong'>XtArgVal</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
A datum large enough to contain an
|
||
|
<function>XtPointer</function>,
|
||
|
<function>Cardinal</function>,
|
||
|
<function>Dimension</function>,
|
||
|
or
|
||
|
<function>Position</function>
|
||
|
value.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis role='strong'>XtEnum</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
An integer datum large enough to encode at least 128 distinct
|
||
|
values, two of which are the symbolic values
|
||
|
<function>True</function>
|
||
|
and
|
||
|
<function>False</function>.
|
||
|
The symbolic values
|
||
|
<emphasis role='strong'>TRUE</emphasis>
|
||
|
and
|
||
|
<emphasis role='strong'>FALSE</emphasis>
|
||
|
are
|
||
|
also defined to be equal to
|
||
|
<function>True</function>
|
||
|
and
|
||
|
<function>False</function>,
|
||
|
respectively.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
</variablelist>
|
||
|
|
||
|
<para>
|
||
|
In addition to these specific types, the precise order of the
|
||
|
fields within the structure declarations for any of the instance
|
||
|
part records
|
||
|
<function>ObjectPart</function>,
|
||
|
<function>RectObjPart</function>,
|
||
|
<function>CorePart</function>,
|
||
|
<function>CompositePart</function>,
|
||
|
<function>ShellPart</function>,
|
||
|
<function>WMShellPart</function>,
|
||
|
<function>TopLevelShellPart</function>,
|
||
|
and
|
||
|
<function>ApplicationShellPart</function>
|
||
|
is implementation-defined. These
|
||
|
structures may also have additional private
|
||
|
fields internal to the implementation.
|
||
|
The
|
||
|
<function>ObjectPart</function>,
|
||
|
<function>RectObjPart</function>,
|
||
|
and
|
||
|
<function>CorePart</function>
|
||
|
structures must be defined so that any member with the same name
|
||
|
appears at the same offset in
|
||
|
<function>ObjectRec</function>,
|
||
|
<function>RectObjRec</function>,
|
||
|
and
|
||
|
<function>CoreRec</function>
|
||
|
<function>( WidgetRec ).</function>
|
||
|
No other relations between the offsets of any two
|
||
|
fields may be assumed.
|
||
|
</para>
|
||
|
</sect1>
|
||
|
|
||
|
<sect1 id="Widget_Classing">
|
||
|
<title>Widget Classing</title>
|
||
|
<para>
|
||
|
The <emphasis remap='I'>widget_class</emphasis> 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.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
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
|
||
|
<function>XtResourceList</function>.
|
||
|
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).
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
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.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
To make good use of subclassing,
|
||
|
widget declarations and naming conventions are highly stylized.
|
||
|
A widget consists of three files:
|
||
|
</para>
|
||
|
<itemizedlist spacing='compact'>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
A public .h file, used by client widgets or applications.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
A private .h file, used by widgets whose classes
|
||
|
are subclasses of the widget class.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
A .c file, which implements the widget.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</itemizedlist>
|
||
|
<sect2 id="Widget_Naming_Conventions">
|
||
|
<title>Widget Naming Conventions</title>
|
||
|
<para>
|
||
|
The Intrinsics provide a vehicle by which programmers can create
|
||
|
new widgets and organize a collection of widgets into an application.
|
||
|
To ensure that applications need not deal with as many styles of capitalization
|
||
|
and spelling as the number of widget classes it uses,
|
||
|
the following guidelines should be followed when writing new widgets:
|
||
|
</para>
|
||
|
<itemizedlist spacing='compact'>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
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,
|
||
|
<function>ArgList</function>
|
||
|
or
|
||
|
<function>XtSetValues ).</function>
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
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 <emphasis remap='I'>background_pixmap</emphasis> field has the corresponding identifier
|
||
|
XtNbackgroundPixmap,
|
||
|
which is defined as the string ``backgroundPixmap''.
|
||
|
Many predefined names are listed in
|
||
|
<function><X11/StringDefs.h></function>.
|
||
|
Before you invent a new name,
|
||
|
you should make sure there is not already a name that you can use.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
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
|
||
|
<function><X11/StringDefs.h></function>.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
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
|
||
|
<function><X11/StringDefs.h></function>.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
New widget classes start with a capital and use uppercase for compound
|
||
|
words.
|
||
|
Given a new class name AbcXyz, you should derive several names:
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<itemizedlist spacing='compact'>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Additional widget instance structure part name AbcXyzPart.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Complete widget instance structure names AbcXyzRec and _AbcXyzRec.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Widget instance structure pointer type name AbcXyzWidget.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Additional class structure part name AbcXyzClassPart.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Complete class structure names AbcXyzClassRec and _AbcXyzClassRec.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Class structure pointer type name AbcXyzWidgetClass.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Class structure variable abcXyzClassRec.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Class structure pointer variable abcXyzWidgetClass.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</itemizedlist>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
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'').
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</itemizedlist>
|
||
|
<para>
|
||
|
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
|
||
|
<function>String</function>.
|
||
|
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.
|
||
|
</para>
|
||
|
</sect2>
|
||
|
|
||
|
<sect2 id="Widget_Subclassing_in_Public_h_Files">
|
||
|
<title>Widget Subclassing in Public .h Files</title>
|
||
|
<para>
|
||
|
The public .h file for a widget class is imported by clients
|
||
|
and contains
|
||
|
</para>
|
||
|
<itemizedlist spacing='compact'>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
A reference to the public .h file for the superclass.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
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.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Type declarations for any new resource data types defined by the class.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
The class record pointer variable used to create widget instances.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
The C type that corresponds to widget instances of this class.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Entry points for new class methods.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</itemizedlist>
|
||
|
<para>
|
||
|
For example, the following is the public .h file for a possible
|
||
|
implementation of a Label widget:
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
#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
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
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.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
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
|
||
|
<function>Constraint.h</function>.
|
||
|
</para>
|
||
|
</sect2>
|
||
|
|
||
|
<sect2 id="Widget_Subclassing_in_Private_h_Files">
|
||
|
<title>Widget Subclassing in Private .h Files</title>
|
||
|
<para>
|
||
|
The private .h file for a widget is imported by widget classes that are
|
||
|
subclasses of the widget and contains
|
||
|
</para>
|
||
|
<itemizedlist spacing='compact'>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
A reference to the public .h file for the class.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
A reference to the private .h file for the superclass.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
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.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
A structure part definition for
|
||
|
the new fields that the widget instance adds to its superclass's
|
||
|
widget structure.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
The complete widget instance structure definition for this widget.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
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.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
The complete
|
||
|
constraint
|
||
|
structure definition if the widget class is a subclass of
|
||
|
Constraint.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Type definitions for any new procedure types used by class methods
|
||
|
declared in the widget class part.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
A structure part definition for
|
||
|
the new fields that this widget class adds to its superclass's widget class
|
||
|
structure.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
The complete widget class structure definition for this widget.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
The complete widget class extension structure definition
|
||
|
for this widget, if any.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
The symbolic constant identifying the class extension version, if any.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
The name of the global class structure variable containing the generic
|
||
|
class structure for this class.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
An inherit constant for each new procedure in the widget class part structure.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</itemizedlist>
|
||
|
<para>
|
||
|
For example, the following is the private .h file for a possible Label widget:
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
#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;
|
||
|
</literallayout>
|
||
|
<literallayout>
|
||
|
/* 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
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
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
|
||
|
<function>ConstrainP.h</function>.
|
||
|
</para>
|
||
|
</sect2>
|
||
|
|
||
|
<sect2 id="Widget_Subclassing_in_c_Files">
|
||
|
<title>Widget Subclassing in .c Files</title>
|
||
|
<para>
|
||
|
The .c file for a widget contains the structure initializer
|
||
|
for the class record variable,
|
||
|
which contains the following parts:
|
||
|
</para>
|
||
|
<itemizedlist spacing='compact'>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Class information (for example, <emphasis remap='I'>superclass</emphasis>, <emphasis remap='I'>class_name</emphasis>,
|
||
|
<emphasis remap='I'>widget_size</emphasis>,
|
||
|
<emphasis remap='I'>class_initialize</emphasis>, and <emphasis remap='I'>class_inited</emphasis>).
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Data constants (for example, <emphasis remap='I'>resources</emphasis> and <emphasis remap='I'>num_resources</emphasis>,
|
||
|
<emphasis remap='I'>actions</emphasis> and <emphasis remap='I'>num_actions</emphasis>, <emphasis remap='I'>visible_interest</emphasis>,
|
||
|
<emphasis remap='I'>compress_motion</emphasis>,
|
||
|
<emphasis remap='I'>compress_exposure</emphasis>, and <emphasis remap='I'>version</emphasis>).
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Widget operations (for example, <emphasis remap='I'>initialize</emphasis>, <emphasis remap='I'>realize</emphasis>, <emphasis remap='I'>destroy</emphasis>,
|
||
|
<emphasis remap='I'>resize</emphasis>, <emphasis remap='I'>expose</emphasis>, <emphasis remap='I'>set_values</emphasis>, <emphasis remap='I'>accept_focus</emphasis>,
|
||
|
and any new operations specific to
|
||
|
the widget).
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</itemizedlist>
|
||
|
<para>
|
||
|
The <emphasis remap='I'>superclass</emphasis> field points to the superclass
|
||
|
global class
|
||
|
record, declared in the superclass private .h file.
|
||
|
For direct subclasses of the generic core widget,
|
||
|
<emphasis remap='I'>superclass</emphasis> should be initialized to the address of the
|
||
|
<function>widgetClassRec</function>
|
||
|
structure.
|
||
|
The superclass is used for class chaining operations and for
|
||
|
inheriting or enveloping a superclass's operations
|
||
|
(see <xref linkend='Superclass_Chaining' />,
|
||
|
<xref linkend='Initializing_a_Widget_Class' />, and
|
||
|
<xref linkend='Inheritance_of_Superclass_Operations' />.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The <emphasis remap='I'>class_name</emphasis> 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.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The <emphasis remap='I'>widget_size</emphasis> field is the size of the corresponding widget
|
||
|
instance structure
|
||
|
(not the size of the class structure).
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The <emphasis remap='I'>version</emphasis> field indicates the toolkit
|
||
|
implementation version number and is used for
|
||
|
runtime consistency checking of the X Toolkit and widgets in an application.
|
||
|
Widget writers must set it to the
|
||
|
implementation-defined symbolic value
|
||
|
<function>XtVersion</function>
|
||
|
in the widget class structure initialization.
|
||
|
Those widget writers who believe that their widget binaries are compatible
|
||
|
with other implementations of the Intrinsics can put the special value
|
||
|
<function>XtVersionDontCheck</function>
|
||
|
in the <emphasis remap='I'>version</emphasis> field to disable version checking for those widgets.
|
||
|
If a widget needs to compile alternative code for different
|
||
|
revisions of the Intrinsics interface definition, it may use the symbol
|
||
|
<function>XtSpecificationRelease</function>,
|
||
|
as described in <xref linkend='Evolution_of_the_Intrinsics' />.
|
||
|
Use of
|
||
|
<function>XtVersion</function>
|
||
|
allows the Intrinsics implementation to recognize widget binaries
|
||
|
that were compiled with older implementations.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The <emphasis remap='I'>extension</emphasis> 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.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
All other fields are described in their respective sections.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
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 <xref linkend='Resource_Management' />.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
/* 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();
|
||
|
.
|
||
|
.
|
||
|
.
|
||
|
</literallayout>
|
||
|
<literallayout>
|
||
|
/* Class record constant */
|
||
|
LabelClassRec labelClassRec = {
|
||
|
{
|
||
|
/* core_class fields */
|
||
|
/* superclass */ (WidgetClass)&coreClassRec,
|
||
|
/* class_name */ "Label",
|
||
|
/* widget_size */ sizeof(LabelRec),
|
||
|
/* class_initialize */ ClassInitialize,
|
||
|
/* class_part_initialize */ NULL,
|
||
|
/* class_inited */ False,
|
||
|
/* initialize */ Initialize,
|
||
|
/* initialize_hook */ NULL,
|
||
|
/* realize */ Realize,
|
||
|
/* actions */ NULL,
|
||
|
/* num_actions */ 0,
|
||
|
/* resources */ resources,
|
||
|
/* num_resources */ XtNumber(resources),
|
||
|
/* xrm_class */ NULLQUARK,
|
||
|
/* compress_motion */ True,
|
||
|
/* compress_exposure */ True,
|
||
|
/* compress_enterleave */ True,
|
||
|
/* visible_interest */ False,
|
||
|
/* destroy */ NULL,
|
||
|
/* resize */ Resize,
|
||
|
/* expose */ Redisplay,
|
||
|
/* set_values */ SetValues,
|
||
|
/* set_values_hook */ NULL,
|
||
|
/* set_values_almost */ XtInheritSetValuesAlmost,
|
||
|
/* get_values_hook */ NULL,
|
||
|
/* accept_focus */ NULL,
|
||
|
/* version */ XtVersion,
|
||
|
/* callback_offsets */ NULL,
|
||
|
/* tm_table */ NULL,
|
||
|
/* query_geometry */ XtInheritQueryGeometry,
|
||
|
/* display_accelerator */ NULL,
|
||
|
/* extension */ NULL
|
||
|
},
|
||
|
{
|
||
|
/* Label_class fields */
|
||
|
/* get_text */ GetText,
|
||
|
/* set_text */ SetText,
|
||
|
/* extension */ NULL
|
||
|
}
|
||
|
};
|
||
|
/* Class record pointer */
|
||
|
WidgetClass labelWidgetClass = (WidgetClass) &labelClassRec;
|
||
|
/* New method access routines */
|
||
|
void LabelSetText(w, text)
|
||
|
Widget w;
|
||
|
String text;
|
||
|
{
|
||
|
LabelWidgetClass lwc = (Label WidgetClass)XtClass(w);
|
||
|
XtCheckSubclass(w, labelWidgetClass, NULL);
|
||
|
*(lwc->label_class.set_text)(w, text)
|
||
|
}
|
||
|
/* Private procedures */
|
||
|
.
|
||
|
.
|
||
|
.
|
||
|
</literallayout>
|
||
|
</sect2>
|
||
|
|
||
|
<sect2 id="Widget_Class_and_Superclass_Look_Up">
|
||
|
<title>Widget Class and Superclass Look Up</title>
|
||
|
<para>
|
||
|
To obtain the class of a widget, use
|
||
|
<xref linkend='XtClass' xrefstyle='select: title'/>.
|
||
|
</para>
|
||
|
|
||
|
|
||
|
|
||
|
<funcsynopsis id='XtClass'>
|
||
|
<funcprototype>
|
||
|
<funcdef>WidgetClass <function>XtClass</function></funcdef>
|
||
|
<paramdef>Widget<parameter> w</parameter></paramdef>
|
||
|
</funcprototype>
|
||
|
</funcsynopsis>
|
||
|
|
||
|
<variablelist>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>w</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies the widget. Must be of class Object or any subclass thereof.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
</variablelist>
|
||
|
|
||
|
|
||
|
<para>
|
||
|
The
|
||
|
<xref linkend='XtClass' xrefstyle='select: title'/>
|
||
|
function returns a pointer to the widget's class structure.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
To obtain the superclass of a widget, use
|
||
|
<function>XtSuperclass</function>.
|
||
|
</para>
|
||
|
|
||
|
<!--
|
||
|
-->
|
||
|
<funcsynopsis id='XtSuperClass'>
|
||
|
<funcprototype>
|
||
|
<funcdef>WidgetClass <function>XtSuperClass</function></funcdef>
|
||
|
<paramdef>Widget<parameter> w</parameter></paramdef>
|
||
|
</funcprototype>
|
||
|
</funcsynopsis>
|
||
|
|
||
|
<variablelist>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>w</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies the widget. Must be of class Object or any subclass thereof.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
</variablelist>
|
||
|
<!--
|
||
|
-->
|
||
|
|
||
|
<para>
|
||
|
The
|
||
|
<function>XtSuperclass</function>
|
||
|
function returns a pointer to the widget's superclass class structure.
|
||
|
</para>
|
||
|
</sect2>
|
||
|
|
||
|
<sect2 id="Widget_Subclass_Verification">
|
||
|
<title>Widget Subclass Verification</title>
|
||
|
<para>
|
||
|
To check the subclass to which a widget belongs, use
|
||
|
<xref linkend='XtIsSubclass' xrefstyle='select: title'/>.
|
||
|
</para>
|
||
|
|
||
|
<funcsynopsis id='XtIsSubclass'>
|
||
|
<funcprototype>
|
||
|
<funcdef>Boolean <function>XtIsSubclass</function></funcdef>
|
||
|
<paramdef>Widget<parameter> w</parameter></paramdef>
|
||
|
<paramdef>WidgetClass<parameter> widget_class</parameter></paramdef>
|
||
|
</funcprototype>
|
||
|
</funcsynopsis>
|
||
|
|
||
|
<variablelist>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>w</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies the widget or object instance whose class is to be checked. Must be of class Object or any subclass thereof.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>widget_class</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies the widget class for which to test. Must be <emphasis role='strong'>objectClass</emphasis> or any subclass thereof.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
</variablelist>
|
||
|
|
||
|
|
||
|
<para>
|
||
|
The
|
||
|
<xref linkend='XtIsSubclass' xrefstyle='select: title'/>
|
||
|
function returns
|
||
|
<function>True</function>
|
||
|
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
|
||
|
<xref linkend='XtIsSubclass' xrefstyle='select: title'/>
|
||
|
to find out if a widget belongs to the desired class of objects.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
To test if a given widget belongs to a subclass of an Intrinsics-defined
|
||
|
class, the Intrinsics define macros or functions equivalent to
|
||
|
<xref linkend='XtIsSubclass' xrefstyle='select: title'/>
|
||
|
for each of the built-in classes. These procedures are
|
||
|
<function>XtIsObject</function>,
|
||
|
<function>XtIsRectObj</function>,
|
||
|
<function>XtIsWidget</function>,
|
||
|
<function>XtIsComposite</function>,
|
||
|
<function>XtIsConstraint</function>,
|
||
|
<function>XtIsShell</function>,
|
||
|
<function>XtIsOverrideShell</function>,
|
||
|
<function>XtIsWMShell</function>,
|
||
|
<function>XtIsVendorShell</function>,
|
||
|
<function>XtIsTransientShell</function>,
|
||
|
<function>XtIsTopLevelShell</function>,
|
||
|
<function>XtIsApplicationShell</function>,
|
||
|
and
|
||
|
<function>XtIsSessionShell</function>.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
All these macros and functions have the same argument description.
|
||
|
</para>
|
||
|
|
||
|
<funcsynopsis id='XtIs'>
|
||
|
<funcprototype>
|
||
|
<funcdef>Boolean <function>XtIs</function></funcdef>
|
||
|
<paramdef>Widget<parameter> w</parameter></paramdef>
|
||
|
</funcprototype>
|
||
|
</funcsynopsis>
|
||
|
|
||
|
<variablelist>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>w</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies the widget or object instance whose class is to be checked. Must be of class Object or any subclass thereof.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
</variablelist>
|
||
|
|
||
|
<para>
|
||
|
These procedures may be faster than calling
|
||
|
<xref linkend='XtIsSubclass' xrefstyle='select: title'/>
|
||
|
directly for the built-in classes.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
To check a widget's class
|
||
|
and to generate a debugging error message, use
|
||
|
<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>,
|
||
|
defined in
|
||
|
<function><X11/IntrinsicP.h></function>:
|
||
|
</para>
|
||
|
|
||
|
<funcsynopsis id='XtCheckSubclass'>
|
||
|
<funcprototype>
|
||
|
<funcdef>void <function>XtCheckSubclass</function></funcdef>
|
||
|
<paramdef>Widget<parameter> w</parameter></paramdef>
|
||
|
<paramdef>WidgetClass<parameter> widget_class</parameter></paramdef>
|
||
|
<paramdef>String<parameter> message</parameter></paramdef>
|
||
|
</funcprototype>
|
||
|
</funcsynopsis>
|
||
|
|
||
|
<variablelist>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>w</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies the widget or object whose class is to be checked. Must be of class Object or any subclass thereof.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>widget_class</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies the widget class for which to test. Must be <emphasis role='strong'>objectClass</emphasis> or any subclass thereof.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>message</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies the message to be used.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
</variablelist>
|
||
|
|
||
|
<para>
|
||
|
The
|
||
|
<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>
|
||
|
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,
|
||
|
<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>
|
||
|
constructs an error message from the supplied message,
|
||
|
the widget's actual class, and the expected class and calls
|
||
|
<xref linkend='XtErrorMsg' xrefstyle='select: title'/>.
|
||
|
<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>
|
||
|
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.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>
|
||
|
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.
|
||
|
</para>
|
||
|
</sect2>
|
||
|
|
||
|
<sect2 id="Superclass_Chaining">
|
||
|
<title>Superclass Chaining</title>
|
||
|
<para>
|
||
|
While most fields in a widget class structure are self-contained,
|
||
|
some fields are linked to their corresponding fields in their superclass
|
||
|
structures.
|
||
|
With a linked field,
|
||
|
the Intrinsics access the field's value only after accessing its corresponding
|
||
|
superclass value (called downward superclass chaining) or
|
||
|
before accessing its corresponding superclass value (called upward superclass
|
||
|
chaining). The self-contained fields are</para>
|
||
|
<literallayout>
|
||
|
In all widget classes: <emphasis remap='I'>class_name</emphasis>
|
||
|
<emphasis remap='I'>class_initialize</emphasis>
|
||
|
<emphasis remap='I'>widget_size</emphasis>
|
||
|
<emphasis remap='I'>realize</emphasis>
|
||
|
<emphasis remap='I'>visible_interest</emphasis>
|
||
|
<emphasis remap='I'>resize</emphasis>
|
||
|
<emphasis remap='I'>expose</emphasis>
|
||
|
<emphasis remap='I'>accept_focus</emphasis>
|
||
|
<emphasis remap='I'>compress_motion</emphasis>
|
||
|
<emphasis remap='I'>compress_exposure</emphasis>
|
||
|
<emphasis remap='I'>compress_enterleave</emphasis>
|
||
|
<emphasis remap='I'>set_values_almost</emphasis>
|
||
|
<emphasis remap='I'>tm_table</emphasis>
|
||
|
<emphasis remap='I'>version</emphasis>
|
||
|
<emphasis remap='I'>allocate</emphasis>
|
||
|
<emphasis remap='I'>deallocate</emphasis>
|
||
|
|
||
|
In Composite widget classes: <emphasis remap='I'>geometry_manager</emphasis>
|
||
|
<emphasis remap='I'>change_managed</emphasis>
|
||
|
<emphasis remap='I'>insert_child</emphasis>
|
||
|
<emphasis remap='I'>delete_child</emphasis>
|
||
|
<emphasis remap='I'>accepts_objects</emphasis>
|
||
|
<emphasis remap='I'>allows_change_managed_set</emphasis>
|
||
|
|
||
|
In Constraint widget classes: <emphasis remap='I'>constraint_size</emphasis>
|
||
|
|
||
|
In Shell widget classes: <emphasis remap='I'>root_geometry_manager</emphasis>
|
||
|
</literallayout>
|
||
|
|
||
|
<para>
|
||
|
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
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
<emphasis remap='I'>class_part_initialize</emphasis>
|
||
|
<emphasis remap='I'>get_values_hook</emphasis>
|
||
|
<emphasis remap='I'>initialize</emphasis>
|
||
|
<emphasis remap='I'>initialize_hook</emphasis>
|
||
|
<emphasis remap='I'>set_values</emphasis>
|
||
|
<emphasis remap='I'>set_values_hook</emphasis>
|
||
|
<emphasis remap='I'>resources</emphasis>
|
||
|
</literallayout>
|
||
|
|
||
|
<para>
|
||
|
In addition, for subclasses of
|
||
|
Constraint,
|
||
|
the following fields of the
|
||
|
<function>ConstraintClassPart</function>
|
||
|
and
|
||
|
<function>ConstraintClassExtensionRec</function>
|
||
|
structures are chained from the
|
||
|
Constraint
|
||
|
class down to the subclass:
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
<emphasis remap='I'>resources</emphasis>
|
||
|
<emphasis remap='I'>initialize</emphasis>
|
||
|
<emphasis remap='I'>set_values</emphasis>
|
||
|
<emphasis remap='I'>get_values_hook</emphasis>
|
||
|
</literallayout>
|
||
|
|
||
|
<para>
|
||
|
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
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
<emphasis remap='I'>destroy</emphasis>
|
||
|
<emphasis remap='I'>actions</emphasis>
|
||
|
</literallayout>
|
||
|
|
||
|
<para>
|
||
|
For subclasses of
|
||
|
Constraint,
|
||
|
the following field of
|
||
|
<function>ConstraintClassPart</function>
|
||
|
is chained from the subclass up to the
|
||
|
Constraint class:
|
||
|
<emphasis remap='I'>destroy</emphasis>
|
||
|
</para>
|
||
|
</sect2>
|
||
|
|
||
|
<sect2 id="Class_Initialization_class_initialize_and_class_part_initialize_Procedures">
|
||
|
<title>Class Initialization: class_initialize and class_part_initialize Procedures</title>
|
||
|
<para>
|
||
|
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.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
Because the C language does not have initialization procedures
|
||
|
that are invoked automatically when a program starts up,
|
||
|
a widget class can declare a class_initialize procedure
|
||
|
that will be automatically called exactly once by the Intrinsics.
|
||
|
A class initialization procedure pointer is of type
|
||
|
<function>XtProc</function>:
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
typedef void (*XtProc)(void);
|
||
|
</para>
|
||
|
<para>
|
||
|
A widget class indicates that it has no class initialization procedure by
|
||
|
specifying NULL in the <emphasis remap='I'>class_initialize</emphasis> field.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
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 <emphasis remap='I'>class_part_initialize</emphasis> field.
|
||
|
The class_part_initialize procedure pointer is of type
|
||
|
<function>XtWidgetClassProc</function>.
|
||
|
</para>
|
||
|
|
||
|
<funcsynopsis>
|
||
|
<funcprototype>
|
||
|
<funcdef>void <function>(*XtWidgetClassProc)(WidgetClass)</function></funcdef>
|
||
|
<paramdef>WidgetClass<parameter> widget_class</parameter></paramdef>
|
||
|
</funcprototype>
|
||
|
</funcsynopsis>
|
||
|
|
||
|
<variablelist>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>widget_class</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Points to the class structure for the class being initialized.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
</variablelist>
|
||
|
<para>
|
||
|
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 <xref linkend='Initializing_a_Widget_Class' />
|
||
|
Classes that do not define any new class fields
|
||
|
or that need no extra processing for them can specify NULL
|
||
|
in the <emphasis remap='I'>class_part_initialize</emphasis> field.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
All widget classes, whether they have a class initialization procedure or not,
|
||
|
must start with their <emphasis remap='I'>class_inited</emphasis> field
|
||
|
<function>False</function>.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The first time a widget of a class is created,
|
||
|
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
|
||
|
ensures that the widget class and all superclasses are initialized, in
|
||
|
superclass-to-subclass order, by checking each <emphasis remap='I'>class_inited</emphasis> field and,
|
||
|
if it is
|
||
|
<function>False</function>,
|
||
|
by calling the class_initialize and the class_part_initialize procedures
|
||
|
for the class and all its superclasses.
|
||
|
The Intrinsics then set the <emphasis remap='I'>class_inited</emphasis> field to a nonzero value.
|
||
|
After the one-time initialization,
|
||
|
a class structure is constant.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The following example provides the class initialization procedure for a Label class.
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
static void ClassInitialize()
|
||
|
{
|
||
|
XtSetTypeConverter(XtRString, XtRJustify, CvtStringToJustify,
|
||
|
NULL, 0, XtCacheNone, NULL);
|
||
|
}
|
||
|
</literallayout>
|
||
|
</sect2>
|
||
|
|
||
|
<sect2 id="Initializing_a_Widget_Class">
|
||
|
<title>Initializing a Widget Class</title>
|
||
|
<para>
|
||
|
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
|
||
|
<xref linkend='XtInitializeWidgetClass' xrefstyle='select: title'/>.
|
||
|
</para>
|
||
|
|
||
|
<funcsynopsis id='XtInitializeWidgetClass'>
|
||
|
<funcprototype>
|
||
|
<funcdef>void <function>XtInitializeWidgetClass</function></funcdef>
|
||
|
<paramdef>WidgetClass<parameter> object_class</parameter></paramdef>
|
||
|
</funcprototype>
|
||
|
</funcsynopsis>
|
||
|
|
||
|
<variablelist>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>object_class</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies the object class to initialize. May be
|
||
|
<function>objectClass</function>
|
||
|
or any subclass thereof.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
</variablelist>
|
||
|
|
||
|
<para>
|
||
|
If the specified widget class is already initialized,
|
||
|
<xref linkend='XtInitializeWidgetClass' xrefstyle='select: title'/>
|
||
|
returns immediately.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
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
|
||
|
<xref linkend='XtInitializeWidgetClass' xrefstyle='select: title'/>
|
||
|
is called
|
||
|
(see <xref linkend='Resource_Conversions' />).
|
||
|
</para>
|
||
|
</sect2>
|
||
|
|
||
|
<sect2 id="Inheritance_of_Superclass_Operations">
|
||
|
<title>Inheritance of Superclass Operations</title>
|
||
|
<para>
|
||
|
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
|
||
|
</para>
|
||
|
<itemizedlist spacing='compact'>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
expose
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
realize
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
insert_child
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
delete_child
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
geometry_manager
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
set_values_almost
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</itemizedlist>
|
||
|
|
||
|
<para>
|
||
|
To inherit an operation <emphasis remap='I'>xyz</emphasis>,
|
||
|
specify the constant
|
||
|
<function>XtInherit</function> <emphasis remap='I'>Xyz</emphasis>
|
||
|
in your class record.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
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.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
Inheriting works by comparing the value of the field with a known, special
|
||
|
value and by copying in the superclass's value for that field if a match
|
||
|
occurs.
|
||
|
This special value, called the inheritance constant,
|
||
|
is usually the Intrinsics internal value
|
||
|
<function>_XtInherit</function>
|
||
|
cast to the appropriate type.
|
||
|
<function>_XtInherit</function>
|
||
|
is a procedure that issues an error message if it is actually called.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
For example,
|
||
|
<function>CompositeP.h</function>
|
||
|
contains these definitions:
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
#define XtInheritGeometryManager ((XtGeometryHandler) _XtInherit)
|
||
|
#define XtInheritChangeManaged ((XtWidgetProc) _XtInherit)
|
||
|
#define XtInheritInsertChild ((XtArgsProc) _XtInherit)
|
||
|
#define XtInheritDeleteChild ((XtWidgetProc) _XtInherit)
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
Composite's class_part_initialize procedure begins as follows:
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
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;
|
||
|
}
|
||
|
.
|
||
|
.
|
||
|
.
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
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:
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
For Object:
|
||
|
</para>
|
||
|
<itemizedlist spacing='compact'>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<function>XtInheritAllocate</function>
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<function>XtInheritDeallocate</function>
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</itemizedlist>
|
||
|
<para>
|
||
|
For Core:
|
||
|
</para>
|
||
|
<itemizedlist spacing='compact'>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<function>XtInheritRealize</function>
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<function>XtInheritResize</function>
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<function>XtInheritExpose</function>
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<function>XtInheritSetValuesAlmost</function>
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<function>XtInheritAcceptFocus</function>
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<function>XtInheritQueryGeometry</function>
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<function>XtInheritTranslations</function>
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<function>XtInheritDisplayAccelerator</function>
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</itemizedlist>
|
||
|
<para>
|
||
|
For Composite:
|
||
|
</para>
|
||
|
<itemizedlist spacing='compact'>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<function>XtInheritGeometryManager</function>
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<function>XtInheritChangeManaged</function>
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<function>XtInheritInsertChild</function>
|
||
|
</para>
|
||
|
</listitem>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<function>XtInheritDeleteChild</function>
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</itemizedlist>
|
||
|
<para>
|
||
|
For Shell:
|
||
|
</para>
|
||
|
<itemizedlist spacing='compact'>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
<function>XtInheritRootGeometryManager</function>
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</itemizedlist>
|
||
|
</sect2>
|
||
|
|
||
|
<sect2 id="Invocation_of_Superclass_Operations">
|
||
|
<title>Invocation of Superclass Operations</title>
|
||
|
<para>
|
||
|
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 <emphasis remap='I'>expose</emphasis>
|
||
|
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 <emphasis remap='I'>insert_child</emphasis>
|
||
|
and then calling
|
||
|
<xref linkend='XtManageChild' xrefstyle='select: title'/>
|
||
|
to add the child to the managed set.
|
||
|
</para>
|
||
|
|
||
|
<note>
|
||
|
<para>
|
||
|
A class method should not use
|
||
|
<function>XtSuperclass</function>
|
||
|
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.
|
||
|
</para>
|
||
|
</note>
|
||
|
<para>
|
||
|
This technique is referred to as <emphasis remap='I'>enveloping</emphasis> the superclass's operation.
|
||
|
</para>
|
||
|
</sect2>
|
||
|
|
||
|
<sect2 id="Class_Extension_Records">
|
||
|
<title>Class Extension Records</title>
|
||
|
<para>
|
||
|
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.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
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
|
||
|
<emphasis remap='I'>extension</emphasis> pointer for the appropriate part in their class structure to
|
||
|
point to a statically declared extension record containing the
|
||
|
additional fields.
|
||
|
Setting the <emphasis remap='I'>extension</emphasis> field is never mandatory; code that uses fields
|
||
|
in the extension record must always check the <emphasis remap='I'>extension</emphasis> field and take
|
||
|
some appropriate default action if it is NULL.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
In order to permit multiple subclasses and libraries to chain extension
|
||
|
records from a single <emphasis remap='I'>extension</emphasis> 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:
|
||
|
</para>
|
||
|
<literallayout>
|
||
|
struct {
|
||
|
XtPointer next_extension;
|
||
|
XrmQuark record_type;
|
||
|
long version;
|
||
|
Cardinal record_size;
|
||
|
};
|
||
|
</literallayout>
|
||
|
|
||
|
<variablelist>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>next_extension</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies the next record in the list, or NULL.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>record_type</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies the particular structure declaration to which
|
||
|
each extension record instance conforms.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>version</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies a version id symbolic constant supplied by
|
||
|
the definer of the structure.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>record_size</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies the total number of bytes allocated for the
|
||
|
extension record.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
</variablelist>
|
||
|
|
||
|
<para>
|
||
|
The <emphasis remap='I'>record_type</emphasis> 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
|
||
|
<emphasis remap='I'>record_type</emphasis> field is normally assigned the
|
||
|
result of
|
||
|
<function>XrmStringToQuark</function>
|
||
|
for a registered string constant. The
|
||
|
Intrinsics reserve all record type strings beginning with the two
|
||
|
characters ``XT'' for future standard uses. The value
|
||
|
<emphasis role='strong'>NULLQUARK</emphasis>
|
||
|
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.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The <emphasis remap='I'>version</emphasis> 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 <emphasis remap='I'>record_size</emphasis> field value includes the four common header fields and
|
||
|
should normally be initialized with
|
||
|
<function>sizeof ().</function>
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
Any value stored in the class part extension fields of
|
||
|
<function>CompositeClassPart</function>,
|
||
|
<function>ConstraintClassPart</function>,
|
||
|
or
|
||
|
<function>ShellClassPart</function>
|
||
|
must point to an extension record conforming to this definition.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The Intrinsics provide a utility function for widget writers to locate a
|
||
|
particular class extension record in a linked list, given a widget class
|
||
|
and the offset of the <emphasis remap='I'>extension</emphasis> field in the class record.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
To locate a class extension record, use
|
||
|
<xref linkend='XtGetClassExtension' xrefstyle='select: title'/>.
|
||
|
</para>
|
||
|
|
||
|
<funcsynopsis id='XtGetClassExtension'>
|
||
|
<funcprototype>
|
||
|
<funcdef>XtPointer <function>XtGetClassExtension</function></funcdef>
|
||
|
<paramdef>WidgetClass<parameter> object_class</parameter></paramdef>
|
||
|
<paramdef>Cardinal<parameter> byte_offset</parameter></paramdef>
|
||
|
<paramdef>XrmQuark<parameter> type</parameter></paramdef>
|
||
|
<paramdef>long<parameter> version</parameter></paramdef>
|
||
|
<paramdef>Cardinal<parameter> record_size</parameter></paramdef>
|
||
|
</funcprototype>
|
||
|
</funcsynopsis>
|
||
|
|
||
|
<variablelist>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>object_class</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies the object class containing the extension list to be searched.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>byte_offset</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies the offset in bytes from the base of the
|
||
|
class record of the extension field to be searched.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>type</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies the record_type of the class extension to be located.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>version</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies the minimum acceptable version of the class
|
||
|
extension required for a match.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>
|
||
|
<emphasis remap='I'>record_size</emphasis>
|
||
|
</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
Specifies the minimum acceptable length of the class
|
||
|
extension record required for a match, or 0.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
</variablelist>
|
||
|
|
||
|
<para>
|
||
|
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.
|
||
|
<xref linkend='XtGetClassExtension' xrefstyle='select: title'/>
|
||
|
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.
|
||
|
</para>
|
||
|
</sect2>
|
||
|
</sect1>
|
||
|
</chapter>
|