Page: | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
---|
A hierarchy of widget instances constitutes a widget tree. The
shell widget returned by 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.
Widgets can be either composite or primitive. Both kinds of widgets can contain children, but the Intrinsics provide a set of management mechanisms for constructing and interfacing between composite widgets, their children, and other clients.
Composite widgets, that is, members of the class 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.
In addition, the Intrinsics recursively perform many operations
(for example, realization and destruction) on composite widgets
and all their children. Primitive widgets that have children must
be prepared to perform the recursive operations themselves on
behalf of their children.
A widget tree is manipulated by several Intrinsics functions. For example, XtRealizeWidget traverses the tree downward and recursively realizes all pop-up widgets and children of composite widgets. 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. XtMakeGeometryRequest traverses the tree up one level and calls the geometry manager that is responsible for a widget child's geometry.
To facilitate upward traversal of the widget tree, each widget has a pointer to its parent widget. The Shell widget that XtAppCreateShell returns has a parent pointer of NULL.
To facilitate downward traversal of the widget tree, the children 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.
Home |
---|
Before an application can call any Intrinsics function other than
XtSetLanguageProc and XtToolkitThreadInitialize,
it must initialize the Intrinsics by using
or an application can call the convenience procedure XtOpenApplication
which combines the functions of the preceding procedures.
An application wishing to use the ANSI C locale mechanism should
call XtSetLanguageProc prior to calling XtDisplayInitialize,
XtOpenDisplay, XtOpenApplication, or XtAppInitialize.
Multiple instances of X Toolkit applications may be implemented
in a single address space. Each instance needs to be able to read
input and dispatch events independently of any other instance.
Further, an application instance may need multiple display connections
to have widgets on multiple displays. From the application's point
of view, multiple display connections usually are treated together
as a single unit for purposes of event dispatching. To accommodate
both requirements, the Intrinsics define application contexts,
each of which provides the information needed to distinguish one
application instance from another. The major component of an application
context is a list of one or more X Display pointers for
that application. The Intrinsics handle all display connections
within a single application context simultaneously, handling input
in a roundrobin fashion. The application context type XtAppContext
is opaque to clients.
To initialize the Intrinsics internals, use XtToolkitInitialize.
void XtToolkitInitialize( )
If XtToolkitInitialize was previously called, it returns immediately. When XtToolkitThreadInitialize is called before XtToolkitInitialize,the latter is protected against simultaneous activation by multiple threads.
To create an application context, use XtCreateApplicationContext.
XtAppContext XtCreateApplicadonContext( )
The XtCreateApplicationContext function returns an application
context, which is an opaque type. Every application must have
at least one application context.
To destroy an application context and close any remaining display connections in it, use XtDestroyApplicationContext.
app_context | Specifies the application context. |
The XtDestroyApplicationContext function destroys the specified application context. If called from within an event dispatch (for example, in a callback procedure), XtDestroyApplicationContext does not destroy the application context until the dispatch is complete.
To get the application context in which a given widget was created,
use XtWidgetToApplicationContext.
w | Specifies the widget for which you want the application context. Must be of class Object or any subclass thereof. |
The XtWidgetToApplicationContext function returns the application context for the specified widget.
To initialize a display and add it to an application context,
use XtDisplayInitialize.
app_context | Specifies the application context. |
display | Specifies a previously opened display connection. Note that a single display connection can be in at most one application context. |
application_name | Specifies the name of the application instance. |
application_class | Specifies the class name of this application, which is usually the generic Name for all instances of this application. |
options | Specifies how to parse the command line for any application-specific resources. The options argument is passed as a parameter to XrmParseCommand. For further information, see Section 15.9 in Xlib C Language X Interface and Section 2.4 of this specification. |
num_options | Specifies the number of entries in the options list. |
argc | Specifies a pointer to the number of command line parameters. |
argv | Specifies the list of command line parameters. |
The 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 XrmParseCommand function to parse the command line, and performs other per-display initialization. After XrmParseCommand has been called, argc and argv contain only those parameters that were not in the standard option table or in the table specified by the options argument. If the modified argc is not zero, most applications simply print out the modified argv along with a message listing the allowable options. On POSIX-based systems, the application name is usually the final component of argv[0]. If the synchronous resource is True, XtDisplayInitialize calls the Xlib 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 application_name, application_class, options, and num_options arguments.
XtDisplayInitialize calls XrmSetDatabase to associate the resource database of the default screen with the display before returning.
To open a display, initialize it, and then add it to an application
context, use XtOpenDisplay.
The XtOpenDisplay function calls XOpenDisplay with the specified display_string. If display_string is NULL, XtOpenDisplay uses the current value of the -display option specified in argv. If no display is specified in argv, the user's default display is retrieved from the environment. On POSIX-based systems, this is the value of the DISPLAY environment variable.
If this succeeds, XtOpenDisplay then calls XtDisplayInitialize and passes it the opened display and the value of the -name option specified in argv as the application name. If no -name option is specified and application name is non-NULL, application_name is passed to XtDisplayInitialize. If application_name is NULL and if the environment variable RESOURCE_NAME is set, the value of RESOURCE_NAME 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 argv[0] less any directory and file type components, that is, the final component of argv[0], if specified. If argv[0] does not exist or is the empty string, the application name is "main". XtOpenDisplay returns the newly opened display or NULL if it failed.
See Section 7.12 for information regarding the use of XtOpenDisplay in multiple threads.
To close a display and remove it from an application context,
use XtCloseDisplay.
display | Specifies the display. |
The XtCloseDisplay function calls XCloseDisplay with the specified display as soon as it is safe to do so. If called from within an event dispatch (for example, a callback procedure), XtCloseDisplay does not close the display until the dispatch is complete. Note that applications need only call XtCloseDisplay if they are to continue executing after closing the display; otherwise, they should call XtDestroyApplicationContext.
See Section 7.12 for information regarding the use of XtCloseDisplay in multiple threads.
Home |
---|
Resource databases are specified to be created in the current process locale. During display initialization prior to creating the per-screen resource database, the Intrinsics will call out to a specified application procedure to set the locale according to options found on the command line or in the per-display resource specifications.
The callout procedure provided by the application is of type
XtLanguageProc.
The language procedure allows an application to set the locale
to the value of the language resource determined by XtDisplayInitialize.
The function returns a new language string that will be subsequently
used by XtDisplayInitialize to establish the path for loading
resource files. The returned string will be copied by the Intrinsics
into new memory.
Initially, no language procedure is set by the Intrinsics. To set the language procedure for use by XtDisplayInitialize use XtSetLanguageProc.
app_context | Specifies the application context in which the language procedure is to be used, or NULL. |
proc | Specifies the language procedure. |
client_data | Specifies additional client data to be passed to the language procedure when it is called. |
XtSetLanguageProc sets the language procedure that will be called from XtDisplayInitialize for all subsequent Displays initialized in the specified application context. If app_context 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 proc is NULL a default language procedure is registered. 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 XtSetLanguageProc, it will cause the default language procedure to be registered.
The default language procedure does the following:
Home |
---|
The 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:
When the resource database for a particular screen on the display
is needed (either internally, or when XtScreenDatabase is
called), it is created in the following manner using the sources
listed above in the same order:
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 |
- | If XAPPLRESDIR is defined, the default XUSERFILESEARCHPATH must contain at least seven entries. These entries must contain the following directory prefixes and substitutions: |
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 |
To obtain the resource database for a particular screen, use XtScreenDatabase.
screen | Specifies the screen whose resource database is to be returned. |
The XtScreenDatabase function returns the fully merged resource database as specified above, associated with the specified screen. If the specified screen does not belong to a Display initialized by XtDisplayInitialize, the results are undefined.
To obtain the default resource database associated with a particular
display, use XtDatabase.
display | Specifies the display. |
The XtDatabase function is equivalent to XrmGetDatabase. It returns the database associated with the specified display, or NULL if a database has not been set.
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 XtAppSetFallbackResources.
app_context | Specifies the application context in which the fallback specifications will be used. |
specification_list | Specifies a NULL-terminated list of resource specifications to preload the database, or NULL. |
Each entry in specification_list points to a string in the format of XrmPutLineResource. Following a call to XtAppSetFallbackResources, when a resource database is being created for a particular screen and the Intrinsics are not able to find or read an application-specific class resource file according to the rules given above and if specification_list is not NULL the resource specifications in specification_list will be merged into the screen resource database in place of the application-specific class resource file. XtAppSetFallbackResources is not required to copy specification list; 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 XtAppSetFallbackResources is called again. The value NULL for specification_list 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.
Home |
---|
The XtOpenDisplay function first parses the command line
for the following options:
XtDisplayInitialize has a table of standard command line options that are passed to XrmParseCommand for adding resources to me resource database, and it takes as a parameter additional application-specific resource abbreviations. The format of this table is described in Section 15.9 in Xlib - C Language X Interface.
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;
The standard table contains the following entries:
Option String | esource Name | rgument Kind | esource Value |
-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 | NepArg | next argument |
-xnllanguage | .xnlLanguage | SepArg | next argument |
-xrm | next argument | ResArg | next argument |
-xtsessionID | .sessionID | SepArg | next argument |
Note that any unique abbreviation for an option name in the standard
table or in the application table is accepted.
If reverseVideo is True, the values of XtDefaultForeground
and XtDefaultBackground are exchanged for all screens
on the Display.
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, XtDisplayInitialize
makes a call to 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.
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.
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 xmh, you can start it up as
When it parses the command line, XtDisplayInitialize merges the application option table with the standard option table before calling the Xlib 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 Intrinsics reserve all option names beginning with the characters "-xt" for future standard uses.
Home |
---|
The creation of widget instances is a three-phase process:
1. | The widgets are allocated and initialized with resources and are optionally added to the managed subset of their parent. |
2. | All composite widgets are notified of their managed children in a bottom-up traversal of the widget tree. |
3. | The widgets create X windows, which then are mapped. |
To start the first phase, the application calls XtCreateWidget for all its widgets and adds some (usually, most or all) of its widgets to their respective parents' managed set by calling XtManageChild. To avoid an O(n2) 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.
After all widgets have been created, the application calls XtRealizeWidget
with the top-level widget to execute the second and third
phases. 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.
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.
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.
Finally, 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.
2.5.1. Creating and Merging Argument Lists
Many Intrinsics functions may be passed pairs of resource names
and values. These are passed as an arglist, a pointer to an array
of Arg structures, which contains
typedef struct { String name; XtArgVal value; } Arg, *ArgList;
where XtArgVal is as defined in Section 1.5.
If the size of the resource is less than or equal to the size of an XtArgVal, the resource value is stored directly in value; otherwise, a pointer to it is stored in value.
To set values in an ArgList, use XtSetArg.
arg | Specifies the name/value pair to set. |
name | Specifies the name of the resource. |
value | Specifies the value of the resource if it will fit in an XtArgVal, else the address. |
The XtSetArg function is usually used in a highly stylized manner to minimize the probability of making a mistake; for example:
Arg args[20]; int n; n=0; XtSetArg(args[n], XtNheight, 100); n++; XtSetArg(args[n], XtNwidth, 200); n++; XtSetValues(widget, args, n);
Alternatively, an application can statically declare the argument
list and use XtNumber:
static Args args[ ] = { {XtNheight, (XtArgVal) 100}, {XtNwidth, (XtArgVal) 200}, }; XtSetValues(Widget, args, XtNumber(args));
Note that you should not use expressions with side effects such
as auto-increment or autodecrement within the first argument to
XtSetArg. XtSetArg can be implemented as a macro that evaluates
the first argument twice.
To merge two arglist arrays, use XtMergeArgLists.
args1 | Specifies the first argument list. |
num_args1 | Specifies the number of entries in the first argument list. |
args2 | Specifies the second argument list. |
num_ args2 | Specifies the number of entries in the second argument list. |
The 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 XtFree.
All Intrinsics interfaces that require 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 ArgList procedure; e.g., XtVaCreateWidget.
Each procedure named XtVasomething takes as its last
arguments, in place of the corresponding ArgList/ Cardinal
parameters, a variable parameter list of resource name
and value pairs where each name is of type String and each
value is of type XtArgVal. The end of the list is
identified by a name 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 ArgList and
varargs forms interchangeably.
Two special names are defined for use only in varargs lists: XtVaTypedArg
and XtVaNestedList.
#define XtVaTypedArg "XtVaTypedArg"
If the name XtVaTypedArg is specified in place of a resource
name, then the following four arguments are interpreted as a name/type/value/size
tuple where name is of type String, type
is of type String, value is
of type XtArgVal, and size is of type
int. When a varargs list containing 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 type is XtRString then value contains
a pointer to the string and size contains the number
of bytes allocated, including the trailing null byte. If type
is not XtRString, then if size is less than or equal to
sizeof(XtArgVal), the value should be
the data cast to the type XtArgVal, otherwise value
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.
#define XtVaNestedList "XtVaNestedList"
If the name XtVaNestedList is specified in place of a resource
name, then the following argument is interpreted as an 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.
To dynamically allocate a varargs list for use with XtVaNestedList
in multiple calls, use XtVaCreateArgsList.
typedef XtPointer XtVarArgsList;
unused | This argument is not currently used and must be specified as NULL. |
... | Specifies a variable parameter list of resource name and value pairs. |
The XtVaCreateArgsList function allocates memory and copies
its arguments into a single list pointer, which may be used with
XtVaNestedList. The end of both lists is identified
by a name entry containing NULL. Any entries of type 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 XtFree when no longer needed.
Use of resource files and the resource database is generally encouraged
over lengthy arglist or varargs lists whenever possible in order
to permit modification without recompilation.
2.5.2. Creating a Widget Instance
To create an instance of a widget, use XtCreateWidget.
name | 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. |
object_class | Specifies the widget class pointer for the created object. Must be objectClass or any subclass thereof. |
parent | Specifies the parent widget. Must be of class Object or any subclass thereof. |
args | Specifies the argument list to override any other resource specifications. |
num_args | Specifies the number of entries in the argument list. |
The XtCreateWidget function performs all the boilerplate
operations of widget creation, doing the following in order:
To create an instance of a widget using varargs lists, use XtVaCreateWidget.
name | Specifies the resource name for the created widget. |
object_class | Specifies the widget class pointer for the created object. Must be objectClass or any subclass thereof. |
parent | Specifies the parent widget. Must be of class Object or any subclass thereof. |
... | Specifies the variable argument list to override any other resource specifications. |
The XtVaCreateWidget procedure is identical in function
to XtCreateWidget with the args and num_args
parameters replaced by a varargs list, as described in Section 2.5.1.
2.5.3. Creating an Application Shell Instance
An application can have multiple top-level widgets, each of which
specifies a unique widget tree which can potentially be on different
screens or displays. An application uses XtAppCreateShell to
create independent widget trees.
name | Specifies the instance name of the shell widget. If name is NULL, the application name passed to XtDisplayInitialize is used. |
application_class | Specifies the resource class string to be used in place of the widget class_name string when widget_class is or a subclass thereof. |
widget_class | Specifies the widget class for the top-level widget (e.g., applicationShellWidgetClass) |
display | Specifies the display for the default screen and for the resource database used to retrieve the shell widget resources. |
args | Specifies the argument list to override any other resource specifications. |
num_args | Specifies the number of entries in the argument list. |
The 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 args 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 name.screen, class Class.Screen where
Class is the specified application_class if widget_class is applicationShellWidgetClass or a subclass thereof.
If widget_class is not applicationShellWidgetClass or
a subclass, Class is the class_name field from the
CoreClassPart of the specified widget_class. 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 args. The widget
name and Class as determined above are used as the leftmost
(i.e., root) components in all fully qualified resource names
for objects within this widget tree.
If the specified widget class is a subclass of WMShell, the name and Class as determined above will be stored into the WM_CLASS property on the widget's window when it becomes realized. If the specified widget_class is applicationShellWidgetClass or a subclass thereof the WM_COMMAND property will also be set from the values of the XtNargv and XtNargc resources.
To create multiple top-level shells within a single (logical)
application, you can use one of two methods:
xmail.geometry:... | (the main window) |
xmail.read.geometry:... | (the read window) |
xmail.compose.geometry:... | (the compose window) |
xmail.headers.geometry:... | (the headers window) |
xmail.read.geometry:... | (the read window) |
xmail.compose.geometry:... | (the compose window) |
To create a top-level widget that is the root of a widget tree
using varargs lists, use XtVaAppCreateShell.
The XtVaAppCreateShell procedure is identical in function
to XtAppCreateShell with the args and num_args
parameters replaced by a varargs list, as described in Section 2.5.1.
2.5.4. Convenience Procedure to Initialize an Application
To initialize the Intrinsics internals, create an application context, open and initialize a display, and create the initial root shell instance, an application may use XtOpenApplication or XtVaOpenApplication.
app_context_return | Returns the application context, if non-NULL. |
application_class | Specifies the class name of the application. |
options | Specifies the command line options table. |
num_options | Specifies the number of entries in options. |
argc_in_out | Specifies a pointer to the number of command line arguments. |
argv_in_out | Specifies a pointer to the command line arguments. |
fallback_resources | Specifies resource values to be used if the application class resource file cannot be opened or read, or NULL. |
widget_class | Specifies the class of the widget to be created. Must be shellWidgetClass or a subclass. |
args | Specifies the argument list to override any other resource specifications for the created shell widget. |
num_args | Specifies the number of entries in the argument list. |
The XtOpenApplication function calls XtToolkitInitialize followed by XtCreateApplicationContext, then calls XtOpenDisplay with display_string NULL and application_name NULL, and finally calls XtAppCreateShell with name NULL, the specified widget_class, an argument list and count, and returns the created shell. The recommended widget_lass is sessionShellWidgetClass. The argument list and count are created by merging the specified args and num_args with a list containing the specified argc and argv. The modified argc and argv returned by XtDisplayInitialize are returned in argc_in_out and argv_in_out. If app_context_return 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 XtOpenApplication terminates the application. If fallback_resources is non-NULL, XtAppSetFallbackResources is called with the value prior to calling XtOpenDisplay.
app_context_return | Returns the application context, if non-NULL. |
application_class | Specifies the class name of the application. |
options | Specifies the command line options table. |
num_options | Specifies the number of entries in options. |
argc_in_out | Specifies a pointer to the number of command line arguments. |
argv_in_out | Specifies the command line arguments array. |
fallback_resources | Specifies resource values to be used if the application class resource file cannot be opened, or NULL. |
widget_class | Specifies the class of the widget to be created. Must be shellWidgetClass or a subclass. |
... | Specifies the variable argument list to override any other resource specifications for the created shell. |
The XtVaOpenApplication procedure is identical in function
to XtOpenApplication with the args and num_args
parameters replaced by a varargs list, as described in Section 2.5.1.
2.5.5. Widget Instance Allocation: the allocate Procedure
A widget class may optionally provide an instance allocation procedure in the ObjectClassExtension record.
When the call to create a widget includes a varargs list containing XtVaTypedArg, these arguments will be passed to the allocation procedure in an XtTypedArgList.
typedef struct { String name; String type; XtArgVal value; int size; } TypedArg, *XtTypedArgList;
The allocate procedure pointer in the ObjectClassExtension record is of type XtAllocateProc.
widget_class | Specifies the widget class of the instance to allocate. |
constraint_size | Specifies the size of the constraint record to allocate, or 0. |
more_bytes | Specifies the number of auxiliary bytes of memory to allocate. |
args | Specifies the argument list as given in the call to create the widget. |
num_args | Specifies the list of arguments. |
typed_args | Specifies the list of typed arguments given in the call to create the widget. |
num_typed_args | Specifies the number of typed arguments. |
new_return | Returns a pointer to the newly allocated instance, or NULL in case of error. |
more_bytes_return | Returns the auxiliary memory if it was requested, or NULL if requested and an error occurred; otherwise, unchanged. |
At widget allocation time, if an extension record with record_type equal to NULLQUARK is located through the object class part extension field and the allocate field is not NULL, the XtAllocateProc will be invoked to allocate memory for the widget. If no ObjectClassPart extension record is declared with record_type equal to NULLQUARK, then XtInheritAllocate and XtInheritDeallocate are assumed. If no XtAllocateProc is found, the Intrinsics will allocate memory for the widget.
An XtAllocateProc must perform the following:
A class allocation procedure which envelopes the allocadon procedure
of a superclass must rely on the enveloped procedure to perform
the instance and constraint allocation. Allocadon procedures are
discouraged from initializing fields in the widget record but
if they choose to do so they should not touch the instance part
of any superclass.
2.5.6. Widget Instance Initialization: the initialize Procedure
The initialize procedure pointer in a widget class is of type XtInitProc.
An initialization procedure performs the following:
It is not necessary to allocate space for or to copy callback lists. |
A widget may only directly assign its own width and height within the initialize, initialize_hook, set_values and set_values_hook procedures; see Chapter 6. |
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.
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 args and num_args 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.
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 initialize field in the class record.
Sometimes a subclass may want to overwrite values filled in by its superclass. In particular, size calculations of a superclass are often incorrect for a subclass, and in this case, the subclass must modify or recalculate fields declared and computed by its superclass.
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.
The request and new 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 request widget is a copy of the widget as initialized by the arglist and resource database. The new 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.
In the above example, the subclass with the visual surround can
see if the width and height in the request widget
are zero. If so, it adds its surround size to the width and
height fields in the new widget. If not, it must
make do with the size originally specified.
The new widget will become the actual widget instance record.
Therefore, the initialization procedure should do all its work
on the new widget; the request widget should never
be modified. If the initialize procedure needs to call any routines
that operate on a widget, it should specify new as the
widget instance.
2.5.7. Constraint Instance Initialization: the ConstraintClassPart initialize Procedure
The constraint initialization procedure pointer, found in the ConstraintClassPart
initialize field of the widget class record, is of type
XtInitProc. The values passed to the parent constraint
initialization procedures are the same as those passed to the
child's class widget initialization procedures.
The constraints field of the request widget points
to a copy of the constraints record as initialized by the arglist
and resource database.
The constraint initialization procedure should compute any constraint fields derived from constraint resources. It can make further changes to the new widget to make the widget and any other constraint fields conform to the specified constraints, for example, changing the widget's size or position.
If a constraint class does not need a constraint initialization
procedure, it can specify NULL for the initialize field
of the ConstraintClassPart in the class record.
2.5.8. Nonwidget Data Initialization: the initialize_hook Procedure
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. |
The initialize_hook procedure pointer is of type XtArgsProc:
If this procedure is not NULL, it is called immediately after the corresponding initialize procedure or in its place if the initialize field is NULL.
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.
Home |
---|
To realize a widget instance, use XtRealizeWidget.
w | Specifies the widget. Must be of class Core or any subclass thereof. |
If the widget is already realized, XtRealizeWidget simply
returns. Otherwise it performs the following:
If the widget is a top-level shell widget (that is, it has no
parent), and mapped_when_managed is True,
XtRealizeWidget maps the widget window.
XtCreateWidget, XtVaCreateWidget, XtRealizeWidget,
XtManageChildren, XtUnmanageChildren, XtUnrealizeWidget,
XtSetMappedWhenManaged, and XtDestroyWidget maintain
the following invariants:
All Intrinsics functions and all widget routines should accept
either realized or unrealized widgets. When calling the realize
or change_managed procedures for children of a composite widget,
XtRealizeWidget calls the procedures in reverse order of
appearance in the CompositePart children 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.
To check whether or not a widget has been realized, use XtIsRealized.
w | Specifies the widget. Must be of class Object or any subclass thereof. |
The XtIsRealized function returns 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.
Some widget procedures (for example, set_values) might wish to
operate differently after the widget has been realized.
2.6.1. Widget Instance Window Creation: the realize Procedure
The realize procedure pointer in a widget class is of type XtRealizeProc.
w | Specifies the widget. |
value_mask | Specifies which fields in the attributes structure are used. |
attributes | Specifies the window attributes to use in the XCreateWindow call. |
The realize procedure must create the widget's window.
Before calling the class realize procedure, the generic XtRealizeWidget
function fills in a mask and a corresponding XSetWindowAttributes
structure. It sets the following fields in attributes and
corresponding bits in value_mask based on information in
the widget core structure:
The background_pixmap (or background_pixel if background_pixmap is XtUnspecifiedPixmap) is filled in from the corresponding field.
These or any other fields in attributes and the corresponding bits in value_mask can be set by the realize procedure.
Note that because realize is not a chained operation, the widget class realize procedure must update the XSetWindowAttributes structure with all the appropriate fields from non-Core superclasses.
A widget class can inherit its realize procedure from its superclass
during class initialization. The realize procedure defined for
coreWidgetClass calls XtCreateWindow with the passed
value_mask and attributes and with window_class
and visual set to CopyFromParent. Both
compositeWidgetClass and constraintWidgetClass inherit
this realize procedure, and most new widget subclasses can do
the same (see Section 1.6.10).
The most common noninherited realize procedures set bit_gravity
in the mask and attributes to the appropriate value and then
create the window. For example, depending on its justification,
Label might set bit_gravity to WestGravity, CenterGravity,
or EastGravity. Consequently, shrinking it would
just move the bits appropriately, and no exposure event is needed
for repainting.
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 XtRealizeWidget on its children
itself in the appropriate order from within its own realize
procedure.
Widgets that have children and whose class is not a subclass of compositeWidgetClass are responsible for calling XtRealizeWidget on their children, usually from within the realize procedure.
Realize procedures cannot manage or unmanage their descendants.
2.6.2. Window Creation Convenience Routine
Rather than call the Xlib XCreateWindow function explicitly,
a realize procedure should normally call the Intrinsics analog
XtCreateWindow, which simplifies the creation of
windows for widgets.
The XtCreateWindow function calls the Xlib XCreateWindow
function with values from the widget structure and the passed
parameters. Then, it assigns the created window to the widget's
window field.
XtCreateWindow evaluates the following fields of the widget core structure: depth, screen, parent->core.window, x, y, width, height, and border_width.
Home |
---|
The Core widget class definition contains the screen and window
ids. The window field may be NULL for a while (see Sections 2.5 and 2.6).
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.
w | Specifies the widget. Must be of class Core or any subclass thereof. |
XtDisplay returns the display pointer for the specified
widget.
w | Specifies the widget. Must be of class Object or any subclass thereof. |
XtParent returns the parent object for the specified widget.
The returned object will be of class Object or a subclass.
w | Specifies the widget. Must be of class Core or any subclass thereof. |
XtScreen returns the screen pointer for the specified widget.
w | Specifies the widget. Must be of class Core or any subclass thereof. |
XtWindow returns the window of the specified widget.
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 XtDisplayOfObject, XtScreenOfObject, and XtWindowOfObject.
object | Specifies the object. Must be of class Object or any subclass thereof. |
XtDisplayOfObject is identical in function to XtDisplay if the object is a widget; otherwise XtDisplayOfObject returns the display pointer for the nearest ancestor of object that is of class Widget or a subclass thereof.
object | Specifies the object. Must be of class Object or any subclass thereof. |
XtScreenOfObject is identical in function to XtScreen if the object is a widget; otherwise XtScreenOfObject retums the screen pointer for the nearest ancestor of object that is of class Widget or a subclass thereof.
object | Specifies the object. Must be of class Object or any subclass thereof. |
XtWindowOfObject is identical in function to XtWindow
if the object is a widget; otherwise XtWindowOfObject returns
the window for the nearest ancestor of object that is of
class Widget or a subclass thereof.
To retrieve the instance name of an object, use XtName.
object | Specifies the object whose name is desired. Must be of class Object or any subclass thereof. |
XtName returns a pointer to the instance name of the specified
object. The storage is owned by the Intrinsics and must not be
modified. The name is not qualified by the names of any of the
object's ancestors.
Several window attributes are locally cached in the widget instance.
Thus, they can be set by the resource manager and XtSetValues
as well as used by routines that derive structures from these
values (for example, depth for deriving pixmaps, background_pixel
for deriving GCs, and so on) or in the XtCreateWindow call.
The x, y, width, height, and border_width
window attributes are available to geometry managers. These fields
are maintained synchronously inside the Intrinsics. When an XConfigureWindow
is issued by the Intrinsics on the widget's window (on request
of its parent), these values are updated immediately rather than
some time later when the server generates a ConfigureNotify
event. (In fact, most widgets do not select 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 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).
To destroy the windows associated with a widget and its non-pop-up descendants, use XtUnrealizeWidget.
w | Specifies the widget. Must be of class Core or any subclass thereof. |
If the widget is currently unrealized, XtUnrealizeWidget simply
returns. Otherwise it performs the following:
Any events in the queue or which arrive following a call to XtUnrealizeWidget will be dispatched as if the window(s) of the unrealized widget(s) had never existed.
Home |
---|
The Intrinsics provide support
To destroy a widget instance, use XtDestroyWidget.
w | Specifies the widget. Must be of class Object or any subclass thereof. |
The 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.
In phase 1, XtDestroyWidget performs the following:
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.
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 XtDispatchEvent is about to return,
or immediately if not in XtDispatchEvent.
In phase 2, XtDestroyWidget performs the following on each entry in the destroy list in the order specified:
The 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:
2.8.1. Adding and Removing Destroy Callbacks
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. The destroy callback list
is identified by the resource name XtNdestroyCallback.
The ClientDestroy argument is of type XtCallbackProc;
see Section 8.1.
2.8.2. Dynamic Data Deallocation: the destroy Procedure
The destroy procedure pointers in the ObjectClassPart,
RectObjClassPart, and CoreClassPart structures are
of type XtWidgetProc.
w | Specifies the widget being destroyed. |
The destroy procedures are called in subclass-to-superclass order.
Therefore, a widget's destroy procedure only should deallocate
storage that is specific to the subclass and should ignore the
storage allocated by any of its superclasses. The destroy procedure
should only deallocate 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.
Deallocating storage includes, but is not limited to, the following steps:
During destroy phase 2 for each widget, the Intrinsics remove
the widget from the modal cascade, unregister all event handlers,
remove all key, keyboard, button, and pointer grabs and remove
all callback procedures registered on the widget. Any outstanding
selection transfers will time out.
2.8.3. Dynamic Constraint Data Deallocation: the ConstraintClassPart destroy Procedure
The constraint destroy procedure identified in the ConstraintClassPart structure is called for a widget whose parent is a subclass of constraintWidgetClass. This constraint destroy procedure pointer is of type XtWidgetProc. The constraint destroy procedures are called in subclass-to-superclass order, starting at the class of the widget's parent and ending at constraintWidgetClass. Therefore, a parent's constraint destroy procedure only should deallocate storage that is specific to the constraint subclass and not storage allocated by any of its superclasses.
If a parent does not need to deallocate any constraint storage,
the constraint destroy procedure entry in its class record can
be NULL.
2.8.4. Widget Instance Deallocation: the deallocate Procedure
The deallocate procedure pointer in the ObjectClassExtension
record is of type XtDeallocateProc.
widget | Specifies the widget being destroyed. |
more_bytes | Specifies the auxiliary memory received from the corresponding allocator along with the widget, or NULL. |
When a widget is destroyed, if an ObjectClassExtension record exists in the object class part extension field with record_type NULLQUARK and the deallocate field is not NULL, the XtDeallocateProc will be called. If no ObjectClassPart extension record is declared with record_type equal to NULLQUARK, then XtInheritAllocate and XtInheritDeallocate are assumed. The responsibilities of the deallocate procedure are to deallocate the memory specified by more_bytes if it is not NULL, to deallocate the constraints record as specified by the widget's core.constraints field if it is not NULL, and to deallocate the widget instance itself.
If no XtDeallocateProc is found, it is assumed that the Intrinsics originally allocated the memory and is responsible for freeing it.
Home |
---|
All X Toolkit applications should terminate by calling XtDestroyApplicationContext
and then exiting using the standard method for their operating
system (typically, by calling exit for POSIX-based systems).
The quickest way to make the windows disappear while exiting is
to call XtUnmapWidget on each top-level shell widget. The
Intrinsics have no resources beyond those in the program image,
and the X server will free its resources when its connection to
the application is broken.
Depending upon the widget set in use, it may be necessary to explicitly
destroy individual widgets or widget trees with XtDestroyWidget
before calling 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 additional 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.)
Home |
---|
Contents | Previous Chapter | Next Chapter |