path: root/specs/appC

.\" $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 .