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