diff options
Diffstat (limited to 'specs/appC')
| -rw-r--r-- | specs/appC | 1204 |
1 files changed, 1204 insertions, 0 deletions
diff --git a/specs/appC b/specs/appC new file mode 100644 index 0000000..6f31fd7 --- /dev/null +++ b/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 . |