3166 lines
94 KiB
Plaintext
3166 lines
94 KiB
Plaintext
|
.\" $Xorg: CH02,v 1.3 2000/08/17 19:42:42 cpqbld Exp $
|
||
|
|
.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
|
||
|
|
.\" X Consortium
|
||
|
|
.\"
|
||
|
|
.\" Permission is hereby granted, free of charge, to any person obtaining
|
||
|
|
.\" a copy of this software and associated documentation files (the
|
||
|
|
.\" "Software"), to deal in the Software without restriction, including
|
||
|
|
.\" without limitation the rights to use, copy, modify, merge, publish,
|
||
|
|
.\" distribute, sublicense, and/or sell copies of the Software, and to
|
||
|
|
.\" permit persons to whom the Software is furnished to do so, subject to
|
||
|
|
.\" the following conditions:
|
||
|
|
.\"
|
||
|
|
.\" The above copyright notice and this permission notice shall be included
|
||
|
|
.\" in all copies or substantial portions of the Software.
|
||
|
|
.\"
|
||
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
||
|
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
||
|
|
.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
|
||
|
|
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
|
||
|
|
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
||
|
|
.\" OTHER DEALINGS IN THE SOFTWARE.
|
||
|
|
.\"
|
||
|
|
.\" Except as contained in this notice, the name of the X Consortium shall
|
||
|
|
.\" not be used in advertising or otherwise to promote the sale, use or
|
||
|
|
.\" other dealings in this Software without prior written authorization
|
||
|
|
.\" from the X Consortium.
|
||
|
|
.\"
|
||
|
|
.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
|
||
|
|
.\" Digital Equipment Corporation, Maynard, Massachusetts.
|
||
|
|
.\"
|
||
|
|
.\" Permission to use, copy, modify and distribute this documentation for any
|
||
|
|
.\" purpose and without fee is hereby granted, provided that the above copyright
|
||
|
|
.\" notice appears in all copies and that both that copyright notice and this
|
||
|
|
.\" permission notice appear in supporting documentation, and that the name of
|
||
|
|
.\" Digital not be used in in advertising or publicity pertaining
|
||
|
|
.\" to distribution of the software without specific, written prior permission.
|
||
|
|
.\" Digital makes no representations about the suitability of the
|
||
|
|
.\" software described herein for any purpose.
|
||
|
|
.\" It is provided ``as is'' without express or implied warranty.
|
||
|
|
.\"
|
||
|
|
\&
|
||
|
|
.sp 1
|
||
|
|
.ce 3
|
||
|
|
\s+1\fBChapter 2\fP\s-1
|
||
|
|
|
||
|
|
\s+1\fBWidget Instantiation\fP\s-1
|
||
|
|
.sp 2
|
||
|
|
.nr H1 2
|
||
|
|
.nr H2 0
|
||
|
|
.nr H3 0
|
||
|
|
.nr H4 0
|
||
|
|
.nr H5 0
|
||
|
|
.LP
|
||
|
|
.XS
|
||
|
|
Chapter 2 \(em Widget Instantiation
|
||
|
|
.XE
|
||
|
|
A hierarchy of widget instances constitutes a widget tree.
|
||
|
|
The shell widget returned by
|
||
|
|
.PN XtAppCreateShell
|
||
|
|
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 Chapter 5),
|
||
|
|
this widget tree instance defines the associated X Window tree.
|
||
|
|
.LP
|
||
|
|
Widgets can be either composite or primitive.
|
||
|
|
Both kinds of widgets can contain children,
|
||
|
|
but the \*(xI provide a set of management mechanisms for constructing
|
||
|
|
and interfacing between composite widgets, their children, and
|
||
|
|
other clients.
|
||
|
|
.LP
|
||
|
|
Composite widgets, that is, members of the class
|
||
|
|
.PN compositeWidgetClass ,
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
In addition,
|
||
|
|
the \*(xI 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.
|
||
|
|
.LP
|
||
|
|
A widget tree is manipulated by several \*(xI functions.
|
||
|
|
For example,
|
||
|
|
.PN XtRealizeWidget
|
||
|
|
traverses the tree downward and recursively realizes all
|
||
|
|
pop-up widgets and children of composite widgets.
|
||
|
|
.PN XtDestroyWidget
|
||
|
|
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.
|
||
|
|
.PN XtMakeGeometryRequest
|
||
|
|
traverses the tree up one level and calls the geometry manager
|
||
|
|
that is responsible for a widget child's geometry.
|
||
|
|
.LP
|
||
|
|
To facilitate upward traversal of the widget tree,
|
||
|
|
each widget has a pointer to its parent widget.
|
||
|
|
The
|
||
|
|
Shell
|
||
|
|
widget that
|
||
|
|
.PN XtAppCreateShell
|
||
|
|
returns has a \fIparent\fP pointer of NULL.
|
||
|
|
.LP
|
||
|
|
To facilitate downward traversal of the widget tree,
|
||
|
|
the \fIchildren\fP 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.
|
||
|
|
|
||
|
|
.NH 2
|
||
|
|
Initializing the \*(tk
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Initializing the \*(tk\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
Before an application can call any \*(xI function
|
||
|
|
other than
|
||
|
|
.PN XtSetLanguageProc
|
||
|
|
and
|
||
|
|
.PN XtToolkitThreadInitialize ,
|
||
|
|
it must initialize the \*(xI by using
|
||
|
|
.IP \(bu 5
|
||
|
|
.PN XtToolkitInitialize ,
|
||
|
|
which initializes the \*(xI internals
|
||
|
|
.IP \(bu 5
|
||
|
|
.PN XtCreateApplicationContext ,
|
||
|
|
which initializes the per-application state
|
||
|
|
.IP \(bu 5
|
||
|
|
.PN XtDisplayInitialize
|
||
|
|
or
|
||
|
|
.PN XtOpenDisplay ,
|
||
|
|
which initializes the per-display state
|
||
|
|
.IP \(bu 5
|
||
|
|
.PN XtAppCreateShell ,
|
||
|
|
which creates the root of a widget tree
|
||
|
|
.LP
|
||
|
|
Or an application can call the convenience procedure
|
||
|
|
.PN XtOpenApplication ,
|
||
|
|
which combines the functions of the preceding procedures.
|
||
|
|
An application wishing to use the ANSI C locale mechanism should call
|
||
|
|
.PN XtSetLanguageProc
|
||
|
|
prior to calling
|
||
|
|
.PN XtDisplayInitialize ,
|
||
|
|
.PN XtOpenDisplay ,
|
||
|
|
.PN XtOpenApplication ,
|
||
|
|
or
|
||
|
|
.PN XtAppInitialize .
|
||
|
|
.LP
|
||
|
|
Multiple instances of \*(tk 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.
|
||
|
|
.IN "application context" "" "@DEF@"
|
||
|
|
To accommodate both requirements,
|
||
|
|
the \*(xI 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
|
||
|
|
.PN Display
|
||
|
|
pointers for that application.
|
||
|
|
The \*(xI handle all display connections within a single application
|
||
|
|
context simultaneously, handling input in a round-robin fashion.
|
||
|
|
The application context type
|
||
|
|
.PN XtAppContext
|
||
|
|
.IN "XtAppContext" "" "@DEF@"
|
||
|
|
is opaque to clients.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
To initialize the \*(xI internals, use
|
||
|
|
.PN XtToolkitInitialize .
|
||
|
|
.LP
|
||
|
|
.IN "XtToolkitInitialize" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
void XtToolkitInitialize()
|
||
|
|
.FN
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
If
|
||
|
|
.PN XtToolkitInitialize
|
||
|
|
was previously called, it returns immediately.
|
||
|
|
When
|
||
|
|
.PN XtToolkitThreadInitialize
|
||
|
|
is called before
|
||
|
|
.PN XtToolkitInitialize ,
|
||
|
|
the latter is protected against
|
||
|
|
simultaneous activation by multiple threads.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
To create an application context, use
|
||
|
|
.PN XtCreateApplicationContext .
|
||
|
|
.LP
|
||
|
|
.IN "XtCreateApplicationContext" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
XtAppContext XtCreateApplicationContext()
|
||
|
|
.FN
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtCreateApplicationContext
|
||
|
|
function returns an application context,
|
||
|
|
which is an opaque type.
|
||
|
|
Every application must have at least one application context.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
To destroy an application context and close any
|
||
|
|
remaining display connections in it, use
|
||
|
|
.PN XtDestroyApplicationContext .
|
||
|
|
.LP
|
||
|
|
.IN "XtDestroyApplicationContext" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
void XtDestroyApplicationContext(\fIapp_context\fP)
|
||
|
|
.br
|
||
|
|
XtAppContext \fIapp_context\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIapp_context\fP 1i
|
||
|
|
Specifies the application context.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtDestroyApplicationContext
|
||
|
|
function destroys the specified application context.
|
||
|
|
If called from within an event dispatch (for example, in a callback procedure),
|
||
|
|
.PN XtDestroyApplicationContext
|
||
|
|
does not destroy the application context until the dispatch is complete.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
To get the application context in which a given widget was created, use
|
||
|
|
.PN XtWidgetToApplicationContext .
|
||
|
|
.LP
|
||
|
|
.IN "XtWidgetToApplicationContext" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
XtAppContext XtWidgetToApplicationContext(\fIw\fP)
|
||
|
|
.br
|
||
|
|
Widget \fIw\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIw\fP 1i
|
||
|
|
Specifies the widget for which you want the application context. \*(oI
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtWidgetToApplicationContext
|
||
|
|
function returns the application context for the specified widget.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
To initialize a display and add it to an application context, use
|
||
|
|
.PN XtDisplayInitialize .
|
||
|
|
.LP
|
||
|
|
.IN "XtDisplayInitialize" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
void XtDisplayInitialize(\fIapp_context\fP, \fIdisplay\fP, \
|
||
|
|
\fIapplication_name\fP, \fIapplication_class\fP,
|
||
|
|
.br
|
||
|
|
\fIoptions\fP, \fInum_options\fP, \fIargc\fP, \fIargv\fP)
|
||
|
|
.br
|
||
|
|
XtAppContext \fIapp_context\fP;
|
||
|
|
.br
|
||
|
|
Display *\fIdisplay\fP;
|
||
|
|
.br
|
||
|
|
String \fIapplication_name\fP;
|
||
|
|
.br
|
||
|
|
String \fIapplication_class\fP;
|
||
|
|
.br
|
||
|
|
XrmOptionDescRec *\fIoptions\fP;
|
||
|
|
.br
|
||
|
|
Cardinal \fInum_options\fP;
|
||
|
|
.br
|
||
|
|
int *\fIargc\fP;
|
||
|
|
.br
|
||
|
|
String *\fIargv\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIapp_context\fP 1.4i
|
||
|
|
Specifies the application context.
|
||
|
|
.IP \fIdisplay\fP 1.4i
|
||
|
|
Specifies a previously opened display connection. Note that a single
|
||
|
|
display connection can be in at most one application context.
|
||
|
|
.IP \fIapplication_name\fP 1.4i
|
||
|
|
Specifies the name of the application instance.
|
||
|
|
.IP \fIapplication_class\fP 1.4i
|
||
|
|
Specifies the class name of this application,
|
||
|
|
which is usually the generic name for all instances of this application.
|
||
|
|
.IP \fIoptions\fP 1.4i
|
||
|
|
Specifies how to parse the command line for any application-specific resources.
|
||
|
|
The \fIoptions\fP argument is passed as a parameter to
|
||
|
|
.PN XrmParseCommand .
|
||
|
|
For further information,
|
||
|
|
see Section 15.9 in \fI\*(xL\fP and Section 2.4 of this specification.
|
||
|
|
.IP \fInum_options\fP 1.4i
|
||
|
|
Specifies the number of entries in the options list.
|
||
|
|
.IP \fIargc\fP 1.4i
|
||
|
|
Specifies a pointer to the number of command line parameters.
|
||
|
|
.IP \fIargv\fP 1.4i
|
||
|
|
Specifies the list of command line parameters.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtDisplayInitialize
|
||
|
|
function retrieves the language string to be
|
||
|
|
used for the specified display (see Section 11.11),
|
||
|
|
calls the language procedure (if set) with that language string,
|
||
|
|
builds the resource database for the default screen, calls the Xlib
|
||
|
|
.PN XrmParseCommand
|
||
|
|
function to parse the command line,
|
||
|
|
and performs other per-display initialization.
|
||
|
|
After
|
||
|
|
.PN XrmParseCommand
|
||
|
|
has been called,
|
||
|
|
\fIargc\fP and \fIargv\fP contain only those parameters that
|
||
|
|
were not in the standard option table or in the table specified by the
|
||
|
|
\fIoptions\fP argument.
|
||
|
|
If the modified \fIargc\fP is not zero,
|
||
|
|
most applications simply print out the modified \fIargv\fP along with a message
|
||
|
|
listing the allowable options.
|
||
|
|
On POSIX-based systems,
|
||
|
|
the application name is usually the final component of \fIargv\fP[0].
|
||
|
|
If the synchronous resource is
|
||
|
|
.PN True ,
|
||
|
|
.PN XtDisplayInitialize
|
||
|
|
calls the Xlib
|
||
|
|
.PN XSynchronize
|
||
|
|
function to put Xlib into synchronous mode for this display connection
|
||
|
|
and any others currently open in the application context.
|
||
|
|
See Sections 2.3 and 2.4 for details on the \fIapplication_name\fP,
|
||
|
|
\fIapplication_class\fP, \fIoptions\fP, and \fInum_options\fP arguments.
|
||
|
|
.LP
|
||
|
|
.PN XtDisplayInitialize
|
||
|
|
calls
|
||
|
|
.PN XrmSetDatabase
|
||
|
|
to associate the resource database of the default screen with the
|
||
|
|
display before returning.
|
||
|
|
|
||
|
|
.KS
|
||
|
|
.LP
|
||
|
|
To open a display, initialize it, and then
|
||
|
|
add it to an application context, use
|
||
|
|
.PN XtOpenDisplay .
|
||
|
|
.LP
|
||
|
|
.IN "XtOpenDisplay" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
Display *XtOpenDisplay(\fIapp_context\fP, \fIdisplay_string\fP, \
|
||
|
|
\fIapplication_name\fP, \fIapplication_class\fP,
|
||
|
|
.br
|
||
|
|
\fIoptions\fP, \fInum_options\fP, \fIargc\fP, \fIargv\fP)
|
||
|
|
.br
|
||
|
|
XtAppContext \fIapp_context\fP;
|
||
|
|
.br
|
||
|
|
String \fIdisplay_string\fP;
|
||
|
|
.br
|
||
|
|
String \fIapplication_name\fP;
|
||
|
|
.br
|
||
|
|
String \fIapplication_class\fP;
|
||
|
|
.br
|
||
|
|
XrmOptionDescRec *\fIoptions\fP;
|
||
|
|
.br
|
||
|
|
Cardinal \fInum_options\fP;
|
||
|
|
.br
|
||
|
|
int *\fIargc\fP;
|
||
|
|
.br
|
||
|
|
String *\fIargv\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIapp_context\fP 1.4i
|
||
|
|
Specifies the application context.
|
||
|
|
.IP \fIdisplay_string\fP 1.4i
|
||
|
|
Specifies the display string, or NULL.
|
||
|
|
.IP \fIapplication_name\fP 1.4i
|
||
|
|
Specifies the name of the application instance, or NULL.
|
||
|
|
.IP \fIapplication_class\fP 1.4i
|
||
|
|
Specifies the class name of this application,
|
||
|
|
which is usually the generic name for all instances of this application.
|
||
|
|
.IP \fIoptions\fP 1.4i
|
||
|
|
Specifies how to parse the command line for any application-specific resources.
|
||
|
|
The options argument is passed as a parameter to
|
||
|
|
.PN XrmParseCommand .
|
||
|
|
.IP \fInum_options\fP 1.4i
|
||
|
|
Specifies the number of entries in the options list.
|
||
|
|
.IP \fIargc\fP 1.4i
|
||
|
|
Specifies a pointer to the number of command line parameters.
|
||
|
|
.IP \fIargv\fP 1.4i
|
||
|
|
Specifies the list of command line parameters.
|
||
|
|
.KE
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtOpenDisplay
|
||
|
|
function calls
|
||
|
|
.PN XOpenDisplay
|
||
|
|
with the specified \fIdisplay_string\fP.
|
||
|
|
If \fIdisplay_string\fP is NULL,
|
||
|
|
.PN XtOpenDisplay
|
||
|
|
uses the current value of the \-display option specified in \fIargv\fP.
|
||
|
|
If no display is specified in \fIargv\fP,
|
||
|
|
the user's default display is retrieved from the environment.
|
||
|
|
On POSIX-based systems,
|
||
|
|
this is the value of the
|
||
|
|
.PN \s-1DISPLAY\s+1
|
||
|
|
environment variable.
|
||
|
|
.LP
|
||
|
|
If this succeeds,
|
||
|
|
.PN XtOpenDisplay
|
||
|
|
then calls
|
||
|
|
.PN XtDisplayInitialize
|
||
|
|
and passes it the opened display and
|
||
|
|
the value of the \-name option specified in \fIargv\fP as the application name.
|
||
|
|
If no \-name option is specified
|
||
|
|
and \fIapplication_name\fP is
|
||
|
|
non-NULL, \fIapplication_name\fP is passed to
|
||
|
|
.PN XtDisplayInitialize .
|
||
|
|
If \fIapplication_name\fP is NULL and if the environment variable
|
||
|
|
.PN \s-1RESOURCE_NAME\s+1
|
||
|
|
is set, the value of
|
||
|
|
.PN \s-1RESOURCE_NAME\s+1
|
||
|
|
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 \fIargv\fP[0] less any directory and file type components, that is, the
|
||
|
|
final component of \fIargv\fP[0], if specified. If \fIargv\fP[0] does not exist or
|
||
|
|
is the empty string, the application name is ``main''.
|
||
|
|
.PN XtOpenDisplay
|
||
|
|
returns the newly opened display or NULL if it failed.
|
||
|
|
.LP
|
||
|
|
See Section 7.12 for information regarding the use of
|
||
|
|
.PN XtOpenDisplay
|
||
|
|
in multiple threads.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
To close a display and remove it from an application context, use
|
||
|
|
.PN XtCloseDisplay .
|
||
|
|
.LP
|
||
|
|
.IN "XtCloseDisplay" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
void XtCloseDisplay(\fIdisplay\fP)
|
||
|
|
.br
|
||
|
|
Display *\fIdisplay\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIdisplay\fP 1i
|
||
|
|
Specifies the display.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtCloseDisplay
|
||
|
|
function calls
|
||
|
|
.PN XCloseDisplay
|
||
|
|
with the specified \fIdisplay\fP as soon as it is safe to do so.
|
||
|
|
If called from within an event dispatch (for example, a callback procedure),
|
||
|
|
.PN XtCloseDisplay
|
||
|
|
does not close the display until the dispatch is complete.
|
||
|
|
Note that applications need only call
|
||
|
|
.PN XtCloseDisplay
|
||
|
|
if they are to continue executing after closing the display;
|
||
|
|
otherwise, they should call
|
||
|
|
.PN XtDestroyApplicationContext .
|
||
|
|
.LP
|
||
|
|
See Section 7.12 for information regarding the use of
|
||
|
|
.PN XtCloseDisplay
|
||
|
|
in multiple threads.
|
||
|
|
|
||
|
|
.NH 2
|
||
|
|
Establishing the Locale
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Establishing the Locale\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
Resource databases are specified to be created in the current process
|
||
|
|
locale. During display initialization prior to creating the
|
||
|
|
per-screen resource database, the \*(xI 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.
|
||
|
|
.LP
|
||
|
|
The callout procedure provided by the application is of type
|
||
|
|
.PN XtLanguageProc .
|
||
|
|
.LP
|
||
|
|
.IN "XtLanguageProc" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
typedef String (*XtLanguageProc)(Display*, String, XtPointer);
|
||
|
|
.br
|
||
|
|
Display *\fIdisplay\fP;
|
||
|
|
.br
|
||
|
|
String \fIlanguage\fP;
|
||
|
|
.br
|
||
|
|
XtPointer \fIclient_data\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIdisplay\fP 1i
|
||
|
|
Passes the display.
|
||
|
|
.IP \fIlanguage\fP
|
||
|
|
Passes the initial language value obtained from the command line
|
||
|
|
or server per-display resource specifications.
|
||
|
|
.IP \fIclient_data\fP
|
||
|
|
Passes the additional client data specified in the call to
|
||
|
|
.PN XtSetLanguageProc .
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The language procedure allows an application to set the locale to
|
||
|
|
the value of the language resource determined by
|
||
|
|
.PN XtDisplayInitialize .
|
||
|
|
The function returns a new language string that
|
||
|
|
will be subsequently used by
|
||
|
|
.PN XtDisplayInitialize
|
||
|
|
to establish the path for loading resource files. The returned
|
||
|
|
string will be copied by the \*(xI into new memory.
|
||
|
|
.LP
|
||
|
|
Initially, no language procedure is set by the \*(xI.
|
||
|
|
To set the language procedure for use by
|
||
|
|
.PN XtDisplayInitialize ,
|
||
|
|
use
|
||
|
|
.PN XtSetLanguageProc .
|
||
|
|
.LP
|
||
|
|
.IN XtSetLanguageProc "" "@DEF@"
|
||
|
|
.IN "language procedure" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
XtLanguageProc XtSetLanguageProc(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP)
|
||
|
|
.br
|
||
|
|
XtAppContext \fIapp_context\fP;
|
||
|
|
.br
|
||
|
|
XtLanguageProc \fIproc\fP;
|
||
|
|
.br
|
||
|
|
XtPointer \fIclient_data\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIapp_context\fP 1i
|
||
|
|
Specifies the application context in which the language procedure is
|
||
|
|
to be used, or NULL.
|
||
|
|
.IP \fIproc\fP 1i
|
||
|
|
Specifies the language procedure.
|
||
|
|
.IP \fIclient_data\fP 1i
|
||
|
|
Specifies additional client data to be passed to the language
|
||
|
|
procedure when it is called.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
.PN XtSetLanguageProc
|
||
|
|
sets the language procedure that will be called from
|
||
|
|
.PN XtDisplayInitialize
|
||
|
|
for all subsequent Displays initialized in the specified application
|
||
|
|
context. If \fIapp_context\fP 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 \fIproc\fP is NULL, a default language procedure is
|
||
|
|
registered.
|
||
|
|
.PN XtSetLanguageProc
|
||
|
|
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
|
||
|
|
.PN XtSetLanguageProc ,
|
||
|
|
it will cause the default language procedure to be registered.
|
||
|
|
.LP
|
||
|
|
The default language procedure does the following:
|
||
|
|
.IP \(bu 5
|
||
|
|
Sets the locale according to the environment. On ANSI C-based
|
||
|
|
systems this is done by calling
|
||
|
|
.PN setlocale (
|
||
|
|
.PN LC_ALL ,
|
||
|
|
\fIlanguage\fP ).
|
||
|
|
If an error is encountered, a warning message is issued with
|
||
|
|
.PN XtWarning .
|
||
|
|
.IP \(bu 5
|
||
|
|
Calls
|
||
|
|
.PN XSupportsLocale
|
||
|
|
to verify that the current locale is supported.
|
||
|
|
If the locale is not supported, a warning message is issued with
|
||
|
|
.PN XtWarning
|
||
|
|
and the locale is set to ``C''.
|
||
|
|
.IP \(bu 5
|
||
|
|
Calls
|
||
|
|
.PN XSetLocaleModifiers
|
||
|
|
specifying the empty string.
|
||
|
|
.IP \(bu 5
|
||
|
|
Returns the value of the current locale. On ANSI C-based systems this
|
||
|
|
is the return value from a final call to
|
||
|
|
.PN setlocale (
|
||
|
|
.PN LC_ALL ,
|
||
|
|
NULL ).
|
||
|
|
.LP
|
||
|
|
A client wishing to use this mechanism to establish locale can do so
|
||
|
|
by calling
|
||
|
|
.PN XtSetLanguageProc
|
||
|
|
prior to
|
||
|
|
.PN XtDisplayInitialize ,
|
||
|
|
as in the following example.
|
||
|
|
.LP
|
||
|
|
.Ds 0
|
||
|
|
.TA .5i
|
||
|
|
Widget top;
|
||
|
|
XtSetLanguageProc(NULL, NULL, NULL);
|
||
|
|
top = XtOpenApplication(...);
|
||
|
|
...
|
||
|
|
.De
|
||
|
|
|
||
|
|
.NH 2
|
||
|
|
Loading the Resource Database
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Loading the Resource Database\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
The
|
||
|
|
.PN XtDisplayInitialize
|
||
|
|
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:
|
||
|
|
|
||
|
|
.IP \(bu 5
|
||
|
|
Application command line (\fIargc\fP, \fIargv\fP).
|
||
|
|
.IP \(bu 5
|
||
|
|
Per-host user environment resource file on the local host.
|
||
|
|
.IP \(bu 5
|
||
|
|
Per-screen resource specifications from the server.
|
||
|
|
.IP \(bu 5
|
||
|
|
Per-display resource specifications from the server or from
|
||
|
|
.br
|
||
|
|
the user preference file on the local host.
|
||
|
|
.IP \(bu 5
|
||
|
|
Application-specific user resource file on the local host.
|
||
|
|
.IP \(bu 5
|
||
|
|
Application-specific class resource file on the local host.
|
||
|
|
|
||
|
|
.LP
|
||
|
|
When the resource database for a particular screen on the display
|
||
|
|
is needed (either internally, or when
|
||
|
|
.PN XtScreenDatabase
|
||
|
|
is called),
|
||
|
|
it is created in the following manner using the sources listed
|
||
|
|
above in the same order:
|
||
|
|
|
||
|
|
.IP \(bu 5
|
||
|
|
A temporary database, the ``server resource database'', is
|
||
|
|
created from the string returned by
|
||
|
|
.PN XResourceManagerString
|
||
|
|
or, if
|
||
|
|
.PN XResourceManagerString
|
||
|
|
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/\fB.Xdefaults\fP.
|
||
|
|
.IN ".Xdefaults" "" "@DEF@"
|
||
|
|
|
||
|
|
.IP \(bu 5
|
||
|
|
If a language procedure has been set,
|
||
|
|
.PN XtDisplayInitialize
|
||
|
|
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,
|
||
|
|
.PN XtDisplayInitialize
|
||
|
|
queries the server resource database (which is assumed to be entirely
|
||
|
|
in XPCS) for the resource
|
||
|
|
\fIname\fP\fB.xnlLanguage\fP, class \fIClass\fP\fB.XnlLanguage\fP
|
||
|
|
where \fIname\fP
|
||
|
|
.IN "xnlLanguage" "" "@DEF@"
|
||
|
|
.IN "Resources" "xnlLanguage"
|
||
|
|
and \fIClass\fP are the \fIapplication_name\fP and
|
||
|
|
\fIapplication_class\fP specified to
|
||
|
|
.PN XtDisplayInitialize .
|
||
|
|
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 \*(xI that require the per-display language string.
|
||
|
|
|
||
|
|
.IP \(bu 5
|
||
|
|
The screen resource database is initialized by parsing the command
|
||
|
|
line in the manner specified by Section 2.4.
|
||
|
|
|
||
|
|
.IP \(bu 5
|
||
|
|
If a language procedure has not been set,
|
||
|
|
the initial database is then queried for the resource
|
||
|
|
\fIname\fP\fB.xnlLanguage\fP, class \fIClass\fP\fB.XnlLanguage\fP
|
||
|
|
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
|
||
|
|
.PN \s-1LANG\s+1
|
||
|
|
environment variable. If no language string is
|
||
|
|
found, the empty string is used.
|
||
|
|
This language string is saved for all future references in the \*(xI
|
||
|
|
that require the per-display language string.
|
||
|
|
|
||
|
|
.IP \(bu 5
|
||
|
|
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
|
||
|
|
.PN \s-1XENVIRONMENT\s+1
|
||
|
|
environment variable.
|
||
|
|
If this environment variable does not exist, the user's home directory
|
||
|
|
is searched for a file named
|
||
|
|
.PN \&.Xdefaults-\fIhost\fP ,
|
||
|
|
where \fIhost\fP is the host name of the machine on which the
|
||
|
|
application is running.
|
||
|
|
|
||
|
|
.IP \(bu 5
|
||
|
|
The per-screen resource specifications are then merged into the screen
|
||
|
|
resource database, if they exist. These specifications are the string
|
||
|
|
returned by
|
||
|
|
.PN XScreenResourceString
|
||
|
|
for the respective screen and are owned entirely by the user.
|
||
|
|
|
||
|
|
.IP \(bu 5
|
||
|
|
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.
|
||
|
|
|
||
|
|
.IP \(bu 5
|
||
|
|
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
|
||
|
|
.PN XrmSetDatabase
|
||
|
|
with the current screen resource database, after preserving the
|
||
|
|
original display-associated database, then calling
|
||
|
|
.PN XtResolvePathname
|
||
|
|
with the parameters
|
||
|
|
(\fIdisplay\fP, NULL, NULL, NULL, \fIpath\fP, NULL, 0, NULL),
|
||
|
|
where \fIpath\fP is defined in an operating-system-specific way.
|
||
|
|
On POSIX-based systems, \fIpath\fP is defined to be the value
|
||
|
|
of the environment variable
|
||
|
|
.PN \s-1XUSERFILESEARCHPATH\s+1
|
||
|
|
if this is defined. If
|
||
|
|
.PN \s-1XUSERFILESEARCHPATH\s+1
|
||
|
|
is not defined, an implementation-dependent default value is used.
|
||
|
|
This default value is constrained in the following manner:
|
||
|
|
|
||
|
|
.RS
|
||
|
|
.IP \- 3
|
||
|
|
If the environment variable
|
||
|
|
.PN \s-1XAPPLRESDIR\s+1
|
||
|
|
is not defined, the default
|
||
|
|
.PN \s-1XUSERFILESEARCHPATH\s+1
|
||
|
|
must contain at least six entries. These entries must contain
|
||
|
|
.IN "XUSERFILESEARCHPATH" "" "@DEF@"
|
||
|
|
.IN "XAPPLRESDIR" "" "@DEF@"
|
||
|
|
.IN "$HOME"
|
||
|
|
$HOME as the directory prefix, plus the following substitutions:
|
||
|
|
|
||
|
|
.nf
|
||
|
|
.ta .3i 1.5i 2i
|
||
|
|
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
|
||
|
|
.fi
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
.IP \- 3
|
||
|
|
If
|
||
|
|
.PN \s-1XAPPLRESDIR\s+1
|
||
|
|
is defined, the default
|
||
|
|
.PN \s-1XUSERFILESEARCHPATH\s+1
|
||
|
|
must contain at least seven entries. These entries must contain the
|
||
|
|
following directory prefixes and substitutions:
|
||
|
|
|
||
|
|
.ne 1.1
|
||
|
|
.nf
|
||
|
|
.ta .3i 1.6i 2.2i 3.3i 3.7i
|
||
|
|
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
|
||
|
|
.fi
|
||
|
|
|
||
|
|
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.
|
||
|
|
.RE
|
||
|
|
|
||
|
|
.IP \(bu 5
|
||
|
|
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
|
||
|
|
.PN XtResolvePathname
|
||
|
|
with the parameters
|
||
|
|
(\fIdisplay\fP, ``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
|
||
|
|
.PN XtAppSetFallbackResources .
|
||
|
|
Note that the customization substitution string is retrieved
|
||
|
|
dynamically by
|
||
|
|
.PN XtResolvePathname
|
||
|
|
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
|
||
|
|
.PN XtResolvePathname ,
|
||
|
|
the original display-associated database is restored.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
To obtain the resource database for a particular screen, use
|
||
|
|
.PN XtScreenDatabase .
|
||
|
|
.LP
|
||
|
|
.IN "XtScreenDatabase" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
XrmDatabase XtScreenDatabase(\fIscreen\fP)
|
||
|
|
.br
|
||
|
|
Screen *\fIscreen\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIscreen\fP 1i
|
||
|
|
Specifies the screen whose resource database is to be returned.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtScreenDatabase
|
||
|
|
function returns the fully merged resource database as specified above,
|
||
|
|
associated with the specified screen. If the specified \fIscreen\fP
|
||
|
|
does not belong to a
|
||
|
|
.PN Display
|
||
|
|
initialized by
|
||
|
|
.PN XtDisplayInitialize ,
|
||
|
|
the results are undefined.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
To obtain the default resource database associated with a particular display, use
|
||
|
|
.PN XtDatabase .
|
||
|
|
.LP
|
||
|
|
.IN "XtDatabase" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
XrmDatabase XtDatabase(\fIdisplay\fP)
|
||
|
|
.br
|
||
|
|
Display *\fIdisplay\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIdisplay\fP 1i
|
||
|
|
Specifies the display.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtDatabase
|
||
|
|
function is equivalent to
|
||
|
|
.PN XrmGetDatabase .
|
||
|
|
It returns the database associated with the specified display, or
|
||
|
|
NULL if a database has not been set.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
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
|
||
|
|
.PN XtAppSetFallbackResources .
|
||
|
|
.LP
|
||
|
|
.IN "XtAppSetFallbackResources" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
void XtAppSetFallbackResources(\fIapp_context\fP, \fIspecification_list\fP)
|
||
|
|
.br
|
||
|
|
XtAppContext \fIapp_context\fP;
|
||
|
|
.br
|
||
|
|
String *\fIspecification_list\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIapp_context\fP 1.25i
|
||
|
|
Specifies the application context in which
|
||
|
|
the fallback specifications will be used.
|
||
|
|
.IP \fIspecification_list\fP 1.25i
|
||
|
|
Specifies a NULL-terminated list of
|
||
|
|
resource specifications to preload
|
||
|
|
the database, or NULL.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
Each entry in \fIspecification_list\fP points to a string in the format of
|
||
|
|
.PN XrmPutLineResource .
|
||
|
|
Following a call to
|
||
|
|
.PN XtAppSetFallbackResources ,
|
||
|
|
when a resource database is being created for a particular screen and
|
||
|
|
the \*(xI are not able
|
||
|
|
to find or read an application-specific class resource file according to the
|
||
|
|
rules given above and if \fIspecification_list\fP is not NULL, the
|
||
|
|
resource specifications in \fIspecification_list\fP will be merged
|
||
|
|
into the screen resource database in place of the application-specific
|
||
|
|
class resource file.
|
||
|
|
.PN XtAppSetFallbackResources
|
||
|
|
is not
|
||
|
|
required to copy \fIspecification_list\fP; 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
|
||
|
|
.PN XtAppSetFallbackResources
|
||
|
|
is called again. The value NULL for
|
||
|
|
\fIspecification_list\fP 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.
|
||
|
|
|
||
|
|
.NH 2
|
||
|
|
Parsing the Command Line
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Parsing the Command Line\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
The
|
||
|
|
.PN XtOpenDisplay
|
||
|
|
function first parses the command line for the following options:
|
||
|
|
.IP \-display 1i
|
||
|
|
Specifies the display name for
|
||
|
|
.PN XOpenDisplay .
|
||
|
|
.IP \-name 1i
|
||
|
|
Sets the resource name prefix,
|
||
|
|
which overrides the application name passed to
|
||
|
|
.PN XtOpenDisplay .
|
||
|
|
.IP \-xnllanguage 1i
|
||
|
|
Specifies the initial language string for establishing locale
|
||
|
|
and for finding application class resource files.
|
||
|
|
.LP
|
||
|
|
.PN XtDisplayInitialize
|
||
|
|
has a table of standard command line options that are passed to
|
||
|
|
.PN XrmParseCommand
|
||
|
|
for adding resources to the resource database,
|
||
|
|
and it takes as a parameter additional
|
||
|
|
application-specific resource abbreviations.
|
||
|
|
.IN "XrmOptionDescRec" "" "@DEF@"
|
||
|
|
The format of this table is described in Section 15.9 in \fI\*(xL\fP.
|
||
|
|
.LP
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
.TA .5i 2.75i
|
||
|
|
.ta .5i 2.75i
|
||
|
|
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;
|
||
|
|
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The standard table contains the following entries:
|
||
|
|
.TS H
|
||
|
|
l l l l .
|
||
|
|
_
|
||
|
|
.sp 6p
|
||
|
|
.TH
|
||
|
|
Option String Resource Name Argument Kind Resource Value
|
||
|
|
.sp 6p
|
||
|
|
_
|
||
|
|
.sp 6p
|
||
|
|
\-background *background SepArg next argument
|
||
|
|
\-bd *borderColor SepArg next argument
|
||
|
|
\-bg *background SepArg next argument
|
||
|
|
\-borderwidth .borderWidth SepArg next argument
|
||
|
|
\-bordercolor *borderColor SepArg next argument
|
||
|
|
\-bw .borderWidth SepArg next argument
|
||
|
|
\-display .display SepArg next argument
|
||
|
|
\-fg *foreground SepArg next argument
|
||
|
|
\-fn *font SepArg next argument
|
||
|
|
\-font *font SepArg next argument
|
||
|
|
\-foreground *foreground SepArg next argument
|
||
|
|
\-geometry .geometry SepArg next argument
|
||
|
|
\-iconic .iconic NoArg ``true''
|
||
|
|
\-name .name SepArg next argument
|
||
|
|
\-reverse .reverseVideo NoArg ``on''
|
||
|
|
\-rv .reverseVideo NoArg ``on''
|
||
|
|
+rv .reverseVideo NoArg ``off''
|
||
|
|
\-selectionTimeout .selectionTimeout SepArg next argument
|
||
|
|
\-synchronous .synchronous NoArg ``on''
|
||
|
|
+synchronous .synchronous NoArg ``off''
|
||
|
|
\-title .title SepArg next argument
|
||
|
|
\-xnllanguage .xnlLanguage SepArg next argument
|
||
|
|
\-xrm next argument ResArg next argument
|
||
|
|
\-xtsessionID .sessionID SepArg next argument
|
||
|
|
.sp 6p
|
||
|
|
_
|
||
|
|
.TE
|
||
|
|
.LP
|
||
|
|
Note that any unique abbreviation for an option name in the standard table
|
||
|
|
or in the application table is accepted.
|
||
|
|
.LP
|
||
|
|
If reverseVideo is
|
||
|
|
.PN True ,
|
||
|
|
the values of
|
||
|
|
.PN XtDefaultForeground
|
||
|
|
and
|
||
|
|
.PN XtDefaultBackground
|
||
|
|
are exchanged for all screens on the Display.
|
||
|
|
.LP
|
||
|
|
.IN "synchronous" "" "@DEF@"
|
||
|
|
.IN "Resources" "synchronous"
|
||
|
|
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,
|
||
|
|
.PN XtDisplayInitialize
|
||
|
|
makes a call to
|
||
|
|
.PN XSynchronize
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
.IN "selectionTimeout" "" "@DEF@"
|
||
|
|
.IN "Resources" "selectionTimeout"
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
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
|
||
|
|
.PN xmh ,
|
||
|
|
you can start it up as
|
||
|
|
.LP
|
||
|
|
.Ds
|
||
|
|
xmh \-xrm 'xmh*Command.background: red'
|
||
|
|
.DE
|
||
|
|
.LP
|
||
|
|
When it parses the command line,
|
||
|
|
.PN XtDisplayInitialize
|
||
|
|
merges the application option table with the standard option table
|
||
|
|
before calling the Xlib
|
||
|
|
.PN XrmParseCommand
|
||
|
|
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 \*(xI reserve all option names
|
||
|
|
beginning with the characters ``-xt'' for future standard uses.
|
||
|
|
|
||
|
|
.NH 2
|
||
|
|
Creating Widgets
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Creating Widgets\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
The creation of widget instances is a three-phase process:
|
||
|
|
.IP 1. 5
|
||
|
|
The widgets are allocated and initialized with resources
|
||
|
|
and are optionally added to the managed subset of their parent.
|
||
|
|
.IP 2. 5
|
||
|
|
All composite widgets are notified of their managed children
|
||
|
|
in a bottom-up traversal of the widget tree.
|
||
|
|
.IP 3. 5
|
||
|
|
The widgets create X windows, which then are mapped.
|
||
|
|
.LP
|
||
|
|
.EQ
|
||
|
|
delim $$
|
||
|
|
.EN
|
||
|
|
To start the first phase,
|
||
|
|
the application calls
|
||
|
|
.PN XtCreateWidget
|
||
|
|
for all its widgets and adds some (usually, most or all) of its widgets
|
||
|
|
to their respective parents' managed set by calling
|
||
|
|
.PN XtManageChild .
|
||
|
|
To avoid an $O( n sup 2 )$ 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.
|
||
|
|
.EQ
|
||
|
|
delim off
|
||
|
|
.EN
|
||
|
|
.LP
|
||
|
|
After all widgets have been created,
|
||
|
|
the application calls
|
||
|
|
.PN XtRealizeWidget
|
||
|
|
with the top-level widget to execute the second and third phases.
|
||
|
|
.PN XtRealizeWidget
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
Finally,
|
||
|
|
.PN XtRealizeWidget
|
||
|
|
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.
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Creating and Merging Argument Lists
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Creating and Merging Argument Lists\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
Many \*(xI functions may be passed pairs of resource names and
|
||
|
|
values.
|
||
|
|
These are passed as an arglist, a pointer to an array of
|
||
|
|
.PN Arg
|
||
|
|
structures, which contains
|
||
|
|
.IN "ArgList" "" "@DEF@"
|
||
|
|
.IN "Arg" "" "@DEF@"
|
||
|
|
.LP
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
.TA .5i 3i
|
||
|
|
.ta .5i 3i
|
||
|
|
typedef struct {
|
||
|
|
String name;
|
||
|
|
XtArgVal value;
|
||
|
|
} Arg, *ArgList;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
where
|
||
|
|
.PN XtArgVal
|
||
|
|
is as defined in Section 1.5.
|
||
|
|
.LP
|
||
|
|
If the size of the resource is less than or equal to the size of an
|
||
|
|
.PN XtArgVal ,
|
||
|
|
the resource value is stored directly in \fIvalue\fP;
|
||
|
|
otherwise, a pointer to it is stored in \fIvalue\fP.
|
||
|
|
.LP
|
||
|
|
To set values in an
|
||
|
|
.PN ArgList ,
|
||
|
|
use
|
||
|
|
.PN XtSetArg .
|
||
|
|
.LP
|
||
|
|
.IN "XtSetArg" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
void XtSetArg(\fIarg\fP, \fIname\fP, \fIvalue\fP)
|
||
|
|
.br
|
||
|
|
Arg \fIarg\fP;
|
||
|
|
.br
|
||
|
|
String \fIname\fP;
|
||
|
|
.br
|
||
|
|
XtArgVal \fIvalue\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIarg\fP 1i
|
||
|
|
Specifies the \fIname/value\fP pair to set.
|
||
|
|
.IP \fIname\fP 1i
|
||
|
|
Specifies the name of the resource.
|
||
|
|
.IP \fIvalue\fP 1i
|
||
|
|
Specifies the value of the resource if it will fit in an
|
||
|
|
.PN XtArgVal ,
|
||
|
|
else the address.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtSetArg
|
||
|
|
function is usually used in a highly stylized manner to
|
||
|
|
minimize the probability of making a mistake; for example:
|
||
|
|
.LP
|
||
|
|
.Ds
|
||
|
|
.TA .5i 3i
|
||
|
|
.ta .5i 3i
|
||
|
|
Arg args[20];
|
||
|
|
int n;
|
||
|
|
|
||
|
|
n = 0;
|
||
|
|
XtSetArg(args[n], XtNheight, 100); n++;
|
||
|
|
XtSetArg(args[n], XtNwidth, 200); n++;
|
||
|
|
XtSetValues(widget, args, n);
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
Alternatively, an application can statically declare the argument list
|
||
|
|
and use
|
||
|
|
.PN XtNumber :
|
||
|
|
.LP
|
||
|
|
.Ds
|
||
|
|
.TA .5i 3i
|
||
|
|
.ta .5i 3i
|
||
|
|
static Args args[] = {
|
||
|
|
{XtNheight, (XtArgVal) 100},
|
||
|
|
{XtNwidth, (XtArgVal) 200},
|
||
|
|
};
|
||
|
|
XtSetValues(Widget, args, XtNumber(args));
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
Note that you should not use expressions with side effects such as
|
||
|
|
auto-increment or auto-decrement
|
||
|
|
within the first argument to
|
||
|
|
.PN XtSetArg .
|
||
|
|
.PN XtSetArg
|
||
|
|
can be implemented as a macro that evaluates the first argument twice.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
To merge two
|
||
|
|
arglist arrays, use
|
||
|
|
.PN XtMergeArgLists .
|
||
|
|
.LP
|
||
|
|
.IN "XtMergeArgLists" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
ArgList XtMergeArgLists(\fIargs1\fP, \fInum_args1\fP, \fIargs2\fP, \
|
||
|
|
\fInum_args2\fP)
|
||
|
|
.br
|
||
|
|
ArgList \fIargs1\fP;
|
||
|
|
.br
|
||
|
|
Cardinal \fInum_args1\fP;
|
||
|
|
.br
|
||
|
|
ArgList \fIargs2\fP;
|
||
|
|
.br
|
||
|
|
Cardinal \fInum_args2\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIargs1\fP 1i
|
||
|
|
Specifies the first argument list.
|
||
|
|
.IP \fInum_args1\fP 1i
|
||
|
|
Specifies the number of entries in the first argument list.
|
||
|
|
.IP \fIargs2\fP 1i
|
||
|
|
Specifies the second argument list.
|
||
|
|
.IP \fInum_args2\fP 1i
|
||
|
|
Specifies the number of entries in the second argument list.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtMergeArgLists
|
||
|
|
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
|
||
|
|
.PN XtFree .
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
.IN "varargs" "" "@DEF@"
|
||
|
|
All \*(xI interfaces that require
|
||
|
|
.PN ArgList
|
||
|
|
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
|
||
|
|
.PN ArgList
|
||
|
|
procedure; e.g.,
|
||
|
|
.PN XtVaCreateWidget .
|
||
|
|
Each procedure named \fBXtVa\fP\fIsomething\fP takes as its
|
||
|
|
last arguments, in place of the corresponding
|
||
|
|
.PN ArgList /
|
||
|
|
.PN Cardinal
|
||
|
|
parameters, a variable parameter list of resource name and
|
||
|
|
value pairs where each name is of type
|
||
|
|
.PN String
|
||
|
|
and each value is of type
|
||
|
|
.PN XtArgVal .
|
||
|
|
The end of the list is identified by a \fIname\fP 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
|
||
|
|
.PN ArgList
|
||
|
|
and varargs forms interchangeably.
|
||
|
|
.LP
|
||
|
|
Two special names are defined for use only in varargs lists:
|
||
|
|
.PN XtVaTypedArg
|
||
|
|
and
|
||
|
|
.PN XtVaNestedList .
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
.IN "XtVaTypedArg" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
#define XtVaTypedArg "XtVaTypedArg"
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
If the name
|
||
|
|
.PN XtVaTypedArg
|
||
|
|
is specified in place of a resource
|
||
|
|
name, then the following four arguments are interpreted as a
|
||
|
|
\fIname/type/value/size\fP tuple \fIwhere\fP name is of type
|
||
|
|
.PN String ,
|
||
|
|
\fItype\fP is of type
|
||
|
|
.PN String ,
|
||
|
|
\fIvalue\fP is of type
|
||
|
|
.PN XtArgVal ,
|
||
|
|
and \fIsize\fP is of type int. When a varargs list containing
|
||
|
|
.PN XtVaTypedArg
|
||
|
|
is processed, a resource type
|
||
|
|
conversion (see Section 9.6) is performed if necessary to convert the
|
||
|
|
value into the format required by the associated resource. If \fItype\fP is
|
||
|
|
XtRString, then \fIvalue\fP contains a pointer to the string and \fIsize\fP
|
||
|
|
contains the number of bytes allocated, including the trailing null
|
||
|
|
byte. If \fItype\fP is not XtRString, then \fIif\fP size is
|
||
|
|
less than or equal to
|
||
|
|
\fBsizeof\fP(\fBXtArgVal\fP), the value should be the data cast to the type
|
||
|
|
.PN XtArgVal ,
|
||
|
|
otherwise \fIvalue\fP 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.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
.IN "XtVaNestedList" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
#define XtVaNestedList "XtVaNestedList"
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
If the name
|
||
|
|
.PN XtVaNestedList
|
||
|
|
is specified in place of a resource name,
|
||
|
|
then the following argument is interpreted as an
|
||
|
|
.PN XtVarArgsList
|
||
|
|
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.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
To dynamically allocate a varargs list for use with
|
||
|
|
.PN XtVaNestedList
|
||
|
|
in multiple calls, use
|
||
|
|
.PN XtVaCreateArgsList .
|
||
|
|
.IN "XtVaCreateArgsList" "" "@DEF@"
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
typedef XtPointer XtVarArgsList;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.FD 0
|
||
|
|
XtVarArgsList XtVaCreateArgsList(\fIunused\fP, ...)
|
||
|
|
.br
|
||
|
|
XtPointer \fIunused\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIunused\fP 1i
|
||
|
|
This argument is not currently used and must be specified as NULL.
|
||
|
|
.IP ... 1i
|
||
|
|
Specifies a variable parameter list of resource
|
||
|
|
name and value pairs.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtVaCreateArgsList
|
||
|
|
function allocates memory and copies its arguments into a
|
||
|
|
single list pointer, which may be used with
|
||
|
|
.PN XtVaNestedList .
|
||
|
|
The end of
|
||
|
|
both lists is identified by a \fIname\fP entry containing NULL. Any entries
|
||
|
|
of type
|
||
|
|
.PN XtVaTypedArg
|
||
|
|
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
|
||
|
|
.PN XtFree
|
||
|
|
when no longer needed.
|
||
|
|
.LP
|
||
|
|
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.
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Creating a Widget Instance
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Creating a Widget Instance\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
To create an instance of a widget, use
|
||
|
|
.PN XtCreateWidget .
|
||
|
|
.LP
|
||
|
|
.IN "XtCreateWidget" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
Widget XtCreateWidget(\fIname\fP, \fIobject_class\fP, \fIparent\fP, \
|
||
|
|
\fIargs\fP, \fInum_args\fP)
|
||
|
|
.br
|
||
|
|
String \fIname\fP;
|
||
|
|
.br
|
||
|
|
WidgetClass \fIobject_class\fP;
|
||
|
|
.br
|
||
|
|
Widget \fIparent\fP;
|
||
|
|
.br
|
||
|
|
ArgList \fIargs\fP;
|
||
|
|
.br
|
||
|
|
Cardinal \fInum_args\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIname\fP 1i
|
||
|
|
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.
|
||
|
|
.IP \fIobject_class\fP 1i
|
||
|
|
Specifies the widget class pointer for the created object. \*(oC
|
||
|
|
.IP \fIparent\fP 1i
|
||
|
|
Specifies the parent widget. \*(oI
|
||
|
|
.IP \fIargs\fP 1i
|
||
|
|
Specifies the argument list to override any other resource specifications.
|
||
|
|
.IP \fInum_args\fP 1i
|
||
|
|
Specifies the number of entries in the argument list.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtCreateWidget
|
||
|
|
function performs all the boilerplate operations of widget
|
||
|
|
creation, doing the following in order:
|
||
|
|
.IP \(bu 5
|
||
|
|
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.
|
||
|
|
.IP \(bu 5
|
||
|
|
If the specified class is not
|
||
|
|
.PN coreWidgetClass
|
||
|
|
or a subclass thereof,
|
||
|
|
and the parent's class is a subclass of
|
||
|
|
.PN compositeWidgetClass
|
||
|
|
and either no extension record in
|
||
|
|
the parent's composite class part extension field exists with the
|
||
|
|
\fIrecord_type\fP
|
||
|
|
.PN \s-1NULLQUARK\s+1
|
||
|
|
or the \fIaccepts_objects\fP field in the extension
|
||
|
|
record is
|
||
|
|
.PN False ,
|
||
|
|
.PN XtCreateWidget
|
||
|
|
issues a fatal error; see Section 3.1 and Chapter 12.
|
||
|
|
.IP \(bu 5
|
||
|
|
If the specified class contains an extension record in the object class
|
||
|
|
part \fIextension\fP field with \fIrecord_type\fP
|
||
|
|
.PN \s-1NULLQUARK\s+1
|
||
|
|
and the \fIallocate\fP field is not NULL,
|
||
|
|
the procedure is invoked to allocate memory
|
||
|
|
for the widget instance. If the parent is a member of the class
|
||
|
|
.PN constraintWidgetClass ,
|
||
|
|
the procedure also allocates memory for the
|
||
|
|
parent's constraints and stores the address of this memory into the
|
||
|
|
\fIconstraints\fP field. If no allocate procedure is found, the \*(xI
|
||
|
|
allocate memory for the widget and, when applicable, the constraints,
|
||
|
|
and initializes the \fIconstraints\fP field.
|
||
|
|
.IP \(bu 5
|
||
|
|
Initializes the Core nonresource data fields
|
||
|
|
\fIself\fP, \fIparent\fP, \fIwidget_class\fP, \fIbeing_destroyed\fP,
|
||
|
|
\fIname\fP, \fImanaged\fP, \fIwindow\fP, \fIvisible\fP,
|
||
|
|
\fIpopup_list\fP, and \fInum_popups\fP.
|
||
|
|
.IP \(bu 5
|
||
|
|
Initializes the resource fields (for example, \fIbackground_pixel\fP)
|
||
|
|
by using the
|
||
|
|
.PN CoreClassPart
|
||
|
|
resource lists specified for this class and all superclasses.
|
||
|
|
.IP \(bu 5
|
||
|
|
If the parent is a member of the class
|
||
|
|
.PN constraintWidgetClass ,
|
||
|
|
initializes the resource fields of the constraints record
|
||
|
|
by using the
|
||
|
|
.PN ConstraintClassPart
|
||
|
|
resource lists specified for the parent's class
|
||
|
|
and all superclasses up to
|
||
|
|
.PN constraintWidgetClass .
|
||
|
|
.IP \(bu 5
|
||
|
|
Calls the initialize procedures for the widget starting at the
|
||
|
|
Object
|
||
|
|
initialize procedure on down to the widget's initialize procedure.
|
||
|
|
.IP \(bu 5
|
||
|
|
If the parent is a member of the class
|
||
|
|
.PN constraintWidgetClass ,
|
||
|
|
calls the
|
||
|
|
.PN ConstraintClassPart
|
||
|
|
initialize procedures,
|
||
|
|
starting at
|
||
|
|
.PN constraintWidgetClass
|
||
|
|
on down to the parent's
|
||
|
|
.PN ConstraintClassPart
|
||
|
|
initialize procedure.
|
||
|
|
.IP \(bu 5
|
||
|
|
If the parent is a member of the class
|
||
|
|
.PN compositeWidgetClass ,
|
||
|
|
puts the widget into its parent's children list by calling its parent's
|
||
|
|
insert_child procedure.
|
||
|
|
For further information,
|
||
|
|
see Section 3.1.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
To create an instance of a widget using varargs lists, use
|
||
|
|
.PN XtVaCreateWidget .
|
||
|
|
.LP
|
||
|
|
.IN "XtVaCreateWidget" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
Widget XtVaCreateWidget(\fIname\fP, \fIobject_class\fP, \fIparent\fP, ...)
|
||
|
|
.br
|
||
|
|
String \fIname\fP;
|
||
|
|
.br
|
||
|
|
WidgetClass \fIobject_class\fP;
|
||
|
|
.br
|
||
|
|
Widget \fIparent\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIname\fP 1i
|
||
|
|
Specifies the resource name for the created widget.
|
||
|
|
.IP \fIobject_class\fP 1i
|
||
|
|
Specifies the widget class pointer for the created object. \*(oC
|
||
|
|
.IP \fIparent\fP 1i
|
||
|
|
Specifies the parent widget. \*(oI
|
||
|
|
.IP ... 1i
|
||
|
|
Specifies the variable argument list to override any other
|
||
|
|
resource specifications.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtVaCreateWidget
|
||
|
|
procedure is identical in function to
|
||
|
|
.PN XtCreateWidget
|
||
|
|
with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list,
|
||
|
|
as described
|
||
|
|
in Section 2.5.1.
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Creating an Application Shell Instance
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Creating an Application Shell Instance\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
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
|
||
|
|
.PN XtAppCreateShell
|
||
|
|
to create independent widget trees.
|
||
|
|
.LP
|
||
|
|
.IN "XtAppCreateShell" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
Widget XtAppCreateShell(\fIname\fP, \
|
||
|
|
\fIapplication_class\fP, \fIwidget_class\fP, \fIdisplay\fP, \
|
||
|
|
\fIargs\fP, \fInum_args\fP)
|
||
|
|
.br
|
||
|
|
String \fIname\fP;
|
||
|
|
.br
|
||
|
|
String \fIapplication_class\fP;
|
||
|
|
.br
|
||
|
|
WidgetClass \fIwidget_class\fP;
|
||
|
|
.br
|
||
|
|
Display *\fIdisplay\fP;
|
||
|
|
.br
|
||
|
|
ArgList \fIargs\fP;
|
||
|
|
.br
|
||
|
|
Cardinal \fInum_args\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIname\fP 1.25i
|
||
|
|
Specifies the instance name of the shell widget.
|
||
|
|
If \fIname\fP is NULL,
|
||
|
|
the application name passed to
|
||
|
|
.PN XtDisplayInitialize
|
||
|
|
is used.
|
||
|
|
.IP \fIapplication_class\fP 1.25i
|
||
|
|
Specifies the resource class string to be used in
|
||
|
|
place of the widget \fIclass_name\fP string when
|
||
|
|
\fIwidget_class\fP is
|
||
|
|
.PN applicationShellWidgetClass
|
||
|
|
or a subclass thereof.
|
||
|
|
.IP \fIwidget_class\fP 1.25i
|
||
|
|
Specifies the widget class for the top-level widget (e.g.,
|
||
|
|
.PN applicationShellWidgetClass ).
|
||
|
|
.IP \fIdisplay\fP 1.25i
|
||
|
|
Specifies the display for the default screen
|
||
|
|
and for the resource database used to retrieve
|
||
|
|
the shell widget resources.
|
||
|
|
.IP \fIargs\fP 1.25i
|
||
|
|
Specifies the argument list to override any other resource specifications.
|
||
|
|
.IP \fInum_args\fP 1.25i
|
||
|
|
Specifies the number of entries in the argument list.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtAppCreateShell
|
||
|
|
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
|
||
|
|
\fIargs\fP 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 \fIname\fP.screen,
|
||
|
|
class \fIClass\fP.Screen where \fIClass\fP is the specified
|
||
|
|
\fIapplication_class\fP if \fIwidget_class\fP is
|
||
|
|
.PN applicationShellWidgetClass
|
||
|
|
or a subclass thereof. If \fIwidget_class\fP is not
|
||
|
|
.PN application\%Shell\%Widget\%Class
|
||
|
|
or a subclass, \fIClass\fP is the \fIclass_name\fP
|
||
|
|
field from the
|
||
|
|
.PN CoreClassPart
|
||
|
|
of the specified \fIwidget_class\fP.
|
||
|
|
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
|
||
|
|
\fIargs\fP. The widget name and \fIClass\fP as determined above are
|
||
|
|
used as the leftmost (i.e., root) components in all fully qualified
|
||
|
|
resource names for objects within this widget tree.
|
||
|
|
|
||
|
|
.LP
|
||
|
|
If the specified widget class is a subclass of WMShell, the name and
|
||
|
|
\fIClass\fP as determined above will be stored into the
|
||
|
|
.PN \s-1WM_CLASS\s+1
|
||
|
|
property on the widget's window when it becomes realized.
|
||
|
|
If the specified \fIwidget_class\fP is
|
||
|
|
.PN applicationShellWidgetClass
|
||
|
|
or a subclass thereof, the
|
||
|
|
.PN \s-1WM_COMMAND\s+1
|
||
|
|
property will also be set from the values of the XtNargv and
|
||
|
|
XtNargc resources.
|
||
|
|
|
||
|
|
.LP
|
||
|
|
To create multiple top-level shells within a single (logical)
|
||
|
|
application,
|
||
|
|
you can use one of two methods:
|
||
|
|
.IP \(bu 5
|
||
|
|
Designate one shell as the real top-level shell and
|
||
|
|
create the others as pop-up children of it by using
|
||
|
|
.PN XtCreatePopupShell .
|
||
|
|
.IP \(bu 5
|
||
|
|
Have all shells as pop-up children of an unrealized top-level shell.
|
||
|
|
.LP
|
||
|
|
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:
|
||
|
|
.LP
|
||
|
|
.Ds
|
||
|
|
.TA 2i
|
||
|
|
.ta 2i
|
||
|
|
xmail.geometry:... (the main window)
|
||
|
|
xmail.read.geometry:... (the read window)
|
||
|
|
xmail.compose.geometry:... (the compose window)
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
The second method,
|
||
|
|
which is best if there is no main window,
|
||
|
|
leads to resource specifications like the following:
|
||
|
|
.LP
|
||
|
|
.Ds
|
||
|
|
.TA 2i
|
||
|
|
.ta 2i
|
||
|
|
xmail.headers.geometry:... (the headers window)
|
||
|
|
xmail.read.geometry:... (the read window)
|
||
|
|
xmail.compose.geometry:... (the compose window)
|
||
|
|
.De
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
To create a top-level widget that is the root of a widget tree using
|
||
|
|
varargs lists, use
|
||
|
|
.PN XtVaAppCreateShell .
|
||
|
|
.LP
|
||
|
|
.IN "XtVaAppCreateShell" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
Widget XtVaAppCreateShell(\fIname\fP, \fIapplication_class\fP, \
|
||
|
|
\fIwidget_class\fP, \fIdisplay\fP, ...)
|
||
|
|
.br
|
||
|
|
String \fIname\fP;
|
||
|
|
.br
|
||
|
|
String \fIapplication_class\fP;
|
||
|
|
.br
|
||
|
|
WidgetClass \fIwidget_class\fP;
|
||
|
|
.br
|
||
|
|
Display *\fIdisplay\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIname\fP 1.5i
|
||
|
|
Specifies the instance name of the shell widget.
|
||
|
|
If \fIname\fP is NULL,
|
||
|
|
the application name passed to
|
||
|
|
.PN XtDisplayInitialize
|
||
|
|
is used.
|
||
|
|
.IP \fIapplication_class\fP 1.5i
|
||
|
|
Specifies the resource class string to be used in
|
||
|
|
place of the widget \fIclass_name\fP string when
|
||
|
|
\fIwidget_class\fP is
|
||
|
|
.PN applicationShellWidgetClass
|
||
|
|
or a subclass thereof.
|
||
|
|
.IP \fIwidget_class\fP 1.5i
|
||
|
|
Specifies the widget class for the top-level widget.
|
||
|
|
.IP \fIdisplay\fP 1.5i
|
||
|
|
Specifies the display for the default screen
|
||
|
|
and for the resource database used to retrieve
|
||
|
|
the shell widget resources.
|
||
|
|
.IP ... 1.5i
|
||
|
|
Specifies the variable argument list to override any other
|
||
|
|
resource specifications.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtVaAppCreateShell
|
||
|
|
procedure is identical in function to
|
||
|
|
.PN XtAppCreateShell
|
||
|
|
with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as
|
||
|
|
described in Section 2.5.1.
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Convenience Procedure to Initialize an Application
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Convenience Procedure to Initialize an Application\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
To initialize the \*(xI internals, create an application context,
|
||
|
|
open and initialize a display, and create the initial root shell
|
||
|
|
instance, an application may use
|
||
|
|
.PN XtOpenApplication
|
||
|
|
or
|
||
|
|
.PN XtVaOpenApplication .
|
||
|
|
.LP
|
||
|
|
.IN "XtOpenApplication" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
Widget XtOpenApplication(\fIapp_context_return\fP, \fIapplication_class\fP, \
|
||
|
|
\fIoptions\fP, \fInum_options\fP,
|
||
|
|
.br
|
||
|
|
\fIargc_in_out\fP, \fIargv_in_out\fP, \
|
||
|
|
\fIfallback_resources\fP, \fIwidget_class\fP, \fIargs\fP, \fInum_args\fP)
|
||
|
|
.br
|
||
|
|
XtAppContext *\fIapp_context_return\fP;
|
||
|
|
.br
|
||
|
|
String \fIapplication_class\fP;
|
||
|
|
.br
|
||
|
|
XrmOptionDescList \fIoptions\fP;
|
||
|
|
.br
|
||
|
|
Cardinal \fInum_options\fP;
|
||
|
|
.br
|
||
|
|
int *\fIargc_in_out\fP;
|
||
|
|
.br
|
||
|
|
String *\fIargv_in_out\fP;
|
||
|
|
.br
|
||
|
|
String *\fIfallback_resources\fP;
|
||
|
|
.br
|
||
|
|
WidgetClass \fIwidget_class\fP;
|
||
|
|
.br
|
||
|
|
ArgList \fIargs\fP;
|
||
|
|
.br
|
||
|
|
Cardinal \fInum_args\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIapp_context_return\fP 1.5i
|
||
|
|
Returns the application context, if non-NULL.
|
||
|
|
.IP \fIapplication_class\fP 1.5i
|
||
|
|
Specifies the class name of the application.
|
||
|
|
.IP \fIoptions\fP 1.5i
|
||
|
|
Specifies the command line options table.
|
||
|
|
.IP \fInum_options\fP 1.5i
|
||
|
|
Specifies the number of entries in \fIoptions\fP.
|
||
|
|
.IP \fIargc_in_out\fP 1.5i
|
||
|
|
Specifies a pointer to the number of command line arguments.
|
||
|
|
.IP \fIargv_in_out\fP 1.5i
|
||
|
|
Specifies a pointer to the command line arguments.
|
||
|
|
.IP \fIfallback_resources\fP 1.5i
|
||
|
|
Specifies resource values to be used if the application class resource
|
||
|
|
file cannot be opened or read, or NULL.
|
||
|
|
.IP \fIwidget_class\fP 1.5i
|
||
|
|
Specifies the class of the widget to be created. Must be shellWidgetClass
|
||
|
|
or a subclass.
|
||
|
|
.br
|
||
|
|
.IP \fIargs\fP 1.5i
|
||
|
|
Specifies the argument list to override any
|
||
|
|
other resource specifications for the created shell widget.
|
||
|
|
.IP \fInum_args\fP 1.5i
|
||
|
|
Specifies the number of entries in the argument list.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtOpenApplication
|
||
|
|
function calls
|
||
|
|
.PN XtToolkitInitialize
|
||
|
|
followed by
|
||
|
|
.PN XtCreateApplicationContext ,
|
||
|
|
then calls
|
||
|
|
.PN XtOpenDisplay
|
||
|
|
with \fIdisplay_string\fP NULL and
|
||
|
|
\fIapplication_name\fP NULL, and finally calls
|
||
|
|
.PN XtAppCreateShell
|
||
|
|
with \fIname\fP NULL, the specified \fIwidget_class\fP,
|
||
|
|
an argument list and count,
|
||
|
|
and returns the created shell.
|
||
|
|
The recommended \fIwidget_class\fP is
|
||
|
|
.PN sessionShellWidgetClass .
|
||
|
|
The argument list and count are created by merging
|
||
|
|
the specified \fIargs\fP and \fInum_args\fP with a list
|
||
|
|
containing the specified \fIargc\fP and \fIargv\fP.
|
||
|
|
The modified \fIargc\fP and \fIargv\fP returned by
|
||
|
|
.PN XtDisplayInitialize
|
||
|
|
are returned in \fIargc_in_out\fP and \fIargv_in_out\fP. If
|
||
|
|
\fIapp_context_return\fP 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
|
||
|
|
.PN XtOpenApplication
|
||
|
|
terminates the application. If \fIfallback_resources\fP is non-NULL,
|
||
|
|
.PN XtAppSetFallbackResources
|
||
|
|
is called with the value prior to calling
|
||
|
|
.PN XtOpenDisplay .
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
.IN "XtVaOpenApplication" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
Widget XtVaOpenApplication(\fIapp_context_return\fP, \fIapplication_class\fP, \
|
||
|
|
\fIoptions\fP, \fInum_options\fP,
|
||
|
|
.br
|
||
|
|
\fIargc_in_out\fP, \fIargv_in_out\fP, \
|
||
|
|
\fIfallback_resources\fP, \fIwidget_class\fP, ...)
|
||
|
|
.br
|
||
|
|
XtAppContext *\fIapp_context_return\fP;
|
||
|
|
.br
|
||
|
|
String \fIapplication_class\fP;
|
||
|
|
.br
|
||
|
|
XrmOptionDescList \fIoptions\fP;
|
||
|
|
.br
|
||
|
|
Cardinal \fInum_options\fP;
|
||
|
|
.br
|
||
|
|
int *\fIargc_in_out\fP;
|
||
|
|
.br
|
||
|
|
String *\fIargv_in_out\fP;
|
||
|
|
.br
|
||
|
|
String *\fIfallback_resources\fP;
|
||
|
|
.br
|
||
|
|
WidgetClass \fIwidget_class\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIapp_context_return\fP 1.5i
|
||
|
|
Returns the application context, if non-NULL.
|
||
|
|
.IP \fIapplication_class\fP 1.5i
|
||
|
|
Specifies the class name of the application.
|
||
|
|
.IP \fIoptions\fP 1.5i
|
||
|
|
Specifies the command line options table.
|
||
|
|
.IP \fInum_options\fP 1.5i
|
||
|
|
Specifies the number of entries in \fIoptions\fP.
|
||
|
|
.IP \fIargc_in_out\fP 1.5i
|
||
|
|
Specifies a pointer to the number of command line arguments.
|
||
|
|
.IP \fIargv_in_out\fP 1.5i
|
||
|
|
Specifies the command line arguments array.
|
||
|
|
.IP \fIfallback_resources\fP 1.5i
|
||
|
|
Specifies resource values to be used if the application class
|
||
|
|
resource file cannot be opened, or NULL.
|
||
|
|
.IP \fIwidget_class\fP 1.5i
|
||
|
|
Specifies the class of the widget to be created. Must be shellWidgetClass
|
||
|
|
or a subclass.
|
||
|
|
.IP ... 1.5i
|
||
|
|
Specifies the variable argument list to override any other
|
||
|
|
resource specifications for the created shell.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtVaOpenApplication
|
||
|
|
procedure is identical in function to
|
||
|
|
.PN XtOpenApplication
|
||
|
|
with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list,
|
||
|
|
as described
|
||
|
|
in Section 2.5.1.
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Widget Instance Allocation: The allocate Procedure
|
||
|
|
.XS
|
||
|
|
\*(SN Widget Instance Allocation: The allocate Procedure
|
||
|
|
.XE
|
||
|
|
.IN "Widget Allocation"
|
||
|
|
.LP
|
||
|
|
A widget class may optionally provide an instance allocation procedure
|
||
|
|
in the
|
||
|
|
.PN ObjectClassExtension
|
||
|
|
record.
|
||
|
|
.LP
|
||
|
|
When the call to create a widget includes a varargs list containing
|
||
|
|
.PN XtVaTypedArg ,
|
||
|
|
these arguments will be passed to the allocation procedure in an
|
||
|
|
.PN XtTypedArgList .
|
||
|
|
.LP
|
||
|
|
.IN "XtTypedArgList" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.Ds 0
|
||
|
|
.TA .5i 3i
|
||
|
|
.ta .5i 3i
|
||
|
|
typedef struct {
|
||
|
|
String name;
|
||
|
|
String type;
|
||
|
|
XtArgVal value;
|
||
|
|
int size;
|
||
|
|
} XtTypedArg, *XtTypedArgList;
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
.IN "allocate procedure" "" "@DEF@"
|
||
|
|
The allocate procedure pointer in the
|
||
|
|
.PN ObjectClassExtension
|
||
|
|
record is of type
|
||
|
|
.PN XtAllocateProc .
|
||
|
|
.LP
|
||
|
|
.IN "XtAllocateProc" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
typedef void (*XtAllocateProc)(WidgetClass, Cardinal*, Cardinal*, ArgList, \
|
||
|
|
Cardinal*,
|
||
|
|
XtTypedArgList, Cardinal*, \
|
||
|
|
Widget*, XtPointer*);
|
||
|
|
.br
|
||
|
|
WidgetClass \fIwidget_class\fP;
|
||
|
|
.br
|
||
|
|
Cardinal* \fIconstraint_size\fP;
|
||
|
|
.br
|
||
|
|
Cardinal* \fImore_bytes\fP;
|
||
|
|
.br
|
||
|
|
ArgList \fIargs\fP;
|
||
|
|
.br
|
||
|
|
Cardinal* \fInum_args\fP;
|
||
|
|
.br
|
||
|
|
XtTypedArgList \fItyped_args\fP,
|
||
|
|
.br
|
||
|
|
Cardinal* \fInum_typed_args\fP;
|
||
|
|
.br
|
||
|
|
Widget* \fInew_return\fP;
|
||
|
|
.br
|
||
|
|
XtPointer* \fImore_bytes_return\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIwidget_class\fP 1.5i
|
||
|
|
Specifies the widget class of the instance to allocate.
|
||
|
|
.IP \fIconstraint_size\fP 1.5i
|
||
|
|
Specifies the size of the constraint record to allocate, or 0.
|
||
|
|
.IP \fImore_bytes\fP 1.5i
|
||
|
|
Specifies the number of auxiliary bytes of memory to allocate.
|
||
|
|
.IP \fIargs\fP 1.5i
|
||
|
|
Specifies the argument list as given in the call to create the widget.
|
||
|
|
.IP \fInum_args\fP 1.5i
|
||
|
|
Specifies the number of arguments.
|
||
|
|
.IP \fItyped_args\fP 1.5i
|
||
|
|
Specifies the list of typed arguments given in the call to create the widget.
|
||
|
|
.IP \fInum_typed_args\fP 1.5i
|
||
|
|
Specifies the number of typed arguments.
|
||
|
|
.IP \fInew_return\fP 1.5i
|
||
|
|
Returns a pointer to the newly allocated instance, or NULL in case of error.
|
||
|
|
.IP \fImore_bytes_return\fP 1.5i
|
||
|
|
Returns the auxiliary memory if it was requested, or NULL
|
||
|
|
if requested and an error occurred; otherwise, unchanged.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
At widget allocation time, if an extension record with \fIrecord_type\fP
|
||
|
|
equal to
|
||
|
|
.PN \s-1NULLQUARK\s+1
|
||
|
|
is located through the object class part \fIextension\fP field
|
||
|
|
and the \fIallocate\fP field is not NULL, the
|
||
|
|
.PN XtAllocateProc
|
||
|
|
will be invoked to allocate memory for the widget. If no ObjectClassPart
|
||
|
|
extension record is declared with \fIrecord_type equal\fP to
|
||
|
|
.PN \s-1NULLQUARK\s+1 ,
|
||
|
|
then
|
||
|
|
.PN XtInheritAllocate
|
||
|
|
and
|
||
|
|
.PN XtInheritDeallocate
|
||
|
|
are assumed.
|
||
|
|
If no
|
||
|
|
.PN XtAllocateProc
|
||
|
|
is found, the \*(xI will allocate memory for the widget.
|
||
|
|
.LP
|
||
|
|
An
|
||
|
|
.PN XtAllocateProc
|
||
|
|
must perform the following:
|
||
|
|
.IP \(bu 5
|
||
|
|
Allocate memory for the widget instance and return it in \fInew_return\fP.
|
||
|
|
The memory must be at least \fIwc->core_class.widget_size\fP bytes in length,
|
||
|
|
double-word aligned.
|
||
|
|
.IP \(bu 5
|
||
|
|
Initialize the \fIcore.constraints\fP field in the instance record to NULL
|
||
|
|
or to point to a constraint record. If \fIconstraint_size\fP
|
||
|
|
is not 0, the procedure must allocate memory for the constraint record.
|
||
|
|
The memory must be double-word aligned.
|
||
|
|
.IP \(bu 5
|
||
|
|
If \fImore_bytes\fP is not 0, then the address of a block of memory
|
||
|
|
at least \fImore_bytes\fP in size, double-word aligned, must be
|
||
|
|
returned in the \fImore_bytes_return\fP parameter,
|
||
|
|
or NULL to indicate an error.
|
||
|
|
.LP
|
||
|
|
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.
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Widget Instance Initialization: The initialize Procedure
|
||
|
|
.XS
|
||
|
|
\*(SN Widget Instance Initialization: The initialize Procedure
|
||
|
|
.XE
|
||
|
|
.IN "Initialization"
|
||
|
|
.IN "Chaining"
|
||
|
|
.IN "Superclass Chaining"
|
||
|
|
.IN "Inheritance"
|
||
|
|
.LP
|
||
|
|
The initialize procedure pointer in a widget class is of type
|
||
|
|
.PN XtInitProc .
|
||
|
|
.LP
|
||
|
|
.IN "XtInitProc" "" "@DEF@"
|
||
|
|
.IN "initialize procedure" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
typedef void (*XtInitProc)(Widget, Widget, ArgList, Cardinal*);
|
||
|
|
.br
|
||
|
|
Widget \fIrequest\fP;
|
||
|
|
.br
|
||
|
|
Widget \fInew\fP;
|
||
|
|
.br
|
||
|
|
ArgList \fIargs\fP;
|
||
|
|
.br
|
||
|
|
Cardinal *\fInum_args\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIrequest\fP 1i
|
||
|
|
Specifies a copy of the widget with resource values as requested by the
|
||
|
|
argument list, the resource database, and the widget defaults.
|
||
|
|
.IP \fInew\fP 1i
|
||
|
|
Specifies the widget with the new values, both resource and nonresource,
|
||
|
|
that are actually allowed.
|
||
|
|
.IP \fIargs\fP 1i
|
||
|
|
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
|
||
|
|
.PN XtVaTypedArg
|
||
|
|
are converted to the widget representation and the list is transformed
|
||
|
|
into the
|
||
|
|
.PN ArgList
|
||
|
|
format.
|
||
|
|
.IP \fInum_args\fP 1i
|
||
|
|
Specifies the number of entries in the argument list.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
An initialization procedure performs the following:
|
||
|
|
.IP \(bu 5
|
||
|
|
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
|
||
|
|
.PN String ,
|
||
|
|
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.
|
||
|
|
.NT
|
||
|
|
It is not necessary to allocate space for or to copy callback lists.
|
||
|
|
.NE
|
||
|
|
.IP \(bu 5
|
||
|
|
Computes values for unspecified resource fields.
|
||
|
|
For example, if \fIwidth\fP and \fIheight\fP are zero,
|
||
|
|
the widget should compute an appropriate width and height
|
||
|
|
based on its other resources.
|
||
|
|
.NT
|
||
|
|
A widget may directly assign only
|
||
|
|
its own \fIwidth\fP and \fIheight\fP within the initialize, initialize_hook,
|
||
|
|
set_values, and
|
||
|
|
set_values_hook procedures; see Chapter 6.
|
||
|
|
.NE
|
||
|
|
.IP \(bu 5
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
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
|
||
|
|
\fIargs\fP and \fInum_args\fP
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
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 \fIinitialize\fP field in the class record.
|
||
|
|
.LP
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
The \fIrequest\fP and \fInew\fP 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 \fIrequest\fP widget is a copy of the widget as initialized by the
|
||
|
|
arglist and resource database.
|
||
|
|
The \fInew\fP 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.
|
||
|
|
.LP
|
||
|
|
In the above example,
|
||
|
|
the subclass with the visual surround can see
|
||
|
|
if the \fIwidth\fP and \fIheight\fP in the \fIrequest\fP widget are zero.
|
||
|
|
If so,
|
||
|
|
it adds its surround size to the \fIwidth\fP and \fIheight\fP
|
||
|
|
fields in the \fInew\fP widget.
|
||
|
|
If not, it must make do with the size originally specified.
|
||
|
|
.LP
|
||
|
|
The \fInew\fP widget will become the actual widget instance record.
|
||
|
|
Therefore,
|
||
|
|
the initialization procedure should do all its work on the \fInew\fP widget;
|
||
|
|
the \fIrequest\fP widget should never be modified.
|
||
|
|
If the initialize procedure
|
||
|
|
needs to call any routines that operate on a widget,
|
||
|
|
it should specify \fInew\fP as the widget instance.
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Constraint Instance Initialization: The ConstraintClassPart initialize Procedure
|
||
|
|
.XS
|
||
|
|
\*(SN Constraint Instance Initialization: The ConstraintClassPart initialize Procedure
|
||
|
|
.XE
|
||
|
|
.IN "Initialization"
|
||
|
|
.IN "XtInitProc"
|
||
|
|
.IN "initialize procedure"
|
||
|
|
.IN "Chaining"
|
||
|
|
.IN "Superclass Chaining"
|
||
|
|
.IN "Inheritance"
|
||
|
|
.LP
|
||
|
|
The constraint initialization procedure pointer, found in the
|
||
|
|
.PN ConstraintClassPart
|
||
|
|
\fIinitialize\fP field of the widget class record, is of type
|
||
|
|
.PN XtInitProc .
|
||
|
|
The values passed to the parent constraint initialization procedures
|
||
|
|
are the same as those passed to the child's class widget initialization
|
||
|
|
procedures.
|
||
|
|
.LP
|
||
|
|
The \fIconstraints\fP field of the \fIrequest\fP widget points to a copy of the
|
||
|
|
constraints record as initialized by the arglist and resource database.
|
||
|
|
.LP
|
||
|
|
The constraint initialization procedure should compute any constraint fields
|
||
|
|
derived from constraint resources.
|
||
|
|
It can make further changes to the \fInew\fP widget to make the widget
|
||
|
|
and any other constraint fields
|
||
|
|
conform to the specified constraints, for example,
|
||
|
|
changing the widget's size or position.
|
||
|
|
.LP
|
||
|
|
If a constraint class does not need a constraint initialization procedure,
|
||
|
|
it can specify NULL for the \fIinitialize\fP field of the
|
||
|
|
.PN ConstraintClassPart
|
||
|
|
in the class record.
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Nonwidget Data Initialization: The initialize_hook Procedure
|
||
|
|
.XS
|
||
|
|
\*(SN Nonwidget Data Initialization: The initialize_hook Procedure
|
||
|
|
.XE
|
||
|
|
.IN "Initialization"
|
||
|
|
.LP
|
||
|
|
.NT
|
||
|
|
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.
|
||
|
|
.NE
|
||
|
|
.LP
|
||
|
|
The initialize_hook procedure pointer is of type
|
||
|
|
.PN XtArgsProc :
|
||
|
|
.LP
|
||
|
|
.IN "initialize_hook procedure" "" "@DEF@"
|
||
|
|
.IN "XtArgsProc" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
typedef void (*XtArgsProc)(Widget, ArgList, Cardinal*);
|
||
|
|
.br
|
||
|
|
Widget \fIw\fP;
|
||
|
|
.br
|
||
|
|
ArgList \fIargs\fP;
|
||
|
|
.br
|
||
|
|
Cardinal *\fInum_args\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIw\fP 1i
|
||
|
|
Specifies the widget.
|
||
|
|
.IP \fIargs\fP 1i
|
||
|
|
Specifies the argument list passed by the client.
|
||
|
|
If the client created the widget using a varargs form, any resources
|
||
|
|
specified via
|
||
|
|
.PN XtVaTypedArg
|
||
|
|
are converted to the widget representation and the list is transformed
|
||
|
|
into the
|
||
|
|
.PN ArgList
|
||
|
|
format.
|
||
|
|
.IP \fInum_args\fP 1i
|
||
|
|
Specifies the number of entries in the argument list.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
If this procedure is not NULL,
|
||
|
|
it is called immediately after the corresponding initialize
|
||
|
|
procedure or in its place if the \fIinitialize\fP field is NULL.
|
||
|
|
.LP
|
||
|
|
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.
|
||
|
|
|
||
|
|
.NH 2
|
||
|
|
Realizing Widgets
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Realizing Widgets\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
To realize a widget instance, use
|
||
|
|
.PN XtRealizeWidget .
|
||
|
|
.LP
|
||
|
|
.IN "XtRealizeWidget" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
void XtRealizeWidget(\fIw\fP)
|
||
|
|
.br
|
||
|
|
Widget \fIw\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIw\fP 1i
|
||
|
|
Specifies the widget. \*(cI
|
||
|
|
.eM
|
||
|
|
.LP
|
||
|
|
If the widget is already realized,
|
||
|
|
.PN XtRealizeWidget
|
||
|
|
simply returns.
|
||
|
|
Otherwise it performs the following:
|
||
|
|
.IP \(bu 5
|
||
|
|
Binds all action names in the widget's
|
||
|
|
translation table to procedures (see Section 10.1.2).
|
||
|
|
.IP \(bu 5
|
||
|
|
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.
|
||
|
|
.IP \(bu 5
|
||
|
|
Constructs an
|
||
|
|
.PN XSetWindowAttributes
|
||
|
|
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.
|
||
|
|
.IP \(bu 5
|
||
|
|
If the widget is
|
||
|
|
not a subclass of
|
||
|
|
.PN compositeWidgetClass ,
|
||
|
|
.PN XtRealizeWidget
|
||
|
|
returns; otherwise it continues and performs the following:
|
||
|
|
.RS
|
||
|
|
.IP \- 5
|
||
|
|
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.
|
||
|
|
.IP \- 5
|
||
|
|
Maps all of the managed children windows that have \fImapped_when_managed\fP
|
||
|
|
.PN True .
|
||
|
|
If a widget is managed but \fImapped_when_managed\fP is
|
||
|
|
.PN False ,
|
||
|
|
the widget is allocated visual space but is not displayed.
|
||
|
|
.RE
|
||
|
|
.LP
|
||
|
|
If the widget is a top-level shell widget (that is, it has no parent), and
|
||
|
|
\fImapped_when_managed\fP is
|
||
|
|
.PN True ,
|
||
|
|
.PN XtRealizeWidget
|
||
|
|
maps the widget window.
|
||
|
|
.LP
|
||
|
|
.PN XtCreateWidget ,
|
||
|
|
.PN XtVaCreateWidget ,
|
||
|
|
.PN XtRealizeWidget ,
|
||
|
|
.PN XtManageChildren ,
|
||
|
|
.PN XtUnmanage\%Children ,
|
||
|
|
.PN XtUnrealizeWidget ,
|
||
|
|
.PN XtSetMappedWhenManaged ,
|
||
|
|
and
|
||
|
|
.PN XtDestroy\%Widget
|
||
|
|
maintain the following invariants:
|
||
|
|
.IP \(bu 5
|
||
|
|
If a composite widget is realized, then all its managed children are realized.
|
||
|
|
.IP \(bu 5
|
||
|
|
If a composite widget is realized, then all its managed children that have
|
||
|
|
\fImapped_when_managed\fP
|
||
|
|
.PN True
|
||
|
|
are mapped.
|
||
|
|
.LP
|
||
|
|
All \*(xI 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,
|
||
|
|
.PN XtRealizeWidget
|
||
|
|
calls the procedures in reverse order of
|
||
|
|
appearance in the
|
||
|
|
.PN CompositePart
|
||
|
|
\fIchildren\fP 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.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
To check whether or not a widget has been realized, use
|
||
|
|
.PN XtIsRealized .
|
||
|
|
.LP
|
||
|
|
.IN "XtIsRealized" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
Boolean XtIsRealized(\fIw\fP)
|
||
|
|
.br
|
||
|
|
Widget \fIw\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIw\fP 1i
|
||
|
|
Specifies the widget. \*(oI
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtIsRealized
|
||
|
|
function returns
|
||
|
|
.PN True
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
Some widget procedures (for example, set_values) might wish to
|
||
|
|
operate differently
|
||
|
|
after the widget has been realized.
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Widget Instance Window Creation: The realize Procedure
|
||
|
|
.XS
|
||
|
|
\*(SN Widget Instance Window Creation: The realize Procedure
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
The realize procedure pointer in a widget class is of type
|
||
|
|
.PN XtRealizeProc .
|
||
|
|
.LP
|
||
|
|
.IN "XtRealizeProc" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
typedef void (*XtRealizeProc)(Widget, XtValueMask*, XSetWindowAttributes*);
|
||
|
|
.br
|
||
|
|
Widget \fIw\fP;
|
||
|
|
.br
|
||
|
|
XtValueMask *\fIvalue_mask\fP;
|
||
|
|
.br
|
||
|
|
XSetWindowAttributes *\fIattributes\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIw\fP 1i
|
||
|
|
Specifies the widget.
|
||
|
|
.IP \fIvalue_mask\fP 1i
|
||
|
|
Specifies which fields in the \fIattributes\fP structure are used.
|
||
|
|
.IP \fIattributes\fP 1i
|
||
|
|
Specifies the window attributes to use in the
|
||
|
|
.PN XCreateWindow
|
||
|
|
call.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The realize procedure must create the widget's window.
|
||
|
|
.LP
|
||
|
|
Before calling the class realize procedure, the generic
|
||
|
|
.PN XtRealizeWidget
|
||
|
|
function fills in a mask and a corresponding
|
||
|
|
.PN XSetWindowAttributes
|
||
|
|
structure.
|
||
|
|
It sets the following fields in \fIattributes\fP and
|
||
|
|
corresponding bits in \fIvalue_mask\fP
|
||
|
|
based on information in the widget
|
||
|
|
core
|
||
|
|
structure:
|
||
|
|
.IP \(bu 5
|
||
|
|
The \fIbackground_pixmap\fP (or \fIbackground_pixel\fP if \fIbackground_pixmap\fP is
|
||
|
|
.PN XtUnspecifiedPixmap )
|
||
|
|
is filled in from the corresponding field.
|
||
|
|
.IP \(bu 5
|
||
|
|
The \fIborder_pixmap\fP (or \fIborder_pixel\fP if \fIborder_pixmap\fP is
|
||
|
|
.PN XtUnspecifiedPixmap )
|
||
|
|
is filled in from the corresponding field.
|
||
|
|
.IP \(bu 5
|
||
|
|
The \fIcolormap\fP is filled in from the corresponding field.
|
||
|
|
.IP \(bu 5
|
||
|
|
The \fIevent_mask\fP is filled in based on the event handlers registered,
|
||
|
|
the event translations specified, whether the \fIexpose\fP field is non-NULL,
|
||
|
|
and whether \fIvisible_interest\fP is
|
||
|
|
.PN True .
|
||
|
|
.IP \(bu 5
|
||
|
|
The \fIbit_gravity\fP is set to
|
||
|
|
.PN NorthWestGravity
|
||
|
|
if the \fIexpose\fP field is NULL.
|
||
|
|
.LP
|
||
|
|
These or any other fields in attributes and the corresponding bits in
|
||
|
|
\fIvalue_mask\fP can be set by the realize procedure.
|
||
|
|
.LP
|
||
|
|
Note that because realize is not a chained operation,
|
||
|
|
the widget class realize procedure must update the
|
||
|
|
.PN XSetWindowAttributes
|
||
|
|
structure with all the appropriate fields from
|
||
|
|
non-Core
|
||
|
|
superclasses.
|
||
|
|
.LP
|
||
|
|
.IN "Inheritance"
|
||
|
|
A widget class can inherit its realize procedure from its superclass
|
||
|
|
during class initialization.
|
||
|
|
The realize procedure defined for
|
||
|
|
.PN coreWidgetClass
|
||
|
|
calls
|
||
|
|
.PN XtCreateWindow
|
||
|
|
with the passed \fIvalue_mask\fP and \fIattributes\fP
|
||
|
|
and with \fIwindow_class\fP and \fIvisual\fP set to
|
||
|
|
.PN CopyFromParent .
|
||
|
|
Both
|
||
|
|
.PN compositeWidgetClass
|
||
|
|
and
|
||
|
|
.PN constraintWidgetClass
|
||
|
|
inherit this realize procedure, and most new widget subclasses
|
||
|
|
can do the same (see Section 1.6.10).
|
||
|
|
.LP
|
||
|
|
The most common noninherited realize procedures set \fIbit_gravity\fP in the mask
|
||
|
|
and attributes to the appropriate value and then create the window.
|
||
|
|
For example, depending on its justification, Label might set \fIbit_gravity\fP to
|
||
|
|
.PN WestGravity ,
|
||
|
|
.PN CenterGravity ,
|
||
|
|
or
|
||
|
|
.PN EastGravity .
|
||
|
|
Consequently, shrinking it would just move the bits appropriately,
|
||
|
|
and no
|
||
|
|
exposure
|
||
|
|
event is needed for repainting.
|
||
|
|
.LP
|
||
|
|
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
|
||
|
|
.PN XtRealizeWidget
|
||
|
|
on its children itself in the appropriate order from within its own
|
||
|
|
realize procedure.
|
||
|
|
.LP
|
||
|
|
Widgets that have children and whose class is not a subclass of
|
||
|
|
.PN compositeWidgetClass
|
||
|
|
are responsible for calling
|
||
|
|
.PN XtRealizeWidget
|
||
|
|
on their children, usually from within the realize procedure.
|
||
|
|
.LP
|
||
|
|
Realize procedures cannot manage or unmanage their descendants.
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Window Creation Convenience Routine
|
||
|
|
.XS
|
||
|
|
\*(SN Window Creation Convenience Routine
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
Rather than call the Xlib
|
||
|
|
.PN XCreateWindow
|
||
|
|
.IN "realize procedure"
|
||
|
|
function explicitly, a realize procedure should normally call the \*(xI analog
|
||
|
|
.PN XtCreateWindow ,
|
||
|
|
which simplifies the creation of windows for widgets.
|
||
|
|
.LP
|
||
|
|
.IN "XtCreateWindow" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
void XtCreateWindow(\fIw\fP, \fIwindow_class\fP, \fIvisual\fP, \
|
||
|
|
\fIvalue_mask\fP, \fIattributes\fP)
|
||
|
|
.br
|
||
|
|
Widget \fIw\fP;
|
||
|
|
.br
|
||
|
|
unsigned int \fIwindow_class\fP;
|
||
|
|
.br
|
||
|
|
Visual *\fIvisual\fP;
|
||
|
|
.br
|
||
|
|
XtValueMask \fIvalue_mask\fP;
|
||
|
|
.br
|
||
|
|
XSetWindowAttributes *\fIattributes\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIw\fP 1i
|
||
|
|
Specifies the widget that defines the additional window attributed. \*(cI
|
||
|
|
.IP \fIwindow_class\fP 1i
|
||
|
|
Specifies the Xlib window class (for example,
|
||
|
|
.PN InputOutput ,
|
||
|
|
.PN InputOnly ,
|
||
|
|
or
|
||
|
|
.PN CopyFromParent ).
|
||
|
|
.IP \fIvisual\fP 1i
|
||
|
|
Specifies the visual type (usually
|
||
|
|
.PN CopyFromParent ).
|
||
|
|
.ds Vm attribute fields to use
|
||
|
|
.IP \fIvalue_mask\fP 1i
|
||
|
|
Specifies which fields in the \fIattributes\fP structure are used.
|
||
|
|
.IP \fIattributes\fP 1i
|
||
|
|
Specifies the window attributes to use in the
|
||
|
|
.PN XCreateWindow
|
||
|
|
call.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtCreateWindow
|
||
|
|
function calls the Xlib
|
||
|
|
.PN XCreateWindow
|
||
|
|
function with values from the widget structure and the passed parameters.
|
||
|
|
Then, it assigns the created window to the widget's \fIwindow\fP field.
|
||
|
|
.LP
|
||
|
|
.PN XtCreateWindow
|
||
|
|
evaluates the following fields of the widget core
|
||
|
|
structure: \fIdepth\fP, \fIscreen\fP, \fIparent->core.window\fP, \fIx\fP,
|
||
|
|
\fIy\fP, \fIwidth\fP, \fIheight\fP, and
|
||
|
|
\fIborder_width\fP.
|
||
|
|
|
||
|
|
.NH 2
|
||
|
|
Obtaining Window Information from a Widget
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Obtaining Window Information from a Widget\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
The
|
||
|
|
Core
|
||
|
|
widget class definition contains the screen and window ids.
|
||
|
|
The \fIwindow\fP field may be NULL for a while
|
||
|
|
(see Sections 2.5 and 2.6).
|
||
|
|
.LP
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
.IN "XtDisplay" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
Display *XtDisplay(\fIw\fP)
|
||
|
|
.br
|
||
|
|
Widget \fIw\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIw\fP 1i
|
||
|
|
Specifies the widget. \*(cI
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
.PN XtDisplay
|
||
|
|
returns the display pointer for the specified widget.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
.IN "XtParent" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
Widget XtParent(\fIw\fP)
|
||
|
|
.br
|
||
|
|
Widget \fIw\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIw\fP 1i
|
||
|
|
Specifies the widget. \*(oI
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
.PN XtParent
|
||
|
|
returns the parent object for the specified widget. The returned object
|
||
|
|
will be of class Object or a subclass.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
.IN "XtScreen" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
Screen *XtScreen(\fIw\fP)
|
||
|
|
.br
|
||
|
|
Widget \fIw\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIw\fP 1i
|
||
|
|
Specifies the widget. \*(cI
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
.PN XtScreen
|
||
|
|
returns the screen pointer for the specified widget.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
.IN "XtWindow" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
Window XtWindow(\fIw\fP)
|
||
|
|
.br
|
||
|
|
Widget \fIw\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIw\fP 1i
|
||
|
|
Specifies the widget. \*(cI
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
.PN XtWindow
|
||
|
|
returns the window of the specified widget.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
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
|
||
|
|
.PN XtDisplayOfObject ,
|
||
|
|
.PN XtScreenOfObject ,
|
||
|
|
and
|
||
|
|
.PN XtWindowOfObject .
|
||
|
|
.IN "XtDisplayOfObject" "" "@DEF@"
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
Display *XtDisplayOfObject(\fIobject\fP)
|
||
|
|
.br
|
||
|
|
Widget \fIobject\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIobject\fP 1i
|
||
|
|
Specifies the object. \*(oI
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
.PN XtDisplayOfObject
|
||
|
|
is identical in function to
|
||
|
|
.PN XtDisplay
|
||
|
|
if the object is a widget; otherwise
|
||
|
|
.PN XtDisplayOfObject
|
||
|
|
returns the display
|
||
|
|
pointer for the nearest ancestor of \fIobject\fP that is of class
|
||
|
|
Widget or a subclass thereof.
|
||
|
|
.LP
|
||
|
|
.IN "XtScreenOfObject" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
Screen *XtScreenOfObject(\fIobject\fP)
|
||
|
|
.br
|
||
|
|
Widget \fIobject\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIobject\fP 1i
|
||
|
|
Specifies the object. \*(oI
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
.PN XtScreenOfObject
|
||
|
|
is identical in function to
|
||
|
|
.PN XtScreen
|
||
|
|
if the object is a widget; otherwise
|
||
|
|
.PN XtScreenOfObject
|
||
|
|
returns the screen pointer
|
||
|
|
for the nearest ancestor of \fIobject\fP that is of class
|
||
|
|
Widget or a subclass thereof.
|
||
|
|
.LP
|
||
|
|
.IN "XtWindowOfObject" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
Window XtWindowOfObject(\fIobject\fP)
|
||
|
|
.br
|
||
|
|
Widget \fIobject\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIobject\fP 1i
|
||
|
|
Specifies the object. \*(oI
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
.PN XtWindowOfObject
|
||
|
|
is identical in function to
|
||
|
|
.PN XtWindow
|
||
|
|
if the object is a widget; otherwise
|
||
|
|
.PN XtWindowOfObject
|
||
|
|
returns the window for the nearest ancestor of \fIobject\fP that is of class
|
||
|
|
Widget or a subclass thereof.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
To retrieve the instance name of an object, use
|
||
|
|
.PN XtName .
|
||
|
|
.LP
|
||
|
|
.IN "XtName" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
String XtName(\fIobject\fP)
|
||
|
|
.br
|
||
|
|
Widget \fIobject\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIobject\fP 1i
|
||
|
|
Specifies the object whose name is desired. \*(oI
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
.PN XtName
|
||
|
|
returns a pointer to the instance name of the specified object.
|
||
|
|
The storage is owned by the \*(xI and must not be modified. The
|
||
|
|
name is not qualified by the names of any of the object's ancestors.
|
||
|
|
.LP
|
||
|
|
Several window attributes are locally cached in the widget instance.
|
||
|
|
Thus, they can be set by the resource manager and
|
||
|
|
.PN XtSetValues
|
||
|
|
as well as used by routines that derive structures from these values
|
||
|
|
(for example, \fIdepth\fP for deriving pixmaps,
|
||
|
|
\fIbackground_pixel\fP for deriving GCs, and so on) or in the
|
||
|
|
.PN XtCreateWindow
|
||
|
|
call.
|
||
|
|
.LP
|
||
|
|
The \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP, and \fIborder_width\fP
|
||
|
|
window attributes are available to
|
||
|
|
geometry managers.
|
||
|
|
These fields are maintained synchronously inside the \*(xI.
|
||
|
|
When an
|
||
|
|
.PN XConfigureWindow
|
||
|
|
is issued by the \*(xI 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
|
||
|
|
.PN ConfigureNotify
|
||
|
|
event.
|
||
|
|
(In fact, most widgets do not select
|
||
|
|
.PN SubstructureNotify
|
||
|
|
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
|
||
|
|
.PN ConfigureNotify
|
||
|
|
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 Chapter 6).
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Unrealizing Widgets
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Unrealizing Widgets\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
To destroy the windows associated with a widget and its
|
||
|
|
non-pop-up descendants, use
|
||
|
|
.PN XtUnrealizeWidget .
|
||
|
|
.LP
|
||
|
|
.IN "XtUnrealizeWidget" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
void XtUnrealizeWidget(\fIw\fP)
|
||
|
|
.br
|
||
|
|
Widget \fIw\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIw\fP 1i
|
||
|
|
Specifies the widget. \*(cI
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
If the widget is currently unrealized,
|
||
|
|
.PN XtUnrealizeWidget
|
||
|
|
simply returns. Otherwise it performs the following:
|
||
|
|
.IP \(bu 5
|
||
|
|
Unmanages the widget if the widget is managed.
|
||
|
|
.IP \(bu 5
|
||
|
|
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
|
||
|
|
.IN XtNunrealizeCallback
|
||
|
|
XtNunrealizeCallback
|
||
|
|
list.
|
||
|
|
.IN "unrealizeCallback" "" "@DEF@"
|
||
|
|
.IP \(bu 5
|
||
|
|
Destroys the widget's window and any subwindows by calling
|
||
|
|
.PN XDestroyWindow
|
||
|
|
with the specified widget's \fIwindow\fP field.
|
||
|
|
.LP
|
||
|
|
Any events in the queue or which arrive following a call to
|
||
|
|
.PN XtUnrealizeWidget
|
||
|
|
will be dispatched as if the window(s) of the
|
||
|
|
unrealized widget(s) had never existed.
|
||
|
|
|
||
|
|
.NH 2
|
||
|
|
Destroying Widgets
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Destroying Widgets\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
The \*(xI provide support
|
||
|
|
.IP \(bu 5
|
||
|
|
To destroy all the pop-up children of the widget being destroyed
|
||
|
|
and destroy all children of composite widgets.
|
||
|
|
.IP \(bu 5
|
||
|
|
To remove (and unmap) the widget from its parent.
|
||
|
|
.IP \(bu 5
|
||
|
|
To call the callback procedures that have been registered to trigger
|
||
|
|
when the widget is destroyed.
|
||
|
|
.IP \(bu 5
|
||
|
|
To minimize the number of things a widget has to deallocate when destroyed.
|
||
|
|
.IP \(bu 5
|
||
|
|
To minimize the number of
|
||
|
|
.PN XDestroyWindow
|
||
|
|
calls when destroying a widget tree.
|
||
|
|
.sp
|
||
|
|
.LP
|
||
|
|
To destroy a widget instance, use
|
||
|
|
.PN XtDestroyWidget .
|
||
|
|
.LP
|
||
|
|
.IN "XtDestroyWidget" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
void XtDestroyWidget(\fIw\fP)
|
||
|
|
.br
|
||
|
|
Widget \fIw\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIw\fP 1i
|
||
|
|
Specifies the widget. \*(oI
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
The
|
||
|
|
.PN XtDestroyWidget
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
In phase 1,
|
||
|
|
.PN XtDestroyWidget
|
||
|
|
performs the following:
|
||
|
|
.IP \(bu 5
|
||
|
|
If the \fIbeing_destroyed\fP field of the widget is
|
||
|
|
.PN True ,
|
||
|
|
it returns immediately.
|
||
|
|
.IP \(bu 5
|
||
|
|
Recursively descends the widget tree and
|
||
|
|
sets the \fIbeing_destroyed\fP field to
|
||
|
|
.PN True
|
||
|
|
for the widget and all normal and pop-up children.
|
||
|
|
.IP \(bu 5
|
||
|
|
Adds the widget to a list of widgets (the destroy list) that should be
|
||
|
|
destroyed when it is safe to do so.
|
||
|
|
.LP
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
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
|
||
|
|
.PN XtDispatchEvent
|
||
|
|
is about to return, or immediately if not in
|
||
|
|
.PN XtDispatchEvent .
|
||
|
|
.LP
|
||
|
|
In phase 2,
|
||
|
|
.PN XtDestroyWidget
|
||
|
|
performs the following on each entry in the destroy list in the order
|
||
|
|
specified:
|
||
|
|
.IP \(bu 5
|
||
|
|
If the widget is not a pop-up child and the widget's parent is a subclass of
|
||
|
|
.PN composite\%WidgetClass ,
|
||
|
|
and if the parent is not being destroyed,
|
||
|
|
it calls
|
||
|
|
.PN XtUnmanageChild
|
||
|
|
on the widget and then calls the widget's parent's delete_child procedure
|
||
|
|
(see Section 3.3).
|
||
|
|
.IP \(bu 5
|
||
|
|
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).
|
||
|
|
.LP
|
||
|
|
The
|
||
|
|
.PN XtDestroyWidget
|
||
|
|
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:
|
||
|
|
.IP \(bu 5
|
||
|
|
If the widget is not a pop-up child and the widget's parent is a subclass of
|
||
|
|
.PN constraint\%WidgetClass ,
|
||
|
|
it calls the
|
||
|
|
.PN ConstraintClassPart
|
||
|
|
destroy procedure for the parent,
|
||
|
|
then for the parent's superclass,
|
||
|
|
until finally it calls the
|
||
|
|
.PN ConstraintClassPart
|
||
|
|
destroy procedure for
|
||
|
|
.PN constraintWidgetClass .
|
||
|
|
.IP \(bu 5
|
||
|
|
Calls the
|
||
|
|
.PN CoreClassPart
|
||
|
|
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.
|
||
|
|
.IP \(bu 5
|
||
|
|
If the widget class object class part contains an
|
||
|
|
.PN ObjectClassExtension
|
||
|
|
record with the record_type
|
||
|
|
.PN \s-1NULLQUARK\s+1
|
||
|
|
and the \fIdeallocate\fP field is not NULL,
|
||
|
|
calls the deallocate procedure to deallocate the instance and if one
|
||
|
|
exists, the constraint record. Otherwise, the \*(xI will deallocate
|
||
|
|
the widget instance record and if one exists, the constraint record.
|
||
|
|
.IP \(bu 5
|
||
|
|
Calls
|
||
|
|
.PN XDestroyWindow
|
||
|
|
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.)
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Adding and Removing Destroy Callbacks
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Adding and Removing Destroy Callbacks\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
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 Chapter 8.
|
||
|
|
.IN "Destroy Callbacks"
|
||
|
|
The destroy callback list is identified by the resource name
|
||
|
|
XtNdestroyCallback.
|
||
|
|
.LP
|
||
|
|
For example, the following adds an application-supplied destroy callback
|
||
|
|
procedure \fIClientDestroy\fP with client data to a widget by calling
|
||
|
|
.PN XtAddCallback .
|
||
|
|
.IN "XtAddCallback"
|
||
|
|
.Ds
|
||
|
|
XtAddCallback(\fIw\fP, XtNdestroyCallback, \fIClientDestroy\fP, \fIclient_data\fP)
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
Similarly, the following removes the application-supplied destroy callback
|
||
|
|
procedure \fIClientDestroy\fP by calling
|
||
|
|
.PN XtRemoveCallback .
|
||
|
|
.IN "XtRemoveCallback"
|
||
|
|
.Ds
|
||
|
|
XtRemoveCallback(\fIw\fP, XtNdestroyCallback, \fIClientDestroy\fP, \fIclient_data\fP)
|
||
|
|
.De
|
||
|
|
.LP
|
||
|
|
The \fIClientDestroy\fP argument is of type
|
||
|
|
.PN XtCallbackProc ;
|
||
|
|
see Section 8.1.
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Dynamic Data Deallocation: The destroy Procedure
|
||
|
|
.XS
|
||
|
|
\*(SN Dynamic Data Deallocation: The destroy Procedure
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
.IN "destroy procedure" "" "@DEF@"
|
||
|
|
The destroy procedure pointers in the
|
||
|
|
.PN ObjectClassPart ,
|
||
|
|
.PN RectObjClassPart ,
|
||
|
|
and
|
||
|
|
.PN CoreClassPart
|
||
|
|
structures are of type
|
||
|
|
.PN XtWidgetProc .
|
||
|
|
.LP
|
||
|
|
.IN "XtWidgetProc" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
typedef void (*XtWidgetProc)(Widget);
|
||
|
|
.br
|
||
|
|
Widget \fIw\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIw\fP 1i
|
||
|
|
Specifies the widget being destroyed.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
Deallocating storage includes, but is not limited to,
|
||
|
|
the following steps:
|
||
|
|
.IP \(bu 5
|
||
|
|
Calling
|
||
|
|
.PN XtFree
|
||
|
|
on dynamic storage allocated with
|
||
|
|
.PN XtMalloc ,
|
||
|
|
.PN XtCalloc ,
|
||
|
|
and so on.
|
||
|
|
.IP \(bu 5
|
||
|
|
Calling
|
||
|
|
.PN XFreePixmap
|
||
|
|
on pixmaps created with direct X calls.
|
||
|
|
.IP \(bu 5
|
||
|
|
Calling
|
||
|
|
.PN XtReleaseGC
|
||
|
|
on GCs allocated with
|
||
|
|
.PN XtGetGC .
|
||
|
|
.IP \(bu 5
|
||
|
|
Calling
|
||
|
|
.PN XFreeGC
|
||
|
|
on GCs allocated with direct X calls.
|
||
|
|
.IP \(bu 5
|
||
|
|
Calling
|
||
|
|
.PN XtRemoveEventHandler
|
||
|
|
on event handlers added to other widgets.
|
||
|
|
.IP \(bu 5
|
||
|
|
Calling
|
||
|
|
.PN XtRemoveTimeOut
|
||
|
|
on timers created with
|
||
|
|
.PN XtAppAddTimeOut .
|
||
|
|
.IP \(bu 5
|
||
|
|
Calling
|
||
|
|
.PN XtDestroyWidget
|
||
|
|
for each child if the widget has children
|
||
|
|
and is not a subclass of
|
||
|
|
.PN compositeWidgetClass .
|
||
|
|
.LP
|
||
|
|
During destroy phase 2 for each widget, the \*(xI 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.
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Dynamic Constraint Data Deallocation: The ConstraintClassPart destroy Procedure
|
||
|
|
.XS
|
||
|
|
\*(SN Dynamic Constraint Data Deallocation: The ConstraintClassPart destroy Procedure
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
The constraint destroy procedure identified in the
|
||
|
|
.PN ConstraintClassPart
|
||
|
|
structure is called for a widget whose parent is a subclass of
|
||
|
|
.PN constraintWidgetClass .
|
||
|
|
This constraint destroy procedure pointer is of type
|
||
|
|
.PN XtWidgetProc .
|
||
|
|
The constraint destroy procedures are called in subclass-to-superclass order,
|
||
|
|
starting at the class of the widget's parent and ending at
|
||
|
|
.PN constraint\%WidgetClass .
|
||
|
|
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.
|
||
|
|
.LP
|
||
|
|
If a parent does not need to deallocate any constraint storage,
|
||
|
|
the constraint destroy procedure entry
|
||
|
|
in its class record can be NULL.
|
||
|
|
|
||
|
|
.NH 3
|
||
|
|
Widget Instance Deallocation: The deallocate Procedure
|
||
|
|
.XS
|
||
|
|
\*(SN Widget Instance Deallocation: The deallocate Procedure
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
.IN "deallocate procedure" "" "@DEF@"
|
||
|
|
The deallocate procedure pointer in the
|
||
|
|
.PN ObjectClassExtension
|
||
|
|
record is of type
|
||
|
|
.PN XtDeallocateProc .
|
||
|
|
.LP
|
||
|
|
.IN "XtDeallocateProc" "" "@DEF@"
|
||
|
|
.sM
|
||
|
|
.FD 0
|
||
|
|
typedef void (*XtDeallocateProc)(Widget, XtPointer);
|
||
|
|
.br
|
||
|
|
Widget \fIwidget\fP;
|
||
|
|
.br
|
||
|
|
XtPointer \fImore_bytes\fP;
|
||
|
|
.FN
|
||
|
|
.IP \fIwidget\fP 1i
|
||
|
|
Specifies the widget being destroyed.
|
||
|
|
.IP \fImore_bytes\fP 1i
|
||
|
|
Specifies the auxiliary memory received from the corresponding allocator
|
||
|
|
along with the widget, or NULL.
|
||
|
|
.LP
|
||
|
|
.eM
|
||
|
|
When a widget is destroyed, if an
|
||
|
|
.PN ObjectClassExtension
|
||
|
|
record exists in the object class part \fIextension\fP field
|
||
|
|
with \fIrecord_type\fP
|
||
|
|
.PN \s-1NULLQUARK\s+1
|
||
|
|
and the \fIdeallocate\fP field is not NULL, the
|
||
|
|
.PN XtDeallocateProc
|
||
|
|
will be called.
|
||
|
|
If no ObjectClassPart extension record is declared with \fIrecord_type\fP
|
||
|
|
equal to
|
||
|
|
.PN \s-1NULLQUARK\s+1 ,
|
||
|
|
then
|
||
|
|
.PN XtInheritAllocate
|
||
|
|
and
|
||
|
|
.PN XtInheritDeallocate
|
||
|
|
are assumed.
|
||
|
|
The responsibilities of the deallocate procedure are to deallocate the
|
||
|
|
memory specified by \fImore_bytes\fP if it is not NULL,
|
||
|
|
to deallocate the constraints record as specified by the
|
||
|
|
widget's \fIcore.constraints\fP field if it is
|
||
|
|
not NULL, and to deallocate the widget instance itself.
|
||
|
|
.LP
|
||
|
|
If no
|
||
|
|
.PN XtDeallocateProc
|
||
|
|
is found, it is assumed that the \*(xI
|
||
|
|
originally allocated the memory and is responsible for freeing it.
|
||
|
|
|
||
|
|
.NH 2
|
||
|
|
Exiting from an Application
|
||
|
|
.XS
|
||
|
|
\fB\*(SN Exiting from an Application\fP
|
||
|
|
.XE
|
||
|
|
.LP
|
||
|
|
All \*(tk applications should terminate
|
||
|
|
by calling
|
||
|
|
.PN XtDestroyApplicationContext
|
||
|
|
and then exiting
|
||
|
|
using the
|
||
|
|
standard method for their operating system (typically, by calling
|
||
|
|
.PN exit
|
||
|
|
for POSIX-based systems).
|
||
|
|
The quickest way to make the windows disappear while exiting is to call
|
||
|
|
.PN XtUnmapWidget
|
||
|
|
on each top-level shell widget.
|
||
|
|
The \*(xI 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.
|
||
|
|
.LP
|
||
|
|
Depending upon the widget set in use, it may be necessary to explicitly
|
||
|
|
destroy individual widgets or widget trees with
|
||
|
|
.PN XtDestroyWidget
|
||
|
|
before calling
|
||
|
|
.PN XtDestroyApplicationContext
|
||
|
|
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 Section 4.2), then the client may wish to resign from the session
|
||
|
|
before exiting. See Section 4.2.4 for details.
|
||
|
|
.bp
|