diff options
Diffstat (limited to 'libXt/specs/CH02')
| -rw-r--r-- | libXt/specs/CH02 | 3165 |
1 files changed, 3165 insertions, 0 deletions
diff --git a/libXt/specs/CH02 b/libXt/specs/CH02 new file mode 100644 index 000000000..cbb4bb8a5 --- /dev/null +++ b/libXt/specs/CH02 @@ -0,0 +1,3165 @@ +.\" $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 |