summaryrefslogtreecommitdiffstats
path: root/doc/convert.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/convert.html')
-rw-r--r--doc/convert.html146
1 files changed, 146 insertions, 0 deletions
diff --git a/doc/convert.html b/doc/convert.html
new file mode 100644
index 0000000..a8d0dd2
--- /dev/null
+++ b/doc/convert.html
@@ -0,0 +1,146 @@
+<!-- =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>