svn merge ^/branches/released .

1 files changed, 1204 insertions, 0 deletions

diff --git a/libXt/specs/appC b/libXt/specs/appC
new file mode 100644
index 000000000..6f31fd7d5
--- /dev/null
+++ b/libXt/specs/appC
@@ -0,0 +1,1204 @@
+.\" $Xorg: appC,v 1.3 2000/08/17 19:42:48 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.
+.\"
+.bp
+\&
+.sp 1
+.ce 3
+\s+1\fBAppendix C\fP\s-1
+
+\s+1\fBCompatibility Functions\fP\s-1
+.sp 2
+.LP
+.XS
+\fBAppendix C \(em Compatibility Functions\fP
+.XE
+.FS
+This appendix is part of the formal Intrinsics Specification.
+.FE
+.LP
+In prototype versions of the \*(tk
+each widget class
+implemented an Xt<\^\fIWidget\fP\^>Create (for example,
+.PN XtLabelCreate )
+function, in which most of the code was identical from widget to widget.
+In the \*(xI, a single generic
+.PN XtCreateWidget
+performs most of the common work and then calls the initialize procedure
+implemented for the particular widget class.
+.LP
+Each Composite class also implemented the procedures
+Xt<\^\fIWidget\fP\^>Add and an Xt<\^\fIWidget\fP\^>Delete (for example,
+.PN XtButtonBoxAddButton
+and
+.PN XtButtonBoxDeleteButton ).
+In the \*(xI, the Composite generic procedures
+.PN XtManageChildren
+and
+.PN XtUnmanageChildren
+perform error checking and screening out of certain children.
+Then they call the change_managed procedure
+implemented for the widget's Composite class.
+If the widget's parent has not yet been realized,
+the call to the change_managed procedure is delayed until realization time.
+.LP
+Old-style calls can be implemented in the \*(tk by defining
+one-line procedures or macros that invoke a generic routine.  For example,
+you could define the macro
+.PN XtLabelCreate
+as:
+.IP
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+#define XtLabelCreate(\fIname\fP, \fIparent\fP, \fIargs\fP, \fInum_args\fP) \\
+        ((LabelWidget) XtCreateWidget(\fIname\fP, \fIlabelWidgetClass\fP,   \
+\fIparent\fP, \fIargs\fP, \fInum_args\fP))
+.De
+.sp
+.LP
+Pop-up shells in some of the prototypes automatically performed an
+.PN XtManageChild
+on their child within their insert_child procedure.
+.IN "insert_child procedure"
+Creators of pop-up children need to call
+.PN XtManageChild
+themselves.
+.sp
+.LP
+.PN XtAppInitialize
+and 
+.PN XtVaAppInitialize 
+have been replaced by 
+.PN XtOpenApplication
+and
+.PN XtVaOpenApplication .
+.LP
+To initialize the \*(xI internals, create an application context,
+open and initialize a display, and create the initial application shell
+instance, an application may use
+.PN XtAppInitialize
+or
+.PN XtVaAppInitialize .
+.LP
+.IN "XtAppInitialize" "" "@DEF@"
+.sM
+.FD 0
+Widget XtAppInitialize(\fIapp_context_return\fP, \fIapplication_class\fP, \
+\fIoptions\fP, \fInum_options\fP,
+.br
+                       \fIargc_in_out\fP, \fIargv_in_out\fP, \
+\fIfallback_resources\fP, \fIargs\fP, \fInum_args\fP)
+.br
+      XtAppContext *\fIapp_context_return\fP;
+.br
+      String \fIapplication_class\fP;
+.br
+      XrmOptionDescList \fIoptions\fP;
+.br
+      Cardinal \fInum_options\fP;
+.br
+      int *\fIargc_in_out\fP;
+.br
+      String *\fIargv_in_out\fP;
+.br
+      String *\fIfallback_resources\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIapp_context_return\fP 1.5i
+Returns the application context, if non-NULL.
+.IP \fIapplication_class\fP 1.5i
+Specifies the class name of the application.
+.IP \fIoptions\fP 1.5i
+Specifies the command line options table.
+.IP \fInum_options\fP 1.5i
+Specifies the number of entries in \fIoptions\fP.
+.IP \fIargc_in_out\fP 1.5i
+Specifies a pointer to the number of command line arguments.
+.IP \fIargv_in_out\fP 1.5i
+Specifies a pointer to the command line arguments.
+.IP \fIfallback_resources\fP 1.5i
+Specifies resource values to be used if the application class resource
+file cannot be opened or read, or NULL.
+.IP \fIargs\fP 1.5i
+Specifies the argument list to override any
+other resource specifications for the created shell widget.
+.IP \fInum_args\fP 1.5i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+The
+.PN XtAppInitialize
+function calls
+.PN XtToolkitInitialize
+followed by
+.PN XtCreateApplicationContext ,
+then calls
+.PN XtOpenDisplay
+with \fIdisplay_string\fP NULL and
+\fIapplication_name\fP NULL, and finally calls
+.PN XtAppCreateShell
+with \fIapplication_name\fP NULL, \fIwidget_class\fP
+.PN application\%Shell\%Widget\%Class ,
+and the specified \fIargs\fP and \fInum_args\fP
+and returns the created shell.  The modified \fIargc\fP and \fIargv\fP returned by
+.PN XtDisplayInitialize
+are returned in \fIargc_in_out\fP and \fIargv_in_out\fP.  If
+\fIapp_context_return\fP is not NULL, the created application context is
+also returned.  If the display specified by the command line cannot be
+opened, an error message is issued and
+.PN XtAppInitialize
+terminates the application.  If \fIfallback_resources\fP is non-NULL,
+.PN XtAppSetFallbackResources
+is called with the value prior to calling
+.PN XtOpenDisplay .
+.sp
+.LP
+.IN "XtVaAppInitialize" "" "@DEF@"
+.sM
+.FD 0
+Widget XtVaAppInitialize(\fIapp_context_return\fP, \fIapplication_class\fP, \
+\fIoptions\fP, \fInum_options\fP,
+.br
+                         \fIargc_in_out\fP, \fIargv_in_out\fP, \
+\fIfallback_resources\fP, ...)
+.br
+    XtAppContext *\fIapp_context_return\fP;
+.br
+    String \fIapplication_class\fP;
+.br
+    XrmOptionDescList \fIoptions\fP;
+.br
+    Cardinal \fInum_options\fP;
+.br
+    int *\fIargc_in_out\fP;
+.br
+    String *\fIargv_in_out\fP;
+.br
+    String *\fIfallback_resources\fP;
+.FN
+.IP \fIapp_context_return\fP 1.5i
+Returns the application context, if non-NULL.
+.IP \fIapplication_class\fP 1.5i
+Specifies the class name of the application.
+.IP \fIoptions\fP 1.5i
+Specifies the command line options table.
+.IP \fInum_options\fP 1.5i
+Specifies the number of entries in \fIoptions\fP.
+.IP \fIargc_in_out\fP 1.5i
+Specifies a pointer to the number of command line arguments.
+.IP \fIargv_in_out\fP 1.5i
+Specifies the command line arguments array.
+.IP \fIfallback_resources\fP 1.5i
+Specifies resource values to be used if the application class
+resource file cannot be opened, or NULL.
+.IP ... 1.5i
+Specifies the variable argument list to override any other
+resource specifications for the created shell.
+.LP
+.eM
+The
+.PN XtVaAppInitialize
+procedure is identical in function to
+.PN XtAppInitialize
+with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list,
+as described
+in Section 2.5.1.
+.sp
+.LP
+As a convenience to people converting from earlier versions of the toolkit
+without application contexts, the following routines exist:
+.PN XtInitialize ,
+.PN XtMainLoop ,
+.PN XtNextEvent ,
+.PN XtProcessEvent ,
+.PN XtPeekEvent ,
+.PN XtPending ,
+.PN XtAddInput ,
+.PN XtAddTimeOut ,
+.PN XtAddWorkProc ,
+.PN XtCreateApplicationShell ,
+.PN XtAddActions ,
+.PN XtSetSelectionTimeout ,
+and
+.PN XtGetSelectionTimeout .
+.LP
+.IN "XtInitialize" "" "@DEF@"
+.sM
+.FD 0
+Widget XtInitialize(\fIshell_name\fP, \fIapplication_class\fP, \fIoptions\fP, \
+\fInum_options\fP, \fIargc\fP, \fIargv\fP)
+.br
+      String \fIshell_name\fP;
+.br
+      String \fIapplication_class\fP;
+.br
+      XrmOptionDescRec \fIoptions\fP[];
+.br
+      Cardinal \fInum_options\fP;
+.br
+      int *\fIargc\fP;
+.br
+      String \fIargv\fP[];
+.FN
+.IP \fIshell_name\fP 1i
+This parameter is ignored; therefore, you can specify NULL.
+.IP \fIapplication_class\fP 1i
+Specifies the class name of this application.
+.IP \fIoptions\fP 1i
+Specifies how to parse the command line for any application-specific resources.
+The \fIoptions\fP argument is passed as a parameter to 
+.PN XrmParseCommand .
+.IP \fInum_options\fP 1i
+Specifies the number of entries in the options list.
+.IP \fIargc\fP 1i
+Specifies a pointer to the number of command line parameters.
+.IP \fIargv\fP 1i
+Specifies the command line parameters.
+.LP
+.eM
+.PN XtInitialize
+calls
+.PN XtToolkitInitialize
+to initialize the toolkit internals,
+creates a default application context for use by the other convenience
+routines, calls
+.PN XtOpenDisplay
+with \fIdisplay_string\fP NULL and \fIapplication_name\fP NULL, and
+finally calls
+.PN XtAppCreateShell
+with \fIapplication_name\fP NULL and
+returns the created shell.
+The semantics of calling
+.PN XtInitialize
+more than once are undefined.
+This routine has been replaced by
+.PN XtOpenApplication .
+.sp
+.IN "XtMainLoop" "" "@DEF@"
+.sM
+.FD 0
+void XtMainLoop(void)
+.FN
+.LP
+.eM
+.PN XtMainLoop
+first reads the next alternate input, timer, or X event by calling
+.PN XtNextEvent .
+Then it dispatches this to the appropriate registered procedure by calling
+.PN XtDispatchEvent .
+This routine has been replaced by
+.PN XtAppMainLoop .
+.sp
+.IN "XtNextEvent" "" "@DEF@"
+.sM
+.FD 0
+void XtNextEvent(\fIevent_return\fP)
+.br
+      XEvent *\fIevent_return\fP;
+.FN
+.IP \fIevent_return\fP 1i
+Returns the event information to the specified event structure.
+.LP
+.eM
+If no input is on the X input queue for the default application context, 
+.PN XtNextEvent 
+flushes the X output buffer 
+and waits for an event while looking at the alternate input sources 
+and timeout values and calling any callback procedures triggered by them.
+This routine has been replaced by
+.PN XtAppNextEvent .
+.PN XtInitialize
+must be called before using this routine.
+.sp
+.IN "XtProcessEvent" "" "@DEF@"
+.sM
+.FD 0
+void XtProcessEvent(\fImask\fP)
+.br
+      XtInputMask \fImask\fP;
+.FN
+.IP \fImask\fP 1i
+Specifies the type of input to process.
+.LP
+.eM
+.PN XtProcessEvent
+processes one X event, timeout, or alternate input source 
+(depending on the value of \fImask\fP), blocking if necessary.
+It has been replaced by
+.PN XtAppProcessEvent .
+.PN XtInitialize
+must be called before using this function.
+.sp
+.IN "XtPeekEvent" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtPeekEvent(\fIevent_return\fP)
+.br
+      XEvent *\fIevent_return\fP;
+.FN
+.IP \fIevent_return\fP 1i
+Returns the event information to the specified event structure.
+.LP
+.eM
+If there is an event in the queue for the default application context, 
+.PN XtPeekEvent
+fills in the event and returns a nonzero value.
+If no X input is on the queue, 
+.PN XtPeekEvent
+flushes the output buffer and blocks until input is available, possibly
+calling some timeout callbacks in the process.
+If the input is an event,
+.PN XtPeekEvent
+fills in the event and returns a nonzero value. 
+Otherwise, the input is for an alternate input source, and
+.PN XtPeekEvent
+returns zero. 
+This routine has been replaced by
+.PN XtAppPeekEvent .
+.PN XtInitialize
+must be called before using this routine.
+.sp
+.IN "XtPending" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtPending()
+.FN
+.LP
+.eM
+.PN XtPending
+returns a nonzero value if there are 
+events pending from the X server or alternate input sources in the default
+application context.
+If there are no events pending, 
+it flushes the output buffer and returns a zero value.
+It has been replaced by
+.PN XtAppPending .
+.PN XtInitialize
+must be called before using this routine.
+.sp
+.IN "XtAddInput" "" "@DEF@"
+.sM
+.FD 0
+XtInputId XtAddInput(\fIsource\fP, \fIcondition\fP, \fIproc\fP, \
+\fIclient_data\fP)
+.br
+      int \fIsource\fP;
+.br
+      XtPointer \fIcondition\fP;
+.br
+      XtInputCallbackProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIsource\fP 1i
+Specifies the source file descriptor on a POSIX-based system 
+or other operating-system-dependent device specification.
+.IP \fIcondition\fP 1i
+Specifies the mask that indicates either a read, write, or exception condition
+or some operating-system-dependent condition.
+.IP \fIproc\fP 1i
+Specifies the procedure called when input is available.
+.IP \fIclient_data\fP 1i
+Specifies the parameter to be passed to \fIproc\fP when input is available.
+.LP
+.eM
+The 
+.PN XtAddInput
+function registers in the default application context a new 
+source of events, 
+which is usually file input but can also be file output.
+(The word \fIfile\fP should be loosely interpreted to mean any sink 
+or source of data.)
+.PN XtAddInput
+also specifies the conditions under which the source can generate events.
+When input is pending on this source in the default application context, 
+the callback procedure is called.
+This routine has been replaced by
+.PN XtAppAddInput .
+.PN XtInitialize
+must be called before using this routine.
+.sp
+.IN "XtAddTimeOut" "" "@DEF@"
+.sM
+.FD 0
+XtIntervalId XtAddTimeOut(\fIinterval\fP, \fIproc\fP, \fIclient_data\fP)
+.br
+      unsigned long \fIinterval\fP;
+.br
+      XtTimerCallbackProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIinterval\fP 1i
+Specifies the time interval in milliseconds.
+.IP \fIproc\fP 1i
+Specifies the procedure to be called when time expires.
+.IP \fIclient_data\fP 1i
+Specifies the parameter to be passed to \fIproc\fP when it is called.
+.LP
+.eM
+The 
+.PN XtAddTimeOut
+function creates a timeout in the default application context
+and returns an identifier for it.
+The timeout value is set to \fIinterval\fP.
+The callback procedure will be called after
+the time interval elapses, after which the timeout is removed.
+This routine has been replaced by 
+.PN XtAppAddTimeOut .
+.PN XtInitialize
+must be called before using this routine.
+.sp
+.IN "XtAddWorkProc" "" "@DEF@"
+.sM
+.FD 0
+XtWorkProcId XtAddWorkProc(\fIproc\fP, \fIclient_data\fP)
+.br
+      XtWorkProc \fIproc\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIproc\fP 1i
+Procedure to call to do the work.
+.IP \fIclient_data\fP 1i
+Client data to pass to \fIproc\fP when it is called.
+.LP
+.eM
+This routine registers a work procedure in the default application context. It has
+been replaced by
+.PN XtAppAddWorkProc .
+.PN XtInitialize
+must be called before using this routine.
+.sp
+.IN "XtCreateApplicationShell" "" "@DEF@"
+.sM
+.FD 0
+Widget XtCreateApplicationShell(\fIname\fP, \fIwidget_class\fP, \fIargs\fP, \
+\fInum_args\fP)
+.br
+      String \fIname\fP;
+.br
+      WidgetClass \fIwidget_class\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIname\fP 1i
+This parameter is ignored; therefore, you can specify NULL.
+.IP \fIwidget_class\fP 1i
+Specifies the widget class pointer for the created application shell widget.
+This will usually be 
+.PN topLevelShellWidgetClass 
+or a subclass thereof.
+.IP \fIargs\fP 1i
+Specifies the argument list to override  any other resource specifications.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in \fIargs\fP.
+.LP
+.eM
+The procedure
+.PN XtCreateApplicationShell
+calls
+.PN XtAppCreateShell
+with \fIapplication_name\fP NULL, the application class passed to
+.PN XtInitialize ,
+and the default application context created by
+.PN XtInitialize .
+This routine has been replaced by
+.PN XtAppCreateShell .
+.sp
+.LP
+An old-format resource type converter procedure pointer is of type
+.PN XtConverter .
+.LP
+.IN "XtConverter" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtConverter)(XrmValue*, Cardinal*, XrmValue*, XrmValue*);
+.br
+      XrmValue *\fIargs\fP;
+.br
+      Cardinal *\fInum_args\fP;
+.br
+      XrmValue *\fIfrom\fP;
+.br
+      XrmValue *\fIto\fP;
+.FN
+.IP \fIargs\fP 1i
+Specifies a list of additional
+.PN XrmValue
+arguments to the converter if additional context is needed
+to perform the conversion, or NULL.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in \fIargs\fP.
+.IP \fIfrom\fP 1i
+Specifies the value to convert.
+.IP \fIto\fP 1i
+Specifies the descriptor to use to return the converted value.
+.LP
+.eM
+Type converters should perform the following actions:
+.IP \(bu 5
+Check to see that the number of arguments passed is correct.
+.IP \(bu 5
+Attempt the type conversion.
+.IP \(bu 5
+If successful, return the size and pointer to the data in the \fIto\fP argument;
+otherwise, call
+.PN XtWarningMsg
+and return without modifying the \fIto\fP argument.
+.LP
+Most type converters just take the data described by the specified \fIfrom\fP
+argument and return data by writing into the specified \fIto\fP argument.
+A few need other information, which is available in the specified 
+argument list.
+A type converter can invoke another type converter,
+which allows differing sources that may convert into a common intermediate
+result to make maximum use of the type converter cache.
+.LP
+Note that the address returned in \fIto->addr\fP cannot be that of a local variable of 
+the converter because this is not valid after the converter returns.
+It should be a pointer to a static variable.
+.LP
+The procedure type
+.PN XtConverter
+has been replaced by
+.PN XtTypeConverter .
+.sp
+.LP
+The
+.PN XtStringConversionWarning
+.IN "XtStringConversionWarning" "" "@DEF@"
+function is a convenience routine for old-format resource converters
+that convert from strings.
+.LP
+.sM
+.FD 0
+void XtStringConversionWarning(\fIsrc\fP, \fIdst_type\fP)
+.br
+      String \fIsrc\fP, \fIdst_type\fP;
+.FN
+.IP \fIsrc\fP 1i
+Specifies the string that could not be converted.
+.IP \fIdst_type\fP 1i
+Specifies the name of the type to which the string could not be converted.
+.LP
+.eM
+The
+.PN XtStringConversionWarning
+function issues a warning message with name ``conversionError'',
+type ``string'', class ``XtToolkitError, and the default message string
+``Cannot convert "\fIsrc\fP" to type \fIdst_type\fP''.  This routine
+has been superseded by
+.PN XtDisplayStringConversionWarning .
+.sp
+.LP
+To register an old-format converter, use
+.PN XtAddConverter
+.IN "XtAddConverter" "" "@DEF@"
+or
+.PN XtAppAddConverter .
+.IN "XtAppAddConverter" "" "@DEF@"
+.LP
+.sM
+.FD 0
+void XtAddConverter(\fIfrom_type\fP, \fIto_type\fP, \fIconverter\fP, \
+\fIconvert_args\fP, \fInum_args\fP)
+.br
+      String \fIfrom_type\fP;
+.br
+      String \fIto_type\fP;
+.br
+      XtConverter \fIconverter\fP;
+.br
+      XtConvertArgList \fIconvert_args\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIfrom_type\fP 1i
+Specifies the source type.
+.IP \fIto_type\fP 1i
+Specifies the destination type.
+.IP \fIconverter\fP 1i
+Specifies the type converter procedure.
+.IP \fIconvert_args\fP 1i
+Specifies how to compute the additional arguments to the converter, or NULL.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in \fIconvert_args\fP.
+.sp
+.LP
+.eM
+.PN XtAddConverter
+is equivalent in function to
+.PN XtSetTypeConverter
+with \fIcache_type\fP equal to
+.PN XtCacheAll
+for old-format type converters.  It has been superseded by
+.PN XtSetTypeConverter .
+.sp
+.sM
+.FD 0
+void XtAppAddConverter(\fIapp_context\fP, \fIfrom_type\fP, \fIto_type\fP, \
+\fIconverter\fP, \fIconvert_args\fP, \fInum_args\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      String \fIfrom_type\fP;
+.br
+      String \fIto_type\fP;
+.br
+      XtConverter \fIconverter\fP;
+.br
+      XtConvertArgList \fIconvert_args\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fIfrom_type\fP 1i
+Specifies the source type.
+.IP \fIto_type\fP 1i
+Specifies the destination type.
+.IP \fIconverter\fP 1i
+Specifies the type converter procedure.
+.IP \fIconvert_args\fP 1i
+Specifies how to compute the additional arguments to the converter, or NULL.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in \fIconvert_args\fP.
+.LP
+.eM
+.PN XtAppAddConverter
+is equivalent in function to
+.PN XtAppSetTypeConverter
+with \fIcache_type\fP equal to
+.PN XtCacheAll
+for old-format type converters.  It has been superseded by
+.PN XtAppSetTypeConverter .
+.sp
+.LP
+To invoke resource conversions, a client may use
+.PN XtConvert
+or, for old-format converters only,
+.PN XtDirectConvert .
+.LP
+.IN "XtConvert" "" "@DEF@"
+.sM
+.FD 0
+void XtConvert(\fIw\fP, \fIfrom_type\fP, \fIfrom\fP, \fIto_type\fP, \
+\fIto_return\fP)
+.br
+      Widget \fIw\fP;
+.br
+      String \fIfrom_type\fP;
+.br
+      XrmValuePtr \fIfrom\fP;
+.br
+      String \fIto_type\fP;
+.br
+      XrmValuePtr \fIto_return\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget to use for additional arguments, if any are
+needed.
+.IP \fIfrom_type\fP 1i
+Specifies the source type.
+.IP \fIfrom\fP 1i
+Specifies the value to be converted.
+.IP \fIto_type\fP 1i
+Specifies the destination type.
+.IP \fIto_return\fP 1i
+Returns the converted value.
+.LP
+.IN "XtDirectConvert" "" "@DEF@"
+.FD 0
+void XtDirectConvert(\fIconverter\fP, \fIargs\fP, \fInum_args\fP, \fIfrom\fP, \
+\fIto_return\fP)
+.br
+      XtConverter \fIconverter\fP;
+.br
+      XrmValuePtr \fIargs\fP;
+.br
+      Cardinal \fInum_args\fP;
+.br
+      XrmValuePtr \fIfrom\fP;
+.br
+      XrmValuePtr \fIto_return\fP;
+.FN
+.IP \fIconverter\fP 1i
+Specifies the conversion procedure to be called.
+.IP \fIargs\fP 1i
+Specifies the argument list that contains the additional arguments
+needed to perform the conversion (often NULL).
+.IP \fInum_args\fP 1i
+Specifies the number of entries in \fIargs\fP.
+.IP \fIfrom\fP 1i
+Specifies the value to be converted.
+.IP \fIto_return\fP 1i
+Returns the converted value.
+.LP
+.eM
+The
+.PN XtConvert
+function looks up the type converter registered to convert \fIfrom_type\fP 
+to \fIto_type\fP, computes any additional arguments needed, and then calls
+.PN XtDirectConvert
+or
+.PN XtCallConverter .
+The
+.PN XtDirectConvert
+function looks in the converter cache to see if this conversion procedure
+has been called with the specified arguments.
+If so, it returns a descriptor for information stored in the cache;
+otherwise, it calls the converter and enters the result in the cache.
+.LP
+Before calling the specified converter,
+.PN XtDirectConvert
+sets the return value size to zero and the return value address to NULL.
+To determine if the conversion was successful,
+the client should check \fIto_return.addr\fP for non-NULL.
+The data returned by
+.PN XtConvert
+must be copied immediately by the caller,
+as it may point to static data in the type converter.
+.LP
+.PN XtConvert
+has been replaced by
+.PN XtConvertAndStore ,
+and
+.PN XtDirectConvert
+has been superseded by
+.PN XtCallConverter .
+.sp
+.LP
+To deallocate a shared GC when it is no longer needed, use
+.PN XtDestroyGC .
+.LP
+.IN "XtDestroyGC" "" "@DEF@"
+.sM
+.FD 0
+void XtDestroyGC(\fIw\fP, \fIgc\fP)
+.br
+      Widget \fIw\fP;
+.br
+      GC \fIgc\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies any object on the display for which the shared GC was
+created.  \*(oI
+.IP \fIgc\fP 1i
+Specifies the shared GC to be deallocated.
+.LP
+.eM
+References to sharable GCs are counted and a free request is generated to the
+server when the last user of a given GC destroys it.
+Note that some earlier versions of
+.PN XtDestroyGC
+had only a \fIgc\fP argument.
+Therefore, this function is not very portable,
+and you are encouraged to use
+.PN XtReleaseGC
+instead.
+.sp
+.LP
+To declare an action table in the default application context
+and register it with the translation manager, use
+.PN XtAddActions .
+.LP
+.IN "XtAddActions" "" "@DEF@"
+.sM
+.FD 0
+void XtAddActions(\fIactions\fP, \fInum_actions\fP)
+.br
+      XtActionList \fIactions\fP;
+.br
+      Cardinal \fInum_actions\fP;
+.FN
+.IP \fIactions\fP 1i
+Specifies the action table to register.
+.IP \fInum_actions\fP 1i
+Specifies the number of entries in \fIactions\fP.
+.LP
+.eM
+If more than one action is registered with the same name, 
+the most recently registered action is used.
+If duplicate actions exist in an action table,
+the first is used.
+The \*(xI register an action table for
+.PN XtMenuPopup
+and
+.PN XtMenuPopdown
+as part of \*(tk initialization.
+This routine has been replaced by
+.PN XtAppAddActions .
+.PN XtInitialize
+must be called before using this routine.
+.sp
+.LP
+To set the \*(xI selection timeout in the default application context, use
+.PN XtSetSelectionTimeout .
+.LP
+.IN "XtSetSelectionTimeout" "" "@DEF@"
+.sM
+.FD 0
+void XtSetSelectionTimeout(\fItimeout\fP)
+.br
+      unsigned long \fItimeout\fP;
+.FN
+.IP \fItimeout\fP 1i
+Specifies the selection timeout in milliseconds.
+This routine has been replaced by
+.PN XtAppSetSelectionTimeout .
+.PN XtInitialize
+must be called before using this routine.
+.LP
+.eM
+.sp
+.LP
+To get the current selection timeout value in the default application
+context, use
+.PN XtGetSelectionTimeout .
+.LP
+.IN "XtGetSelectionTimeout" "" "@DEF@"
+.sM
+.FD 0
+unsigned long XtGetSelectionTimeout()
+.FN
+.LP
+.eM
+The selection timeout is the time within which the two communicating 
+applications must respond to one another.
+If one of them does not respond within this interval,
+the \*(xI abort the selection request.
+.LP
+This routine has been replaced by
+.PN XtAppGetSelectionTimeout .
+.PN XtInitialize
+must be called before using this routine.
+.sp
+.LP
+To obtain the global error database (for example, to merge with
+an application- or widget-specific database), use
+.PN XtGetErrorDatabase .
+.LP
+.IN "XtGetErrorDatabase" "" "@DEF@"
+.sM
+.FD 0
+XrmDatabase *XtGetErrorDatabase()
+.FN
+.LP
+.eM
+The
+.PN XtGetErrorDatabase
+function returns the address of the error database.
+The \*(xI do a lazy binding of the error database and do not merge in the
+database file until the first call to
+.PN XtGetErrorDatbaseText .
+This routine has been replaced by
+.PN XtAppGetErrorDatabase .
+.sp
+.LP
+An error message handler can obtain the error database text for an
+error or a warning by calling
+.PN XtGetErrorDatabaseText .
+.LP
+.IN "XtGetErrorDatabaseText" "" "@DEF@"
+.sM
+.FD 0
+void XtGetErrorDatabaseText(\fIname\fP, \fItype\fP, \fIclass\fP, \
+\fIdefault\fP, \fIbuffer_return\fP, \fInbytes\fP)
+.br
+      String \fIname\fP, \fItype\fP, \fIclass\fP;
+.br
+      String \fIdefault\fP;
+.br
+      String \fIbuffer_return\fP;
+.br
+      int \fInbytes\fP;
+.FN
+.IP \fIname\fP 1i
+.br
+.ns
+.IP \fItype\fP 1i
+Specify the name and type that are concatenated to form the resource name 
+of the error message.
+.IP \fIclass\fP 1i
+Specifies the resource class of the error message.
+.IP \fIdefault\fP 1i
+Specifies the default message to use if an error database entry is not found.
+.IP \fIbuffer_return\fP 1i
+Specifies the buffer into which the error message is to be returned.
+.IP \fInbytes\fP 1i
+Specifies the size of the buffer in bytes.
+.LP
+.eM
+The
+.PN XtGetErrorDatabaseText
+returns the appropriate message from the error database
+associated with the default application context
+or returns the specified default message if one is not found in the
+error database.
+To form the full resource name and class when querying the database,
+the \fIname\fP and \fItype\fP are concatenated with a single ``.''
+between them and the \fIclass\fP is concatenated with itself with a
+single ``.'' if it does not already contain a ``.''.
+This routine has been superseded by
+.PN XtAppGetErrorDatabaseText .
+.sp
+.LP
+To register a procedure to be called on fatal error conditions, use
+.PN XtSetErrorMsgHandler .
+.LP
+.IN "XtSetErrorMsgHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtSetErrorMsgHandler(\fImsg_handler\fP)
+.br
+      XtErrorMsgHandler \fImsg_handler\fP;
+.FN
+.IP \fImsg_handler\fP 1i
+Specifies the new fatal error procedure, which should not return.
+.LP
+.eM
+The default error handler provided by the \*(xI constructs a
+string from the error resource database and calls
+.PN XtError .
+Fatal error message handlers should not return.
+If one does,
+subsequent \*(xI behavior is undefined.
+This routine has been superseded by
+.PN XtAppSetErrorMsgHandler .
+.sp
+.LP
+To call the high-level error handler, use
+.PN XtErrorMsg .
+.LP
+.IN "XtErrorMsg" "" "@DEF@"
+.sM
+.FD 0
+void XtErrorMsg(\fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \
+\fIparams\fP, \fInum_params\fP)
+.br
+      String \fIname\fP;
+.br
+      String \fItype\fP;
+.br
+      String \fIclass\fP;
+.br
+      String \fIdefault\fP;
+.br
+      String *\fIparams\fP;
+.br
+      Cardinal *\fInum_params\fP;
+.FN
+.IP \fIname\fP 1i
+Specifies the general kind of error.
+.IP \fItype\fP 1i
+Specifies the detailed name of the error.
+.IP \fIclass\fP 1i
+Specifies the resource class.
+.IP \fIdefault\fP 1i
+Specifies the default message to use if an error database entry is not found.
+.IP \fIparams\fP 1i
+Specifies a pointer to a list of values to be stored in the message.
+.IP \fInum_params\fP 1i
+Specifies the number of entries in \fIparams\fP.
+.LP
+.eM
+This routine has been superseded by
+.PN XtAppErrorMsg .
+.sp
+.LP
+To register a procedure to be called on nonfatal error conditions, use
+.PN XtSetWarningMsgHandler .
+.LP
+.IN "XtSetWarningMsgHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtSetWarningMsgHandler(\fImsg_handler\fP)
+.br
+      XtErrorMsgHandler \fImsg_handler\fP;
+.FN
+.IP \fImsg_handler\fP 1i
+Specifies the new nonfatal error procedure, which usually returns.
+.LP
+.eM
+The default warning handler provided by the \*(xI constructs a string
+from the error resource database and calls
+.PN XtWarning .
+This routine has been superseded by
+.PN XtAppSetWarningMsgHandler .
+.sp
+.LP
+To call the installed high-level warning handler, use
+.PN XtWarningMsg .
+.LP
+.IN "XtWarningMsg" "" "@DEF@"
+.sM
+.FD 0
+void XtWarningMsg(\fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \
+\fIparams\fP, \fInum_params\fP)
+.br
+      String \fIname\fP;
+.br
+      String \fItype\fP;
+.br
+      String \fIclass\fP;
+.br
+      String \fIdefault\fP;
+.br
+      String *\fIparams\fP;
+.br
+      Cardinal *\fInum_params\fP;
+.FN
+.IP \fIname\fP 1i
+Specifies the general kind of error.
+.IP \fItype\fP 1i
+Specifies the detailed name of the error.
+.IP \fIclass\fP 1i
+Specifies the resource class.
+.IP \fIdefault\fP 1i
+Specifies the default message to use if an error database entry is not found.
+.IP \fIparams\fP 1i
+Specifies a pointer to a list of values to be stored in the message.
+.IP \fInum_params\fP 1i
+Specifies the number of entries in \fIparams\fP.
+.LP
+.eM
+This routine has been superseded by
+.PN XtAppWarningMsg .
+.sp
+.LP
+To register a procedure to be called on fatal error conditions, use
+.PN XtSetErrorHandler .
+.LP
+.IN "XtSetErrorHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtSetErrorHandler(\fIhandler\fP)
+.br
+      XtErrorHandler \fIhandler\fP;
+.FN
+.IP \fIhandler\fP 1i
+Specifies the new fatal error procedure, which should not return.
+.LP
+.eM
+The default error handler provided by the \*(xI is
+.PN _XtError .
+On POSIX-based systems,
+it prints the message to standard error and terminates the application.
+Fatal error message handlers should not return.
+If one does,
+subsequent \*(tk behavior is undefined.
+This routine has been superseded by
+.PN XtAppSetErrorHandler .
+.sp
+.LP
+To call the installed fatal error procedure, use
+.PN XtError .
+.LP
+.IN "XtError" "" "@DEF@"
+.sM
+.FD 0
+void XtError(\fImessage\fP)
+.br
+      String \fImessage\fP;
+.FN
+.IP \fImessage\fP 1i
+Specifies the message to be reported.
+.LP
+.eM
+Most programs should use
+.PN XtAppErrorMsg ,
+not
+.PN XtError ,
+to provide for customization and internationalization of error
+messages.  This routine has been superseded by
+.PN XtAppError .
+.sp
+.LP
+To register a procedure to be called on nonfatal error conditions, use
+.PN XtSetWarningHandler .
+.LP
+.IN "XtSetWarningHandler" "" "@DEF@"
+.sM
+.FD 0
+void XtSetWarningHandler(\fIhandler\fP)
+.br
+      XtErrorHandler \fIhandler\fP;
+.FN
+.IP \fIhandler\fP 1i
+Specifies the new nonfatal error procedure, which usually returns.
+.LP
+.eM
+The default warning handler provided by the \*(xI is
+.PN _XtWarning .
+On POSIX-based systems,
+it prints the message to standard error and returns to the caller.
+This routine has been superseded by
+.PN XtAppSetWarningHandler .
+.sp
+.LP
+To call the installed nonfatal error procedure, use
+.PN XtWarning .
+.LP
+.IN "XtWarning" "" "@DEF@"
+.sM
+.FD 0
+void XtWarning(\fImessage\fP)
+.br
+      String \fImessage\fP;
+.FN
+.IP \fImessage\fP 1i
+Specifies the nonfatal error message to be reported.
+.LP
+.eM
+Most programs should use
+.PN XtAppWarningMsg ,
+not
+.PN XtWarning ,
+to provide for customization and internationalization of warning messages.
+This routine has been superseded by
+.PN XtAppWarning .