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

\s+1\fBConversion Notes\fP\s-1
.sp 2
.LP
.XS
Appendix C \- Conversion Notes
.XE
.LP
In the X Version 10 and alpha release X Version 11 \*(tk
each widget class
implemented an Xt<\^\fIWidget\fP\^>Create (for example,
.PN XtLabelCreate )
function, in which most of the code was identical from widget to widget.
In this \*(tk, a single generic
.PN XtCreateWidget
performs most of the common work and then calls the initialize procedure
implemented for the particular widget class.
.LP
Each composite widget class also implemented the procedures
Xt<\^\fIWidget\fP\^>Add and an Xt<\^\fIWidget\fP\^>Delete (for example,
.PN XtButtonBoxAddButton
and
.PN XtButtonBoxDeleteButton ).
In the beta release X Version 11 \*(tk, the composite generic procedures
.PN XtManageChildren
and
.PN XtUnmanageChildren
perform error-checking and screening out of certain children.
Then, they call the change_managed procedure
implemented for the widget's composite class.
If the widget's parent has not yet been realized,
the call on the change_managed procedure is delayed until realization time.
.LP
Old style calls can be implemented in the \*(tk by defining
one-line procedures or macros that invoke a generic routine.  For example,
you could define the macro
.PN XtCreateLabel
as:
.IP
.Ds 0
.TA .5i 3i
.ta .5i 3i
#define XtCreateLabel(\fIname\fP, \fIparent\fP, \fIargs\fP, \fInum_args\fP) \\
        ((LabelWidget) XtCreateWidget(\fIname\fP, \fIlabelWidgetClass\fP,   \
\fIparent\fP, \fIargs\fP, \fInum_args\fP))
.De
.sp
.LP
Pop-up shells no longer automatically perform an
.PN XtManageChild
on their child within their insert_child procedure.
.IN "insert_child procedure"
Creators of pop-up children need to call
.PN XtManageChild
themselves.
.sp
.LP
As a convenience to people converting from earlier versions of the toolkit
and for greater orthogonality,
the following routines exist:
.PN XtInitialize ,
.PN XtMainLoop ,
.PN XtNextEvent ,
.PN XtProcessEvent ,
.PN XtPeekEvent ,
.PN XtPending ,
.PN XtAddInput ,
.PN XtAddTimeOut ,
.PN XtAddWorkProc ,
and
.PN XtCreateApplicationShell .
.sp
.IN "XtInitialize" "" "@DEF@"
.FD 0
Widget XtInitialize(\fIshell_name\fP, \fIapplication_class\fP, \fIoptions\fP, \
\fInum_options\fP, \fIargc\fP, \fIargv\fP)
.br
      String \fIshell_name\fP;
.br
      String \fIapplication_class\fP;
.br
      XrmOptionDescRec \fIoptions\fP[];
.br
      Cardinal \fInum_options\fP;
.br
      Cardinal *\fIargc\fP;
.br
      String \fIargv\fP[];
.FN
.IP \fIshell_name\fP 1i
This parameter is ignored; therefore, you can specify NULL.
.IP \fIapplication_class\fP 1i
Specifies the class name of this application.
.IP \fIoptions\fP 1i
Specifies how to parse the command line for any application-specific resources.
The options argument is passed as a parameter to 
.PN XrmParseCommand .
For further information,
see \fI\*(xL\fP.
.IP \fInum_options\fP 1i
Specifies the number of entries in options list.
.IP \fIargc\fP 1i
Specifies a pointer to the number of command line parameters.
.IP \fIargv\fP 1i
Specifies the command line parameters.
.LP
.PN XtInitialize
calls
.PN XtToolkitInitialize
to initialize the toolkit internals,
creates a default application context for use by the other convenience
routines, then calls
.PN XtOpenDisplay
with a display_string of NULL and an application_name of NULL, and
finally calls
.PN XtAppCreateShell
with an application_name of NULL and
returns the created shell.
The semantics of calling
.PN XtInitialize
more than once are undefined.
See
.PN XtCreateApplicationContext ,
.PN XtDisplayInitialize ,
and
.PN XtAppCreateShell
for more information.
.sp
.IN "XtMainLoop" "" "@DEF@"
.FD 0
void XtMainLoop()
.FN
.PN XtMainLoop
first reads the next incoming file, timer, or X event by calling
.PN XtNextEvent .
Then, it dispatches this to the appropriate registered procedure by calling
.PN XtDispatchEvent .
This can be used as the main loop of \*(tk applications, 
and, as such, it does not return.
Applications are expected to exit in response to some user action.
This routine has been replaced by
.PN XtAppMainLoop .
.LP
There is nothing special about
.PN XtMainLoop .
It is simply an infinite loop that calls
.br
.PN XtNextEvent
then
.PN XtDispatchEvent .
.sp
.IN "XtNextEvent" "" "@DEF@"
.FD 0
void XtNextEvent(\fIevent_return\fP)
.br
      XEvent *\fIevent_return\fP;
.FN
.IP \fIevent_return\fP 1i
Returns the event information to the specified event structure.
.LP
If no input is on the X input queue for the default application context, 
.PN XtNextEvent 
flushes the X output buffer 
and waits for an event while looking at the other input sources 
and timeout values and calling any callback procedures triggered by them.
This routine has been replaced by
.PN XtAppNextEvent .
.PN XtInitialize
must be called before using this routine.
.sp
.IN "XtProcessEvent" "" "@DEF@"
.FD 0
void XtProcessEvent(\fImask\fP)
.br
       XtInputMask \fImask\fP;
.FN
.IP \fImask\fP 1i
Specifies the type of input to process.
.LP
.PN XtProcessEvent
processes one input event, timeout, or alternate input source 
(depending on the value of mask), waiting if necessary.
It has been replaced by
.PN XtAppProcessEvent .
.PN XtInitialize
must be called before using this function.
.sp
.IN "XtPeekEvent" "" "@DEF@"
.FD 0
Boolean XtPeekEvent(\fIevent_return\fP)
.br
      XEvent *\fIevent_return\fP;
.FN
.IP \fIevent_return\fP 1i
Returns the event information to the specified event structure.
.LP
If there is an event in the queue for the default application context, 
.PN XtPeekEvent
fills in the event and returns a non-zero value.
If no X input is on the queue, 
.PN XtPeekEvent
flushes the output buffer and blocks until input is available, possibly
calling some timeout callbacks in the process.
If the input is an event,
.PN XtPeekEvent
fills in the event and returns a non-zero value. 
Otherwise, the input is for an alternate input source, and
.PN XtPeekEvent
returns zero. 
This routine has been replaced by
.PN XtAppPeekEvent .
.PN XtInitialize
must be called before using this routine.
.sp
.IN "XtPending" "" "@DEF@"
.FD 0
Boolean XtPending()
.FN
The 
.PN XtPending
returns a nonzero value if there are 
events pending from the X server or other input sources in the default
application context.
If there are no events pending, 
it flushes the output buffer and returns a zero value.
It has been replaced by
.PN XtAppPending .
.PN XtInitialize
must be called before using this routine.
.sp
.IN "XtAddInput" "" "@DEF@"
.FD 0
XtInputId XtAddInput(\fIsource\fP, \fIcondition\fP, \fIproc\fP, \
\fIclient_data\fP)
.br
      int \fIsource\fP;
.br
      caddr_t \fIcondition\fP;
.br
      XtInputCallbackProc \fIproc\fP;
.br
      caddr_t \fIclient_data\fP;
.FN
.IP \fIsource\fP 1i
Specifies the source file descriptor on a UNIX-based system 
or other operating system dependent device specification.
.IP \fIcondition\fP 1i
Specifies the mask that indicates either a read, write, or exception condition
or some operating system dependent condition.
.IP \fIproc\fP 1i
Specifies the procedure that is called when input is available.
.IP \fIclient_data\fP 1i
Specifies the parameter to be passed to proc when input is available.
.LP
The 
.PN XtAddInput
function registers with the \*(tk default application context a new 
source of events, 
which is usually file input but can also be file output.
(The word ``file'' should be loosely interpreted to mean any sink 
or source of data.)
.PN XtAddInput
also specifies the conditions under which the source can generate events.
When input is pending on this source in the default application context, 
the callback procedure is called.
This routine has been replaced by
.PN XtAppAddInput .
.PN XtInitialize
must be called before using this routine.
.sp
.IN "XtAddTimeOut" "" "@DEF@"
.FD 0
XtIntervalId XtAddTimeOut(\fIinterval\fP, \fIproc\fP, \fIclient_data\fP)
.br
      unsigned long \fIinterval\fP;
.br
      XtTimerCallbackProc \fIproc\fP;
.br
      caddr_t \fIclient_data\fP;
.FN
.IP \fIinterval\fP 1i
Specifies the time interval in milliseconds.
.IP \fIproc\fP 1i
Specifies the procedure to be called when time expires.
.IP \fIclient_data\fP 1i
Specifies the parameter to be passed to proc when it is called.
.LP
The 
.PN XtAddTimeOut
function creates a timeout in the default application context
and returns an identifier for it.
The timeout value is set to interval.
The callback procedure will be called after
the time interval elapses, after which the timeout is removed.
This routine has been replaced by 
.PN XtAppAddTimeOut .
.PN XtInitialize
must be called before using this routine.
.sp
.IN "XtAddWorkProc" "" "@DEF@"
.FD 0
XtWorkProcId XtAddWorkProc(\fIproc\fP, \fIclosure\fP)
.br
      XtWorkProc \fIproc\fP;
.br
      Opaque \fIclosure\fP;
.FN
.IP \fIproc\fP 1i
Procedure to call to do the work.
.IP \fIclosure\fP 1i
Client data to pass to proc when it is called.
.LP
This routine registers a work proc in the default application context. It has
been replaced by
.PN XtAppAddWorkProc .
.PN XtInitialize
must be called before using this routine.
.sp
.IN "XtCreateApplicationShell" "" "@DEF@"
.FD 0
Widget XtCreateApplicationShell(\fIname\fP, \fIwidget_class\fP, \fIargs\fP, \
\fInum_args\fP)
.br
      String \fIname\fP;
.br
      WidgetClass \fIwidget_class\fP;
.br
      ArgList \fIargs\fP;
.br
      Cardinal \fInum_args\fP;
.FN
.IP \fIname\fP 1i
This parameter is ignored; therefore, you can specify NULL.
.IP \fIwidget_class\fP 1i
Specifies the widget class pointer for the created application shell widget.
This will usually be 
.PN topLevelShellWidgetClass 
or a subclass thereof.
.IP \fIargs\fP 1i
Specifies the argument list to override the resource defaults.
.IP \fInum_args\fP 1i
Specifies the number of arguments in args.
.LP
.PN XtCreateApplicationShell
calls
.PN XtAppCreateShell
with an application_name of NULL, the application_class passed to
.PN XtInitialize
and the default application context created by
.PN XtInitialize .
This routine has been replaced by
.PN XtAppCreateShell .
.sp
.LP
To register a new converter, use the procedure
.PN XtAddConverter .
.IN "XtAddConverter" "" "@DEF@"
.FD 0
void XtAddConverter(\fIfrom_type\fP, \fIto_type\fP, \fIconverter\fP, \
\fIconvert_args\fP, \fInum_args\fP)
.br
    String \fIfrom_type\fP;
.br
    String \fIto_type\fP;
.br
    XtConverter \fIconverter\fP;
.br
    XtConvertArgList \fIconvert_args\fP;
.br
    Cardinal \fInum_args\fP;
.FN
.IP \fIfrom_type\fP 1i
Specifies the source type.
.IP \fIto_type\fP 1i
Specifies the destination type.
.IP \fIconverter\fP 1i
Specifies the type converter procedure.
.IP \fIconvert_args\fP 1i
Specifies how to compute the additional arguments to the converter or NULL.
.IP \fInum_args\fP 1i
Specifies the number of additional arguments to the converter or zero.
.LP
For the few type converters that need additional arguments,
the \*(xI conversion mechanism provides a method of specifying
how these arguments should be computed.
The enumerated type
.PN XtAddressMode
and the structure
.PN XtConvertArgRec
specify how each argument is derived.
These are defined in
.Pn < X11/Convert.h >.
.LP
.Ds
.TA .5i 2.5i
.ta .5i 2.5i
typedef enum {
	/* address mode parameter representation */
	   XtAddress,	/* address */
	   XtBaseOffset,	/* offset */
	   XtImmediate,	/* constant */
	   XtResourceString,	/* resource name string */
	   XtResourceQuark	/* resource name quark */
} XtAddressMode;

typedef struct {
	XtAddressMode address_mode;
	caddr_t address_id;
	Cardinal size;
} XtConvertArgRec, *XtConvertArgList;
.De
.LP
The address_mode field specifies how the address_id field should be
interpreted.
.PN XtAddress
causes address_id to be interpreted as the address of the data.
.PN XtBaseOffset
causes address_id to be interpreted as the offset from the widget base.
.PN XtImmediate
causes address_id to be interpreted as a constant.
.PN XtResourceString
causes address_id to be interpreted as the name of a resource
that is to be converted into an offset from widget base.
.PN XtResourceQuark
is an internal compiled form of an
.PN XtResourceString .
The size field specifies the length of the data in bytes.
.LP
The following provides the code that was used to register the CvtStringToPixel 
routine shown earlier:
.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
static XtConvertArgRec colorConvertArgs[] = {
	{XtBaseOffset, (caddr_t) XtOffset(Widget, core.screen),  sizeof(Screen *)},
	{XtBaseOffset, (caddr_t) XtOffset(Widget, core.colormap),sizeof(Colormap)}
};

XtAddConverter(XtRString, XtRPixel, CvtStringToPixel,
    colorConvertArgs, XtNumber(colorConvertArgs));
.De
.LP
The conversion argument descriptors colorConvertArgs and screenConvertArg are
predefined.
The screenConvertArg descriptor puts the widget's screen field into args[0].
The colorConvertArgs descriptor puts the widget's screen field into args[0],
and the widget's colormap field into args[1].
.LP
Conversion routines should not just put a descriptor for the address of the
base of the widget into args[0], and use that in the routine.
They should pass in the actual values that the conversion depends on.
By keeping the dependencies of the conversion procedure specific,
it is more likely that subsequent conversions will find what they need
in the conversion cache.
This way the cache is smaller and has fewer and more widely applicable entries.
.sp
.LP
To deallocate a shared GC when it is no longer needed, use
.PN XtDestroyGC .
.IN "XtDestroyGC" "" "@DEF@"
.FD 0
void XtDestroyGC(\fIw\fP, \fIgc\fP)
.br
      Widget \fIw\fP;
.br
      GC \fIgc\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget.
.IP \fIgc\fP 1i
Specifies the GC to be deallocated.
.LP
References to sharable GCs are counted and a free request is generated to the
server when the last user of a given GC destroys it.
Note that some earlier versions of
.PN XtDestroyGC
had only a gc argument.
Therefore, this function is not very portable,
and you are encouraged to use
.PN XtReleaseGC
instead.
.sp
.LP
To declare an action table and register it with the translation manager, use
.PN XtAddActions .
.IN "XtAddActions" "" "@DEF@"
.FD 0
void XtAddActions(\fIactions\fP, \fInum_actions\fP)
.br
      XtActionList \fIactions\fP;
.br
      Cardinal \fInum_actions\fP;
.FN
.IP \fIactions\fP 1i
Specifies the action table to register.
.IP \fInum_args\fP 1i
Specifies the number of entries in this action table.
.LP
If more than one action is registered with the same name, 
the most recently registered action is used.
If duplicate actions exist in an action table,
the first is used.
The \*(xI register an action table for
.PN MenuPopup
and
.PN MenuPopdown
as part of \*(tk initialization.
.sp
.LP
To set the \*(xI selection timeout, use
.PN XtSetSelectionTimeout .
.IN "XtSetSelectionTimeout" "" "@DEF@"
.FD 0
void XtSetSelectionTimeout(\fItimeout\fP)
.br
    unsigned long \fItimeout\fP;
.FN
.IP \fItimeout\fP 1i
Specifies the selection timeout in milliseconds.
.sp
.LP
To get the current selection timeout value, use
.PN XtGetSelectionTimeout .
.IN "XtGetSelectionTimeout" "" "@DEF@"
.FD 0
unsigned long XtGetSelectionTimeout()
.FN
.LP
The selection timeout is the time within which the two communicating 
applications must respond to one another.
If one of them does not respond within this interval,
the \*(xI aborts the selection request.
The default value of the selection timeout is five seconds.
.sp
.LP
To obtain the error database (for example, to merge with
an application or widget specific database), use
.PN XtGetErrorDatabase .
.IN "XtGetErrorDatabase" "" "@DEF@"
.FD 0
XrmDatabase *XtGetErrorDatabase()
.FN
.LP
The
.PN XtGetErrorDatabase
function returns tha address of the error database.
The \*(xI do a lazy binding of the error database and do not merge in the
database file until the first call to
.PN XtGetErrorDatbaseText .
.LP
For a complete listing of all errors and warnings 
that can be generated by the \*(xI, see Appendix D.
.sp
.LP
An error message handler can obtain the error database text for an
error or a warning by calling
.PN XtGetErrorDatabaseText .
.IN "XtGetErrorDatabaseText" "" "@DEF@"
.FD 0
void XtGetErrorDatabaseText(\fIname\fP, \fItype\fP, \fIclass\fP, \
\fIdefault\fP, \fIbuffer_return\fP, \fInbytes\fP)
.br
       char *\fIname\fP, *\fItype\fP, *\fIclass\fP;
.br
       char *\fIdefault\fP;
.br
       char *\fIbuffer_return\fP;
.br
       int \fInbytes\fP;
.FN
.IP \fIname\fP 1i
.br
.ns
.IP \fItype\fP 1i
Specifies the name and type that are concatenated to form the resource name 
of the error message.
.ds Cl \ of the error message
.IP \fIclass\fP 1i
Specifies the resource class\*(Cl.
.ds Dm \ if an error database entry is not found
.IP \fIdefault\fP 1i
Specifies the default message to use\*(Dm.
.IP \fIbuffer_return\fP 1i
Specifies the buffer into which the error message is to be returned.
.IP \fInbytes\fP 1i
Specifies the size of the buffer in bytes.
.LP
The
.PN XtGetErrorDatabaseText
returns the appropriate message from the error database
or returns the specified default message if one is not found in the
error database.
.sp
.LP
To register a procedure to be called on fatal error conditions, use
.PN XtSetErrorMsgHandler .
.IN "XtSetErrorMsgHandler" "" "@DEF@"
.FD 0
void XtSetErrorMsgHandler(\fImsg_handler\fP)
.br
      XtErrorMsgHandler \fImsg_handler\fP;
.FN
.ds Mh fatal error procedure, which should not return
.IP \fImsg_handler\fP 1i
Specifies the new \*(Mh.
.LP
The default error handler provided by the \*(xI constructs a
string from the error resource database and calls
.PN XtError .
Fatal error message handlers should not return.
If one does,
subsequent \*(tk behavior is undefined.
.sp
.LP
To call the high-level error handler, use
.PN XtErrorMsg .
.IN "XtErrorMsg" "" "@DEF@"
.FD 0
void XtErrorMsg(\fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \
\fIparams\fP, \fInum_params\fP)
.br
    String \fIname\fP;
.br
    String \fItype\fP;
.br
    String \fIclass\fP;
.br
    String \fIdefault\fP;
.br
    String *\fIparams\fP;
.br
    Cardinal *\fInum_params\fP;
.FN
.IP \fIname\fP 1i
Specifies the general kind of error.
.IP \fItype\fP 1i
Specifies the detailed name of the error.
.ds Cl
.IP \fIclass\fP 1i
Specifies the resource class\*(Cl.
.IP \fIdefault\fP 1i
Specifies the default message to use\*(Dm.
.IP \fIparams\fP 1i
Specifies a pointer to a list of values to be stored in the message.
.IP \fInum_params\fP 1i
Specifies the number of values in the parameter list.
.LP
The \*(xI internal errors all have class
.PN XtToolkitError .
.sp
.LP
To register a procedure to be called on nonfatal error conditions, use
.PN XtSetWarningMsgHandler .
.IN "XtSetWarningMsgHandler" "" "@DEF@"
.FD 0
void XtSetWarningMsgHandler(\fImsg_handler\fP)
.br
      XtErrorMsgHandler \fImsg_handler\fP;
.FN
.ds Mh nonfatal error procedure, which usually returns
.IP \fImsg_handler\fP 1i
Specifies the new \*(Mh.
.LP
The default warning handler provided by the \*(xI constructs a string
from the error resource database and calls
.PN XtWarning .
.sp
.LP
To call the installed high-level warning handler, use
.PN XtWarningMsg .
.IN "XtWarningMsg" "" "@DEF@"
.FD 0
void XtWarningMsg(\fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \
\fIparams\fP, \fInum_params\fP)
.br
    String \fIname\fP;
.br
    String \fItype\fP;
.br
    String \fIclass\fP;
.br
    String \fIdefault\fP;
.br
    String *\fIparams\fP;
.br
    Cardinal *\fInum_params\fP;
.FN
.IP \fIname\fP 1i
Specifies the general kind of error.
.IP \fItype\fP 1i
Specifies the detailed name of the error.
.cd Cl
.IP \fIclass\fP 1i
Specifies the resource class\*(Cl.
.IP \fIdefault\fP 1i
Specifies the default message to use\*(Dm.
.IP \fIparams\fP 1i
Specifies a pointer to a list of values to be stored in the message.
.IP \fInum_params\fP 1i
Specifies the number of values in the parameter list.
.LP
The \*(xI internal warninings all have class
.PN XtToolkitError .
.sp
.LP
To register a procedure to be called on fatal error conditions, use
.PN XtSetErrorHandler .
.IN "XtSetErrorHandler" "" "@DEF@"
.FD 0
void XtSetErrorHandler(\fIhandler\fP)
.br
      XtErrorHandler \fIhandler\fP;
.FN
.ds Ha fatal error procedure, which should not return
.IP \fIhandler\fP 1i
Specifies the new \*(Ha.
.LP
The default error handler provided by the \*(xI is
.PN _XtError .
On UNIX-based systems,
it prints the message to standard error and terminates the application.
Fatal error message handlers should not return.
If one does,
subsequent \*(tk behavior is undefined.
.sp
.LP
To call the installed fatal error procedure, use
.PN XtError .
.IN "XtError" "" "@DEF@"
.FD 0
void XtError(\fImessage\fP)
.br
      String \fImessage\fP;
.FN
.ds Me reported
.IP \fImessage\fP 1i
Specifies the message that is to be \*(Me.
.LP
Most programs should use
.PN XtErrorMsg ,
not
.PN XtError ,
to provide for customization and internationalization of error messages.
.sp
.LP
To register a procedure to be called on nonfatal error conditions, use
.PN XtSetWarningHandler .
.IN "XtSetWarningHandler" "" "@DEF@"
.FD 0
void XtSetWarningHandler(\fIhandler\fP)
.br
      XtErrorHandler \fIhandler\fP;
.FN
.ds Ha nonfatal error procedure, which usually returns
.IP \fIhandler\fP 1i
Specifies the new \*(Ha.
.LP
The default warning handler provided by the \*(xI is
.PN _XtWarning .
On UNIX-based systems,
it prints the message to standard error and returns to the caller.
.sp
.LP
To call the installed nonfatal error procedure, use
.PN XtWarning .
.IN "XtWarning" "" "@DEF@"
.FD 0
void XtWarning(\fImessage\fP)
.br
      String \fImessage\fP;
.FN
.IP \fImessage\fP 1i
Specifies the nonfatal error message that is to be reported.
.LP
Most programs should use
.PN XtWarningMsg ,
not
.PN XtWarning ,
to provide for customization and internationalization of warning messages.
