4539 lines
140 KiB
XML
4539 lines
140 KiB
XML
<chapter id='Widget_Instantiation'>
|
||
<title>Widget Instantiation</title>
|
||
<para>
|
||
A hierarchy of widget instances constitutes a widget tree.
|
||
The shell widget returned by
|
||
<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
|
||
is the root of the widget tree instance.
|
||
The widgets with one or more children are the intermediate nodes of that tree,
|
||
and the widgets with no children of any kind are the leaves of the widget tree.
|
||
With the exception of pop-up children (see <xref linkend='Pop_Up_Widgets' />),
|
||
this widget tree instance defines the associated X Window tree.
|
||
</para>
|
||
|
||
<para>
|
||
Widgets can be either composite or primitive.
|
||
Both kinds of widgets can contain children,
|
||
but the Intrinsics provide a set of management mechanisms for constructing
|
||
and interfacing between composite widgets, their children, and
|
||
other clients.
|
||
</para>
|
||
|
||
<para>
|
||
Composite widgets, that is, members of the class
|
||
<function>compositeWidgetClass</function>,
|
||
are containers for an arbitrary,
|
||
but widget implementation-defined, collection of children,
|
||
which may be instantiated by the composite widget itself,
|
||
by other clients, or by a combination of the two.
|
||
Composite widgets also contain methods for managing the geometry (layout)
|
||
of any child widget.
|
||
Under unusual circumstances,
|
||
a composite widget may have zero children,
|
||
but it usually has at least one.
|
||
By contrast,
|
||
primitive widgets that contain children typically instantiate
|
||
specific children of known classes themselves and do not expect external
|
||
clients to do so.
|
||
Primitive widgets also do not have general geometry management methods.
|
||
</para>
|
||
|
||
<para>
|
||
In addition,
|
||
the Intrinsics recursively perform many operations
|
||
(for example, realization and destruction)
|
||
on composite widgets and all their children.
|
||
Primitive widgets that have children must be prepared
|
||
to perform the recursive operations themselves on behalf of their children.
|
||
</para>
|
||
|
||
<para>
|
||
A widget tree is manipulated by several Intrinsics functions.
|
||
For example,
|
||
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
|
||
traverses the tree downward and recursively realizes all
|
||
pop-up widgets and children of composite widgets.
|
||
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
|
||
traverses the tree downward and destroys all pop-up widgets
|
||
and children of composite widgets.
|
||
The functions that fetch and modify resources traverse the tree upward
|
||
and determine the inheritance of resources from a widget's ancestors.
|
||
<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
|
||
traverses the tree up one level and calls the geometry manager
|
||
that is responsible for a widget child's geometry.
|
||
</para>
|
||
|
||
<para>
|
||
To facilitate upward traversal of the widget tree,
|
||
each widget has a pointer to its parent widget.
|
||
The
|
||
Shell
|
||
widget that
|
||
<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
|
||
returns has a <emphasis remap='I'>parent</emphasis> pointer of NULL.
|
||
</para>
|
||
|
||
<para>
|
||
To facilitate downward traversal of the widget tree,
|
||
the <emphasis remap='I'>children</emphasis> field of
|
||
each composite widget is a pointer to an array of child widgets,
|
||
which includes all normal children created,
|
||
not just the subset of children that are managed by the composite widget's
|
||
geometry manager.
|
||
Primitive widgets
|
||
that instantiate children are entirely responsible for all operations
|
||
that require downward traversal below themselves.
|
||
In addition,
|
||
every widget has a pointer to an array of pop-up children.
|
||
</para>
|
||
|
||
<sect1 id="Initializing_the_tk">
|
||
<title>Initializing the X Toolkit</title>
|
||
<para>
|
||
Before an application can call any Intrinsics function
|
||
other than
|
||
<function>XtSetLanguageProc</function>
|
||
and
|
||
<xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/>,
|
||
it must initialize the Intrinsics by using
|
||
</para>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>,
|
||
which initializes the Intrinsics internals
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>,
|
||
which initializes the per-application state
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
|
||
or
|
||
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>,
|
||
which initializes the per-display state
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>,
|
||
which creates the root of a widget tree
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
Or an application can call the convenience procedure
|
||
<xref linkend='XtOpenApplication' xrefstyle='select: title'/>,
|
||
which combines the functions of the preceding procedures.
|
||
An application wishing to use the ANSI C locale mechanism should call
|
||
<function>XtSetLanguageProc</function>
|
||
prior to calling
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>,
|
||
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>,
|
||
<xref linkend='XtOpenApplication' xrefstyle='select: title'/>,
|
||
or
|
||
<xref linkend='XtAppInitialize' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<para>
|
||
Multiple instances of X Toolkit applications may be implemented
|
||
in a single address space.
|
||
Each instance needs to be able to read
|
||
input and dispatch events independently of any other instance.
|
||
Further, an application instance may need multiple display connections
|
||
to have widgets on multiple displays.
|
||
From the application's point of view, multiple display connections
|
||
usually are treated together as a single unit
|
||
for purposes of event dispatching.
|
||
To accommodate both requirements,
|
||
the Intrinsics define application contexts,
|
||
each of which provides the information needed to distinguish one application
|
||
instance from another.
|
||
The major component of an application context is a list of one or more X
|
||
<function>Display</function>
|
||
pointers for that application.
|
||
The Intrinsics handle all display connections within a single application
|
||
context simultaneously, handling input in a round-robin fashion.
|
||
The application context type
|
||
<function>XtAppContext</function>
|
||
is opaque to clients.
|
||
</para>
|
||
|
||
<para>
|
||
To initialize the Intrinsics internals, use
|
||
<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtToolkitInitialize'>
|
||
<funcprototype>
|
||
<funcdef>void <function>XtToolkitInitialize</function></funcdef>
|
||
<paramdef> <parameter></parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<para>
|
||
If
|
||
<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>
|
||
was previously called, it returns immediately.
|
||
When
|
||
<xref linkend='XtToolkitThreadInitialize' xrefstyle='select: title'/>
|
||
is called before
|
||
<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>,
|
||
the latter is protected against
|
||
simultaneous activation by multiple threads.
|
||
</para>
|
||
|
||
<para>
|
||
To create an application context, use
|
||
<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtCreateApplicationContext'>
|
||
<funcprototype>
|
||
<funcdef>XtAppContext <function>XtCreateApplicationContext</function></funcdef>
|
||
<paramdef> <parameter></parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>
|
||
function returns an application context,
|
||
which is an opaque type.
|
||
Every application must have at least one application context.
|
||
</para>
|
||
|
||
<para>
|
||
To destroy an application context and close any
|
||
remaining display connections in it, use
|
||
<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtDestroyApplicationContext'>
|
||
<funcprototype>
|
||
<funcdef>void <function>XtDestroyApplicationContext</function></funcdef>
|
||
<paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>app_context</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the application context.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>
|
||
function destroys the specified application context.
|
||
If called from within an event dispatch (for example, in a callback procedure),
|
||
<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>
|
||
does not destroy the application context until the dispatch is complete.
|
||
</para>
|
||
|
||
<para>
|
||
To get the application context in which a given widget was created, use
|
||
<xref linkend='XtWidgetToApplicationContext' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtWidgetToApplicationContext'>
|
||
<funcprototype>
|
||
<funcdef>XtAppContext <function>XtWidgetToApplicationContext</function></funcdef>
|
||
<paramdef>Widget <parameter>w</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>w</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the widget for which you want the application context. Must be of class Object or any subclass thereof.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtWidgetToApplicationContext' xrefstyle='select: title'/>
|
||
function returns the application context for the specified widget.
|
||
</para>
|
||
|
||
<para>
|
||
To initialize a display and add it to an application context, use
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtDisplayInitialize'>
|
||
<funcprototype>
|
||
<funcdef>void <function>XtDisplayInitialize</function></funcdef>
|
||
<paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
|
||
<paramdef>Display * <parameter>display</parameter></paramdef>
|
||
<paramdef>String <parameter>application_name</parameter></paramdef>
|
||
<paramdef>String <parameter>application_class</parameter></paramdef>
|
||
<paramdef>XrmOptionDescRec * <parameter>options</parameter></paramdef>
|
||
<paramdef>Cardinal <parameter>num_options</parameter></paramdef>
|
||
<paramdef>int * <parameter>argc</parameter></paramdef>
|
||
<paramdef>String * <parameter>argv</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>app_context</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the application context.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>display</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a previously opened display connection. Note that a single
|
||
display connection can be in at most one application context.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>application_name</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the name of the application instance.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>application_class</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the class name of this application,
|
||
which is usually the generic name for all instances of this application.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>options</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies how to parse the command line for any application-specific resources.
|
||
The <emphasis remap='I'>options</emphasis> argument is passed as a parameter to
|
||
<function>XrmParseCommand</function>.
|
||
For further information,
|
||
see <olink targetdoc='libX11' targetptr='Parsing_Command_Line_Options'>Parsing Command Line Options</olink> in <olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface</olink> and <xref linkend='Parsing_the_Command_Line' /> of this specification.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>num_options</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the number of entries in the options list.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>argc</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a pointer to the number of command line parameters.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>argv</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the list of command line parameters.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
|
||
function retrieves the language string to be
|
||
used for the specified display (see <xref linkend='Finding_File_Names' />),
|
||
calls the language procedure (if set) with that language string,
|
||
builds the resource database for the default screen, calls the Xlib
|
||
<function>XrmParseCommand</function>
|
||
function to parse the command line,
|
||
and performs other per-display initialization.
|
||
After
|
||
<function>XrmParseCommand</function>
|
||
has been called,
|
||
<emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis> contain only those parameters that
|
||
were not in the standard option table or in the table specified by the
|
||
<emphasis remap='I'>options</emphasis> argument.
|
||
If the modified <emphasis remap='I'>argc</emphasis> is not zero,
|
||
most applications simply print out the modified <emphasis remap='I'>argv</emphasis> along with a message
|
||
listing the allowable options.
|
||
On POSIX-based systems,
|
||
the application name is usually the final component of <emphasis remap='I'>argv</emphasis>[0].
|
||
If the synchronous resource is
|
||
<function>True</function>,
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
|
||
calls the Xlib
|
||
<function>XSynchronize</function>
|
||
function to put Xlib into synchronous mode for this display connection
|
||
and any others currently open in the application context.
|
||
See <xref linkend='Loading_the_Resource_Database' />
|
||
and <xref linkend='Parsing_the_Command_Line' />
|
||
for details on the <emphasis remap='I'>application_name</emphasis>,
|
||
<emphasis remap='I'>application_class</emphasis>, <emphasis remap='I'>options</emphasis>, and <emphasis remap='I'>num_options</emphasis> arguments.
|
||
</para>
|
||
|
||
<para>
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
|
||
calls
|
||
<function>XrmSetDatabase</function>
|
||
to associate the resource database of the default screen with the
|
||
display before returning.
|
||
</para>
|
||
|
||
<para>
|
||
To open a display, initialize it, and then
|
||
add it to an application context, use
|
||
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtOpenDisplay'>
|
||
<funcprototype>
|
||
<funcdef>Display <function>*XtOpenDisplay</function></funcdef>
|
||
<paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
|
||
<paramdef>String <parameter>display_string</parameter></paramdef>
|
||
<paramdef>String <parameter>application_name</parameter></paramdef>
|
||
<paramdef>String <parameter>application_class</parameter></paramdef>
|
||
<paramdef>XrmOptionDescRec * <parameter>options</parameter></paramdef>
|
||
<paramdef>Cardinal <parameter>num_options</parameter></paramdef>
|
||
<paramdef>int * <parameter>argc</parameter></paramdef>
|
||
<paramdef>String * <parameter>argv</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
|
||
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>app_context</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the application context.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>display_string</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the display string, or NULL.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>application_name</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the name of the application instance, or NULL.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>application_class</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the class name of this application,
|
||
which is usually the generic name for all instances of this application.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>options</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies how to parse the command line for any application-specific resources.
|
||
The options argument is passed as a parameter to
|
||
<function>XrmParseCommand</function>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>num_options</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the number of entries in the options list.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>argc</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a pointer to the number of command line parameters.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>argv</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the list of command line parameters.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
|
||
function calls
|
||
<function>XOpenDisplay</function>
|
||
with the specified <emphasis remap='I'>display_string</emphasis>.
|
||
If <emphasis remap='I'>display_string</emphasis> is NULL,
|
||
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
|
||
uses the current value of the \-display option specified in <emphasis remap='I'>argv</emphasis>.
|
||
If no display is specified in <emphasis remap='I'>argv</emphasis>,
|
||
the user's default display is retrieved from the environment.
|
||
On POSIX-based systems,
|
||
this is the value of the
|
||
<emphasis role='strong'>DISPLAY</emphasis>
|
||
environment variable.
|
||
</para>
|
||
|
||
<para>
|
||
If this succeeds,
|
||
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
|
||
then calls
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
|
||
and passes it the opened display and
|
||
the value of the \-name option specified in <emphasis remap='I'>argv</emphasis> as the application name.
|
||
If no \-name option is specified
|
||
and <emphasis remap='I'>application_name</emphasis> is
|
||
non-NULL, <emphasis remap='I'>application_name</emphasis> is passed to
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
|
||
If <emphasis remap='I'>application_name</emphasis> is NULL and if the environment variable
|
||
<emphasis role='strong'>RESOURCE_NAME</emphasis>
|
||
is set, the value of
|
||
<emphasis role='strong'>RESOURCE_NAME</emphasis>
|
||
is used. Otherwise, the application
|
||
name is the name used to invoke the program. On implementations that
|
||
conform to ANSI C Hosted Environment support, the application name will
|
||
be <emphasis remap='I'>argv</emphasis>[0] less any directory and file type components, that is, the
|
||
final component of <emphasis remap='I'>argv</emphasis>[0], if specified. If <emphasis remap='I'>argv</emphasis>[0] does not exist or
|
||
is the empty string, the application name is ``main''.
|
||
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
|
||
returns the newly opened display or NULL if it failed.
|
||
</para>
|
||
|
||
<para>
|
||
See <xref linkend='Using_the_Intrinsics_in_a_Multi_Threaded_Environment' />
|
||
for information regarding the use of
|
||
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
|
||
in multiple threads.
|
||
</para>
|
||
|
||
<para>
|
||
To close a display and remove it from an application context, use
|
||
<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtCloseDisplay'>
|
||
<funcprototype>
|
||
<funcdef>void <function>XtCloseDisplay</function></funcdef>
|
||
<paramdef>Display * <parameter>display</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>display</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the display.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
|
||
function calls
|
||
<function>XCloseDisplay</function>
|
||
with the specified <emphasis remap='I'>display</emphasis> as soon as it is safe to do so.
|
||
If called from within an event dispatch (for example, a callback procedure),
|
||
<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
|
||
does not close the display until the dispatch is complete.
|
||
Note that applications need only call
|
||
<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
|
||
if they are to continue executing after closing the display;
|
||
otherwise, they should call
|
||
<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<para>
|
||
See <xref linkend='Using_the_Intrinsics_in_a_Multi_Threaded_Environment' />
|
||
for information regarding the use of
|
||
<xref linkend='XtCloseDisplay' xrefstyle='select: title'/>
|
||
in multiple threads.
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="Establishing_the_Locale">
|
||
<title>Establishing the Locale</title>
|
||
<para>
|
||
Resource databases are specified to be created in the current process
|
||
locale. During display initialization prior to creating the
|
||
per-screen resource database, the Intrinsics will call out to a specified
|
||
application procedure to set the locale according to options found on
|
||
the command line or in the per-display resource specifications.
|
||
</para>
|
||
|
||
<para>
|
||
The callout procedure provided by the application is of type
|
||
<function>XtLanguageProc</function>.
|
||
</para>
|
||
|
||
<funcsynopsis>
|
||
<funcprototype>
|
||
<funcdef>typedef String <function>(*XtLanguageProc)</function></funcdef>
|
||
<paramdef>Display <parameter>display</parameter></paramdef>
|
||
<paramdef>String <parameter>language</parameter></paramdef>
|
||
<paramdef>XtPointer <parameter>client_data</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>display</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Passes the display.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>language</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Passes the initial language value obtained from the command line
|
||
or server per-display resource specifications.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>client_data</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Passes the additional client data specified in the call to
|
||
<function>XtSetLanguageProc</function>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
<para>
|
||
The language procedure allows an application to set the locale to
|
||
the value of the language resource determined by
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
|
||
The function returns a new language string that
|
||
will be subsequently used by
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
|
||
to establish the path for loading resource files. The returned
|
||
string will be copied by the Intrinsics into new memory.
|
||
</para>
|
||
|
||
<para>
|
||
Initially, no language procedure is set by the Intrinsics.
|
||
To set the language procedure for use by
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>,
|
||
use
|
||
<function>XtSetLanguageProc</function>.
|
||
</para>
|
||
|
||
<funcsynopsis>
|
||
<funcprototype>
|
||
<funcdef>XtLanguageProc <function>XtSetLanguageProc</function></funcdef>
|
||
<paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
|
||
<paramdef>XtLanguageProc <parameter>proc</parameter></paramdef>
|
||
<paramdef>XtPointer <parameter>client_data</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>app_context</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the application context in which the language procedure is
|
||
to be used, or NULL.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>proc</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the language procedure.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>client_data</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies additional client data to be passed to the language
|
||
procedure when it is called.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<function>XtSetLanguageProc</function>
|
||
sets the language procedure that will be called from
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
|
||
for all subsequent Displays initialized in the specified application
|
||
context. If <emphasis remap='I'>app_context</emphasis> is NULL, the specified language
|
||
procedure is registered in all application contexts created by the
|
||
calling process, including any future application contexts that may
|
||
be created. If <emphasis remap='I'>proc</emphasis> is NULL, a default language procedure is
|
||
registered.
|
||
<function>XtSetLanguageProc</function>
|
||
returns the previously registered language procedure.
|
||
If a language procedure has not yet been registered, the return value
|
||
is unspecified, but if this return value is used in a subsequent call to
|
||
<function>XtSetLanguageProc</function>,
|
||
it will cause the default language procedure to be registered.
|
||
</para>
|
||
|
||
<para>
|
||
The default language procedure does the following:
|
||
</para>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
Sets the locale according to the environment. On ANSI C-based
|
||
systems this is done by calling
|
||
<function>setlocale</function>(
|
||
<function>LC_ALL</function>,
|
||
<emphasis remap='I'>language</emphasis> ).
|
||
If an error is encountered, a warning message is issued with
|
||
<xref linkend='XtWarning' xrefstyle='select: title'/>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Calls
|
||
<function>XSupportsLocale</function>
|
||
to verify that the current locale is supported.
|
||
If the locale is not supported, a warning message is issued with
|
||
<xref linkend='XtWarning' xrefstyle='select: title'/>
|
||
and the locale is set to ``C''.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Calls
|
||
<function>XSetLocaleModifiers</function>
|
||
specifying the empty string.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Returns the value of the current locale. On ANSI C-based systems this
|
||
is the return value from a final call to
|
||
<function>setlocale</function>(
|
||
<function>LC_ALL</function>,
|
||
NULL ).
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
A client wishing to use this mechanism to establish locale can do so
|
||
by calling
|
||
<function>XtSetLanguageProc</function>
|
||
prior to
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>,
|
||
as in the following example.
|
||
</para>
|
||
<literallayout>
|
||
Widget top;
|
||
XtSetLanguageProc(NULL, NULL, NULL);
|
||
top = XtOpenApplication(...);
|
||
...
|
||
</literallayout>
|
||
</sect1>
|
||
|
||
<sect1 id="Loading_the_Resource_Database">
|
||
<title>Loading the Resource Database</title>
|
||
<para>
|
||
The
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
|
||
function first determines the language
|
||
string to be used for the specified display. It then
|
||
creates a resource database for the default screen of the display by
|
||
combining the following sources in order, with the entries in the
|
||
first named source having highest precedence:
|
||
</para>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
Application command line (<emphasis remap='I'>argc</emphasis>, <emphasis remap='I'>argv</emphasis>).
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Per-host user environment resource file on the local host.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Per-screen resource specifications from the server.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Per-display resource specifications from the server or from
|
||
the user preference file on the local host.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Application-specific user resource file on the local host.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Application-specific class resource file on the local host.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
When the resource database for a particular screen on the display
|
||
is needed (either internally, or when
|
||
<xref linkend='XtScreenDatabase' xrefstyle='select: title'/>
|
||
is called),
|
||
it is created in the following manner using the sources listed
|
||
above in the same order:
|
||
</para>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
A temporary database, the ``server resource database'', is
|
||
created from the string returned by
|
||
<function>XResourceManagerString</function>
|
||
or, if
|
||
<function>XResourceManagerString</function>
|
||
returns NULL, the contents of a resource file in the user's home
|
||
directory. On POSIX-based systems, the usual name for this user
|
||
preference resource file is $HOME/<function>.Xdefaults</function>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
If a language procedure has been set,
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
|
||
first searches the command line for the option ``-xnlLanguage'', or
|
||
for a -xrm option that specifies the xnlLanguage/XnlLanguage resource,
|
||
as specified by Section 2.4.
|
||
If such a resource is found, the value is assumed to be
|
||
entirely in XPCS, the X Portable Character Set. If neither option is
|
||
specified on the command line,
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
|
||
queries the server resource database (which is assumed to be entirely
|
||
in XPCS) for the resource
|
||
<emphasis remap='I'>name</emphasis><function>.xnlLanguage</function>, class <emphasis remap='I'>Class</emphasis><function>.XnlLanguage</function>
|
||
where <emphasis remap='I'>name</emphasis>
|
||
and <emphasis remap='I'>Class</emphasis> are the <emphasis remap='I'>application_name</emphasis> and
|
||
<emphasis remap='I'>application_class</emphasis> specified to
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
|
||
The language procedure is then invoked with
|
||
the resource value if found, else the empty string. The
|
||
string returned from the language procedure is saved for all future
|
||
references in the Intrinsics that require the per-display language string.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The screen resource database is initialized by parsing the command
|
||
line in the manner specified by Section 2.4.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
If a language procedure has not been set,
|
||
the initial database is then queried for the resource
|
||
<emphasis remap='I'>name</emphasis><function>.xnlLanguage</function>, class <emphasis remap='I'>Class</emphasis><function>.XnlLanguage</function>
|
||
as specified above.
|
||
If this database query fails, the server resource database is
|
||
queried; if this query also fails, the language is determined from
|
||
the environment; on POSIX-based systems, this is done by retrieving the
|
||
value of the
|
||
<emphasis role='strong'>LANG</emphasis>
|
||
environment variable. If no language string is
|
||
found, the empty string is used.
|
||
This language string is saved for all future references in the Intrinsics
|
||
that require the per-display language string.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
After determining the language string, the user's environment resource
|
||
file is then merged into the initial resource database if the file exists.
|
||
This file is user-, host-, and process-specific and is expected to
|
||
contain user preferences that are to override those specifications in
|
||
the per-display and per-screen resources.
|
||
On POSIX-based systems, the user's environment resource file name is
|
||
specified by the value of the
|
||
<emphasis role='strong'>XENVIRONMENT</emphasis>
|
||
environment variable.
|
||
If this environment variable does not exist, the user's home directory
|
||
is searched for a file named
|
||
<function>.Xdefaults-</function><emphasis>host</emphasis>,
|
||
where <emphasis remap='I'>host</emphasis> is the host name of the machine on which the
|
||
application is running.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The per-screen resource specifications are then merged into the screen
|
||
resource database, if they exist. These specifications are the string
|
||
returned by
|
||
<function>XScreenResourceString</function>
|
||
for the respective screen and are owned entirely by the user.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Next, the server resource database created earlier is merged into the
|
||
screen resource database. The server property, and corresponding user
|
||
preference file, are owned and constructed entirely by the user.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The application-specific user resource file from the local host is
|
||
then merged into the screen resource database.
|
||
This file contains user customizations and is stored
|
||
in a directory owned by the user.
|
||
Either the user or the application or both can store resource specifications
|
||
in the file. Each should be prepared to find and respect entries made
|
||
by the other.
|
||
The file name is found by calling
|
||
<function>XrmSetDatabase</function>
|
||
with the current screen resource database, after preserving the
|
||
original display-associated database, then calling
|
||
<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
|
||
with the parameters
|
||
(<emphasis remap='I'>display</emphasis>, NULL, NULL, NULL, <emphasis remap='I'>path</emphasis>, NULL, 0, NULL),
|
||
where <emphasis remap='I'>path</emphasis> is defined in an operating-system-specific way.
|
||
On POSIX-based systems, <emphasis remap='I'>path</emphasis> is defined to be the value
|
||
of the environment variable
|
||
<emphasis role='strong'>XUSERFILESEARCHPATH</emphasis>
|
||
if this is defined. If
|
||
<emphasis role='strong'>XUSERFILESEARCHPATH</emphasis>
|
||
is not defined, an implementation-dependent default value is used.
|
||
This default value is constrained in the following manner:
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
If the environment variable
|
||
<emphasis role='strong'>XAPPLRESDIR</emphasis>
|
||
is not defined, the default
|
||
<emphasis role='strong'>XUSERFILESEARCHPATH</emphasis>
|
||
must contain at least six entries. These entries must contain
|
||
$HOME as the directory prefix, plus the following substitutions:
|
||
</para>
|
||
<literallayout>
|
||
1. %C, %N, %L or %C, %N, %l, %t, %c
|
||
2. %C, %N, %l
|
||
3. %C, %N
|
||
4. %N, %L or %N, %l, %t, %c
|
||
5. %N, %l
|
||
6. %N
|
||
</literallayout>
|
||
<para>
|
||
The order of these six entries within the path must be as given above.
|
||
The order and use of substitutions within a given entry are
|
||
implementation-dependent.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para> If
|
||
<emphasis role='strong'>XAPPLRESDIR</emphasis>
|
||
is defined, the default
|
||
<emphasis role='strong'>XUSERFILESEARCHPATH</emphasis>
|
||
must contain at least seven entries. These entries must contain the
|
||
following directory prefixes and substitutions:
|
||
</para>
|
||
<literallayout>
|
||
1. $XAPPLRESDIR with %C, %N, %L or %C, %N, %l, %t, %c
|
||
2. $XAPPLRESDIR with %C, %N, %l
|
||
3. $XAPPLRESDIR with %C, %N
|
||
4. $XAPPLRESDIR with %N, %L or %N, %l, %t, %c
|
||
5. $XAPPLRESDIR with %N, %l
|
||
6. $XAPPLRESDIR with %N
|
||
7. $HOME with %N
|
||
</literallayout>
|
||
<para>
|
||
The order of these seven entries within the path must be as given above.
|
||
The order and use of substitutions within a given entry are
|
||
implementation-dependent.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Last, the application-specific class resource file from the local
|
||
host is merged into the screen resource database.
|
||
This file is owned by the application and is usually installed in
|
||
a system directory when the application is installed.
|
||
It may contain sitewide customizations specified by the system manager.
|
||
The name of the application class resource file is found by calling
|
||
<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
|
||
with the parameters
|
||
(<emphasis remap='I'>display</emphasis>, ``app-defaults'', NULL, NULL, NULL, NULL, 0, NULL).
|
||
This file is expected to be provided by the developer of the application
|
||
and may be required for the application to function properly.
|
||
A simple application that wants to be assured of having a minimal
|
||
set of resources in the absence of its class resource file can declare
|
||
fallback resource specifications with
|
||
<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>.
|
||
Note that the customization substitution string is retrieved
|
||
dynamically by
|
||
<xref linkend='XtResolvePathname' xrefstyle='select: title'/>
|
||
so that the resolved file name of the application class resource file
|
||
can be affected by any of the earlier sources for the screen resource
|
||
database, even though the contents of the class resource file have
|
||
lowest precedence. After calling
|
||
<xref linkend='XtResolvePathname' xrefstyle='select: title'/>,
|
||
the original display-associated database is restored.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
To obtain the resource database for a particular screen, use
|
||
<xref linkend='XtScreenDatabase' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtScreenDatabase'>
|
||
<funcprototype>
|
||
<funcdef>XrmDatabase <function>XtScreenDatabase</function></funcdef>
|
||
<paramdef>Screen * <parameter>screen</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>screen</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the screen whose resource database is to be returned.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtScreenDatabase' xrefstyle='select: title'/>
|
||
function returns the fully merged resource database as specified above,
|
||
associated with the specified screen. If the specified <emphasis remap='I'>screen</emphasis>
|
||
does not belong to a
|
||
<function>Display</function>
|
||
initialized by
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>,
|
||
the results are undefined.
|
||
</para>
|
||
|
||
<para>
|
||
To obtain the default resource database associated with a particular display, use
|
||
<xref linkend='XtDatabase' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
|
||
<funcsynopsis id='XtDatabase'>
|
||
<funcprototype>
|
||
<funcdef>XrmDatabase <function>XtDatabase</function></funcdef>
|
||
<paramdef>Display * <parameter>display</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>display</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the display.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtDatabase' xrefstyle='select: title'/>
|
||
function is equivalent to
|
||
<function>XrmGetDatabase</function>.
|
||
It returns the database associated with the specified display, or
|
||
NULL if a database has not been set.
|
||
</para>
|
||
|
||
<para>
|
||
To specify a default set of resource values that will be used to
|
||
initialize the resource database if no application-specific class
|
||
resource file is found (the last of the six sources listed above),
|
||
use
|
||
<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtAppSetFallbackResources'>
|
||
<funcprototype>
|
||
<funcdef>void <function>XtAppSetFallbackResources</function></funcdef>
|
||
<paramdef>XtAppContext * <parameter>app_context</parameter></paramdef>
|
||
<paramdef>String * <parameter>specification_list</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>app_context</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the application context in which
|
||
the fallback specifications will be used.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>specification_list</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a NULL-terminated list of
|
||
resource specifications to preload
|
||
the database, or NULL.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
Each entry in <emphasis remap='I'>specification_list</emphasis> points to a string in the format of
|
||
<function>XrmPutLineResource</function>.
|
||
Following a call to
|
||
<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>,
|
||
when a resource database is being created for a particular screen and
|
||
the Intrinsics are not able
|
||
to find or read an application-specific class resource file according to the
|
||
rules given above and if <emphasis remap='I'>specification_list</emphasis> is not NULL, the
|
||
resource specifications in <emphasis remap='I'>specification_list</emphasis> will be merged
|
||
into the screen resource database in place of the application-specific
|
||
class resource file.
|
||
<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>
|
||
is not
|
||
required to copy <emphasis remap='I'>specification_list</emphasis>; the caller must ensure that the
|
||
contents of the list and of the strings addressed by the list remain
|
||
valid until all displays are initialized or until
|
||
<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>
|
||
is called again. The value NULL for
|
||
<emphasis remap='I'>specification_list</emphasis> removes any previous fallback resource specification
|
||
for the application context. The intended use for fallback resources
|
||
is to provide a minimal
|
||
number of resources that will make the application usable (or at
|
||
least terminate with helpful diagnostic messages) when some problem
|
||
exists in finding and loading the application defaults file.
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="Parsing_the_Command_Line">
|
||
<title>Parsing the Command Line</title>
|
||
<para>
|
||
The
|
||
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
|
||
function first parses the command line for the following options:
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>-display</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the display name for
|
||
<function>XOpenDisplay</function>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>-name</term>
|
||
<listitem>
|
||
<para>
|
||
Sets the resource name prefix,
|
||
which overrides the application name passed to
|
||
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>-xnllanguage</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the initial language string for establishing locale
|
||
and for finding application class resource files.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
|
||
<para>
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
|
||
has a table of standard command line options that are passed to
|
||
<function>XrmParseCommand</function>
|
||
for adding resources to the resource database,
|
||
and it takes as a parameter additional
|
||
application-specific resource abbreviations.
|
||
The format of this table is described in Section 15.9 in <emphasis remap='I'>Xlib — C Language X Interface</emphasis>.
|
||
</para>
|
||
<literallayout>
|
||
typedef enum {
|
||
XrmoptionNoArg, /* Value is specified in OptionDescRec.value */
|
||
XrmoptionIsArg, /* Value is the option string itself */
|
||
XrmoptionStickyArg, /* Value is characters immediately following option */
|
||
XrmoptionSepArg, /* Value is next argument in argv */
|
||
XrmoptionResArg, /* Use the next argument as input to XrmPutLineResource*/
|
||
XrmoptionSkipArg, /* Ignore this option and the next argument in argv */
|
||
XrmoptionSkipNArgs, /* Ignore this option and the next */
|
||
/* OptionDescRec.value arguments in argv */
|
||
XrmoptionSkipLine /* Ignore this option and the rest of argv */
|
||
} XrmOptionKind;
|
||
typedef struct {
|
||
char *option; /* Option name in argv */
|
||
char *specifier; /* Resource name (without application name) */
|
||
XrmOptionKind argKind; /* Location of the resource value */
|
||
XPointer value; /* Value to provide if XrmoptionNoArg */
|
||
} XrmOptionDescRec, *XrmOptionDescList;
|
||
</literallayout>
|
||
<para>The standard table contains the following entries:</para>
|
||
|
||
<informaltable frame='topbot'>
|
||
<?dbfo keep-together="always" ?>
|
||
<tgroup cols='4' align='left' colsep='0' rowsep='0'>
|
||
<colspec colwidth='1.0*' colname='c1'/>
|
||
<colspec colwidth='1.0*' colname='c2'/>
|
||
<colspec colwidth='1.0*' colname='c3'/>
|
||
<colspec colwidth='1.0*' colname='c4'/>
|
||
<thead>
|
||
<row rowsep='1'>
|
||
<entry>Option String</entry>
|
||
<entry>Resource Name</entry>
|
||
<entry>Argument Kind</entry>
|
||
<entry>Resource Value</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry>−background</entry>
|
||
<entry>*background</entry>
|
||
<entry>SepArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−bd</entry>
|
||
<entry>*borderColor</entry>
|
||
<entry>SepArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−bg</entry>
|
||
<entry>*background</entry>
|
||
<entry>SepArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−borderwidth</entry>
|
||
<entry>.borderWidth</entry>
|
||
<entry>SepArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−bordercolor</entry>
|
||
<entry>*borderColor</entry>
|
||
<entry>SepArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−bw</entry>
|
||
<entry>.borderWidth</entry>
|
||
<entry>SepArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−display</entry>
|
||
<entry>.display</entry>
|
||
<entry>SepArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−fg</entry>
|
||
<entry>*foreground</entry>
|
||
<entry>SepArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−fn</entry>
|
||
<entry>*font</entry>
|
||
<entry>SepArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−font</entry>
|
||
<entry>*font</entry>
|
||
<entry>SepArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−foreground</entry>
|
||
<entry>*foreground</entry>
|
||
<entry>SepArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−geometry</entry>
|
||
<entry>.geometry</entry>
|
||
<entry>SepArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−iconic</entry>
|
||
<entry>.iconic</entry>
|
||
<entry>NoArg</entry>
|
||
<entry>"true"</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−name</entry>
|
||
<entry>.name</entry>
|
||
<entry>SepArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−reverse</entry>
|
||
<entry>.reverseVideo</entry>
|
||
<entry>NoArg</entry>
|
||
<entry>"on"</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−rv</entry>
|
||
<entry>.reverseVideo</entry>
|
||
<entry>NoArg</entry>
|
||
<entry>"on"</entry>
|
||
</row>
|
||
<row>
|
||
<entry>+rv</entry>
|
||
<entry>.reverseVideo</entry>
|
||
<entry>NoArg</entry>
|
||
<entry>"off"</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−selectionTimeout</entry>
|
||
<entry>.selectionTimeout</entry>
|
||
<entry>SepArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−synchronous</entry>
|
||
<entry>.synchronous</entry>
|
||
<entry>NoArg</entry>
|
||
<entry>"on"</entry>
|
||
</row>
|
||
<row>
|
||
<entry>+synchronous</entry>
|
||
<entry>.synchronous</entry>
|
||
<entry>NoArg</entry>
|
||
<entry>"off"</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−title</entry>
|
||
<entry>.title</entry>
|
||
<entry>SepArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−xnllanguage</entry>
|
||
<entry>.xnlLanguage</entry>
|
||
<entry>SepArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−xrm</entry>
|
||
<entry>next argument</entry>
|
||
<entry>ResArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
<row>
|
||
<entry>−xtsessionID</entry>
|
||
<entry>.sessionID</entry>
|
||
<entry>SepArg</entry>
|
||
<entry>next argument</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>
|
||
Note that any unique abbreviation for an option name in the standard table
|
||
or in the application table is accepted.
|
||
</para>
|
||
|
||
<para>
|
||
If reverseVideo is
|
||
<function>True</function>,
|
||
the values of
|
||
<function>XtDefaultForeground</function>
|
||
and
|
||
<function>XtDefaultBackground</function>
|
||
are exchanged for all screens on the Display.
|
||
</para>
|
||
|
||
<para>
|
||
The value of the synchronous resource specifies whether or not
|
||
Xlib is put into synchronous mode. If a value is found in the resource
|
||
database during display initialization,
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
|
||
makes a call to
|
||
<function>XSynchronize</function>
|
||
for all display
|
||
connections currently open in the application context. Therefore,
|
||
when multiple displays are initialized in the same application
|
||
context, the most recent value specified for the synchronous resource
|
||
is used for all displays in the application context.
|
||
</para>
|
||
|
||
<para>
|
||
The value of the selectionTimeout resource applies to all displays
|
||
opened in the same application context. When multiple displays are
|
||
initialized in the same application context, the most recent value
|
||
specified is used for all displays in the application context.
|
||
</para>
|
||
|
||
<para>
|
||
The -xrm option provides a method of setting any resource in an application.
|
||
The next argument should be a quoted string identical in format to a line in
|
||
the user resource file.
|
||
For example,
|
||
to give a red background to all command buttons in an application named
|
||
<function>xmh</function>,
|
||
you can start it up as
|
||
</para>
|
||
<literallayout>
|
||
xmh -xrm 'xmh*Command.background: red'
|
||
</literallayout>
|
||
<para>
|
||
When it parses the command line,
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
|
||
merges the application option table with the standard option table
|
||
before calling the Xlib
|
||
<function>XrmParseCommand</function>
|
||
function.
|
||
An entry in the application table with the same name as an entry
|
||
in the standard table overrides the standard table entry.
|
||
If an option name is a prefix of another option name,
|
||
both names are kept in the merged table.
|
||
The Intrinsics reserve all option names
|
||
beginning with the characters ``-xt'' for future standard uses.
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="Creating_Widgets">
|
||
<title>Creating Widgets</title>
|
||
<para>
|
||
The creation of widget instances is a three-phase process:
|
||
</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>
|
||
The widgets are allocated and initialized with resources
|
||
and are optionally added to the managed subset of their parent.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
All composite widgets are notified of their managed children
|
||
in a bottom-up traversal of the widget tree.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The widgets create X windows, which then are mapped.
|
||
</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
<para>
|
||
To start the first phase,
|
||
the application calls
|
||
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
|
||
for all its widgets and adds some (usually, most or all) of its widgets
|
||
to their respective parents' managed set by calling
|
||
<xref linkend='XtManageChild' xrefstyle='select: title'/>.
|
||
To avoid an O(n<superscript>2</superscript>) creation process where each composite widget
|
||
lays itself out each time a widget is created and managed,
|
||
parent widgets are not notified of changes in their managed set
|
||
during this phase.
|
||
</para>
|
||
|
||
<para>
|
||
After all widgets have been created,
|
||
the application calls
|
||
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
|
||
with the top-level widget to execute the second and third phases.
|
||
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
|
||
first recursively traverses the widget tree in a postorder (bottom-up)
|
||
traversal and then notifies each composite widget with one
|
||
or more managed children by means of its change_managed procedure.
|
||
</para>
|
||
|
||
<para>
|
||
Notifying a parent about its managed set involves geometry layout and
|
||
possibly geometry negotiation.
|
||
A parent deals with constraints on its size imposed from above
|
||
(for example, when a user specifies the application window size)
|
||
and suggestions made from below (for example,
|
||
when a primitive child computes its preferred size).
|
||
One difference between the two can cause geometry changes to ripple
|
||
in both directions through the widget tree.
|
||
The parent may force some of its children to change size and position
|
||
and may issue geometry requests to its own parent in order to better
|
||
accommodate all its children.
|
||
You cannot predict where anything will go on the screen
|
||
until this process finishes.
|
||
</para>
|
||
|
||
<para>
|
||
Consequently, in the first and second phases,
|
||
no X windows are actually created, because it is likely
|
||
that they will get moved around after creation.
|
||
This avoids unnecessary requests to the X server.
|
||
</para>
|
||
|
||
<para>
|
||
Finally,
|
||
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
|
||
starts the third phase by making a preorder (top-down) traversal
|
||
of the widget tree, allocates an X window to each widget by means of
|
||
its realize procedure, and finally maps the widgets that are managed.
|
||
</para>
|
||
|
||
<sect2 id="Creating_and_Merging_Argument_Lists">
|
||
<title>Creating and Merging Argument Lists</title>
|
||
<para>
|
||
Many Intrinsics functions may be passed pairs of resource names and
|
||
values.
|
||
These are passed as an arglist, a pointer to an array of
|
||
<function>Arg</function>
|
||
structures, which contains
|
||
</para>
|
||
<literallayout>
|
||
typedef struct {
|
||
String name;
|
||
XtArgVal value;
|
||
} Arg, *ArgList;
|
||
</literallayout>
|
||
<para>
|
||
where
|
||
<function>XtArgVal</function>
|
||
is as defined in Section 1.5.
|
||
</para>
|
||
|
||
<para>
|
||
If the size of the resource is less than or equal to the size of an
|
||
<function>XtArgVal</function>,
|
||
the resource value is stored directly in <emphasis remap='I'>value</emphasis>;
|
||
otherwise, a pointer to it is stored in <emphasis remap='I'>value</emphasis>.
|
||
</para>
|
||
|
||
<para>
|
||
To set values in an
|
||
<function>ArgList</function>,
|
||
use
|
||
<xref linkend='XtSetArg' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtSetArg'>
|
||
<funcprototype>
|
||
<funcdef>void <function>XtSetArg</function></funcdef>
|
||
<paramdef>Arg <parameter>arg</parameter></paramdef>
|
||
<paramdef>String <parameter>name</parameter></paramdef>
|
||
<paramdef>XtArgVal <parameter>value</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>arg</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the <emphasis remap='I'>name/value</emphasis> pair to set.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>name</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the name of the resource.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>value</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the value of the resource if it will fit in an
|
||
<function>XtArgVal</function>,
|
||
else the address.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtSetArg' xrefstyle='select: title'/>
|
||
function is usually used in a highly stylized manner to
|
||
minimize the probability of making a mistake; for example:
|
||
</para>
|
||
<literallayout>
|
||
Arg args[20];
|
||
int n;
|
||
n = 0;
|
||
XtSetArg(args[n], XtNheight, 100); n++;
|
||
XtSetArg(args[n], XtNwidth, 200); n++;
|
||
XtSetValues(widget, args, n);
|
||
</literallayout>
|
||
<para>
|
||
Alternatively, an application can statically declare the argument list
|
||
and use
|
||
<xref linkend='XtNumber' xrefstyle='select: title'/>:
|
||
</para>
|
||
<literallayout>
|
||
static Args args[] = {
|
||
{XtNheight, (XtArgVal) 100},
|
||
{XtNwidth, (XtArgVal) 200},
|
||
};
|
||
XtSetValues(Widget, args, XtNumber(args));
|
||
</literallayout>
|
||
<para>
|
||
Note that you should not use expressions with side effects such as
|
||
auto-increment or auto-decrement
|
||
within the first argument to
|
||
<xref linkend='XtSetArg' xrefstyle='select: title'/>.
|
||
<xref linkend='XtSetArg' xrefstyle='select: title'/>
|
||
can be implemented as a macro that evaluates the first argument twice.
|
||
</para>
|
||
|
||
<para>
|
||
To merge two
|
||
arglist arrays, use
|
||
<xref linkend='XtMergeArgLists' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtMergeArgLists'>
|
||
<funcprototype>
|
||
<funcdef>ArgList <function>XtMergeArgLists</function></funcdef>
|
||
<paramdef>ArgList <parameter>args1</parameter></paramdef>
|
||
<paramdef>Cardinal <parameter>num_args1</parameter></paramdef>
|
||
<paramdef>ArgList <parameter>args2</parameter></paramdef>
|
||
<paramdef>Cardinal <parameter>num_args2</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>args1</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the first argument list.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>num_args1</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the number of entries in the first argument list.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>args2</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the second argument list.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>num_args2</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the number of entries in the second argument list.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtMergeArgLists' xrefstyle='select: title'/>
|
||
function allocates enough storage to hold the combined
|
||
arglist arrays and copies them into it.
|
||
Note that it does not check for duplicate entries.
|
||
The length of the returned list is the sum of the lengths of the
|
||
specified lists.
|
||
When it is no longer needed,
|
||
free the returned storage by using
|
||
<xref linkend='XtFree' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<para>
|
||
All Intrinsics interfaces that require
|
||
<function>ArgList</function>
|
||
arguments have analogs
|
||
conforming to the ANSI C variable argument list
|
||
(traditionally called ``varargs'')
|
||
calling convention. The name of the analog is formed by prefixing
|
||
``Va'' to the name of the corresponding
|
||
<function>ArgList</function>
|
||
procedure; e.g.,
|
||
<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>.
|
||
Each procedure named <function>XtVa</function><emphasis remap='I'>something</emphasis> takes as its
|
||
last arguments, in place of the corresponding
|
||
<function>ArgList</function>/
|
||
<function>Cardinal</function>
|
||
parameters, a variable parameter list of resource name and
|
||
value pairs where each name is of type
|
||
<function>String</function>
|
||
and each value is of type
|
||
<function>XtArgVal</function>.
|
||
The end of the list is identified by a <emphasis remap='I'>name</emphasis> entry
|
||
containing NULL. Developers writing in the C language wishing to pass
|
||
resource name and value pairs to any of these interfaces may use the
|
||
<function>ArgList</function>
|
||
and varargs forms interchangeably.
|
||
</para>
|
||
|
||
<para>
|
||
Two special names are defined for use only in varargs lists:
|
||
<function>XtVaTypedArg</function>
|
||
and
|
||
<function>XtVaNestedList</function>.
|
||
</para>
|
||
<literallayout>
|
||
#define XtVaTypedArg "XtVaTypedArg"
|
||
</literallayout>
|
||
<para>
|
||
If the name
|
||
<function>XtVaTypedArg</function>
|
||
is specified in place of a resource
|
||
name, then the following four arguments are interpreted as a
|
||
<emphasis remap='I'>name/type/value/size</emphasis> tuple <emphasis remap='I'>where</emphasis> name is of type
|
||
<function>String</function>,
|
||
<emphasis remap='I'>type</emphasis> is of type
|
||
<function>String</function>,
|
||
<emphasis remap='I'>value</emphasis> is of type
|
||
<function>XtArgVal</function>,
|
||
and <emphasis remap='I'>size</emphasis> is of type int. When a varargs list containing
|
||
<function>XtVaTypedArg</function>
|
||
is processed, a resource type
|
||
conversion (see <xref linkend='Resource_Conversions' />) is performed if necessary to convert the
|
||
value into the format required by the associated resource. If <emphasis remap='I'>type</emphasis> is
|
||
XtRString, then <emphasis remap='I'>value</emphasis> contains a pointer to the string and <emphasis remap='I'>size</emphasis>
|
||
contains the number of bytes allocated, including the trailing null
|
||
byte. If <emphasis remap='I'>type</emphasis> is not XtRString, then <emphasis remap='I'>if</emphasis> size is
|
||
less than or equal to
|
||
<function>sizeof</function>(<function>XtArgVal</function>), the value should be the data cast to the type
|
||
<function>XtArgVal</function>,
|
||
otherwise <emphasis remap='I'>value</emphasis> is a pointer to the data. If the type
|
||
conversion fails for any reason, a warning message is issued and the
|
||
list entry is skipped.
|
||
</para>
|
||
<literallayout>
|
||
#define XtVaNestedList "XtVaNestedList"
|
||
</literallayout>
|
||
<para>
|
||
If the name
|
||
<function>XtVaNestedList</function>
|
||
is specified in place of a resource name,
|
||
then the following argument is interpreted as an
|
||
<function>XtVarArgsList</function>
|
||
value, which specifies another
|
||
varargs list that is logically inserted into the original list at the
|
||
point of declaration. The end of the nested list is identified with a
|
||
name entry containing NULL. Varargs lists may nest to any depth.
|
||
</para>
|
||
|
||
<para>
|
||
To dynamically allocate a varargs list for use with
|
||
<function>XtVaNestedList</function>
|
||
in multiple calls, use
|
||
<xref linkend='XtVaCreateArgsList' xrefstyle='select: title'/>.
|
||
</para>
|
||
<literallayout>
|
||
typedef XtPointer XtVarArgsList;
|
||
</literallayout>
|
||
|
||
<funcsynopsis id='XtVaCreateArgsList'>
|
||
<funcprototype>
|
||
<funcdef>XtVarArgsList <function>XtVaCreateArgsList</function></funcdef>
|
||
<paramdef>XtPointer <parameter>unused</parameter></paramdef>
|
||
<paramdef> <parameter>...</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>unused</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
This argument is not currently used and must be specified as NULL.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
...
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a variable parameter list of resource
|
||
name and value pairs.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtVaCreateArgsList' xrefstyle='select: title'/>
|
||
function allocates memory and copies its arguments into a
|
||
single list pointer, which may be used with
|
||
<function>XtVaNestedList</function>.
|
||
The end of
|
||
both lists is identified by a <emphasis remap='I'>name</emphasis> entry containing NULL. Any entries
|
||
of type
|
||
<function>XtVaTypedArg</function>
|
||
are copied as specified without applying
|
||
conversions. Data passed by reference (including Strings) are not
|
||
copied, only the pointers themselves; the caller must ensure that the
|
||
data remain valid for the lifetime of the created varargs list. The
|
||
list should be freed using
|
||
<xref linkend='XtFree' xrefstyle='select: title'/>
|
||
when no longer needed.
|
||
</para>
|
||
|
||
<para>
|
||
Use of resource files and of the resource database is generally
|
||
encouraged over lengthy arglist or varargs lists whenever possible in
|
||
order to permit modification without recompilation.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="Creating_a_Widget_Instance">
|
||
<title>Creating a Widget Instance</title>
|
||
<para>
|
||
To create an instance of a widget, use
|
||
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtCreateWidget'>
|
||
<funcprototype>
|
||
<funcdef>Widget <function>XtCreateWidget</function></funcdef>
|
||
<paramdef>String <parameter>name</parameter></paramdef>
|
||
<paramdef>WidgetClass <parameter>object_class</parameter></paramdef>
|
||
<paramdef>Widget <parameter>parent</parameter></paramdef>
|
||
<paramdef>ArgList <parameter>args</parameter></paramdef>
|
||
<paramdef>Cardinal <parameter>num_args</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>name</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the resource instance name for the created widget,
|
||
which is used for retrieving resources
|
||
and, for that reason, should not be the same as any other widget
|
||
that is a child of the same parent.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>object_class</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the widget class pointer for the created object. Must be <emphasis role='strong'>objectClass</emphasis> or any subclass thereof.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>parent</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the parent widget. Must be of class Object or any subclass thereof.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>args</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the argument list to override any other resource specifications.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>num_args</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the number of entries in the argument list.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
|
||
function performs all the boilerplate operations of widget
|
||
creation, doing the following in order:
|
||
</para>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
Checks to see if the class_initialize procedure has been called for this class
|
||
and for all superclasses and, if not, calls those necessary in a
|
||
superclass-to-subclass order.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
If the specified class is not
|
||
<function>coreWidgetClass</function>
|
||
or a subclass thereof,
|
||
and the parent's class is a subclass of
|
||
<function>compositeWidgetClass</function>
|
||
and either no extension record in
|
||
the parent's composite class part extension field exists with the
|
||
<emphasis remap='I'>record_type</emphasis>
|
||
<emphasis role='strong'>NULLQUARK</emphasis>
|
||
or the <emphasis remap='I'>accepts_objects</emphasis> field in the extension
|
||
record is
|
||
<function>False</function>,
|
||
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
|
||
issues a fatal error; see <xref linkend='Addition_of_Children_to_a_Composite_Widget_The_insert_child_Procedure' /> and <xref linkend='Nonwidget_Objects' />.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
If the specified class contains an extension record in the object class
|
||
part <emphasis remap='I'>extension</emphasis> field with <emphasis remap='I'>record_type</emphasis>
|
||
<emphasis role='strong'>NULLQUARK</emphasis>
|
||
and the <emphasis remap='I'>allocate</emphasis> field is not NULL,
|
||
the procedure is invoked to allocate memory
|
||
for the widget instance. If the parent is a member of the class
|
||
<function>constraintWidgetClass</function>,
|
||
the procedure also allocates memory for the
|
||
parent's constraints and stores the address of this memory into the
|
||
<emphasis remap='I'>constraints</emphasis> field. If no allocate procedure is found, the Intrinsics
|
||
allocate memory for the widget and, when applicable, the constraints,
|
||
and initializes the <emphasis remap='I'>constraints</emphasis> field.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Initializes the Core nonresource data fields
|
||
<emphasis remap='I'>self</emphasis>, <emphasis remap='I'>parent</emphasis>, <emphasis remap='I'>widget_class</emphasis>, <emphasis remap='I'>being_destroyed</emphasis>,
|
||
<emphasis remap='I'>name</emphasis>, <emphasis remap='I'>managed</emphasis>, <emphasis remap='I'>window</emphasis>, <emphasis remap='I'>visible</emphasis>,
|
||
<emphasis remap='I'>popup_list</emphasis>, and <emphasis remap='I'>num_popups</emphasis>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Initializes the resource fields (for example, <emphasis remap='I'>background_pixel</emphasis>)
|
||
by using the
|
||
<function>CoreClassPart</function>
|
||
resource lists specified for this class and all superclasses.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
If the parent is a member of the class
|
||
<function>constraintWidgetClass</function>,
|
||
initializes the resource fields of the constraints record
|
||
by using the
|
||
<function>ConstraintClassPart</function>
|
||
resource lists specified for the parent's class
|
||
and all superclasses up to
|
||
<function>constraintWidgetClass</function>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Calls the initialize procedures for the widget starting at the
|
||
Object
|
||
initialize procedure on down to the widget's initialize procedure.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
If the parent is a member of the class
|
||
<function>constraintWidgetClass</function>,
|
||
calls the
|
||
<function>ConstraintClassPart</function>
|
||
initialize procedures,
|
||
starting at
|
||
<function>constraintWidgetClass</function>
|
||
on down to the parent's
|
||
<function>ConstraintClassPart</function>
|
||
initialize procedure.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
If the parent is a member of the class
|
||
<function>compositeWidgetClass</function>,
|
||
puts the widget into its parent's children list by calling its parent's
|
||
insert_child procedure.
|
||
For further information,
|
||
see <xref linkend='Addition_of_Children_to_a_Composite_Widget_The_insert_child_Procedure' />.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
To create an instance of a widget using varargs lists, use
|
||
<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtVaCreateWidget'>
|
||
<funcprototype>
|
||
<funcdef>Widget <function>XtVaCreateWidget</function></funcdef>
|
||
<paramdef>String <parameter>name</parameter></paramdef>
|
||
<paramdef>WidgetClass <parameter>object_class</parameter></paramdef>
|
||
<paramdef>Widget <parameter>parent</parameter></paramdef>
|
||
<paramdef> <parameter>...</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>name</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the resource name for the created widget.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>object_class</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the widget class pointer for the created object. Must be <emphasis role='strong'>objectClass</emphasis> or any subclass thereof.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>parent</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the parent widget. Must be of class Object or any subclass thereof.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
...
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the variable argument list to override any other
|
||
resource specifications.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>
|
||
procedure is identical in function to
|
||
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>
|
||
with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list,
|
||
as described
|
||
in Section 2.5.1.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="Creating_an_Application_Shell_Instance">
|
||
<title>Creating an Application Shell Instance</title>
|
||
<para>
|
||
An application can have multiple top-level widgets, each of which
|
||
specifies a unique widget tree
|
||
that can potentially be on different screens or displays.
|
||
An application uses
|
||
<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
|
||
to create independent widget trees.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtAppCreateShell'>
|
||
<funcprototype>
|
||
<funcdef>Widget <function>XtAppCreateShell</function></funcdef>
|
||
<paramdef>String <parameter>name</parameter></paramdef>
|
||
<paramdef>String <parameter>application_class</parameter></paramdef>
|
||
<paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
|
||
<paramdef>Display * <parameter>display</parameter></paramdef>
|
||
<paramdef>ArgList <parameter>args</parameter></paramdef>
|
||
<paramdef>Cardinal <parameter>num_args</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>name</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the instance name of the shell widget.
|
||
If <emphasis remap='I'>name</emphasis> is NULL,
|
||
the application name passed to
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
|
||
is used.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>application_class</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the resource class string to be used in
|
||
place of the widget <emphasis remap='I'>class_name</emphasis> string when
|
||
<emphasis remap='I'>widget_class</emphasis> is
|
||
<function>applicationShellWidgetClass</function>
|
||
or a subclass thereof.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>widget_class</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the widget class for the top-level widget (e.g.,
|
||
<function>applicationShellWidgetClass ).</function>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>display</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the display for the default screen
|
||
and for the resource database used to retrieve
|
||
the shell widget resources.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>args</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the argument list to override any other resource specifications.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>num_args</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the number of entries in the argument list.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
|
||
function
|
||
creates a new shell widget instance as the root of a widget tree.
|
||
The screen resource for this widget is determined by first scanning
|
||
<emphasis remap='I'>args</emphasis> for the XtNscreen argument. If no XtNscreen argument is
|
||
found, the resource database associated with the default screen of
|
||
the specified display is queried for the resource <emphasis remap='I'>name</emphasis>.screen,
|
||
class <emphasis remap='I'>Class</emphasis>.Screen where <emphasis remap='I'>Class</emphasis> is the specified
|
||
<emphasis remap='I'>application_class</emphasis> if <emphasis remap='I'>widget_class</emphasis> is
|
||
<function>applicationShellWidgetClass</function>
|
||
or a subclass thereof. If <emphasis remap='I'>widget_class</emphasis> is not
|
||
<function>application\%Shell\%Widget\%Class</function>
|
||
or a subclass, <emphasis remap='I'>Class</emphasis> is the <emphasis remap='I'>class_name</emphasis>
|
||
field from the
|
||
<function>CoreClassPart</function>
|
||
of the specified <emphasis remap='I'>widget_class</emphasis>.
|
||
If this query fails, the default
|
||
screen of the specified display is used. Once the screen is determined,
|
||
the resource database associated with that screen is used to retrieve
|
||
all remaining resources for the shell widget not specified in
|
||
<emphasis remap='I'>args</emphasis>. The widget name and <emphasis remap='I'>Class</emphasis> as determined above are
|
||
used as the leftmost (i.e., root) components in all fully qualified
|
||
resource names for objects within this widget tree.
|
||
</para>
|
||
|
||
<para>
|
||
If the specified widget class is a subclass of WMShell, the name and
|
||
<emphasis remap='I'>Class</emphasis> as determined above will be stored into the
|
||
<emphasis role='strong'>WM_CLASS</emphasis>
|
||
property on the widget's window when it becomes realized.
|
||
If the specified <emphasis remap='I'>widget_class</emphasis> is
|
||
<function>applicationShellWidgetClass</function>
|
||
or a subclass thereof, the
|
||
<emphasis role='strong'>WM_COMMAND</emphasis>
|
||
property will also be set from the values of the XtNargv and
|
||
XtNargc resources.
|
||
</para>
|
||
|
||
<para>
|
||
To create multiple top-level shells within a single (logical)
|
||
application,
|
||
you can use one of two methods:
|
||
</para>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
Designate one shell as the real top-level shell and
|
||
create the others as pop-up children of it by using
|
||
<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Have all shells as pop-up children of an unrealized top-level shell.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
The first method,
|
||
which is best used when there is a clear choice for what is the main window,
|
||
leads to resource specifications like the following:
|
||
</para>
|
||
<literallayout>
|
||
xmail.geometry:... (the main window)
|
||
xmail.read.geometry:... (the read window)
|
||
xmail.compose.geometry:... (the compose window)
|
||
</literallayout>
|
||
<para>
|
||
The second method,
|
||
which is best if there is no main window,
|
||
leads to resource specifications like the following:
|
||
</para>
|
||
<literallayout>
|
||
xmail.headers.geometry:... (the headers window)
|
||
xmail.read.geometry:... (the read window)
|
||
xmail.compose.geometry:... (the compose window)
|
||
</literallayout>
|
||
<para>
|
||
To create a top-level widget that is the root of a widget tree using
|
||
varargs lists, use
|
||
<xref linkend='XtVaAppCreateShell' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtVaAppCreateShell'>
|
||
<funcprototype>
|
||
<funcdef>Widget <function>XtVaAppCreateShell</function></funcdef>
|
||
<paramdef>String <parameter>name</parameter></paramdef>
|
||
<paramdef>String <parameter>application_class</parameter></paramdef>
|
||
<paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
|
||
<paramdef>Display * <parameter>display</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>name</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the instance name of the shell widget.
|
||
If <emphasis remap='I'>name</emphasis> is NULL,
|
||
the application name passed to
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
|
||
is used.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>application_class</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the resource class string to be used in
|
||
place of the widget <emphasis remap='I'>class_name</emphasis> string when
|
||
<emphasis remap='I'>widget_class</emphasis> is
|
||
<function>applicationShellWidgetClass</function>
|
||
or a subclass thereof.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>widget_class</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the widget class for the top-level widget.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>display</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the display for the default screen
|
||
and for the resource database used to retrieve
|
||
the shell widget resources.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
...
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the variable argument list to override any other
|
||
resource specifications.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtVaAppCreateShell' xrefstyle='select: title'/>
|
||
procedure is identical in function to
|
||
<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
|
||
with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as
|
||
described in Section 2.5.1.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="Convenience_Procedure_to_Initialize_an_Application">
|
||
<title>Convenience Procedure to Initialize an Application</title>
|
||
<para>
|
||
To initialize the Intrinsics internals, create an application context,
|
||
open and initialize a display, and create the initial root shell
|
||
instance, an application may use
|
||
<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
|
||
or
|
||
<xref linkend='XtVaOpenApplication' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtOpenApplication'>
|
||
<funcprototype>
|
||
<funcdef>Widget <function>XtOpenApplication</function></funcdef>
|
||
<paramdef>XtAppContext * <parameter>app_context_return</parameter></paramdef>
|
||
<paramdef>String <parameter>application_class</parameter></paramdef>
|
||
<paramdef>XrmOptionDescList <parameter>options</parameter></paramdef>
|
||
<paramdef>Cardinal <parameter>num_options</parameter></paramdef>
|
||
<paramdef>int * <parameter>argc_in_out</parameter></paramdef>
|
||
<paramdef>String * <parameter>argv_in_out</parameter></paramdef>
|
||
<paramdef>String * <parameter>fallback_resources</parameter></paramdef>
|
||
<paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
|
||
<paramdef>ArgList <parameter>args</parameter></paramdef>
|
||
<paramdef>Cardinal <parameter>num_args</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>app_context_return</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Returns the application context, if non-NULL.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>application_class</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the class name of the application.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>options</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the command line options table.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>num_options</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the number of entries in <emphasis remap='I'>options</emphasis>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>argc_in_out</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a pointer to the number of command line arguments.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>argv_in_out</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a pointer to the command line arguments.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>fallback_resources</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies resource values to be used if the application class resource
|
||
file cannot be opened or read, or NULL.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>widget_class</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the class of the widget to be created. Must be shellWidgetClass
|
||
or a subclass.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>args</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the argument list to override any
|
||
other resource specifications for the created shell widget.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>num_args</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the number of entries in the argument list.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
|
||
function calls
|
||
<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/>
|
||
followed by
|
||
<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>,
|
||
then calls
|
||
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>
|
||
with <emphasis remap='I'>display_string</emphasis> NULL and
|
||
<emphasis remap='I'>application_name</emphasis> NULL, and finally calls
|
||
<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>
|
||
with <emphasis remap='I'>name</emphasis> NULL, the specified <emphasis remap='I'>widget_class</emphasis>,
|
||
an argument list and count,
|
||
and returns the created shell.
|
||
The recommended <emphasis remap='I'>widget_class</emphasis> is
|
||
<function>sessionShellWidgetClass</function>.
|
||
The argument list and count are created by merging
|
||
the specified <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> with a list
|
||
containing the specified <emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis>.
|
||
The modified <emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis> returned by
|
||
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>
|
||
are returned in <emphasis remap='I'>argc_in_out</emphasis> and <emphasis remap='I'>argv_in_out</emphasis>. If
|
||
<emphasis remap='I'>app_context_return</emphasis> is not NULL, the created application context is
|
||
also returned. If the display specified by the command line cannot be
|
||
opened, an error message is issued and
|
||
<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
|
||
terminates the application. If <emphasis remap='I'>fallback_resources</emphasis> is non-NULL,
|
||
<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/>
|
||
is called with the value prior to calling
|
||
<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtVaOpenApplication'>
|
||
<funcprototype>
|
||
<funcdef>Widget <function>XtVaOpenApplication</function></funcdef>
|
||
<paramdef>XtAppContext * <parameter>app_context_return</parameter></paramdef>
|
||
<paramdef>String <parameter>application_class</parameter></paramdef>
|
||
<paramdef>XrmOptionDescList <parameter>options</parameter></paramdef>
|
||
<paramdef>Cardinal <parameter>num_options</parameter></paramdef>
|
||
<paramdef>int * <parameter>argc_in_out</parameter></paramdef>
|
||
<paramdef>String * <parameter>argv_in_out</parameter></paramdef>
|
||
<paramdef>String * <parameter>fallback_resources</parameter></paramdef>
|
||
<paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>app_context_return</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Returns the application context, if non-NULL.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>application_class</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the class name of the application.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>options</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the command line options table.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>num_options</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the number of entries in <emphasis remap='I'>options</emphasis>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>argc_in_out</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a pointer to the number of command line arguments.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>argv_in_out</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the command line arguments array.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>fallback_resources</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies resource values to be used if the application class
|
||
resource file cannot be opened, or NULL.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>widget_class</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the class of the widget to be created. Must be shellWidgetClass
|
||
or a subclass.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
...
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the variable argument list to override any other
|
||
resource specifications for the created shell.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtVaOpenApplication' xrefstyle='select: title'/>
|
||
procedure is identical in function to
|
||
<xref linkend='XtOpenApplication' xrefstyle='select: title'/>
|
||
with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list,
|
||
as described
|
||
in Section 2.5.1.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="Widget_Instance_Allocation_The_allocate_Procedure">
|
||
<title>Widget Instance Allocation: The allocate Procedure</title>
|
||
<para>
|
||
A widget class may optionally provide an instance allocation procedure
|
||
in the
|
||
<function>ObjectClassExtension</function>
|
||
record.
|
||
</para>
|
||
|
||
<para>
|
||
When the call to create a widget includes a varargs list containing
|
||
<function>XtVaTypedArg</function>,
|
||
these arguments will be passed to the allocation procedure in an
|
||
<function>XtTypedArgList</function>.
|
||
</para>
|
||
<literallayout>
|
||
typedef struct {
|
||
String name;
|
||
String type;
|
||
XtArgVal value;
|
||
int size;
|
||
} XtTypedArg, *XtTypedArgList;
|
||
</literallayout>
|
||
<para>
|
||
The allocate procedure pointer in the
|
||
<function>ObjectClassExtension</function>
|
||
record is of type
|
||
<xref linkend='XtAllocateProc' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtAllocateProc'>
|
||
<funcprototype>
|
||
<funcdef>typedef void <function>(*AllocateProc)</function></funcdef>
|
||
<paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
|
||
<paramdef>Cardinal* <parameter>constraint_size</parameter></paramdef>
|
||
<paramdef>Cardinal* <parameter>more_bytes</parameter></paramdef>
|
||
<paramdef>ArgList <parameter>args</parameter></paramdef>
|
||
<paramdef>Cardinal* <parameter>num_args</parameter></paramdef>
|
||
<paramdef>XtTypedArgList <parameter>typed_args</parameter></paramdef>
|
||
<paramdef>Cardinal* <parameter>num_typed_args</parameter></paramdef>
|
||
<paramdef>Widget* <parameter>new_return</parameter></paramdef>
|
||
<paramdef>XtPointer* <parameter>more_bytes_return</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>widget_class</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the widget class of the instance to allocate.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>constraint_size</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the size of the constraint record to allocate, or 0.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>more_bytes</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the number of auxiliary bytes of memory to allocate.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>args</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the argument list as given in the call to create the widget.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>num_args</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the number of arguments.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>typed_args</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the list of typed arguments given in the call to create the widget.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>num_typed_args</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the number of typed arguments.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>new_return</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Returns a pointer to the newly allocated instance, or NULL in case of error.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>more_bytes_return</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Returns the auxiliary memory if it was requested, or NULL
|
||
if requested and an error occurred; otherwise, unchanged.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
At widget allocation time, if an extension record with <emphasis remap='I'>record_type</emphasis>
|
||
equal to
|
||
<emphasis role='strong'>NULLQUARK</emphasis>
|
||
is located through the object class part <emphasis remap='I'>extension</emphasis> field
|
||
and the <emphasis remap='I'>allocate</emphasis> field is not NULL, the
|
||
<xref linkend='XtAllocateProc' xrefstyle='select: title'/>
|
||
will be invoked to allocate memory for the widget. If no ObjectClassPart
|
||
extension record is declared with <emphasis remap='I'>record_type equal</emphasis> to
|
||
<emphasis role='strong'>NULLQUARK</emphasis>,
|
||
then
|
||
<function>XtInheritAllocate</function>
|
||
and
|
||
<function>XtInheritDeallocate</function>
|
||
are assumed.
|
||
If no
|
||
<xref linkend='XtAllocateProc' xrefstyle='select: title'/>
|
||
is found, the Intrinsics will allocate memory for the widget.
|
||
</para>
|
||
|
||
<para>
|
||
An
|
||
<xref linkend='XtAllocateProc' xrefstyle='select: title'/>
|
||
must perform the following:
|
||
</para>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
Allocate memory for the widget instance and return it in <emphasis remap='I'>new_return</emphasis>.
|
||
The memory must be at least <emphasis remap='I'>wc->core_class.widget_size</emphasis> bytes in length,
|
||
double-word aligned.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Initialize the <emphasis remap='I'>core.constraints</emphasis> field in the instance record to NULL
|
||
or to point to a constraint record. If <emphasis remap='I'>constraint_size</emphasis>
|
||
is not 0, the procedure must allocate memory for the constraint record.
|
||
The memory must be double-word aligned.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
If <emphasis remap='I'>more_bytes</emphasis> is not 0, then the address of a block of memory
|
||
at least <emphasis remap='I'>more_bytes</emphasis> in size, double-word aligned, must be
|
||
returned in the <emphasis remap='I'>more_bytes_return</emphasis> parameter,
|
||
or NULL to indicate an error.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
A class allocation procedure that envelops the allocation procedure of a
|
||
superclass must rely on the enveloped procedure to perform the instance
|
||
and constraint allocation.
|
||
Allocation procedures should refrain from initializing fields in the
|
||
widget record except to store pointers to newly allocated additional memory.
|
||
Under no circumstances should an allocation procedure that envelopes
|
||
its superclass allocation procedure modify fields in the
|
||
instance part of any superclass.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="Widget_Instance_Initialization_The_initialize_Procedure">
|
||
<title>Widget Instance Initialization: The initialize Procedure</title>
|
||
<para>
|
||
The initialize procedure pointer in a widget class is of type
|
||
<xref linkend='XtInitProc' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtInitProc'>
|
||
<funcprototype>
|
||
<funcdef>typedef void <function>(*XtInitProc)</function></funcdef>
|
||
<paramdef>Widget <parameter>request</parameter></paramdef>
|
||
<paramdef>Widget <parameter>new</parameter></paramdef>
|
||
<paramdef>ArgList <parameter>args</parameter></paramdef>
|
||
<paramdef>Cardinal * <parameter>num_args</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>request</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies a copy of the widget with resource values as requested by the
|
||
argument list, the resource database, and the widget defaults.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>new</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the widget with the new values, both resource and nonresource,
|
||
that are actually allowed.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>args</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the argument list passed by the client, for
|
||
computing derived resource values.
|
||
If the client created the widget using a varargs form, any resources
|
||
specified via
|
||
<function>XtVaTypedArg</function>
|
||
are converted to the widget representation and the list is transformed
|
||
into the
|
||
<function>ArgList</function>
|
||
format.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>num_args</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the number of entries in the argument list.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
An initialization procedure performs the following:
|
||
</para>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
Allocates space for and copies any resources referenced by address
|
||
that the client is allowed to free or modify
|
||
after the widget has been created.
|
||
For example,
|
||
if a widget has a field that is a
|
||
<function>String</function>,
|
||
it may choose not to
|
||
depend on the characters at that address remaining constant
|
||
but dynamically allocate space for the string and copy it to the new space.
|
||
Widgets that do not copy one or more resources referenced
|
||
by address should clearly so state in their user documentation.
|
||
<note><para>
|
||
It is not necessary to allocate space for or to copy callback lists.
|
||
</para></note>
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Computes values for unspecified resource fields.
|
||
For example, if <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> are zero,
|
||
the widget should compute an appropriate width and height
|
||
based on its other resources.
|
||
<note><para>
|
||
A widget may directly assign only
|
||
its own <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> within the initialize, initialize_hook,
|
||
set_values, and
|
||
set_values_hook procedures; see <xref linkend='Geometry_Management' />.
|
||
</para></note>
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Computes values for uninitialized nonresource fields that are derived from
|
||
resource fields.
|
||
For example, graphics contexts (GCs) that the widget uses are derived from
|
||
resources like background, foreground, and font.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
An initialization procedure also can check certain fields for
|
||
internal consistency.
|
||
For example, it makes no sense to specify a colormap for a depth
|
||
that does not support that colormap.
|
||
</para>
|
||
|
||
<para>
|
||
Initialization procedures are called in superclass-to-subclass order
|
||
after all fields specified in the resource lists have been
|
||
initialized. The initialize procedure does not need to examine
|
||
<emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis>
|
||
if all public resources are declared in the resource list.
|
||
Most of the initialization code for a specific widget class deals with fields
|
||
defined in that class and not with fields defined in its superclasses.
|
||
</para>
|
||
|
||
<para>
|
||
If a subclass does not need an initialization procedure
|
||
because it does not need to perform any of the above operations,
|
||
it can specify NULL for the <emphasis remap='I'>initialize</emphasis> field in the class record.
|
||
</para>
|
||
|
||
<para>
|
||
Sometimes a subclass may want to overwrite values filled in by its
|
||
superclass.
|
||
In particular, size calculations of a superclass often are
|
||
incorrect for a subclass, and in this case,
|
||
the subclass must modify or recalculate fields declared
|
||
and computed by its superclass.
|
||
</para>
|
||
|
||
<para>
|
||
As an example,
|
||
a subclass can visually surround its superclass display.
|
||
In this case, the width and height calculated by the superclass initialize
|
||
procedure are too small and need to be incremented by the size of the surround.
|
||
The subclass needs to know if its superclass's size was calculated by the
|
||
superclass or was specified explicitly.
|
||
All widgets must place themselves into whatever size is explicitly given,
|
||
but they should compute a reasonable size if no size is requested.
|
||
</para>
|
||
|
||
<para>
|
||
The <emphasis remap='I'>request</emphasis> and <emphasis remap='I'>new</emphasis> arguments provide the necessary information for
|
||
a subclass to determine the difference between an explicitly specified field
|
||
and a field computed by a superclass.
|
||
The <emphasis remap='I'>request</emphasis> widget is a copy of the widget as initialized by the
|
||
arglist and resource database.
|
||
The <emphasis remap='I'>new</emphasis> widget starts with the values in the request,
|
||
but it has been updated by all superclass initialization procedures called
|
||
so far.
|
||
A subclass initialize procedure can compare these two to resolve
|
||
any potential conflicts.
|
||
</para>
|
||
|
||
<para>
|
||
In the above example,
|
||
the subclass with the visual surround can see
|
||
if the <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> in the <emphasis remap='I'>request</emphasis> widget are zero.
|
||
If so,
|
||
it adds its surround size to the <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis>
|
||
fields in the <emphasis remap='I'>new</emphasis> widget.
|
||
If not, it must make do with the size originally specified.
|
||
</para>
|
||
|
||
<para>
|
||
The <emphasis remap='I'>new</emphasis> widget will become the actual widget instance record.
|
||
Therefore,
|
||
the initialization procedure should do all its work on the <emphasis remap='I'>new</emphasis> widget;
|
||
the <emphasis remap='I'>request</emphasis> widget should never be modified.
|
||
If the initialize procedure
|
||
needs to call any routines that operate on a widget,
|
||
it should specify <emphasis remap='I'>new</emphasis> as the widget instance.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="Constraint_Instance_Initialization_The_ConstraintClassPart_initialize_Procedure">
|
||
<title>Constraint Instance Initialization: The ConstraintClassPart initialize Procedure</title>
|
||
<para>
|
||
The constraint initialization procedure pointer, found in the
|
||
<function>ConstraintClassPart</function>
|
||
<emphasis remap='I'>initialize</emphasis> field of the widget class record, is of type
|
||
<xref linkend='XtInitProc' xrefstyle='select: title'/>.
|
||
The values passed to the parent constraint initialization procedures
|
||
are the same as those passed to the child's class widget initialization
|
||
procedures.
|
||
</para>
|
||
|
||
<para>
|
||
The <emphasis remap='I'>constraints</emphasis> field of the <emphasis remap='I'>request</emphasis> widget points to a copy of the
|
||
constraints record as initialized by the arglist and resource database.
|
||
</para>
|
||
|
||
<para>
|
||
The constraint initialization procedure should compute any constraint fields
|
||
derived from constraint resources.
|
||
It can make further changes to the <emphasis remap='I'>new</emphasis> widget to make the widget
|
||
and any other constraint fields
|
||
conform to the specified constraints, for example,
|
||
changing the widget's size or position.
|
||
</para>
|
||
|
||
<para>
|
||
If a constraint class does not need a constraint initialization procedure,
|
||
it can specify NULL for the <emphasis remap='I'>initialize</emphasis> field of the
|
||
<function>ConstraintClassPart</function>
|
||
in the class record.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="Nonwidget_Data_Initialization_The_initialize_hook_Procedure">
|
||
<title>Nonwidget Data Initialization: The initialize_hook Procedure</title>
|
||
<note>
|
||
<para>
|
||
The initialize_hook procedure is obsolete, as the same information
|
||
is now available to the initialize procedure. The procedure has been
|
||
retained for those widgets that used it in previous releases.
|
||
</para>
|
||
</note>
|
||
|
||
<para>
|
||
The initialize_hook procedure pointer is of type
|
||
<xref linkend='XtArgsProc' xrefstyle='select: title'/>:
|
||
</para>
|
||
|
||
<funcsynopsis id='XtArgsProc'>
|
||
<funcprototype>
|
||
<funcdef>typedef void<function>(*XtArgsProc)</function></funcdef>
|
||
<paramdef>Widget <parameter>w</parameter></paramdef>
|
||
<paramdef>ArgList <parameter>args</parameter></paramdef>
|
||
<paramdef>Cardinal * <parameter>num_args</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>w</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the widget.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>args</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the argument list passed by the client.
|
||
If the client created the widget using a varargs form, any resources
|
||
specified via
|
||
<function>XtVaTypedArg</function>
|
||
are converted to the widget representation and the list is transformed
|
||
into the
|
||
<function>ArgList</function>
|
||
format.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>num_args</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the number of entries in the argument list.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
If this procedure is not NULL,
|
||
it is called immediately after the corresponding initialize
|
||
procedure or in its place if the <emphasis remap='I'>initialize</emphasis> field is NULL.
|
||
</para>
|
||
|
||
<para>
|
||
The initialize_hook procedure allows a widget instance to initialize
|
||
nonresource data using information from the specified argument list
|
||
as if it were a resource.
|
||
</para>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 id="Realizing_Widgets">
|
||
<title>Realizing Widgets</title>
|
||
<para>
|
||
To realize a widget instance, use
|
||
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtRealizeWidget'>
|
||
<funcprototype>
|
||
<funcdef>void <function>XtRealizeWidget</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 Core or any subclass thereof.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
If the widget is already realized,
|
||
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
|
||
simply returns.
|
||
Otherwise it performs the following:
|
||
</para>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
Binds all action names in the widget's
|
||
translation table to procedures (see <xref linkend='Action_Names_to_Procedure_Translations' />).
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Makes a postorder traversal of the widget tree rooted
|
||
at the specified widget and calls each non-NULL change_managed procedure
|
||
of all composite widgets that have one or more managed children.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Constructs an
|
||
<function>XSetWindowAttributes</function>
|
||
structure filled in with information derived from the
|
||
Core
|
||
widget fields and calls the realize procedure for the widget,
|
||
which adds any widget-specific attributes and creates the X window.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
If the widget is
|
||
not a subclass of
|
||
<function>compositeWidgetClass</function>,
|
||
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
|
||
returns; otherwise it continues and performs the following:
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
Descends recursively to each of the widget's
|
||
managed children and calls the realize procedures.
|
||
Primitive widgets that instantiate children are responsible for realizing
|
||
those children themselves.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Maps all of the managed children windows that have <emphasis remap='I'>mapped_when_managed</emphasis>
|
||
<function>True</function>.
|
||
If a widget is managed but <emphasis remap='I'>mapped_when_managed</emphasis> is
|
||
<function>False</function>,
|
||
the widget is allocated visual space but is not displayed.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
If the widget is a top-level shell widget (that is, it has no parent), and
|
||
<emphasis remap='I'>mapped_when_managed</emphasis> is
|
||
<function>True</function>,
|
||
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
|
||
maps the widget window.
|
||
</para>
|
||
|
||
<para>
|
||
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>,
|
||
<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/>,
|
||
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>,
|
||
<xref linkend='XtManageChildren' xrefstyle='select: title'/>,
|
||
<function>XtUnmanage\%Children</function>,
|
||
<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>,
|
||
<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>,
|
||
and
|
||
<function>XtDestroy\%Widget</function>
|
||
maintain the following invariants:
|
||
</para>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
If a composite widget is realized, then all its managed children are realized.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
If a composite widget is realized, then all its managed children that have
|
||
<emphasis remap='I'>mapped_when_managed</emphasis>
|
||
<function>True</function>
|
||
are mapped.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
All Intrinsics functions and all widget routines should accept
|
||
either realized or unrealized widgets.
|
||
When calling the realize or change_managed
|
||
procedures for children of a composite
|
||
widget,
|
||
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
|
||
calls the procedures in reverse order of
|
||
appearance in the
|
||
<function>CompositePart</function>
|
||
<emphasis remap='I'>children</emphasis> list. By default, this
|
||
ordering of the realize procedures will
|
||
result in the stacking order of any newly created subwindows being
|
||
top-to-bottom in the order of appearance on the list, and the most
|
||
recently created child will be at the bottom.
|
||
</para>
|
||
|
||
<para>
|
||
To check whether or not a widget has been realized, use
|
||
<xref linkend='XtIsRealized' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtIsRealized'>
|
||
<funcprototype>
|
||
<funcdef>Boolean <function>XtIsRealized</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='XtIsRealized' xrefstyle='select: title'/>
|
||
function returns
|
||
<function>True</function>
|
||
if the widget has been realized,
|
||
that is, if the widget has a nonzero window ID.
|
||
If the specified object is not a widget, the state of the nearest
|
||
widget ancestor is returned.
|
||
</para>
|
||
|
||
<para>
|
||
Some widget procedures (for example, set_values) might wish to
|
||
operate differently
|
||
after the widget has been realized.
|
||
</para>
|
||
<sect2 id="Widget_Instance_Window_Creation_The_realize_Procedure">
|
||
<title>Widget Instance Window Creation: The realize Procedure</title>
|
||
<para>
|
||
The realize procedure pointer in a widget class is of type
|
||
<xref linkend='XtRealizeProc' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtRealizeProc'>
|
||
<funcprototype>
|
||
<funcdef>typedef void <function>(*XtRealizeProc)</function></funcdef>
|
||
<paramdef>Widget <parameter>w</parameter></paramdef>
|
||
<paramdef>XtValueMask <parameter>value_mask</parameter></paramdef>
|
||
<paramdef>XSetWindowAttributes <parameter>attributes</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>w</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the widget.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>value_mask</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies which fields in the <emphasis remap='I'>attributes</emphasis> structure are used.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>attributes</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the window attributes to use in the
|
||
<function>XCreateWindow</function>
|
||
call.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The realize procedure must create the widget's window.
|
||
</para>
|
||
|
||
<para>
|
||
Before calling the class realize procedure, the generic
|
||
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
|
||
function fills in a mask and a corresponding
|
||
<function>XSetWindowAttributes</function>
|
||
structure.
|
||
It sets the following fields in <emphasis remap='I'>attributes</emphasis> and
|
||
corresponding bits in <emphasis remap='I'>value_mask</emphasis>
|
||
based on information in the widget
|
||
core
|
||
structure:
|
||
</para>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
The <emphasis remap='I'>background_pixmap</emphasis> (or <emphasis remap='I'>background_pixel</emphasis> if <emphasis remap='I'>background_pixmap</emphasis> is
|
||
<function>XtUnspecifiedPixmap</function>)
|
||
is filled in from the corresponding field.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The <emphasis remap='I'>border_pixmap</emphasis> (or <emphasis remap='I'>border_pixel</emphasis> if <emphasis remap='I'>border_pixmap</emphasis> is
|
||
<function>XtUnspecifiedPixmap</function>)
|
||
is filled in from the corresponding field.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The <emphasis remap='I'>colormap</emphasis> is filled in from the corresponding field.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The <emphasis remap='I'>event_mask</emphasis> is filled in based on the event handlers registered,
|
||
the event translations specified, whether the <emphasis remap='I'>expose</emphasis> field is non-NULL,
|
||
and whether <emphasis remap='I'>visible_interest</emphasis> is
|
||
<function>True</function>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The <emphasis remap='I'>bit_gravity</emphasis> is set to
|
||
<function>NorthWestGravity</function>
|
||
if the <emphasis remap='I'>expose</emphasis> field is NULL.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
These or any other fields in attributes and the corresponding bits in
|
||
<emphasis remap='I'>value_mask</emphasis> can be set by the realize procedure.
|
||
</para>
|
||
|
||
<para>
|
||
Note that because realize is not a chained operation,
|
||
the widget class realize procedure must update the
|
||
<function>XSetWindowAttributes</function>
|
||
structure with all the appropriate fields from
|
||
non-Core
|
||
superclasses.
|
||
</para>
|
||
|
||
<para>
|
||
A widget class can inherit its realize procedure from its superclass
|
||
during class initialization.
|
||
The realize procedure defined for
|
||
<function>coreWidgetClass</function>
|
||
calls
|
||
<xref linkend='XtCreateWindow' xrefstyle='select: title'/>
|
||
with the passed <emphasis remap='I'>value_mask</emphasis> and <emphasis remap='I'>attributes</emphasis>
|
||
and with <emphasis remap='I'>window_class</emphasis> and <emphasis remap='I'>visual</emphasis> set to
|
||
<function>CopyFromParent</function>.
|
||
Both
|
||
<function>compositeWidgetClass</function>
|
||
and
|
||
<function>constraintWidgetClass</function>
|
||
inherit this realize procedure, and most new widget subclasses
|
||
can do the same (see <xref linkend='Inheritance_of_Superclass_Operations' />).
|
||
</para>
|
||
|
||
<para>
|
||
The most common noninherited realize procedures set <emphasis remap='I'>bit_gravity</emphasis> in the mask
|
||
and attributes to the appropriate value and then create the window.
|
||
For example, depending on its justification, Label might set <emphasis remap='I'>bit_gravity</emphasis> to
|
||
<function>WestGravity</function>,
|
||
<function>CenterGravity</function>,
|
||
or
|
||
<function>EastGravity</function>.
|
||
Consequently, shrinking it would just move the bits appropriately,
|
||
and no
|
||
exposure
|
||
event is needed for repainting.
|
||
</para>
|
||
|
||
<para>
|
||
If a composite widget's children should be realized in an order other
|
||
than that specified
|
||
(to control the stacking order, for example),
|
||
it should call
|
||
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
|
||
on its children itself in the appropriate order from within its own
|
||
realize procedure.
|
||
</para>
|
||
|
||
<para>
|
||
Widgets that have children and whose class is not a subclass of
|
||
<function>compositeWidgetClass</function>
|
||
are responsible for calling
|
||
<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>
|
||
on their children, usually from within the realize procedure.
|
||
</para>
|
||
|
||
<para>
|
||
Realize procedures cannot manage or unmanage their descendants.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="Window_Creation_Convenience_Routine">
|
||
<title>Window Creation Convenience Routine</title>
|
||
<para>
|
||
Rather than call the Xlib
|
||
<function>XCreateWindow</function>
|
||
function explicitly, a realize procedure should normally call the Intrinsics analog
|
||
<xref linkend='XtCreateWindow' xrefstyle='select: title'/>,
|
||
which simplifies the creation of windows for widgets.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtCreateWindow'>
|
||
<funcprototype>
|
||
<funcdef>void <function>XtCreateWindow</function></funcdef>
|
||
<paramdef>Widget <parameter>w</parameter></paramdef>
|
||
<paramdef>unsigned int <parameter>window_class</parameter></paramdef>
|
||
<paramdef>Visual * <parameter>visual</parameter></paramdef>
|
||
<paramdef>XtValueMask <parameter>value_mask</parameter></paramdef>
|
||
<paramdef>XSetWindowAttributes <parameter>attributes</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>w</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the widget that defines the additional window attributed. Must be of class Core or any subclass thereof.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>window_class</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the Xlib window class (for example,
|
||
<function>InputOutput</function>,
|
||
<function>InputOnly</function>,
|
||
or
|
||
<function>CopyFromParent ).</function>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>visual</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the visual type (usually
|
||
<function>CopyFromParent ).</function>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>value_mask</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies which fields in the <emphasis remap='I'>attributes</emphasis> structure are used.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>attributes</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the window attributes to use in the
|
||
<function>XCreateWindow</function>
|
||
call.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XtCreateWindow' xrefstyle='select: title'/>
|
||
function calls the Xlib
|
||
<function>XCreateWindow</function>
|
||
function with values from the widget structure and the passed parameters.
|
||
Then, it assigns the created window to the widget's <emphasis remap='I'>window</emphasis> field.
|
||
</para>
|
||
|
||
<para>
|
||
<xref linkend='XtCreateWindow' xrefstyle='select: title'/>
|
||
evaluates the following fields of the widget core
|
||
structure: <emphasis remap='I'>depth</emphasis>, <emphasis remap='I'>screen</emphasis>, <emphasis remap='I'>parent->core.window</emphasis>, <emphasis remap='I'>x</emphasis>,
|
||
<emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>, and
|
||
<emphasis remap='I'>border_width</emphasis>.
|
||
</para>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 id="Obtaining_Window_Information_from_a_Widget">
|
||
<title>Obtaining Window Information from a Widget</title>
|
||
<para>
|
||
The
|
||
Core
|
||
widget class definition contains the screen and window ids.
|
||
The <emphasis remap='I'>window</emphasis> field may be NULL for a while
|
||
(see <xref linkend='Creating_Widgets' /> and <xref linkend='Realizing_Widgets' />).
|
||
</para>
|
||
|
||
<para>
|
||
The display pointer, the parent widget, screen pointer,
|
||
and window of a widget are available to the widget writer by means of macros
|
||
and to the application writer by means of functions.
|
||
</para>
|
||
|
||
<funcsynopsis>
|
||
<funcprototype>
|
||
<funcdef>Display <function>XtDisplay</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 Core or any subclass thereof.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<function>XtDisplay</function>
|
||
returns the display pointer for the specified widget.
|
||
</para>
|
||
|
||
<funcsynopsis>
|
||
<funcprototype>
|
||
<funcdef>Widget <function>XtParent</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>
|
||
<function>XtParent</function>
|
||
returns the parent object for the specified widget. The returned object
|
||
will be of class Object or a subclass.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtScreen'>
|
||
<funcprototype>
|
||
<funcdef>Screen <function>*XtScreen</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 Core or any subclass thereof.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<xref linkend='XtScreen' xrefstyle='select: title'/>
|
||
returns the screen pointer for the specified widget.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtWindow'>
|
||
<funcprototype>
|
||
<funcdef>Window <function>XtWindow</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 Core or any subclass thereof.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<xref linkend='XtWindow' xrefstyle='select: title'/>
|
||
returns the window of the specified widget.
|
||
</para>
|
||
|
||
<para>
|
||
The display pointer, screen pointer, and window of a widget or
|
||
of the closest widget ancestor of a nonwidget object are available
|
||
by means of
|
||
<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>,
|
||
<xref linkend='XtScreenOfObject' xrefstyle='select: title'/>,
|
||
and
|
||
<xref linkend='XtWindowOfObject' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtDisplayOfObject'>
|
||
<funcprototype>
|
||
<funcdef>Display <function>*XtDisplayOfObject</function></funcdef>
|
||
<paramdef>Widget <parameter>w</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>object</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the object. Must be of class Object or any subclass thereof.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>
|
||
is identical in function to
|
||
<function>XtDisplay</function>
|
||
if the object is a widget; otherwise
|
||
<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>
|
||
returns the display
|
||
pointer for the nearest ancestor of <emphasis remap='I'>object</emphasis> that is of class
|
||
Widget or a subclass thereof.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtScreenOfObject'>
|
||
<funcprototype>
|
||
<funcdef>Screen <function>*XtScreenOfObject</function></funcdef>
|
||
<paramdef>Widget <parameter>object</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>object</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the object. Must be of class Object or any subclass thereof.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<xref linkend='XtScreenOfObject' xrefstyle='select: title'/>
|
||
is identical in function to
|
||
<xref linkend='XtScreen' xrefstyle='select: title'/>
|
||
if the object is a widget; otherwise
|
||
<xref linkend='XtScreenOfObject' xrefstyle='select: title'/>
|
||
returns the screen pointer
|
||
for the nearest ancestor of <emphasis remap='I'>object</emphasis> that is of class
|
||
Widget or a subclass thereof.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtWindowOfObject'>
|
||
<funcprototype>
|
||
<funcdef>Window <function>XtWindowOfObject</function></funcdef>
|
||
<paramdef>Widget <parameter>object</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>object</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the object. Must be of class Object or any subclass thereof.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<xref linkend='XtWindowOfObject' xrefstyle='select: title'/>
|
||
is identical in function to
|
||
<xref linkend='XtWindow' xrefstyle='select: title'/>
|
||
if the object is a widget; otherwise
|
||
<xref linkend='XtWindowOfObject' xrefstyle='select: title'/>
|
||
returns the window for the nearest ancestor of <emphasis remap='I'>object</emphasis> that is of class
|
||
Widget or a subclass thereof.
|
||
</para>
|
||
|
||
<para>
|
||
To retrieve the instance name of an object, use
|
||
<xref linkend='XtName' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtName'>
|
||
<funcprototype>
|
||
<funcdef>String <function>XtName</function></funcdef>
|
||
<paramdef>Widget <parameter>object</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>object</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the object whose name is desired. Must be of class Object or any subclass thereof.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<xref linkend='XtName' xrefstyle='select: title'/>
|
||
returns a pointer to the instance name of the specified object.
|
||
The storage is owned by the Intrinsics and must not be modified. The
|
||
name is not qualified by the names of any of the object's ancestors.
|
||
</para>
|
||
|
||
<para>
|
||
Several window attributes are locally cached in the widget instance.
|
||
Thus, they can be set by the resource manager and
|
||
<xref linkend='XtSetValues' xrefstyle='select: title'/>
|
||
as well as used by routines that derive structures from these values
|
||
(for example, <emphasis remap='I'>depth</emphasis> for deriving pixmaps,
|
||
<emphasis remap='I'>background_pixel</emphasis> for deriving GCs, and so on) or in the
|
||
<xref linkend='XtCreateWindow' xrefstyle='select: title'/>
|
||
call.
|
||
</para>
|
||
|
||
<para>
|
||
The <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>, and <emphasis remap='I'>border_width</emphasis>
|
||
window attributes are available to
|
||
geometry managers.
|
||
These fields are maintained synchronously inside the Intrinsics.
|
||
When an
|
||
<function>XConfigureWindow</function>
|
||
is issued by the Intrinsics on the widget's window (on request of its parent),
|
||
these values are updated immediately rather than some time later
|
||
when the server generates a
|
||
<function>ConfigureNotify</function>
|
||
event.
|
||
(In fact, most widgets do not select
|
||
<function>SubstructureNotify</function>
|
||
events.)
|
||
This ensures that all geometry calculations are based on the internally
|
||
consistent toolkit world rather than on either
|
||
an inconsistent world updated by asynchronous
|
||
<function>ConfigureNotify</function>
|
||
events or a consistent, but slow, world in which geometry managers
|
||
ask the server
|
||
for window sizes whenever they need to lay out their managed children
|
||
(see <xref linkend='Geometry_Management' />).
|
||
</para>
|
||
<sect2 id="Unrealizing_Widgets">
|
||
<title>Unrealizing Widgets</title>
|
||
<para>
|
||
To destroy the windows associated with a widget and its
|
||
non-pop-up descendants, use
|
||
<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtUnrealizeWidget'>
|
||
<funcprototype>
|
||
<funcdef>void <function>XtUnrealizeWidget</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 Core or any subclass thereof.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
If the widget is currently unrealized,
|
||
<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>
|
||
simply returns. Otherwise it performs the following:
|
||
</para>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
Unmanages the widget if the widget is managed.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Makes a postorder (child-to-parent) traversal of the widget tree
|
||
rooted at the specified widget and, for each widget that has
|
||
declared a callback list resource named ``unrealizeCallback'', executes the
|
||
procedures on the
|
||
XtNunrealizeCallback
|
||
list.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Destroys the widget's window and any subwindows by calling
|
||
<function>XDestroyWindow</function>
|
||
with the specified widget's <emphasis remap='I'>window</emphasis> field.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
Any events in the queue or which arrive following a call to
|
||
<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>
|
||
will be dispatched as if the window(s) of the
|
||
unrealized widget(s) had never existed.
|
||
</para>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 id="Destroying_Widgets">
|
||
<title>Destroying Widgets</title>
|
||
<para>
|
||
The Intrinsics provide support
|
||
</para>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
To destroy all the pop-up children of the widget being destroyed
|
||
and destroy all children of composite widgets.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
To remove (and unmap) the widget from its parent.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
To call the callback procedures that have been registered to trigger
|
||
when the widget is destroyed.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
To minimize the number of things a widget has to deallocate when destroyed.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
To minimize the number of
|
||
<function>XDestroyWindow</function>
|
||
calls when destroying a widget tree.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
To destroy a widget instance, use
|
||
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
|
||
<funcsynopsis id='XtDestroyWidget'>
|
||
<funcprototype>
|
||
<funcdef>void <function>XtDestroyWidget</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='XtDestroyWidget' xrefstyle='select: title'/>
|
||
function provides the only method of destroying a widget,
|
||
including widgets that need to destroy themselves.
|
||
It can be called at any time,
|
||
including from an application callback routine of the widget being destroyed.
|
||
This requires a two-phase destroy process in order to avoid dangling
|
||
references to destroyed widgets.
|
||
</para>
|
||
|
||
<para>
|
||
In phase 1,
|
||
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
|
||
performs the following:
|
||
</para>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
If the <emphasis remap='I'>being_destroyed</emphasis> field of the widget is
|
||
<function>True</function>,
|
||
it returns immediately.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Recursively descends the widget tree and
|
||
sets the <emphasis remap='I'>being_destroyed</emphasis> field to
|
||
<function>True</function>
|
||
for the widget and all normal and pop-up children.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Adds the widget to a list of widgets (the destroy list) that should be
|
||
destroyed when it is safe to do so.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
Entries on the destroy list satisfy the invariant that
|
||
if w2 occurs after w1 on the destroy list, then w2 is not a descendent,
|
||
either normal or pop-up, of w1.
|
||
</para>
|
||
|
||
<para>
|
||
Phase 2 occurs when all procedures that should execute as a result of
|
||
the current event have been called, including all procedures registered with
|
||
the event and translation managers,
|
||
that is, when the current invocation of
|
||
<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>
|
||
is about to return, or immediately if not in
|
||
<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<para>
|
||
In phase 2,
|
||
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
|
||
performs the following on each entry in the destroy list in the order
|
||
specified:
|
||
</para>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
If the widget is not a pop-up child and the widget's parent is a subclass of
|
||
<function>composite\%WidgetClass</function>,
|
||
and if the parent is not being destroyed,
|
||
it calls
|
||
<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>
|
||
on the widget and then calls the widget's parent's delete_child procedure
|
||
(see <xref linkend='Deletion_of_Children_The_delete_child_Procedure' />).
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Calls the destroy callback procedures registered on the widget
|
||
and all normal and pop-up descendants in postorder (it calls child
|
||
callbacks before parent callbacks).
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
The
|
||
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
|
||
function then makes second traversal of the widget and all normal
|
||
and pop-up descendants to perform the following three items on each
|
||
widget in postorder:
|
||
</para>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
If the widget is not a pop-up child and the widget's parent is a subclass of
|
||
<function>constraint\%WidgetClass</function>,
|
||
it calls the
|
||
<function>ConstraintClassPart</function>
|
||
destroy procedure for the parent,
|
||
then for the parent's superclass,
|
||
until finally it calls the
|
||
<function>ConstraintClassPart</function>
|
||
destroy procedure for
|
||
<function>constraintWidgetClass</function>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Calls the
|
||
<function>CoreClassPart</function>
|
||
destroy procedure declared in the widget class,
|
||
then the destroy procedure declared in its superclass,
|
||
until finally it calls the destroy procedure declared in the Object
|
||
class record. Callback lists are deallocated.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
If the widget class object class part contains an
|
||
<function>ObjectClassExtension</function>
|
||
record with the record_type
|
||
<emphasis role='strong'>NULLQUARK</emphasis>
|
||
and the <emphasis remap='I'>deallocate</emphasis> field is not NULL,
|
||
calls the deallocate procedure to deallocate the instance and if one
|
||
exists, the constraint record. Otherwise, the Intrinsics will deallocate
|
||
the widget instance record and if one exists, the constraint record.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Calls
|
||
<function>XDestroyWindow</function>
|
||
if the specified widget is realized (that is, has an X window).
|
||
The server recursively destroys all normal descendant windows.
|
||
(Windows of realized pop-up Shell children, and their
|
||
descendants, are destroyed by a shell class destroy procedure.)
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<sect2 id="Adding_and_Removing_Destroy_Callbacks">
|
||
<title>Adding and Removing Destroy Callbacks</title>
|
||
<para>
|
||
When an application needs to perform additional processing during the
|
||
destruction of a widget,
|
||
it should register a destroy callback procedure for the widget.
|
||
The destroy callback procedures use the mechanism described in
|
||
<xref linkend='Callbacks' />.
|
||
The destroy callback list is identified by the resource name
|
||
XtNdestroyCallback.
|
||
</para>
|
||
|
||
<para>
|
||
For example, the following adds an application-supplied destroy callback
|
||
procedure <emphasis remap='I'>ClientDestroy</emphasis> with client data to a widget by calling
|
||
<xref linkend='XtAddCallback' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<literallayout>
|
||
XtAddCallback(<emphasis remap='I'>w</emphasis>, XtNdestroyCallback, <emphasis remap='I'>ClientDestroy</emphasis>, <emphasis remap='I'>client_data</emphasis>)
|
||
</literallayout>
|
||
|
||
<para>
|
||
Similarly, the following removes the application-supplied destroy callback
|
||
procedure <emphasis remap='I'>ClientDestroy</emphasis> by calling
|
||
<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<literallayout>
|
||
XtRemoveCallback(<emphasis remap='I'>w</emphasis>, XtNdestroyCallback, <emphasis remap='I'>ClientDestroy</emphasis>, <emphasis remap='I'>client_data</emphasis>)
|
||
</literallayout>
|
||
<para>
|
||
The <emphasis remap='I'>ClientDestroy</emphasis> argument is of type
|
||
<xref linkend='XtCallbackProc' xrefstyle='select: title'/>;
|
||
see <xref linkend='Using_Callback_Procedure_and_Callback_List_Definitions' />.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="Dynamic_Data_Deallocation_The_destroy_Procedure">
|
||
<title>Dynamic Data Deallocation: The destroy Procedure</title>
|
||
<para>
|
||
The destroy procedure pointers in the
|
||
<function>ObjectClassPart</function>,
|
||
<function>RectObjClassPart</function>,
|
||
and
|
||
<function>CoreClassPart</function>
|
||
structures are of type
|
||
<xref linkend='XtWidgetProc' xrefstyle='select: title'/>.
|
||
</para>
|
||
|
||
<funcsynopsis id='XtWidgetProc'>
|
||
<funcprototype>
|
||
<funcdef>typedef void <function>XtWidgetProc</function></funcdef>
|
||
<paramdef>Widget <parameter>w</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>w</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the widget being destroyed.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The destroy procedures are called in subclass-to-superclass order.
|
||
Therefore, a widget's destroy procedure should deallocate only storage
|
||
that is specific to the subclass and should ignore the storage
|
||
allocated by any of its superclasses.
|
||
The destroy procedure should deallocate only resources that have been
|
||
explicitly created by the subclass.
|
||
Any resource that was obtained from the resource database
|
||
or passed in an argument list was not created by the widget
|
||
and therefore should not be destroyed by it.
|
||
If a widget does not need to deallocate any storage,
|
||
the destroy procedure entry in its class record can be NULL.
|
||
</para>
|
||
|
||
<para>
|
||
Deallocating storage includes, but is not limited to,
|
||
the following steps:
|
||
</para>
|
||
<itemizedlist spacing='compact'>
|
||
<listitem>
|
||
<para>
|
||
Calling
|
||
<xref linkend='XtFree' xrefstyle='select: title'/>
|
||
on dynamic storage allocated with
|
||
<xref linkend='XtMalloc' xrefstyle='select: title'/>,
|
||
<xref linkend='XtCalloc' xrefstyle='select: title'/>,
|
||
and so on.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Calling
|
||
<function>XFreePixmap</function>
|
||
on pixmaps created with direct X calls.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Calling
|
||
<xref linkend='XtReleaseGC' xrefstyle='select: title'/>
|
||
on GCs allocated with
|
||
<xref linkend='XtGetGC' xrefstyle='select: title'/>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Calling
|
||
<function>XFreeGC</function>
|
||
on GCs allocated with direct X calls.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Calling
|
||
<xref linkend='XtRemoveEventHandler' xrefstyle='select: title'/>
|
||
on event handlers added to other widgets.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Calling
|
||
<xref linkend='XtRemoveTimeOut' xrefstyle='select: title'/>
|
||
on timers created with
|
||
<xref linkend='XtAppAddTimeOut' xrefstyle='select: title'/>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Calling
|
||
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
|
||
for each child if the widget has children
|
||
and is not a subclass of
|
||
<function>compositeWidgetClass</function>.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
During destroy phase 2 for each widget, the Intrinsics remove the widget
|
||
from the modal cascade, unregister all event handlers, remove all key,
|
||
keyboard, button, and pointer grabs and remove all callback procedures
|
||
registered on the widget. Any outstanding selection transfers will time out.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="Dynamic_Constraint_Data_Deallocation_The_ConstraintClassPart_destroy_Procedure">
|
||
<title>Dynamic Constraint Data Deallocation: The ConstraintClassPart destroy Procedure</title>
|
||
<para>
|
||
The constraint destroy procedure identified in the
|
||
<function>ConstraintClassPart</function>
|
||
<function>constraintWidgetClass</function>.
|
||
This constraint destroy procedure pointer is of type
|
||
<xref linkend='XtWidgetProc' xrefstyle='select: title'/>.
|
||
The constraint destroy procedures are called in subclass-to-superclass order,
|
||
starting at the class of the widget's parent and ending at
|
||
<function>constraint\%WidgetClass</function>.
|
||
Therefore, a parent's constraint destroy procedure should deallocate only
|
||
storage that is specific to the constraint subclass
|
||
and not storage allocated by any of its superclasses.
|
||
</para>
|
||
|
||
<para>
|
||
If a parent does not need to deallocate any constraint storage,
|
||
the constraint destroy procedure entry
|
||
in its class record can be NULL.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="Widget_Instance_Deallocation_The_deallocate_Procedure">
|
||
<title>Widget Instance Deallocation: The deallocate Procedure</title>
|
||
<para>
|
||
The deallocate procedure pointer in the
|
||
<function>ObjectClassExtension</function>
|
||
record is of type
|
||
<function>XtDeallocateProc</function>.
|
||
</para>
|
||
|
||
<funcsynopsis>
|
||
<funcprototype>
|
||
<funcdef>typedef void <function>(*XtDeallocateProc)</function></funcdef>
|
||
<paramdef>Widget <parameter>widget</parameter></paramdef>
|
||
<paramdef>XtPointer <parameter>more_bytes</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>widget</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the widget being destroyed.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
<emphasis remap='I'>more_bytes</emphasis>
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the auxiliary memory received from the corresponding allocator
|
||
along with the widget, or NULL.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
When a widget is destroyed, if an
|
||
<function>ObjectClassExtension</function>
|
||
record exists in the object class part <emphasis remap='I'>extension</emphasis> field
|
||
with <emphasis remap='I'>record_type</emphasis>
|
||
<emphasis role='strong'>NULLQUARK</emphasis>
|
||
and the <emphasis remap='I'>deallocate</emphasis> field is not NULL, the
|
||
<function>XtDeallocateProc</function>
|
||
will be called.
|
||
If no ObjectClassPart extension record is declared with <emphasis remap='I'>record_type</emphasis>
|
||
equal to
|
||
<emphasis role='strong'>NULLQUARK</emphasis>,
|
||
then
|
||
<function>XtInheritAllocate</function>
|
||
and
|
||
<function>XtInheritDeallocate</function>
|
||
are assumed.
|
||
The responsibilities of the deallocate procedure are to deallocate the
|
||
memory specified by <emphasis remap='I'>more_bytes</emphasis> if it is not NULL,
|
||
to deallocate the constraints record as specified by the
|
||
widget's <emphasis remap='I'>core.constraints</emphasis> field if it is
|
||
not NULL, and to deallocate the widget instance itself.
|
||
</para>
|
||
|
||
<para>
|
||
If no
|
||
<function>XtDeallocateProc</function>
|
||
is found, it is assumed that the Intrinsics
|
||
originally allocated the memory and is responsible for freeing it.
|
||
</para>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 id="Exiting_from_an_Application">
|
||
<title>Exiting from an Application</title>
|
||
<para>
|
||
All X Toolkit applications should terminate
|
||
by calling
|
||
<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>
|
||
and then exiting
|
||
using the
|
||
standard method for their operating system (typically, by calling
|
||
<function>exit</function>
|
||
for POSIX-based systems).
|
||
The quickest way to make the windows disappear while exiting is to call
|
||
<xref linkend='XtUnmapWidget' xrefstyle='select: title'/>
|
||
on each top-level shell widget.
|
||
The Intrinsics have no resources beyond those in the program image,
|
||
and the X server will free its resources when its connection
|
||
to the application is broken.
|
||
</para>
|
||
|
||
<para>
|
||
Depending upon the widget set in use, it may be necessary to explicitly
|
||
destroy individual widgets or widget trees with
|
||
<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>
|
||
before calling
|
||
<xref linkend='XtDestroyApplicationContext' xrefstyle='select: title'/>
|
||
in order to ensure that any
|
||
required widget cleanup is properly executed. The application developer
|
||
must refer to the widget documentation to learn if a widget needs to
|
||
perform cleanup beyond that performed automatically by the
|
||
operating system. If the client is a session participant
|
||
(see <xref linkend='Session_Participation' />), then the client may wish to resign from the session
|
||
before exiting. See <xref linkend='Resigning_from_a_Session' /> for details.
|
||
</para>
|
||
</sect1>
|
||
</chapter>
|