<!-- =defdoc xpaconvert xpaconvert n -->
<HTML>
<HEAD>
<TITLE>Converting the XPA API to 2.0</TITLE>
</HEAD>
<BODY>
<!-- =section xpaconvert NAME -->
<H2><A NAME="xpaconvert">XPAConvert: Converting the XPA API to 2.0</A></H2>
<!-- =section xpaconvert SYNOPSIS -->
<H2>Summary</H2>
<P>
This document describes tips for converting from xpa 1.0 (Xt-based
xpa) to xpa 2.0 (socket-based xpa).
<!-- =section xpaconvert DESCRIPTION -->
<H2>Description</H2>
<P>
The following are tips for converting from xpa 1.0 (Xt-based xpa) to
xpa 2.0 (socket-based xpa). The changes are straight-forward and
almost can be done automatically (we used editor macros for most of
the conversion).
<UL>
<P>
<LI>The existence of the cpp XPA_VERSION directive to distinguish between 1.0
(where it is not defined) and 2.0 (where it is defined).
<P>
<LI>Remove the first widget argument from all send and receive server
callbacks. Also change first 2 arguments from XtPointer to void
*. For example:
<PRE>
#ifdef XPA_VERSION
static void XPAReceiveFile(client_data, call_data, paramlist, buf, len)
void *client_data;
void *call_data;
char *paramlist;
char *buf;
int len;
#else
static void XPAReceiveFile(w, client_data, call_data, paramlist, buf, len)
Widget w;
XtPointer client_data;
XtPointer call_data;
char *paramlist;
char *buf;
int len;
#endif
</PRE>
<P>
<LI>Server callbacks should be declared as returning int instead
of void. They now should return 0 for no errors, -1 for error.
<P>
<LI> The mode flags have changed when defining XPA server callbacks.
The old <EM>S</EM> flag (save buffer) is replaced by <EM>freebuf=false</EM>.
The old <EM>E</EM> flag (empty buffer is OK) is no longer used (it
was an artifact of the X implementation).
<P>
<LI>Change NewXPACommand() to XPAcmdNew(), with the new calling sequence:
<PRE>
xpa = NewXPACommand(toplevel, NULL, prefix, NULL);
</PRE>
is changed to:
<PRE>
xpa = XPACmdNew(xclass, name);
</PRE>
<P>
<LI>Change the AddXPACommand() subroutine name to XPACmdAdd (with the same
calling sequence):
<PRE>
AddXPACommand(xpa, "file",
"\tdisplay a new file\n\t\t requires: filename",
NULL, NULL, NULL, XPAReceiveFile, text, NULL);
</PRE>
is changed to:
<PRE>
XPACmdAdd(xpa, "file",
"\tdisplay a new file\n\t\t requires: filename",
NULL, NULL, NULL, XPAReceiveFile, text, NULL);
</PRE>
<P>
<LI>The XPAXtAppInput() routine should be called just before XtAppMainLoop()
to add xpa fds to the Xt event loop:
<PRE>
/* add the xpas to the Xt loop */
XPAXtAddInput(app, NULL);
/* process events */
XtAppMainLoop(app);
</PRE>
<P>
<LI>Change NewXPA() to XPANew() and call XPAXtAddInput() if the XtAppMainLoop
routine already has been entered:
<PRE>
xpa = NewXPA(saotng->xim->toplevel, prefix, xparoot,
"FITS data or image filename\n\t\t options: file type",
XPASendData, new, NULL,
XPAReceiveData, new, "SE");
</PRE>
is changed to:
<PRE>
sprintf(tbuf, "%s.%s", prefix, xparoot);
xpa = XPANew("SAOTNG", tbuf,
"FITS data or image filename\n\t\t options: file type",
XPASendData, new, NULL,
XPAReceiveData, new, "SE");
XPAXtAddInput(XtWidgetToApplicationContext(saotng->xim->toplevel), xpa);
</PRE>
<P>
<LI>Change XPAInternalReceiveCommand() to XPACmdInternalReceive()
remove first argument in the calling sequence):
<PRE>
XPAInternalReceiveCommand(im->saotng->xim->toplevel,
im->saotng, im->saotng->commands,
"zoom reset", NULL, 0);
</PRE>
is changed to:
<PRE>
XPACmdInternalReceive(im->saotng, im->saotng->commands,
"zoom reset", NULL, 0);
</PRE>
<P>
<LI>Change DestroyXPA to XPAFree:
<PRE>
DestroyXPA(im->dataxpa);
</PRE>
is changed to:
<PRE>
XPAFree(im->dataxpa);
</PRE>
</UL>
<!-- =section xpaconvert SEE ALSO -->
<!-- =text See xpa(n) for a list of XPA help pages -->
<!-- =stop -->
<P>
<A HREF="./help.html">Go to XPA Help Index</A>
<H5>Last updated: September 10, 2003</H5>
</BODY>
</HTML>
