diff options
| author | Matt Dew <marcoz@osource.org> | 2011-10-20 22:11:52 -0600 |
|---|---|---|
| committer | Matt Dew <marcoz@osource.org> | 2011-10-20 22:11:52 -0600 |
| commit | a1132e0d6b627f4b948f3793649432f9b8d4e73d (patch) | |
| tree | 22a68ca88ecacf4665abf6337a172135e0b4c6d1 | |
| parent | 8a40b5e2a094742eff9cc5e48f4d2cd73e34c0a9 (diff) | |
02 done.
| -rw-r--r-- | specs/CH02.xml | 2278 | ||||
| -rw-r--r-- | specs/intrinsics.xml | 7 |
2 files changed, 774 insertions, 1511 deletions
diff --git a/specs/CH02.xml b/specs/CH02.xml index 484d011..8f35c8a 100644 --- a/specs/CH02.xml +++ b/specs/CH02.xml @@ -1,61 +1,6 @@ -<!-- .\" $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<function>Chapter 2</function>\s-1 - -\s+1<function>Widget Instantiation</function>\s-1 -<!-- .sp 2 --> -<!-- .nr H1 2 --> -<!-- .nr H2 0 --> -<!-- .nr H3 0 --> -<!-- .nr H4 0 --> -<!-- .nr H5 0 --> -<para> -<!-- .LP --> -<!-- .XS --> -<!-- Chapter 2 \(em Widget Instantiation --> -<!-- .XE --> +<chapter id='Widget_Instantiation'> +<title>Widget Instantiation</title> +<para> A hierarchy of widget instances constitutes a widget tree. The shell widget returned by <function>XtAppCreateShell</function> @@ -65,18 +10,18 @@ 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. </para> + <para> -<!-- .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 +but the Intrinsics provide a set of management mechanisms for constructing and interfacing between composite widgets, their children, and other clients. </para> + <para> -<!-- .LP --> Composite widgets, that is, members of the class -<function>compositeWidgetClass ,</function> +<function>compositeWidgetClass</function>, are containers for an arbitrary, but widget implementation-defined, collection of children, which may be instantiated by the composite widget itself, @@ -92,18 +37,18 @@ specific children of known classes themselves and do not expect external clients to do so. Primitive widgets also do not have general geometry management methods. </para> + <para> -<!-- .LP --> In addition, -the (xI recursively perform many operations +the Intrinsics recursively perform many operations (for example, realization and destruction) on composite widgets and all their children. Primitive widgets that have children must be prepared to perform the recursive operations themselves on behalf of their children. </para> + <para> -<!-- .LP --> -A widget tree is manipulated by several (xI functions. +A widget tree is manipulated by several Intrinsics functions. For example, <function>XtRealizeWidget</function> traverses the tree downward and recursively realizes all @@ -117,8 +62,8 @@ and determine the inheritance of resources from a widget's ancestors. traverses the tree up one level and calls the geometry manager that is responsible for a widget child's geometry. </para> + <para> -<!-- .LP --> To facilitate upward traversal of the widget tree, each widget has a pointer to its parent widget. The @@ -127,8 +72,8 @@ widget that <function>XtAppCreateShell</function> returns has a <emphasis remap='I'>parent</emphasis> pointer of NULL. </para> + <para> -<!-- .LP --> To facilitate downward traversal of the widget tree, the <emphasis remap='I'>children</emphasis> field of each composite widget is a pointer to an array of child widgets, @@ -140,32 +85,28 @@ that instantiate children are entirely responsible for all operations that require downward traversal below themselves. In addition, every widget has a pointer to an array of pop-up children. - </para> -<sect2 id="Initializing_the_tk"> + +<sect1 id="Initializing_the_tk"> <title>Initializing the (tk</title> -<!-- .XS --> -<!-- <function>(SN Initializing the (tk</function> --> -<!-- .XE --> <para> -<!-- .LP --> -Before an application can call any (xI function +Before an application can call any Intrinsics function other than <function>XtSetLanguageProc</function> and -<function>XtToolkitThreadInitialize ,</function> -it must initialize the (xI by using +<function>XtToolkitThreadInitialize</function>, +it must initialize the Intrinsics by using </para> <itemizedlist> <listitem> <para> -<function>XtToolkitInitialize ,</function> -which initializes the (xI internals +<function>XtToolkitInitialize</function>, +which initializes the Intrinsics internals </para> </listitem> <listitem> <para> -<function>XtCreateApplicationContext ,</function> +<function>XtCreateApplicationContext</function>, which initializes the per-application state </para> </listitem> @@ -173,33 +114,32 @@ which initializes the per-application state <para> <function>XtDisplayInitialize</function> or -<function>XtOpenDisplay ,</function> +<function>XtOpenDisplay</function>, which initializes the per-display state </para> </listitem> <listitem> <para> -<function>XtAppCreateShell ,</function> +<function>XtAppCreateShell</function>, which creates the root of a widget tree </para> </listitem> </itemizedlist> <para> -<!-- .LP --> Or an application can call the convenience procedure -<function>XtOpenApplication ,</function> +<function>XtOpenApplication</function>, which combines the functions of the preceding procedures. An application wishing to use the ANSI C locale mechanism should call <function>XtSetLanguageProc</function> prior to calling -<function>XtDisplayInitialize ,</function> -<function>XtOpenDisplay ,</function> -<function>XtOpenApplication ,</function> +<function>XtDisplayInitialize</function>, +<function>XtOpenDisplay</function>, +<function>XtOpenApplication</function>, or -<function>XtAppInitialize .</function> +<function>XtAppInitialize</function>. </para> + <para> -<!-- .LP --> Multiple instances of (tk applications may be implemented in a single address space. Each instance needs to be able to read @@ -209,88 +149,78 @@ 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, +the Intrinsics define application contexts, each of which provides the information needed to distinguish one application instance from another. The major component of an application context is a list of one or more X <function>Display</function> pointers for that application. -The (xI handle all display connections within a single application +The Intrinsics handle all display connections within a single application context simultaneously, handling input in a round-robin fashion. The application context type <function>XtAppContext</function> -<!-- .IN "XtAppContext" "" "@DEF@" --> is opaque to clients. -<!-- .sp --> -</para> -<para> -<!-- .LP --> -To initialize the (xI internals, use -<function>XtToolkitInitialize .</function> </para> + <para> -<!-- .LP --> -<!-- .IN "XtToolkitInitialize" "" "@DEF@" --> -<!-- .sM --> +To initialize the Intrinsics internals, use +<function>XtToolkitInitialize</function>. </para> -<!-- .FD 0 --> -void XtToolkitInitialize() -<!-- .FN --> + +<funcsynopsis id='XtToolkitInitialize'> +<funcprototype> + <funcdef>void <function>XtToolkitInitialize</function></funcdef> + <paramdef><parameter></parameter></paramdef> +</funcprototype> +</funcsynopsis> + <para> -<!-- .LP --> -<!-- .eM --> If <function>XtToolkitInitialize</function> was previously called, it returns immediately. When <function>XtToolkitThreadInitialize</function> is called before -<function>XtToolkitInitialize ,</function> +<function>XtToolkitInitialize</function>, the latter is protected against simultaneous activation by multiple threads. -<!-- .sp --> </para> + <para> -<!-- .LP --> To create an application context, use -<function>XtCreateApplicationContext .</function> +<function>XtCreateApplicationContext</function>. </para> + +<funcsynopsis id='XtCreateApplicationContext'> +<funcprototype> + <funcdef>XtAppContext <function>XtCreateApplicationContext</function></funcdef> + <paramdef><parameter></parameter></paramdef> +</funcprototype> +</funcsynopsis> + + <para> -<!-- .LP --> -<!-- .IN "XtCreateApplicationContext" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -XtAppContext XtCreateApplicationContext() -<!-- .FN --> -<para> -<!-- .LP --> -<!-- .eM --> The <function>XtCreateApplicationContext</function> function returns an application context, which is an opaque type. Every application must have at least one application context. -<!-- .sp --> </para> + <para> -<!-- .LP --> To destroy an application context and close any remaining display connections in it, use -<function>XtDestroyApplicationContext .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtDestroyApplicationContext" "" "@DEF@" --> -<!-- .sM --> +<function>XtDestroyApplicationContext</function>. </para> -<!-- .FD 0 --> -void XtDestroyApplicationContext(<emphasis remap='I'>app_context</emphasis>) -<!-- .br --> - XtAppContext <emphasis remap='I'>app_context</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtDestroyApplicationContext'> +<funcprototype> + <funcdef>void <function>XtDestroyApplicationContext</function></funcdef> + <paramdef>XtAppContext <parameter> app_context</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -304,31 +234,26 @@ Specifies the application context. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtDestroyApplicationContext</function> function destroys the specified application context. If called from within an event dispatch (for example, in a callback procedure), <function>XtDestroyApplicationContext</function> does not destroy the application context until the dispatch is complete. -<!-- .sp --> </para> + <para> -<!-- .LP --> To get the application context in which a given widget was created, use -<function>XtWidgetToApplicationContext .</function> +<function>XtWidgetToApplicationContext</function>. </para> -<para> -<!-- .LP --> -<!-- .IN "XtWidgetToApplicationContext" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -XtAppContext XtWidgetToApplicationContext(<emphasis remap='I'>w</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtWidgetToApplicationContext'> +<funcprototype> + <funcdef>XtAppContext <function>XtWidgetToApplicationContext</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -336,51 +261,36 @@ XtAppContext XtWidgetToApplicationContext(<emphasis remap='I'>w</emphasis>) </term> <listitem> <para> -Specifies the widget for which you want the application context. (oI +Specifies the widget for which you want the application context. Must be of class Object or any subclass thereof. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtWidgetToApplicationContext</function> function returns the application context for the specified widget. -<!-- .sp --> </para> + <para> -<!-- .LP --> To initialize a display and add it to an application context, use -<function>XtDisplayInitialize .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtDisplayInitialize" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -void XtDisplayInitialize(<emphasis remap='I'>app_context</emphasis>, <emphasis remap='I'>display</emphasis>, \ -<emphasis remap='I'>application_name</emphasis>, <emphasis remap='I'>application_class</emphasis>, -<!-- .br --> - <emphasis remap='I'>options</emphasis>, <emphasis remap='I'>num_options</emphasis>, <emphasis remap='I'>argc</emphasis>, <emphasis remap='I'>argv</emphasis>) -<!-- .br --> - XtAppContext <emphasis remap='I'>app_context</emphasis>; -<!-- .br --> - Display *<emphasis remap='I'>display</emphasis>; -<!-- .br --> - String <emphasis remap='I'>application_name</emphasis>; -<!-- .br --> - String <emphasis remap='I'>application_class</emphasis>; -<!-- .br --> - XrmOptionDescRec *<emphasis remap='I'>options</emphasis>; -<!-- .br --> - Cardinal <emphasis remap='I'>num_options</emphasis>; -<!-- .br --> - int *<emphasis remap='I'>argc</emphasis>; -<!-- .br --> - String *<emphasis remap='I'>argv</emphasis>; -<!-- .FN --> +<function>XtDisplayInitialize</function>. +</para> + +<funcsynopsis id='XtDisplayInitialize'> +<funcprototype> + <funcdef>void <function>XtDisplayInitialize</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>String <parameter>application_name</parameter></paramdef> + <paramdef>String <parameter>application_class</parameter></paramdef> + <paramdef>XrmOptionDescRec *<parameter>options</parameter></paramdef> + <paramdef>Cardinal <parameter>num_options</parameter></paramdef> + <paramdef>int *<parameter>argc</parameter></paramdef> + <paramdef>String *<parameter>argv</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -432,7 +342,7 @@ which is usually the generic name for all instances of this application. <para> Specifies how to parse the command line for any application-specific resources. The <emphasis remap='I'>options</emphasis> argument is passed as a parameter to -<function>XrmParseCommand .</function> +<function>XrmParseCommand</function>. For further information, see Section 15.9 in <emphasis remap='I'>(xL</emphasis> and Section 2.4 of this specification. </para> @@ -470,8 +380,6 @@ Specifies the list of command line parameters. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtDisplayInitialize</function> function retrieves the language string to be @@ -493,7 +401,7 @@ listing the allowable options. On POSIX-based systems, the application name is usually the final component of <emphasis remap='I'>argv</emphasis>[0]. If the synchronous resource is -<function>True ,</function> +<function>True</function>, <function>XtDisplayInitialize</function> calls the Xlib <function>XSynchronize</function> @@ -502,49 +410,38 @@ and any others currently open in the application context. See Sections 2.3 and 2.4 for details on the <emphasis remap='I'>application_name</emphasis>, <emphasis remap='I'>application_class</emphasis>, <emphasis remap='I'>options</emphasis>, and <emphasis remap='I'>num_options</emphasis> arguments. </para> + <para> -<!-- .LP --> <function>XtDisplayInitialize</function> calls <function>XrmSetDatabase</function> to associate the resource database of the default screen with the display before returning. - -<!-- .KS --> </para> + <para> -<!-- .LP --> To open a display, initialize it, and then add it to an application context, use -<function>XtOpenDisplay .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtOpenDisplay" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -Display *XtOpenDisplay(<emphasis remap='I'>app_context</emphasis>, <emphasis remap='I'>display_string</emphasis>, \ -<emphasis remap='I'>application_name</emphasis>, <emphasis remap='I'>application_class</emphasis>, -<!-- .br --> - <emphasis remap='I'>options</emphasis>, <emphasis remap='I'>num_options</emphasis>, <emphasis remap='I'>argc</emphasis>, <emphasis remap='I'>argv</emphasis>) -<!-- .br --> - XtAppContext <emphasis remap='I'>app_context</emphasis>; -<!-- .br --> - String <emphasis remap='I'>display_string</emphasis>; -<!-- .br --> - String <emphasis remap='I'>application_name</emphasis>; -<!-- .br --> - String <emphasis remap='I'>application_class</emphasis>; -<!-- .br --> - XrmOptionDescRec *<emphasis remap='I'>options</emphasis>; -<!-- .br --> - Cardinal <emphasis remap='I'>num_options</emphasis>; -<!-- .br --> - int *<emphasis remap='I'>argc</emphasis>; -<!-- .br --> - String *<emphasis remap='I'>argv</emphasis>; -<!-- .FN --> +<function>XtOpenDisplay</function>. +</para> + +<funcsynopsis id='XtOpenDisplay'> +<funcprototype> + <funcdef>Display <function>*XtOpenDisplay</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> + <paramdef>String <parameter>display_string</parameter></paramdef> + <paramdef>String <parameter>application_name</parameter></paramdef> + <paramdef>String <parameter>application_class</parameter></paramdef> + <paramdef>XrmOptionDescRec *<parameter>options</parameter></paramdef> + <paramdef>Cardinal <parameter>num_options</parameter></paramdef> + <paramdef>int *<parameter>argc</parameter></paramdef> + <paramdef>String *<parameter>argv</parameter></paramdef> +</funcprototype> +</funcsynopsis> + + + + <variablelist> <varlistentry> <term> @@ -595,7 +492,7 @@ which is usually the generic name for all instances of this application. <para> Specifies how to parse the command line for any application-specific resources. The options argument is passed as a parameter to -<function>XrmParseCommand .</function> +<function>XrmParseCommand</function>. </para> </listitem> </varlistentry> @@ -626,14 +523,11 @@ Specifies a pointer to the number of command line parameters. <listitem> <para> Specifies the list of command line parameters. -<!-- .KE --> </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtOpenDisplay</function> function calls @@ -649,8 +543,8 @@ this is the value of the <function>\s-1DISPLAY\s+1</function> environment variable. </para> + <para> -<!-- .LP --> If this succeeds, <function>XtOpenDisplay</function> then calls @@ -660,7 +554,7 @@ the value of the \-name option specified in <emphasis remap='I'>argv</emphasis> If no \-name option is specified and <emphasis remap='I'>application_name</emphasis> is non-NULL, <emphasis remap='I'>application_name</emphasis> is passed to -<function>XtDisplayInitialize .</function> +<function>XtDisplayInitialize</function>. If <emphasis remap='I'>application_name</emphasis> is NULL and if the environment variable <function>\s-1RESOURCE_NAME\s+1</function> is set, the value of @@ -674,28 +568,25 @@ is the empty string, the application name is ``main''. <function>XtOpenDisplay</function> returns the newly opened display or NULL if it failed. </para> + <para> -<!-- .LP --> See Section 7.12 for information regarding the use of <function>XtOpenDisplay</function> in multiple threads. -<!-- .sp --> </para> + <para> -<!-- .LP --> To close a display and remove it from an application context, use -<function>XtCloseDisplay .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtCloseDisplay" "" "@DEF@" --> -<!-- .sM --> +<function>XtCloseDisplay</function>. </para> -<!-- .FD 0 --> -void XtCloseDisplay(<emphasis remap='I'>display</emphasis>) -<!-- .br --> - Display *<emphasis remap='I'>display</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtCloseDisplay'> +<funcprototype> + <funcdef>void <function>XtCloseDisplay</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -709,8 +600,6 @@ Specifies the display. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtCloseDisplay</function> function calls @@ -723,48 +612,40 @@ Note that applications need only call <function>XtCloseDisplay</function> if they are to continue executing after closing the display; otherwise, they should call -<function>XtDestroyApplicationContext .</function> +<function>XtDestroyApplicationContext</function>. </para> + <para> -<!-- .LP --> See Section 7.12 for information regarding the use of <function>XtCloseDisplay</function> in multiple threads. - </para> -</sect2> -<sect2 id="Establishing_the_Locale"> +</sect1> + +<sect1 id="Establishing_the_Locale"> <title>Establishing the Locale</title> -<!-- .XS --> -<!-- <function>(SN Establishing the Locale</function> --> -<!-- .XE --> <para> -<!-- .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 +per-screen resource database, the Intrinsics will call out to a specified application procedure to set the locale according to options found on the command line or in the per-display resource specifications. </para> + <para> -<!-- .LP --> The callout procedure provided by the application is of type -<function>XtLanguageProc .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtLanguageProc" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -typedef String (*XtLanguageProc)(Display*, String, XtPointer); -<!-- .br --> - Display *<emphasis remap='I'>display</emphasis>; -<!-- .br --> - String <emphasis remap='I'>language</emphasis>; -<!-- .br --> - XtPointer <emphasis remap='I'>client_data</emphasis>; -<!-- .FN --> +<function>XtLanguageProc</function>. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>String <function>(*XtLanguageProc)</function></funcdef> + <paramdef>Display<parameter> display</parameter></paramdef> + <paramdef>String<parameter> language</parameter></paramdef> + <paramdef>XtPointer<parameter> client_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -794,46 +675,39 @@ or server per-display resource specifications. <listitem> <para> Passes the additional client data specified in the call to -<function>XtSetLanguageProc .</function> +<function>XtSetLanguageProc</function>. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The language procedure allows an application to set the locale to the value of the language resource determined by -<function>XtDisplayInitialize .</function> +<function>XtDisplayInitialize</function>. The function returns a new language string that will be subsequently used by <function>XtDisplayInitialize</function> to establish the path for loading resource files. The returned -string will be copied by the (xI into new memory. +string will be copied by the Intrinsics into new memory. </para> + <para> -<!-- .LP --> -Initially, no language procedure is set by the (xI. +Initially, no language procedure is set by the Intrinsics. To set the language procedure for use by -<function>XtDisplayInitialize ,</function> +<function>XtDisplayInitialize</function>, use -<function>XtSetLanguageProc .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN XtSetLanguageProc "" "@DEF@" --> -<!-- .IN "language procedure" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -XtLanguageProc XtSetLanguageProc(<emphasis remap='I'>app_context</emphasis>, <emphasis remap='I'>proc</emphasis>, <emphasis remap='I'>client_data</emphasis>) -<!-- .br --> - XtAppContext <emphasis remap='I'>app_context</emphasis>; -<!-- .br --> - XtLanguageProc <emphasis remap='I'>proc</emphasis>; -<!-- .br --> - XtPointer <emphasis remap='I'>client_data</emphasis>; -<!-- .FN --> +<function>XtSetLanguageProc</function>. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>XtLanguageProc<function>XtSetLanguageProc</function></funcdef> + <paramdef>XtAppContext<parameter> app_context</parameter></paramdef> + <paramdef>XtLanguageProc<parameter> proc</parameter></paramdef> + <paramdef>XtPointer<parameter> client_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -869,8 +743,6 @@ procedure when it is called. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> <function>XtSetLanguageProc</function> sets the language procedure that will be called from <function>XtDisplayInitialize</function> @@ -884,11 +756,11 @@ registered. returns the previously registered language procedure. If a language procedure has not yet been registered, the return value is unspecified, but if this return value is used in a subsequent call to -<function>XtSetLanguageProc ,</function> +<function>XtSetLanguageProc</function>, it will cause the default language procedure to be registered. </para> + <para> -<!-- .LP --> The default language procedure does the following: </para> <itemizedlist> @@ -896,11 +768,11 @@ The default language procedure does the following: <para> Sets the locale according to the environment. On ANSI C-based systems this is done by calling -<function>setlocale (</function> -<function>LC_ALL ,</function> +<function>setlocale</function>( +<function>LC_ALL</function>, <emphasis remap='I'>language</emphasis> ). If an error is encountered, a warning message is issued with -<function>XtWarning .</function> +<function>XtWarning</function>. </para> </listitem> <listitem> @@ -924,40 +796,31 @@ specifying the empty string. <para> Returns the value of the current locale. On ANSI C-based systems this is the return value from a final call to -<function>setlocale (</function> -<function>LC_ALL ,</function> +<function>setlocale</function>( +<function>LC_ALL</function>, NULL ). </para> </listitem> </itemizedlist> <para> -<!-- .LP --> A client wishing to use this mechanism to establish locale can do so by calling <function>XtSetLanguageProc</function> prior to -<function>XtDisplayInitialize ,</function> +<function>XtDisplayInitialize</function>, as in the following example. </para> -<para> -<!-- .LP --> <literallayout class="monospaced"> -<!-- .TA .5i --> Widget top; XtSetLanguageProc(NULL, NULL, NULL); top = XtOpenApplication(...); ... </literallayout> +</sect1> -</para> -</sect2> -<sect2 id="Loading_the_Resource_Database"> +<sect1 id="Loading_the_Resource_Database"> <title>Loading the Resource Database</title> -<!-- .XS --> -<!-- <function>(SN Loading the Resource Database</function> --> -<!-- .XE --> <para> -<!-- .LP --> The <function>XtDisplayInitialize</function> function first determines the language @@ -965,7 +828,6 @@ string to be used for the specified display. It then creates a resource database for the default screen of the display by combining the following sources in order, with the entries in the first named source having highest precedence: - </para> <itemizedlist> <listitem> @@ -986,7 +848,6 @@ Per-screen resource specifications from the server. <listitem> <para> Per-display resource specifications from the server or from -<!-- .br --> the user preference file on the local host. </para> </listitem> @@ -998,19 +859,16 @@ Application-specific user resource file on the local host. <listitem> <para> Application-specific class resource file on the local host. - </para> </listitem> </itemizedlist> <para> -<!-- .LP --> When the resource database for a particular screen on the display is needed (either internally, or when <function>XtScreenDatabase</function> is called), it is created in the following manner using the sources listed above in the same order: - </para> <itemizedlist> <listitem> @@ -1023,8 +881,6 @@ or, if returns NULL, the contents of a resource file in the user's home directory. On POSIX-based systems, the usual name for this user preference resource file is $HOME/<function>.Xdefaults</function>. -<!-- .IN ".Xdefaults" "" "@DEF@" --> - </para> </listitem> <listitem> @@ -1042,23 +898,19 @@ queries the server resource database (which is assumed to be entirely in XPCS) for the resource <emphasis remap='I'>name</emphasis><function>.xnlLanguage</function>, class <emphasis remap='I'>Class</emphasis><function>.XnlLanguage</function> where <emphasis remap='I'>name</emphasis> -<!-- .IN "xnlLanguage" "" "@DEF@" --> -<!-- .IN "Resources" "xnlLanguage" --> and <emphasis remap='I'>Class</emphasis> are the <emphasis remap='I'>application_name</emphasis> and <emphasis remap='I'>application_class</emphasis> specified to -<function>XtDisplayInitialize .</function> +<function>XtDisplayInitialize</function>. 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. - +references in the Intrinsics that require the per-display language string. </para> </listitem> <listitem> <para> The screen resource database is initialized by parsing the command line in the manner specified by Section 2.4. - </para> </listitem> <listitem> @@ -1074,9 +926,8 @@ value of the <function>\s-1LANG\s+1</function> 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 +This language string is saved for all future references in the Intrinsics that require the per-display language string. - </para> </listitem> <listitem> @@ -1092,10 +943,9 @@ specified by the value of the environment variable. If this environment variable does not exist, the user's home directory is searched for a file named -<function>\&.Xdefaults-<emphasis remap='I'>host</emphasis> ,</function> +<function>.Xdefaults-</function><emphasis>host</emphasis>, where <emphasis remap='I'>host</emphasis> is the host name of the machine on which the application is running. - </para> </listitem> <listitem> @@ -1105,7 +955,6 @@ resource database, if they exist. These specifications are the string returned by <function>XScreenResourceString</function> for the respective screen and are owned entirely by the user. - </para> </listitem> <listitem> @@ -1113,7 +962,6 @@ for the respective screen and are owned entirely by the user. Next, the server resource database created earlier is merged into the screen resource database. The server property, and corresponding user preference file, are owned and constructed entirely by the user. - </para> </listitem> <listitem> @@ -1140,8 +988,6 @@ if this is defined. If <function>\s-1XUSERFILESEARCHPATH\s+1</function> is not defined, an implementation-dependent default value is used. This default value is constrained in the following manner: - -<!-- .RS --> </para> </listitem> <listitem> @@ -1151,25 +997,16 @@ If the environment variable is not defined, the default <function>\s-1XUSERFILESEARCHPATH\s+1</function> 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. - </para> </listitem> <listitem> @@ -1180,10 +1017,6 @@ is defined, the default <function>\s-1XUSERFILESEARCHPATH\s+1</function> 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 @@ -1191,13 +1024,9 @@ following directory prefixes and substitutions: 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 --> - </para> </listitem> <listitem> @@ -1216,7 +1045,7 @@ 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 -<function>XtAppSetFallbackResources .</function> +<function>XtAppSetFallbackResources</function>. Note that the customization substitution string is retrieved dynamically by <function>XtResolvePathname</function> @@ -1224,27 +1053,24 @@ 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 -<function>XtResolvePathname ,</function> +<function>XtResolvePathname</function>, the original display-associated database is restored. -<!-- .sp --> </para> </listitem> </itemizedlist> <para> -<!-- .LP --> To obtain the resource database for a particular screen, use -<function>XtScreenDatabase .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtScreenDatabase" "" "@DEF@" --> -<!-- .sM --> +<function>XtScreenDatabase</function>. </para> -<!-- .FD 0 --> -XrmDatabase XtScreenDatabase(<emphasis remap='I'>screen</emphasis>) -<!-- .br --> - Screen *<emphasis remap='I'>screen</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtScreenDatabase'> +<funcprototype> + <funcdef>XrmDatabase <function>XtScreenDatabase</function></funcdef> + <paramdef>Screen *<parameter>screen</parameter></paramdef> +</funcprototype> +</funcsynopsis> + + <variablelist> <varlistentry> <term> @@ -1258,8 +1084,6 @@ Specifies the screen whose resource database is to be returned. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtScreenDatabase</function> function returns the fully merged resource database as specified above, @@ -1267,25 +1091,24 @@ associated with the specified screen. If the specified <emphasis remap='I'>scre does not belong to a <function>Display</function> initialized by -<function>XtDisplayInitialize ,</function> +<function>XtDisplayInitialize</function>, the results are undefined. -<!-- .sp --> </para> + <para> -<!-- .LP --> To obtain the default resource database associated with a particular display, use -<function>XtDatabase .</function> +<function>XtDatabase</function>. </para> -<para> -<!-- .LP --> -<!-- .IN "XtDatabase" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -XrmDatabase XtDatabase(<emphasis remap='I'>display</emphasis>) -<!-- .br --> - Display *<emphasis remap='I'>display</emphasis>; -<!-- .FN --> + + +<funcsynopsis id='XtDatabase'> +<funcprototype> + <funcdef>XrmDatabase <function>XtDatabase</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> +</funcprototype> +</funcsynopsis> + + <variablelist> <varlistentry> <term> @@ -1299,36 +1122,30 @@ Specifies the display. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtDatabase</function> function is equivalent to -<function>XrmGetDatabase .</function> +<function>XrmGetDatabase</function>. It returns the database associated with the specified display, or NULL if a database has not been set. -<!-- .sp --> </para> + <para> -<!-- .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 -<function>XtAppSetFallbackResources .</function> +<function>XtAppSetFallbackResources</function>. </para> -<para> -<!-- .LP --> -<!-- .IN "XtAppSetFallbackResources" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -void XtAppSetFallbackResources(<emphasis remap='I'>app_context</emphasis>, <emphasis remap='I'>specification_list</emphasis>) -<!-- .br --> - XtAppContext <emphasis remap='I'>app_context</emphasis>; -<!-- .br --> - String *<emphasis remap='I'>specification_list</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtAppSetFallbackResources'> +<funcprototype> + <funcdef>void <function>XtAppSetFallbackResources</function></funcdef> + <paramdef>XtAppContext *<parameter>app_context</parameter></paramdef> + <paramdef>String *<parameter>specification_list</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -1355,14 +1172,12 @@ the database, or NULL. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> Each entry in <emphasis remap='I'>specification_list</emphasis> points to a string in the format of -<function>XrmPutLineResource .</function> +<function>XrmPutLineResource</function>. Following a call to -<function>XtAppSetFallbackResources ,</function> +<function>XtAppSetFallbackResources</function>, when a resource database is being created for a particular screen and -the (xI are not able +the Intrinsics are not able to find or read an application-specific class resource file according to the rules given above and if <emphasis remap='I'>specification_list</emphasis> is not NULL, the resource specifications in <emphasis remap='I'>specification_list</emphasis> will be merged @@ -1381,16 +1196,12 @@ is to provide a minimal number of resources that will make the application usable (or at least terminate with helpful diagnostic messages) when some problem exists in finding and loading the application defaults file. - </para> -</sect2> -<sect2 id="Parsing_the_Command_Line"> +</sect1> + +<sect1 id="Parsing_the_Command_Line"> <title>Parsing the Command Line</title> -<!-- .XS --> -<!-- <function>(SN Parsing the Command Line</function> --> -<!-- .XE --> <para> -<!-- .LP --> The <function>XtOpenDisplay</function> function first parses the command line for the following options: @@ -1402,7 +1213,7 @@ function first parses the command line for the following options: <listitem> <para> Specifies the display name for -<function>XOpenDisplay .</function> +<function>XOpenDisplay</function>. </para> </listitem> </varlistentry> @@ -1414,7 +1225,7 @@ Specifies the display name for <para> Sets the resource name prefix, which overrides the application name passed to -<function>XtOpenDisplay .</function> +<function>XtOpenDisplay</function>. </para> </listitem> </varlistentry> @@ -1431,23 +1242,17 @@ and for finding application class resource files. </varlistentry> </variablelist> </para> + <para> -<!-- .LP --> <function>XtDisplayInitialize</function> has a table of standard command line options that are passed to <function>XrmParseCommand</function> for adding resources to the resource database, and it takes as a parameter additional application-specific resource abbreviations. -<!-- .IN "XrmOptionDescRec" "" "@DEF@" --> The format of this table is described in Section 15.9 in <emphasis remap='I'>(xL</emphasis>. </para> -<para> -<!-- .LP --> -<!-- .sM --> <literallayout class="monospaced"> -<!-- .TA .5i 2.75i --> -<!-- .ta .5i 2.75i --> typedef enum { XrmoptionNoArg, /* Value is specified in OptionDescRec.value */ XrmoptionIsArg, /* Value is the option string itself */ @@ -1459,104 +1264,44 @@ typedef enum { /* OptionDescRec.value arguments in argv */ XrmoptionSkipLine /* Ignore this option and the rest of argv */ } XrmOptionKind; - typedef struct { char *option; /* Option name in argv */ char *specifier; /* Resource name (without application name) */ XrmOptionKind argKind; /* Location of the resource value */ XPointer value; /* Value to provide if XrmoptionNoArg */ } XrmOptionDescRec, *XrmOptionDescList; - </literallayout> -</para> <para> -<!-- .LP --> -<!-- .eM --> The standard table contains the following entries: <informaltable> - <tgroup cols='' align='center'> + <tgroup cols='3' align='center'> <tbody> <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> - </row> - <row> + <entry></entry> + <entry></entry> + <entry></entry> </row> </tbody> </tgroup> </informaltable> </para> + <para> -<!-- .LP --> Note that any unique abbreviation for an option name in the standard table or in the application table is accepted. </para> + <para> -<!-- .LP --> If reverseVideo is -<function>True ,</function> +<function>True</function>, the values of <function>XtDefaultForeground</function> and <function>XtDefaultBackground</function> are exchanged for all screens on the Display. </para> + <para> -<!-- .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, @@ -1569,33 +1314,27 @@ when multiple displays are initialized in the same application context, the most recent value specified for the synchronous resource is used for all displays in the application context. </para> + <para> -<!-- .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. </para> + <para> -<!-- .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 -<function>xmh ,</function> +<function>xmh</function>, you can start it up as </para> -<para> -<!-- .LP --> <literallayout class="monospaced"> xmh \-xrm 'xmh*Command.background: red' </literallayout> -</para> <para> -<!-- .LP --> When it parses the command line, <function>XtDisplayInitialize</function> merges the application option table with the standard option table @@ -1606,18 +1345,14 @@ 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 +The Intrinsics reserve all option names beginning with the characters ``-xt'' for future standard uses. - </para> -</sect2> -<sect2 id="Creating_Widgets"> +</sect1> + +<sect1 id="Creating_Widgets"> <title>Creating Widgets</title> -<!-- .XS --> -<!-- <function>(SN Creating Widgets</function> --> -<!-- .XE --> <para> -<!-- .LP --> The creation of widget instances is a three-phase process: </para> <itemizedlist> @@ -1640,26 +1375,21 @@ The widgets create X windows, which then are mapped. </listitem> </itemizedlist> <para> -<!-- .LP --> -<!-- .EQ --> delim $$ -<!-- .EN --> To start the first phase, the application calls <function>XtCreateWidget</function> for all its widgets and adds some (usually, most or all) of its widgets to their respective parents' managed set by calling -<function>XtManageChild .</function> +<function>XtManageChild</function>. 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 --> </para> + <para> -<!-- .LP --> After all widgets have been created, the application calls <function>XtRealizeWidget</function> @@ -1669,8 +1399,8 @@ first recursively traverses the widget tree in a postorder (bottom-up) traversal and then notifies each composite widget with one or more managed children by means of its change_managed procedure. </para> + <para> -<!-- .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 @@ -1685,84 +1415,67 @@ accommodate all its children. You cannot predict where anything will go on the screen until this process finishes. </para> + <para> -<!-- .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. </para> + <para> -<!-- .LP --> Finally, <function>XtRealizeWidget</function> starts the third phase by making a preorder (top-down) traversal of the widget tree, allocates an X window to each widget by means of its realize procedure, and finally maps the widgets that are managed. - </para> -<sect3 id="Creating_and_Merging_Argument_Lists"> + +<sect2 id="Creating_and_Merging_Argument_Lists"> <title>Creating and Merging Argument Lists</title> -<!-- .XS --> -<!-- <function>(SN Creating and Merging Argument Lists</function> --> -<!-- .XE --> <para> -<!-- .LP --> -Many (xI functions may be passed pairs of resource names and +Many Intrinsics functions may be passed pairs of resource names and values. These are passed as an arglist, a pointer to an array of <function>Arg</function> structures, which contains -<!-- .IN "ArgList" "" "@DEF@" --> -<!-- .IN "Arg" "" "@DEF@" --> </para> -<para> -<!-- .LP --> -<!-- .sM --> <literallayout class="monospaced"> -<!-- .TA .5i 3i --> -<!-- .ta .5i 3i --> typedef struct { String name; XtArgVal value; } Arg, *ArgList; </literallayout> -</para> <para> -<!-- .LP --> -<!-- .eM --> where <function>XtArgVal</function> is as defined in Section 1.5. </para> + <para> -<!-- .LP --> If the size of the resource is less than or equal to the size of an -<function>XtArgVal ,</function> +<function>XtArgVal</function>, the resource value is stored directly in <emphasis remap='I'>value</emphasis>; otherwise, a pointer to it is stored in <emphasis remap='I'>value</emphasis>. </para> + <para> -<!-- .LP --> To set values in an -<function>ArgList ,</function> +<function>ArgList</function>, use -<function>XtSetArg .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtSetArg" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -void XtSetArg(<emphasis remap='I'>arg</emphasis>, <emphasis remap='I'>name</emphasis>, <emphasis remap='I'>value</emphasis>) -<!-- .br --> - Arg <emphasis remap='I'>arg</emphasis>; -<!-- .br --> - String <emphasis remap='I'>name</emphasis>; -<!-- .br --> - XtArgVal <emphasis remap='I'>value</emphasis>; -<!-- .FN --> +<function>XtSetArg</function>. +</para> + +<funcsynopsis id='XtSetArg'> +<funcprototype> + <funcdef>void <function>XtSetArg</function></funcdef> + <paramdef>Arg<parameter> arg</parameter></paramdef> + <paramdef>String<parameter> name</parameter></paramdef> + <paramdef>XtArgVal<parameter> value</parameter></paramdef> +</funcprototype> +</funcsynopsis> + + <variablelist> <varlistentry> <term> @@ -1791,85 +1504,64 @@ Specifies the name of the resource. <listitem> <para> Specifies the value of the resource if it will fit in an -<function>XtArgVal ,</function> +<function>XtArgVal</function>, else the address. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtSetArg</function> function is usually used in a highly stylized manner to minimize the probability of making a mistake; for example: </para> -<para> -<!-- .LP --> <literallayout class="monospaced"> -<!-- .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); </literallayout> -</para> <para> -<!-- .LP --> Alternatively, an application can statically declare the argument list and use -<function>XtNumber :</function> +<function>XtNumber</function>: </para> -<para> -<!-- .LP --> <literallayout class="monospaced"> -<!-- .TA .5i 3i --> -<!-- .ta .5i 3i --> static Args args[] = { {XtNheight, (XtArgVal) 100}, {XtNwidth, (XtArgVal) 200}, }; XtSetValues(Widget, args, XtNumber(args)); </literallayout> -</para> <para> -<!-- .LP --> Note that you should not use expressions with side effects such as auto-increment or auto-decrement within the first argument to -<function>XtSetArg .</function> +<function>XtSetArg</function>. <function>XtSetArg</function> can be implemented as a macro that evaluates the first argument twice. -<!-- .sp --> </para> + <para> -<!-- .LP --> To merge two arglist arrays, use -<function>XtMergeArgLists .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtMergeArgLists" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -ArgList XtMergeArgLists(<emphasis remap='I'>args1</emphasis>, <emphasis remap='I'>num_args1</emphasis>, <emphasis remap='I'>args2</emphasis>, \ -<emphasis remap='I'>num_args2</emphasis>) -<!-- .br --> - ArgList <emphasis remap='I'>args1</emphasis>; -<!-- .br --> - Cardinal <emphasis remap='I'>num_args1</emphasis>; -<!-- .br --> - ArgList <emphasis remap='I'>args2</emphasis>; -<!-- .br --> - Cardinal <emphasis remap='I'>num_args2</emphasis>; -<!-- .FN --> +<function>XtMergeArgLists</function>. +</para> + +<funcsynopsis id='XtMergeArgLists'> +<funcprototype> + <funcdef>ArgList <function>XtMergeArgLists</function></funcdef> + <paramdef>ArgList <parameter>args1</parameter></paramdef> + <paramdef>Cardinal <parameter>num_args1</parameter></paramdef> + <paramdef>ArgList <parameter>args2</parameter></paramdef> + <paramdef>Cardinal <parameter>num_args2</parameter></paramdef> +</funcprototype> +</funcsynopsis> + + <variablelist> <varlistentry> <term> @@ -1913,8 +1605,6 @@ Specifies the number of entries in the second argument list. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtMergeArgLists</function> function allocates enough storage to hold the combined @@ -1924,13 +1614,11 @@ 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 -<function>XtFree .</function> -<!-- .sp --> +<function>XtFree</function>. </para> + <para> -<!-- .LP --> -<!-- .IN "varargs" "" "@DEF@" --> -All (xI interfaces that require +All Intrinsics interfaces that require <function>ArgList</function> arguments have analogs conforming to the ANSI C variable argument list @@ -1939,51 +1627,43 @@ calling convention. The name of the analog is formed by prefixing ``Va'' to the name of the corresponding <function>ArgList</function> procedure; e.g., -<function>XtVaCreateWidget .</function> +<function>XtVaCreateWidget</function>. Each procedure named <function>XtVa</function><emphasis remap='I'>something</emphasis> takes as its last arguments, in place of the corresponding -<function>ArgList /</function> +<function>ArgList</function>/ <function>Cardinal</function> parameters, a variable parameter list of resource name and value pairs where each name is of type <function>String</function> and each value is of type -<function>XtArgVal .</function> +<function>XtArgVal</function>. The end of the list is identified by a <emphasis remap='I'>name</emphasis> entry containing NULL. Developers writing in the C language wishing to pass resource name and value pairs to any of these interfaces may use the <function>ArgList</function> and varargs forms interchangeably. </para> + <para> -<!-- .LP --> Two special names are defined for use only in varargs lists: <function>XtVaTypedArg</function> and -<function>XtVaNestedList .</function> -<!-- .sp --> +<function>XtVaNestedList</function>. </para> -<para> -<!-- .LP --> -<!-- .IN "XtVaTypedArg" "" "@DEF@" --> -<!-- .sM --> <literallayout class="monospaced"> #define XtVaTypedArg "XtVaTypedArg" </literallayout> -</para> <para> -<!-- .LP --> -<!-- .eM --> If the name <function>XtVaTypedArg</function> is specified in place of a resource name, then the following four arguments are interpreted as a <emphasis remap='I'>name/type/value/size</emphasis> tuple <emphasis remap='I'>where</emphasis> name is of type -<function>String ,</function> +<function>String</function>, <emphasis remap='I'>type</emphasis> is of type -<function>String ,</function> +<function>String</function>, <emphasis remap='I'>value</emphasis> is of type -<function>XtArgVal ,</function> +<function>XtArgVal</function>, and <emphasis remap='I'>size</emphasis> is of type int. When a varargs list containing <function>XtVaTypedArg</function> is processed, a resource type @@ -1994,23 +1674,15 @@ contains the number of bytes allocated, including the trailing null byte. If <emphasis remap='I'>type</emphasis> is not XtRString, then <emphasis remap='I'>if</emphasis> size is less than or equal to <function>sizeof</function>(<function>XtArgVal</function>), the value should be the data cast to the type -<function>XtArgVal ,</function> +<function>XtArgVal</function>, otherwise <emphasis remap='I'>value</emphasis> is a pointer to the data. If the type conversion fails for any reason, a warning message is issued and the list entry is skipped. -<!-- .sp --> </para> -<para> -<!-- .LP --> -<!-- .IN "XtVaNestedList" "" "@DEF@" --> -<!-- .sM --> <literallayout class="monospaced"> #define XtVaNestedList "XtVaNestedList" </literallayout> -</para> <para> -<!-- .LP --> -<!-- .eM --> If the name <function>XtVaNestedList</function> is specified in place of a resource name, @@ -2020,32 +1692,25 @@ 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 --> </para> + <para> -<!-- .LP --> To dynamically allocate a varargs list for use with <function>XtVaNestedList</function> in multiple calls, use -<function>XtVaCreateArgsList .</function> -<!-- .IN "XtVaCreateArgsList" "" "@DEF@" --> -<!-- .sp --> +<function>XtVaCreateArgsList</function>. </para> -<para> -<!-- .LP --> -<!-- .sM --> <literallayout class="monospaced"> typedef XtPointer XtVarArgsList; </literallayout> -</para> -<para> -<!-- .LP --> -</para> -<!-- .FD 0 --> -XtVarArgsList XtVaCreateArgsList(<emphasis remap='I'>unused</emphasis>, ...) -<!-- .br --> - XtPointer <emphasis remap='I'>unused</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtVaCreateArgsList'> +<funcprototype> + <funcdef>XtVarArgsList <function>XtVaCreateArgsList</function></funcdef> + <paramdef>XtPointer <parameter>unused</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -2070,13 +1735,11 @@ name and value pairs. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtVaCreateArgsList</function> function allocates memory and copies its arguments into a single list pointer, which may be used with -<function>XtVaNestedList .</function> +<function>XtVaNestedList</function>. The end of both lists is identified by a <emphasis remap='I'>name</emphasis> entry containing NULL. Any entries of type @@ -2089,43 +1752,33 @@ list should be freed using <function>XtFree</function> when no longer needed. </para> + <para> -<!-- .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. - </para> -</sect3> -<sect3 id="Creating_a_Widget_Instance"> +</sect2> + +<sect2 id="Creating_a_Widget_Instance"> <title>Creating a Widget Instance</title> -<!-- .XS --> -<!-- <function>(SN Creating a Widget Instance</function> --> -<!-- .XE --> <para> -<!-- .LP --> To create an instance of a widget, use -<function>XtCreateWidget .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtCreateWidget" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -Widget XtCreateWidget(<emphasis remap='I'>name</emphasis>, <emphasis remap='I'>object_class</emphasis>, <emphasis remap='I'>parent</emphasis>, \ -<emphasis remap='I'>args</emphasis>, <emphasis remap='I'>num_args</emphasis>) -<!-- .br --> - String <emphasis remap='I'>name</emphasis>; -<!-- .br --> - WidgetClass <emphasis remap='I'>object_class</emphasis>; -<!-- .br --> - Widget <emphasis remap='I'>parent</emphasis>; -<!-- .br --> - ArgList <emphasis remap='I'>args</emphasis>; -<!-- .br --> - Cardinal <emphasis remap='I'>num_args</emphasis>; -<!-- .FN --> +<function>XtCreateWidget</function>. +</para> + +<funcsynopsis id='XtCreateWidget'> +<funcprototype> + <funcdef>Widget <function>XtCreateWidget</function></funcdef> + <paramdef>String <parameter>name</parameter></paramdef> + <paramdef>WidgetClass <parameter>object_class</parameter></paramdef> + <paramdef>Widget <parameter>parent</parameter></paramdef> + <paramdef>ArgList <parameter>args</parameter></paramdef> + <paramdef>Cardinal <parameter>num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> + + <variablelist> <varlistentry> <term> @@ -2156,7 +1809,7 @@ Specifies the widget class pointer for the created object. (oC </term> <listitem> <para> -Specifies the parent widget. (oI +Specifies the parent widget. Must be of class Object or any subclass thereof. </para> </listitem> </varlistentry> @@ -2182,8 +1835,6 @@ Specifies the number of entries in the argument list. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtCreateWidget</function> function performs all the boilerplate operations of widget @@ -2210,7 +1861,7 @@ the parent's composite class part extension field exists with the <function>\s-1NULLQUARK\s+1</function> or the <emphasis remap='I'>accepts_objects</emphasis> field in the extension record is -<function>False ,</function> +<function>False</function>, <function>XtCreateWidget</function> issues a fatal error; see Section 3.1 and Chapter 12. </para> @@ -2223,10 +1874,10 @@ part <emphasis remap='I'>extension</emphasis> field with <emphasis remap='I'>rec and the <emphasis remap='I'>allocate</emphasis> field is not NULL, the procedure is invoked to allocate memory for the widget instance. If the parent is a member of the class -<function>constraintWidgetClass ,</function> +<function>constraintWidgetClass</function>, the procedure also allocates memory for the parent's constraints and stores the address of this memory into the -<emphasis remap='I'>constraints</emphasis> field. If no allocate procedure is found, the (xI +<emphasis remap='I'>constraints</emphasis> field. If no allocate procedure is found, the Intrinsics allocate memory for the widget and, when applicable, the constraints, and initializes the <emphasis remap='I'>constraints</emphasis> field. </para> @@ -2250,13 +1901,13 @@ resource lists specified for this class and all superclasses. <listitem> <para> If the parent is a member of the class -<function>constraintWidgetClass ,</function> +<function>constraintWidgetClass</function>, initializes the resource fields of the constraints record by using the <function>ConstraintClassPart</function> resource lists specified for the parent's class and all superclasses up to -<function>constraintWidgetClass .</function> +<function>constraintWidgetClass</function>. </para> </listitem> <listitem> @@ -2269,7 +1920,7 @@ initialize procedure on down to the widget's initialize procedure. <listitem> <para> If the parent is a member of the class -<function>constraintWidgetClass ,</function> +<function>constraintWidgetClass</function>, calls the <function>ConstraintClassPart</function> initialize procedures, @@ -2283,34 +1934,29 @@ initialize procedure. <listitem> <para> If the parent is a member of the class -<function>compositeWidgetClass ,</function> +<function>compositeWidgetClass</function>, 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 --> </para> </listitem> </itemizedlist> <para> -<!-- .LP --> To create an instance of a widget using varargs lists, use -<function>XtVaCreateWidget .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtVaCreateWidget" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -Widget XtVaCreateWidget(<emphasis remap='I'>name</emphasis>, <emphasis remap='I'>object_class</emphasis>, <emphasis remap='I'>parent</emphasis>, ...) -<!-- .br --> - String <emphasis remap='I'>name</emphasis>; -<!-- .br --> - WidgetClass <emphasis remap='I'>object_class</emphasis>; -<!-- .br --> - Widget <emphasis remap='I'>parent</emphasis>; -<!-- .FN --> +<function>XtVaCreateWidget</function>. +</para> + +<funcsynopsis id='XtVaCreateWidget'> +<funcprototype> + <funcdef>Widget <function>XtVaCreateWidget</function></funcdef> + <paramdef>String <parameter>name</parameter></paramdef> + <paramdef>WidgetClass <parameter>object_class</parameter></paramdef> + <paramdef>Widget <parameter>parent</parameter></paramdef> +</funcprototype> +</funcsynopsis> + + <variablelist> <varlistentry> <term> @@ -2338,7 +1984,7 @@ Specifies the widget class pointer for the created object. (oC </term> <listitem> <para> -Specifies the parent widget. (oI +Specifies the parent widget. Must be of class Object or any subclass thereof. </para> </listitem> </varlistentry> @@ -2355,8 +2001,6 @@ resource specifications. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtVaCreateWidget</function> procedure is identical in function to @@ -2364,16 +2008,12 @@ procedure is identical in function to with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as described in Section 2.5.1. - </para> -</sect3> -<sect3 id="Creating_an_Application_Shell_Instance"> +</sect2> + +<sect2 id="Creating_an_Application_Shell_Instance"> <title>Creating an Application Shell Instance</title> -<!-- .XS --> -<!-- <function>(SN Creating an Application Shell Instance</function> --> -<!-- .XE --> <para> -<!-- .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. @@ -2381,28 +2021,20 @@ An application uses <function>XtAppCreateShell</function> to create independent widget trees. </para> -<para> -<!-- .LP --> -<!-- .IN "XtAppCreateShell" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -Widget XtAppCreateShell(<emphasis remap='I'>name</emphasis>, \ -<emphasis remap='I'>application_class</emphasis>, <emphasis remap='I'>widget_class</emphasis>, <emphasis remap='I'>display</emphasis>, \ -<emphasis remap='I'>args</emphasis>, <emphasis remap='I'>num_args</emphasis>) -<!-- .br --> - String <emphasis remap='I'>name</emphasis>; -<!-- .br --> - String <emphasis remap='I'>application_class</emphasis>; -<!-- .br --> - WidgetClass <emphasis remap='I'>widget_class</emphasis>; -<!-- .br --> - Display *<emphasis remap='I'>display</emphasis>; -<!-- .br --> - ArgList <emphasis remap='I'>args</emphasis>; -<!-- .br --> - Cardinal <emphasis remap='I'>num_args</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtAppCreateShell'> +<funcprototype> + <funcdef>Widget <function>XtAppCreateShell</function></funcdef> + <paramdef>String <parameter>name</parameter></paramdef> + <paramdef>String <parameter>application_class</parameter></paramdef> + <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef> + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>ArgList <parameter>args</parameter></paramdef> + <paramdef>Cardinal <parameter>num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> + + <variablelist> <varlistentry> <term> @@ -2477,8 +2109,6 @@ Specifies the number of entries in the argument list. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtAppCreateShell</function> function @@ -2503,10 +2133,9 @@ all remaining resources for the shell widget not specified in <emphasis remap='I'>args</emphasis>. The widget name and <emphasis remap='I'>Class</emphasis> as determined above are used as the leftmost (i.e., root) components in all fully qualified resource names for objects within this widget tree. - </para> + <para> -<!-- .LP --> If the specified widget class is a subclass of WMShell, the name and <emphasis remap='I'>Class</emphasis> as determined above will be stored into the <function>\s-1WM_CLASS\s+1</function> @@ -2517,10 +2146,9 @@ or a subclass thereof, the <function>\s-1WM_COMMAND\s+1</function> property will also be set from the values of the XtNargv and XtNargc resources. - </para> + <para> -<!-- .LP --> To create multiple top-level shells within a single (logical) application, you can use one of two methods: @@ -2530,7 +2158,7 @@ you can use one of two methods: <para> Designate one shell as the real top-level shell and create the others as pop-up children of it by using -<function>XtCreatePopupShell .</function> +<function>XtCreatePopupShell</function>. </para> </listitem> <listitem> @@ -2540,61 +2168,41 @@ Have all shells as pop-up children of an unrealized top-level shell. </listitem> </itemizedlist> <para> -<!-- .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: </para> -<para> -<!-- .LP --> <literallayout class="monospaced"> -<!-- .TA 2i --> -<!-- .ta 2i --> xmail.geometry:... (the main window) xmail.read.geometry:... (the read window) xmail.compose.geometry:... (the compose window) </literallayout> -</para> <para> -<!-- .LP --> The second method, which is best if there is no main window, leads to resource specifications like the following: </para> -<para> -<!-- .LP --> <literallayout class="monospaced"> -<!-- .TA 2i --> -<!-- .ta 2i --> xmail.headers.geometry:... (the headers window) xmail.read.geometry:... (the read window) xmail.compose.geometry:... (the compose window) </literallayout> -<!-- .sp --> -</para> <para> -<!-- .LP --> To create a top-level widget that is the root of a widget tree using varargs lists, use -<function>XtVaAppCreateShell .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtVaAppCreateShell" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -Widget XtVaAppCreateShell(<emphasis remap='I'>name</emphasis>, <emphasis remap='I'>application_class</emphasis>, \ -<emphasis remap='I'>widget_class</emphasis>, <emphasis remap='I'>display</emphasis>, ...) -<!-- .br --> - String <emphasis remap='I'>name</emphasis>; -<!-- .br --> - String <emphasis remap='I'>application_class</emphasis>; -<!-- .br --> - WidgetClass <emphasis remap='I'>widget_class</emphasis>; -<!-- .br --> - Display *<emphasis remap='I'>display</emphasis>; -<!-- .FN --> +<function>XtVaAppCreateShell</function>. +</para> + +<funcsynopsis id='XtVaAppCreateShell'> +<funcprototype> + <funcdef>Widget <function>XtVaAppCreateShell</function></funcdef> + <paramdef>String <parameter>name</parameter></paramdef> + <paramdef>String <parameter>application_class</parameter></paramdef> + <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef> + <paramdef>Display *<parameter>display</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -2659,63 +2267,42 @@ resource specifications. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtVaAppCreateShell</function> procedure is identical in function to <function>XtAppCreateShell</function> with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as described in Section 2.5.1. - </para> -</sect3> -<sect3 id="Convenience_Procedure_to_Initialize_an_Application"> +</sect2> + +<sect2 id="Convenience_Procedure_to_Initialize_an_Application"> <title>Convenience Procedure to Initialize an Application</title> -<!-- .XS --> -<!-- <function>(SN Convenience Procedure to Initialize an Application</function> --> -<!-- .XE --> <para> -<!-- .LP --> -To initialize the (xI internals, create an application context, +To initialize the Intrinsics internals, create an application context, open and initialize a display, and create the initial root shell instance, an application may use <function>XtOpenApplication</function> or -<function>XtVaOpenApplication .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtOpenApplication" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -Widget XtOpenApplication(<emphasis remap='I'>app_context_return</emphasis>, <emphasis remap='I'>application_class</emphasis>, \ -<emphasis remap='I'>options</emphasis>, <emphasis remap='I'>num_options</emphasis>, -<!-- .br --> - <emphasis remap='I'>argc_in_out</emphasis>, <emphasis remap='I'>argv_in_out</emphasis>, \ -<emphasis remap='I'>fallback_resources</emphasis>, <emphasis remap='I'>widget_class</emphasis>, <emphasis remap='I'>args</emphasis>, <emphasis remap='I'>num_args</emphasis>) -<!-- .br --> - XtAppContext *<emphasis remap='I'>app_context_return</emphasis>; -<!-- .br --> - String <emphasis remap='I'>application_class</emphasis>; -<!-- .br --> - XrmOptionDescList <emphasis remap='I'>options</emphasis>; -<!-- .br --> - Cardinal <emphasis remap='I'>num_options</emphasis>; -<!-- .br --> - int *<emphasis remap='I'>argc_in_out</emphasis>; -<!-- .br --> - String *<emphasis remap='I'>argv_in_out</emphasis>; -<!-- .br --> - String *<emphasis remap='I'>fallback_resources</emphasis>; -<!-- .br --> - WidgetClass <emphasis remap='I'>widget_class</emphasis>; -<!-- .br --> - ArgList <emphasis remap='I'>args</emphasis>; -<!-- .br --> - Cardinal <emphasis remap='I'>num_args</emphasis>; -<!-- .FN --> +<function>XtVaOpenApplication</function>. +</para> + +<funcsynopsis id='XtOpenApplication'> +<funcprototype> + <funcdef>Widget <function>XtOpenApplication</function></funcdef> + <paramdef>XtAppContext *<parameter>app_context_return</parameter></paramdef> + <paramdef>String <parameter>application_class</parameter></paramdef> + <paramdef>XrmOptionDescList <parameter>options</parameter></paramdef> + <paramdef>Cardinal <parameter>num_options</parameter></paramdef> + <paramdef>int *<parameter>argc_in_out</parameter></paramdef> + <paramdef>String *<parameter>argv_in_out</parameter></paramdef> + <paramdef>String *<parameter>fallback_resources</parameter></paramdef> + <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef> + <paramdef>ArgList <parameter>args</parameter></paramdef> + <paramdef>Cardinal <parameter>num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -2796,7 +2383,6 @@ file cannot be opened or read, or NULL. <para> Specifies the class of the widget to be created. Must be shellWidgetClass or a subclass. -<!-- .br --> </para> </listitem> </varlistentry> @@ -2823,14 +2409,12 @@ Specifies the number of entries in the argument list. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtOpenApplication</function> function calls <function>XtToolkitInitialize</function> followed by -<function>XtCreateApplicationContext ,</function> +<function>XtCreateApplicationContext</function>, then calls <function>XtOpenDisplay</function> with <emphasis remap='I'>display_string</emphasis> NULL and @@ -2840,7 +2424,7 @@ with <emphasis remap='I'>name</emphasis> NULL, the specified <emphasis remap='I' an argument list and count, and returns the created shell. The recommended <emphasis remap='I'>widget_class</emphasis> is -<function>sessionShellWidgetClass .</function> +<function>sessionShellWidgetClass</function>. The argument list and count are created by merging the specified <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> with a list containing the specified <emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis>. @@ -2854,37 +2438,23 @@ opened, an error message is issued and terminates the application. If <emphasis remap='I'>fallback_resources</emphasis> is non-NULL, <function>XtAppSetFallbackResources</function> is called with the value prior to calling -<function>XtOpenDisplay .</function> -<!-- .sp --> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtVaOpenApplication" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -Widget XtVaOpenApplication(<emphasis remap='I'>app_context_return</emphasis>, <emphasis remap='I'>application_class</emphasis>, \ -<emphasis remap='I'>options</emphasis>, <emphasis remap='I'>num_options</emphasis>, -<!-- .br --> - <emphasis remap='I'>argc_in_out</emphasis>, <emphasis remap='I'>argv_in_out</emphasis>, \ -<emphasis remap='I'>fallback_resources</emphasis>, <emphasis remap='I'>widget_class</emphasis>, ...) -<!-- .br --> - XtAppContext *<emphasis remap='I'>app_context_return</emphasis>; -<!-- .br --> - String <emphasis remap='I'>application_class</emphasis>; -<!-- .br --> - XrmOptionDescList <emphasis remap='I'>options</emphasis>; -<!-- .br --> - Cardinal <emphasis remap='I'>num_options</emphasis>; -<!-- .br --> - int *<emphasis remap='I'>argc_in_out</emphasis>; -<!-- .br --> - String *<emphasis remap='I'>argv_in_out</emphasis>; -<!-- .br --> - String *<emphasis remap='I'>fallback_resources</emphasis>; -<!-- .br --> - WidgetClass <emphasis remap='I'>widget_class</emphasis>; -<!-- .FN --> +<function>XtOpenDisplay</function>. +</para> + +<funcsynopsis id='XtVaOpenApplication'> +<funcprototype> + <funcdef>Widget <function>XtVaOpenApplication</function></funcdef> + <paramdef>XtAppContext *<parameter>app_context_return</parameter></paramdef> + <paramdef>String <parameter>application_class</parameter></paramdef> + <paramdef>XrmOptionDescList <parameter>options</parameter></paramdef> + <paramdef>Cardinal <parameter>num_options</parameter></paramdef> + <paramdef>int *<parameter>argc_in_out</parameter></paramdef> + <paramdef>String *<parameter>argv_in_out</parameter></paramdef> + <paramdef>String *<parameter>fallback_resources</parameter></paramdef> + <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -2981,8 +2551,6 @@ resource specifications for the created shell. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtVaOpenApplication</function> procedure is identical in function to @@ -2990,36 +2558,25 @@ procedure is identical in function to with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, as described in Section 2.5.1. - </para> -</sect3> -<sect3 id="Widget_Instance_Allocation_The_allocate_Procedure"> +</sect2> + +<sect2 id="Widget_Instance_Allocation_The_allocate_Procedure"> <title>Widget Instance Allocation: The allocate Procedure</title> -<!-- .XS --> -<!-- (SN Widget Instance Allocation: The allocate Procedure --> -<!-- .XE --> -<!-- .IN "Widget Allocation" --> <para> -<!-- .LP --> A widget class may optionally provide an instance allocation procedure in the <function>ObjectClassExtension</function> record. </para> + <para> -<!-- .LP --> When the call to create a widget includes a varargs list containing -<function>XtVaTypedArg ,</function> +<function>XtVaTypedArg</function>, these arguments will be passed to the allocation procedure in an -<function>XtTypedArgList .</function> +<function>XtTypedArgList</function>. </para> -<para> -<!-- .LP --> -<!-- .IN "XtTypedArgList" "" "@DEF@" --> -<!-- .sM --> <literallayout class="monospaced"> -<!-- .TA .5i 3i --> -<!-- .ta .5i 3i --> typedef struct { String name; String type; @@ -3027,45 +2584,28 @@ typedef struct { int size; } XtTypedArg, *XtTypedArgList; </literallayout> -</para> <para> -<!-- .LP --> -<!-- .eM --> -<!-- .IN "allocate procedure" "" "@DEF@" --> The allocate procedure pointer in the <function>ObjectClassExtension</function> record is of type -<function>XtAllocateProc .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtAllocateProc" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -typedef void (*XtAllocateProc)(WidgetClass, Cardinal*, Cardinal*, ArgList, \ -Cardinal*, - XtTypedArgList, Cardinal*, \ -Widget*, XtPointer*); -<!-- .br --> - WidgetClass <emphasis remap='I'>widget_class</emphasis>; -<!-- .br --> - Cardinal* <emphasis remap='I'>constraint_size</emphasis>; -<!-- .br --> - Cardinal* <emphasis remap='I'>more_bytes</emphasis>; -<!-- .br --> - ArgList <emphasis remap='I'>args</emphasis>; -<!-- .br --> - Cardinal* <emphasis remap='I'>num_args</emphasis>; -<!-- .br --> - XtTypedArgList <emphasis remap='I'>typed_args</emphasis>, -<!-- .br --> - Cardinal* <emphasis remap='I'>num_typed_args</emphasis>; -<!-- .br --> - Widget* <emphasis remap='I'>new_return</emphasis>; -<!-- .br --> - XtPointer* <emphasis remap='I'>more_bytes_return</emphasis>; -<!-- .FN --> +<function>XtAllocateProc</function>. +</para> + +<funcsynopsis id='XtAppContext'> +<funcprototype> + <funcdef>void <function>(*XtAppContext)</function></funcdef> + <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef> + <paramdef>Cardinal* <parameter>constraint_size</parameter></paramdef> + <paramdef>Cardinal* <parameter>more_bytes</parameter></paramdef> + <paramdef>ArgList <parameter>args</parameter></paramdef> + <paramdef>Cardinal* <parameter>num_args</parameter></paramdef> + <paramdef>XtTypedArgList <parameter>typed_args</parameter></paramdef> + <paramdef>Cardinal* <parameter>num_typed_args</parameter></paramdef> + <paramdef>Widget* <parameter>new_return</parameter></paramdef> + <paramdef>XtPointer* <parameter>more_bytes_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -3160,8 +2700,6 @@ if requested and an error occurred; otherwise, unchanged. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> At widget allocation time, if an extension record with <emphasis remap='I'>record_type</emphasis> equal to <function>\s-1NULLQUARK\s+1</function> @@ -3170,7 +2708,7 @@ and the <emphasis remap='I'>allocate</emphasis> field is not NULL, the <function>XtAllocateProc</function> will be invoked to allocate memory for the widget. If no ObjectClassPart extension record is declared with <emphasis remap='I'>record_type equal</emphasis> to -<function>\s-1NULLQUARK\s+1 ,</function> +<function>\s-1NULLQUARK\s+1</function>, then <function>XtInheritAllocate</function> and @@ -3178,10 +2716,10 @@ and are assumed. If no <function>XtAllocateProc</function> -is found, the (xI will allocate memory for the widget. +is found, the Intrinsics will allocate memory for the widget. </para> + <para> -<!-- .LP --> An <function>XtAllocateProc</function> must perform the following: @@ -3212,7 +2750,6 @@ or NULL to indicate an error. </listitem> </itemizedlist> <para> -<!-- .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. @@ -3221,40 +2758,26 @@ widget record except to store pointers to newly allocated additional memory. Under no circumstances should an allocation procedure that envelopes its superclass allocation procedure modify fields in the instance part of any superclass. - </para> -</sect3> -<sect3 id="Widget_Instance_Initialization_The_initialize_Procedure"> +</sect2> + +<sect2 id="Widget_Instance_Initialization_The_initialize_Procedure"> <title>Widget Instance Initialization: The initialize Procedure</title> -<!-- .XS --> -<!-- (SN Widget Instance Initialization: The initialize Procedure --> -<!-- .XE --> -<!-- .IN "Initialization" --> -<!-- .IN "Chaining" --> -<!-- .IN "Superclass Chaining" --> -<!-- .IN "Inheritance" --> -<para> -<!-- .LP --> +<para> The initialize procedure pointer in a widget class is of type -<function>XtInitProc .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtInitProc" "" "@DEF@" --> -<!-- .IN "initialize procedure" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -typedef void (*XtInitProc)(Widget, Widget, ArgList, Cardinal*); -<!-- .br --> - Widget <emphasis remap='I'>request</emphasis>; -<!-- .br --> - Widget <emphasis remap='I'>new</emphasis>; -<!-- .br --> - ArgList <emphasis remap='I'>args</emphasis>; -<!-- .br --> - Cardinal *<emphasis remap='I'>num_args</emphasis>; -<!-- .FN --> +<function>XtInitProc</function>. +</para> + +<funcsynopsis id='XtInitProc'> +<funcprototype> + <funcdef>void<function>(*XtInitProc)</function></funcdef> + <paramdef>Widget<parameter> request</parameter></paramdef> + <paramdef>Widget<parameter> new</parameter></paramdef> + <paramdef>ArgList<parameter> args</parameter></paramdef> + <paramdef>Cardinal *<parameter> num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -3308,8 +2831,6 @@ Specifies the number of entries in the argument list. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> An initialization procedure performs the following: </para> <itemizedlist> @@ -3320,15 +2841,13 @@ that the client is allowed to free or modify after the widget has been created. For example, if a widget has a field that is a -<function>String ,</function> +<function>String</function>, it may choose not to depend on the characters at that address remaining constant but dynamically allocate space for the string and copy it to the new space. Widgets that do not copy one or more resources referenced by address should clearly so state in their user documentation. -<!-- .NT --> It is not necessary to allocate space for or to copy callback lists. -<!-- .NE --> </para> </listitem> <listitem> @@ -3337,12 +2856,10 @@ Computes values for unspecified resource fields. For example, if <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> are zero, the widget should compute an appropriate width and height based on its other resources. -<!-- .NT --> A widget may directly assign only its own <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> within the initialize, initialize_hook, set_values, and set_values_hook procedures; see Chapter 6. -<!-- .NE --> </para> </listitem> <listitem> @@ -3355,14 +2872,13 @@ resources like background, foreground, and font. </listitem> </itemizedlist> <para> -<!-- .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. </para> + <para> -<!-- .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 @@ -3371,14 +2887,14 @@ if all public resources are declared in the resource list. Most of the initialization code for a specific widget class deals with fields defined in that class and not with fields defined in its superclasses. </para> + <para> -<!-- .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 <emphasis remap='I'>initialize</emphasis> field in the class record. </para> + <para> -<!-- .LP --> Sometimes a subclass may want to overwrite values filled in by its superclass. In particular, size calculations of a superclass often are @@ -3386,8 +2902,8 @@ incorrect for a subclass, and in this case, the subclass must modify or recalculate fields declared and computed by its superclass. </para> + <para> -<!-- .LP --> As an example, a subclass can visually surround its superclass display. In this case, the width and height calculated by the superclass initialize @@ -3397,8 +2913,8 @@ superclass or was specified explicitly. All widgets must place themselves into whatever size is explicitly given, but they should compute a reasonable size if no size is requested. </para> + <para> -<!-- .LP --> The <emphasis remap='I'>request</emphasis> and <emphasis remap='I'>new</emphasis> arguments provide the necessary information for a subclass to determine the difference between an explicitly specified field and a field computed by a superclass. @@ -3410,8 +2926,8 @@ so far. A subclass initialize procedure can compare these two to resolve any potential conflicts. </para> + <para> -<!-- .LP --> In the above example, the subclass with the visual surround can see if the <emphasis remap='I'>width</emphasis> and <emphasis remap='I'>height</emphasis> in the <emphasis remap='I'>request</emphasis> widget are zero. @@ -3420,8 +2936,8 @@ it adds its surround size to the <emphasis remap='I'>width</emphasis> and <empha fields in the <emphasis remap='I'>new</emphasis> widget. If not, it must make do with the size originally specified. </para> + <para> -<!-- .LP --> The <emphasis remap='I'>new</emphasis> widget will become the actual widget instance record. Therefore, the initialization procedure should do all its work on the <emphasis remap='I'>new</emphasis> widget; @@ -3429,37 +2945,27 @@ the <emphasis remap='I'>request</emphasis> widget should never be modified. If the initialize procedure needs to call any routines that operate on a widget, it should specify <emphasis remap='I'>new</emphasis> as the widget instance. - </para> -</sect3> -<sect3 id="Constraint_Instance_Initialization_The_ConstraintClassPart_initialize_Procedure"> +</sect2> + +<sect2 id="Constraint_Instance_Initialization_The_ConstraintClassPart_initialize_Procedure"> <title>Constraint Instance Initialization: The ConstraintClassPart initialize Procedure</title> -<!-- .XS --> -<!-- (SN Constraint Instance Initialization: The ConstraintClassPart initialize Procedure --> -<!-- .XE --> -<!-- .IN "Initialization" --> -<!-- .IN "XtInitProc" --> -<!-- .IN "initialize procedure" --> -<!-- .IN "Chaining" --> -<!-- .IN "Superclass Chaining" --> -<!-- .IN "Inheritance" --> -<para> -<!-- .LP --> +<para> The constraint initialization procedure pointer, found in the <function>ConstraintClassPart</function> <emphasis remap='I'>initialize</emphasis> field of the widget class record, is of type -<function>XtInitProc .</function> +<function>XtInitProc</function>. The values passed to the parent constraint initialization procedures are the same as those passed to the child's class widget initialization procedures. </para> + <para> -<!-- .LP --> The <emphasis remap='I'>constraints</emphasis> field of the <emphasis remap='I'>request</emphasis> widget points to a copy of the constraints record as initialized by the arglist and resource database. </para> + <para> -<!-- .LP --> The constraint initialization procedure should compute any constraint fields derived from constraint resources. It can make further changes to the <emphasis remap='I'>new</emphasis> widget to make the widget @@ -3467,49 +2973,37 @@ and any other constraint fields conform to the specified constraints, for example, changing the widget's size or position. </para> + <para> -<!-- .LP --> If a constraint class does not need a constraint initialization procedure, it can specify NULL for the <emphasis remap='I'>initialize</emphasis> field of the <function>ConstraintClassPart</function> in the class record. - </para> -</sect3> -<sect3 id="Nonwidget_Data_Initialization_The_initialize_hook_Procedure"> +</sect2> + +<sect2 id="Nonwidget_Data_Initialization_The_initialize_hook_Procedure"> <title>Nonwidget Data Initialization: The initialize_hook Procedure</title> -<!-- .XS --> -<!-- (SN Nonwidget Data Initialization: The initialize_hook Procedure --> -<!-- .XE --> -<!-- .IN "Initialization" --> <para> -<!-- .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 --> </para> + <para> -<!-- .LP --> The initialize_hook procedure pointer is of type -<function>XtArgsProc :</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "initialize_hook procedure" "" "@DEF@" --> -<!-- .IN "XtArgsProc" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -typedef void (*XtArgsProc)(Widget, ArgList, Cardinal*); -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .br --> - ArgList <emphasis remap='I'>args</emphasis>; -<!-- .br --> - Cardinal *<emphasis remap='I'>num_args</emphasis>; -<!-- .FN --> +<function>XtArgsProc</function>: +</para> + +<funcsynopsis id='XtArgsProc'> +<funcprototype> + <funcdef>void<function>(*XtArgsProc)</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>ArgList<parameter> args</parameter></paramdef> + <paramdef>Cardinal *<parameter> num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -3550,41 +3044,33 @@ Specifies the number of entries in the argument list. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> If this procedure is not NULL, it is called immediately after the corresponding initialize procedure or in its place if the <emphasis remap='I'>initialize</emphasis> field is NULL. </para> + <para> -<!-- .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. - </para> -</sect3> </sect2> -<sect2 id="Realizing_Widgets"> +</sect1> + +<sect1 id="Realizing_Widgets"> <title>Realizing Widgets</title> -<!-- .XS --> -<!-- <function>(SN Realizing Widgets</function> --> -<!-- .XE --> <para> -<!-- .LP --> To realize a widget instance, use -<function>XtRealizeWidget .</function> +<function>XtRealizeWidget</function>. </para> -<para> -<!-- .LP --> -<!-- .IN "XtRealizeWidget" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -void XtRealizeWidget(<emphasis remap='I'>w</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtRealizeWidget'> +<funcprototype> + <funcdef>void<function>XtRealizeWidget</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -3592,14 +3078,12 @@ void XtRealizeWidget(<emphasis remap='I'>w</emphasis>) </term> <listitem> <para> -Specifies the widget. (cI -<!-- .eM --> +Specifies the widget. Must be of class Core or any subclass thereof. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> If the widget is already realized, <function>XtRealizeWidget</function> simply returns. @@ -3633,10 +3117,9 @@ which adds any widget-specific attributes and creates the X window. <para> If the widget is not a subclass of -<function>compositeWidgetClass ,</function> +<function>compositeWidgetClass</function>, <function>XtRealizeWidget</function> returns; otherwise it continues and performs the following: -<!-- .RS --> </para> </listitem> <listitem> @@ -3650,31 +3133,29 @@ those children themselves. <listitem> <para> Maps all of the managed children windows that have <emphasis remap='I'>mapped_when_managed</emphasis> -<function>True .</function> +<function>True</function>. If a widget is managed but <emphasis remap='I'>mapped_when_managed</emphasis> is -<function>False ,</function> +<function>False</function>, the widget is allocated visual space but is not displayed. -<!-- .RE --> </para> </listitem> </itemizedlist> <para> -<!-- .LP --> If the widget is a top-level shell widget (that is, it has no parent), and <emphasis remap='I'>mapped_when_managed</emphasis> is -<function>True ,</function> +<function>True</function>, <function>XtRealizeWidget</function> maps the widget window. </para> + <para> -<!-- .LP --> -<function>XtCreateWidget ,</function> -<function>XtVaCreateWidget ,</function> -<function>XtRealizeWidget ,</function> -<function>XtManageChildren ,</function> -<function>XtUnmanage\%Children ,</function> -<function>XtUnrealizeWidget ,</function> -<function>XtSetMappedWhenManaged ,</function> +<function>XtCreateWidget</function>, +<function>XtVaCreateWidget</function>, +<function>XtRealizeWidget</function>, +<function>XtManageChildren</function>, +<function>XtUnmanage\%Children</function>, +<function>XtUnrealizeWidget</function>, +<function>XtSetMappedWhenManaged</function>, and <function>XtDestroy\%Widget</function> maintain the following invariants: @@ -3695,8 +3176,7 @@ are mapped. </listitem> </itemizedlist> <para> -<!-- .LP --> -All (xI functions and all widget routines should accept +All Intrinsics functions and all widget routines should accept either realized or unrealized widgets. When calling the realize or change_managed procedures for children of a composite @@ -3710,23 +3190,20 @@ 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 --> </para> + <para> -<!-- .LP --> To check whether or not a widget has been realized, use -<function>XtIsRealized .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtIsRealized" "" "@DEF@" --> -<!-- .sM --> +<function>XtIsRealized</function>. </para> -<!-- .FD 0 --> -Boolean XtIsRealized(<emphasis remap='I'>w</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtIsRealized'> +<funcprototype> + <funcdef>Boolean<function>XtIsRealized</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -3734,14 +3211,12 @@ Boolean XtIsRealized(<emphasis remap='I'>w</emphasis>) </term> <listitem> <para> -Specifies the widget. (oI +Specifies the widget. Must be of class Object or any subclass thereof. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtIsRealized</function> function returns @@ -3751,37 +3226,28 @@ that is, if the widget has a nonzero window ID. If the specified object is not a widget, the state of the nearest widget ancestor is returned. </para> + <para> -<!-- .LP --> Some widget procedures (for example, set_values) might wish to operate differently after the widget has been realized. - </para> -<sect3 id="Widget_Instance_Window_Creation_The_realize_Procedure"> +<sect2 id="Widget_Instance_Window_Creation_The_realize_Procedure"> <title>Widget Instance Window Creation: The realize Procedure</title> -<!-- .XS --> -<!-- (SN Widget Instance Window Creation: The realize Procedure --> -<!-- .XE --> <para> -<!-- .LP --> The realize procedure pointer in a widget class is of type -<function>XtRealizeProc .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtRealizeProc" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -typedef void (*XtRealizeProc)(Widget, XtValueMask*, XSetWindowAttributes*); -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .br --> - XtValueMask *<emphasis remap='I'>value_mask</emphasis>; -<!-- .br --> - XSetWindowAttributes *<emphasis remap='I'>attributes</emphasis>; -<!-- .FN --> +<function>XtRealizeProc</function>. +</para> + +<funcsynopsis id='XtRealizeProc'> +<funcprototype> + <funcdef>void<function>(*XtRealizeProc)</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XtValueMask<parameter> value_mask</parameter></paramdef> + <paramdef>XSetWindowAttributes <parameter> attributes</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -3817,12 +3283,10 @@ call. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The realize procedure must create the widget's window. </para> + <para> -<!-- .LP --> Before calling the class realize procedure, the generic <function>XtRealizeWidget</function> function fills in a mask and a corresponding @@ -3838,14 +3302,14 @@ structure: <listitem> <para> The <emphasis remap='I'>background_pixmap</emphasis> (or <emphasis remap='I'>background_pixel</emphasis> if <emphasis remap='I'>background_pixmap</emphasis> is -<function>XtUnspecifiedPixmap )</function> +<function>XtUnspecifiedPixmap</function>) is filled in from the corresponding field. </para> </listitem> <listitem> <para> The <emphasis remap='I'>border_pixmap</emphasis> (or <emphasis remap='I'>border_pixel</emphasis> if <emphasis remap='I'>border_pixmap</emphasis> is -<function>XtUnspecifiedPixmap )</function> +<function>XtUnspecifiedPixmap</function>) is filled in from the corresponding field. </para> </listitem> @@ -3859,7 +3323,7 @@ The <emphasis remap='I'>colormap</emphasis> is filled in from the corresponding The <emphasis remap='I'>event_mask</emphasis> is filled in based on the event handlers registered, the event translations specified, whether the <emphasis remap='I'>expose</emphasis> field is non-NULL, and whether <emphasis remap='I'>visible_interest</emphasis> is -<function>True .</function> +<function>True</function>. </para> </listitem> <listitem> @@ -3871,12 +3335,11 @@ if the <emphasis remap='I'>expose</emphasis> field is NULL. </listitem> </itemizedlist> <para> -<!-- .LP --> These or any other fields in attributes and the corresponding bits in <emphasis remap='I'>value_mask</emphasis> can be set by the realize procedure. </para> + <para> -<!-- .LP --> Note that because realize is not a chained operation, the widget class realize procedure must update the <function>XSetWindowAttributes</function> @@ -3884,9 +3347,8 @@ structure with all the appropriate fields from non-Core superclasses. </para> + <para> -<!-- .LP --> -<!-- .IN "Inheritance" --> A widget class can inherit its realize procedure from its superclass during class initialization. The realize procedure defined for @@ -3895,7 +3357,7 @@ calls <function>XtCreateWindow</function> with the passed <emphasis remap='I'>value_mask</emphasis> and <emphasis remap='I'>attributes</emphasis> and with <emphasis remap='I'>window_class</emphasis> and <emphasis remap='I'>visual</emphasis> set to -<function>CopyFromParent .</function> +<function>CopyFromParent</function>. Both <function>compositeWidgetClass</function> and @@ -3903,22 +3365,22 @@ and inherit this realize procedure, and most new widget subclasses can do the same (see Section 1.6.10). </para> + <para> -<!-- .LP --> The most common noninherited realize procedures set <emphasis remap='I'>bit_gravity</emphasis> in the mask and attributes to the appropriate value and then create the window. For example, depending on its justification, Label might set <emphasis remap='I'>bit_gravity</emphasis> to -<function>WestGravity ,</function> -<function>CenterGravity ,</function> +<function>WestGravity</function>, +<function>CenterGravity</function>, or -<function>EastGravity .</function> +<function>EastGravity</function>. Consequently, shrinking it would just move the bits appropriately, and no exposure event is needed for repainting. </para> + <para> -<!-- .LP --> If a composite widget's children should be realized in an order other than that specified (to control the stacking order, for example), @@ -3927,53 +3389,41 @@ it should call on its children itself in the appropriate order from within its own realize procedure. </para> + <para> -<!-- .LP --> Widgets that have children and whose class is not a subclass of <function>compositeWidgetClass</function> are responsible for calling <function>XtRealizeWidget</function> on their children, usually from within the realize procedure. </para> + <para> -<!-- .LP --> Realize procedures cannot manage or unmanage their descendants. - </para> -</sect3> -<sect3 id="Window_Creation_Convenience_Routine"> +</sect2> + +<sect2 id="Window_Creation_Convenience_Routine"> <title>Window Creation Convenience Routine</title> -<!-- .XS --> -<!-- (SN Window Creation Convenience Routine --> -<!-- .XE --> <para> -<!-- .LP --> Rather than call the Xlib <function>XCreateWindow</function> -<!-- .IN "realize procedure" --> -function explicitly, a realize procedure should normally call the (xI analog -<function>XtCreateWindow ,</function> +function explicitly, a realize procedure should normally call the Intrinsics analog +<function>XtCreateWindow</function>, which simplifies the creation of windows for widgets. </para> -<para> -<!-- .LP --> -<!-- .IN "XtCreateWindow" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -void XtCreateWindow(<emphasis remap='I'>w</emphasis>, <emphasis remap='I'>window_class</emphasis>, <emphasis remap='I'>visual</emphasis>, \ -<emphasis remap='I'>value_mask</emphasis>, <emphasis remap='I'>attributes</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .br --> - unsigned int <emphasis remap='I'>window_class</emphasis>; -<!-- .br --> - Visual *<emphasis remap='I'>visual</emphasis>; -<!-- .br --> - XtValueMask <emphasis remap='I'>value_mask</emphasis>; -<!-- .br --> - XSetWindowAttributes *<emphasis remap='I'>attributes</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtCreateWindow'> +<funcprototype> + <funcdef>void<function>XtCreateWindow</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>unsigned int<parameter> window_class</parameter></paramdef> + <paramdef>Visual *<parameter> visual</parameter></paramdef> + <paramdef>XtValueMask<parameter> value_mask</parameter></paramdef> + <paramdef>XSetWindowAttributes <parameter> attributes</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -3981,7 +3431,7 @@ void XtCreateWindow(<emphasis remap='I'>w</emphasis>, <emphasis remap='I'>window </term> <listitem> <para> -Specifies the widget that defines the additional window attributed. (cI +Specifies the widget that defines the additional window attributed. Must be of class Core or any subclass thereof. </para> </listitem> </varlistentry> @@ -3992,8 +3442,8 @@ Specifies the widget that defines the additional window attributed. (cI <listitem> <para> Specifies the Xlib window class (for example, -<function>InputOutput ,</function> -<function>InputOnly ,</function> +<function>InputOutput</function>, +<function>InputOnly</function>, or <function>CopyFromParent ).</function> </para> @@ -4007,7 +3457,6 @@ or <para> Specifies the visual type (usually <function>CopyFromParent ).</function> -<!-- .ds Vm attribute fields to use --> </para> </listitem> </varlistentry> @@ -4035,8 +3484,6 @@ call. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtCreateWindow</function> function calls the Xlib @@ -4044,46 +3491,40 @@ function calls the Xlib function with values from the widget structure and the passed parameters. Then, it assigns the created window to the widget's <emphasis remap='I'>window</emphasis> field. </para> + <para> -<!-- .LP --> <function>XtCreateWindow</function> evaluates the following fields of the widget core structure: <emphasis remap='I'>depth</emphasis>, <emphasis remap='I'>screen</emphasis>, <emphasis remap='I'>parent->core.window</emphasis>, <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>, and <emphasis remap='I'>border_width</emphasis>. - </para> -</sect3> </sect2> -<sect2 id="Obtaining_Window_Information_from_a_Widget"> +</sect1> + +<sect1 id="Obtaining_Window_Information_from_a_Widget"> <title>Obtaining Window Information from a Widget</title> -<!-- .XS --> -<!-- <function>(SN Obtaining Window Information from a Widget</function> --> -<!-- .XE --> <para> -<!-- .LP --> The Core widget class definition contains the screen and window ids. The <emphasis remap='I'>window</emphasis> field may be NULL for a while (see Sections 2.5 and 2.6). </para> + <para> -<!-- .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. </para> -<para> -<!-- .LP --> -<!-- .IN "XtDisplay" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -Display *XtDisplay(<emphasis remap='I'>w</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .FN --> + +<funcsynopsis> +<funcprototype> + <funcdef>Display<function>XtDisplay</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -4091,28 +3532,23 @@ Display *XtDisplay(<emphasis remap='I'>w</emphasis>) </term> <listitem> <para> -Specifies the widget. (cI +Specifies the widget. Must be of class Core or any subclass thereof. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> <function>XtDisplay</function> returns the display pointer for the specified widget. -<!-- .sp --> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtParent" "" "@DEF@" --> -<!-- .sM --> </para> -<!-- .FD 0 --> -Widget XtParent(<emphasis remap='I'>w</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .FN --> + +<funcsynopsis> +<funcprototype> + <funcdef>Widget<function>XtParent</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -4120,29 +3556,24 @@ Widget XtParent(<emphasis remap='I'>w</emphasis>) </term> <listitem> <para> -Specifies the widget. (oI +Specifies the widget. Must be of class Object or any subclass thereof. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> <function>XtParent</function> returns the parent object for the specified widget. The returned object will be of class Object or a subclass. -<!-- .sp --> </para> -<para> -<!-- .LP --> -<!-- .IN "XtScreen" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -Screen *XtScreen(<emphasis remap='I'>w</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtScreen'> +<funcprototype> + <funcdef>Screen<function>*XtScreen</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -4150,28 +3581,23 @@ Screen *XtScreen(<emphasis remap='I'>w</emphasis>) </term> <listitem> <para> -Specifies the widget. (cI +Specifies the widget. Must be of class Core or any subclass thereof. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> <function>XtScreen</function> returns the screen pointer for the specified widget. -<!-- .sp --> </para> -<para> -<!-- .LP --> -<!-- .IN "XtWindow" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -Window XtWindow(<emphasis remap='I'>w</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtWindow'> +<funcprototype> + <funcdef>Window<function>XtWindow</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -4179,39 +3605,33 @@ Window XtWindow(<emphasis remap='I'>w</emphasis>) </term> <listitem> <para> -Specifies the widget. (cI +Specifies the widget. Must be of class Core or any subclass thereof. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> <function>XtWindow</function> returns the window of the specified widget. -<!-- .sp --> </para> + <para> -<!-- .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 -<function>XtDisplayOfObject ,</function> -<function>XtScreenOfObject ,</function> +<function>XtDisplayOfObject</function>, +<function>XtScreenOfObject</function>, and -<function>XtWindowOfObject .</function> -<!-- .IN "XtDisplayOfObject" "" "@DEF@" --> -<!-- .sp --> -</para> -<para> -<!-- .LP --> -<!-- .sM --> +<function>XtWindowOfObject</function>. </para> -<!-- .FD 0 --> -Display *XtDisplayOfObject(<emphasis remap='I'>object</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>object</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtDisplayOfObject'> +<funcprototype> + <funcdef>Display <function>*XtDisplayOfObject</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -4219,14 +3639,12 @@ Display *XtDisplayOfObject(<emphasis remap='I'>object</emphasis>) </term> <listitem> <para> -Specifies the object. (oI +Specifies the object. Must be of class Object or any subclass thereof. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> <function>XtDisplayOfObject</function> is identical in function to <function>XtDisplay</function> @@ -4236,16 +3654,15 @@ returns the display pointer for the nearest ancestor of <emphasis remap='I'>object</emphasis> that is of class Widget or a subclass thereof. </para> -<para> -<!-- .LP --> -<!-- .IN "XtScreenOfObject" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -Screen *XtScreenOfObject(<emphasis remap='I'>object</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>object</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtScreenOfObject'> +<funcprototype> + <funcdef>Screen <function>*XtScreenOfObject</function></funcdef> + <paramdef>Widget<parameter> object</parameter></paramdef> +</funcprototype> +</funcsynopsis> + + <variablelist> <varlistentry> <term> @@ -4253,14 +3670,12 @@ Screen *XtScreenOfObject(<emphasis remap='I'>object</emphasis>) </term> <listitem> <para> -Specifies the object. (oI +Specifies the object. Must be of class Object or any subclass thereof. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> <function>XtScreenOfObject</function> is identical in function to <function>XtScreen</function> @@ -4270,16 +3685,14 @@ returns the screen pointer for the nearest ancestor of <emphasis remap='I'>object</emphasis> that is of class Widget or a subclass thereof. </para> -<para> -<!-- .LP --> -<!-- .IN "XtWindowOfObject" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -Window XtWindowOfObject(<emphasis remap='I'>object</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>object</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtWindowOfObject'> +<funcprototype> + <funcdef>Window <function>XtWindowOfObject</function></funcdef> + <paramdef>Widget<parameter> object</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -4287,14 +3700,12 @@ Window XtWindowOfObject(<emphasis remap='I'>object</emphasis>) </term> <listitem> <para> -Specifies the object. (oI +Specifies the object. Must be of class Object or any subclass thereof. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> <function>XtWindowOfObject</function> is identical in function to <function>XtWindow</function> @@ -4302,23 +3713,20 @@ if the object is a widget; otherwise <function>XtWindowOfObject</function> returns the window for the nearest ancestor of <emphasis remap='I'>object</emphasis> that is of class Widget or a subclass thereof. -<!-- .sp --> </para> + <para> -<!-- .LP --> To retrieve the instance name of an object, use -<function>XtName .</function> +<function>XtName</function>. </para> -<para> -<!-- .LP --> -<!-- .IN "XtName" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -String XtName(<emphasis remap='I'>object</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>object</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtName'> +<funcprototype> + <funcdef>String <function>XtName</function></funcdef> + <paramdef>Widget<parameter> object</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -4326,21 +3734,19 @@ String XtName(<emphasis remap='I'>object</emphasis>) </term> <listitem> <para> -Specifies the object whose name is desired. (oI +Specifies the object whose name is desired. Must be of class Object or any subclass thereof. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> <function>XtName</function> returns a pointer to the instance name of the specified object. -The storage is owned by the (xI and must not be modified. The +The storage is owned by the Intrinsics and must not be modified. The name is not qualified by the names of any of the object's ancestors. </para> + <para> -<!-- .LP --> Several window attributes are locally cached in the widget instance. Thus, they can be set by the resource manager and <function>XtSetValues</function> @@ -4350,15 +3756,15 @@ as well as used by routines that derive structures from these values <function>XtCreateWindow</function> call. </para> + <para> -<!-- .LP --> The <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, <emphasis remap='I'>height</emphasis>, and <emphasis remap='I'>border_width</emphasis> window attributes are available to geometry managers. -These fields are maintained synchronously inside the (xI. +These fields are maintained synchronously inside the Intrinsics. When an <function>XConfigureWindow</function> -is issued by the (xI on the widget's window (on request of its parent), +is issued by the Intrinsics on the widget's window (on request of its parent), these values are updated immediately rather than some time later when the server generates a <function>ConfigureNotify</function> @@ -4374,29 +3780,22 @@ 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). - </para> -<sect3 id="Unrealizing_Widgets"> +<sect2 id="Unrealizing_Widgets"> <title>Unrealizing Widgets</title> -<!-- .XS --> -<!-- <function>(SN Unrealizing Widgets</function> --> -<!-- .XE --> <para> -<!-- .LP --> To destroy the windows associated with a widget and its non-pop-up descendants, use -<function>XtUnrealizeWidget .</function> +<function>XtUnrealizeWidget</function>. </para> -<para> -<!-- .LP --> -<!-- .IN "XtUnrealizeWidget" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -void XtUnrealizeWidget(<emphasis remap='I'>w</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtUnrealizeWidget'> +<funcprototype> + <funcdef>void<function>XtUnrealizeWidget</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -4404,14 +3803,12 @@ void XtUnrealizeWidget(<emphasis remap='I'>w</emphasis>) </term> <listitem> <para> -Specifies the widget. (cI +Specifies the widget. Must be of class Core or any subclass thereof. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> If the widget is currently unrealized, <function>XtUnrealizeWidget</function> simply returns. Otherwise it performs the following: @@ -4428,10 +3825,8 @@ 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@" --> </para> </listitem> <listitem> @@ -4443,23 +3838,18 @@ with the specified widget's <emphasis remap='I'>window</emphasis> field. </listitem> </itemizedlist> <para> -<!-- .LP --> Any events in the queue or which arrive following a call to <function>XtUnrealizeWidget</function> will be dispatched as if the window(s) of the unrealized widget(s) had never existed. - </para> -</sect3> </sect2> -<sect2 id="Destroying_Widgets"> +</sect1> + +<sect1 id="Destroying_Widgets"> <title>Destroying Widgets</title> -<!-- .XS --> -<!-- <function>(SN Destroying Widgets</function> --> -<!-- .XE --> <para> -<!-- .LP --> -The (xI provide support +The Intrinsics provide support </para> <itemizedlist> <listitem> @@ -4489,25 +3879,22 @@ To minimize the number of things a widget has to deallocate when destroyed. To minimize the number of <function>XDestroyWindow</function> calls when destroying a widget tree. -<!-- .sp --> </para> </listitem> </itemizedlist> <para> -<!-- .LP --> To destroy a widget instance, use -<function>XtDestroyWidget .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtDestroyWidget" "" "@DEF@" --> -<!-- .sM --> +<function>XtDestroyWidget</function>. </para> -<!-- .FD 0 --> -void XtDestroyWidget(<emphasis remap='I'>w</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .FN --> + + +<funcsynopsis id='XtDestroyWidget'> +<funcprototype> + <funcdef>void<function>XtDestroyWidget</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -4515,14 +3902,12 @@ void XtDestroyWidget(<emphasis remap='I'>w</emphasis>) </term> <listitem> <para> -Specifies the widget. (oI +Specifies the widget. Must be of class Object or any subclass thereof. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtDestroyWidget</function> function provides the only method of destroying a widget, @@ -4532,8 +3917,8 @@ including from an application callback routine of the widget being destroyed. This requires a two-phase destroy process in order to avoid dangling references to destroyed widgets. </para> + <para> -<!-- .LP --> In phase 1, <function>XtDestroyWidget</function> performs the following: @@ -4542,7 +3927,7 @@ performs the following: <listitem> <para> If the <emphasis remap='I'>being_destroyed</emphasis> field of the widget is -<function>True ,</function> +<function>True</function>, it returns immediately. </para> </listitem> @@ -4562,23 +3947,22 @@ destroyed when it is safe to do so. </listitem> </itemizedlist> <para> -<!-- .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. </para> + <para> -<!-- .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 <function>XtDispatchEvent</function> is about to return, or immediately if not in -<function>XtDispatchEvent .</function> +<function>XtDispatchEvent</function>. </para> + <para> -<!-- .LP --> In phase 2, <function>XtDestroyWidget</function> performs the following on each entry in the destroy list in the order @@ -4588,7 +3972,7 @@ specified: <listitem> <para> If the widget is not a pop-up child and the widget's parent is a subclass of -<function>composite\%WidgetClass ,</function> +<function>composite\%WidgetClass</function>, and if the parent is not being destroyed, it calls <function>XtUnmanageChild</function> @@ -4605,7 +3989,6 @@ callbacks before parent callbacks). </listitem> </itemizedlist> <para> -<!-- .LP --> The <function>XtDestroyWidget</function> function then makes second traversal of the widget and all normal @@ -4616,7 +3999,7 @@ widget in postorder: <listitem> <para> If the widget is not a pop-up child and the widget's parent is a subclass of -<function>constraint\%WidgetClass ,</function> +<function>constraint\%WidgetClass</function>, it calls the <function>ConstraintClassPart</function> destroy procedure for the parent, @@ -4624,7 +4007,7 @@ then for the parent's superclass, until finally it calls the <function>ConstraintClassPart</function> destroy procedure for -<function>constraintWidgetClass .</function> +<function>constraintWidgetClass</function>. </para> </listitem> <listitem> @@ -4645,7 +4028,7 @@ record with the record_type <function>\s-1NULLQUARK\s+1</function> and the <emphasis remap='I'>deallocate</emphasis> field is not NULL, calls the deallocate procedure to deallocate the instance and if one -exists, the constraint record. Otherwise, the (xI will deallocate +exists, the constraint record. Otherwise, the Intrinsics will deallocate the widget instance record and if one exists, the constraint record. </para> </listitem> @@ -4657,79 +4040,65 @@ if the specified widget is realized (that is, has an X window). The server recursively destroys all normal descendant windows. (Windows of realized pop-up Shell children, and their descendants, are destroyed by a shell class destroy procedure.) - </para> </listitem> </itemizedlist> -<sect3 id="Adding_and_Removing_Destroy_Callbacks"> +<sect2 id="Adding_and_Removing_Destroy_Callbacks"> <title>Adding and Removing Destroy Callbacks</title> -<!-- .XS --> -<!-- <function>(SN Adding and Removing Destroy Callbacks</function> --> -<!-- .XE --> <para> -<!-- .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. </para> + <para> -<!-- .LP --> For example, the following adds an application-supplied destroy callback procedure <emphasis remap='I'>ClientDestroy</emphasis> with client data to a widget by calling -<function>XtAddCallback .</function> -<!-- .IN "XtAddCallback" --> +<function>XtAddCallback</function>. +</para> + <literallayout class="monospaced"> XtAddCallback(<emphasis remap='I'>w</emphasis>, XtNdestroyCallback, <emphasis remap='I'>ClientDestroy</emphasis>, <emphasis remap='I'>client_data</emphasis>) </literallayout> -</para> + <para> -<!-- .LP --> Similarly, the following removes the application-supplied destroy callback procedure <emphasis remap='I'>ClientDestroy</emphasis> by calling -<function>XtRemoveCallback .</function> -<!-- .IN "XtRemoveCallback" --> +<function>XtRemoveCallback</function>. +</para> + <literallayout class="monospaced"> XtRemoveCallback(<emphasis remap='I'>w</emphasis>, XtNdestroyCallback, <emphasis remap='I'>ClientDestroy</emphasis>, <emphasis remap='I'>client_data</emphasis>) </literallayout> -</para> <para> -<!-- .LP --> The <emphasis remap='I'>ClientDestroy</emphasis> argument is of type -<function>XtCallbackProc ;</function> +<function>XtCallbackProc</function>; see Section 8.1. - </para> -</sect3> -<sect3 id="Dynamic_Data_Deallocation_The_destroy_Procedure"> +</sect2> + +<sect2 id="Dynamic_Data_Deallocation_The_destroy_Procedure"> <title>Dynamic Data Deallocation: The destroy Procedure</title> -<!-- .XS --> -<!-- (SN Dynamic Data Deallocation: The destroy Procedure --> -<!-- .XE --> <para> -<!-- .LP --> -<!-- .IN "destroy procedure" "" "@DEF@" --> The destroy procedure pointers in the -<function>ObjectClassPart ,</function> -<function>RectObjClassPart ,</function> +<function>ObjectClassPart</function>, +<function>RectObjClassPart</function>, and <function>CoreClassPart</function> structures are of type -<function>XtWidgetProc .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtWidgetProc" "" "@DEF@" --> -<!-- .sM --> +<function>XtWidgetProc</function>. </para> -<!-- .FD 0 --> -typedef void (*XtWidgetProc)(Widget); -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtWidgetProc'> +<funcprototype> + <funcdef>void<function>XtWidgetProc</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -4743,8 +4112,6 @@ Specifies the widget being destroyed. </varlistentry> </variablelist> <para> -<!-- .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 @@ -4757,8 +4124,8 @@ and therefore should not be destroyed by it. If a widget does not need to deallocate any storage, the destroy procedure entry in its class record can be NULL. </para> + <para> -<!-- .LP --> Deallocating storage includes, but is not limited to, the following steps: </para> @@ -4768,8 +4135,8 @@ the following steps: Calling <function>XtFree</function> on dynamic storage allocated with -<function>XtMalloc ,</function> -<function>XtCalloc ,</function> +<function>XtMalloc</function>, +<function>XtCalloc</function>, and so on. </para> </listitem> @@ -4785,7 +4152,7 @@ on pixmaps created with direct X calls. Calling <function>XtReleaseGC</function> on GCs allocated with -<function>XtGetGC .</function> +<function>XtGetGC</function>. </para> </listitem> <listitem> @@ -4807,7 +4174,7 @@ on event handlers added to other widgets. Calling <function>XtRemoveTimeOut</function> on timers created with -<function>XtAppAddTimeOut .</function> +<function>XtAppAddTimeOut</function>. </para> </listitem> <listitem> @@ -4816,72 +4183,58 @@ Calling <function>XtDestroyWidget</function> for each child if the widget has children and is not a subclass of -<function>compositeWidgetClass .</function> +<function>compositeWidgetClass</function>. </para> </listitem> </itemizedlist> <para> -<!-- .LP --> -During destroy phase 2 for each widget, the (xI remove the widget +During destroy phase 2 for each widget, the Intrinsics remove the widget from the modal cascade, unregister all event handlers, remove all key, keyboard, button, and pointer grabs and remove all callback procedures registered on the widget. Any outstanding selection transfers will time out. - </para> -</sect3> -<sect3 id="Dynamic_Constraint_Data_Deallocation_The_ConstraintClassPart_destroy_Procedure"> +</sect2> + +<sect2 id="Dynamic_Constraint_Data_Deallocation_The_ConstraintClassPart_destroy_Procedure"> <title>Dynamic Constraint Data Deallocation: The ConstraintClassPart destroy Procedure</title> -<!-- .XS --> -<!-- (SN Dynamic Constraint Data Deallocation: The ConstraintClassPart destroy Procedure --> -<!-- .XE --> <para> -<!-- .LP --> The constraint destroy procedure identified in the <function>ConstraintClassPart</function> -structure is called for a widget whose parent is a subclass of -<function>constraintWidgetClass .</function> +<function>constraintWidgetClass</function>. This constraint destroy procedure pointer is of type -<function>XtWidgetProc .</function> +<function>XtWidgetProc</function>. The constraint destroy procedures are called in subclass-to-superclass order, starting at the class of the widget's parent and ending at -<function>constraint\%WidgetClass .</function> +<function>constraint\%WidgetClass</function>. Therefore, a parent's constraint destroy procedure should deallocate only storage that is specific to the constraint subclass and not storage allocated by any of its superclasses. </para> + <para> -<!-- .LP --> If a parent does not need to deallocate any constraint storage, the constraint destroy procedure entry in its class record can be NULL. - </para> -</sect3> -<sect3 id="Widget_Instance_Deallocation_The_deallocate_Procedure"> +</sect2> + +<sect2 id="Widget_Instance_Deallocation_The_deallocate_Procedure"> <title>Widget Instance Deallocation: The deallocate Procedure</title> -<!-- .XS --> -<!-- (SN Widget Instance Deallocation: The deallocate Procedure --> -<!-- .XE --> <para> -<!-- .LP --> -<!-- .IN "deallocate procedure" "" "@DEF@" --> The deallocate procedure pointer in the <function>ObjectClassExtension</function> record is of type -<function>XtDeallocateProc .</function> +<function>XtDeallocateProc</function>. </para> -<para> -<!-- .LP --> -<!-- .IN "XtDeallocateProc" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -typedef void (*XtDeallocateProc)(Widget, XtPointer); -<!-- .br --> - Widget <emphasis remap='I'>widget</emphasis>; -<!-- .br --> - XtPointer <emphasis remap='I'>more_bytes</emphasis>; -<!-- .FN --> + +<funcsynopsis> +<funcprototype> + <funcdef>void<function>(*XtDeallocateProc)</function></funcdef> + <paramdef>Widget<parameter> widget</parameter></paramdef> + <paramdef>XtPointer<parameter> more_bytes</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -4906,8 +4259,6 @@ along with the widget, or NULL. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> When a widget is destroyed, if an <function>ObjectClassExtension</function> record exists in the object class part <emphasis remap='I'>extension</emphasis> field @@ -4918,7 +4269,7 @@ and the <emphasis remap='I'>deallocate</emphasis> field is not NULL, the will be called. If no ObjectClassPart extension record is declared with <emphasis remap='I'>record_type</emphasis> equal to -<function>\s-1NULLQUARK\s+1 ,</function> +<function>\s-1NULLQUARK\s+1</function>, then <function>XtInheritAllocate</function> and @@ -4930,23 +4281,19 @@ to deallocate the constraints record as specified by the widget's <emphasis remap='I'>core.constraints</emphasis> field if it is not NULL, and to deallocate the widget instance itself. </para> + <para> -<!-- .LP --> If no <function>XtDeallocateProc</function> -is found, it is assumed that the (xI +is found, it is assumed that the Intrinsics originally allocated the memory and is responsible for freeing it. - </para> -</sect3> </sect2> -<sect2 id="Exiting_from_an_Application"> +</sect1> + +<sect1 id="Exiting_from_an_Application"> <title>Exiting from an Application</title> -<!-- .XS --> -<!-- <function>(SN Exiting from an Application</function> --> -<!-- .XE --> <para> -<!-- .LP --> All (tk applications should terminate by calling <function>XtDestroyApplicationContext</function> @@ -4958,12 +4305,12 @@ for POSIX-based systems). The quickest way to make the windows disappear while exiting is to call <function>XtUnmapWidget</function> on each top-level shell widget. -The (xI have no resources beyond those in the program image, +The Intrinsics have no resources beyond those in the program image, and the X server will free its resources when its connection to the application is broken. </para> + <para> -<!-- .LP --> Depending upon the widget set in use, it may be necessary to explicitly destroy individual widgets or widget trees with <function>XtDestroyWidget</function> @@ -4976,89 +4323,6 @@ 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 --> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - </para> -</sect2> +</sect1> </chapter> -</book> diff --git a/specs/intrinsics.xml b/specs/intrinsics.xml index 58ce38d..6eaa7be 100644 --- a/specs/intrinsics.xml +++ b/specs/intrinsics.xml @@ -1,8 +1,7 @@ <?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" -[ -<!ENTITY % defs SYSTEM "defs.ent"> %defs; +[ <!ENTITY % defs SYSTEM "defs.ent"> %defs; ]> @@ -49,10 +48,10 @@ <!-- .\" It is provided ``as is'' without express or implied warranty. --> <!-- -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH01.xml.out"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH01.xml"/> --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH02.xml.out"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH02.xml"/> <!-- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH03.xml"/> |