diff options
author | Matt Dew <marcoz@osource.org> | 2011-10-24 23:17:17 -0600 |
---|---|---|
committer | Matt Dew <marcoz@osource.org> | 2011-10-24 23:17:17 -0600 |
commit | 97129be6e050d103c1c26eac13711241850e7eb2 (patch) | |
tree | d5e9ea2500c635e0748938e1d14485b0d2050af6 | |
parent | 0aeb779aa1e954d253816151559480672351da0e (diff) |
proofread CH02.xml
-rw-r--r-- | specs/CH02.xml | 505 |
1 files changed, 334 insertions, 171 deletions
diff --git a/specs/CH02.xml b/specs/CH02.xml index 8f35c8a..b3a8115 100644 --- a/specs/CH02.xml +++ b/specs/CH02.xml @@ -88,7 +88,7 @@ every widget has a pointer to an array of pop-up children. </para> <sect1 id="Initializing_the_tk"> -<title>Initializing the (tk</title> +<title>Initializing the X Toolkit</title> <para> Before an application can call any Intrinsics function other than @@ -140,7 +140,7 @@ or </para> <para> -Multiple instances of (tk applications may be implemented +Multiple instances of X Toolkit applications may be implemented in a single address space. Each instance needs to be able to read input and dispatch events independently of any other instance. @@ -171,7 +171,7 @@ To initialize the Intrinsics internals, use <funcsynopsis id='XtToolkitInitialize'> <funcprototype> <funcdef>void <function>XtToolkitInitialize</function></funcdef> - <paramdef><parameter></parameter></paramdef> + <paramdef> <parameter></parameter></paramdef> </funcprototype> </funcsynopsis> @@ -195,7 +195,7 @@ To create an application context, use <funcsynopsis id='XtCreateApplicationContext'> <funcprototype> <funcdef>XtAppContext <function>XtCreateApplicationContext</function></funcdef> - <paramdef><parameter></parameter></paramdef> + <paramdef> <parameter></parameter></paramdef> </funcprototype> </funcsynopsis> @@ -217,7 +217,7 @@ remaining display connections in it, use <funcsynopsis id='XtDestroyApplicationContext'> <funcprototype> <funcdef>void <function>XtDestroyApplicationContext</function></funcdef> - <paramdef>XtAppContext <parameter> app_context</parameter></paramdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -249,8 +249,8 @@ To get the application context in which a given widget was created, use <funcsynopsis id='XtWidgetToApplicationContext'> <funcprototype> - <funcdef>XtAppContext <function>XtWidgetToApplicationContext</function></funcdef> - <paramdef>Widget<parameter> w</parameter></paramdef> + <funcdef>XtAppContext <function>XtWidgetToApplicationContext</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -281,13 +281,13 @@ To initialize a display and add it to an application context, use <funcprototype> <funcdef>void <function>XtDisplayInitialize</function></funcdef> <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> - <paramdef>Display *<parameter>display</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>XrmOptionDescRec * <parameter>options</parameter></paramdef> <paramdef>Cardinal <parameter>num_options</parameter></paramdef> - <paramdef>int *<parameter>argc</parameter></paramdef> - <paramdef>String *<parameter>argv</parameter></paramdef> + <paramdef>int * <parameter>argc</parameter></paramdef> + <paramdef>String * <parameter>argv</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -344,7 +344,7 @@ 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>. For further information, -see Section 15.9 in <emphasis remap='I'>(xL</emphasis> and Section 2.4 of this specification. +see Section 15.9 in <emphasis remap='I'>Xlib — C Language X Interface</emphasis> and Section 2.4 of this specification. </para> </listitem> </varlistentry> @@ -432,10 +432,10 @@ add it to an application context, use <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>XrmOptionDescRec * <parameter>options</parameter></paramdef> <paramdef>Cardinal <parameter>num_options</parameter></paramdef> - <paramdef>int *<parameter>argc</parameter></paramdef> - <paramdef>String *<parameter>argv</parameter></paramdef> + <paramdef>int * <parameter>argc</parameter></paramdef> + <paramdef>String * <parameter>argv</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -540,7 +540,7 @@ If no display is specified in <emphasis remap='I'>argv</emphasis>, the user's default display is retrieved from the environment. On POSIX-based systems, this is the value of the -<function>\s-1DISPLAY\s+1</function> +<emphasis role='bold'>DISPLAY</emphasis> environment variable. </para> @@ -556,9 +556,9 @@ and <emphasis remap='I'>application_name</emphasis> is non-NULL, <emphasis remap='I'>application_name</emphasis> is passed to <function>XtDisplayInitialize</function>. If <emphasis remap='I'>application_name</emphasis> is NULL and if the environment variable -<function>\s-1RESOURCE_NAME\s+1</function> +<emphasis role='bold'>RESOURCE_NAME</emphasis> is set, the value of -<function>\s-1RESOURCE_NAME\s+1</function> +<emphasis role='bold'>RESOURCE_NAME</emphasis> is used. Otherwise, the application name is the name used to invoke the program. On implementations that conform to ANSI C Hosted Environment support, the application name will @@ -583,7 +583,7 @@ To close a display and remove it from an application context, use <funcsynopsis id='XtCloseDisplay'> <funcprototype> <funcdef>void <function>XtCloseDisplay</function></funcdef> - <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>Display * <parameter>display</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -639,10 +639,10 @@ The callout procedure provided by the application is of type <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> + <funcdef>typedef 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> @@ -701,10 +701,10 @@ use <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> + <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> @@ -923,7 +923,7 @@ If this database query fails, the server resource database is queried; if this query also fails, the language is determined from the environment; on POSIX-based systems, this is done by retrieving the value of the -<function>\s-1LANG\s+1</function> +<emphasis role='bold'>LANG</emphasis> environment variable. If no language string is found, the empty string is used. This language string is saved for all future references in the Intrinsics @@ -939,7 +939,7 @@ contain user preferences that are to override those specifications in the per-display and per-screen resources. On POSIX-based systems, the user's environment resource file name is specified by the value of the -<function>\s-1XENVIRONMENT\s+1</function> +<emphasis role='bold'>XENVIRONMENT</emphasis> environment variable. If this environment variable does not exist, the user's home directory is searched for a file named @@ -983,51 +983,62 @@ with the parameters where <emphasis remap='I'>path</emphasis> is defined in an operating-system-specific way. On POSIX-based systems, <emphasis remap='I'>path</emphasis> is defined to be the value of the environment variable -<function>\s-1XUSERFILESEARCHPATH\s+1</function> +<emphasis role='bold'>XUSERFILESEARCHPATH</emphasis> if this is defined. If -<function>\s-1XUSERFILESEARCHPATH\s+1</function> +<emphasis role='bold'>XUSERFILESEARCHPATH</emphasis> is not defined, an implementation-dependent default value is used. This default value is constrained in the following manner: </para> </listitem> <listitem> - <para> + <itemizedlist> + <listitem> + <para> If the environment variable -<function>\s-1XAPPLRESDIR\s+1</function> +<emphasis role='bold'>XAPPLRESDIR</emphasis> is not defined, the default -<function>\s-1XUSERFILESEARCHPATH\s+1</function> +<emphasis role='bold'>XUSERFILESEARCHPATH</emphasis> must contain at least six entries. These entries must contain $HOME as the directory prefix, plus the following substitutions: -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 + </para> +<literallayout> + 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 +</literallayout> + <para> 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> - <para> -If -<function>\s-1XAPPLRESDIR\s+1</function> + </para> + </listitem> + <listitem> + <para> If +<emphasis role='bold'>XAPPLRESDIR</emphasis> is defined, the default -<function>\s-1XUSERFILESEARCHPATH\s+1</function> +<emphasis role='bold'>XUSERFILESEARCHPATH</emphasis> must contain at least seven entries. These entries must contain the following directory prefixes and substitutions: -1. $XAPPLRESDIR with %C, %N, %L or %C, %N, %l, %t, %c -2. $XAPPLRESDIR with %C, %N, %l -3. $XAPPLRESDIR with %C, %N -4. $XAPPLRESDIR with %N, %L or %N, %l, %t, %c -5. $XAPPLRESDIR with %N, %l -6. $XAPPLRESDIR with %N -7. $HOME with %N + </para> +<literallayout> + 1. $XAPPLRESDIR with %C, %N, %L or %C, %N, %l, %t, %c + 2. $XAPPLRESDIR with %C, %N, %l + 3. $XAPPLRESDIR with %C, %N + 4. $XAPPLRESDIR with %N, %L or %N, %l, %t, %c + 5. $XAPPLRESDIR with %N, %l + 6. $XAPPLRESDIR with %N + 7. $HOME with %N +</literallayout> + <para> 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. - </para> + </para> + </listitem> + </itemizedlist> </listitem> <listitem> <para> @@ -1058,6 +1069,7 @@ the original display-associated database is restored. </para> </listitem> </itemizedlist> + <para> To obtain the resource database for a particular screen, use <function>XtScreenDatabase</function>. @@ -1066,7 +1078,7 @@ To obtain the resource database for a particular screen, use <funcsynopsis id='XtScreenDatabase'> <funcprototype> <funcdef>XrmDatabase <function>XtScreenDatabase</function></funcdef> - <paramdef>Screen *<parameter>screen</parameter></paramdef> + <paramdef>Screen * <parameter>screen</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -1104,7 +1116,7 @@ To obtain the default resource database associated with a particular display, us <funcsynopsis id='XtDatabase'> <funcprototype> <funcdef>XrmDatabase <function>XtDatabase</function></funcdef> - <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>Display * <parameter>display</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -1141,8 +1153,8 @@ use <funcsynopsis id='XtAppSetFallbackResources'> <funcprototype> <funcdef>void <function>XtAppSetFallbackResources</function></funcdef> - <paramdef>XtAppContext *<parameter>app_context</parameter></paramdef> - <paramdef>String *<parameter>specification_list</parameter></paramdef> + <paramdef>XtAppContext * <parameter>app_context</parameter></paramdef> + <paramdef>String * <parameter>specification_list</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -1207,9 +1219,7 @@ The function first parses the command line for the following options: <variablelist> <varlistentry> - <term> - \-display - </term> + <term>-display</term> <listitem> <para> Specifies the display name for @@ -1218,9 +1228,7 @@ Specifies the display name for </listitem> </varlistentry> <varlistentry> - <term> - \-name - </term> + <term>-name</term> <listitem> <para> Sets the resource name prefix, @@ -1230,9 +1238,7 @@ which overrides the application name passed to </listitem> </varlistentry> <varlistentry> - <term> - \-xnllanguage - </term> + <term>-xnllanguage</term> <listitem> <para> Specifies the initial language string for establishing locale @@ -1250,41 +1256,187 @@ has a table of standard command line options that are passed to for adding resources to the resource database, and it takes as a parameter additional application-specific resource abbreviations. -The format of this table is described in Section 15.9 in <emphasis remap='I'>(xL</emphasis>. +The format of this table is described in Section 15.9 in <emphasis remap='I'>Xlib — C Language X Interface</emphasis>. </para> <literallayout class="monospaced"> typedef enum { - XrmoptionNoArg, /* Value is specified in OptionDescRec.value */ - XrmoptionIsArg, /* Value is the option string itself */ - XrmoptionStickyArg, /* Value is characters immediately following option */ - XrmoptionSepArg, /* Value is next argument in argv */ - XrmoptionResArg, /* Use the next argument as input to XrmPutLineResource*/ - XrmoptionSkipArg, /* Ignore this option and the next argument in argv */ - XrmoptionSkipNArgs, /* Ignore this option and the next */ - /* OptionDescRec.value arguments in argv */ - XrmoptionSkipLine /* Ignore this option and the rest of argv */ + XrmoptionNoArg, /* Value is specified in OptionDescRec.value */ + XrmoptionIsArg, /* Value is the option string itself */ + XrmoptionStickyArg, /* Value is characters immediately following option */ + XrmoptionSepArg, /* Value is next argument in argv */ + XrmoptionResArg, /* Use the next argument as input to XrmPutLineResource*/ + XrmoptionSkipArg, /* Ignore this option and the next argument in argv */ + XrmoptionSkipNArgs, /* Ignore this option and the next */ + /* OptionDescRec.value arguments in argv */ + XrmoptionSkipLine /* Ignore this option and the rest of argv */ } XrmOptionKind; typedef struct { - char *option; /* Option name in argv */ - char *specifier; /* Resource name (without application name) */ - XrmOptionKind argKind; /* Location of the resource value */ - XPointer value; /* Value to provide if XrmoptionNoArg */ + 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> -The standard table contains the following entries: +<para>The standard table contains the following entries:</para> + <informaltable> - <tgroup cols='3' align='center'> + <tgroup cols='4' align='center'> + <thead> + <row> + <entry>Option String</entry> + <entry>Resource Name</entry> + <entry>Argument Kind</entry> + <entry>Resource Value</entry> + </row> + </thead> <tbody> <row> - <entry></entry> - <entry></entry> - <entry></entry> + <entry>−background</entry> + <entry>*background</entry> + <entry>SepArg</entry> + <entry>next argument</entry> + </row> + <row> + <entry>−bd</entry> + <entry>*borderColor</entry> + <entry>SepArg</entry> + <entry>next argument</entry> + </row> + <row> + <entry>−bg</entry> + <entry>*background</entry> + <entry>SepArg</entry> + <entry>next argument</entry> + </row> + <row> + <entry>−borderwidth</entry> + <entry>.borderWidth</entry> + <entry>SepArg</entry> + <entry>next argument</entry> + </row> + <row> + <entry>−bordercolor</entry> + <entry>*borderColor</entry> + <entry>SepArg</entry> + <entry>next argument</entry> + </row> + <row> + <entry>−bw</entry> + <entry>.borderWidth</entry> + <entry>SepArg</entry> + <entry>next argument</entry> + </row> + <row> + <entry>−display</entry> + <entry>.display</entry> + <entry>SepArg</entry> + <entry>next argument</entry> + </row> + <row> + <entry>−fg</entry> + <entry>*foreground</entry> + <entry>SepArg</entry> + <entry>next argument</entry> + </row> + <row> + <entry>−fn</entry> + <entry>*font</entry> + <entry>SepArg</entry> + <entry>next argument</entry> + </row> + <row> + <entry>−font</entry> + <entry>*font</entry> + <entry>SepArg</entry> + <entry>next argument</entry> + </row> + <row> + <entry>−foreground</entry> + <entry>*foreground</entry> + <entry>SepArg</entry> + <entry>next argument</entry> + </row> + <row> + <entry>−geometry</entry> + <entry>.geometry</entry> + <entry>SepArg</entry> + <entry>next argument</entry> + </row> + <row> + <entry>−iconic</entry> + <entry>.iconic</entry> + <entry>NoArg</entry> + <entry>"true"</entry> + </row> + <row> + <entry>−name</entry> + <entry>.name</entry> + <entry>SepArg</entry> + <entry>next argument</entry> + </row> + <row> + <entry>−reverse</entry> + <entry>.reverseVideo</entry> + <entry>NoArg</entry> + <entry>"on"</entry> + </row> + <row> + <entry>−rv</entry> + <entry>.reverseVideo</entry> + <entry>NoArg</entry> + <entry>"on"</entry> + </row> + <row> + <entry>+rv</entry> + <entry>.reverseVideo</entry> + <entry>NoArg</entry> + <entry>"off"</entry> + </row> + <row> + <entry>−selectionTimeout</entry> + <entry>.selectionTimeout</entry> + <entry>SepArg</entry> + <entry>next argument</entry> + </row> + <row> + <entry>−synchronous</entry> + <entry>.synchronous</entry> + <entry>NoArg</entry> + <entry>"on"</entry> + </row> + <row> + <entry>+synchronous</entry> + <entry>.synchronous</entry> + <entry>NoArg</entry> + <entry>"off"</entry> + </row> + <row> + <entry>−title</entry> + <entry>.title</entry> + <entry>SepArg</entry> + <entry>next argument</entry> + </row> + <row> + <entry>−xnllanguage</entry> + <entry>.xnlLanguage</entry> + <entry>SepArg</entry> + <entry>next argument</entry> + </row> + <row> + <entry>−xrm</entry> + <entry>next argument</entry> + <entry>ResArg</entry> + <entry>next argument</entry> + </row> + <row> + <entry>−xtsessionID</entry> + <entry>.sessionID</entry> + <entry>SepArg</entry> + <entry>next argument</entry> </row> </tbody> </tgroup> </informaltable> -</para> <para> Note that any unique abbreviation for an option name in the standard table @@ -1323,7 +1475,7 @@ specified is used for all displays in the application context. </para> <para> -The \-xrm option provides a method of setting any resource in an application. +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, @@ -1332,7 +1484,7 @@ to give a red background to all command buttons in an application named you can start it up as </para> <literallayout class="monospaced"> -xmh \-xrm 'xmh*Command.background: red' +xmh -xrm 'xmh*Command.background: red' </literallayout> <para> When it parses the command line, @@ -1355,7 +1507,8 @@ beginning with the characters ``-xt'' for future standard uses. <para> The creation of widget instances is a three-phase process: </para> -<itemizedlist> + +<orderedlist> <listitem> <para> The widgets are allocated and initialized with resources @@ -1373,20 +1526,18 @@ in a bottom-up traversal of the widget tree. The widgets create X windows, which then are mapped. </para> </listitem> -</itemizedlist> +</orderedlist> <para> -delim $$ 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>. -To avoid an $O( n sup 2 )$ creation process where each composite widget +To avoid an O(n<superscript>2</superscript>) 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. -delim off </para> <para> @@ -1469,9 +1620,9 @@ use <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> + <paramdef>Arg <parameter>arg</parameter></paramdef> + <paramdef>String <parameter>name</parameter></paramdef> + <paramdef>XtArgVal <parameter>value</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -1708,6 +1859,7 @@ typedef XtPointer XtVarArgsList; <funcprototype> <funcdef>XtVarArgsList <function>XtVaCreateArgsList</function></funcdef> <paramdef>XtPointer <parameter>unused</parameter></paramdef> + <paramdef> <parameter>...</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -1858,7 +2010,7 @@ and the parent's class is a subclass of and either no extension record in the parent's composite class part extension field exists with the <emphasis remap='I'>record_type</emphasis> -<function>\s-1NULLQUARK\s+1</function> +<emphasis role='bold'>NULLQUARK</emphasis> or the <emphasis remap='I'>accepts_objects</emphasis> field in the extension record is <function>False</function>, @@ -1870,7 +2022,7 @@ issues a fatal error; see Section 3.1 and Chapter 12. <para> If the specified class contains an extension record in the object class part <emphasis remap='I'>extension</emphasis> field with <emphasis remap='I'>record_type</emphasis> -<function>\s-1NULLQUARK\s+1</function> +<emphasis role='bold'>NULLQUARK</emphasis> 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 @@ -1953,6 +2105,7 @@ To create an instance of a widget using varargs lists, use <paramdef>String <parameter>name</parameter></paramdef> <paramdef>WidgetClass <parameter>object_class</parameter></paramdef> <paramdef>Widget <parameter>parent</parameter></paramdef> + <paramdef> <parameter>...</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -2028,7 +2181,7 @@ to create independent widget trees. <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>Display * <parameter>display</parameter></paramdef> <paramdef>ArgList <parameter>args</parameter></paramdef> <paramdef>Cardinal <parameter>num_args</parameter></paramdef> </funcprototype> @@ -2138,12 +2291,12 @@ resource names for objects within this widget tree. <para> 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> +<emphasis role='bold'>WM_CLASS</emphasis> property on the widget's window when it becomes realized. If the specified <emphasis remap='I'>widget_class</emphasis> is <function>applicationShellWidgetClass</function> or a subclass thereof, the -<function>\s-1WM_COMMAND\s+1</function> +<emphasis role='bold'>WM_COMMAND</emphasis> property will also be set from the values of the XtNargv and XtNargc resources. </para> @@ -2199,7 +2352,7 @@ varargs lists, use <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>Display * <parameter>display</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -2290,13 +2443,13 @@ or <funcsynopsis id='XtOpenApplication'> <funcprototype> <funcdef>Widget <function>XtOpenApplication</function></funcdef> - <paramdef>XtAppContext *<parameter>app_context_return</parameter></paramdef> + <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>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> @@ -2444,13 +2597,13 @@ is called with the value prior to calling <funcsynopsis id='XtVaOpenApplication'> <funcprototype> <funcdef>Widget <function>XtVaOpenApplication</function></funcdef> - <paramdef>XtAppContext *<parameter>app_context_return</parameter></paramdef> + <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>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> @@ -2591,9 +2744,9 @@ record is of type <function>XtAllocateProc</function>. </para> -<funcsynopsis id='XtAppContext'> +<funcsynopsis id='XtAllocateProc'> <funcprototype> - <funcdef>void <function>(*XtAppContext)</function></funcdef> + <funcdef>typedef void <function>(*AllocateProc)</function></funcdef> <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef> <paramdef>Cardinal* <parameter>constraint_size</parameter></paramdef> <paramdef>Cardinal* <parameter>more_bytes</parameter></paramdef> @@ -2702,13 +2855,13 @@ if requested and an error occurred; otherwise, unchanged. <para> At widget allocation time, if an extension record with <emphasis remap='I'>record_type</emphasis> equal to -<function>\s-1NULLQUARK\s+1</function> +<emphasis role='bold'>NULLQUARK</emphasis> is located through the object class part <emphasis remap='I'>extension</emphasis> field 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>, +<emphasis role='bold'>NULLQUARK</emphasis>, then <function>XtInheritAllocate</function> and @@ -2770,11 +2923,11 @@ The initialize procedure pointer in a widget class is of type <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> + <funcdef>typedef 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> @@ -2847,7 +3000,9 @@ 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. +<note><para> It is not necessary to allocate space for or to copy callback lists. +</para></note> </para> </listitem> <listitem> @@ -2856,10 +3011,12 @@ 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. +<note><para> 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. +</para></note> </para> </listitem> <listitem> @@ -2984,11 +3141,13 @@ in the class record. <sect2 id="Nonwidget_Data_Initialization_The_initialize_hook_Procedure"> <title>Nonwidget Data Initialization: The initialize_hook Procedure</title> +<note> <para> 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. </para> +</note> <para> The initialize_hook procedure pointer is of type @@ -2997,10 +3156,10 @@ The initialize_hook procedure pointer is of type <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> + <funcdef>typedef 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> @@ -3066,8 +3225,8 @@ To realize a widget instance, use <funcsynopsis id='XtRealizeWidget'> <funcprototype> - <funcdef>void<function>XtRealizeWidget</function></funcdef> - <paramdef>Widget<parameter> w</parameter></paramdef> + <funcdef>void <function>XtRealizeWidget</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -3123,21 +3282,25 @@ returns; otherwise it continues and performs the following: </para> </listitem> <listitem> - <para> + <itemizedlist> + <listitem> + <para> Descends recursively to each of the widget's managed children and calls the realize procedures. Primitive widgets that instantiate children are responsible for realizing those children themselves. - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> Maps all of the managed children windows that have <emphasis remap='I'>mapped_when_managed</emphasis> <function>True</function>. If a widget is managed but <emphasis remap='I'>mapped_when_managed</emphasis> is <function>False</function>, the widget is allocated visual space but is not displayed. - </para> + </para> + </listitem> + </itemizedlist> </listitem> </itemizedlist> <para> @@ -3199,8 +3362,8 @@ To check whether or not a widget has been realized, use <funcsynopsis id='XtIsRealized'> <funcprototype> - <funcdef>Boolean<function>XtIsRealized</function></funcdef> - <paramdef>Widget<parameter> w</parameter></paramdef> + <funcdef>Boolean <function>XtIsRealized</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -3241,10 +3404,10 @@ The realize procedure pointer in a widget class is of type <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> + <funcdef>typedef 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> @@ -3415,12 +3578,12 @@ which simplifies the creation of windows for widgets. <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> + <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> @@ -3520,8 +3683,8 @@ and to the application writer by means of functions. <funcsynopsis> <funcprototype> - <funcdef>Display<function>XtDisplay</function></funcdef> - <paramdef>Widget<parameter> w</parameter></paramdef> + <funcdef>Display <function>XtDisplay</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -3544,8 +3707,8 @@ returns the display pointer for the specified widget. <funcsynopsis> <funcprototype> - <funcdef>Widget<function>XtParent</function></funcdef> - <paramdef>Widget<parameter> w</parameter></paramdef> + <funcdef>Widget <function>XtParent</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -3569,8 +3732,8 @@ will be of class Object or a subclass. <funcsynopsis id='XtScreen'> <funcprototype> - <funcdef>Screen<function>*XtScreen</function></funcdef> - <paramdef>Widget<parameter> w</parameter></paramdef> + <funcdef>Screen <function>*XtScreen</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -3593,8 +3756,8 @@ returns the screen pointer for the specified widget. <funcsynopsis id='XtWindow'> <funcprototype> - <funcdef>Window<function>XtWindow</function></funcdef> - <paramdef>Widget<parameter> w</parameter></paramdef> + <funcdef>Window <function>XtWindow</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -3628,7 +3791,7 @@ and <funcsynopsis id='XtDisplayOfObject'> <funcprototype> <funcdef>Display <function>*XtDisplayOfObject</function></funcdef> - <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>Widget <parameter>w</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -3658,7 +3821,7 @@ Widget or a subclass thereof. <funcsynopsis id='XtScreenOfObject'> <funcprototype> <funcdef>Screen <function>*XtScreenOfObject</function></funcdef> - <paramdef>Widget<parameter> object</parameter></paramdef> + <paramdef>Widget <parameter>object</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -3689,7 +3852,7 @@ Widget or a subclass thereof. <funcsynopsis id='XtWindowOfObject'> <funcprototype> <funcdef>Window <function>XtWindowOfObject</function></funcdef> - <paramdef>Widget<parameter> object</parameter></paramdef> + <paramdef>Widget <parameter>object</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -3723,7 +3886,7 @@ To retrieve the instance name of an object, use <funcsynopsis id='XtName'> <funcprototype> <funcdef>String <function>XtName</function></funcdef> - <paramdef>Widget<parameter> object</parameter></paramdef> + <paramdef>Widget <parameter>object</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -3791,8 +3954,8 @@ non-pop-up descendants, use <funcsynopsis id='XtUnrealizeWidget'> <funcprototype> - <funcdef>void<function>XtUnrealizeWidget</function></funcdef> - <paramdef>Widget<parameter> w</parameter></paramdef> + <funcdef>void <function>XtUnrealizeWidget</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -3890,8 +4053,8 @@ To destroy a widget instance, use <funcsynopsis id='XtDestroyWidget'> <funcprototype> - <funcdef>void<function>XtDestroyWidget</function></funcdef> - <paramdef>Widget<parameter> w</parameter></paramdef> + <funcdef>void <function>XtDestroyWidget</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -4025,7 +4188,7 @@ class record. Callback lists are deallocated. If the widget class object class part contains an <function>ObjectClassExtension</function> record with the record_type -<function>\s-1NULLQUARK\s+1</function> +<emphasis role='bold'>NULLQUARK</emphasis> 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 Intrinsics will deallocate @@ -4094,8 +4257,8 @@ structures are of type <funcsynopsis id='XtWidgetProc'> <funcprototype> - <funcdef>void<function>XtWidgetProc</function></funcdef> - <paramdef>Widget<parameter> w</parameter></paramdef> + <funcdef>typedef void <function>XtWidgetProc</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -4229,9 +4392,9 @@ record is of type <funcsynopsis> <funcprototype> - <funcdef>void<function>(*XtDeallocateProc)</function></funcdef> - <paramdef>Widget<parameter> widget</parameter></paramdef> - <paramdef>XtPointer<parameter> more_bytes</parameter></paramdef> + <funcdef>typedef void <function>(*XtDeallocateProc)</function></funcdef> + <paramdef>Widget <parameter>widget</parameter></paramdef> + <paramdef>XtPointer <parameter>more_bytes</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -4263,13 +4426,13 @@ When a widget is destroyed, if an <function>ObjectClassExtension</function> record exists in the object class part <emphasis remap='I'>extension</emphasis> field with <emphasis remap='I'>record_type</emphasis> -<function>\s-1NULLQUARK\s+1</function> +<emphasis role='bold'>NULLQUARK</emphasis> and the <emphasis remap='I'>deallocate</emphasis> field is not NULL, the <function>XtDeallocateProc</function> 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>, +<emphasis role='bold'>NULLQUARK</emphasis>, then <function>XtInheritAllocate</function> and @@ -4294,7 +4457,7 @@ originally allocated the memory and is responsible for freeing it. <sect1 id="Exiting_from_an_Application"> <title>Exiting from an Application</title> <para> -All (tk applications should terminate +All X Toolkit applications should terminate by calling <function>XtDestroyApplicationContext</function> and then exiting |