.bp
\&
.sp 1
.ce 3
\s+1\fBAppendix C\fP\s-1

\s+1\fBConversion Notes\fP\s-1
.sp 2
.LP
.XS
Appendix C \- Conversion Notes
.XE
.LP
In the X Version 10 and alpha release X Version 11 \*(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 this \*(tk, 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 widget class also implemented the procedures
Xt<\^\fIWidget\fP\^>Add and an Xt<\^\fIWidget\fP\^>Delete (for example,
.PN XtButtonBoxAddButton
and
.PN XtButtonBoxDeleteButton ).
In the beta release X Version 11 \*(tk, 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 on 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 XtCreateLabel
as:
.IP
.Ds 0
.TA .5i 3i
.ta .5i 3i
#define XtCreateLabel(\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 no longer automatically perform 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
As a convenience to people converting from earlier versions of the toolkit
and for greater orthogonality,
the following routines exist:
.PN XtInitialize ,
.PN XtMainLoop ,
.PN XtNextEvent ,
.PN XtProcessEvent ,
.PN XtPeekEvent ,
.PN XtPending ,
.PN XtAddInput ,
.PN XtAddTimeOut ,
.PN XtAddWorkProc ,
and
.PN XtCreateApplicationShell .
.sp
.IN "XtInitialize" "" "@DEF@"
.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
      Cardinal *\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 options argument is passed as a parameter to 
.PN XrmParseCommand .
For further information,
see \fI\*(xL\fP.
.IP \fInum_options\fP 1i
Specifies the number of entries in 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
.PN XtInitialize
calls
.PN XtToolkitInitialize
to initialize the toolkit internals,
creates a default application context for use by the other convenience
routines, then calls
.PN XtOpenDisplay
with a display_string of NULL and an application_name of NULL, and
finally calls
.PN XtAppCreateShell
with an application_name of NULL and
returns the created shell.
The semantics of calling
.PN XtInitialize
more than once are undefined.
See
.PN XtCreateApplicationContext ,
.PN XtDisplayInitialize ,
and
.PN XtAppCreateShell
for more information.
.sp
.IN "XtMainLoop" "" "@DEF@"
.FD 0
void XtMainLoop()
.FN
.PN XtMainLoop
first reads the next incoming file, timer, or X event by calling
.PN XtNextEvent .
Then, it dispatches this to the appropriate registered procedure by calling
.PN XtDispatchEvent .
This can be used as the main loop of \*(tk applications, 
and, as such, it does not return.
Applications are expected to exit in response to some user action.
This routine has been replaced by
.PN XtAppMainLoop .
.LP
There is nothing special about
.PN XtMainLoop .
It is simply an infinite loop that calls
.br
.PN XtNextEvent
then
.PN XtDispatchEvent .
.sp
.IN "XtNextEvent" "" "@DEF@"
.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
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 other 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@"
.FD 0
void XtProcessEvent(\fImask\fP)
.br
       XtInputMask \fImask\fP;
.FN
.IP \fImask\fP 1i
Specifies the type of input to process.
.LP
.PN XtProcessEvent
processes one input event, timeout, or alternate input source 
(depending on the value of mask), waiting if necessary.
It has been replaced by
.PN XtAppProcessEvent .
.PN XtInitialize
must be called before using this function.
.sp
.IN "XtPeekEvent" "" "@DEF@"
.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
If there is an event in the queue for the default application context, 
.PN XtPeekEvent
fills in the event and returns a non-zero 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 non-zero 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@"
.FD 0
Boolean XtPending()
.FN
The 
.PN XtPending
returns a nonzero value if there are 
events pending from the X server or other 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@"
.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 that is called when input is available.
.IP \fIclient_data\fP 1i
Specifies the parameter to be passed to proc when input is available.
.LP
The 
.PN XtAddInput
function registers with the \*(tk default application context a new 
source of events, 
which is usually file input but can also be file output.
(The word ``file'' 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@"
.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 proc when it is called.
.LP
The 
.PN XtAddTimeOut
function creates a timeout in the default application context
and returns an identifier for it.
The timeout value is set to interval.
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@"
.FD 0
XtWorkProcId XtAddWorkProc(\fIproc\fP, \fIclosure\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 proc when it is called.
.LP
This routine registers a work proc 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@"
.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 the resource defaults.
.IP \fInum_args\fP 1i
Specifies the number of arguments in args.
.LP
.PN XtCreateApplicationShell
calls
.PN XtAppCreateShell
with an application_name of 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 converter procedure pointer is of type
.PN XtConverter :
.IN "XtConverter" "" "@DEF@"
.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.
For example, the string-to-font converter needs the widget's screen,
or the string to pixel converter needs the widget's screen and color map.
.IP \fInum_args\fP 1i
Specifies the number of additional 
.PN XrmValue 
arguments or zero.
.IP \fIfrom\fP 1i
Specifies the value to convert.
.IP \fIto\fP 1i
Specifies the descriptor to use to return the converted value.
.LP
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 to parameter;
otherwise, call
.PN XtWarningMsg
and return without modifying the to argument.
.LP
Most type converters just take the data described by the specified from
argument and return data by writing into the specified to 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 written to->addr 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.

.sp
.LP
The
.PN XtStringConversionWarning
.IN "XtStringConversionWarning" "" "@DEF@"
function is a convenience routine for old-format resource converters
that convert from strings.
.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
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''.

.sp
.LP
To register an old-format converter, use
.PN XtAddConverter
.IN "XtAddConverter" "" "@DEF@"
or
.PN XtAppAddConverter .
.IN "XtAppAddConverter" "" "@DEF@"
.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 additional arguments to the converter or zero.
.sp
.LP
.PN XtAddConverter
is equivalent in function to XtSetTypeConverter with cache_type equal to
.PN XtCacheAll .

.sp
.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 additional arguments to the converter or zero.
.LP
.PN XtAppAddConverter
is equivalent in function to XtAppSetTypeConverter with cache_type equal to
.PN XtCacheAll .

.sp
.LP
To invoke resource conversions, a client may use
.PN XtConvert
or, for old-format converters only,
.PN XtDirectConvert .
.LP
.sp
.IN "XtConvert" "" "@DEF@"
.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
.ds Wi to use for additional arguments (if any are needed)
.IP \fIw\fP 1i
Specifies the widget \*(Wi.
.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 that is to be called.
.ds Al that contains the additional arguments needed to perform \
the conversion (often NULL)
.IP \fIargs\fP 1i
Specifies the argument list \*(Al.
.IP \fInum_args\fP 1i
Specifies the number of additional arguments (often zero).
.IP \fIfrom\fP 1i
Specifies the value to be converted.
.IP \fIto_return\fP 1i
Returns the converted value.
.LP
The
.PN XtConvert
function looks up the type converter registered to convert from_type 
to to_type, 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 to_return.address for non-NULL.
The data returned by XtConvert must be copied immediately by the caller,
as it may point to static data in the type converter.

.sp
.LP
To deallocate a shared GC when it is no longer needed, use
.PN XtDestroyGC .
.IN "XtDestroyGC" "" "@DEF@"
.FD 0
void XtDestroyGC(\fIw\fP, \fIgc\fP)
.br
      Widget \fIw\fP;
.br
      GC \fIgc\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget.
.IP \fIgc\fP 1i
Specifies the GC to be deallocated.
.LP
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 gc argument.
Therefore, this function is not very portable,
and you are encouraged to use
.PN XtReleaseGC
instead.
.sp
.LP
To declare an action table and register it with the translation manager, use
.PN XtAddActions .
.IN "XtAddActions" "" "@DEF@"
.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_args\fP 1i
Specifies the number of entries in this action table.
.LP
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 MenuPopup
and
.PN MenuPopdown
as part of \*(tk initialization.
.sp
.LP
To set the \*(xI selection timeout, use
.PN XtSetSelectionTimeout .
.IN "XtSetSelectionTimeout" "" "@DEF@"
.FD 0
void XtSetSelectionTimeout(\fItimeout\fP)
.br
    unsigned long \fItimeout\fP;
.FN
.IP \fItimeout\fP 1i
Specifies the selection timeout in milliseconds.
.sp
.LP
To get the current selection timeout value, use
.PN XtGetSelectionTimeout .
.IN "XtGetSelectionTimeout" "" "@DEF@"
.FD 0
unsigned long XtGetSelectionTimeout()
.FN
.LP
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 aborts the selection request.
The default value of the selection timeout is five seconds.
.sp
.LP
To obtain the error database (for example, to merge with
an application or widget specific database), use
.PN XtGetErrorDatabase .
.IN "XtGetErrorDatabase" "" "@DEF@"
.FD 0
XrmDatabase *XtGetErrorDatabase()
.FN
.LP
The
.PN XtGetErrorDatabase
function returns tha 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 .
.LP
For a complete listing of all errors and warnings 
that can be generated by the \*(xI, see Appendix D.
.sp
.LP
An error message handler can obtain the error database text for an
error or a warning by calling
.PN XtGetErrorDatabaseText .
.IN "XtGetErrorDatabaseText" "" "@DEF@"
.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
Specifies the name and type that are concatenated to form the resource name 
of the error message.
.ds Cl \ of the error message
.IP \fIclass\fP 1i
Specifies the resource class\*(Cl.
.ds Dm \ if an error database entry is not found
.IP \fIdefault\fP 1i
Specifies the default message to use\*(Dm.
.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
The
.PN XtGetErrorDatabaseText
returns the appropriate message from the error database
or returns the specified default message if one is not found in the
error database.
.sp
.LP
To register a procedure to be called on fatal error conditions, use
.PN XtSetErrorMsgHandler .
.IN "XtSetErrorMsgHandler" "" "@DEF@"
.FD 0
void XtSetErrorMsgHandler(\fImsg_handler\fP)
.br
      XtErrorMsgHandler \fImsg_handler\fP;
.FN
.ds Mh fatal error procedure, which should not return
.IP \fImsg_handler\fP 1i
Specifies the new \*(Mh.
.LP
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 \*(tk behavior is undefined.
.sp
.LP
To call the high-level error handler, use
.PN XtErrorMsg .
.IN "XtErrorMsg" "" "@DEF@"
.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.
.ds Cl
.IP \fIclass\fP 1i
Specifies the resource class\*(Cl.
.IP \fIdefault\fP 1i
Specifies the default message to use\*(Dm.
.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 values in the parameter list.
.LP
The \*(xI internal errors all have class
.PN XtToolkitError .
.sp
.LP
To register a procedure to be called on nonfatal error conditions, use
.PN XtSetWarningMsgHandler .
.IN "XtSetWarningMsgHandler" "" "@DEF@"
.FD 0
void XtSetWarningMsgHandler(\fImsg_handler\fP)
.br
      XtErrorMsgHandler \fImsg_handler\fP;
.FN
.ds Mh nonfatal error procedure, which usually returns
.IP \fImsg_handler\fP 1i
Specifies the new \*(Mh.
.LP
The default warning handler provided by the \*(xI constructs a string
from the error resource database and calls
.PN XtWarning .
.sp
.LP
To call the installed high-level warning handler, use
.PN XtWarningMsg .
.IN "XtWarningMsg" "" "@DEF@"
.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.
.cd Cl
.IP \fIclass\fP 1i
Specifies the resource class\*(Cl.
.IP \fIdefault\fP 1i
Specifies the default message to use\*(Dm.
.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 values in the parameter list.
.LP
The \*(xI internal warninings all have class
.PN XtToolkitError .
.sp
.LP
To register a procedure to be called on fatal error conditions, use
.PN XtSetErrorHandler .
.IN "XtSetErrorHandler" "" "@DEF@"
.FD 0
void XtSetErrorHandler(\fIhandler\fP)
.br
      XtErrorHandler \fIhandler\fP;
.FN
.ds Ha fatal error procedure, which should not return
.IP \fIhandler\fP 1i
Specifies the new \*(Ha.
.LP
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.
.sp
.LP
To call the installed fatal error procedure, use
.PN XtError .
.IN "XtError" "" "@DEF@"
.FD 0
void XtError(\fImessage\fP)
.br
      String \fImessage\fP;
.FN
.ds Me reported
.IP \fImessage\fP 1i
Specifies the message that is to be \*(Me.
.LP
Most programs should use
.PN XtErrorMsg ,
not
.PN XtError ,
to provide for customization and internationalization of error messages.
.sp
.LP
To register a procedure to be called on nonfatal error conditions, use
.PN XtSetWarningHandler .
.IN "XtSetWarningHandler" "" "@DEF@"
.FD 0
void XtSetWarningHandler(\fIhandler\fP)
.br
      XtErrorHandler \fIhandler\fP;
.FN
.ds Ha nonfatal error procedure, which usually returns
.IP \fIhandler\fP 1i
Specifies the new \*(Ha.
.LP
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.
.sp
.LP
To call the installed nonfatal error procedure, use
.PN XtWarning .
.IN "XtWarning" "" "@DEF@"
.FD 0
void XtWarning(\fImessage\fP)
.br
      String \fImessage\fP;
.FN
.IP \fImessage\fP 1i
Specifies the nonfatal error message that is to be reported.
.LP
Most programs should use
.PN XtWarningMsg ,
not
.PN XtWarning ,
to provide for customization and internationalization of warning messages.
