1205 lines
32 KiB
Plaintext
1205 lines
32 KiB
Plaintext
.\" $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 .
|